External Cannbot Ops Pypto Op Design

PyPTO 算子设计方案生成

基于算子规格与相关上下文，生成结构化的算子设计文档 DESIGN.md，涵盖 API 映射、数据规格、tiling 策略、loop 结构等完整设计内容，用于指导后续代码实现。

1. 从用户输入提取算子名称、规格信息等必要内容
2. 如果信息不足，向用户逐步提问补充
3. 按工作流执行设计方案生成（输入验证 → 信息收集 → 生成草稿 → 确认 → 输出）
4. 输出 DESIGN.md 到当前目录或用户指定位置

1. 所需信息

2. 算子信息获取

从输入中提取算子名称和规格信息。如果信息不足，向用户逐步提问补充。

3. 规格字段检查

读取算子规格信息后，检查字段完整性：

必须字段（缺失则报错退出）

建议字段（缺失时引导补充）

典型配置缺失时的处理

引导用户提供，用户跳过时根据动态轴范围推荐默认配置，确认后补充到算子规格信息中。

典型配置采用 7 列格式：

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

章节 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. 知识库使用规范

知识库文件

详细的 API 映射、Tiling 规则、Loop 策略、性能参数等信息通过搜索 docs/ 动态获取。

来源优先级

docs/（官方文档）→ 规则来源，API 规格验证
              ↓
输入中附带的约束限制、参考实现等信息 → 用户提供
              ↓
models/（生产代码）→ 实践参考
              ↓
examples/（教学示例）→ 教学参考

知识库文件是预整理的经验总结，使用时需要到 docs/ 中验证其准确性。当知识库内容与 docs/ 不一致时，以 docs/ 为准。

8. 典型配置使用

算子规格中的典型配置在 DESIGN.md 中的用途：

典型配置 7 列格式：

字段说明：

• 类型：功能 或 性能。性能类配置也需先验证功能正确性
• 优先级：P0（核心/必须） > P1（重要/推荐） > P2 > P3
• 验证顺序：性能_P0 → 性能_P1 → 功能_P0 → 功能_P1

9. 错误处理

容错策略：

• 非必须字段缺失时，使用默认值继续生成
• 必须字段缺失时，明确告知用户需要什么
• 知识库无法匹配时，降级为基于 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}