尧图网页设计 
pypto-gym 算子可行性报告模板解析API_REPORT.md 的九个章节、门禁校验与填写规范【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文以 PyPTO-Gym 算子开发工作流中的api_report.md模板cannbot-skills/ops/pypto-api-explore/templates/api_report.md为主体逐字段、逐章节拆解这份 API 探索报告的结构设计并结合 pypto-api-explore SKILL.md 定义的核心工作流与 OL10 门禁校验实现说明如何把一份“算子能不能用 PyPTO 实现”的探索结论落成一份可通过 lint 门禁、可被下游设计阶段直接消费的结构化报告。读完后你将掌握该模板的 front matter 字段约定、九个章节各自的填写要点以及报告通过自动化校验的硬性条件。1. 模板定位算子开发 Stage 1 的核心产物在 PyPTO-Gym 的算子编排工作流中API_REPORT.md是 API 探索阶段Stage 1的固定交付物。SKILL.md 明确了其产出约定输出件API_REPORT.md格式Markdown强制使用 templates/api_report.md 模板输出路径当前目录或用户指定位置front matter至少填写schema_version、op_name并建议填充supported_dtypes、axes_list、shape_constraints、tiling_required、feasibility其中axes_list应为 YAML 列表例如[N]或[N,M]。从 门禁规则表 可以看到API_REPORT.md属于 Stage 1 产出、Stage 3 设计阶段读取的衔接产物lint 规则 OL10 会对其做结构化章节校验。也就是说这份模板不是“自由发挥的笔记格式”而是被自动化门禁约束的合同章节标题、front matter schema 都是可机器校验的。2. Front matter七个元数据字段模板开头是一段 YAML front matter完整继承如下占位符以{...}表示--- schema_version: 1 op_name: {operator_name} supported_dtypes: {supported_dtypes} dynamic_axes: {axes_list} shape_constraints: {shape_constraints} tiling_required: {tiling_required} feasibility: {feasibility} ---各字段的作用与填写约定字段必填性说明schema_version必填模板 schema 版本当前为1op_name必填算子名称与后续SPEC.md、DESIGN.md中的命名保持一致supported_dtypes建议该算子支持的数据类型集合供 Stage 3 设计时直接引用dynamic_axes建议动态轴列表YAML 列表形式如[N]shape_constraints建议shape 层面的约束描述对齐、范围等tiling_required建议是否需要 Tiling与正文第 5 章呼应feasibility建议可行性结论与正文第 9 章呼应从 front matter 校验逻辑 看API_REPORT的 schema 强制字段是[schema_version, op_name]即后五项属于“建议填充”填了可让下游免读正文但不填不会触发 schema 报错。这正是 SKILL.md 中“至少填写……并建议填充……”表述的出处。3. 九个章节逐节拆解模板正文为九个一级章节H2其中概述、API 映射、参考实现、风险评估、证据索引、结论六个章节被标记!-- REQUIRED --。以下按模板顺序逐节说明继承内容与填写要点。3.1 第 1 章 概述输入摘要与算子分类该章包含两个小节1.1 输入摘要填写{输入内容摘要}即对原始需求自然语言描述、数学公式、PyTorch 代码片段或 spec 文档的压缩概括。SKILL.md 的输入解析步骤要求从中提取算子名称、数学公式/计算逻辑、输入输出规格shape、dtype与其他约束条件这一小节就是这些提取结果的落点。1.2 算子分类给出- **类型**: {Vector / Cube / 混合}与- **判断依据**: {type_reason}。分类判据来自 SKILL.md 内嵌的“算子类型判断”决策树这一分类直接决定第 5 章 Tiling 该配哪个 API公式分析 │ ├── 含 matmul/ → Cube 类型 → set_cube_tile_shapes │ ├── 仅逐元素/归约 → Vector 类型 → set_vec_tile_shapes │ └── matmul 逐元素 → 混合类型 → 两者都需要例如一个含matmul加 epilogue 的融合算子应判为“混合”类型并写明判断依据哪一步引入 matmul、哪些步骤是逐元素。3.2 第 2 章 公式分解把计算逻辑拆成原子操作模板给出统一的分步表格步骤操作类型数学表达说明1{op_type}{math_expr}{desc}操作类型op_type取自 SKILL.md 步骤 2 定义的六类原子操作elementwiseadd、sub、mul、div、exp、log、sin、cos……reductionsum、max、min、mean、var……matmulmatmul、bmm、linear……shapereshape、transpose、concat……indexgather、scatter、index_select……activationrelu、sigmoid、softmax……这一步的意义在于后续第 3 章的 API 映射是“逐步骤映射”公式分解越原子化映射表的每一行就越短、约束检查就越可逐项勾选。3.3 第 3 章 API 映射三级映射与 Substitute 配方这是整份报告的技术核心模板分为两小节3.1 映射结果——每步公式对应的 PyPTO API 与映射级别步骤数学表达PyPTO API映射级别约束满足1{expr}{api}{direct/substitute/unsupported}{✓/⚠/✗}三级映射的语义direct存在同名/等价 API直接调用。可先查 torch-pypto-op-mapping.md 的“同名映射”表其中逐元素、归约、索引、形状、排序裁剪等大批算子与 Torch 同名同参直接以pypto.{op}调用即可“同名不同参”条目如sum的dim必填、matmul的out_dtype必填则需按表适配。substitute无直接 API需多个 API 组合。映射表中的“命名映射”与“组合方案”两节给出了现成配方例如mean → sum div、softmax → amax sub exp sum div、sigmoid → cast exp add div、nn.Linear → matmul add且 examples/ 目录下每个算子都有一篇 kernel 参考骨架占位符约定见 examples/README.md。unsupported确认真无实现路径需在第 7 章风险评估中标注。3.2 Substitute 配方——模板要求“仅 substitute 时填写”格式为{operation}: {recipe}即把组合方案写成“操作名: API 序列”的可执行配方供 Stage 3 设计阶段直接展开。此外涉及量化数据流、稀疏注意力、RoPE 重排、多核写同一输出、UB/L1 gather 等 NPU 特有场景时应查 pypto-specific-ops.md例如scaled_mm仅 950PR/DT、quant_mx、atomic_add、deinterleavegym 中 InterleaveRope 的偶奇位拆分场景、fillpad尾部 chunk 补零对齐等接口——这些接口 Torch 无对应物是“命名映射”表之外的第三类映射来源。存在多种实现策略的算子如 GELU 的 tanh 近似 vs erf 精确、Attention 的 online softmax 分块 vs 整块则参考 strategy-comparison.md 在配方中记录选型理由。3.4 第 4 章 约束检查入口约束与 API 约束两层模板分两小节对应 SKILL.md 中 Explore subagent 1 要提取的“三层约束”4.1 入口约束——针对张量从 host 进入 PyPTO 的边界条件约束项要求输入值结果dtype{supported}{input_dtype}{✓/✗}contiguous必须—{✓/需确保}4.2 API 约束——针对每个实际调用的 APIAPI约束项要求结果{api}dtype{list}{✓/✗}填写时应对照 SKILL.md 内嵌的“硬约束速查”表逐项打勾约束类型规则dtype 入口FP16/BF16/FP32/FP64/INT8/INT16/INT32/INT64/UINT8/UINT16/UINT32/UINT64/BOOLshape 入口非空 Tensorcontiguous必须连续TileShape每维 0最多 4 维Cube TileShape32 字节对齐buffer 空间需满足 K 轴 × 2 ≤ L1 容量shape size≤ INT32_MAX特别地速查表中最后一条动态 shape 兼容性约束要求matmul / 归约类等计算 API 在编译期需要 concrete shape不接受含 DYNAMIC 维度的 tensor报错has invalid shape value: -1。若算子有动态轴且用到这类 API必须在第 7 章风险评估中标注并说明需采用“loop 切 tile”策略。这是该模板中唯一被显式强调“必须写入风险章节”的约束项。3.5 第 5 章 Tiling 需求模板将算子类型与所需 Tiling API 固化为一张二列表算子类型需调用 API{type}pypto.set_{vec/cube}_tile_shapes()Vector 算子填pypto.set_vec_tile_shapes()Cube 算子填pypto.set_cube_tile_shapes()混合类型两行都写。该章与 front matter 的tiling_required字段相互印证也与 OL10 门禁检查的 “Tiling” 关键词对应。3.6 第 6 章 参考实现匹配示例、可复用模式与差异分析这是模板中带最多“填写纪律注释”的章节三个小节各有硬性约定6.1 匹配示例。模板内嵌的注释明确了两条置信度规则与一条边界置信度标定正式算子实现为「高」golden 用法为「高」experimental 实现为「中」tests/中的 golden/用法仅作 API 用法参考不是 production 实现标准简化写法如pypto.Tensor([])可能违反 lint/门禁与 lint 冲突时以 lint 为准不得据此判定 lint 误报。对应表格参考路径来源相似度置信度可复用点{ref_path}{算子实现/golden}pypto-docs-search命中{高/中/低}{高/中}{reuse_points}无匹配时填“无匹配参考实现需从零设计”——注意章节本身不可缺失见第 5 节 Checklist。6.2 可复用模式——固定四个 bullet要求从参考实现中提炼实现层模式而非只贴路径API 调用模式{api_usage_pattern}Tiling 策略{tiling_pattern}Loop 结构{loop_pattern}边界处理{boundary_pattern}6.3 差异分析——把“参考实现的做法”与“本算子的需求”逐点对照给出调整建议差异点示例做法本算子需求调整建议{diff}{example_approach}{current_need}{suggestion}3.7 第 7 章 风险评估阻断问题与注意事项两小节分别为7.1 阻断问题问题原因建议{issue}{reason}{suggestion}7.2 注意事项注意点说明{warning}{desc}按 SKILL.md 的错误处理表以下场景必须落进本章API 不存在标记 unsupported 并说明、约束不满足标记 ✗ 并给替代方案、动态 shape 冲突如 3.4 节所述。该章与第 9 章结论联动——“需调整/不可行”的结论必须能在此章找到对应问题条目。3.8 第 8 章 证据索引模板要求把“每条关键结论的证据路径”登记成表已知具体文档给文档路径参考实现给pypto-docs-search命中的算子参考实现路径。模板内置的示例行覆盖四类证据信息文档路径API 存在性PyPTO 官方文档站docs/zh/api/operation/index.md{api} 文档docs/zh/api/operation/pypto-{api}.md入口约束docs/zh/api/others/pypto-from_torch.md参考实现pypto-docs-search命中的算子参考实现路径如有这一章的设计意图是“可复核”Stage 3 的 Architect 或人工评审无需重新搜索即可按图索骥验证 API 存在性、约束取值与参考实现的来源。SKILL.md 中三个 Explore subagentAPI 文档与约束、算子参考实现、用法参考的返回内容都要求携带证据索引路径列表本章即其汇总落点。3.9 第 9 章 结论模板将结论收敛为两行 bullet可行性: {可行 / 需调整 / 不可行}主要问题: {main_issue}三态结论与 front matter 的feasibility字段保持一致形成“元数据可速读、正文章节可深读”的闭环。4. 填写纪律先复制模板再改以及门禁如何校验SKILL.md 步骤 4 对生成方式有强制要求先复制模板再改——先cp templates/api_report.md 目标/API_REPORT.md再用编辑替换占位符不要自由重写整份文件以免漏掉门禁要求的中文章节标题API 映射 / 约束 / Tiling。这条纪律背后是真实的自动化校验。OL10 检查器 的逻辑是API_REPORT.md文件必须存在否则 FAIL提取全部 Markdown 标题要求同时命中API mapping、constraints、Tiling三组关键词即模板第 3/4/5 章的“API 映射”“约束”“Tiling 需求”缺一即 FAIL且报错信息会提示“若标题用了英文等价写法可能匹配失败”。lint-gate-rules.md 对 OL10 的登记进一步说明了产物生命周期“API_REPORT.md 必须通过结构化章节校验API 映射、约束、TilingStage 1 产出Stage 3 设计阶段读取”。而 SKILL.md 自身的 Checklist 则是对 OL10 的“加严版”自检——要求 6 个章节存在且内容不为空## 1. 概述## 3. API 映射## 6. 参考实现可标注「无匹配」但不可缺失## 7. 风险评估## 8. 证据索引## 9. 结论从源码结构看机器门禁OL10校验 3 组关键词、人工/Agent Checklist 校验 6 个章节二者叠加构成模板的最低合格线标题用中文模板原文最稳妥任何“意译改写章节名”的写法都有触发 OL10 FAIL 的风险。5. 与上游工作流的衔接报告是在哪里被填充的模板中的占位符并非凭空手写SKILL.md 定义了一套“本地映射优先 三路并行探索”的填充流程理解它对正确填写各章节很有帮助步骤 2.5 本地映射优先发起探索前先查 references/torch-pypto-op-mapping.md命中“命名映射/组合方案”即按表取 API 或配方并阅读 examples/ 对应 kernel 骨架命中量化、稀疏注意力等场景则查 pypto-specific-ops.md。未命中才进入全量探索。步骤 3 三路并行探索三个 Explore subagent 在同一条消息中并行发起——subagent 1 用pypto-docs-search搜索 API 文档pypto-op.md命中即证明存在、入口约束pypto-from_torch.md、Tiling 约束pypto-set_vec_tile_shapes.md/pypto-set_cube_tile_shapes.md与 DataType/TileOpFormat 枚举对应报告第 3/4/5/8 章subagent 2 遍历搜索生产级参考实现要求“不要找到一个就停止”对应第 6 章subagent 3 搜索真实用法与 golden 用法定位仅为 API 用法参考非 production 标准同样汇入第 6 章。汇总等待三路全部返回后合并映射与约束结果对比评估选出最佳匹配存在多个高质量参考时报告应列出 Top 3 并说明推荐首选及理由。按这一流程模板第 6 章“参考路径”列的值应能追溯到pypto-docs-search的具体命中文件第 8 章证据索引与之一一对应——这正是“可复用点/相似度/置信度”三列存在的意义让 Stage 3 的设计阶段pypto-op-design 产物DESIGN.md同样有 OL12 门禁要求包含计算图、Tiling 与验证计划章节拿到的是已经过筛选与定级的素材而不是待甄别的路径列表。6. 一个最小填写示例softmax 的映射行把上述规则落到具体算子上以 strategy-comparison.md 与 examples/softmax.md 为依据softmax 在报告中的典型填写形态如下演示用法数值参数需按实际输入确认front matterop_name: softmaxsupported_dtypes按 API 文档确认tiling_required: trueVector 类型第 1.2 节类型 Vector仅逐元素 归约判断依据 “amax 归约 sub/exp/sum/div 逐元素无 matmul”第 3.1 节映射行1 | max 稳定化 |pypto.amax| direct | ✓…5 | 归一化 |pypto.div| direct | ✓其中sum属“同名不同参”——pypto 侧dim必填第 3.2 节配方若把 softmax 整体视为组合方案softmax: amax sub exp sum div第 4.2 节对pypto.sum需确认 FP16/BF16 输入前的 cast 要求strategy-comparison 的 mean 条目指出pypto.sum存在 FP32 硬约束softmax 分母求和同理应在归约前 cast第 5 章Vector 类型 →pypto.set_vec_tile_shapes()第 6.1 节参考路径指向 examples/softmax.md 及pypto-docs-search命中的 golden/实现按“骨架仅展示轴切分、未逐一经 NPU 编译验证”的 占位符约定 给出置信度。7. 相关路径索引资源路径报告模板本文主体templates/api_report.md工作流定义输入/输出/步骤/ChecklistSKILL.mdTorch↔Pypto 映射手册torch-pypto-op-mapping.mdNPU 特有接口表pypto-specific-ops.md多策略选型对比strategy-comparison.mdkernel 参考骨架与占位符约定examples/README.mdOL10 门禁实现checks/d2_artifact.pyfront matter schema 校验pypto_op_lint/utils.py门禁规则登记lint-gate-rules.md适用前提以上所有结论均基于当前仓库cannbot-skills/ops/pypto-api-explore技能包与pypto-op-orchestrator插件内的 SKILL.md、references 与 lint 源码模板中的schema_version: 1与门禁规则如后续升级应以仓库最新文件为准。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pypto-gym 算子可行性报告模板解析：API_REPORT.md 的九个章节、门禁校验与填写规范
pypto-gym 算子可行性报告模板解析API_REPORT.md 的九个章节、门禁校验与填写规范【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文以 PyPTO-Gym 算子开发工作流中的api_report.md模板cannbot-skills/ops/pypto-api-explore/templates/api_report.md为主体逐字段、逐章节拆解这份 API 探索报告的结构设计并结合 pypto-api-explore SKILL.md 定义的核心工作流与 OL10 门禁校验实现说明如何把一份“算子能不能用 PyPTO 实现”的探索结论落成一份可通过 lint 门禁、可被下游设计阶段直接消费的结构化报告。读完后你将掌握该模板的 front matter 字段约定、九个章节各自的填写要点以及报告通过自动化校验的硬性条件。1. 模板定位算子开发 Stage 1 的核心产物在 PyPTO-Gym 的算子编排工作流中API_REPORT.md是 API 探索阶段Stage 1的固定交付物。SKILL.md 明确了其产出约定输出件API_REPORT.md格式Markdown强制使用 templates/api_report.md 模板输出路径当前目录或用户指定位置front matter至少填写schema_version、op_name并建议填充supported_dtypes、axes_list、shape_constraints、tiling_required、feasibility其中axes_list应为 YAML 列表例如[N]或[N,M]。从 门禁规则表 可以看到API_REPORT.md属于 Stage 1 产出、Stage 3 设计阶段读取的衔接产物lint 规则 OL10 会对其做结构化章节校验。也就是说这份模板不是“自由发挥的笔记格式”而是被自动化门禁约束的合同章节标题、front matter schema 都是可机器校验的。2. Front matter七个元数据字段模板开头是一段 YAML front matter完整继承如下占位符以{...}表示--- schema_version: 1 op_name: {operator_name} supported_dtypes: {supported_dtypes} dynamic_axes: {axes_list} shape_constraints: {shape_constraints} tiling_required: {tiling_required} feasibility: {feasibility} ---各字段的作用与填写约定字段必填性说明schema_version必填模板 schema 版本当前为1op_name必填算子名称与后续SPEC.md、DESIGN.md中的命名保持一致supported_dtypes建议该算子支持的数据类型集合供 Stage 3 设计时直接引用dynamic_axes建议动态轴列表YAML 列表形式如[N]shape_constraints建议shape 层面的约束描述对齐、范围等tiling_required建议是否需要 Tiling与正文第 5 章呼应feasibility建议可行性结论与正文第 9 章呼应从 front matter 校验逻辑 看API_REPORT的 schema 强制字段是[schema_version, op_name]即后五项属于“建议填充”填了可让下游免读正文但不填不会触发 schema 报错。这正是 SKILL.md 中“至少填写……并建议填充……”表述的出处。3. 九个章节逐节拆解模板正文为九个一级章节H2其中概述、API 映射、参考实现、风险评估、证据索引、结论六个章节被标记!-- REQUIRED --。以下按模板顺序逐节说明继承内容与填写要点。3.1 第 1 章 概述输入摘要与算子分类该章包含两个小节1.1 输入摘要填写{输入内容摘要}即对原始需求自然语言描述、数学公式、PyTorch 代码片段或 spec 文档的压缩概括。SKILL.md 的输入解析步骤要求从中提取算子名称、数学公式/计算逻辑、输入输出规格shape、dtype与其他约束条件这一小节就是这些提取结果的落点。1.2 算子分类给出- **类型**: {Vector / Cube / 混合}与- **判断依据**: {type_reason}。分类判据来自 SKILL.md 内嵌的“算子类型判断”决策树这一分类直接决定第 5 章 Tiling 该配哪个 API公式分析 │ ├── 含 matmul/ → Cube 类型 → set_cube_tile_shapes │ ├── 仅逐元素/归约 → Vector 类型 → set_vec_tile_shapes │ └── matmul 逐元素 → 混合类型 → 两者都需要例如一个含matmul加 epilogue 的融合算子应判为“混合”类型并写明判断依据哪一步引入 matmul、哪些步骤是逐元素。3.2 第 2 章 公式分解把计算逻辑拆成原子操作模板给出统一的分步表格步骤操作类型数学表达说明1{op_type}{math_expr}{desc}操作类型op_type取自 SKILL.md 步骤 2 定义的六类原子操作elementwiseadd、sub、mul、div、exp、log、sin、cos……reductionsum、max、min、mean、var……matmulmatmul、bmm、linear……shapereshape、transpose、concat……indexgather、scatter、index_select……activationrelu、sigmoid、softmax……这一步的意义在于后续第 3 章的 API 映射是“逐步骤映射”公式分解越原子化映射表的每一行就越短、约束检查就越可逐项勾选。3.3 第 3 章 API 映射三级映射与 Substitute 配方这是整份报告的技术核心模板分为两小节3.1 映射结果——每步公式对应的 PyPTO API 与映射级别步骤数学表达PyPTO API映射级别约束满足1{expr}{api}{direct/substitute/unsupported}{✓/⚠/✗}三级映射的语义direct存在同名/等价 API直接调用。可先查 torch-pypto-op-mapping.md 的“同名映射”表其中逐元素、归约、索引、形状、排序裁剪等大批算子与 Torch 同名同参直接以pypto.{op}调用即可“同名不同参”条目如sum的dim必填、matmul的out_dtype必填则需按表适配。substitute无直接 API需多个 API 组合。映射表中的“命名映射”与“组合方案”两节给出了现成配方例如mean → sum div、softmax → amax sub exp sum div、sigmoid → cast exp add div、nn.Linear → matmul add且 examples/ 目录下每个算子都有一篇 kernel 参考骨架占位符约定见 examples/README.md。unsupported确认真无实现路径需在第 7 章风险评估中标注。3.2 Substitute 配方——模板要求“仅 substitute 时填写”格式为{operation}: {recipe}即把组合方案写成“操作名: API 序列”的可执行配方供 Stage 3 设计阶段直接展开。此外涉及量化数据流、稀疏注意力、RoPE 重排、多核写同一输出、UB/L1 gather 等 NPU 特有场景时应查 pypto-specific-ops.md例如scaled_mm仅 950PR/DT、quant_mx、atomic_add、deinterleavegym 中 InterleaveRope 的偶奇位拆分场景、fillpad尾部 chunk 补零对齐等接口——这些接口 Torch 无对应物是“命名映射”表之外的第三类映射来源。存在多种实现策略的算子如 GELU 的 tanh 近似 vs erf 精确、Attention 的 online softmax 分块 vs 整块则参考 strategy-comparison.md 在配方中记录选型理由。3.4 第 4 章 约束检查入口约束与 API 约束两层模板分两小节对应 SKILL.md 中 Explore subagent 1 要提取的“三层约束”4.1 入口约束——针对张量从 host 进入 PyPTO 的边界条件约束项要求输入值结果dtype{supported}{input_dtype}{✓/✗}contiguous必须—{✓/需确保}4.2 API 约束——针对每个实际调用的 APIAPI约束项要求结果{api}dtype{list}{✓/✗}填写时应对照 SKILL.md 内嵌的“硬约束速查”表逐项打勾约束类型规则dtype 入口FP16/BF16/FP32/FP64/INT8/INT16/INT32/INT64/UINT8/UINT16/UINT32/UINT64/BOOLshape 入口非空 Tensorcontiguous必须连续TileShape每维 0最多 4 维Cube TileShape32 字节对齐buffer 空间需满足 K 轴 × 2 ≤ L1 容量shape size≤ INT32_MAX特别地速查表中最后一条动态 shape 兼容性约束要求matmul / 归约类等计算 API 在编译期需要 concrete shape不接受含 DYNAMIC 维度的 tensor报错has invalid shape value: -1。若算子有动态轴且用到这类 API必须在第 7 章风险评估中标注并说明需采用“loop 切 tile”策略。这是该模板中唯一被显式强调“必须写入风险章节”的约束项。3.5 第 5 章 Tiling 需求模板将算子类型与所需 Tiling API 固化为一张二列表算子类型需调用 API{type}pypto.set_{vec/cube}_tile_shapes()Vector 算子填pypto.set_vec_tile_shapes()Cube 算子填pypto.set_cube_tile_shapes()混合类型两行都写。该章与 front matter 的tiling_required字段相互印证也与 OL10 门禁检查的 “Tiling” 关键词对应。3.6 第 6 章 参考实现匹配示例、可复用模式与差异分析这是模板中带最多“填写纪律注释”的章节三个小节各有硬性约定6.1 匹配示例。模板内嵌的注释明确了两条置信度规则与一条边界置信度标定正式算子实现为「高」golden 用法为「高」experimental 实现为「中」tests/中的 golden/用法仅作 API 用法参考不是 production 实现标准简化写法如pypto.Tensor([])可能违反 lint/门禁与 lint 冲突时以 lint 为准不得据此判定 lint 误报。对应表格参考路径来源相似度置信度可复用点{ref_path}{算子实现/golden}pypto-docs-search命中{高/中/低}{高/中}{reuse_points}无匹配时填“无匹配参考实现需从零设计”——注意章节本身不可缺失见第 5 节 Checklist。6.2 可复用模式——固定四个 bullet要求从参考实现中提炼实现层模式而非只贴路径API 调用模式{api_usage_pattern}Tiling 策略{tiling_pattern}Loop 结构{loop_pattern}边界处理{boundary_pattern}6.3 差异分析——把“参考实现的做法”与“本算子的需求”逐点对照给出调整建议差异点示例做法本算子需求调整建议{diff}{example_approach}{current_need}{suggestion}3.7 第 7 章 风险评估阻断问题与注意事项两小节分别为7.1 阻断问题问题原因建议{issue}{reason}{suggestion}7.2 注意事项注意点说明{warning}{desc}按 SKILL.md 的错误处理表以下场景必须落进本章API 不存在标记 unsupported 并说明、约束不满足标记 ✗ 并给替代方案、动态 shape 冲突如 3.4 节所述。该章与第 9 章结论联动——“需调整/不可行”的结论必须能在此章找到对应问题条目。3.8 第 8 章 证据索引模板要求把“每条关键结论的证据路径”登记成表已知具体文档给文档路径参考实现给pypto-docs-search命中的算子参考实现路径。模板内置的示例行覆盖四类证据信息文档路径API 存在性PyPTO 官方文档站docs/zh/api/operation/index.md{api} 文档docs/zh/api/operation/pypto-{api}.md入口约束docs/zh/api/others/pypto-from_torch.md参考实现pypto-docs-search命中的算子参考实现路径如有这一章的设计意图是“可复核”Stage 3 的 Architect 或人工评审无需重新搜索即可按图索骥验证 API 存在性、约束取值与参考实现的来源。SKILL.md 中三个 Explore subagentAPI 文档与约束、算子参考实现、用法参考的返回内容都要求携带证据索引路径列表本章即其汇总落点。3.9 第 9 章 结论模板将结论收敛为两行 bullet可行性: {可行 / 需调整 / 不可行}主要问题: {main_issue}三态结论与 front matter 的feasibility字段保持一致形成“元数据可速读、正文章节可深读”的闭环。4. 填写纪律先复制模板再改以及门禁如何校验SKILL.md 步骤 4 对生成方式有强制要求先复制模板再改——先cp templates/api_report.md 目标/API_REPORT.md再用编辑替换占位符不要自由重写整份文件以免漏掉门禁要求的中文章节标题API 映射 / 约束 / Tiling。这条纪律背后是真实的自动化校验。OL10 检查器 的逻辑是API_REPORT.md文件必须存在否则 FAIL提取全部 Markdown 标题要求同时命中API mapping、constraints、Tiling三组关键词即模板第 3/4/5 章的“API 映射”“约束”“Tiling 需求”缺一即 FAIL且报错信息会提示“若标题用了英文等价写法可能匹配失败”。lint-gate-rules.md 对 OL10 的登记进一步说明了产物生命周期“API_REPORT.md 必须通过结构化章节校验API 映射、约束、TilingStage 1 产出Stage 3 设计阶段读取”。而 SKILL.md 自身的 Checklist 则是对 OL10 的“加严版”自检——要求 6 个章节存在且内容不为空## 1. 概述## 3. API 映射## 6. 参考实现可标注「无匹配」但不可缺失## 7. 风险评估## 8. 证据索引## 9. 结论从源码结构看机器门禁OL10校验 3 组关键词、人工/Agent Checklist 校验 6 个章节二者叠加构成模板的最低合格线标题用中文模板原文最稳妥任何“意译改写章节名”的写法都有触发 OL10 FAIL 的风险。5. 与上游工作流的衔接报告是在哪里被填充的模板中的占位符并非凭空手写SKILL.md 定义了一套“本地映射优先 三路并行探索”的填充流程理解它对正确填写各章节很有帮助步骤 2.5 本地映射优先发起探索前先查 references/torch-pypto-op-mapping.md命中“命名映射/组合方案”即按表取 API 或配方并阅读 examples/ 对应 kernel 骨架命中量化、稀疏注意力等场景则查 pypto-specific-ops.md。未命中才进入全量探索。步骤 3 三路并行探索三个 Explore subagent 在同一条消息中并行发起——subagent 1 用pypto-docs-search搜索 API 文档pypto-op.md命中即证明存在、入口约束pypto-from_torch.md、Tiling 约束pypto-set_vec_tile_shapes.md/pypto-set_cube_tile_shapes.md与 DataType/TileOpFormat 枚举对应报告第 3/4/5/8 章subagent 2 遍历搜索生产级参考实现要求“不要找到一个就停止”对应第 6 章subagent 3 搜索真实用法与 golden 用法定位仅为 API 用法参考非 production 标准同样汇入第 6 章。汇总等待三路全部返回后合并映射与约束结果对比评估选出最佳匹配存在多个高质量参考时报告应列出 Top 3 并说明推荐首选及理由。按这一流程模板第 6 章“参考路径”列的值应能追溯到pypto-docs-search的具体命中文件第 8 章证据索引与之一一对应——这正是“可复用点/相似度/置信度”三列存在的意义让 Stage 3 的设计阶段pypto-op-design 产物DESIGN.md同样有 OL12 门禁要求包含计算图、Tiling 与验证计划章节拿到的是已经过筛选与定级的素材而不是待甄别的路径列表。6. 一个最小填写示例softmax 的映射行把上述规则落到具体算子上以 strategy-comparison.md 与 examples/softmax.md 为依据softmax 在报告中的典型填写形态如下演示用法数值参数需按实际输入确认front matterop_name: softmaxsupported_dtypes按 API 文档确认tiling_required: trueVector 类型第 1.2 节类型 Vector仅逐元素 归约判断依据 “amax 归约 sub/exp/sum/div 逐元素无 matmul”第 3.1 节映射行1 | max 稳定化 |pypto.amax| direct | ✓…5 | 归一化 |pypto.div| direct | ✓其中sum属“同名不同参”——pypto 侧dim必填第 3.2 节配方若把 softmax 整体视为组合方案softmax: amax sub exp sum div第 4.2 节对pypto.sum需确认 FP16/BF16 输入前的 cast 要求strategy-comparison 的 mean 条目指出pypto.sum存在 FP32 硬约束softmax 分母求和同理应在归约前 cast第 5 章Vector 类型 →pypto.set_vec_tile_shapes()第 6.1 节参考路径指向 examples/softmax.md 及pypto-docs-search命中的 golden/实现按“骨架仅展示轴切分、未逐一经 NPU 编译验证”的 占位符约定 给出置信度。7. 相关路径索引资源路径报告模板本文主体templates/api_report.md工作流定义输入/输出/步骤/ChecklistSKILL.mdTorch↔Pypto 映射手册torch-pypto-op-mapping.mdNPU 特有接口表pypto-specific-ops.md多策略选型对比strategy-comparison.mdkernel 参考骨架与占位符约定examples/README.mdOL10 门禁实现checks/d2_artifact.pyfront matter schema 校验pypto_op_lint/utils.py门禁规则登记lint-gate-rules.md适用前提以上所有结论均基于当前仓库cannbot-skills/ops/pypto-api-explore技能包与pypto-op-orchestrator插件内的 SKILL.md、references 与 lint 源码模板中的schema_version: 1与门禁规则如后续升级应以仓库最新文件为准。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考