external-cannbot-ops-pypto-op-design

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 结构等完整设计内容，用于指导后续代码实现。

1. 从用户输入提取算子名称、规格信息等必要内容
2. 如果信息不足，向用户逐步提问补充
3. 按工作流执行设计方案生成（输入验证 → 信息收集 → 生成草稿 → 确认 → 输出）
4. 输出 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 项检查表逐项检查：

1. API 映射是否具体

   • 每个关键步骤都写出明确的 PyPTO API 名称
   • 不得使用“相关 API”“合适的 API”这类空泛表述

2. Tiling / Loop 是否说明理由

   • 不仅给出结论，还要说明为什么这样设计
   • 至少写清适用条件、判断依据或限制

3. 验证方案是否覆盖典型配置

   • 至少覆盖算子规格中的主要典型配置
   • 不得只写“后续验证”或“按需补充”

4. 风险点是否具体

   • 每个风险点都要说明触发场景或影响
   • 不得只写“注意性能问题”“注意边界情况”

5. 是否存在空话或占位符

   • 不得残留 {placeholder}、TODO、待补充
   • 不得出现大段“通常/一般/按需调整/可根据情况修改”之类空泛描述

输出检查结果时，必须给出：

• 通过 / 不通过
• 不通过原因
• 修复建议

如果存在不通过项，只修复不通过的章节，不重写整篇文档。

回修要求：

• 保留已通过的章节内容
• 只补充缺失的 API、理由、验证配置、风险说明
• 如果信息不足，明确写“待确认”，不得编造确定性结论

自检通过条件：

• 5 项检查中至少通过 4 项
• “API 映射是否具体”必须通过
• “Tiling / Loop 是否说明理由”必须通过
• 不得残留占位符

---

7. 知识库使用规范

知识库文件

文件	内容	使用时机
references/quick_ref.md	tiling / loop / runtime 核心原则速查	阶段 1 特征分析 + 阶段 2 信息收集时读取

详细的 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}