PyPTO-Pro 资料探索报告EXPLORE_REPORT模板深度解析与实战指南【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文以 cannbot-skills/ops/pypto-pro-material-explore/templates/explore_report.md 模板为骨架结合 SKILL.md 定义的工作流、索引生成器 与 官方样例清单 的实现细节系统讲解 PyPTO-Pro 五阶段算子开发流程中 Stage 1 资料探索报告EXPLORE_REPORT.md的生成逻辑、章节结构与实战填写规范帮助开发者理解如何基于目标版本资料取证、判定算子可行性、并为 Stage 3 架构设计提供事实输入。导读在 PyPTO-Pro 深度编排流程中EXPLORE_REPORT.md是 Stage 1需求规划的关键交付物之一回答当前目标版本能否实现、证据在哪里、有哪些约束这三个问题。本文以pypto-pro-material-exploreskill 的报告模板为核心逐一拆解其 10 个章节的填写逻辑并结合仓库内索引生成器、官方样例清单与编排合同说明每条证据的来源与验证方式。读完本文你将掌握如何将 SPEC 公式分解为原子数学步骤并映射到vf.*/pl.*API如何按纯 Cube / 纯 Vec / VC 融合三类组织官方样例取证如何沉淀环境常量快照并输出可供 Stage 3 直接消费的设计事实。1. 模板定位一份只取证、不决策的事实报告EXPLORE_REPORT.md不是设计文档也不是性能报告。按 pypto-pro-material-explore/SKILL.md 的定义该 skill只负责回答当前目标版本能否实现、证据在哪里、有哪些约束需求语义以 SPEC 为准KB 路由由 plan 负责最终 Module / tile / 同步方案由 Stage 3架构设计决定。因此报告本身不得冻结 topology、Module、tile、同步事件或 KB_SELECTION只能提出 Stage 3 需解决的设计问题。这一约束直接体现在模板的两处设计上模板头部 YAML Front Matter 携带op_name与feasibility可行 / 需调整 / 不可行两个字段让可行性结论可在阶段间机器可读地流转第 6 章Stage 3 设计事实输入明确写明本节是 Stage 3 的消费入口只汇总事实与待裁定项不冻结 tile、Module、同步事件或 topology这些由 Stage 3 决定。从编排层面看该报告与PRO_MATERIAL_INDEX.md一起由 orchestrator 在 Stage 1 调度pypto-pro-op-planner加载 skillpypto-pro-op-plan时串行产出随后由 verifier 执行stage1-check门禁校验PASS 后complete_stage(1)自动推进 Stage 2见 orchestration.md。也就是说报告结构是否完整第 1–10 章齐全、无未解决阻断项是 Stage 1 门禁的一部分。1.1 证据优先级SKILL.md 明确了四条证据优先级报告中的所有结论必须落到这四类来源上当前$PYPTO_DEVKIT_DIR中目标版本的 API 文档official_samples.md 指定且缓存中存在的官方样例当前缓存中的 Pro 编程指南、快速入门与共享简介KB 中与当前 class 匹配、状态为validated的补充材料。关键约束API 签名、平台常量和能力边界以前三项为准KB 或模型记忆不能覆盖目标版本事实。共享的 buffer / Vector 性能规则只读取$CANNBOT_CONFIG_ROOT/references/performance-constraints.md本 skill 不复制或重新解释完整规则只为每个相关步骤记录目标版本证据供 Stage 3 裁定。2. 章节总览模板的 10 段骨架模板由 10 个章节构成其中标记!-- REQUIRED --的为必填段1、3、4、5、6、7、8、9、10第 2 章公式分解虽未标 REQUIRED 但为第 3 章 API 映射的事实基础实际也不可省略。整体逻辑链条为SPEC 输入 → 1 概述分类 → 2 公式分解原子步骤 → 3 API 映射与约束探索方向 1索引 §A → 4 算子样例探索探索方向 2索引 §B → 5 教程与设计指南探索方向 3索引 §C → 6 Stage 3 设计事实输入汇总 345 → 7 环境常量快照 → 8 风险评估 → 9 证据索引 → 10 结论feasibility三个探索方向分别对应 PRO_MATERIAL_INDEX 模板 的 §AAPI 文档、§B官方指定算子样例、§C教程与设计指南三节——探索报告的取证广度与索引的扫描范围一一对应。3. 第 1 章概述——输入摘要、算子分类与 API 类别预判3.1 输入摘要{输入内容摘要}应浓缩 SPEC 中的算子名称、数学公式/计算逻辑、输入输出 tensor 的 dtype 等事实。注意 SKILL 边界算子名称、公式、I/O dtype 由用户提供shape 在 design 阶段才设计无需在输入阶段确认。3.2 算子分类模板要求判定计算引擎类型取值Vector / Cube / VF / 混合判断依据是公式中是否含matmul→ Cube矩阵计算仅逐元素 / 归约 → Vector需要 VF 指令 → VF。3.3 API 类别预判表模板预置了一张六行 API 类别表数据搬运 / VF 实现 / 矩阵计算 / 系统访问 / 控制流 / 工具每行需填写是否涉及、关键 API、指定算子是否覆盖。这张表的作用是预筛在正式逐 API 阅读前先圈定本算子大概率会用到的 API 家族。模板注释强调实际 API 以本次 PRO_MATERIAL_INDEX §A 扫描结果为准即预判表不是结论只是检索起点。模板中预填的关键 API 清单本身即是很好的候选词表数据搬运load_tile/store_tile/load/store/moveVF 实现vf.add/vf.mul/vf.max/vf.astype/vf.exp_sub/vf.muls等矩阵计算Cubematmul/matmul_acc系统访问get_block_idx/get_block_num控制流section_vector/section_cube/pl.range工具动态维度声明 /set_validshape/make_tile_group。4. 第 2 章公式分解——不改变表达式的原子化公式分解是 API 映射的前置步骤。SKILL.md 第 2 步规定把 SPEC 的公式/算法拆成原子数学步骤但不改变表达式。对需要近似的步骤必须记录近似来源、适用区间和至少两个已知点的数值 sanity check。发现 SPEC 自相矛盾时停止并回到需求阶段。模板的分解表结构为步骤操作类型数学表达vf.* 调用链vec/ pl.* 调用链cube说明{n}{op_type}{math_expr}vf.{api1}→vf.{api2}vec/pl.{api1}cube{desc}注意第 2 章表中已出现vf.* 调用链 / pl.* 调用链列这与第 3 章的 API 映射表结构对称——第 2 章是预填的候选链第 3 章是经文档验证后的最终链两章共同保证每个公式步骤都有可行 API 链或带完整证据的 unsupported这一完成条件。5. 第 3 章API 文档探索——从索引 §A 到约束表5.1 API 映射结果探索方向 1 基于PRO_MATERIAL_INDEX.md§A。SKILL.md 第 3 步规定了映射细则从索引 §A 定位候选 API 并阅读全文名称不足以定位时只在 §A 已列文档中全文检索结论写入 EXPLORE_REPORT不手工修改索引记录准确签名、参数单位/语义、dtype、shape、layout、MemorySpace、tile 和版本约束Vector 步骤先查目标版本是否有单一 VF API没有时再记录有文档依据的 VF 组合两者都无法完整表达语义才标记unsupported——本阶段不做 VF / tile-op 性能选择Cube 步骤记录对应pl.*API、累加语义及 layout 约束没有可行调用链时标记unsupported附查过的文档和失败原因不得编造 API。映射结果表的状态列取值{直接可用/需组合/不支持}约束满足列取值{✓/⚠/✗}将能不能用和约束满不满足两个维度解耦。5.2 替代方案表模板要求每个 Vector 步骤均填写无 Vector 步骤时注明不适用。表列包括默认 VF 映射、API 依据API path excerpt、目标版本、适用条件dtype/shape/layout、交接状态待 Stage 3 核对已选 KB 模板。该表是第 3.1 节需组合情形的展开明确记录组合依据来自哪个文档片段保证 Stage 3 可以回溯。5.3 API 约束表约束表是第 3 章信息密度最高的部分要求按三类维度记录参数语义如 offset 单位、layout 取值、matmul module 累加语义寄存器级行为如vf.astype的 BF16/FP32 映射同名差异如vf.gather与pl.gather的差异。5.4 MemorySpace 约束表操作MemorySpace约束{op}{space}{constraint}MemorySpace 约束UB / L1 / L0A / L0B / L0C / GM直接影响第 7 章环境常量快照与 Stage 3 的 tile 规划因此单独成表而非并入 5.3。6. 第 4 章算子样例探索——按 cube/vec 组成分类取证6.1 官方样例的唯一来源探索方向 2 基于索引 §B。需要特别强调的是官方指定算子是精选实现参考a5 目录下其余文件不得参考模板注释原文。§B 的内容来自 official_samples.md——该文件是整个 PyPTO-Pro 工作流的统一官方样例索引来源orchestrator 资源缓存准备时按清单装配$PYPTO_DEVKIT_DIR/pro_ops/只保留清单内文件material-explore 生成索引 §B 时以它为唯一来源所有 skill/agent 提到官方指定算子样例§B时最终都指向该文件。当前清单共 13 个样例覆盖三类分类代表样例缓存相对路径elementwise纯 Vecaddpro_ops/element_wise/test_add.pymatmul 入门 / 性能纯 Cubematmul_8k_example、matmul_perf_asw_4k/8k_k128含动态轴变体pro_ops/matmul/test_matmul_*.pyFlashAttention 教学 / 性能 / FlexAttentionVC 融合fa_tilingkey_attn_mask、fa_with_mask、fa_perf_tkv_preload、flex_attentionpro_ops/fa/test_*.pyVF TopK / VF LayerNorm / VF Softmaxquant_lightning_indexer_vf、layernorm_tile_group_vf、softmax_tile_group_vfpro_ops/lightning_indexer/、pro_ops/vf_api/6.2 全量样例参考表模板要求全量阅读索引 §B 中所有官方指定算子样例并按 cube/vec 组成分类记录参考价值而非只读与当前算子最像的那一个纯 Cube 样例matmul 类记录 cube tile 管理、K 累加链、matmul_accmodule、L1/L0 布局、set_mm_layout_transform等可复用点纯 Vec 样例elementwise 类、vf_api 类记录 vf 指令组合、make_tile_group双缓冲、auto_mutex、load_align/store_align等VC 融合样例FA 类、lightning_indexer 类记录section_cube → acc_to_vec → section_vector衔接、cross_core 流水、多 Module 分块等。选参考原则在模板中有明确表述优先从当前算子对应分类中提取直接可复用模式同时从所有样例中提取通用写法参考API 用法、分核策略、同步事件管理、尾块处理等。6.3 可复用模式、差异分析与推荐4.2 可复用模式分为两层直接可复用来自当前算子对应分类的样例标注来源路径覆盖 API 调用链、Tile 配置、同步策略、循环结构四项与通用写法参考来自所有样例覆盖 API 用法、分核覆盖/重叠/空转检查、event_id 分配/隔离、valid_shape/compact/fillpad 尾块处理。4.3 差异分析用示例做法 → 本算子需求 → 调整建议三列对比防止把样例写法无差别照搬。4.4 高参考价值样例推荐只作推荐、不否定其余样例理由是对当前算子参考价值高的具体分析。模板还提示可按pypto-pro-op-kb/examples/kernel-index.md补充条目但仅允许validated、路径存在且 topology/dtype/layout/platform 匹配的代码study状态不能作为正确性依据。7. 第 5 章教程与设计指南探索探索方向 3 基于索引 §C。SKILL.md 第 5 步要求逐一评估索引 §C 中的 Pro 编程指南、快速入门及共享简介记录与当前算子相关的设计模式、适用条件和章节路径不相关也要标记不适用——这是为了证明遍历完整避免遗漏可能的约束。5.1 适用的设计模式表逐行填写每个指南文档来源目录、设计模式、适用性适用性列需写对本算子的指导意义或不适用5.2 来自教程的关键约束与建议记录来源、约束/建议、影响将教程中的规范性要求如 tile 对齐、同步范式沉淀为结构化条目。索引 §C 的扫描范围由 build_material_index.py 定义docs/guide/programming_guide/pro/**/*.md、docs/guide/quick_start/pro/**/*.md与docs/guide/introduction.md且不扫描 Tensor 专属指南目录三个 Pro 目录的根索引index.md或简介缺失时生成器会非零退出。8. 第 6–7 章Stage 3 设计事实输入与环境常量快照8.1 Stage 3 设计事实输入第 6 章是探索报告对下游的正式消费接口综合 §3API 约束 §4样例参考 §5教程指导三路证据。模板刻意将本章设计为只汇总事实与待裁定项设计问题已证实约束证据路径Stage 3 待裁定项{tile_or_sync_question}{documented_constraint}{path section}{decision_needed}每个设计问题行必须同时给出已证实约束有文档/样例证据支撑与Stage 3 待裁定项如 tile 尺寸、Module 划分、同步事件分配、topology从而把证据与决策严格分离。8.2 环境常量快照第 7 章从当前仓库的 API 文档和官方指定算子中提取硬件/版本相关常量供下游 Stage 3/4 全部引用不再各自写死。模板对此有两条硬性规则禁止预填历史参考值——每个值都必须来自本次文档遍历或官方样例扫描无法确认时写unknown并列入风险。需探测的常量清单常量探测方式UB 容量目标版本文档或官方样例路径标注 target/version/适用条件cross_core event_id 上限目标版本 API 文档路径标注取值范围地址对齐要求目标版本 API 文档路径标注 MemorySpace/适用条件Cube tile 对齐目标版本教学/文档路径标注 tile 尺寸对齐要求这一设计的意义在于Stage 3/4 引用的是本次扫描实时探测并带来源的常量而不是模型记忆或历史文档中的旧值从根本上避免版本漂移导致的 UB 超限、对齐错误等实现事故。9. 第 8–10 章风险评估、证据索引与结论9.1 风险评估8.1 阻断问题问题 / 原因 / 建议对应 SKILL 完成条件中无未解决阻断项典型阻断如某公式步骤无可行 API 链且替代组合也无法表达语义unsupported、SPEC 自相矛盾、官方样例清单有缺项、缓存缺失等8.2 注意事项注意点 / 说明记录非阻断但需警惕的事项如近似步骤的数值风险、候选 VF 组合的性能不确定性等。9.2 证据索引第 9 章按API 文档证据 / 算子样例证据 / 指南与教程文档证据三类汇总所有引用过的路径并在章首再次给出全量资料索引位置custom/{operator_name}/PRO_MATERIAL_INDEX.md。该章是报告的可审计性基础——每条结论都能沿证据索引回溯到具体文档片段或样例文件。9.3 结论第 10 章只有两个字段可行性: {可行 / 需调整 / 不可行}主要问题: {main_issue}该结论与模板头部 YAML 中的feasibility字段对应构成报告的头尾闭环。需注意需调整与不可行的判定边界按 SKILL.md没有可行调用链时标记unsupported并附查过的文档和失败原因发现 SPEC 自相矛盾时停止并要求回到需求阶段——这些是不可行/需调整的触发条件而可行必须满足完成条件中每个公式步骤都有可行 API 链。10. 与索引生成器的配合报告的事实底座EXPLORE_REPORT.md的取证范围完全由 PRO_MATERIAL_INDEX.md 决定而索引由 build_material_index.py 固定生成。从生成器源码可以确认以下实现事实命令行接口--devkit缓存绝对路径必填、--output索引输出路径必填、--check仅校验现有索引是否为最新不覆盖写只读与保护生成器只读 devkit失败时不覆盖已有索引输出必须位于 devkit 之外且不得覆盖生成器自身的输入manifest、模板、脚本本身完整性门禁API 根索引docs/pypto_pro/api/index.md、§B 清单项、§C 任一 Pro 目录及其根索引或简介缺失时生成器非零退出exit code 2同时校验模板占位符恰好出现一次且章节顺序正确、清单路径必须与pro_ops/下实际文件一一对应、行号连续且不重复清单严格性清单外样例不写入索引也不得参考——与模板a5 目录下其余文件不得参考的规则一致。SKILL.md 给出的标准调用方式为python skill-dir/scripts/build_material_index.py \ --devkit 缓存绝对路径 \ --output custom/op/PRO_MATERIAL_INDEX.md生成后可用--check验证索引未过期完成条件第 1 条要求 exit code 为 0。11. 完成条件与常见误区11.1 完成条件清单按 SKILL.md本阶段只有满足以下全部条件才算完成索引生成器以--check检查现有 INDEX 时 exit code 为 0每个公式步骤都有可行 API 链或带完整证据的unsupported所有采用的 API、平台常量、样例模式均带目标版本来源所有官方样例和 §C 文档均有适用性记录含不适用标记EXPLORE_REPORT 的 1–10 章节完整无未解决阻断项没有修改 SPEC也没有执行 Stage 3/4 决策。11.2 常见误区把报告写成设计文档在报告中顺便定下 tile 尺寸、Module 划分或同步方案——这违反模板第 6 章的边界声明且会干扰 Stage 3 的独立决策预填环境常量UB 容量、event_id 上限等直接采用历史文档值而不标注本次探测来源——违反第 7 章禁止预填历史参考值只读相似样例不遍历 §B 全部 13 个官方样例——违反第 4 章全量阅读要求会漏掉通用写法参考如尾块处理、分核策略编造 API找不到可行调用链时臆造不存在的 API 名称——必须标记unsupported并附查过的文档与失败原因跳过清单外文件检查参考pro_ops/中不在 official_samples.md 清单内的样例——清单是唯一权威清单外文件一律不得参考。12. 总结EXPLORE_REPORT.md模板是 PyPTO-Pro Stage 1 资料探索阶段证据纪律的载体它用 10 个章节把算子分类 → 公式分解 → API 映射 → 样例取证 → 教程约束 → 事实汇总 → 常量快照 → 风险评估 → 证据索引 → 可行性结论串成一条可审计的取证链并与 PRO_MATERIAL_INDEX.md 的三个索引分区§A API / §B 官方样例 / §C 教程严格对应。所有结论都必须带目标版本来源、不允许预填历史值、不允许编造 API、不允许越界做设计决策——这些约束保证了进入 Stage 3 的事实底座与目标版本一致是五阶段流水线稳定推进的前提。对于需要在 PyPTO-Pro 上开发算子的开发者掌握本模板的填写规范等于掌握了用证据回答可行性的标准方法。关联文件速查作用路径探索报告模板本文主题templates/explore_report.md资料索引模板§A/§B/§C 三节templates/pro_material_index.mdSkill 工作流与证据优先级SKILL.md索引生成器实现scripts/build_material_index.py官方指定算子清单§B 唯一来源references/official_samples.mdStage 1 在五阶段流程中的位置orchestration.md【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PyPTO-Pro 资料探索报告EXPLORE_REPORT模板深度解析与实战指南【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym本文以 cannbot-skills/ops/pypto-pro-material-explore/templates/explore_report.md 模板为骨架结合 SKILL.md 定义的工作流、索引生成器 与 官方样例清单 的实现细节系统讲解 PyPTO-Pro 五阶段算子开发流程中 Stage 1 资料探索报告EXPLORE_REPORT.md的生成逻辑、章节结构与实战填写规范帮助开发者理解如何基于目标版本资料取证、判定算子可行性、并为 Stage 3 架构设计提供事实输入。导读在 PyPTO-Pro 深度编排流程中EXPLORE_REPORT.md是 Stage 1需求规划的关键交付物之一回答当前目标版本能否实现、证据在哪里、有哪些约束这三个问题。本文以pypto-pro-material-exploreskill 的报告模板为核心逐一拆解其 10 个章节的填写逻辑并结合仓库内索引生成器、官方样例清单与编排合同说明每条证据的来源与验证方式。读完本文你将掌握如何将 SPEC 公式分解为原子数学步骤并映射到vf.*/pl.*API如何按纯 Cube / 纯 Vec / VC 融合三类组织官方样例取证如何沉淀环境常量快照并输出可供 Stage 3 直接消费的设计事实。1. 模板定位一份只取证、不决策的事实报告EXPLORE_REPORT.md不是设计文档也不是性能报告。按 pypto-pro-material-explore/SKILL.md 的定义该 skill只负责回答当前目标版本能否实现、证据在哪里、有哪些约束需求语义以 SPEC 为准KB 路由由 plan 负责最终 Module / tile / 同步方案由 Stage 3架构设计决定。因此报告本身不得冻结 topology、Module、tile、同步事件或 KB_SELECTION只能提出 Stage 3 需解决的设计问题。这一约束直接体现在模板的两处设计上模板头部 YAML Front Matter 携带op_name与feasibility可行 / 需调整 / 不可行两个字段让可行性结论可在阶段间机器可读地流转第 6 章Stage 3 设计事实输入明确写明本节是 Stage 3 的消费入口只汇总事实与待裁定项不冻结 tile、Module、同步事件或 topology这些由 Stage 3 决定。从编排层面看该报告与PRO_MATERIAL_INDEX.md一起由 orchestrator 在 Stage 1 调度pypto-pro-op-planner加载 skillpypto-pro-op-plan时串行产出随后由 verifier 执行stage1-check门禁校验PASS 后complete_stage(1)自动推进 Stage 2见 orchestration.md。也就是说报告结构是否完整第 1–10 章齐全、无未解决阻断项是 Stage 1 门禁的一部分。1.1 证据优先级SKILL.md 明确了四条证据优先级报告中的所有结论必须落到这四类来源上当前$PYPTO_DEVKIT_DIR中目标版本的 API 文档official_samples.md 指定且缓存中存在的官方样例当前缓存中的 Pro 编程指南、快速入门与共享简介KB 中与当前 class 匹配、状态为validated的补充材料。关键约束API 签名、平台常量和能力边界以前三项为准KB 或模型记忆不能覆盖目标版本事实。共享的 buffer / Vector 性能规则只读取$CANNBOT_CONFIG_ROOT/references/performance-constraints.md本 skill 不复制或重新解释完整规则只为每个相关步骤记录目标版本证据供 Stage 3 裁定。2. 章节总览模板的 10 段骨架模板由 10 个章节构成其中标记!-- REQUIRED --的为必填段1、3、4、5、6、7、8、9、10第 2 章公式分解虽未标 REQUIRED 但为第 3 章 API 映射的事实基础实际也不可省略。整体逻辑链条为SPEC 输入 → 1 概述分类 → 2 公式分解原子步骤 → 3 API 映射与约束探索方向 1索引 §A → 4 算子样例探索探索方向 2索引 §B → 5 教程与设计指南探索方向 3索引 §C → 6 Stage 3 设计事实输入汇总 345 → 7 环境常量快照 → 8 风险评估 → 9 证据索引 → 10 结论feasibility三个探索方向分别对应 PRO_MATERIAL_INDEX 模板 的 §AAPI 文档、§B官方指定算子样例、§C教程与设计指南三节——探索报告的取证广度与索引的扫描范围一一对应。3. 第 1 章概述——输入摘要、算子分类与 API 类别预判3.1 输入摘要{输入内容摘要}应浓缩 SPEC 中的算子名称、数学公式/计算逻辑、输入输出 tensor 的 dtype 等事实。注意 SKILL 边界算子名称、公式、I/O dtype 由用户提供shape 在 design 阶段才设计无需在输入阶段确认。3.2 算子分类模板要求判定计算引擎类型取值Vector / Cube / VF / 混合判断依据是公式中是否含matmul→ Cube矩阵计算仅逐元素 / 归约 → Vector需要 VF 指令 → VF。3.3 API 类别预判表模板预置了一张六行 API 类别表数据搬运 / VF 实现 / 矩阵计算 / 系统访问 / 控制流 / 工具每行需填写是否涉及、关键 API、指定算子是否覆盖。这张表的作用是预筛在正式逐 API 阅读前先圈定本算子大概率会用到的 API 家族。模板注释强调实际 API 以本次 PRO_MATERIAL_INDEX §A 扫描结果为准即预判表不是结论只是检索起点。模板中预填的关键 API 清单本身即是很好的候选词表数据搬运load_tile/store_tile/load/store/moveVF 实现vf.add/vf.mul/vf.max/vf.astype/vf.exp_sub/vf.muls等矩阵计算Cubematmul/matmul_acc系统访问get_block_idx/get_block_num控制流section_vector/section_cube/pl.range工具动态维度声明 /set_validshape/make_tile_group。4. 第 2 章公式分解——不改变表达式的原子化公式分解是 API 映射的前置步骤。SKILL.md 第 2 步规定把 SPEC 的公式/算法拆成原子数学步骤但不改变表达式。对需要近似的步骤必须记录近似来源、适用区间和至少两个已知点的数值 sanity check。发现 SPEC 自相矛盾时停止并回到需求阶段。模板的分解表结构为步骤操作类型数学表达vf.* 调用链vec/ pl.* 调用链cube说明{n}{op_type}{math_expr}vf.{api1}→vf.{api2}vec/pl.{api1}cube{desc}注意第 2 章表中已出现vf.* 调用链 / pl.* 调用链列这与第 3 章的 API 映射表结构对称——第 2 章是预填的候选链第 3 章是经文档验证后的最终链两章共同保证每个公式步骤都有可行 API 链或带完整证据的 unsupported这一完成条件。5. 第 3 章API 文档探索——从索引 §A 到约束表5.1 API 映射结果探索方向 1 基于PRO_MATERIAL_INDEX.md§A。SKILL.md 第 3 步规定了映射细则从索引 §A 定位候选 API 并阅读全文名称不足以定位时只在 §A 已列文档中全文检索结论写入 EXPLORE_REPORT不手工修改索引记录准确签名、参数单位/语义、dtype、shape、layout、MemorySpace、tile 和版本约束Vector 步骤先查目标版本是否有单一 VF API没有时再记录有文档依据的 VF 组合两者都无法完整表达语义才标记unsupported——本阶段不做 VF / tile-op 性能选择Cube 步骤记录对应pl.*API、累加语义及 layout 约束没有可行调用链时标记unsupported附查过的文档和失败原因不得编造 API。映射结果表的状态列取值{直接可用/需组合/不支持}约束满足列取值{✓/⚠/✗}将能不能用和约束满不满足两个维度解耦。5.2 替代方案表模板要求每个 Vector 步骤均填写无 Vector 步骤时注明不适用。表列包括默认 VF 映射、API 依据API path excerpt、目标版本、适用条件dtype/shape/layout、交接状态待 Stage 3 核对已选 KB 模板。该表是第 3.1 节需组合情形的展开明确记录组合依据来自哪个文档片段保证 Stage 3 可以回溯。5.3 API 约束表约束表是第 3 章信息密度最高的部分要求按三类维度记录参数语义如 offset 单位、layout 取值、matmul module 累加语义寄存器级行为如vf.astype的 BF16/FP32 映射同名差异如vf.gather与pl.gather的差异。5.4 MemorySpace 约束表操作MemorySpace约束{op}{space}{constraint}MemorySpace 约束UB / L1 / L0A / L0B / L0C / GM直接影响第 7 章环境常量快照与 Stage 3 的 tile 规划因此单独成表而非并入 5.3。6. 第 4 章算子样例探索——按 cube/vec 组成分类取证6.1 官方样例的唯一来源探索方向 2 基于索引 §B。需要特别强调的是官方指定算子是精选实现参考a5 目录下其余文件不得参考模板注释原文。§B 的内容来自 official_samples.md——该文件是整个 PyPTO-Pro 工作流的统一官方样例索引来源orchestrator 资源缓存准备时按清单装配$PYPTO_DEVKIT_DIR/pro_ops/只保留清单内文件material-explore 生成索引 §B 时以它为唯一来源所有 skill/agent 提到官方指定算子样例§B时最终都指向该文件。当前清单共 13 个样例覆盖三类分类代表样例缓存相对路径elementwise纯 Vecaddpro_ops/element_wise/test_add.pymatmul 入门 / 性能纯 Cubematmul_8k_example、matmul_perf_asw_4k/8k_k128含动态轴变体pro_ops/matmul/test_matmul_*.pyFlashAttention 教学 / 性能 / FlexAttentionVC 融合fa_tilingkey_attn_mask、fa_with_mask、fa_perf_tkv_preload、flex_attentionpro_ops/fa/test_*.pyVF TopK / VF LayerNorm / VF Softmaxquant_lightning_indexer_vf、layernorm_tile_group_vf、softmax_tile_group_vfpro_ops/lightning_indexer/、pro_ops/vf_api/6.2 全量样例参考表模板要求全量阅读索引 §B 中所有官方指定算子样例并按 cube/vec 组成分类记录参考价值而非只读与当前算子最像的那一个纯 Cube 样例matmul 类记录 cube tile 管理、K 累加链、matmul_accmodule、L1/L0 布局、set_mm_layout_transform等可复用点纯 Vec 样例elementwise 类、vf_api 类记录 vf 指令组合、make_tile_group双缓冲、auto_mutex、load_align/store_align等VC 融合样例FA 类、lightning_indexer 类记录section_cube → acc_to_vec → section_vector衔接、cross_core 流水、多 Module 分块等。选参考原则在模板中有明确表述优先从当前算子对应分类中提取直接可复用模式同时从所有样例中提取通用写法参考API 用法、分核策略、同步事件管理、尾块处理等。6.3 可复用模式、差异分析与推荐4.2 可复用模式分为两层直接可复用来自当前算子对应分类的样例标注来源路径覆盖 API 调用链、Tile 配置、同步策略、循环结构四项与通用写法参考来自所有样例覆盖 API 用法、分核覆盖/重叠/空转检查、event_id 分配/隔离、valid_shape/compact/fillpad 尾块处理。4.3 差异分析用示例做法 → 本算子需求 → 调整建议三列对比防止把样例写法无差别照搬。4.4 高参考价值样例推荐只作推荐、不否定其余样例理由是对当前算子参考价值高的具体分析。模板还提示可按pypto-pro-op-kb/examples/kernel-index.md补充条目但仅允许validated、路径存在且 topology/dtype/layout/platform 匹配的代码study状态不能作为正确性依据。7. 第 5 章教程与设计指南探索探索方向 3 基于索引 §C。SKILL.md 第 5 步要求逐一评估索引 §C 中的 Pro 编程指南、快速入门及共享简介记录与当前算子相关的设计模式、适用条件和章节路径不相关也要标记不适用——这是为了证明遍历完整避免遗漏可能的约束。5.1 适用的设计模式表逐行填写每个指南文档来源目录、设计模式、适用性适用性列需写对本算子的指导意义或不适用5.2 来自教程的关键约束与建议记录来源、约束/建议、影响将教程中的规范性要求如 tile 对齐、同步范式沉淀为结构化条目。索引 §C 的扫描范围由 build_material_index.py 定义docs/guide/programming_guide/pro/**/*.md、docs/guide/quick_start/pro/**/*.md与docs/guide/introduction.md且不扫描 Tensor 专属指南目录三个 Pro 目录的根索引index.md或简介缺失时生成器会非零退出。8. 第 6–7 章Stage 3 设计事实输入与环境常量快照8.1 Stage 3 设计事实输入第 6 章是探索报告对下游的正式消费接口综合 §3API 约束 §4样例参考 §5教程指导三路证据。模板刻意将本章设计为只汇总事实与待裁定项设计问题已证实约束证据路径Stage 3 待裁定项{tile_or_sync_question}{documented_constraint}{path section}{decision_needed}每个设计问题行必须同时给出已证实约束有文档/样例证据支撑与Stage 3 待裁定项如 tile 尺寸、Module 划分、同步事件分配、topology从而把证据与决策严格分离。8.2 环境常量快照第 7 章从当前仓库的 API 文档和官方指定算子中提取硬件/版本相关常量供下游 Stage 3/4 全部引用不再各自写死。模板对此有两条硬性规则禁止预填历史参考值——每个值都必须来自本次文档遍历或官方样例扫描无法确认时写unknown并列入风险。需探测的常量清单常量探测方式UB 容量目标版本文档或官方样例路径标注 target/version/适用条件cross_core event_id 上限目标版本 API 文档路径标注取值范围地址对齐要求目标版本 API 文档路径标注 MemorySpace/适用条件Cube tile 对齐目标版本教学/文档路径标注 tile 尺寸对齐要求这一设计的意义在于Stage 3/4 引用的是本次扫描实时探测并带来源的常量而不是模型记忆或历史文档中的旧值从根本上避免版本漂移导致的 UB 超限、对齐错误等实现事故。9. 第 8–10 章风险评估、证据索引与结论9.1 风险评估8.1 阻断问题问题 / 原因 / 建议对应 SKILL 完成条件中无未解决阻断项典型阻断如某公式步骤无可行 API 链且替代组合也无法表达语义unsupported、SPEC 自相矛盾、官方样例清单有缺项、缓存缺失等8.2 注意事项注意点 / 说明记录非阻断但需警惕的事项如近似步骤的数值风险、候选 VF 组合的性能不确定性等。9.2 证据索引第 9 章按API 文档证据 / 算子样例证据 / 指南与教程文档证据三类汇总所有引用过的路径并在章首再次给出全量资料索引位置custom/{operator_name}/PRO_MATERIAL_INDEX.md。该章是报告的可审计性基础——每条结论都能沿证据索引回溯到具体文档片段或样例文件。9.3 结论第 10 章只有两个字段可行性: {可行 / 需调整 / 不可行}主要问题: {main_issue}该结论与模板头部 YAML 中的feasibility字段对应构成报告的头尾闭环。需注意需调整与不可行的判定边界按 SKILL.md没有可行调用链时标记unsupported并附查过的文档和失败原因发现 SPEC 自相矛盾时停止并要求回到需求阶段——这些是不可行/需调整的触发条件而可行必须满足完成条件中每个公式步骤都有可行 API 链。10. 与索引生成器的配合报告的事实底座EXPLORE_REPORT.md的取证范围完全由 PRO_MATERIAL_INDEX.md 决定而索引由 build_material_index.py 固定生成。从生成器源码可以确认以下实现事实命令行接口--devkit缓存绝对路径必填、--output索引输出路径必填、--check仅校验现有索引是否为最新不覆盖写只读与保护生成器只读 devkit失败时不覆盖已有索引输出必须位于 devkit 之外且不得覆盖生成器自身的输入manifest、模板、脚本本身完整性门禁API 根索引docs/pypto_pro/api/index.md、§B 清单项、§C 任一 Pro 目录及其根索引或简介缺失时生成器非零退出exit code 2同时校验模板占位符恰好出现一次且章节顺序正确、清单路径必须与pro_ops/下实际文件一一对应、行号连续且不重复清单严格性清单外样例不写入索引也不得参考——与模板a5 目录下其余文件不得参考的规则一致。SKILL.md 给出的标准调用方式为python skill-dir/scripts/build_material_index.py \ --devkit 缓存绝对路径 \ --output custom/op/PRO_MATERIAL_INDEX.md生成后可用--check验证索引未过期完成条件第 1 条要求 exit code 为 0。11. 完成条件与常见误区11.1 完成条件清单按 SKILL.md本阶段只有满足以下全部条件才算完成索引生成器以--check检查现有 INDEX 时 exit code 为 0每个公式步骤都有可行 API 链或带完整证据的unsupported所有采用的 API、平台常量、样例模式均带目标版本来源所有官方样例和 §C 文档均有适用性记录含不适用标记EXPLORE_REPORT 的 1–10 章节完整无未解决阻断项没有修改 SPEC也没有执行 Stage 3/4 决策。11.2 常见误区把报告写成设计文档在报告中顺便定下 tile 尺寸、Module 划分或同步方案——这违反模板第 6 章的边界声明且会干扰 Stage 3 的独立决策预填环境常量UB 容量、event_id 上限等直接采用历史文档值而不标注本次探测来源——违反第 7 章禁止预填历史参考值只读相似样例不遍历 §B 全部 13 个官方样例——违反第 4 章全量阅读要求会漏掉通用写法参考如尾块处理、分核策略编造 API找不到可行调用链时臆造不存在的 API 名称——必须标记unsupported并附查过的文档与失败原因跳过清单外文件检查参考pro_ops/中不在 official_samples.md 清单内的样例——清单是唯一权威清单外文件一律不得参考。12. 总结EXPLORE_REPORT.md模板是 PyPTO-Pro Stage 1 资料探索阶段证据纪律的载体它用 10 个章节把算子分类 → 公式分解 → API 映射 → 样例取证 → 教程约束 → 事实汇总 → 常量快照 → 风险评估 → 证据索引 → 可行性结论串成一条可审计的取证链并与 PRO_MATERIAL_INDEX.md 的三个索引分区§A API / §B 官方样例 / §C 教程严格对应。所有结论都必须带目标版本来源、不允许预填历史值、不允许编造 API、不允许越界做设计决策——这些约束保证了进入 Stage 3 的事实底座与目标版本一致是五阶段流水线稳定推进的前提。对于需要在 PyPTO-Pro 上开发算子的开发者掌握本模板的填写规范等于掌握了用证据回答可行性的标准方法。关联文件速查作用路径探索报告模板本文主题templates/explore_report.md资料索引模板§A/§B/§C 三节templates/pro_material_index.mdSkill 工作流与证据优先级SKILL.md索引生成器实现scripts/build_material_index.py官方指定算子清单§B 唯一来源references/official_samples.mdStage 1 在五阶段流程中的位置orchestration.md【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
