@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ops-spec-gen/references/usage-scenarios.md

@@ -0,0 +1,265 @@
+# 应用场景
+
+> 本文描述从 REQUIREMENTS.md 出发的完整操作步骤，
+> 包括 spec 生成（场景二）和 spec 独立评审（场景五）。
+
+---
+
+## 场景二：从 REQUIREMENTS.md 生成 spec.yaml
+
+### 强制规则
+
+| ID | 规则 |
+|----|------|
+| S1 | 必须使用 `scripts/generate_spec.py` 生成骨架，**禁止手写 spec.yaml** |
+| S2 | 生成完成后必须跑 `scripts/validate_spec.py spec.yaml` 12-stage 校验全 PASS（stage 9/10/11/12 SKIP 视为通过） |
+| S3 | （建议）`scripts/compute_spec_hash.py` 工具链尚未交付，v1 不要求锁 spec_hash；待工具与 schema 字段就绪后启用 |
+| S4 | 字段值必须**与 REQUIREMENTS.md 一致**——dtype / shape 约束 / 平台限制 / 容差由 REQUIREMENTS 推导，不允许凭空添加 |
+| S5 | numerical_stability.techniques.anti_pattern_id 引用必须在 `registries/anti_pattern_registry.yaml` 中已注册（如未来 schema 加 enum） |
+| S6 | **必须填 `op.platform_constraints.supported_chips`**（来自 REQUIREMENTS §2 运行环境；与 chip_registry.yaml 对齐） |
+| S7 | （建议）`interface_binding.arg_order` / `aclnn` / `ge_ir` 字段尚未纳入 `schemas/op-spec.json`（顶层 `additionalProperties: false`），v1 不填；待 schema 扩展后启用 |
+| S8 | （建议）`performance_budget` 同上，schema 未定义，v1 不填 |
+| S9 | （建议）`performance_baseline` 同上，schema 未定义，v1 不填 |
+
+### 执行步骤
+
+**Step 1: 读取 REQUIREMENTS.md**，提取以下字段映射到 spec.yaml：
+
+| REQUIREMENTS.md 字段 | spec.yaml 字段 |
+|---|---|
+| 算子类别 | `op.category` |
+| 算子范式（多选） | `op.paradigms` |
+| **范式间组合方式**（横向组合 / 纵向融合） | **`op.paradigm_groups`** + `--paradigm-groups` 参数（见下方说明） |
+| **算子接口描述中的非张量参数声明** | **`attributes[]` + `--axis-source` 参数**（见下方说明） |
+| **数据排布格式支持**（NCHW/NHWC/NCDHW 等） | **`math_semantics.format_variants[]`** + `--format-variants` 参数 |
+| 输入张量列表 + dtype | `inputs[].name / dtype_set / shape.symbolic` |
+| 输出张量 + dtype 推导规则 | `outputs[].dtype_rule / shape_rule` |
+| 数学公式 | `math_semantics.formula` |
+| 参考实现 / oracle | `math_semantics.reference_oracle` |
+| 数值稳定性技术 | `numerical_stability.techniques` |
+| 精度容差 | `numerical_tolerance.per_dtype` |
+| 边界 case | `boundary_conditions[]` / `extreme_inputs[]` |
+| **§2 运行环境（芯片号）** | **`op.platform_constraints.supported_chips`** |
+| **§2 运行环境（DAV 宏 / CANN 版本）** | `REQUIREMENTS.md` 继续承载；schema 未定义时不要写入 spec |
+| **§5 ACLNN API 接口（参数列表 / 顺序）** | _v1 暂缓_：`interface_binding.*` 尚未纳入 schema |
+| **§6 GE IR 定义（IR 算子名 / 动态 shape）** | _v1 暂缓_：`interface_binding.ge_ir.*` 尚未纳入 schema |
+| **§8 资源约束（workspace 上限 / 对齐）** | _v1 暂缓_：`performance_budget` 尚未纳入 schema |
+| **§7 性能指标（利用率 / 带宽 / 延迟）** | _v1 暂缓_：`performance_baseline` 尚未纳入 schema |
+
+**attribute / axis_source 选择规则**：
+
+查看 REQUIREMENTS.md 中的算子接口描述（可能以 REG_OP 宏、ACLNN API 参数表、GE IR 表格或自然语言描述等形式出现），判断归约轴是如何指定的：
+
+| 接口特征 | `--axis-source` 值 | 说明 |
+|---|---|---|
+| 归约轴作为非张量参数声明（如 REG_OP 的 `.ATTR(dim, ...)`、ACLNN 参数表中的 int64/list 类型参数、GE IR 表格的 ATTR 行） | `attribute`（默认） | 归约轴作为 attribute 传入 |
+| 归约轴作为整型 tensor 输入声明（如 REG_OP 的 `.INPUT(axes, ...)`、ACLNN 参数表中的 aclTensor 类型参数） | `input_tensor` | 归约轴作为 tensor input |
+| 无归约轴参数，归约轴固定（如 reduce 特定维度） | `fixed` | 归约轴硬编码在算子内部 |
+| 无归约轴参数，reduce 所有轴（输出为标量） | `implicit_all` | 隐式归约所有轴，无需显式指定 |
+
+> **注意**：当 REQUIREMENTS.md 的算子接口描述中无归约轴相关参数时，必须根据算子语义选择 `fixed` 或 `implicit_all`，不能使用默认的 `attribute`（否则会注入不存在的 `dim`/`keep_dims` attribute）。
+
+**paradigm_groups 选择规则**：
+
+当算子有多个范式且不同属性值触发不同计算模式时，需要声明范式间组合方式：
+
+| 判断条件 | `--paradigm-groups` 值 | 说明 |
+|---|---|---|
+| 属性值切换导致计算模式根本性变化（如 reduction=none→逐元素 vs reduction=sum/mean→归约；mode=training vs mode=inference） | `combination` | 横向组合：多范式择一，由属性值决定激活哪个。每个 paradigm 独立一条 combination 组 |
+| 多范式串联执行（如先 Elementwise 再 Reduction 再 Elementwise，所有范式始终参与） | `fusion` | 纵向融合：所有范式按序执行 |
+| 仅 1 个范式，或所有属性值走同一范式 | 不传（默认） | 无需声明组合关系 |
+
+> **关键判断**：检查 REQUIREMENTS.md 中是否存在"模式切换"属性——某个属性值使算子退化为完全不同的计算模式（如 `reduction=none` 使 Reduce 算子退化为逐元素、`training=False` 跳过 dropout）。若存在，必须选 `combination` 并在 spec 中补 Elementwise 范式。
+
+**Step 2: 调用生成器**（非交互式，CI 友好）：
+
+```bash
+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 可求值的表达式
+- `math_semantics.reference_oracle` — 单 callable api，或填 absent=true + governance 签字
+- `math_semantics.invariants` — **≥1 条值级、formula 无关**的语义不变量（保范/单位元/对称/代数恒等/极限退化，源自 REQUIREMENTS 数学；**非** shape 结构断言、**非** formula 自反重述）。**SPEC-ORACLE-1 硬性要求**，`reference_oracle.absent=true` 时强制
+- `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: 跑 11-stage 校验**：
+
+```bash
+python3 ops/ops-spec-gen/scripts/validate_spec.py operators/{operator_name}/docs/spec.yaml
+```
+
+预期 stage 1-8 全 PASS。stage 9 在测试机未装 torch 时走 SKIP（不算失败）。stage 10 在 oracle 可达时比对 formula 与 oracle 的特殊值输出，SKIP 亦不算失败。任一 FAIL 必须修复后重跑，**禁止跳过**。校验详情见 SKILL.md §4。
+
+**Step 5: 锁 spec_hash**（建议）：`compute_spec_hash.py` 工具链 v1 未交付；不要求执行，待工具就绪后再纳入流程。
+
+### 特殊算子类：属性决定多输出（split / chunk / unbind）
+
+当算子**输出个数与 shape 由属性决定**（如 split 的 `split_size` 决定切几段、每段多大），区别于 nonzero/where 这类**输出个数由输入数据决定**的算子。这类算子用：
+
+```yaml
+op:
+  category: VariableOutput
+  paradigms: [VariableOutput]
+  output_count_determined_by: attribute   # 关键：声明输出个数由属性决定
+outputs:
+  - name: y0
+    shape_rule_kind: numpy_expr           # 输出 shape 由属性可静态推导
+    shape_rule: |
+      y0.shape = list(x.shape); y0.shape[dim] = split_size[0]
+```
+
+- `output_count_determined_by: attribute` 会**豁免** `data_dependent_shape: true` 强制要求，以及 VariableOutput 默认必含的 nonzero 类 boundary case（empty_output / full_output / normal_sparse）——这些是为"数据决定输出个数"设计的，不适用于属性决定。
+- **list 属性**（如 `split_size: list[int64]`）在 `boundary_conditions` / `extreme_inputs` 的 synthesize 里书写时，加引号或不加均可：`attr.split_size: "[2,2]"` 或 `attr.split_size: [2,2]`（框架会按字面量解析注入 formula/shape_rule 沙箱，仅采纳 list/tuple，不会误转字符串属性）。
+- 完整范例见 `examples/split/spec.yaml`。
+
+### 完成标志
+
+- spec.yaml 已生成并通过 11-stage 校验
+- 字段与 REQUIREMENTS.md 内容一致（dtype / shape / 平台 / 容差均可追溯到需求）
+
+---
+
+## 场景五：spec 独立评审（17 条 SPEC-\* 条款评审）
+
+> 在 CP1.5 用户人工 review 前，先做 17 条 SPEC-\* 条款级评审——逐项对照 spec ↔ REQUIREMENTS
+> 中**机器可判**的项。把明显错误（dtype 漏一个、芯片不匹配、attribute 凭空注入、错误码缺漏、性能字段没填、
+> 公式形式与 oracle 不一致）先拦下，避免拿一份"机器自洽但语义错"的 spec 去骚扰用户。
+
+### 前置条件
+
+- 已存在 `operators/{operator_name}/docs/spec.yaml`（11-stage 全 PASS）
+- 已存在 `operators/{operator_name}/docs/REQUIREMENTS.md`
+
+### 17 条 SPEC-\* 条款
+
+| 条款 ID | 检查项 | 数据来源对照 |
+|---|---|---|
+| **SPEC-CHIP-1** | spec.op.platform_constraints.supported_chips ⊆ REQUIREMENTS §2 目标芯片 | 字符串集合包含关系 |
+| **SPEC-DAV-1** | _v1 暂缓_ — DAV 宏由 REQUIREMENTS / DESIGN 承载，`dav_macros` 尚未纳入 schema | — |
+| **SPEC-DTYPE-1** | spec.dtype_policy.supported_combinations 输入 dtype 集 = REQUIREMENTS §4 支持类型集 | 集合相等 |
+| **SPEC-DTYPE-2** | spec.inputs[].dtype_set 覆盖 REQUIREMENTS §4 数据类型 | 集合包含 |
+| **SPEC-IO-1** | spec.inputs/outputs 数量 + name 与 REQUIREMENTS §5 ACLNN 参数列表对齐 | 长度 + 名字集合 |
+| **SPEC-ATTR-1** | spec.attributes[].name 集合 ⊆ REQUIREMENTS 算子接口描述中声明的非张量参数集合（接口描述中无归约轴等 attribute 类参数时 spec.attributes 应为空） | 集合包含 |
+| **SPEC-ARG-1** | _v1 暂缓_ — `interface_binding.arg_order` 尚未纳入 schema，待扩展后启用 | — |
+| **SPEC-ERROR-1** | spec.op.error_codes ⊇ REQUIREMENTS §8 错误码集合 | 集合包含 |
+| **SPEC-PERF-1** | _v1 暂缓_ — `performance_baseline` 尚未纳入 schema，待扩展后启用 | — |
+| **SPEC-RES-1** | _v1 暂缓_ — `performance_budget` 尚未纳入 schema，待扩展后启用 | — |
+| **SPEC-FORMULA-1** | spec.math_semantics.formula 至少引用所有 input name | 字符串包含 |
+| **SPEC-FORMULA-2**（硬拦） | spec.math_semantics.formula 与 reference_oracle 在含特殊值（NaN/inf/大数/带符号零）输入上产出**一致的 NaN/inf/零符号模式**且有限值在容差内。stage 10 校验 PASS 或 SKIP 视为通过；stage 10 FAIL → ❌（详见下方判定细则） | stage 10 机器校验 |
+| **SPEC-LAYOUT-1** | canonical 通道轴/规约轴须：① 显式（`formula` 可判）② 各 boundary/extreme 用例 `(C,) len == x.shape[该轴]` 自洽 ③ 等于 REQUIREMENTS 调用框架默认 format 通道位（无收窄豁免）。任一不满足 → ❌（详见下方判定细则） | formula 轴位置 + 调用框架默认 format 通道位 + 用例 shape 自洽 |
+| **SPEC-ORACLE-1** | `math_semantics.invariants` 须含 ≥1 条**值级、formula 无关**的独立不变量（源自 REQUIREMENTS 数学；非结构断言、非 formula 自反）；`reference_oracle.absent=true` 时**强制**。无独立锚点 → ❌（详见下方判定细则） | reference_oracle 独立性 + invariants 值级且非 formula 自反 |
+| **SPEC-PARADIGM-1** | spec.op.paradigms 与 category 隐含范式 + REQUIREMENTS 暗示的修饰范式对齐 | 集合差 |
+| **SPEC-LIFECYCLE-1** | spec.op.lifecycle 与 REQUIREMENTS 描述匹配（experimental vs stable）| 字符串匹配 |
+| **SPEC-INTERFACE-1** | _v1 暂缓_ — `interface_binding.*` 尚未纳入 schema，待扩展后启用 | — |
+
+> **SPEC-LAYOUT-1 判定细则**（三查均为 ❌ 硬拦；收窄合理性另列必看清单供人复核，但**不改 ❌ 判定**）：
+> - **① 显式（❌ 硬拦）**：formula 无法判出通道轴/规约轴（既没用 `x.shape[k]` 也无 shape_constraints 说明）→ ❌（轴不显式，find-proto 无从写进 proto §4，黑盒只能自行猜轴）。
+> - **② 用例自洽（❌ 硬拦）**：任一 boundary/extreme 用例的 `(C,)` 张量长度 ≠ `x.shape[该轴]` → ❌。
+> - **③ 与「调用框架默认 format」一致（❌ 硬拦，无收窄豁免）**：spec canonical 轴**必须等于** REQUIREMENTS「调用框架/主 format」的通道位（PyTorch=NCHW→轴1、TF=NHWC→轴-1 等）。不等 → **❌**，**即使 spec 声明"由适配层映射"也不豁免**——工作流不产出 transpose/适配层，黑盒直调 aclnn 传入的就是框架 layout 张量，轴不匹配必与 golden/kernel/用例撞轴（bn_training_update：spec 末轴、黑盒 NCHW → 535 全挂）。**唯一豁免**：transpose/适配层是本工作流显式交付物（默认没有）。
+
+> **SPEC-ORACLE-1 判定细则**（golden 与 kernel 同源 spec.formula，共享错误则 matches_oracle 假绿；须挂一个不经过 formula 的独立锚点才测得出公式语义错）：
+> - **① 值级不变量存在（absent=true 时 ❌ 硬拦）**：`invariants` 全是 `shape_equals`/`no_leak` 等结构项、无任何值级语义性质 → ❌。值级性质示例：保范 `‖out‖=‖in‖`（旋转/正交类）、单位元 `f(x, 恒等参数)=x`、对称/反对称、代数恒等（softmax 行和=1、归一化后统计量）、极限退化。
+> - **② 独立性（非 formula 自反）**：值级不变量不得是 formula 的直接重述（把公式抄成断言不算独立）；须能在**不引用 formula** 的前提下由 REQUIREMENTS 数学独立推出。疑似自反 → ⚠ 入必看清单人复核。
+> - **③ absent 不免验证**：`reference_oracle.absent=true` 时①为强制；absent=false 且指向真实独立外部实现时①可放宽为建议（但仍推荐同时有）。
+
+> **SPEC-FORMULA-2 判定细则**（公式形式差异是 spec→design→kernel→黑盒 全链路返工的最大单因——数学等价但计算不等价的公式在 NaN/inf 传播与末位舍入上发散，导致 kernel 与 golden bit 级背离）：
+> - **① stage 10 机器校验**：跑 `validate_spec.py` stage 10（formula_oracle_equiv）。stage 10 在含 NaN/inf/大数/带符号零的输入上同时执行 formula 和 oracle，比对 NaN 模式、inf 模式、零符号模式、有限值容差。PASS 或 SKIP → ✓；FAIL → ❌。
+> - **② SKIP 不等于豁免**：stage 10 在以下情况 SKIP（视为通过，不阻塞）：formula_kind 非 numpy_expr、oracle absent、composition DAG 模式、framework 未安装、oracle 调用失败。SKIP 时应在报告中注明跳过原因，并提示用户在安装对应 framework 后重跑。
+> - **③ 典型陷阱**：教科书合并形式 `m_new = β1·m + (1-β1)·grad` 与 TF 增量形式 `m = m + (1-β1)·(grad-m)` 数学等价但浮点不等价——当 `m=inf` 时前者产出 `inf`，后者产出 `NaN`（`inf - inf = NaN`）。stage 10 的 nan/inf 输入组会捕获此类差异。
+
+### 执行步骤
+
+1. **逐条对照 spec ↔ REQUIREMENTS**：按 17 条条款表逐项评审，每条输出 ✓/⚠/❌ + 证据（spec 字段值与 REQUIREMENTS 来源的对照）
+2. **生成必看清单**：列出 agent 独立评审无法判但必须由人 review 的项（见下文）
+3. **状态判定**：任一 ❌ → 状态=❌失败；全 ✓ 或 ⚠ → 状态=✅通过（⚠ 提示用户但不阻塞）
+4. **输出 SPEC_REVIEW.md**：按下文报告格式模板输出
+
+> **注意**：本场景只读、只评审、只输出报告；不得修改 spec.yaml。修复由场景二（spec-generation）执行。
+
+### 必看清单（用户对照摘要必含）
+
+agent 独立评审无法判但必须由人 review 的项：
+
+> **强制规则**：以下每一项**必须**出现在评审报告的"必看清单"中。即使判断为 ✓ 也必须输出并附简要证据，不允许省略。
+
+| 必看项 | 为什么 agent 判不了 |
+|---|---|
+| 公式数学意图 | "y = (x - mean) / sqrt(var + eps)" 写得对但用户真想要的可能是 RMSNorm 不是 LayerNorm |
+| tolerance 数值合理性 | 1e-3 还是 5e-3？需要算子领域知识 + 上下游精度标准 |
+| boundary case 业务覆盖 | 业务上 K 维 > 4096 是否常见？需领域知识 |
+| composition 拆分合理性 | FusedComposite 算子的 primitives 拆分是否符合预期融合方式 |
+| reference_oracle 选择 | 选 torch.matmul 还是 torch.linalg.matmul？两者数值差异在边界 case 可能很大 |
+| **范式选择正确性** | spec.op.paradigms 列出的范式是否完整覆盖了算子的所有计算路径？典型陷阱：reduction=none 时算子退化为 Elementwise，但 spec 只声明了 Reduction + FusedComposite，漏掉了 Elementwise。agent 只能校验"声明的范式是否与 category 对齐"，无法判断"是否漏了一条独立的计算路径" |
+| **范式组合方式（paradigm_groups）** | 多个范式之间的关系是横向组合（combination，按属性值择一激活）还是纵向融合（fusion，串联执行）？agent 只能做结构校验（switch/when 格式），无法判断组合方式是否符合算子实际的分发逻辑。典型陷阱：存在模式切换属性但未声明 paradigm_groups，导致下游 design 无法生成分区 TilingKey |
+| **REQ「调用框架默认 format」判定是否可靠（SPEC-LAYOUT-1 ③）** | ③ 自动硬拦"spec 轴 ≠ 调用框架默认 format 通道位"。此必看项仅辅助复核：REQ 并列多框架、主次不清时人需定夺取哪个为准，避免 ③ 误判 |
+| **不变量是否真独立 & 覆盖是否够（SPEC-ORACLE-1）** | agent 判得了"有没有值级不变量"，判不了"它是否是 formula 的隐性重述、是否强到能捕获真实语义错"。人需确认：所列不变量确实由 REQUIREMENTS/论文独立推出、且强度足以卡住 formula 的常见错（如 RoPE 的保范可卡住 cos/sin 扩展 tile/repeat 用错） |
+
+### 报告格式（精确模板，供主 Agent 机读判定）
+
+```markdown
+**状态**: ✅通过 / ❌失败
+
+**spec.yaml 路径**: operators/{op}/docs/spec.yaml
+**REQUIREMENTS.md 路径**: operators/{op}/docs/REQUIREMENTS.md
+
+## 17 条 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，修订后**重跑 11-stage + 重跑本场景**；最多重试 2 次
+- 禁止把 ❌ 报告直接抛给用户

package/assets/ops-direct-invoke/skills/ops-spec-gen/registries/anti_pattern_registry.yaml

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+
+# Anti-pattern registry —— Developer Agent 反模式编号
+#
+# 作用：
+#   spec.yaml 在 numerical_stability.techniques[].anti_pattern_id 引用本表中的
+#   AP-NNN 编号；Developer Agent 拿到 spec 后按编号触发对应的代码反模式审计。
+#   schema 用 pattern ^AP-\d{3}$ 卡住格式，本注册表锁定**有效编号集合**——避免
+#   有人写 AP-999（未分配）或 AP-001（已废弃）的 typo。
+#
+# 编号约定：
+#   AP-001..AP-099 通用数值稳定（fp16 上溢 / 累加误差 / 反量化）
+#   AP-100..AP-199 访存反模式（GM 多余往返 / 不连续 stride / cache miss）
+#   AP-200..AP-299 控制流反模式（branch divergence / 同步过多）
+#   AP-300..AP-399 量化反模式（zp 处理错 / scale 截断 / 跨 tile scale 不一致）
+#
+# 维护：新增 AP-NNN 必须先登记到本文件，并在 Developer Agent 仓库中实现对应审计。
+#       spec 引用未登记 ID ⇒ stage 2 emit `paradigm_constraint.unknown_anti_pattern`。
+
+schema_version: 1
+
+anti_patterns:
+  # ---- 数值稳定（AP-001..099）----
+  - id: AP-004
+    summary: "softmax 缺 max-shift 数值稳定"
+    triggers: "Reduction + NumericalStable 范式且 fp16/bf16 输入"
+    detection: "搜索 exp(x) 模式但前序无 max(x, axis=...) 减法"
+    severity: error
+    used_by_examples: [softmax]
+
+  - id: AP-007
+    summary: "fp16/bf16/int 累加未拓宽到 fp32"
+    triggers: "Contraction 范式且 accumulator_dtype < fp32"
+    detection: "Cube/Vector 累加变量声明 dtype 与 accumulator_dtype 不一致；或 reduce 链路缺 cast"
+    severity: error
+    used_by_examples: [matmul, fused_quant_matmul]
+
+  # ---- 访存（AP-100..199）----
+  - id: AP-006
+    summary: "FusedComposite 中间 tensor 经 GM 多余往返"
+    triggers: "FusedComposite 范式且 dataflow.no_leak: true"
+    detection: "中间 tensor 出现在 outputs 或被多次 GM read/write，未被 fuse"
+    severity: warning
+    used_by_examples: []
+    referenced_by: [primitive_whitelist.yaml]

package/assets/ops-direct-invoke/skills/ops-spec-gen/registries/boundary_min_cases.yaml

@@ -0,0 +1,215 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+
+# Boundary minimum cases —— 各 paradigm 必须在 spec.yaml 中覆盖的最低 case 集
+#
+# 作用：
+#   光让算子开发者随便写几条 boundary_conditions / extreme_inputs 不够 —— 不同范式
+#   有自己的"必测退化点"。比如 Reduction 必须测"轴长=1 / rank=0 / 空 Tensor"，
+#   NumericalStable 必须测"fp16 上溢边界"。本文件是这张需求清单。stage 6 据此检查
+#   spec.yaml 是否覆盖到了 paradigms 对应的全部最低 case。
+#
+# 使用方法：
+#   每条 requirement 形如：
+#     - id: reduce_axis_size_1                # 内部唯一 id（用于 finding 引用）
+#       summary: "reduce 轴长度为 1（退化为常数输出）"
+#       section: boundary_conditions          # 在 spec.yaml 的哪个段查找
+#       match_any:                            # 任一关键词出现在 case 描述中即算覆盖
+#         - "reduce 轴长"
+#         - "归约轴.*1"
+#   或：
+#     - id: shape_set_min_three
+#       special_check: dynamic_shape_set_size_min_3   # 结构性检查（见 stage_6 实现）
+#
+# 匹配是子串包含（不是正则）—— 简单、宽容、跨语言友好。
+# 算子作者只要 case 描述里写了任一关键词就过；命中不了说明 case 真的没写。
+#
+# 维护：新增 paradigm 或调整 paradigm 必含 case 时，改本文件即可，stage 6 自动应用。
+
+schema_version: 1
+
+paradigm_requirements:
+
+  Reduction:
+    - id: reduce_axis_size_1
+      summary: "reduce 轴长度为 1（退化为常数输出）"
+      section: boundary_conditions
+      match_any: ["reduce 轴长", "归约轴长度", "轴长度为 1", "axis size 1", "reduce axis"]
+    - id: rank_zero_scalar
+      summary: "rank=0 标量输入"
+      section: boundary_conditions
+      match_any: ["rank=0", "rank 0", "标量输入", "scalar input", "0-dim"]
+    - id: empty_tensor
+      summary: "空 Tensor（含 0 维）"
+      section: boundary_conditions
+      match_any: ["空 Tensor", "空 tensor", "empty tensor", "empty Tensor"]
+
+  NumericalStable:
+    - id: fp16_overflow_boundary
+      summary: "fp16 上溢边界 extreme case（验证数值稳定性技巧是否生效）"
+      section: extreme_inputs
+      match_any: ["fp16 上溢", "fp16 overflow", "上溢边界", "overflow", "60000", "65504"]
+
+  SlidingWindow:
+    - id: stride_gt_kernel
+      summary: "stride > kernel（极端 stride，可能跳过元素）"
+      section: boundary_conditions
+      match_any: ["stride > kernel", "stride 大于 kernel", "stride>kernel"]
+
+  Padding:
+    - id: zero_padding_degenerate
+      summary: "零 padding 退化（padding=0，应等同无 padding）"
+      section: boundary_conditions
+      match_any: ["零 padding", "zero padding", "padding=0", "padding 为 0", "no padding"]
+    - id: huge_padding
+      summary: "超大 padding（padding 远大于输入）"
+      section: boundary_conditions
+      match_any: ["超大 padding", "huge padding", "large padding", "padding 超过"]
+
+  IndexGather:
+    - id: index_out_of_bounds
+      summary: "索引越界（负向 / 超长 / 负数索引）"
+      section: boundary_conditions
+      match_any: ["索引越界", "index out of bounds", "out-of-bound", "out of range", "负索引", "越界"]
+    - id: all_same_index
+      summary: "全相同索引（极端访存模式，触发写冲突或缓存命中）"
+      section: extreme_inputs
+      match_any: ["全相同索引", "same index", "duplicate indices", "重复索引"]
+
+  ScatterUpdate:
+    - id: index_out_of_bounds
+      summary: "索引越界"
+      section: boundary_conditions
+      match_any: ["索引越界", "index out of bounds", "out-of-bound", "越界"]
+
+  AtomicUpdate:
+    - id: index_out_of_bounds
+      summary: "索引越界"
+      section: boundary_conditions
+      match_any: ["索引越界", "index out of bounds", "out-of-bound", "越界"]
+    - id: index_collision
+      summary: "索引冲突（多写到同一目标位置）"
+      section: extreme_inputs
+      match_any: ["索引冲突", "index collision", "collision", "写冲突", "重复索引"]
+
+  MaskPredicate:
+    - id: all_true_mask
+      summary: "全 True mask（应等同恒等映射）"
+      section: extreme_inputs
+      match_any: ["全 True", "all true", "all-true", "全 true"]
+    - id: all_false_mask
+      summary: "全 False mask（应返回填充值或空）"
+      section: extreme_inputs
+      match_any: ["全 False", "all false", "all-false", "全 false"]
+
+  SortSelect:
+    - id: k_zero
+      summary: "k=0（取 0 个元素）"
+      section: boundary_conditions
+      match_any: ["k=0", "k = 0", "k 等于 0"]
+    - id: k_eq_n
+      summary: "k=N（取全部元素）"
+      section: boundary_conditions
+      match_any: ["k=N", "k = N", "k 等于 N", "全部元素", "k = n"]
+
+  ArgReduce:
+    - id: tie_breaking
+      summary: "等值 tie（多个最大/最小值，约定返回最小索引）"
+      section: extreme_inputs
+      match_any: ["等值", "tie", "tie break", "tie-break", "全相同值"]
+
+  Histogram:
+    - id: same_bin_collision
+      summary: "所有值落同一 bin（验证原子加正确性）"
+      section: boundary_conditions
+      match_any: ["落同一 bin", "same bin", "all in one bin", "同一 bin"]
+
+  Spectral:
+    - id: power_of_two_length
+      summary: "长度=2 幂次（fft 优化路径）"
+      section: boundary_conditions
+      match_any: ["2 幂次", "power of two", "power-of-two", "2^"]
+    - id: non_power_of_two
+      summary: "非 2 幂次长度（fft 通用路径）"
+      section: boundary_conditions
+      match_any: ["非 2 幂次", "non power of two", "non-power-of-two", "non-2"]
+
+  DynamicShape: []  # shape_set 要求已移至 ascendc-st-design skill 管理
+
+  RandomSampling:
+    - id: deterministic_with_seed
+      summary: "固定 seed 下结果确定性"
+      section: extreme_inputs
+      match_any: ["固定 seed", "fixed seed", "deterministic", "确定性"]
+
+  Quantization:
+    - id: zero_input
+      summary: "全零输入（验证 zero_point 行为）"
+      section: extreme_inputs
+      match_any: ["全零", "all zero", "zero input"]
+
+  Stateful:
+    - id: state_persists_across_calls
+      summary: "跨调用状态保持（多次调用前后状态一致性）"
+      section: boundary_conditions
+      match_any: ["状态保持", "state persist", "跨调用", "across calls",
+                   "state", "状态", "running", "持久"]   # 放宽匹配——大多数 stateful 算子
+                                                          # 描述里会提到 state/running/状态字样
+
+  VariableOutput:
+    - id: empty_output
+      summary: "零非零元素输入 → K=0 空输出（shape_bounds.min 退化）"
+      section: boundary_conditions
+      match_any: ["全零", "all zero", "K=0", "empty", "空输出", "zero input"]
+    - id: full_output
+      summary: "全非零输入 → K 达到 max_elements 上界（验证分配足够）"
+      section: boundary_conditions
+      match_any: ["全非零", "all nonzero", "满输出", "K=numel", "K=N", "full output"]
+    - id: normal_sparse
+      summary: "正常稀疏情形（介于两个极端之间）"
+      section: boundary_conditions
+      match_any: ["正常稀疏", "normal sparse", "50%", "sparse", "稀疏"]
+
+  Sparse:
+    - id: zero_nnz
+      summary: "零非零元素（退化为空稀疏结构）"
+      section: boundary_conditions
+      match_any: ["零非零", "zero nnz", "empty sparse", "无非零"]
+    - id: fully_dense
+      summary: "全密集（nnz = numel，退化为 dense 操作）"
+      section: boundary_conditions
+      match_any: ["全密集", "fully dense", "dense", "nnz = numel", "满密"]
+
+  Contraction:
+    - id: k_zero_empty_inner_product
+      summary: "K 维 = 0（空内积；输出应为 0 或空）"
+      section: boundary_conditions
+      match_any: ["K == 0", "K=0", "空内积", "empty contraction", "K 为 0", "K 维 0"]
+    - id: k_mismatch_raises
+      summary: "K 维不匹配 → 报错"
+      section: boundary_conditions
+      match_any: ["K 维不匹配", "K mismatch", "K 不一致", "K 不匹配", "contraction mismatch"]
+
+  Elementwise:
+    - id: shape_equal_no_broadcast
+      summary: "输入 shape 完全一致（无广播）"
+      section: boundary_conditions
+      match_any: ["shape 完全一致", "shape equal", "no broadcast", "无需广播",
+                   "rank=2 标准", "rank=3", "rank=4", "标量", "scalar"]
+    # Elementwise 标量 / 空 tensor 已被 Reduction 共覆盖；这里只要"不广播路径"可达即可
+
+  Broadcast:
+    - id: broadcast_with_size_one
+      summary: "需广播（含 size-1 维）"
+      section: boundary_conditions
+      match_any: ["广播", "broadcast", "size 1", "size-1", "维度广播"]
+    - id: non_broadcastable_raises
+      summary: "不可广播（两侧维度冲突）→ 报错"
+      section: boundary_conditions
+      match_any: ["不可广播", "non-broadcastable", "不能广播", "broadcast 冲突",
+                   "广播不合法", "广播不兼容", "K 维不匹配"]

package/assets/ops-direct-invoke/skills/ops-spec-gen/registries/category_enum.yaml

@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+
+# 算子 spec.yaml — op.category 受控集合（26 类）
+schema_version: 1
+categories:
+  - Elementwise            # 纯元素级计算，不涉及广播；e.g. relu, silu, gelu, sin, cos, abs, neg
+  - Reduction              # 沿维度做结合性聚合（sum / mean / max）；e.g. reduce_sum, reduce_mean, reduce_max
+  - ReductionComposite    # reduction + 数值稳定 / 归一化复合；e.g. softmax, layer_norm, rms_norm
+  - Contraction            # 收缩维度乘加；e.g. matmul, bmm, linear, addmm
+  - LayoutTransform       # 不涉及计算，仅通过 shape 变换 / 轴重排 / 拼接拆分 / 广播等方式重组织数据；e.g. reshape, transpose, permute, cat, split, expand, broadcast_to, tile
+  - IndexGather           # 按整数索引读取；e.g. gather, index_select, embedding
+  - ScatterUpdate         # 按索引覆盖写（无写冲突）；e.g. scatter（不含 reduce 形式）
+  - MaskPredicate         # 元素级 mask / predicate 控制计算或访存；e.g. masked_fill, where
+  - SortSelect            # 排序 / TopK / 选择 / 路由筛选；e.g. topk, sort, argsort
+  - FusedComposite        # 多基础范式融合的高价值算子；e.g. flash_attention, attention
+  - RandomSampling        # 含随机数生成 / 采样；e.g. dropout, multinomial
+  - SlidingWindow         # 滑动窗口聚合（Conv / Pool / Stencil）；e.g. conv2d, max_pool, avg_pool
+  - Collective             # 跨设备通信原语；e.g. all_reduce, all_gather, reduce_scatter, broadcast(分布式)
+  - ControlFlow           # 图级控制流；e.g. cond, while_loop
+  - Recurrence             # 含 inter-iteration 顺序依赖；e.g. cumsum, cumprod, lstm, gru, rnn
+  - Interpolation          # 浮点坐标驱动的插值 / 重采样；e.g. interpolate(bilinear), grid_sample, roi_align
+  - Quantization           # 量化 / 反量化转换（INT8 / INT4 / FP8）；e.g. quantize_per_tensor, dequantize, fake_quant
+  - Stateful               # 含跨调用持久状态读写；e.g. batch_norm(running stats), adam_step, sgd_momentum_step
+  - ArgReduce             # 沿维度归约返回索引而非值；e.g. argmax, argmin
+  - Sparse                 # 基于稀疏数据结构（CSR / COO / BSR）；e.g. sparse.mm, sparse.softmax, sparse_addmm
+  - Padding                # 张量边缘填充（zero / reflect / replicate）；e.g. pad, ZeroPad, ReflectionPad
+  - VariableOutput        # 输出 shape 由输入数据值决定；e.g. unique, nonzero, masked_select, dynamic_partition
+  - Spectral               # 频域变换（FFT / DCT / 蝶形）；e.g. fft, ifft, dct, stft
+  - Histogram              # 直方图统计（必有写冲突）；e.g. histogram, histc, bincount
+  - AtomicUpdate          # 按索引累加（含写冲突，需原子操作）；e.g. scatter_add, scatter_reduce, index_add
+  - Broadcast             # 算子计算需要对数据进行广播（数据复制/扩展）；e.g. add, mul, where