| name | external-cannbot-ops-pypto-op-design |
| description | 当需要设计 PyPTO 算子实现方案时使用此 skill。基于算子规格与相关上下文，生成 DESIGN.md（含 API 映射、Tiling 策略、Loop 结构）。Triggers: 生成设计方案、生成 design、设计这个算子、写 DESIGN.md、算子设计、API 映射、Tiling 策略、tiling strategy、Loop 结构、数据切分、怎么切分数据、怎么做 tiling、设计文档、实现方案。 |
| original-name | pypto-op-design |
| synced-from | https://gitcode.com/cann/cannbot-skills |
| synced-date | 2026-05-26 |
| synced-commit | ac5bbd2b4cf427d011874e11f8d1e8b1bef66eda |
| license | UNKNOWN |
PyPTO 算子设计方案生成
基于算子规格与相关上下文，生成结构化的算子设计文档 DESIGN.md，涵盖 API 映射、数据规格、tiling 策略、loop 结构等完整设计内容，用于指导后续代码实现。
- 从用户输入提取算子名称、规格信息等必要内容
- 如果信息不足，向用户逐步提问补充
- 按工作流执行设计方案生成（输入验证 → 信息收集 → 生成草稿 → 确认 → 输出）
- 输出 DESIGN.md 到当前目录或用户指定位置
1. 所需信息
| 项目 | 说明 |
|---|
| 输入 | 算子规格信息（如 SPEC.md）、参考实现（可选）、相关上下文 |
| 输出 | DESIGN.md，路径为当前目录或用户指定位置 |
2. 算子信息获取
从输入中提取算子名称和规格信息。如果信息不足，向用户逐步提问补充。
3. 规格字段检查
读取算子规格信息后，检查字段完整性：
必须字段（缺失则报错退出）
| 字段 | 用途 |
|---|
| 算子名称 | 目录名、文件命名 |
| 数学公式 | API 映射、计算逻辑设计 |
| 输入规格 | 数据规格设计、Tiling 策略 |
| 输出规格 | 数据规格设计 |
建议字段（缺失时引导补充）
| 字段 | 用途 | 缺失时处理 |
|---|
| 典型配置 | 验证方案、性能目标 | 引导用户补充 |
| 算法描述 | 复杂算子的 Loop/Tiling 设计 | 简单算子可省略，复杂算子提示补充 |
| 动态轴范围 | Tiling/Loop 策略参考 | 使用默认范围 |
典型配置缺失时的处理
引导用户提供，用户跳过时根据动态轴范围推荐默认配置，确认后补充到算子规格信息中。
典型配置采用 7 列格式：
| 配置名称 | 类型 | 优先级 | 参数 | 输入 Shape | 输出 Shape | 说明 |
|---|
4. 工作流程
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 1：输入验证与特征分析 │
├───────────────────────────────────────────────────────────────────┤
│ 1. 读取算子规格信息 │
│ 2. 验证必须字段完整性 │
│ 3. 分析算子特征： │
│ - 类型判断：含 matmul → Cube；仅逐元素/归约 → Vector │
│ - 复杂度：简单（≤5 步）/ 中等（5-15 步）/ 复杂（>15 步） │
│ - Loop 判断：按 references/quick_ref.md §2.1 判据表逐条检查 │
│ - 动态 shape：检查规格信息中是否声明动态轴 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 2：信息收集 │
├───────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 若输入已包含约束、参考实现等信息，优先复用 │ │
│ │ 否则自行搜索补充 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ ┌────────────────────┐ │
│ │ 知识库查询 │ │ 动态查询文档 │ │
│ │ - references/ │ │ - 搜索 docs/ │ │
│ │ quick_ref.md │ │ - 查找类似算子示例 │ │
│ │ - 核心原则速查 │ │ - 验证 API 规格 │ │
│ └───────────────────┘ └────────────────────┘ │
│ │ │ │
│ └──────────┬─────────────┘ │
│ ▼ │
│ 合并生成信息 │
│ 成功标准：每个公式步骤均找到对应 PyPTO API 或标记为 unsupported │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 3：生成 DESIGN.md │
├───────────────────────────────────────────────────────────────────┤
│ 基于模板 templates/design-template.md 生成完整 DESIGN.md 草稿 │
│ 包含全部 9 个章节 │
│ 成功标准： │
│ ✓ DESIGN.md 包含全部 9 个章节标题 │
│ ✓ §2 API 映射表每步均有对应 PyPTO API（或标记 unsupported） │
│ ✓ §5 Loop 结构已按场景 A 或场景 B 填写（无空白占位） │
│ ✓ 无残留 {placeholder} 占位符 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 4：质量自检 │
├───────────────────────────────────────────────────────────────────┤
│ 按 5 项检查表逐项检查： │
│ □ API 映射是否具体 │
│ □ Tiling / Loop 是否说明理由 │
│ □ 验证方案是否覆盖典型配置 │
│ □ 风险点是否具体 │
│ □ 是否存在空话或占位符 │
│ │
│ 输出：通过 / 不通过 + 修复建议 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 5：定向回修（如需要） │
├───────────────────────────────────────────────────────────────────┤
│ 仅修复不通过项，不重写整篇文档 │
│ 保留已通过章节；信息不足时写”待确认”，不得编造结论 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 6：输出文件 │
├───────────────────────────────────────────────────────────────────┤
│ 自检通过后输出：DESIGN.md │
│ 如回修后仍有关键未决项，向用户确认缺口 │
│ 如果文件已存在 → 通过 AskUserQuestion 询问是否覆盖 │
└───────────────────────────────────────────────────────────────────┘
5. DESIGN.md 章节结构
DESIGN.md 包含 9 个章节，模板文件位于: templates/design-template.md
| 章节 | 内容 | 信息来源 |
|---|
| 1. 概述 | 算子名称、功能、数学公式、数据流图 | 算子规格（基础信息、数据流图） |
| 2. API 映射设计 | 公式分解、PyPTO API 映射表、计算步骤 | references/quick_ref.md + docs/ |
| 3. 数据规格设计 | Input/Output dataclass、中间 Tensor、数据格式、JIT 配置 | 算子规格（数据规格） |
| 4. Tiling 策略 | 算子类型判断、TileShape 配置、设置依据 | references/quick_ref.md + docs/ |
| 5. Loop 结构设计 | 是否需要 loop、静态/动态轴处理、尾块处理 | references/quick_ref.md + docs/ |
| 6. 验证方案 | Golden 函数设计、测试用例（基于典型配置）、精度标准 | 算子规格（精度要求、典型配置） |
| 7. 性能指标与开箱配置 | 性能目标、TileShape、pass_options、runtime_options | references/quick_ref.md + docs/ |
| 8. 风险点与注意事项 | 已知约束、常见错误规避、特殊场景处理 | 知识库 + docs/ |
| 9. 交付件清单 | 目录结构、文件清单、命名规范、生成顺序 | 固定模板 |
章节 5（Loop 结构设计） 始终生成：不需要 Loop 时使用场景 A 模板，需要 Loop 时使用场景 B 模板。
6. 质量自检与定向回修
生成 DESIGN.md 草稿后，必须按以下 5 项检查表逐项检查：
-
API 映射是否具体
- 每个关键步骤都写出明确的 PyPTO API 名称
- 不得使用“相关 API”“合适的 API”这类空泛表述
-
Tiling / Loop 是否说明理由
- 不仅给出结论，还要说明为什么这样设计
- 至少写清适用条件、判断依据或限制
-
验证方案是否覆盖典型配置
- 至少覆盖算子规格中的主要典型配置
- 不得只写“后续验证”或“按需补充”
-
风险点是否具体
- 每个风险点都要说明触发场景或影响
- 不得只写“注意性能问题”“注意边界情况”
-
是否存在空话或占位符
- 不得残留
{placeholder}、TODO、待补充
- 不得出现大段“通常/一般/按需调整/可根据情况修改”之类空泛描述
输出检查结果时，必须给出：
如果存在不通过项，只修复不通过的章节，不重写整篇文档。
回修要求：
- 保留已通过的章节内容
- 只补充缺失的 API、理由、验证配置、风险说明
- 如果信息不足，明确写“待确认”，不得编造确定性结论
自检通过条件：
- 5 项检查中至少通过 4 项
- “API 映射是否具体”必须通过
- “Tiling / Loop 是否说明理由”必须通过
- 不得残留占位符
7. 知识库使用规范
知识库文件
详细的 API 映射、Tiling 规则、Loop 策略、性能参数等信息通过搜索 docs/ 动态获取。
来源优先级
docs/（官方文档）→ 规则来源，API 规格验证
↓
输入中附带的约束限制、参考实现等信息 → 用户提供
↓
models/（生产代码）→ 实践参考
↓
examples/（教学示例）→ 教学参考
知识库文件是预整理的经验总结，使用时需要到 docs/ 中验证其准确性。当知识库内容与 docs/ 不一致时，以 docs/ 为准。
8. 典型配置使用
算子规格中的典型配置在 DESIGN.md 中的用途：
| 用途 | 使用的配置 | 对应 DESIGN.md 章节 |
|---|
| 验证方案 | 所有典型配置（性能+功能） | §6 验证方案 |
| 性能目标 | 性能类配置（性能_P0, 性能_P1） | §7 性能指标 |
| Tiling 参考 | 性能_P0 的 shape | §4 Tiling 策略 |
典型配置 7 列格式：
| 配置名称 | 类型 | 优先级 | 参数 | 输入 Shape | 输出 Shape | 说明 |
|---|
字段说明：
- 类型：
功能 或 性能。性能类配置也需先验证功能正确性
- 优先级：P0（核心/必须） > P1（重要/推荐） > P2 > P3
- 验证顺序：性能_P0 → 性能_P1 → 功能_P0 → 功能_P1
9. 错误处理
| 场景 | 处理方式 |
|---|
| 缺少算子规格信息 | 报错退出，提示先提供需求信息 |
| 必须字段缺失 | 列出缺少的字段，引导用户补充 |
| 典型配置缺失 | 引导用户提供或确认推荐配置 |
| 知识库查询未命中 | 动态搜索 docs/ 和 models/ 补充信息 |
| docs 查询失败 | 基于 AI 知识生成，标注"需人工确认" |
| DESIGN.md 已存在 | 通过 AskUserQuestion 询问是否覆盖 |
容错策略：
- 非必须字段缺失时，使用默认值继续生成
- 必须字段缺失时，明确告知用户需要什么
- 知识库无法匹配时，降级为基于 AI 知识生成，并在对应章节标注"需人工确认"
10. 完成报告
文件生成完成后，先自检以下各项，再向用户展示报告：
- DESIGN.md 包含全部 9 个章节
- §2 API 映射无 unsupported 项（有则在报告中列出）
- §5 Loop 结论与阶段 1 特征分析一致
- API 映射是否具体：通过 / 不通过
- Tiling / Loop 理由：通过 / 不通过
- 验证方案覆盖：通过 / 不通过
- 风险点具体性：通过 / 不通过
- 空话 / 占位符：通过 / 不通过
✅ 设计文档已生成:
• DESIGN.md
• API 映射：{N} 步全部映射 / {M} 步标记 unsupported
• Loop 结论：{不需要 / 需要 pypto.loop / 需要 loop_unroll}
• 质量检查：
- API 映射：{通过 / 不通过}
- Tiling / Loop 理由：{通过 / 不通过}
- 验证方案覆盖：{通过 / 不通过}
- 风险点具体性：{通过 / 不通过}
- 空话 / 占位符：{通过 / 不通过}
如果未达到自检通过条件，则输出：
⚠️ 当前文档为草稿，需人工补强：
• {问题 1}
• {问题 2}
