PyPTO-Pro 算子需求规格SPEC模板全解以 JSON 机器合同为单一事实源的验收规格写法【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gymPyPTO-Gym 仓库的pypto-pro-intent-understandskill 负责把自然语言、官方 API、论文或用户代码中的 PyPTO-Pro 算子需求整理为可执行、可校验的SPEC.mdStage 1 需求澄清阶段的最终交付物。本文以该 skill 的 SPEC 模板 为骨架逐字段讲解 JSON machine-contract 的填写约束并结合 validate_spec.py 的源码级校验逻辑、回归测试与下游消费方golden 脚手架、编排 lint 门禁给出可复制的完整写法。读完本文你可以独立为任意 PyPTO-Pro 算子撰写一份能通过 canonical validator 的 SPEC并理解公式、公开接口、验收配置的唯一机器事实源这一设计如何贯穿 Stage 1 到 Stage 5。一、模板在流水线中的定位pypto-pro-intent-understand只负责回答三件事算什么、接口是什么、怎样算正确。它明确不负责选择 PyPTO-Pro API、计算拓扑、Module、tile、同步或 kernel 写法——那些分别属于 material-explore 与 Stage 3/4。对应的 SKILL.md 描述了完整的输入输出契约输入用户陈述以及用户明确给出的公式、代码、测试、论文或官方 API 引用输出custom/op/SPEC.md必须使用 SPEC 模板覆盖规则若SPEC.md已存在不得静默覆盖先让用户确认覆盖无人值守任务中保留原文件并返回blocked。模板中醒目地写着一条总纲下列 JSON 是公式、公开接口、验收配置的唯一机器事实源。正文只解释语义与证据不复制字段值。这意味着整份 SPEC 由两层组成一个严格的 JSON fenced block机器可解析、可强制校验以及 12 个语义说明小节供人与 Agent 阅读、解释证据与置信度。两者之间有一条硬性纪律正文不得重复机器字段值机器合同不得包含正文才能解释的内容。二、JSON machine-contract 全字段结构模板在json machine-contractfenced block 中给出契约骨架原文占位符形式{ schema_version: 1, op_name: {{OP_NAME}}, formula: {{FORMULA_OR_NUMBERED_STEPS}}, supported_dtypes: [], inputs: [], outputs: [], default_params: {}, tolerance: { atol: null, rtol: null }, dynamic_axes_ranges: {}, shape_constraints: [], p0_cases: [], perf_target: null }从 validate_spec.py 的REQUIRED/OPTIONAL常量可以看到该校验器对字段集合的精确要求必填 11 项schema_version、op_name、formula、supported_dtypes、inputs、outputs、default_params、tolerance、dynamic_axes_ranges、shape_constraints、p0_cases可选 1 项perf_target任何未知字段、缺失字段都会直接报错missing fields/unknown fieldsschema_version必须严格等于1L283-L287。2.1 顶层字段逐项说明字段类型含义与填写要点schema_version整数当前恒为1校验器强校验op_name字符串lower_snake_case正则^[a-z][a-z0-9_]*$小写字母开头只含小写字母、数字、下划线formula字符串用一个 JSON 字符串定义每个公开输出简单算子写可审查等式复杂递推写编号伪代码步骤换行转义为\n每个输出都必须是赋值或箭头目标supported_dtypes数组按首次出现顺序列出本 SPEC 公开输入输出实际使用的全部 canonical dtypeinputs/outputs数组按公开签名顺序每项含name、shape、dtype、value_rangedefault_params对象只放公开签名中的标量默认参数顺序与签名一致无默认参数写{}tolerance对象atol/rtol两个非负有限数未裁定时为nulldynamic_axes_ranges对象动态 shape 符号 → 正整数闭区间[min, max]shape_constraints数组非空字符串组成的约束列表如 rank 关系、广播前提等p0_cases数组至少一项每项含name、params、input_shapes、output_shapesperf_target数值/null只有用户明确给出且可复算的数值目标才填写否则为null2.2 与校验器实现一一对应的细节dtype 词表L35-L38bfloat16、float16、float32、float64、int8、uint8、int16、int32、int64、bool。测试test_rejects_unknown_dtype_and_dynamic_symbol_drift专门验证了把float32换成banana会被拒canonical dtypes。supported_dtypes 必须等于输入输出 dtype 的首现顺序L307-L313校验器收集inputs outputs的 dtype 去重后与supported_dtypes逐项比对。测试test_preserves_mixed_public_tensor_dtypes验证了[int32, float32]这类混合 dtype 组合的保留。tolerance 必须是对象且仅含atol、rtol两个非负有限数L327-L333。perf_targetL335-L340null或正有限数0、负数、NaN、字符串、布尔值均被拒。测试test_perf_target_is_null_or_positive_finite_number逐项覆盖。p0_cases 的 key 与顺序每项的paramskey 名与顺序必须严格等于default_paramsL201-L208input_shapes/output_shapes的 key 名与顺序必须严格等于inputs/outputs的name顺序L211-L219。三、填写约束逐条解读附源码依据模板在 JSON 之后列出了 7 条填写约束这些不是建议而是校验规则。逐条对照源码1. 算子名与 dtype 组合op_name用 lower_snake_casesupported_dtypes按首次出现顺序列出实际使用的全部 canonical dtype同一接口的另一组 dtype 组合拆为独立 class/SPEC——避免下游静默丢失 index、mask 或量化辅助 tensor 的 dtype。这正是_validate_tensor_dtypes严格比对首现顺序的原因。2. formula 必须可执行用一个 JSON 字符串定义每个公开输出。简单算子写可审查等式复杂递推写编号伪代码步骤换行转义为\n且每个输出都必须是赋值或箭头目标。不要只写自然语言标签。校验器只做结构校验——非空字符串L194-L198语义审查由 Agent 负责测试test_requires_auditable_formula验证了缺失、空串、非字符串三种非法形态。3. inputs/outputs 的严格结构按公开签名顺序填写每项严格包含name、shape、dtype、value_rangeTENSOR_FIELDS。rank-0 shape 写[]闭区间值域写有限数值[min, max]界限必须有语义依据未知时不得猜测或用模板示例替代。校验器对每个 tensor 检查name唯一且 lower_snake_case、shape 各维为正、dtype 是 canonical 名、value_range是长度为 2 的有限数数组且min maxL169-L191。4. shape 表达式语法维度只使用正整数或由符号、整数、 - * //和括号构成的表达式。每个动态符号须在至少一个输入 shape 中作为独立维度出现并在dynamic_axes_ranges中给出正整数闭区间。源码中有两级约束语法层_check_shape_syntax用 AST 白名单校验——只允许Name、整数常量、一元/-、二元 - * //和括号L132-L147绑定层_validate_dynamic_symbols要求dynamic_axes_ranges的 key 集合与全部 shape 中出现的符号集合完全相等且每个符号必须作为某输入的独立维度出现L374-L384。测试test_requires_each_shape_symbol_to_have_an_input_anchor验证了把[N, 16]改成[2*N, 16]会被拒standalone dimensiontest_rejects_unknown_dtype_and_dynamic_symbol_drift验证了多余的 range key 与缺失的 range key 都会报exactly match shape symbols。5. default_params 范围只放公开签名中的标量默认参数顺序与签名一致无默认参数写{}。源码要求所有 key 为 lower_snake_case、值为 JSON 标量不能是 dict/listL315-L324。6. p0_cases 至少一项每项严格包含name、params、input_shapes、output_shapes所有映射均按合同声明顺序覆盖全量字段首项params等于default_params每个 shape 都是公式代入后的具体整数数组。源码验证case 名 unique 且 lower_snake_case、首项 params 必须等于默认值L201-L208且每个 case 的 shape 必须代入符号环境后与公式一致_validate_case_expected_shapes。测试test_rejects_schema_and_p0_shape_errors验证了输出 shape 与公式推导不一致会报does not equal。7. 不适用字段用空值不适用的可选字段使用空数组、空对象或null不要保留示例值或另建第二份机器表格。这与 SKILL.md 中禁止把模板占位符或示例值留在成品中一致。四、P0 用例的符号绑定机制SPEC 的核心可验证性来自 P0 用例与 shape 表达式的双向绑定。校验器在 L231-L243 的_case_environment中执行先把 case 的params中所有整数值作为符号环境初始绑定再逐个读取输入 shape 的具体整数与合同中该维的表达式配对如果表达式恰为独立符号就把具体值绑定到该符号重复出现时必须一致否则报inconsistent随后用该环境对所有输入/输出 shape 表达式求值若与 case 中填写的具体 shape 不一致则报错。这套机制保证了每个动态 shape 符号须在至少一个输入维中单独出现这一约束的用途只有独立维度才能提供确定绑定其余输入/输出可以使用由它组成的表达式如2*N、N1。校验器还会检查每个 case 中符号的实际取值落在dynamic_axes_ranges闭区间内L262-L267。值得注意的一个细节校验器在通过后会向调用方返回一个内存字段p0_shapes——取自第一个P0 case 的输入 shapeL427。该字段只供旧调用方使用SPEC 文档本身不双写它test_stage1_skill_contract.py 专门断言模板中不得出现p0_shapes字样防止文档与派生字段漂移。五、语义说明的 12 个小节正文只解释语义与证据模板在机器合同之后固定了 12 个 H3 小节构成 SPEC 的可读部分。每个小节的核心纪律是不重复机器字段值各自承担明确职责小节职责禁止事项1. 功能与分类算子做什么、属于哪一类—2. 公式符号与依据解释公式中每个符号的含义与数学依据不重复 formula 字段内容3. 算法描述复杂算子的逐步算法定义数学过程不规定 tile/硬件实现—4. 数据流说明数据如何流转、广播/预展开前提—5. 接口语义公开接口语义如是否要求调用方预展开辅助 tensor不重复 inputs/outputs 字段6. 功能与可选参数依据optional 参数的公式位置、计算作用、依赖/互斥、默认语义不混入 kernel 实现方式7. 精度语义精度标准与考量不重复 tolerance 字段8. 动态 Shape 与约束依据动态轴与 shape 约束的理由不重复 machine 字段9. 边界条件处理零值、极值、NaN/Inf、空维度、尾部元素的数学行为—10. P0 与性能目标依据为什么选这些 P0、性能目标来源不重复 p0_cases / perf_target 字段11. 参考与来源每条结论的来源与置信度—12. 自动决策无人值守模式下采用的非阻塞默认值及其理由/影响—模板末尾是两行元信息*生成时间: {{TIMESTAMP}}*与*确认状态: {{CONFIRMATION_STATUS}}*用于记录规格的生成时刻与确认状态。SKILL.md 为这些小节提供了证据规则每项非显然结论必须记录来源与置信度——✓ 高用户事实、已批准合同或目标版本官方资料、⚠ 中从论文、源码或用户代码分析得到、❓ 低推断等待确认或按无人值守规则披露。事实优先级为用户陈述/测试 已批准接口合同 官方文档/标准 API 论文/源码/参考实现 模型知识仅可形成待确认草稿。六、校验器实现原理如何做到唯一机器事实源validate_spec.py 是模板的直接执行者其校验管线可以归纳为五步占位符检查任何{{...}}残留直接报unresolved template placeholder remainsL25 与 L54-L59唯一 fenced block 提取正则BLOCK_RE匹配json machine-contract块全文档必须恰好一个否则报exactly oneL24测试test_rejects_second_contract_and_unknown_fields验证了重复块被拒严格 JSON 解析使用object_pairs_hook_unique_object拒绝重复 key用parse_constant钩子把NaN/Infinity转成错误非有限 JSON 数确保机器字段可被任何下游确定性消费L60-L70字段集合校验必填/可选/未知字段三层核对tensor 与 case 各自有严格的字段白名单语义一致性校验shape 表达式求值、P0 shape 与公式一致性、动态符号绑定与区间、dtype 首现顺序、perf_target 合法性。CLI 入口L470-L481接受一个 SPEC 路径参数失败打印FAIL: 原因并退出码 1成功打印PASS: SPEC JSON machine contract is valid。SKILL.md 给出的标准调用方式通过$CANNBOT_CONFIG_ROOT指向 skill 根目录python $CANNBOT_CONFIG_ROOT/skills/pypto-pro-intent-understand/scripts/validate_spec.py \ custom/op/SPEC.md七、一个合法的完整示例test_validate_spec.py 中内置了一个通过校验的最小合法样例demo_op展示了所有约束的落点——注意动态符号N以独立维度出现在输入 shape 中、dynamic_axes_ranges给出闭区间、首项 P0 的params为空对象与default_params一致、两个 P0 case 的输出 shape 均由公式y x代入得到{ schema_version: 1, op_name: demo_op, formula: y x, supported_dtypes: [float32], inputs: [{name: x, shape: [N, 16], dtype: float32, value_range: [-4, 4]}], outputs: [{name: y, shape: [N, 16], dtype: float32, value_range: [-4, 4]}], default_params: {}, tolerance: {atol: 0.001, rtol: 0.002}, dynamic_axes_ranges: {N: [1, 128]}, shape_constraints: [], perf_target: null, p0_cases: [ {name: small, params: {}, input_shapes: {x: [8, 16]}, output_shapes: {y: [8, 16]}}, {name: large, params: {}, input_shapes: {x: [32, 16]}, output_shapes: {y: [32, 16]}} ] }八、模板的守护与下游消费8.1 模板本身被回归测试守护test_stage1_skill_contract.py 中的test_spec_template_has_no_operator_specific_defaults对模板本体施加了硬约束模板中不得出现任何算子特定默认值bfloat16、1024、eps、min_v、max_v等必须恰好包含一个json machine-contract块formula/supported_dtypes/default_params必须保持占位符形态且不得包含派生字段p0_shapes。这保证了模板永远是一份中性契约不会把示例值泄漏成事实。8.2 下游消费golden 脚手架与编排 lintSPEC 并非孤立文档它被流水线强制消费gen_golden_scaffold.pyStage 2 通过load_spec_contract()读取并验证合同把校验后的formula写入生成源码的_SPEC_FORMULA并按合同顺序生成全部p0_cases的签名、shape、参数和 case 名合同无效或字段缺失时非零退出先修正 SPEC 再继续d2_artifact.py 的 PL03 检查编排器的硬门禁会定位 canonical validator在skills/或ops/布局下寻找pypto-pro-intent-understand/scripts/validate_spec.py动态加载其load_spec_contract_text()校验 SPEC.md并核对op_name与编排上下文一致校验失败即FAIL阻塞 Stage 2 推进SKILL.md 的性能单一来源规则只有用户明确给出且可复算的数值目标时才写入perf_target并在第 10 小节记录用户来源否则写null并在自动决策中说明 Stage 5 将使用逐 P0 case 的默认理想参考golden_reference_ratio 1.0——但这一系统默认值不得写成用户要求或交付硬门禁。九、常见错误与排错对照表结合测试用例与校验器实现以下是模板使用中最高频的错误形态及修复要点症状校验器报错根因修复unresolved template placeholder remains模板占位符{{...}}未替换干净逐项替换全部占位符删除不适用的可选行SPEC.md must contain exactly one fenced ... blockmachine-contract 块重复或缺失保证全文档恰有一个json machine-contract块duplicate JSON keyJSON 中出现重复 key使用object_pairs_hook同款严格 JSON 检查non-finite JSON numberNaN/Infinity进入 JSON所有数值必须是有限数supported_dtypes must list ... first-appearance orderdtype 列表与输入输出首现顺序不符按inputs outputs的 dtype 首次出现顺序重排unknown dtype ... canonical dtypesdtype 不在词表内使用bfloat16/float16/float32/float64/int8/uint8/int16/int32/int64/booldynamic_axes_ranges names must exactly match shape symbolsrange key 与 shape 符号集合不一致增删 range key 使其与全部 shape 符号完全相等each shape symbol must appear as a standalone dimension ...符号只出现在复合表达式如2*N中让该符号在至少一个输入维度上独立出现the first P0 case params must equal default_params首项 P0 参数与默认参数不一致首项params原样复制default_paramsshape ... does not equal ...P0 shape 未按公式代入用 case 环境求值 shape 表达式后回填具体整数value_range minimum exceeds maximum/must be a finite number值域越界或非有限给每个输入输出写有语义依据的有限闭区间perf_target must be null or a positive finite number性能目标为 0/负数/非数值无用户目标时写nullschema_version must be 1版本号不符保持schema_version: 1十、端到端实践清单把模板投入使用的推荐流程与 SKILL.md 的四步工作流一致提取最小语义合同确定合法算子名lower_snake_case、公式或逐步算法、每个公开输入/输出/可选参数的 name/rank/shape/dtype/动态轴/语义、输出 shape 推导关系、每个 tensor 的有限value_range、边界行为、精度标准与至少一组可执行 P0 配置识别会改变公开语义的特性mask、量化、融合、动态 shape、混合精度、随机性、稀疏性或数值稳定策略逐项记录是否需要、来源置信度、P0/P1/P2/P3 优先级与对公式/接口/验收的影响P0/P1 必须进入首版集中处理歧义交互模式一次展示数据流摘要、规格清单、关键歧义及拟采用默认值最多两轮无人值守模式仅对非阻塞字段使用先披露再持久化的可追溯默认并在自动决策小节记录数学语义或最小输入输出合同无法确定时返回blocked不猜测生成并自检复制模板逐项替换占位符删除不适用的可选行然后运行validate_spec.py非零退出时修复后重跑直至PASS。完成条件速查SKILL.md算子名/数学语义/最小输入输出合同已确定shape、dtype、动态轴、optional 参数和边界行为已确认或留有证据复杂算子含可恢复算法步骤所有功能已标优先级且 P0/P1 无遗漏所有 P0 可构造 golden 输入且输出 shape 与公式一致所有 machine-contract 输入输出均有有依据的有限value_range恰有一个严格 JSON machine-contract、正文无机器字段重复、无占位符或未披露默认值性能目标来源已明确记录validate_spec.py通过。至此从模板字段、填写约束、校验器实现、回归测试到下游消费SPEC.md 作为 Stage 1 唯一机器事实源的完整闭环已经清晰模板负责规定写什么校验器负责保证写得对golden 脚手架与编排 lint 负责确保下游读得一致。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考