# External Cannbot Ops Pypto Op Design

> 当需要设计 PyPTO 算子实现方案时使用此 skill。基于算子规格与相关上下文，生成 DESIGN.md（含 API 映射、Tiling 策略、Loop 结构）。Triggers: 生成设计方案、生成 design、设计这个算子、写 DESIGN.md、算子设计、API 映射、Tiling 策略、tiling strategy、Loop 结构、数据切分、怎么切分数据、怎么做 tiling、设计文档、实现方案。

- Skill: `ascend-ai-coding/external-cannbot-ops-pypto-op-design` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ascend-ai-coding/external-cannbot-ops-pypto-op-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ascend-ai-coding/external-cannbot-ops-pypto-op-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: UNKNOWN
- Author: ascend-ai-coding (https://skillmd.com/u/ascend-ai-coding)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ascend-ai-coding/external-cannbot-ops-pypto-op-design

---


# 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. 工作流程

```text
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 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](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](references/quick_ref.md) | tiling / loop / runtime 核心原则速查 | 阶段 1 特征分析 + 阶段 2 信息收集时读取 |

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

### 来源优先级

```text
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 理由：通过 / 不通过
- 验证方案覆盖：通过 / 不通过
- 风险点具体性：通过 / 不通过
- 空话 / 占位符：通过 / 不通过

```text
✅ 设计文档已生成:
  • DESIGN.md
  • API 映射：{N} 步全部映射 / {M} 步标记 unsupported
  • Loop 结论：{不需要 / 需要 pypto.loop / 需要 loop_unroll}
  • 质量检查：
    - API 映射：{通过 / 不通过}
    - Tiling / Loop 理由：{通过 / 不通过}
    - 验证方案覆盖：{通过 / 不通过}
    - 风险点具体性：{通过 / 不通过}
    - 空话 / 占位符：{通过 / 不通过}
```

如果未达到自检通过条件，则输出：

```text
⚠️ 当前文档为草稿，需人工补强：
  • {问题 1}
  • {问题 2}
```