External Cannbot Ops Pypto Intent Understand

PyPTO 算子需求意图理解

将用户的自然语言描述转化为结构化、完备的 PyPTO 算子开发需求文档（SPEC.md）。

核心原则

严格遵循以下核心原则，确保需求理解准确完整

原则 1：基于事实，不猜测

• ✅ 明确标注信息来源和置信度（✓ 高 / ⚠ 中 / ❓ 低）
• ✅ 不确定时主动询问，而非自行推断
• ❌ 禁止凭空猜测公式、规格或参数含义

原则 2：功能优先级明确

• ✅ 对所有功能（包括可选参数）标注优先级（P0/P1/P2/P3）
• ✅ P0 和 P1 功能必须在第一个版本实现
• ✅ 明确标注哪些功能暂不支持及原因

原则 3：可选参数深度分析

• ✅ 从代码位置、计算逻辑、实现复杂度、依赖关系四个维度分析可选参数
• ✅ 明确参数间的约束和互斥关系
• ❌ 禁止遗漏常用可选参数的分析

原则 4：信息完整性

• ✅ 必须信息（算子名称、公式、输入输出规格、动态轴）不可缺失
• ✅ 复杂算子必须提供算法描述
• ✅ 建议提供典型配置，便于后续 golden 生成和设计方案

原则 5：至少确认一次

• ✅ 除非用户强烈要求无需确认，否则至少确认一次
• ✅ 最多 2 次确认，整体确认而非逐项确认

原则 6：默认值必须显式披露

• ✅ 允许使用默认值的字段，必须在确认环节展示
• ✅ 默认值只能补齐非阻塞信息，不得静默替代关键需求
• ❌ 禁止用户未感知的默认值注入

核心工作流

阶段 1: 快速解析 → 阶段 2: 可视化确认 → 阶段 3: 可选补充 → 输出文件

当用户的首次输入已包含全部必须信息（算子名称、公式/算法、输入输出规格），可将阶段 1 和阶段 2 合并为一步：直接展示数据流图 + 规格确认清单，等待用户确认后生成文件。不需要机械地走完每个阶段。

阶段 1：快速解析

接收用户输入

用户可以用任意方式描述算子需求。接收后立即进行输入分类。

输入分类

先判断输入属于以下 4 类中的哪一类：

1. 标准参考类

   • 适用：常见算子、框架 API 参考、可搜索到标准定义的算子
   • 识别特征：用户直接给出算子名，或明确说“参考 PyTorch/NumPy/TensorFlow/JAX 的 ...”

2. 外部材料类

   • 适用：论文/文档链接、代码片段参考
   • 识别特征：输入包含 URL、论文链接、文档片段、函数定义、import 语句或明显代码语法

3. 自定义描述类

   • 适用：自定义算子、无标准定义、无法定位可信外部资料的算子
   • 识别特征：名称明显是自定义，或搜索无法定位可信定义

4. 直接规格类

   • 适用：用户首次输入已经包含算子名称、公式/算法、输入输出规格等关键信息
   • 识别特征：无需依赖外部资料即可直接进入规格确认

复杂度判定与关键特性识别

完成输入分类后，判断是否属于复杂算子并识别关键特性。

复杂算子判定标准：

• 涉及多步骤、分块、循环、在线更新、状态维护或多个子算子组合
• 标记后追加以下要求：
  • 必须提供算法描述或可恢复算法描述的材料
  • 必须展示分解后的计算图
  • 必须提高确认强度，确保流程理解无歧义

关键特性识别（复杂算子必须执行）： 复杂算子通常包含可独立配置的关键特性，这些特性会显著影响实现复杂度和性能。必须主动识别并拆解，让用户确认。

常见关键特性清单：

特性识别流程：

1. 从用户描述中提取已提及的特性
2. 从参考材料（论文/文档/代码）中识别隐含特性
3. 生成特性清单，标注置信度和来源
4. 在确认环节让用户逐一确认或修改

各类输入的详细处理

类别 1：标准参考类（通常为 ✓ 高置信度）

优先从已有知识或可信参考中恢复标准定义。

已知的常见算子包括：

处理方式：

1. 从自身知识库或可信参考中获取公式和标准规格
2. 标记为 ✓ 高置信度，展示并建议确认
3. 若属于多步骤/复杂算子（如 Flash Attention、Scan），追加算法描述要求

交互示例：

用户: 开发一个 GELU 算子

助手: 我知道 GELU 算子：

      GELU(x) = x * Φ(x)
            ≈ x * 0.5 * (1 + tanh(√(2/π) * (x + 0.044715*x³)))

      标准规格：
      - 输入: x [...], float32
      - 输出: y [...], float32 (shape与输入相同)

      ✓ 算子名称: gelu
      ✓ 公式: GELU(x) = x * Φ(x)
      ⚠ 有两个版本：
         1. 精确版 (使用erf)
         2. 近似版 (使用tanh)
      ❓ 你需要哪个版本？

类别 2：外部材料类（通常为 ⚠ 中置信度）

识别特征：输入包含 URL、论文链接、文档片段、代码片段或函数定义。

处理方式：

1. 若是论文/文档链接，使用 WebFetch 获取内容并提取规格信息
2. 若是代码片段，分析代码结构，提取输入输出与计算逻辑
3. 统一标记为 ⚠ 中置信度
4. 必须让用户确认提取结果是否正确

降级策略（WebFetch 不可用时）：

1. 基于 AI 自身知识库中的标准定义生成规格信息
2. 置信度降为 ⚠ 中（来源：AI 知识库推断，非原始材料）
3. 在 SPEC.md 中标注"⚠ 原始材料无法获取，基于标准参考生成，建议人工确认"
4. 向用户说明降级原因并展示推断依据

交互示例：

用户: 参考 PyTorch 的 F.scaled_dot_product_attention

助手: 我提取到以下规格信息：

      公式: Attention(Q,K,V) = softmax(QK^T/√d) @ V

      标准规格：
      - Q: [batch, num_heads, seq_len, head_dim]
      - K: [batch, num_heads, seq_len, head_dim]
      - V: [batch, num_heads, seq_len, head_dim]
      - Output: [batch, num_heads, seq_len, head_dim]

      可选参数：
      - attn_mask: 注意力掩码
      - dropout_p: dropout 概率
      - is_causal: 是否因果注意力
      - scale: 缩放因子（默认 1/√d）

      ❓ 你需要支持哪些可选参数？
      ❓ 输入的dtype是什么？(float32/bfloat16)

类别 3：自定义描述类（通常为 ❓ 需完整描述）

识别特征：名称明显是自定义（如 my_op, custom_fusion）、无法定位可信标准定义、或用户明确说是自定义。

处理方式：

1. 明确告知这是自定义算子
2. 引导用户提供必须信息（数学公式、输入输出规格）
3. 提供多种输入方式：公式描述、伪代码、NumPy/PyTorch 代码、流程图描述

助手: 我没有找到 "my_fusion_op" 的标准定义，这似乎是一个自定义算子。

      请提供以下信息：

      必须提供：
      1. 数学公式（例如: y = f(x) = ... 或用文字描述计算逻辑）
      2. 输入输出规格（输入: x [shape] dtype / 输出: y [shape] dtype）

      你可以用以下任一方式提供：
      - 公式描述: "y = relu(x) * sigmoid(gate), x和gate都是[b,s,d]的float32"
      - 伪代码: h1 = relu(x); h2 = sigmoid(gate); y = h1 * h2
      - NumPy/PyTorch 代码: def my_op(x, gate): return torch.relu(x) * torch.sigmoid(gate)

类别 4：直接规格类（信息完整度决定置信度）

识别特征：用户首次输入已经包含算子名称、公式/算法、输入输出规格等关键信息。

处理方式：

1. 直接整理已有信息，生成结构化规格草稿
2. 若信息完整且一致，可直接进入可视化确认
3. 若信息存在空缺，仅补问缺失项，不重复追问已有信息

置信度标记规范

阶段 2：可视化确认

这是最关键的一步，确保理解与用户意图对齐。

展示内容

按以下顺序展示：

0. 关键特性拆解（复杂算子专属）

对于复杂算子，在展示数据流图之前，必须先展示识别出的关键特性清单：

🔍 识别到的关键特性:

| 特性 | 是否需要 | 置信度 | 来源 | 实现说明 | 优先级 |
|------|----------|--------|----------|--------|
| causal_mask | ✓ 需要 | ✓ 高 | 用户描述 | 需要上三角 mask 逻辑 | P0 |
| online_softmax | ✓ 需要 | ⚠ 中 | 论文推断 | 需要分块 + 数值稳定更新 | P0 |
| multi_query_attention | ✗ 不需要 | ❓ 低 | 默认假设 | - | - |
| paged_attention | ? 待确认 | ❓ 低 | 网络搜索 | 需要KV cache管理 | P1 |
| dropout | ? 待确认 | ❓ 低 | 框架默认 | 需要随机数生成 | P2 |

❓ 请确认以上特性是否符合你的需求：
  - 需要调整哪些特性的"是否需要"状态？
  - 是否有遗漏的特性？

特性确认交互：

• 使用 AskUserQuestion 让用户确认特性清单
• 提供选项：全部确认 / 修改特性 / 添加新特性 / 我不确定，帮我解释
• 若用户不确定，提供每个特性的简要说明和典型使用场景

1. ASCII 数据流图

根据算子类型选择合适的数据流图模板：

简单 Element-wise 算子（单输入，shape 不变）：

    输入 x                      输出 y
┌────────────────┐         ┌────────────────┐
│  [b, s, n, d]  │ ──────▶ │  [b, s, n, d]  │
│   float32      │  sinh   │   float32      │
└────────────────┘         └────────────────┘

公式: y = sinh(x) = (e^x - e^(-x)) / 2
动态轴: b, s

多输入 Matmul 类算子：

    输入 a           输入 b           输入 c (可选)
┌──────────┐    ┌──────────┐    ┌──────────┐
│  [m, k]  │    │  [n, k]  │    │  [m, n]  │
└────┬─────┘    └────┬─────┘    └────┬─────┘
     │               │               │
     │    ┌──────────┘               │
     ▼    ▼                          │
  ┌────────────┐                     │
  │  a @ b^T   │                     │
  └─────┬──────┘                     │
        │                            │
        ▼                            ▼
     ┌──────────────────────────────────┐
     │              +                   │
     └───────────────┬──────────────────┘
                   ▼
             ┌──────────┐
             │ 输出 y   │
             │  [m, n]  │
             └──────────┘

其他算子：参考上述模板，按实际数据流绘制。组合算子展示子算子的分解与合并关系。

2. 规格确认清单

对于简单算子（公式足以描述）：

✅ 必须信息:
  [✓] 算子名称: {operator_name}
  [✓] 数学公式: {formula}
  [✓] 输入: {input_name}[{shape}] {dtype}, 动态轴: {dynamic_axes}
  [✓] 输出: {output_name}[{shape}] {dtype}, 动态轴: {dynamic_axes}

⚙️ 自动推断（使用默认值，可修改）:
  • 支持数据类型: float32 (atol=0.001, rtol=0.001)
  • 性能目标: 无特殊要求
  • 边界处理: 正常计算

对于复杂算子（公式无法完整表述计算流程），增加算法部分和关键特性部分：

✅ 必须信息:
  [✓] 算子名称: {operator_name}
  [✓] 数学公式: {formula}
  [✓] 关键特性:
      ┌─────────────────────┬────────┬──────────────────────────┐
      │ 特性                │ 状态   │ 实现说明                 │
      ├─────────────────────┼────────┼──────────────────────────┤
      │ causal_mask         │ ✓ 需要 │ 上三角 mask 逻辑         │
      │ online_softmax      │ ✓ 需要 │ 分块 + 数值稳定更新      │
      │ paged_attention     │ ✗ 不需 │ -                        │
      │ dropout             │ ✗ 不需 │ -                        │
      └─────────────────────┴────────┴──────────────────────────┘
  [✓] 算法描述:
      Algorithm: {algorithm_name}
      ────────────────────────────
      {带编号的伪代码步骤}
  [✓] 输入: ...
  [✓] 输出: ...

何时需要算法描述：当计算涉及分块、循环、在线更新、状态维护等流程性逻辑时，公式只能描述数学语义但无法描述实现策略。此时需要算法描述来说明"怎么算"。典型例子：Flash Attention 的分块计算 + Online Softmax、Scan 类算子的递推过程。

算法描述格式：使用带编号的伪代码步骤，清晰展示循环结构、分块策略、状态更新等流程。示例：

Algorithm: Flash Attention (Forward)
────────────────────────────────────
输入: Q, K, V ∈ R^{N×d}, 分块大小 Br, Bc
输出: O ∈ R^{N×d}

1. 将 Q 分为 Tr = ⌈N/Br⌉ 块, K/V 分为 Tc = ⌈N/Bc⌉ 块
2. 初始化 O = 0, l = 0, m = -∞
3. for j = 1 to Tc:                          // 外层循环: K/V 块
     3.1 从 HBM 加载 K_j, V_j 到 SRAM
     3.2 for i = 1 to Tr:                    // 内层循环: Q 块
           3.2.1 从 HBM 加载 Q_i, O_i, l_i, m_i 到 SRAM
           3.2.2 S_ij = Q_i @ K_j^T  ∈ R^{Br×Bc}
           3.2.3 m̃_ij = rowmax(S_ij)
           3.2.4 P̃_ij = exp(S_ij - m̃_ij)
           3.2.5 l̃_ij = rowsum(P̃_ij)
           3.2.6 m_new = max(m_i, m̃_ij)
           3.2.7 l_new = exp(m_i - m_new) * l_i + exp(m̃_ij - m_new) * l̃_ij
           3.2.8 O_i ← diag(l_new)^{-1} * (diag(l_i) * exp(m_i - m_new) * O_i
                        + exp(m̃_ij - m_new) * P̃_ij @ V_j)
           3.2.9 写回 O_i, l_new, m_new 到 HBM
4. return O

3. 操作选项

使用 AskUserQuestion 工具向用户提供以下选择：

• 修改某项 — 修改以上任何信息
• 添加更多细节 — 进入阶段 3
• 确认无误，继续 — 跳过阶段 3 直接生成文件

确认策略

• 高置信度 (✓)：展示但不强制确认，用户可以直接继续
• 中置信度 (⚠)：必须确认 1 次
• 确认次数：最多 2 次（分类确认（仅中置信度时）+ 最终确认）
• 确认方式：整体确认，不逐项确认
• 多步骤/复杂算子：分解展示，整体确认

阶段 3：可选补充

如果用户选择"添加更多细节"，通过 AskUserQuestion 展示以下可选配置项：

1. 动态轴范围 — 动态轴的取值范围（默认: 无限制）

2. 性能目标 — 是否有特殊性能指标要求（默认: 无特殊要求）

3. 边界条件处理 — 零值/极值/NaN/Inf 的处理方式（默认: 正常计算）

4. 参考实现 — PyTorch/NumPy 参考实现链接或代码

5. 应用场景与典型配置 — 目标模型、使用位置、典型配置表格（强烈建议提供）

   典型配置用于后续 golden 验证和设计方案生成，采用 7 列格式：

   配置名称	类型	优先级	参数	输入 Shape	输出 Shape	说明
   性能_P0	性能	P0	{关键参数}	{各输入shape}	{输出shape}	核心性能场景
   功能_P0	功能	P0	{关键参数}	{各输入shape}	{输出shape}	核心功能验证

   引导流程：若用户选择提供应用场景，主动询问是否提供典型配置。若用户不提供典型配置，根据动态轴范围推荐默认配置供确认。

用户可以只填写关心的项，其余使用默认值。

输出文件生成

用户确认后，生成 SPEC.md 文件：

SPEC.md 模板

模板文件位于: templates/spec-template.md

使用时需替换以下占位符:

• {operator_name} — 算子名称
• {category} — 算子分类 (element-wise / reduction / matmul / attention / custom)
• {formula} — 数学公式
• {description} — 功能描述
• front matter 结构化字段：
  • {axes_list} / {axes_ranges} / {shape_constraints}
  • {performance_target}
  • {atol} / {rtol}
  • 约定：axes_list 必须是 YAML 可解析列表（例如 ['N'] 或 ['N','M']）
• {feature_name}, {need_or_not}, {confidence}, {impl_note}, {priority} — 关键特性表格行（复杂算子必须）
• {algorithm_name} / {带编号的伪代码步骤} — 算法描述（可选，复杂算子需要）
• {ASCII数据流图} — 数据流图
• {name}, {shape}, {dtype}, {dynamic_axes}, {description} — 输入输出规格
• {atol}, {rtol} — 精度要求
• {axes_list}, {axes_meanings}, {axes_ranges} — 动态轴说明
• {zero_handling}, {inf_handling}, {nan_handling} — 边界条件处理
• {performance_target} — 性能目标
• {reference_impl}, {paper}, {similar_ops} — 参考信息
• {model}, {layer} — 应用场景
• {config_name}, {type}, {priority}, {params}, {input_shapes}, {output_shapes}, {config_desc} — 典型配置表格行
• {timestamp} — 生成时间

文件冲突处理

如果目标路径下 SPEC.md 已存在，必须通过 AskUserQuestion 询问用户：

⚠ 文件已存在:
  - SPEC.md 路径

请选择:
  1. 覆盖 — 用新生成的内容替换已有文件
  2. 取消 — 不生成文件，保留现有内容

字段定义与默认值

必须字段（无默认值，用户必须提供）

条件必须字段（特定场景下必须提供）

公式描述"算什么"，算法描述"怎么算"。大多数需要算法的算子同时也有公式。简单算子（如 y = sinh(x)）只需公式；复杂算子（如 Flash Attention）两者兼有。

建议字段（有默认值）

可选字段（有合理默认值，可完全跳过）

默认值披露规则

当以下信息未提供且允许使用默认值时，必须在确认环节明确展示，不得静默补全：

• dtype 默认值
• atol / rtol 默认值
• 动态轴范围默认值
• 性能目标默认值

展示格式建议：

⚙️ 将使用以下默认值（如不修改，将直接写入 SPEC.md）：
- dtype: float32
- atol/rtol: 0.001 / 0.001
- 动态轴范围: [1, INT32_MAX]
- 性能目标: 首跑精度成功性能的 2 倍

⚠️ 默认值持久化要求：确认环节中展示的所有默认值，必须写入生成的 SPEC.md 中对应字段（如 default_params frontmatter 字段、精度要求 section 等），不得仅展示而不持久化。

可选参数深度分析

当算子涉及可选参数时（如框架 API 参考场景），需从以下四个维度进行深度分析：

分析方法：

1. 定位代码位置：在参考实现中搜索参数名，找到使用位置
2. 理解计算逻辑：分析参数如何影响计算流程
3. 评估实现复杂度：判断 PyPTO API 是否支持，实现难度如何
4. 确定依赖关系：分析参数间的约束和互斥关系

功能优先级体系

根据功能的重要性确定实现优先级：

重要原则：

• P0 和 P1 功能必须在第一个版本实现
• 只有 P2/P3 功能可以延后
• 在规格确认清单中标注各功能的优先级

示例：

✅ 必须信息:
  [✓] 算子名称: scaled_dot_product_attention
  [✓] 数学公式: Attention(Q,K,V) = softmax(QK^T/√d) @ V
  [✓] 输入: Q, K, V [b, h, s, d] float32 (P0)
  [✓] 可选参数:
      - attn_mask: 注意力掩码 (P2)
      - dropout_p: dropout 概率 (P3)
      - is_causal: 因果注意力 (P1)
      - scale: 缩放因子 (P1)

需求理解 Checklist

• 当前需求信息完整度已评估（高 / 中 / 低）
• 默认值使用情况已显式展示
• 算子名称已确认，符合命名规范（见"字段定义"§算子名称）
• 数学公式已确认，清晰描述核心计算逻辑
• 复杂算子已识别关键特性并让用户确认（见"复杂度判定与关键特性识别"）
• 复杂算子已提供算法描述（见"阶段 2"§何时需要算法描述）
• 所有关键特性已标注实现状态（✓ 需要 / ✗ 不需要 / ? 待确认）和优先级
• 所有信息已标注置信度（✓ 高 / ⚠ 中 / ❓ 低）
• 输入输出 shape、dtype、动态轴已明确
• 可选参数已列出并标注优先级（P0-P3），P0/P1 已完成四维度分析
• P0 和 P1 功能无遗漏（见"功能优先级体系"）
• 精度要求、边界条件、动态轴范围已明确或使用默认值
• 性能目标、参考实现、应用场景、典型配置已询问
• 中置信度信息已确认 1 次，确认次数未超过 2 次