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

package/assets/ops-direct-invoke/skills/ops-spec-gen/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: ops-spec-gen
+description: "生成或校验算子 spec.yaml（算子的 L0 数学约束唯一真值）。当用户提及：生成 spec.yaml、新算子 spec 骨架、scaffold spec、validate spec.yaml、spec schema 校验、算子规格校验 时触发。"
+---
+
+# 算子 spec.yaml 生成与校验
+
+为 CANNBot 算子产出符合 schema 的 `spec.yaml`，并对其执行完整 12-stage L0 校验：
+- **stage 1** schema_static — JSON Schema 字段静态校验
+- **stage 2** category_paradigm_consistency — category↔paradigm 一致性 + paradigm_groups + paradigm 内部约束
+- **stage 3** shape_closure — numpy_expr 求值 `outputs[].shape_rule`（含 `data_dependent` 分流）
+- **stage 4** dtype_closure — dtype DSL 推导 vs supported_combinations 显式表交叉验证
+- **stage 5** broadcast_legality — 算子计算的 broadcast 语义校验（numpy / none / explicit）
+- **stage 6** boundary_min_set — 按 paradigms 检查 boundary/extreme case 是否覆盖最低集
+- **stage 7** tolerance_coverage — `numerical_tolerance.per_dtype` 覆盖输出 dtype + 紧度启发式
+- **stage 8** formula_smoke_eval — 把 formula 在小 shape (`[2,3]`) 上跑通，沙箱 numpy 执行
+- **stage 9** oracle_reachable — 真 import framework + getattr 链找 api + 占位符校验
+- **stage 10** formula_oracle_equiv — 在含特殊值（NaN/inf/大数/带符号零+0/-0）输入上比对 formula 与 oracle 输出，捕获公式形式差异
+- **stage 11** invariant_exec — 在生成输入上执行 invariants[] 校验 formula 输出，无需 oracle，是 stage 10 SKIP 时的替代机器校验
+- **stage 12** extreme_check — extreme_inputs × formula × machine_check 联合校验：按 pattern 合成输入执行 formula，核对声明期望（produces_nan/nan_propagates/matches_oracle）与实际 NaN/±inf 模式一致，拦截"异号无穷相减误判 NaN"类的特殊值断言错误
+
+## 1. 何时使用
+
+| 场景 | 使用分支 |
+|---|---|
+| 新算子起手，需要 spec.yaml 骨架 | **生成器**（§3） |
+| 已有 spec.yaml，CI/PR 校验或 Designer Agent 重生成回灌 | **校验器**（§4） |
+| 不清楚 26 category × 27 paradigm 怎么填 | 先读 §3.0 分类决策流程（强制读 `category_enum.yaml`），再看 [references/spec-cheatsheet.md](references/spec-cheatsheet.md) |
+| 想看完整范例（11 个 example，全部 PASS 校验） | 看 [examples/](examples/README.md) |
+
+## 2. 输入与输出
+
+| 项 | 说明 |
+|---|---|
+| 入参（生成） | 算子名、category、paradigms[]、inputs（带 dtype_set）、outputs |
+| 出参（生成） | `<output_dir>/spec.yaml`（含 TODO 占位符，需手填 formula / oracle.api / supported_combinations / boundary cases） |
+| 入参（校验） | spec.yaml 路径 |
+| 出参（校验） | 12-stage findings；返回码 0=PASS / 1=FAIL（含 internal_error）/ 2=YAML 解析错；`--strict` 时 warning 也退 1 |
+
+## 3. 生成 spec.yaml
+
+### 3.0 分类决策（前置必读）
+
+> **⚠️ 强制前置步骤**：在调用 `generate_spec.py` 之前，**必须**先读取分类注册表确定 category 和 paradigms，禁止凭直觉猜测。
+
+**步骤**：
+
+1. **读 `registries/category_enum.yaml`**：26 类 category 的定义 + 示例算子列表。逐条对照算子功能，找到匹配的 category。
+2. **读 `registries/paradigm_enum.yaml`**：27 项 paradigm 的分组和优先级。按 category 确定必含 paradigm，再按需追加辅助 paradigm。
+3. **读 `registries/category_paradigm_map.yaml`**：确认 category ↔ paradigm 必含映射（stage 2 会校验此映射）。
+
+**决策示例**：
+
+| 算子 | 读 category_enum.yaml 匹配过程 | 结果 |
+|------|------|------|
+| tile | "不涉及计算，仅通过 shape 变换/广播等方式重组织数据；e.g. reshape, transpose, cat, **tile**" | `LayoutTransform` |
+| slice | "按整数索引读取；e.g. gather, index_select" | `IndexGather` |
+| add(a,b) | "算子计算需要对数据进行广播；e.g. add, mul, where" | `Broadcast` |
+| softmax | "reduction + 数值稳定/归一化复合" + "多基础范式融合" | `ReductionComposite` |
+
+**常见混淆**：
+
+| 易混淆对 | 区分依据 |
+|---------|---------|
+| **Broadcast** vs **LayoutTransform** | Broadcast = 广播是计算的**手段**（add/mul 需要先对齐 shape 再计算）；LayoutTransform = 数据重组织本身就是**目的**（tile/reshape/transpose 不涉及计算） |
+| **IndexGather** vs **LayoutTransform** | IndexGather = 按**整数索引数组**采集元素（gather/embedding）；LayoutTransform = 按**规则**重排/扩展/裁剪（reshape/tile/slice 的索引是确定性推导而非自由索引） |
+| **Reduction** vs **ArgReduce** | Reduction = 输出**值**（sum/max）；ArgReduce = 输出**索引**（argmax/argmin） |
+
+**禁止**：仅凭 cheatsheet 的启发式规则选 category（那些规则覆盖面有限，是辅助参考而非决策依据）。
+
+### 3.1 交互式向导（推荐）
+
+```
+python3 scripts/generate_spec.py --output-dir <ops_dir>/<op_name>
+```
+
+向导会问：op 名称、category（26 类单选）、paradigms（在 category 必含基础上自由追加）、每个 input/output 名+dtype、promotion / broadcast / accumulation_order；当需求存在逻辑布局变体时，还会收集 `layout_contract`。
+
+### 3.2 非交互式（CI / 脚本）
+
+```
+python3 scripts/generate_spec.py \
+    --op-name softmax \
+    --category ReductionComposite \
+    --paradigms Reduction,NumericalStable,FusedComposite \
+    --inputs "x:float16,float32,bfloat16" \
+    --outputs y \
+    --description "Softmax along reduce_axis with max-shift stabilization" \
+    --output-dir ops/softmax
+```
+
+注：`--inputs` 多个时用 `;` 分隔（避免与 dtype_set 的 `,` 冲突），如 `"a:float16,float32;b:float16,float32"`。
+
+### 3.3 自动注入
+
+按 `op.paradigms` 自动注入对应字段（dim attribute / accumulator_dtype / seed / composition 占位等）。完整注入规则见 `registries/category_paradigm_map.yaml` 的 `paradigm_inject_hints` 段。
+
+> **注意**：自动注入基于 paradigm 启发式推断，必须对照 REQUIREMENTS.md 中算子接口描述确认是否需要。当算子接口描述（REG_OP 宏、ACLNN API 参数表、GE IR 表格或自然语言描述）中无归约轴相关参数时，非交互模式应指定 `--axis-source fixed` 或 `--axis-source implicit_all`，避免错误注入 `dim`/`keep_dims` attribute。详见 [usage-scenarios.md](references/usage-scenarios.md) 中 attribute / axis_source 选择规则表。
+
+**format_variants**：当算子支持多种数据排布（NCHW/NHWC/NCDHW 等）且归约轴或计算逻辑因格式而异时，使用 `--format-variants` 参数声明每种格式的具体参数（归约轴、oracle kwargs 等）。生成器会在 `math_semantics` 下注入 `format_variants` 段。
+
+**layout_contract**：当 layout selector 会改变多个 Tensor 的业务逻辑轴顺序（如 attention 的 BSND/BNSD、NCHW→NHWC）时，仅交互式收集 `variants[].when` 与各 Tensor 的 `logical_axes`。它复用已有 `inputs[].layout` / `outputs[].layout` 记录物理 format，不新增 CLI 参数，也不代替 shape rule 或公式。
+
+**paradigm_groups 自动注入**：使用 `--paradigm-groups combination` 或 `--paradigm-groups fusion` 声明范式组合模式。`combination` 模式下 Elementwise 不会被自动过滤（它代表独立的范式分支），生成器为每个 paradigm 生成一条 combination 组（switch/when 为 TODO 占位符，需手填）。交互模式下，当选了 ≥ 2 个范式时会自动询问。
+
+### 3.4 必须手填的 TODO
+
+生成器只产骨架 + 按 paradigm 自动注入的 boundary/extreme case。算子 owner 必须手填：
+- `outputs[].shape_rule` — numpy 子集表达式（如 `c.shape = np.broadcast_shapes(a.shape, b.shape)`）。
+  确定性 shape 的完整 input shape / attribute 依赖必须写在这里；`notes` / `global_constraints`
+  / `REQUIREMENTS.md` 里的文字不算机器可执行规则。
+  若是 VariableOutput 范式的算子（shape 由输入值决定），改声明 `shape_rule_kind: data_dependent` +
+  `shape_rule_description` + `shape_bounds.max_elements`，不写表达式。
+  DynamicShape 范式分两种：attr-driven（reshape / stridedslice，shape 由属性决定）用
+  `numpy_expr` 引用 attribute；value-driven（splitv 的 size_splits 张量输入决定 shape）用
+  `data_dependent` + `shape_rule_description` + `shape_bounds`。
+- `outputs[].dtype_rule` — numpy 子集表达式（如 `c.dtype = np.promote_types(a.dtype, b.dtype)`、
+  `y.dtype = x.dtype`、`y.dtype = np.int32`）
+- `math_semantics.formula` — numpy 可求值的表达式
+- `math_semantics.reference_oracle.api` — 真实的 torch/numpy/scipy API 全限定名
+- `dtype_policy.supported_combinations` — 显式枚举 (input dtypes) → output dtypes
+- `numerical_tolerance.per_dtype` — 覆盖 supported_combinations 中所有 output dtype
+
+按需补充（生成器已自动注入按 paradigm 必含的最低 case，stage 6 通过；下面这些是把生成器的占位描述改成项目语境下的真值）：
+- `boundary_conditions` — 校核 / 补全自动注入的退化 case 描述（详见 cheatsheet §B6）
+- `extreme_inputs` — 校核 / 补全 NaN / Inf / 全零三类
+- `math_semantics.format_variants` — 若算子支持多种数据排布（NCHW/NHWC/NCDHW 等）且计算因格式而异，校核每种格式的 reduction_axes 和 oracle_kwargs
+- `layout_contract` — 若存在逻辑布局变体，校核 selector、参与 Tensor 和每个 variant 的逻辑轴顺序；未确认的布局事实不得猜测生成
+
+## 4. 校验 spec.yaml
+
+```
+python3 scripts/validate_spec.py path/to/spec.yaml          # 文本输出，跑全 11 stage
+python3 scripts/validate_spec.py path/to/spec.yaml --json   # 机器可读
+python3 scripts/validate_spec.py path/to/spec.yaml --strict # 警告也 fail
+python3 scripts/validate_spec.py path/to/spec.yaml --quiet  # 仅打 FAIL 的 stage
+python3 scripts/validate_spec.py path/to/spec.yaml --stage 1 --stage 2  # 仅跑选中的 stage
+```
+
+| stage | 名称 | 核心检查 |
+|-------|------|---------|
+| 1 | schema_static | JSON Schema 字段校验（必填、类型、enum、pattern） |
+| 2 | category_paradigm_consistency | category↔paradigm 必含映射 + paradigm_groups + paradigm 内部约束 + 白名单 + TensorList/semantic_cases/layout_contract 跨字段约束 |
+| 3 | shape_closure | `outputs[].shape_rule` numpy_expr 求值 + data_dependent 分流 |
+| 4 | dtype_closure | `outputs[].dtype_rule` 推导 vs supported_combinations 交叉验证 |
+| 5 | broadcast_legality | broadcast 语义校验（numpy / none / explicit） |
+| 6 | boundary_min_set | 按 paradigms 检查 boundary/extreme case 最低覆盖 |
+| 7 | tolerance_coverage | per_dtype 容差覆盖输出 dtype + 紧度启发式 |
+| 8 | formula_smoke_eval | formula 小 shape 沙箱 numpy 执行 |
+| 9 | oracle_reachable | 真 import framework + getattr 链 + 占位符校验 |
+| 10 | formula_oracle_equiv | 含特殊值（NaN/inf/大数/带符号零）输入上 formula vs oracle 值等价比对 |
+| 11 | invariant_exec | 在生成输入上执行 invariants[] 校验 formula 输出（无需 oracle） |
+| 12 | extreme_check | extreme_inputs 条目按 pattern 合成输入执行 formula，machine_check 声明与实际 NaN/±inf 模式联合校验 |
+
+完整子规则表、numpy 子集 API 列表、代码示例见 [references/stage-rules.md](references/stage-rules.md)。
+
+## 5. 文件结构
+
+```
+ops/ops-spec-gen/
+├── SKILL.md                              # 本文件
+├── references/
+│   ├── spec-cheatsheet.md                # 字段速查（按需阅读）
+│   ├── stage-rules.md                    # 12-stage 完整子规则 + numpy 子集 API
+│   ├── usage-scenarios.md                # 应用场景（场景二 + 场景五）
+│   └── error-codes.md                    # rule_id 全表（自动生成）
+├── examples/                             # 11 个 PASS 校验的范例（教学 + CI fixture）
+│   ├── README.md
+│   ├── add/spec.yaml                     #   Broadcast
+│   ├── softmax/spec.yaml                 #   ReductionComposite + Broadcast + FusedComposite
+│   ├── matmul/spec.yaml                  #   Contraction + Broadcast
+│   ├── complex/spec.yaml                 #   LayoutTransform + Broadcast
+│   ├── cumsum/spec.yaml                  #   Recurrence
+│   ├── dropout/spec.yaml                 #   RandomSampling
+│   ├── fused_quant_matmul/spec.yaml      #   FusedComposite + Broadcast + Quantization
+│   ├── nonzero/spec.yaml                 #   VariableOutput + IndexGather
+│   ├── reduce_sum/spec.yaml              #   Reduction（axis_source=input_tensor）
+│   ├── reduce_sum_fixed/spec.yaml        #   Reduction（axis_source=fixed）
+│   └── reduce_sum_all/spec.yaml          #   Reduction（axis_source=implicit_all）
+├── registries/                           # 13 个 yaml 注册表（白名单+映射，可独立维护）
+│   ├── category_enum.yaml                #   26 类 category
+│   ├── paradigm_enum.yaml                #   27 项 paradigm
+│   ├── category_paradigm_map.yaml        #   category↔paradigm 必含映射 + 注入提示
+│   ├── primitive_whitelist.yaml          #   composition.primitives.op
+│   ├── invariant_kind_registry.yaml      #   invariants.kind（value/algebraic/structural 三组）
+│   ├── machine_check_kind_registry.yaml  #   boundary/extreme.machine_check.kind
+│   ├── synthesize_pattern_registry.yaml  #   extreme_inputs.synthesize.patterns[].pattern
+│   ├── error_code_enum.yaml              #   raises_error.error_type
+│   ├── boundary_min_cases.yaml           #   各 paradigm 必含的 boundary/extreme case（stage 6 数据源）
+│   ├── framework_oracle_registry.yaml    #   stage 9 已知 framework 列表
+│   ├── tolerance_defaults.yaml           #   per_dtype 默认容差 + stage 7 紧度阈值
+│   ├── chip_registry.yaml                #   芯片白名单
+│   └── anti_pattern_registry.yaml        #   反模式 ID 注册表
+├── schemas/op-spec.json                  # JSON Schema (Draft 2020-12)
+├── templates/spec.yaml.tmpl              # spec.yaml 起手模板
+├── scripts/
+│   ├── generate_spec.py                  # 生成器（交互/非交互）
+│   ├── validate_spec.py                  # 校验器主入口（完整 12 stage）
+│   ├── check_registry_schema_sync.py     # registry↔schema 同步检查
+│   ├── dump_rule_ids.py                  # rule_id 全表生成
+│   └── evaluators/                       # numpy 子集 AST 求值器（stage 3-5/8/9/10 实现）
+│       ├── _ast_sandbox.py               #   AST 白名单 / dunder 拒绝 / timeout
+│       ├── types.py                      #   Dim / SymbolicShape / DslError
+│       ├── parser.py                     #   parse_shape_literal
+│       ├── shape_eval.py                 #   stage 3 SymbolicShapeEvaluator
+│       ├── dtype_eval.py                 #   stage 4 DtypeEvaluator
+│       ├── promote.py                    #   numpy 类型提升表
+│       ├── broadcast.py                  #   numpy / none / explicit 广播模拟
+│       ├── stages.py                     #   stage_3 / stage_4 / stage_5 入口
+│       ├── formula_eval.py               #   stage_8 numpy 沙箱
+│       ├── oracle_check.py               #   stage_9 真 import + 占位符校验
+│       └── formula_oracle_equiv.py       #   stage_10 formula vs oracle 值等价
+└── tests/                                # 14 个测试文件
+    ├── conftest.py
+    ├── test_examples.py                  # pytest：所有 examples 必须 PASS
+    ├── test_broadcast.py
+    ├── test_doc_drift.py
+    ├── test_dtype_eval.py
+    ├── test_formula_eval.py
+    ├── test_generate_spec.py
+    ├── test_main_pipeline.py
+    ├── test_oracle.py
+    ├── test_promote.py
+    ├── test_registry_schema_sync.py
+    ├── test_sandbox_escape.py
+    ├── test_shape_eval.py
+    ├── test_shape_literal.py
+    └── test_stage2_constraints.py
+```
+
+## 6. 维护规则
+
+注册表是 schema 的真值。当上游 schema 字段变更时，按以下表同步：
+
+| 变更内容 | 同步位置 |
+|---|---|
+| 增减 category | `registries/category_enum.yaml` + `schemas/op-spec.json` 的 `properties.op.category.enum` |
+| 增减 paradigm | `registries/paradigm_enum.yaml` + JSON Schema 同处 |
+| category↔paradigm 必含映射 | `registries/category_paradigm_map.yaml` |
+| 增减 PRIMITIVE_WHITELIST | `registries/primitive_whitelist.yaml` + JSON Schema |
+| 增减 invariants.kind | `registries/invariant_kind_registry.yaml` + JSON Schema |
+| 增减 machine_check.kind | `registries/machine_check_kind_registry.yaml` + JSON Schema |
+| 增减 synthesize patterns | `registries/synthesize_pattern_registry.yaml` |
+| 增减 paradigm 必含 boundary/extreme case（stage 6 数据） | `registries/boundary_min_cases.yaml` |
+| 调整容差紧度阈值（stage 7 启发式）/ 默认容差 | `registries/tolerance_defaults.yaml` |
+| 扩展 shape_eval / dtype_eval 支持的 numpy API | `scripts/evaluators/shape_eval.py` / `dtype_eval.py` |
+| 调整 numpy 类型提升规则 | `scripts/evaluators/promote.py` |
+| 调整沙箱白名单（AST 节点 / builtins） | `scripts/evaluators/_ast_sandbox.py` |
+| 新增 stage 9 已知 framework | `registries/framework_oracle_registry.yaml` |
+
+每次变更后，跑 examples 回归确认无破坏：
+```
+pytest tests/test_examples.py -v
+```
+预期：11 个 example 全 PASS。任一 FAIL 说明本次 schema/registry 变更破坏了向后兼容，需要回归 example 或回滚变更。
+
+## 7. 依赖
+
+- Python ≥ 3.10
+- `pyyaml`、`jsonschema` (≥ 4.18 支持 Draft 2020-12)
+- `numpy`（可选；缺失则 stage 8 SKIP）
+- 至少一个 reference framework（可选；缺失则对应 stage 9 SKIP）—— 已知列表见 `registries/framework_oracle_registry.yaml`
+- `pytest` (可选，仅运行 `tests/` 时需要)
+
+```
+pip install pyyaml jsonschema numpy pytest
+# 想跑 stage 9 真 import 校验：另装目标 framework
+pip install torch  # 或 jax / scipy / tensorflow
+```
+
+降级矩阵：
+
+| 已装 | stage 8 | stage 9 真 import |
+|---|---|---|
+| pyyaml + jsonschema 仅 | SKIP | SKIP（占位符校验仍跑） |
+| + numpy | ✓ | SKIP（占位符校验仍跑） |
+| + numpy + torch | ✓ | ✓（torch 类 oracle） |
+| + numpy + 全 framework | ✓ | ✓ |
+
+## 8. 与下游 skill / agent 的关系
+
+### 8.1 字段所有权声明
+
+> 本节是 spec.yaml 字段所有权的**唯一权威声明**。Agent 不得自行维护字段所有权列表，必须引用本节。
+
+#### 完整字段列表
+
+以下字段以 `spec.yaml` 为唯一真值源，禁止从 `REQUIREMENTS.md` 正文重新推导、覆盖或自行扩展：
+
+| # | 字段 | 说明 | spec 生成 | 测试 |
+|---|------|------|:---------:|:----:|
+| 1 | `op.category` | 算子主分类（26 类单选） | ✓ | |
+| 2 | `op.paradigms` | 算子范式标签（27 项多选） | ✓ | |
+| 3 | `op.paradigm_groups` | 范式分组（fusion=纵向融合，combination=横向组合） | ✓ | ✓ |
+| 4 | `op.platform_constraints.supported_chips` | 适用芯片白名单 | ✓ | |
+| 5 | `inputs` | 输入张量/标量/state | ✓ | ✓ |
+| 6 | `attributes` | 非张量参数 | ✓ | ✓ |
+| 7 | `outputs` | 输出张量 | ✓ | ✓ |
+| 8 | `outputs[].shape_rule` / `outputs[].shape_rule_kind` | 输出 shape 推导规则 | ✓ | ✓ |
+| 9 | `outputs[].dtype_rule` / `outputs[].dtype_rule_kind` | 输出 dtype 推导规则 | ✓ | ✓ |
+| 10 | `shape_constraints` | 符号表 + 全局约束（`global_constraints` 为咨询性 notes） | ✓ | |
+| 11 | `dtype_policy` | promotion + supported_combinations | ✓ | ✓ |
+| 12 | `broadcast` | 算子计算的 broadcast 语义（数据复制/扩展） | ✓ | ✓ |
+| 13 | `math_semantics` | formula + oracle + invariants + composition | ✓ | ✓ |
+| 14 | `numerical_tolerance` | per_dtype 容差 | ✓ | ✓ |
+| 15 | `boundary_conditions` | 合法但退化的输入 case | ✓ | ✓ |
+| 16 | `extreme_inputs` | NaN / Inf / 全零等异常 case | ✓ | ✓ |
+| 17 | `determinism` | 确定性保证 | ✓ | ✓ |
+| 18 | `numerical_stability` | 数值稳定性技术 | ✓ | ✓ |
+| 19 | `inputs[].data_distribution` | 输入数据分布策略（累加类 Reduction/ReductionComposite/Recurrence/AtomicUpdate/Histogram 必须 normal，非累加类不填；stage 2 强校验） | ✓ | ✓ |
+
+#### 字段职责分层
+
+| 职责层级 | 字段 | 说明 |
+|----------|------|------|
+| **L0 数学约束** | `inputs` / `outputs` / `layout_contract` / `math_semantics` / `shape_constraints` / `dtype_policy` / `broadcast` / `paradigm_groups` | 算子"应该做什么"，下游不可覆盖 |
+| **L0 边界语义** | `boundary_conditions` / `extreme_inputs` | 算子在边界/异常情况的行为预期，下游不可覆盖 |
+| **L0 精度语义** | `numerical_tolerance` / `numerical_stability` / `determinism` | 算子精度要求，下游不可覆盖 |
+| **已移出** | `test_matrix` | 测试生成参数由 `ascendc-st-design` skill 独立管理 |
+
+### 8.2 测试配置管理
+
+- **设计原则**：L0 规格只包含算子数学约束；测试生成参数由下游 skill 独立管理
+- **下游职责**：`ascendc-st-design` skill 在 `operators/{op}/tests/st/design/02_测试配置.yaml` 中定义测试参数
+- **边界/极端数据**：`boundary_conditions` / `extreme_inputs` 仍保留在 spec.yaml（是算子语义，不是测试参数）
+
+### 8.3 上游与下游
+
+- **上游**（提供）：Designer Agent 接收的算子需求 / REQUIREMENTS.md
+- **下游**（消费）：
+  - 12-stage L0 校验器以本 skill 输出的 spec.yaml 为输入
+  - `ascendc-st-design` skill 用 `boundary_conditions / extreme_inputs` 作为测试用例来源
+  - Developer Agent 按 `numerical_stability.techniques.anti_pattern_id` 触发反模式审计
+
+## 9. 已知限制
+
+- stage 3 numpy_expr 求值器暴露的 `np` 命名空间仅含 `broadcast_shapes` / `reduce_shape`；如需更多形状变换语义，需在 `scripts/evaluators/shape_eval.py` 扩展
+- stage 5 v1 仅 2 输入广播；`explicit` rules 仅支持 `trailing + leading` 组合（matmul 形式）
+- stage 6 用关键词子串匹配判 case 是否覆盖；spec 作者用罕见措辞时可能漏匹配
+- stage 8 用 `[2,3]` 作为默认小 shape；`bfloat16` 用 `float32` 模拟
+- stage 9 不真跑 oracle —— 只确认 callable 存在
+
+## 10. 应用场景
+
+| 场景 | 描述 |
+|------|------|
+| 从 REQUIREMENTS.md 生成 spec | 读取需求文档，调用生成器，手填 TODO，跑 12-stage 校验 |
+| spec 独立评审 | 17 条 SPEC-\* 条款逐项对照 spec ↔ REQUIREMENTS，输出评审报告 |
+
+详见 [references/usage-scenarios.md](references/usage-scenarios.md)。

package/assets/ops-direct-invoke/skills/ops-spec-gen/evals/evals.json

@@ -0,0 +1,114 @@
+{
+  "eval_mode": "text",
+  "evals": [
+    {
+      "id": 1,
+      "title": "ops-spec-gen 技能的主要功能与两种模式",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "ops-spec-gen 技能的主要功能是什么？它有哪两种运行模式？可以加载技能，不需要执行其他外部工具调用。",
+      "expected_output": "回复应说明 ops-spec-gen 的两个主要模式：生成模式用于创建 spec.yaml 脚手架文件，校验模式用于执行 9 阶段 L0 验证以确保算子规格定义的正确性和完整性。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 2,
+      "title": "spec.yaml 的 9 阶段 L0 验证",
+      "config": {
+        "max_tokens": 100000,
+        "max_tokens_by_model": {
+          "deepseek-v4-flash": 120000,
+          "glm-5": 110000
+        },
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "ops-spec-gen 的 9 阶段 L0 验证具体包含哪些检查项？可以加载技能，不需要执行其他外部工具调用。",
+      "expected_output": "回复应说明 spec.yaml 的 9 阶段 L0 验证具体包含哪些检查项以及每阶段的作用。",
+      "files": [],
+      "expectations": []
+    },
+    {
+      "id": 3,
+      "title": "category 单选与 paradigms 多选的职责边界",
+      "config": {
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "给一个同时包含广播和计算的算子生成 spec 时，op.category 和 op.paradigms 应如何选择？能不能只看 cheatsheet 的启发式规则决定 category？",
+      "expected_output": "回复应说明 category 是按算子主要数学目的选择的 26 类单选，paradigms 是能力标签多选并包含 category 的必含范式；不得仅凭 cheatsheet 启发式选 category，应依据数学语义区分例如 Broadcast 与 LayoutTransform。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 4,
+      "title": "生成器骨架中的必填 TODO",
+      "config": {
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "generate_spec.py 已经生成 spec.yaml，是否可以不修改直接交给下游？哪些核心字段必须由算子 owner 手工补全？",
+      "expected_output": "1. 回复应说明生成器只产骨架、其中描述真实数学语义的字段仍是 TODO 占位，必须由算子 owner 手工补全后才能交给下游，不能直接视为真值。\n2. 回复应指出必须手工补全的核心字段至少包含 outputs[].shape_rule（VariableOutput/DynamicShape 改声明 data_dependent 描述）、outputs[].dtype_rule、math_semantics.formula、math_semantics.reference_oracle.api、dtype_policy.supported_combinations，并结合需求校核 boundary_conditions/extreme_inputs 等自动注入的占位描述。\n3. 回复应指出 numerical_tolerance.per_dtype 必须覆盖 supported_combinations 中出现的所有输出 dtype。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 5,
+      "title": "无归约轴接口时禁止误注入 dim",
+      "config": {
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "一个 Reduction 算子的 REG_OP、ACLNN 参数和需求描述里都没有归约轴参数。非交互生成 spec 时应该让工具自动注入 dim/keep_dims 吗？",
+      "expected_output": "回复应说明自动注入只是启发式，不能凭空增加接口字段；当接口无归约轴参数时，应按真实语义显式指定 --axis-source fixed 或 --axis-source implicit_all，避免错误注入 dim/keep_dims。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 6,
+      "title": "可选依赖缺失时的 9-stage 降级语义",
+      "config": {
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "环境只有 pyyaml 和 jsonschema，没有 numpy、torch 等 reference framework。9-stage 中哪些部分会降级？能否宣称已经真实执行 oracle？",
+      "expected_output": "回复应说明 stage 8 formula smoke eval 因无 numpy 而 SKIP，stage 9 的真实 framework import 检查 SKIP，但占位符检查仍执行；不能宣称真实执行了 oracle，因为 stage 9 本来也只验证 callable 可达而不运行 oracle。",
+      "expectations": [],
+      "files": []
+    },
+    {
+      "id": 7,
+      "title": "spec 字段所有权阻止下游重新推导",
+      "config": {
+        "ascend_platforms": [
+          "A2"
+        ],
+        "eval_mode": "text"
+      },
+      "prompt": "下游测试设计发现 REQUIREMENTS.md 的文字似乎与 spec.yaml 的 dtype、shape、容差不一致，能否自行按需求正文重写这些字段？测试生成参数又应该放在哪里？",
+      "expected_output": "回复应说明 spec.yaml 是 dtype、shape、数学语义、边界和容差等 L0 字段的唯一真值源，下游不得从 REQUIREMENTS.md 重新推导或覆盖，应先走 spec 修订流程；测试生成参数独立放在 operators/{op}/tests/st/design/02_测试配置.yaml，而非放回 spec 的 test_matrix。",
+      "expectations": [],
+      "files": []
+    }
+  ],
+  "skill_name": "ops-spec-gen"
+}

package/assets/ops-direct-invoke/skills/ops-spec-gen/examples/README.md

@@ -0,0 +1,71 @@
+# spec.yaml 范例
+
+11 个范例覆盖典型复杂度阶梯。**全部通过 9 stage 校验**（stage 9 因测试环境未装 torch 走 SKIP，不算失败）。可以直接拷出来作为新算子起手模板。
+
+| 算子 | 复杂度 | category | 主要 paradigms | stage 通过情况 | 教学点 |
+|---|---|---|---|---|---|
+| [add](add/spec.yaml) | 入门 | broadcast | Broadcast | ✅ 1-8 PASS · ↷ 9 SKIP | 双输入 numpy promote、algebraic invariant（交换律 / 加法零元）、`patterns[]` 数组写法 |
+| [softmax](softmax/spec.yaml) | 中等 | reduction_composite | Reduction + Broadcast + NumericalStable + FusedComposite | ✅ 1-8 PASS · ↷ 9 SKIP | dim attribute 自动注入、accumulator_dtype 必填、composition 五原语链（max-shift + exp + reduce + div）、4 种 invariant 综合（elementwise_ge/le + reduce_equals + no_leak_intermediates）、AP-004 反模式联动 |
+| [reduce_sum](reduce_sum/spec.yaml) | 中等 | reduction | Reduction | ✅ 1-8 PASS · ↷ 9 SKIP | **axis 作为 tensor input**（axis_source=input_tensor）、data_dependent shape_rule_kind、运行时 axis 值决定输出 shape |
+| [reduce_sum_fixed](reduce_sum_fixed/spec.yaml) | 中等 | reduction | Reduction | ✅ 1-8 PASS · ↷ 9 SKIP | **固定归约轴**（axis_source=fixed）、无 dim attribute、reduction.fixed_value 声明固定轴、shape_rule 用字面量 axis |
+| [reduce_sum_all](reduce_sum_all/spec.yaml) | 中等 | reduction | Reduction | ✅ 1-8 PASS · ↷ 9 SKIP | **隐式全轴归约**（axis_source=implicit_all）、无 axis/keep_dims attribute、输出为标量、reduction.axis_source: implicit_all |
+| [cumsum](cumsum/spec.yaml) | 中等 | recurrence | Recurrence | ✅ 1-8 PASS · ↷ 9 SKIP | 沿轴累加、accumulation_order: sequential、dim attribute |
+| [dropout](dropout/spec.yaml) | 中等 | random_sampling | Elementwise + RandomSampling | ✅ 1-8 PASS · ↷ 9 SKIP | seed attribute 自动注入、training/eval 双路径、固定 seed 下 deterministic invariant |
+| [matmul](matmul/spec.yaml) | 进阶 | contraction | Contraction + Broadcast | ✅ 1-8 PASS · ↷ 9 SKIP | 折叠维 + 显式维混合（`"...batch_a", "M", "K"`）、shape_rule 用 numpy_expr + IfExp 表达 transpose、explicit broadcast.rules、algebraic invariant（`equals_when_input_is_zero` / `associative_along_batch`） |
+| [complex](complex/spec.yaml) | 进阶 | layout_transform | Elementwise + Broadcast + LayoutTransform | ✅ 1-8 PASS · ↷ 9 SKIP | 双 input 不同 dtype（real/imag 各 fp32/fp64）、IfExp dtype_rule（fp→complex64/128）、numpy promote 行 + complex 输出 |
+| [nonzero](nonzero/spec.yaml) | 进阶 | variable_output | IndexGather + VariableOutput | ✅ 1-8 PASS · ↷ 9 SKIP | data_dependent shape_rule_kind、shape_bounds.max_elements 上界声明、static_dims/dynamic_dims 拆分、固定输出 dtype int64 |
+| [fused_quant_matmul](fused_quant_matmul/spec.yaml) | 高阶 | fused_composite | Contraction + Broadcast + Quantization + FusedComposite | ✅ 1-8 PASS · ↷ 9 SKIP | composition DAG oracle（5 节点链）+ Quantization + FusedComposite 三合一；CANN 公式 2（FP bias）+ gelu_tanh |
+
+> 安装 torch 后 stage 9 也会变 ✅（`pip install torch`）。
+
+## 阅读顺序
+
+1. **add** — 先看一眼，理解 16 个顶层字段长什么样
+2. **softmax** — 覆盖范式最多，最佳代表（数学性质机器化 + composition 白盒分解）
+3. **reduce_sum** / **reduce_sum_fixed** / **reduce_sum_all** — Reduction 范式的三种 axis_source 模式：
+   - `reduce_sum`: axis 作为 tensor input（运行时决定归约轴）
+   - `reduce_sum_fixed`: 固定归约轴（axis_source=fixed，无 dim attribute）
+   - `reduce_sum_all`: 隐式全轴归约（axis_source=implicit_all，输出标量）
+4. **cumsum** / **dropout** — Recurrence、RandomSampling 范式骨架
+5. **matmul** — contraction 类的 shape 表达（folded + IfExp + explicit broadcast.rules）
+6. **complex** — 多 input 不同 dtype + IfExp dtype_rule
+7. **nonzero** — data_dependent shape_rule 的范式（输出形状由输入值决定）
+8. **fused_quant_matmul** — FusedComposite 的真实落地（量化 + matmul + bias + 激活的 composition DAG）
+
+## 跑校验
+
+```
+# 单个
+python3 ../scripts/validate_spec.py add/spec.yaml
+
+# 全部（用 glob 兜底，新增 example 不需要改命令）
+for d in */; do
+  python3 ../scripts/validate_spec.py "${d}spec.yaml"
+done
+
+# pytest 回归
+pytest ../tests/test_examples.py -v
+```
+
+## 怎么用作模板
+
+1. 选与自己算子最接近的范例
+2. 复制 `spec.yaml` 到 `ops/<your_op>/spec.yaml`
+3. 改 `op.name` / `op.description` / `op.category` / `op.paradigms`
+4. 改 `inputs` / `outputs` / `attributes`
+5. 重写 `math_semantics.formula` 与 `reference_oracle.api`
+6. 调整 `boundary_conditions` / `extreme_inputs`
+7. 跑 `validate_spec.py` 直到 PASS
+
+## 不在范例里的范式
+
+11 个范例覆盖 elementwise / reduction_composite / reduction（三种 axis_source）/ contraction / fused_composite / layout_transform / recurrence / random_sampling / variable_output 等类型。其他算子起手时，先用**生成器**搭骨架：
+
+```
+python3 ../scripts/generate_spec.py \
+    --op-name <your_op> --category <category> --paradigms <PascalCase,...> \
+    --inputs "<name>:<dtype1>,<dtype2>" --outputs <name> \
+    --output-dir <path>
+```
+
+生成的骨架会按 paradigms 自动注入对应字段（accumulator_dtype / composition 占位 / dim attribute 等）。