version: "1.0.0" name: ops-spec-gen description: "生成或校验算子 spec.yaml（算子的 L0 数学约束唯一真值）。当用户提及：生成 spec.yaml、新算子 spec 骨架、scaffold spec、validate spec.yaml、spec schema 校验、算子规格校验 时触发。"

算子 spec.yaml 生成与校验

为 CANNBot 算子产出符合 schema 的 spec.yaml，并对其执行完整 9-stage L0 校验：

• stage 1 schema_static — JSON Schema 字段静态校验
• stage 2 category_paradigm_consistency — category↔paradigm 一致性 + 4 套白名单 + paradigm 内部约束
• stage 3 shape_closure — numpy_expr 求值 outputs[].shape_rule（含 data_dependent 分流；折叠/显式维 + np.broadcast_shapes）
• stage 4 dtype_closure — dtype DSL 推导 vs supported_combinations 显式表交叉验证
• stage 5 broadcast_legality — broadcast.kind/rules 模拟（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 + 占位符校验

1. 何时使用

2. 输入与输出

3. 生成 spec.yaml

3.1 交互式向导（推荐）

python3 scripts/generate_spec.py --output-dir <ops_dir>/<op_name>

向导会问：op 名称、category（25 类单选）、paradigms（在 category 必含基础上自由追加）、每个 input/output 名+dtype、promotion / broadcast / accumulation_order。

3.2 非交互式（CI / 脚本）

python3 scripts/generate_spec.py \
    --op-name softmax \
    --category reduction_composite \
    --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 自动注入：

• Reduction（且无 Recurrence）⇒ 添加 dim attribute（int_in_range_relative_to_rank）
• Quantization ⇒ 添加 scale / zero_point attribute
• RandomSampling ⇒ 添加 seed attribute
• Stateful ⇒ 第一个 input 标 role: state
• CollectiveCommunication ⇒ op.platform_constraints.requires_hccl: true
• category=contraction / category=reduction_composite / paradigms 含 NumericalStable+Reduction ⇒ 添加 accumulator_dtype: float32
• FusedComposite ⇒ 添加 composition.primitives（2 条占位）+ dataflow.no_leak: true
• NumericalStable ⇒ numerical_stability.required: true + 一条 technique 占位

更多注入提示见 registries/category_paradigm_map.yaml 的 paradigm_inject_hints 段。

3.4 必须手填的 TODO

生成器只产骨架 + 按 paradigm 自动注入的 boundary/extreme case。算子 owner 必须手填：

• outputs[].shape_rule — numpy 子集表达式（如 c.shape = np.broadcast_shapes(a.shape, b.shape)）。

若是 VariableOutput 范式的算子（shape 由输入值决定），改声明 shape_rule_kind: data_dependent + shape_rule_description + shape_bounds.max_elements，不写表达式。

• 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 可 eval 的表达式
• 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 / 全零三类

4. 校验 spec.yaml

python3 scripts/validate_spec.py path/to/spec.yaml          # 文本输出，跑全 9 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

4.1 stage 1 — schema_static

按 schemas/op-spec.json（Draft 2020-12）逐字段校验：必填、类型、enum、pattern、additionalProperties。

4.2 stage 2 — category_paradigm_consistency

校验 category↔paradigm 必含映射 + 4 套白名单 + paradigm 内部约束：

4.3 stage 3 — shape_closure（numpy_expr 求值）

按 outputs[].shape_rule_kind 分流：

• `numpy_expr`（默认）— 在受限 AST 沙箱中执行 outputs[].shape_rule（numpy 子集表达式），求出每个输出的 SymbolicShape。
• `data_dependent` — 输出 shape 由输入数据值决定（nonzero / unique / masked_select 等）；不求解，但强制校验 data_dependent_shape: true + shape_bounds.max_elements + 建议配 shape_rule_description。

shape_rule 的 numpy_expr 示例（matmul）：

outputs:
  - name: c
    shape_rule_kind: numpy_expr
    shape_rule: |
      c.shape = (
          np.broadcast_shapes(a.shape[:-2], b.shape[:-2])
          + ((a.shape[-1] if transpose_a else a.shape[-2]),)
          + ((b.shape[-2] if transpose_b else b.shape[-1]),)
      )

data_dependent 示例（nonzero）：

outputs:
  - name: indices
    shape_rule_kind: data_dependent
    data_dependent_shape: true
    shape_rule_description: |
      indices.shape = (K, rank(x))，K = count(x != 0)，仅运行时已知
    shape_bounds:
      max_elements: "prod(x.shape) * rank(x)"
      output_rank: 2
      static_dims: [{axis: 1, value: "rank(x)"}]
      dynamic_dims: [{axis: 0, name: K, depends_on_value_of: x}]

numpy_expr 支持的子集（按需可扩展，见 scripts/evaluators/shape_eval.py）：

• x.shape / x.shape[-1] / x.shape[:-2]（切片 + 负索引）
• tuple 拼接 +（(a.shape[-1],) + (b.shape[-1],)）
• np.broadcast_shapes(*shapes)（numpy 标准 API 签名）
• IfExp：a if cond else b（cond 从 attribute 默认值解析为 bool）

沙箱规则同 stage 8：禁 import / def / class / for / while / lambda / dunder attribute；5 秒超时。

4.4 stage 4 — dtype_closure

对 dtype_policy.supported_combinations 的每一行，执行 outputs[].dtype_rule（numpy 子集表达式）推导输出 dtype，与显式表交叉比对。常见形式：

# 同 dtype 直传
dtype_rule: "y.dtype = x.dtype"
# 类型提升
dtype_rule: "c.dtype = np.promote_types(a.dtype, b.dtype)"
# 固定 dtype（如 ArgReduce 输出索引）
dtype_rule: "y.dtype = np.int64"
# 条件分支（如 complex_of）
dtype_rule: |
  out.dtype = np.complex64 if real.dtype == np.float32 else np.complex128

numpy 子集支持：

• x.dtype （input 的 dtype 字符串）
• np.promote_types(a, b) / np.result_type(*xs) — 复用 promote 表
• np.int8 / int16 / int32 / int64 / uint8 / uint16 / uint32 / uint64 / float16 / float32 / float64 / bfloat16 / complex64 / complex128 / bool_ dtype 常量
• 比较与 IfExp：a.dtype == np.float32、x if cond else y

Promotion 表覆盖 fp16 / fp32 / fp64 / bf16 / int8 / int16 / int32 / int64 / uint* / bool / complex64 / complex128 + 窄浮点 fp4_e2m1 / fp8_e4m3fn / fp8_e5m2 / hifloat8（见 scripts/evaluators/promote.py）。

4.5 stage 5 — broadcast_legality

按 broadcast.kind 模拟输入 shape 之间的对齐。

v1 已实现：numpy（含折叠维）/ none / explicit（broadcast.rules 必须恰好一条 scope: trailing + 一条 scope: leading，policy 各支持 numpy / no_broadcast，覆盖 matmul 形式）。explicit 的高阶组合（多于 2 个 input、scope: axis）留待扩展。

4.6 stage 6 — boundary_min_set

按 op.paradigms 检查 boundary_conditions[] / extreme_inputs[] 是否覆盖该范式必含的最低 case 集。数据源：registries/boundary_min_cases.yaml。

匹配方式：每条 requirement 用 match_any 关键词列表与 case 描述做子串包含；任一命中即算覆盖。结构性约束（如 shape_set 数量）走 special_check 直接检查。

覆盖的 paradigms：Reduction / NumericalStable / SlidingWindow / Padding / IndexGather / ScatterUpdate / AtomicUpdate / MaskPredicate / SortSelect / ArgReduce / Histogram / Spectral / DynamicShape / RandomSampling / Quantization / Stateful。其他 paradigms 当前无强制最低 case。

4.7 stage 7 — tolerance_coverage

注：本 skill 用 stage 4 输出 dtype 集合（在 stage 4 实现前用 supported_combinations 显式枚举作为代理）；两者通常一致。

4.8 stage 8 — formula_smoke_eval

把 math_semantics.formula 在小 shape（默认 [2,3]）上用 numpy 跑一遍，确认能跑通且产出预期 dtype。

设计要点：

• AST 白名单沙箱 —— 只允许表达式、赋值、numpy 调用；禁止 import / def / class / 循环 / lambda
• 受限 globals —— 只暴露 np / math + 安全 builtins 子集
• 5 秒超时 —— SIGALRM-based，防止意外死循环
• 小 shape —— 折叠维 ...d 丢弃；显式符号维默认 3；常量维原样使用
• dtype 选择 —— 取 supported_combinations[0] 的输入 dtype；bfloat16 没有 numpy 原生类型，用 float32 替代

formula_kind 取值的影响：

• numpy_expr → 跑 stage 8
• python_block / textual_only → SKIP（写在 formula 里的 LaTeX / 自然语言无法 eval）

4.9 stage 9 — oracle_reachable

真 import math_semantics.reference_oracle.framework 并走 getattr 链找到 api，确认它存在且 callable；同时校验 kwargs 中的 ${...} 占位符引用真实存在的 attribute / input / output。

降级策略：

• framework 未装 ⇒ SKIP，不算失败（这是环境问题，不是 spec 缺陷）
• api 拼错 ⇒ FAIL（前提是 framework 装了；没装则跳过）
• 占位符校验与是否装框架无关，永远跑

性能：torch 冷启动 1-3 秒；同进程内多次调用因 import 缓存而即时返回。pre-commit 用户若没装 torch，stage 9 走 SKIP 不影响 < 1s 体验。

5. 文件结构

ops/ops-spec-gen/
├── SKILL.md                              # 本文件
├── references/spec-cheatsheet.md         # 字段速查（按需阅读）
├── examples/                             # PASS 校验的范例（教学 + CI fixture）
│   ├── README.md
│   ├── add/spec.yaml                     #   elementwise + Broadcast
│   ├── softmax/spec.yaml                 #   reduction_composite + NumericalStable + FusedComposite
│   ├── matmul/spec.yaml                  #   contraction（numpy_expr + IfExp transpose）
│   ├── complex/spec.yaml                 #   fused_composite + 复数 dtype（IfExp dtype_rule）
│   ├── cumsum/spec.yaml                  #   recurrence
│   ├── dropout/spec.yaml                 #   random_sampling
│   ├── fused_quant_matmul/spec.yaml      #   fused_composite + quantization（composition DAG）
│   └── nonzero/spec.yaml                 #   variable_output + IndexGather（data_dependent）
├── registries/                           # 11 个 yaml 注册表（白名单+映射，可独立维护）
│   ├── category_enum.yaml                #   25 类 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 列表（unknown 触发 WARN）
│   └── tolerance_defaults.yaml           #   per_dtype 默认容差 + stage 7 紧度阈值（generator/validator 共享）
├── schemas/op-spec.json                  # JSON Schema (Draft 2020-12)
├── templates/spec.yaml.tmpl              # spec.yaml 起手模板
├── scripts/
│   ├── generate_spec.py                  # 生成器（交互/非交互）
│   ├── validate_spec.py                  # 校验器主入口（完整 9 stage）
│   └── evaluators/                       # numpy 子集 AST 求值器（stage 3-5/8/9 实现）
│       ├── _ast_sandbox.py               #   AST 白名单 / dunder 拒绝 / timeout（三 evaluator 共享）
│       ├── types.py                      #   Dim / SymbolicShape / DslError
│       ├── parser.py                     #   parse_shape_literal（解析 inputs[].shape.symbolic）
│       ├── 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 + 占位符校验
└── tests/
    ├── conftest.py                       # pytest sys.path 注入
    ├── test_examples.py                  # pytest：所有 examples 必须 PASS
    ├── test_shape_literal.py             # parse_shape_literal 单测
    ├── test_shape_eval.py                # SymbolicShapeEvaluator 单测
    ├── test_dtype_eval.py                # DtypeEvaluator 单测
    ├── test_broadcast.py                 # broadcast 单测
    ├── test_promote.py                   # promote 表单测
    ├── test_formula_eval.py              # stage 8 沙箱单测
    └── test_oracle.py                    # stage 9 单测

6. 维护规则

注册表是 schema 的真值。当上游 schema 字段变更时，按以下表同步：

每次变更后，跑 examples 回归确认无破坏：

pytest tests/test_examples.py -v
# 或：
for ex in examples/*/spec.yaml; do
  python3 scripts/validate_spec.py "$ex"
done

预期：4 个 example（add / softmax / matmul / complex）全 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 时 numpy 冷启动 ~150 ms，之后同进程内 ~2 ms（pre-commit 钩子每次新进程时是冷启动；总耗时仍 < 1 s 可接受）。

降级矩阵：

8. 与下游 skill / agent 的关系

8.1 字段职责分层

spec.yaml 中的字段按职责分为三层：

8.2 测试配置管理

• 设计原则：L0 规格只包含算子数学约束；测试生成参数由下游 skill 独立管理
• 下游职责：ascendc-st-design skill 在 operators/{op}/tests/st/design/02_测试配置.yaml 中定义测试参数（seed、n_cases、shape_sampler 等）
• 边界/极端数据：boundary_conditions / extreme_inputs 仍保留在 spec.yaml（是算子语义，不是测试参数）

8.3 上游与下游

• 上游（提供）：Designer Agent 接收的算子需求 / REQUIREMENTS.md
• 下游（消费）：
• 9-stage L0 校验器（stage 3-9）以本 skill 输出的 spec.yaml 为输入
• pypto-op-design skill 用 spec.yaml 中 inputs / outputs / math_semantics.formula 生成 DESIGN.md
• Developer Agent 按 spec.yaml numerical_stability.techniques.anti_pattern_id 触发反模式审计
• ascendc-st-design skill 用 boundary_conditions / extreme_inputs 作为测试用例来源（L0 语义），独立管理测试配置参数

9. 已知限制

• stage 3 numpy_expr 求值器暴露的 np 命名空间仅含 broadcast_shapes；如需 reshape / transpose / concat 等形状变换语义，需在 scripts/evaluators/shape_eval.py 的 _NpNamespace 与 _ShapeTuple 上扩展
• stage 4 dtype_eval 的 np 命名空间含 promote_types / result_type + dtype 常量字符串（int8..complex128 + bfloat16）；复杂条件走 IfExp
• stage 5 v1 仅 2 输入广播；explicit rules 仅支持 trailing + leading 组合（matmul 形式）
• stage 6 用关键词子串匹配判 case 是否覆盖；spec 作者用罕见措辞时可能漏匹配，可在 boundary_min_cases.yaml 的 match_any 中扩展关键词
• stage 7 用 dtype_policy.supported_combinations 显式枚举作为输出 dtype 代理
• stage 8 用 [2,3] 作为默认小 shape；折叠维 ...d 展开为 1 维（保证 np.nonzero 等不接受 0-D 的 API 也能跑）；bfloat16 用 float32 模拟（dtype 比对自动放过 stand-in 对）
• stage 9 不真跑 oracle —— 只确认 callable 存在；运行结果与 spec.formula 对拍是 stage 8 + 测试阶段的事
• scripts/validate_spec.py 仍是单文件（stage 2 已拆 8 个子函数）；未来若团队规模扩大可拆 scripts/validators/ 子包，与 scripts/evaluators/ 对称