| name | external-cannbot-ops-pypto-intent-understand |
| description | PyPTO 算子需求意图理解。将用户的自然语言算子描述转化为结构化需求文档。当用户描述要开发、实现、创建某个算子时触发，例如：'开发一个 sinh 算子'、'实现 GELU'、'参考 PyTorch 的 F.scaled_dot_product_attention'、'根据论文实现算子'、'创建自定义算子' |
| original-name | pypto-intent-understand |
| synced-from | https://gitcode.com/cann/cannbot-skills |
| synced-date | 2026-05-26 |
| synced-commit | ac5bbd2b4cf427d011874e11f8d1e8b1bef66eda |
| license | UNKNOWN |
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 类中的哪一类：
-
标准参考类
- 适用：常见算子、框架 API 参考、可搜索到标准定义的算子
- 识别特征：用户直接给出算子名，或明确说“参考 PyTorch/NumPy/TensorFlow/JAX 的 ...”
-
外部材料类
- 适用：论文/文档链接、代码片段参考
- 识别特征：输入包含 URL、论文链接、文档片段、函数定义、import 语句或明显代码语法
-
自定义描述类
- 适用：自定义算子、无标准定义、无法定位可信外部资料的算子
- 识别特征：名称明显是自定义，或搜索无法定位可信定义
-
直接规格类
- 适用：用户首次输入已经包含算子名称、公式/算法、输入输出规格等关键信息
- 识别特征：无需依赖外部资料即可直接进入规格确认
复杂度判定与关键特性识别
完成输入分类后，判断是否属于复杂算子并识别关键特性。
复杂算子判定标准：
- 涉及多步骤、分块、循环、在线更新、状态维护或多个子算子组合
- 标记后追加以下要求：
- 必须提供算法描述或可恢复算法描述的材料
- 必须展示分解后的计算图
- 必须提高确认强度，确保流程理解无歧义
关键特性识别（复杂算子必须执行）：
复杂算子通常包含可独立配置的关键特性，这些特性会显著影响实现复杂度和性能。必须主动识别并拆解，让用户确认。
常见关键特性清单：
| 特性类别 | 典型特性 | 适用算子类型 | 影响范围 |
|---|
| 数值稳定性 | safe_softmax, logsumexp, numerical_stable | Softmax/归一化/指数运算 | 计算精度、溢出处理 |
| 分块策略 | tiling_strategy, block_size | 大规模矩阵/注意力/卷积 | 内存布局、循环结构 |
| Mask 机制 | causal_mask, padding_mask, custom_mask, sliding_window | 注意力/序列处理 | 数据流、内存访问、边界处理 |
| 在线算法 | online_softmax, online_reduction, streaming_update | Reduction/Softmax | 计算顺序、中间状态 |
| 量化支持 | int8_quant, fp8_quant, blockwise_quant, dequantize | 量化算子 | 数据类型、缩放因子 |
| 融合模式 | bias_add, residual_add, activation_fused | 通用 | 算子边界、中间结果复用 |
| 动态 Shape | variable_length, ragged_tensor, dynamic_axis | 序列处理/变长输入 | 内存分配、循环展开 |
| 并行策略 | split_k, split_n, parallel_reduction | 矩阵乘法/Reduction | 并行度、同步开销 |
| 内存优化 | in_place, workspace_reuse, page_attention | 通用 | 内存占用、数据依赖、内存优化 |
| 边界处理 | padding_mode, boundary_condition, edge_handling | 卷积/池化/插值 | 边界精度、计算逻辑 |
| 精度控制 | mixed_precision, accumulator_dtype, rounding_mode | 通用 | 计算精度、数值范围 |
| 随机性 | deterministic, seed_control, dropout_rate | Dropout/随机采样 | 可复现性、随机数生成 |
| 稀疏性 | sparse_pattern, masked_compute, structured_sparsity | 稀疏算子 | 数据布局、计算跳过 |
特性识别流程：
- 从用户描述中提取已提及的特性
- 从参考材料（论文/文档/代码）中识别隐含特性
- 生成特性清单，标注置信度和来源
- 在确认环节让用户逐一确认或修改
各类输入的详细处理
类别 1：标准参考类（通常为 ✓ 高置信度）
优先从已有知识或可信参考中恢复标准定义。
已知的常见算子包括：
| 类别 | 算子列表 |
|---|
| 激活函数 | relu, gelu, silu, swish, mish, sigmoid, tanh, softmax, hardswish, hardsigmoid |
| 数学运算 | sin, cos, sinh, cosh, tanh, exp, log, log2, log10, sqrt, rsqrt, pow, abs, sign |
| 归一化 | layer_norm, rms_norm, batch_norm, instance_norm, group_norm |
| 注意力 | scaled_dot_product_attention, multi_head_attention |
| 矩阵运算 | matmul, addmm, bmm, linear, einsum |
| Reduction | sum, mean, max, min, amax, amin, argmax, argmin, prod |
| 逐元素 | add, sub, mul, div, maximum, minimum, clamp |
处理方式：
- 从自身知识库或可信参考中获取公式和标准规格
- 标记为 ✓ 高置信度，展示并建议确认
- 若属于多步骤/复杂算子（如 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、论文链接、文档片段、代码片段或函数定义。
处理方式：
- 若是论文/文档链接，使用 WebFetch 获取内容并提取规格信息
- 若是代码片段，分析代码结构，提取输入输出与计算逻辑
- 统一标记为 ⚠ 中置信度
- 必须让用户确认提取结果是否正确
降级策略（WebFetch 不可用时）：
- 基于 AI 自身知识库中的标准定义生成规格信息
- 置信度降为 ⚠ 中（来源：AI 知识库推断，非原始材料）
- 在 SPEC.md 中标注"⚠ 原始材料无法获取，基于标准参考生成，建议人工确认"
- 向用户说明降级原因并展示推断依据
交互示例：
用户: 参考 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）、无法定位可信标准定义、或用户明确说是自定义。
处理方式：
- 明确告知这是自定义算子
- 引导用户提供必须信息（数学公式、输入输出规格）
- 提供多种输入方式：公式描述、伪代码、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：直接规格类（信息完整度决定置信度）
识别特征：用户首次输入已经包含算子名称、公式/算法、输入输出规格等关键信息。
处理方式：
- 直接整理已有信息，生成结构化规格草稿
- 若信息完整且一致，可直接进入可视化确认
- 若信息存在空缺，仅补问缺失项，不重复追问已有信息
置信度标记规范
| 标记 | 置信度 | 信息来源 | 处理方式 |
|---|
| ✓ | 高 | 自身知识库/框架知识 | 展示并建议确认 |
| ⚠ | 中 | WebSearch/WebFetch/代码分析 | 必须让用户确认 |
| ❓ | 低 | 推断/猜测 | 主动询问用户 |
阶段 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 展示以下可选配置项：
-
动态轴范围 — 动态轴的取值范围（默认: 无限制）
-
性能目标 — 是否有特殊性能指标要求（默认: 无特殊要求）
-
边界条件处理 — 零值/极值/NaN/Inf 的处理方式（默认: 正常计算）
-
参考实现 — PyTorch/NumPy 参考实现链接或代码
-
应用场景与典型配置 — 目标模型、使用位置、典型配置表格（强烈建议提供）
典型配置用于后续 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. 取消 — 不生成文件，保留现有内容
字段定义与默认值
必须字段（无默认值，用户必须提供）
| 字段 | 类型 | 说明 |
|---|
| 算子名称 | string | 唯一标识符，小写字母开头，只能包含小写字母、数字和下划线 |
| 数学公式 | string | 核心计算逻辑，所有算子都需要 |
条件必须字段（特定场景下必须提供）
| 字段 | 类型 | 何时必须 |
|---|
| 算法描述 | string | 当公式无法完整表述计算流程时（涉及分块、循环、在线更新、状态维护等流程性逻辑） |
公式描述"算什么"，算法描述"怎么算"。大多数需要算法的算子同时也有公式。简单算子（如 y = sinh(x)）只需公式；复杂算子（如 Flash Attention）两者兼有。
建议字段（有默认值）
| 字段 | 默认值 | 说明 |
|---|
| 输入 shape | 构建典型值 | 输入张量形状 |
| 输入 dtype | float32 | 输入数据类型 |
| 输出 shape | 根据输入推导 | 输出张量形状 |
| 输出 dtype | 与输入相同 | 输出数据类型 |
| 动态轴 | batch、seq | 支持动态 shape |
| 性能目标 | 首跑精度成功性能的 2 倍 | 性能优化指导 |
| 精度要求 | atol=0.001, rtol=0.001 | 默认精度标准 |
可选字段（有合理默认值，可完全跳过）
| 字段 | 默认值 | 用途 |
|---|
| 可选参数 | 自动推导 | 功能完整 |
| 动态轴范围 | [1, INT32_MAX] | 性能优化 |
| 边界条件处理 | 正常计算 (zero/inf/nan 均为 normal) | 特殊值处理 |
| 参考实现 | 无 | 框架/论文/代码参考 |
| 应用场景 | 建议提供典型配置（7 列表格） | 模型/层/典型配置表格，便于后续 golden 生成和设计方案 |
默认值披露规则
当以下信息未提供且允许使用默认值时，必须在确认环节明确展示，不得静默补全：
- dtype 默认值
- atol / rtol 默认值
- 动态轴范围默认值
- 性能目标默认值
展示格式建议：
⚙️ 将使用以下默认值（如不修改，将直接写入 SPEC.md）：
- dtype: float32
- atol/rtol: 0.001 / 0.001
- 动态轴范围: [1, INT32_MAX]
- 性能目标: 首跑精度成功性能的 2 倍
⚠️ 默认值持久化要求：确认环节中展示的所有默认值，必须写入生成的 SPEC.md 中对应字段（如 default_params frontmatter 字段、精度要求 section 等），不得仅展示而不持久化。
可选参数深度分析
当算子涉及可选参数时（如框架 API 参考场景），需从以下四个维度进行深度分析：
| 维度 | 说明 | 示例 |
|---|
| 代码位置 | 参数在计算流程的哪个阶段使用 | 输入预处理/核心计算/输出后处理 |
| 计算逻辑 | 参数如何影响计算 | 条件分支/数值缩放/数据选择 |
| 实现复杂度 | PyPTO 是否支持 | 低(直接支持)/中(需要特殊处理)/高(不支持) |
| 依赖关系 | 是否依赖其他参数 | 独立/依赖参数X/与参数Y互斥 |
分析方法：
- 定位代码位置：在参考实现中搜索参数名，找到使用位置
- 理解计算逻辑：分析参数如何影响计算流程
- 评估实现复杂度：判断 PyPTO API 是否支持，实现难度如何
- 确定依赖关系：分析参数间的约束和互斥关系
功能优先级体系
根据功能的重要性确定实现优先级：
| 优先级 | 定义 | 说明 |
|---|
| P0（必须） | 核心功能 | 没有就无法工作，所有场景都需要 |
| P1（重要） | 常用功能 | 影响大多数使用场景，必须在第一个版本实现 |
| P2（可选） | 特殊场景功能 | 根据需求决定是否实现 |
| P3（暂缓） | 不支持或成本过高 | PyPTO 不支持或实现成本过高，暂不实现 |
重要原则：
- 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
