CANN算子规范生成器使用场景

应用场景

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills

本文描述从 REQUIREMENTS.md 出发的完整操作步骤， 包括 spec 生成（场景二）和 spec 独立评审（场景五）。

场景二：从 REQUIREMENTS.md 生成 spec.yaml

强制规则

执行步骤

Step 1: 读取 REQUIREMENTS.md，提取以下字段映射到 spec.yaml：

attribute / axis_source 选择规则：

查看 REQUIREMENTS.md 中的算子接口描述（可能以 REG_OP 宏、ACLNN API 参数表、GE IR 表格或自然语言描述等形式出现），判断归约轴是如何指定的：

注意：当 REQUIREMENTS.md 的算子接口描述中无归约轴相关参数时，必须根据算子语义选择fixed或implicit_all，不能使用默认的attribute（否则会注入不存在的dim/keep_dimsattribute）。

paradigm_groups 选择规则：

当算子有多个范式且不同属性值触发不同计算模式时，需要声明范式间组合方式：

关键判断：检查 REQUIREMENTS.md 中是否存在"模式切换"属性——某个属性值使算子退化为完全不同的计算模式（如reduction=none使 Reduce 算子退化为逐元素、training=False跳过 dropout）。若存在，必须选combination并在 spec 中补 Elementwise 范式。

Step 2: 调用生成器（非交互式，CI 友好）：

python3 ops/ops-spec-gen/scripts/generate_spec.py \ --op-name {operator_name} \ --category {category} \ --paradigms {Paradigm1},{Paradigm2},... \ --paradigm-groups {combination|fusion} \ --inputs "{name1}:{dtype1},{dtype2};{name2}:{dtype1},..." \ --outputs {name} \ --axis-source {attribute|input_tensor|fixed|implicit_all} \ --description "{REQUIREMENTS 中的一句描述}" \ --output-dir operators/{operator_name}/docs

--paradigm-groups仅当有 ≥ 2 个范式且存在模式切换时使用。combination模式下 Elementwise 不会被自动过滤。生成后需手填每组switch（属性名）和when（属性值）。

--axis-source仅对 Reduction 类算子有效。默认值为attribute，需根据上方规则表对照 REQUIREMENTS.md 算子原型选择正确值。

注：交互式向导用法见 SKILL.md §3.1。

Step 3: 手填 TODO 字段（生成器只给骨架，详见 SKILL.md §3.4）：

• math_semantics.formula— numpy 可 eval 的表达式
• math_semantics.reference_oracle— 单 callable api，或填 absent=true + governance 签字
• dtype_policy.supported_combinations— 显式枚举 (input dtypes) → output dtypes
• numerical_tolerance.per_dtype— 覆盖输出 dtype（默认值见registries/tolerance_defaults.yaml）
• op.platform_constraints.supported_chips— 来自 REQUIREMENTS §2，与registries/chip_registry.yaml对齐
• op.paradigm_groups[].switch/when— 当使用--paradigm-groups combination时，需手填每组的switch（属性名）和when（属性值），将属性值映射到对应的范式子集
• v1 暂缓：interface_binding/performance_budget/performance_baseline尚未纳入 schema（顶层additionalProperties: false），不要写入；待 schema 扩展后启用

Step 4: 跑 9-stage 校验：

python3 ops/ops-spec-gen/scripts/validate_spec.py operators/{operator_name}/docs/spec.yaml

预期 stage 1-8 全 PASS。stage 9 在测试机未装 torch 时走 SKIP（不算失败）。任一 FAIL 必须修复后重跑，禁止跳过。校验详情见 SKILL.md §4。

Step 5: 锁 spec_hash（建议）：compute_spec_hash.py工具链 v1 未交付；不要求执行，待工具就绪后再纳入流程。

完成标志

• spec.yaml 已生成并通过 9-stage 校验
• 字段与 REQUIREMENTS.md 内容一致（dtype / shape / 平台 / 容差均可追溯到需求）

场景五：spec 独立评审（14 条 SPEC-* 条款评审）

在 CP1.5 用户人工 review 前，先做 14 条 SPEC-* 条款级评审——逐项对照 spec ↔ REQUIREMENTS 中机器可判的项。把明显错误（dtype 漏一个、芯片不匹配、attribute 凭空注入、错误码缺漏、性能字段没填） 先拦下，避免拿一份"机器自洽但语义错"的 spec 去骚扰用户。

前置条件

• 已存在operators/{operator_name}/docs/spec.yaml（9-stage 全 PASS）
• 已存在operators/{operator_name}/docs/REQUIREMENTS.md

14 条 SPEC-* 条款

执行步骤

1. 逐条对照 spec ↔ REQUIREMENTS：按 14 条条款表逐项评审，每条输出 ✓/⚠/❌ + 证据（spec 字段值与 REQUIREMENTS 来源的对照）
2. 生成必看清单：列出 agent 独立评审无法判但必须由人 review 的项（见下文）
3. 状态判定：任一 ❌ → 状态=❌失败；全 ✓ 或 ⚠ → 状态=✅通过（⚠ 提示用户但不阻塞）
4. 输出 SPEC_REVIEW.md：按下文报告格式模板输出

注意：本场景只读、只评审、只输出报告；不得修改 spec.yaml。修复由场景二（spec-generation）执行。

必看清单（用户对照摘要必含）

agent 独立评审无法判但必须由人 review 的项：

强制规则：以下每一项必须出现在评审报告的"必看清单"中。即使判断为 ✓ 也必须输出并附简要证据，不允许省略。

报告格式（精确模板，供主 Agent 机读判定）

**状态**: ✅通过 / ❌失败 **spec.yaml 路径**: operators/{op}/docs/spec.yaml **REQUIREMENTS.md 路径**: operators/{op}/docs/REQUIREMENTS.md ## 14 条 SPEC-* 条款评审 | 条款 ID | 状态 | spec 字段值 | REQUIREMENTS 来源 | 证据 / 备注 | |---------|------|-------------|------------------|------------| | SPEC-CHIP-1 | ✓ | [Ascend910B, Ascend910D] | §2 Atlas A2/A3 训练系列 | 字段值与需求对齐 | | SPEC-DAV-1 | ⚠ | v1 暂缓 | §2 编译宏 | DAV 宏尚未纳入 spec schema，由 REQUIREMENTS / DESIGN 承载 | | SPEC-DTYPE-1 | ⚠ | {fp16, bf16} | §4 fp16/bf16/fp32 | spec 漏 fp32；用户确认是否真要去掉 fp32？ | | ... | ... | ... | ... | ... | ## 必看清单（CP1.5 人工 review 用） ⚠ **公式数学意图**：spec.formula="y = np.exp(x) / np.exp(x).sum(axis=dim)" ⚠ 注意：未做 max-shift 数值稳定。REQUIREMENTS §4 公式同未提；但 NumericalStable 范式已声明。 → 人工确认：是否真不做 max-shift？ ⚠ **tolerance 数值合理性**：fp16 用 1.0e-3，bf16 用 4.0e-3 → 来自 ops-precision-standard 默认；是否需要按业务收紧？ ✓ **boundary case 业务覆盖**：含 reduce 轴=1 / rank=0 / 空 Tensor / fp16 上溢边界 共 4 条 → 自动覆盖 Reduction + NumericalStable 范式必含 case；业务关键路径请人工确认 ⚠ **范式选择正确性**：spec.paradigms=[Reduction, FusedComposite] → 人工确认：是否存在某些属性值使算子退化为完全独立的计算模式（如 reduction=none→逐元素）？ 若是，需要添加 Elementwise 范式并声明 paradigm_groups combination。 ⚠ **范式组合方式**：spec.paradigm_groups 未声明 → 人工确认：多个范式之间是横向组合（按属性值择一）还是纵向融合（串联执行）？ 若存在模式切换属性，需声明 paradigm_groups。 ## 问题清单（仅状态=❌时必填） | 条款 | 严重度 | 问题描述 | 修复建议 | |------|--------|---------|---------| | ... | HIGH/MED/LOW | ... | ... |

主 Agent 处理规则（供调用方参考）

• 状态=✅ → 进入 CP1.5 人工确认
• 状态=❌ → 主 Agent 自动调 (scene: spec-generation) 按 SPEC_REVIEW 修订 spec.yaml，修订后重跑 9-stage + 重跑本场景；最多重试 2 次
• 禁止把 ❌ 报告直接抛给用户

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills