External Cannbot Ops Pypto API Explore

pypto-api-explore

使用 Explore subagent 探索 PyPTO API，为算子开发提供 API 映射、约束检查和 Tiling 需求分析。

输入

接受任意形式的输入，提取算子计算逻辑：

• 自然语言描述（如"计算 softmax"）
• 数学公式（如 softmax(x) = exp(x)/sum(exp(x))）
• 代码片段（PyTorch 或伪代码）
• 已有的 spec 文档内容

如果信息不足，向用户提问补充。

输出

• 输出件：API_REPORT.md
• 格式：markdown，使用 templates/api_report.md 模板
• 输出路径：当前目录或用户指定位置
• front matter：至少填写 schema_version、op_name，并建议填充 supported_dtypes、axes_list、shape_constraints、tiling_required、feasibility（其中 axes_list 应为 YAML 列表，例如 ['N'] 或 ['N','M']）

核心工作流

注意：必须使用 Explore subagent 进行 API 和约束探索，确保搜索的全面性和准确性。

步骤 1: 输入解析

接受任意形式输入，提取：

• 算子名称（如有）
• 数学公式 / 计算逻辑
• 输入输出规格（shape、dtype）
• 其他约束条件

步骤 2: 公式分解

将计算逻辑分解为原子操作序列：

操作类型：

• elementwise: add, sub, mul, div, exp, log, sin, cos...
• reduction: sum, max, min, mean, var...
• matmul: matmul, bmm, linear...
• shape: reshape, transpose, concat...
• index: gather, scatter, index_select...
• activation: relu, sigmoid, softmax...

步骤 3: 并行探索

将 API 探索、参考实现搜索和约束探索合并为三个并行的 Explore subagent，分别负责不同的一级目录。必须在同一条消息中同时发起所有 Agent 调用，确保并行执行。

Explore subagent 1: pypto/docs/zh/ — API 文档与约束

搜索范围：pypto/docs/zh/ 目录

任务：

1. 查 pypto/docs/zh/api/operation/index.md 确认 API 存在性
2. 读取具体 API 文档 pypto/docs/zh/api/operation/pypto-*.md 获取参数和约束
3. 未找到 → 标记 unsupported，尝试 substitute 方案
4. 提取入口约束（pypto/docs/zh/api/others/pypto-from_torch.md）：dtype、contiguous、format
5. 提取 API 约束：dtype 支持、shape 范围、广播规则、特殊值限制
6. 提取 Tiling 约束（pypto/docs/zh/api/config/pypto-set_vec_tile_shapes.md、pypto/docs/zh/api/config/pypto-set_cube_tile_shapes.md）
7. 查阅 pypto/docs/zh/api/datatype/ 获取 DataType、TileOpFormat 枚举信息

返回内容：API 映射表、三层约束检查结果、Tiling 需求、证据索引路径列表

Explore subagent 2: models/ — 生产级参考实现

搜索范围：models/ 目录，排除 models/experimental/（实验性实现，未充分验证，禁止参考）

任务：

1. 搜索与当前算子相关的生产级模型算子实现
2. 提取可复用的实现模式：API 调用方式、Tiling 配置、Loop 结构、数据类型处理
3. 不要找到一个就停止，遍历所有候选，收集所有匹配的参考实现

返回内容：每个匹配实现的路径、相似度、置信度、可复用点；若无匹配标注「无匹配」

Explore subagent 3: examples/ — 官方示例实现

搜索范围：examples/ 目录

任务：

1. 在 pypto/examples/02_intermediate/operators/ 搜索完整算子参考实现
2. 在 pypto/examples/03_advanced/patterns/ 搜索高级组合模式
3. 提取可复用的实现模式：API 调用方式、Tiling 配置、Loop 结构、边界处理
4. 不要找到一个就停止，遍历所有候选，收集所有匹配的参考实现

返回内容：每个匹配实现的路径、相似度、置信度、可复用点；若无匹配标注「无匹配」

并行探索结果汇总

等待三个 Explore subagent 全部返回后：

1. 合并 API 映射与约束检查结果（来自 subagent 1）
2. 合并参考实现搜索结果（来自 subagent 2 和 3），对比评估选择最佳匹配
3. 若存在多个高质量参考，在报告中列出 Top 3，并说明推荐首选及理由

步骤 4: 生成报告

基于 templates/api_report.md 模板生成 API_REPORT.md。

搜索目录

按一级目录分配到对应的 Explore subagent：

内嵌知识

操作 → API 映射速查

常见 Substitute（无直接 API）：

• mean → sum/count
• gelu → 组合 mul + sigmoid + mul（x * sigmoid(1.702 * x)），与 activation.py 一致
• sigmoid → 仅支持 FP32；需在其他 dtype 场景下先 cast 到 FP32 再调用

算子类型判断

公式分析
    │
    ├── 含 matmul/@ → Cube 类型 → set_cube_tile_shapes
    │
    ├── 仅逐元素/归约 → Vector 类型 → set_vec_tile_shapes
    │
    └── matmul + 逐元素 → 混合类型 → 两者都需要

硬约束速查

Checklist

验证 API_REPORT.md 的门禁条件：

1. 文件存在
2. 以下 6 个章节存在且内容不为空：
   • ## 1. 概述
   • ## 3. API 映射
   • ## 6. 参考实现（可标注「无匹配」但不可缺失）
   • ## 7. 风险评估
   • ## 8. 证据索引
   • ## 9. 结论

错误处理