ops-spec-gen
生成或校验算子 spec.yaml(算子的 L0 数学约束唯一真值)。当用户提及:生成 spec.yaml、新算子 spec 骨架、scaffold spec、validate spec.yaml、spec schema 校验、算子规格校验 时触发。
SKILL.mdops/ops-spec-gen/SKILL.md
GitHub算子 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 |
| 想看完整范例(11 个 example,全部 PASS 校验) | 看 examples/ |
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,禁止凭直觉猜测。
步骤:
- 读
registries/category_enum.yaml:26 类 category 的定义 + 示例算子列表。逐条对照算子功能,找到匹配的 category。 - 读
registries/paradigm_enum.yaml:27 项 paradigm 的分组和优先级。按 category 确定必含 paradigm,再按需追加辅助 paradigm。 - 读
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_dimsattribute。详见 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 dtypesnumerical_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_kwargslayout_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。
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 强校验) | ✓ | ✓ |
| 20 | op.aicpu_kernel |
AICPU 前置算子名称(可选)。若算子数据流包含 AICPU 前置计算,在此声明;测试生成 Skill 自动检测并在 NPU 测试时插入 AICPU 调用链 | ✓ |
字段职责分层
| 职责层级 | 字段 | 说明 |
|---|---|---|
| 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-designskill 在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-designskill 用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 输入广播;
explicitrules 仅支持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,输出评审报告 |