PyPTO-Gym 算子布局与结构校验pypto-op-lint 门禁规则全解与实战【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读本文围绕 CANN / pypto-gym 仓库中 pypto-op-review 技能族的 CI 设计展开针对custom/operator_name/目录下的算子工程MEMORY.md、test_op.py、分阶段*_module*_impl.py命名、kernel 代码中禁止 Python 循环、view-rank 一致性、cube-tile 合法性、精度比对 helper 等的布局与结构约束已全部由 pypto-op-lint hooks 自动强制校验不再需要单独的 layout 脚本。读完本文你将掌握 lint 的触发时机文件写入即时拦截 阶段/阶段门禁、完整规则映射表与rules.json注册表语义、S0/S1 阻塞机制与修复流程以及如何使用 CLI 手动检查与extract_pypto_calls.py做逐算子调试。一、背景从独立 layout 脚本到lint 规则在早期版本中custom/operator/的目录布局和文件结构靠一个独立脚本在阶段结束后被动检查而现在这些检查被前置并自动化成为pypto-op-lint hooks的一部分见 CI.md 开头声明Layout and structure rules … are enforcedautomatically by the pypto-op-lint hooks— there is no separate layout script to run.这意味着无需手动运行任何 layout check 命令约束内嵌于 Agent 的每次文件写入与每个阶段门禁中违反规则会当场阻断而不是留到验收阶段才暴露。pypto-op-lint 的实际实现位于 pypto-op-lint 插件 下包含rules.json规则注册表、pypto_op_lint/包core.py/hooks.py/cli.py/infer.py/checks/等以及一个向后兼容入口 pypto_op_lint.py。rules.json的version字段当前为2.0.0。二、门禁如何触发How it fires根据 CI.md 与 hooks.py 的实现lint 在两个层面触发2.1 每次文件写入PostToolUse[Write|Edit]当 Agent 写入或编辑*_impl.py、test_*.py等目标文件时hook_post_edit会按文件类型运行对应规则集*_impl.py→ impl 规则如 OL01–OL08、OL48、OL52、OL57 等test_*.py→ test 规则如 OL17–OL22、OL42、OL60。若命中S0/S1 级别的 FAILhook 返回decisionblock在带内in-band拦截本次写入需要修复后重新 Write/Edit同一个文件。该产物生成即阻断模式由环境变量PYPTO_OP_LINT_POST_EDIT_BLOCK默认1控制见 core.py。特殊保护.orchestrator_state.json不允许直接写入须用state_transition工具Stage 1 完成后SPEC.md冻结仅放行只减少 front mattersupported_dtypes的收敛性修订。2.2 阶段 / 阶段门禁complete_phase / complete_stage / stopcomplete_phaseStage 5 内如M1/M2触发phase 门禁仅扫描当前 phase 对应的累积模块 implmodules/op_module1_impl.py等并额外检查 MEMORY.md 的Phase M_k self-reviewOL53/OL54见 cli.py 的 cmd_check_phase_gate。submit_designStage 4Architect 产出 DESIGN.md 后、Verifier 启动前触发design 门禁只跑 OL12 / OL55 / OL56防止因 DESIGN.md 中的 typo 或不存在 API 导致 Verifier 工作作废。stopAgent 结束前触发交付门禁hook_stop按当前 stage 汇总全部适用规则做跨文件一致性复查存在 S0/S1 错误级违规即decisionblock并返回非零码。从源码结构看checks/目录下按维度组织检查器实现d1_framework.py、d1_pypto_api.py、d2_artifact.py、d3_separation.py、d4_test_spec.py、d5_consistency.py并有tests/下的测试如test_hook_integration.py、test_stage7_impl_gates.py、test_stop_gate_strict_mode.py验证 hook 行为。三、规则映射表原 layout 脚本的替代以下是原独立 layout 脚本承担的检查与现 lint 规则 ID 的完整映射继承自 CI.md可直接作为审查速查表Check检查项Lint rule规则 IDtest_op.py存在三件套OL13 / OL44Test 使用assert_allclose或detailed_tensor_compareOL19每个 active phase 的 staged module 三件套OL44Host wrapper 不得用for ... in range(...)驱动 kernelOL45JIT 图内只允许pypto.loop/pypto.loop_unroll/range(...)OL57pypto.viewrank 一致性不是 reshapeOL52set_cube_tile_shapes的 m/k/n 为[L0, L1]0L0L1L1%L00tile 参数是字面量OL48动态轴迭代必须存在pypto.loopOL23 / OL43完整规则注册表见 rules.json。四、规则注册表 rules.json 详解rules.json是 lint 的单一事实来源每条规则包含id、severityS0–S3、dimensionD1–D5、fix_effortE1–E3、stages适用的阶段 1–7、targetimpl/test/golden/gate与规则描述。规则按五个维度组织D1 框架约束合规kernel/impl 代码本身规则级别语义OL01S0kernel 函数必须有且仅有一个pypto.frontend.jit装饰器禁止一切别名写法如pt.frontend.jit、jitOL02S1输出写回必须用[:]/move()/assemble()禁止out exprOL03S1kernel 函数不能有return语句OL04S1JIT 入口及其同文件可达的 Layer I/H helper 必须调用set_vec_tile_shapes或set_cube_tile_shapes允许 JIT 入口一行委托OL05S1kernel 张量参数必须有pypto.Tensor类型注解OL06S1kernel 内禁用 Python 原生min()/max()改用pypto.minimum/maximumOL07S0impl 文件只能使用正规import pypto禁止 alias、import pypto.frontend as ...、from-importOL08S1wrapper 函数必须导出且以_wrapper结尾OL23S2impl 应显式说明是否需要 loop未检测到 loop 结构时提醒OL25S1Tensor 注解禁止空注解pypto.Tensor()/pypto.Tensor([], dtype)一律 FAIL只缺 dtype 时 WARNOL26S1JIT 函数中张量参数必须在非张量参数之前OL28S2sigmoid/softmax/sin/cos仅支持DT_FP32非 FP32 时警告OL29S2Tensor 注解 shape 中应声明pypto.DYNAMIC/pypto.DYN维度OL37S3design 与 impl 的关键中间变量命名应可追溯重合较少时提示OL45S0Layer Khost wrapper不得包含for ... in range(...)逐 chunk 驱动 kernelchunking 属于_kernel_impl内的pypto.loop(N)pypto.viewoffsetsOL46S2同作用域内仅允许一个pypto.loop(N)冗余的pypto.loop(1)包裹内层pypto.loop(N)被禁止OL47S3_kernel_impl调用 2 个pypto_*子 kernel 时优先在每个子 kernel 内设置 tile shapes分阶段局部 tileOL48S0tile 参数必须是编译期可知的 Python int 字面量或可解析到字面量的常量 Assignset_cube_tile_shapes的 m/k/n 每轴必须为 2 元素 list[L0, L1]且0L0L1、L1%L00OL49S1unroll_list只能出现在最内层pypto.loop/pypto.loop_unroll避免编译路径爆炸或寄存器拷贝精度异常OL52S1pypto.view的 shape / offsets / valid_shape 必须同 rankview 是同 rank 的 sub-view 抽取不是 reshapeOL55S0禁止使用 PyPTO 中不存在的pypto.attr对比 AST 属性访问与dir(pypto)防止 typo 如pypto.emptyOL56S0Stage 6 之前unroll_list只能含单一值默认[1]多值展开调优仅允许 Stage 7OL57S0JIT 图内只允许pypto.loop/pypto.loop_unroll/for ... in range(...)禁止while和非 range 的 Pythonfor及含 pypto 算子的推导式OL58S0Layer K wrapper 内禁止调用pypto.zeros/empty/ones/fullJIT-context creation API 在 host 调用会 runtime crashoutput buffer 必须用torch.empty/zeros/empty_like预分配后作为参数传入 JIT 入口OL61S1Experience Preflight 门禁MEMORY.md 检查 AST 扫描 4 类反模式F4 非法 cast 路径 / F2 Element 双重包装 / F1 scalar 首参 / F8 zeros dtype 位置错误OL62S0impl 内 torch 仅限 layout/alloc/cast/reshape任何 torch 张量算术torch.matmul/.exp/.sum//F.*即 FAIL封堵 dummy-JITdead JIT host torch 等作弊模式D2 工件完整性与流程合规文档/交付物与阶段依赖规则级别语义OL09S1Stage 1SPEC.md 结构化章节校验 front matter schema 校验p0_shapes / supported_dtypes / toleranceOL10S1Stage 1API_REPORT.md 结构化章节校验API 映射、约束、TilingOL11S2Stage 2{op}_golden.py必须可导入作为精度基线OL12S1Stage 3/4DESIGN.md 结构化章节校验计算图、Tiling、验证方案OL13S1Stage 5集成成品三件套完整{op}_impl.py、test_{op}.py、README.mdOL14S1进入 Stage 6 需 Stage 5含 cleanup已完成OL24S1.orchestrator_state.json结构合法OL39S1strict 模式下文档必须包含 front matterOL40S1strict 模式下 front matter 必填字段必须完整OL41S1代码工件禁止包含 lint/门禁输出文本污染OL44S1Stage 5 active Phase M_k 要求modules/op_modulesuffix_k_impl.py_golden.pytest_*三件套OL53S2MEMORY.md Golden function inventory 所有行须标记 Status ✅complete_stage 严格判定OL54S1complete_phase 时 MEMORY.md 须含## Phase M_k self-review章节6 个必须项signature 一致 / output 写出 / view rank / inventory 更新 / 无 for-range / JIT exactly once全部- [x]OL59S1Stage 2 完成时 GOLDEN_PERF_REPORT.md 必须存在且含 Op Performance section由profile_golden.py§15 生成D3 三文件分离golden / impl / test 职责隔离规则级别语义OL15S1golden 文件须为纯 torch 规范化实现禁止import pypto禁止.T/.t()须用torch.transposeOL16S1impl 文件不应导入 golden 模块OL17S1test 文件不应包含 kernel 实现代码OL18S1test 文件必须从 impl 和 golden 分别导入D4 测试规范规则级别语义OL19S1test 必须使用assert_allclose或detailed_tensor_compare做精度比对禁止手写assert max_diffOL20S1test 必须处理TILE_FWK_DEVICE_ID环境变量并调用set_deviceOL21S2test 必须有 Level 0 与 Level 1 两级测试函数_l0/level0、_l1/level1子串判定OL22S2test 应设置torch.manual_seed保证可复现OL42S1NPU 环境可用时禁止硬编码 sim 模式defaultsim或run_modesimOL60S0test 实际调用的入口在可达调用链中必须到达至少一个pypto.frontend.jit函数防测试绕过 jit 走纯 PyTorch 入口D5 跨文件一致性spec / design / impl / test / golden 对齐规则级别语义OL30S2spec 声明支持的 dtype 必须在测试文件中覆盖OL31S1design 动态轴声明须与 impl Tensor 注解中的 DYNAMIC 一致OL32S2spec 的 atol/rtol 须与 test 文件一致OL33S2golden 与 wrapper 的必需参数数量一致OL34S1spec 的 P0 测试配置 shape 须在 test 中覆盖OL43S1DESIGN.md 声明动态轴时相关 impl 的 jit 函数必须包含真实pypto.loop硬性门禁不得因 NPU 运行通过而跳过OL50S1Layer K wrapper 显式参数必须与eval/module_interfaces.yaml的 primary_inputs 顺序一致生产 ABI 不暴露 runtime/debug 参数OL51S1输出数 N 须有 N 个真实写出点pypto.assemble/out.move/out[:]且输出不得是平凡 pass-throughOL62S0见 D1跨维度封堵 dummy-JIT更精简的按维度速查表含规则语义一句话版可参考 lint-gate-rules.md其中还特别说明了 OL21 的测试级别命名坑、supported_dtypes语义只算 P0 输入/输出 tensor dtype权重 buffer 与中间计算 dtype 不算以及{op}_pypto_impl.py桥接文件豁免规则。五、阻塞行为与修复流程5.1 S0/S1 FAIL 立即阻断在 hooks.py 中_split_findings将 findings 分为 FAIL / error_failsS0、S1/ WARN / INFOpost-edit 命中 error_fails 时_blocking_reason生成包含违规文件:行号、blocking_rules列表与fix_hints的阻断消息明确要求read the fix_hints above → fix the violations pointed out by file:line → re-run Write/Edit on the [same file]. Do not use bash to bypass lint, do not move files to another path.stop 门禁命中错误级违规时返回 exit code 2并要求修复后继续。5.2 修复提示示例常用规则的内置修复提示_rule_fix_hintOL01装饰器必须原样写作pypto.frontend.jit或pypto.frontend.jit(...)每个 impl 恰好一个别名形式pt.frontend.jit、F.jit、frontend.jit、jit全部拒绝。OL02输出写回用y[:] expr/pypto.move()/pypto.assemble()。OL05/OL25张量参数带完整注解如pypto.Tensor([N, M], pypto.DT_FP32)。OL26参数必须张量在前、标量在后。OL34在 SPEC.md front matter 的p0_shapes填写 P0 形状并在 test 覆盖格式如[[1024,128]]或[{x: [4,2560]}]value 必须是 list。六、手动运行 lint 检查CLI虽然日常流程中 lint 由 hook 自动触发但 cli.py 也暴露了手动子命令便于在算子工作区op-dir内随时复查# 检查 impl 文件D1 框架约束 impl 相关规则 python3 -m pypto_op_lint --lint-impl --op-dir custom/operator_name --stage 5 # 检查 golden 文件OL15 python3 -m pypto_op_lint --lint-golden --op-dir custom/operator_name --stage 5 # 检查 test 文件D4 测试规范 python3 -m pypto_op_lint --lint-test --op-dir custom/operator_name --stage 5 # 检查跨文件一致性D5 python3 -m pypto_op_lint --lint-consistency --op-dir custom/operator_name --stage 5 # 检查当前 stage 的完整门禁 python3 -m pypto_op_lint --check-gate --op-dir custom/operator_name --stage 5 # Stage 5 phase 门禁只扫描当前 phase 累积模块 impl python3 -m pypto_op_lint --check-phase-gate --op-dir custom/operator_name --phase M1 --stage 5 # Stage 4 design 门禁Architect 之后、Verifier 之前 python3 -m pypto_op_lint --check-design-gate --op-dir custom/operator_name --stage 4其中--stage默认值为 5--check-design-gate未显式给 stage 时会自动按 4 处理。任一命令存在 S0/S1 错误级 FAIL 时以 exit code 2 结束_has_error_fail的判定逻辑见 core.py。规则分组IMPL_RULE_IDS/GOLDEN_RULE_IDS/TEST_RULE_IDS/CONSISTENCY_RULE_IDS同样定义在 core.py。七、配套调试工具extract_pypto_calls.py除了自动化布局校验pypto-op-review 还提供一个逐算子 PyPTO 调用点提取工具extract_pypto_calls.py用于定位 kernel 中每个pypto.*调用位置配合 lint 规则做行级调试python3 cannbot-skills/ops/pypto-op-review/scripts/extract_pypto_calls.py \ custom/operator_name/kernel_file.py # JSON lines 输出每行一个调用点便于脚本消费 python3 cannbot-skills/ops/pypto-op-review/scripts/extract_pypto_calls.py \ custom/operator_name/kernel_file.py --json该工具基于 AST 分析不执行代码先收集import pypto含import pypto as p别名与from pypto import matmul等短导入再遍历所有ast.Call节点解析属性链如pypto.matmul(...)、pypto.frontend.jit(...)、p.view(...)记录line、col、call表达式与调用种类attr/short_import默认按行号:列号排序输出Lline前缀的清单便于对照源码逐行审查算子实现是否符合 OL02/OL04/OL48/OL52/OL57 等规则。该脚本也被 pypto-orchestration-manual 的 rules.md 与 pypto-general-debug 参考文档引用为 op-by-op 调试的通用手段。八、工程实践小结把 lint 当编译器post-edit 的 S0/S1 阻断相当于写错即报错修复应在原文件上完成不要用 bash 绕过或迁移文件路径。理解文件类型分流impl / test / golden / gate 规则集不同*_pypto_impl.py纯 torch 桥接与test_*不要误用 kernel 规则。动态轴必须有 loopOL23 / OL43 / OL57 联动DESIGN.md 声明 dynamic_axes 后kernel 内必须有真实的pypto.loop遍历且图内禁止while与非 range 的for。tile 与 view 是最常见的 S0/S1 雷区set_cube_tile_shapes的 m/k/n 必须是[L0, L1]字面量且满足L1 % L0 0pypto.view的 shape/offsets/valid_shape 必须同 rank。跨文件一致性靠门禁兜底dtype、动态轴、容差、P0 shape、golden 与 wrapper 参数数量全部需要在 spec/design/impl/test/golden 之间对齐靠--check-gate/ stop 门禁统一收口。最终规则清单以 rules.json 为准需要快速查阅某条[OLxx][Sx]的语义时可先查 lint-gate-rules.md再回到 rules.json 看完整的stages/target/fix_effort元数据。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyPTO-Gym 算子布局与结构校验：pypto-op-lint 门禁规则全解与实战
PyPTO-Gym 算子布局与结构校验pypto-op-lint 门禁规则全解与实战【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读本文围绕 CANN / pypto-gym 仓库中 pypto-op-review 技能族的 CI 设计展开针对custom/operator_name/目录下的算子工程MEMORY.md、test_op.py、分阶段*_module*_impl.py命名、kernel 代码中禁止 Python 循环、view-rank 一致性、cube-tile 合法性、精度比对 helper 等的布局与结构约束已全部由 pypto-op-lint hooks 自动强制校验不再需要单独的 layout 脚本。读完本文你将掌握 lint 的触发时机文件写入即时拦截 阶段/阶段门禁、完整规则映射表与rules.json注册表语义、S0/S1 阻塞机制与修复流程以及如何使用 CLI 手动检查与extract_pypto_calls.py做逐算子调试。一、背景从独立 layout 脚本到lint 规则在早期版本中custom/operator/的目录布局和文件结构靠一个独立脚本在阶段结束后被动检查而现在这些检查被前置并自动化成为pypto-op-lint hooks的一部分见 CI.md 开头声明Layout and structure rules … are enforcedautomatically by the pypto-op-lint hooks— there is no separate layout script to run.这意味着无需手动运行任何 layout check 命令约束内嵌于 Agent 的每次文件写入与每个阶段门禁中违反规则会当场阻断而不是留到验收阶段才暴露。pypto-op-lint 的实际实现位于 pypto-op-lint 插件 下包含rules.json规则注册表、pypto_op_lint/包core.py/hooks.py/cli.py/infer.py/checks/等以及一个向后兼容入口 pypto_op_lint.py。rules.json的version字段当前为2.0.0。二、门禁如何触发How it fires根据 CI.md 与 hooks.py 的实现lint 在两个层面触发2.1 每次文件写入PostToolUse[Write|Edit]当 Agent 写入或编辑*_impl.py、test_*.py等目标文件时hook_post_edit会按文件类型运行对应规则集*_impl.py→ impl 规则如 OL01–OL08、OL48、OL52、OL57 等test_*.py→ test 规则如 OL17–OL22、OL42、OL60。若命中S0/S1 级别的 FAILhook 返回decisionblock在带内in-band拦截本次写入需要修复后重新 Write/Edit同一个文件。该产物生成即阻断模式由环境变量PYPTO_OP_LINT_POST_EDIT_BLOCK默认1控制见 core.py。特殊保护.orchestrator_state.json不允许直接写入须用state_transition工具Stage 1 完成后SPEC.md冻结仅放行只减少 front mattersupported_dtypes的收敛性修订。2.2 阶段 / 阶段门禁complete_phase / complete_stage / stopcomplete_phaseStage 5 内如M1/M2触发phase 门禁仅扫描当前 phase 对应的累积模块 implmodules/op_module1_impl.py等并额外检查 MEMORY.md 的Phase M_k self-reviewOL53/OL54见 cli.py 的 cmd_check_phase_gate。submit_designStage 4Architect 产出 DESIGN.md 后、Verifier 启动前触发design 门禁只跑 OL12 / OL55 / OL56防止因 DESIGN.md 中的 typo 或不存在 API 导致 Verifier 工作作废。stopAgent 结束前触发交付门禁hook_stop按当前 stage 汇总全部适用规则做跨文件一致性复查存在 S0/S1 错误级违规即decisionblock并返回非零码。从源码结构看checks/目录下按维度组织检查器实现d1_framework.py、d1_pypto_api.py、d2_artifact.py、d3_separation.py、d4_test_spec.py、d5_consistency.py并有tests/下的测试如test_hook_integration.py、test_stage7_impl_gates.py、test_stop_gate_strict_mode.py验证 hook 行为。三、规则映射表原 layout 脚本的替代以下是原独立 layout 脚本承担的检查与现 lint 规则 ID 的完整映射继承自 CI.md可直接作为审查速查表Check检查项Lint rule规则 IDtest_op.py存在三件套OL13 / OL44Test 使用assert_allclose或detailed_tensor_compareOL19每个 active phase 的 staged module 三件套OL44Host wrapper 不得用for ... in range(...)驱动 kernelOL45JIT 图内只允许pypto.loop/pypto.loop_unroll/range(...)OL57pypto.viewrank 一致性不是 reshapeOL52set_cube_tile_shapes的 m/k/n 为[L0, L1]0L0L1L1%L00tile 参数是字面量OL48动态轴迭代必须存在pypto.loopOL23 / OL43完整规则注册表见 rules.json。四、规则注册表 rules.json 详解rules.json是 lint 的单一事实来源每条规则包含id、severityS0–S3、dimensionD1–D5、fix_effortE1–E3、stages适用的阶段 1–7、targetimpl/test/golden/gate与规则描述。规则按五个维度组织D1 框架约束合规kernel/impl 代码本身规则级别语义OL01S0kernel 函数必须有且仅有一个pypto.frontend.jit装饰器禁止一切别名写法如pt.frontend.jit、jitOL02S1输出写回必须用[:]/move()/assemble()禁止out exprOL03S1kernel 函数不能有return语句OL04S1JIT 入口及其同文件可达的 Layer I/H helper 必须调用set_vec_tile_shapes或set_cube_tile_shapes允许 JIT 入口一行委托OL05S1kernel 张量参数必须有pypto.Tensor类型注解OL06S1kernel 内禁用 Python 原生min()/max()改用pypto.minimum/maximumOL07S0impl 文件只能使用正规import pypto禁止 alias、import pypto.frontend as ...、from-importOL08S1wrapper 函数必须导出且以_wrapper结尾OL23S2impl 应显式说明是否需要 loop未检测到 loop 结构时提醒OL25S1Tensor 注解禁止空注解pypto.Tensor()/pypto.Tensor([], dtype)一律 FAIL只缺 dtype 时 WARNOL26S1JIT 函数中张量参数必须在非张量参数之前OL28S2sigmoid/softmax/sin/cos仅支持DT_FP32非 FP32 时警告OL29S2Tensor 注解 shape 中应声明pypto.DYNAMIC/pypto.DYN维度OL37S3design 与 impl 的关键中间变量命名应可追溯重合较少时提示OL45S0Layer Khost wrapper不得包含for ... in range(...)逐 chunk 驱动 kernelchunking 属于_kernel_impl内的pypto.loop(N)pypto.viewoffsetsOL46S2同作用域内仅允许一个pypto.loop(N)冗余的pypto.loop(1)包裹内层pypto.loop(N)被禁止OL47S3_kernel_impl调用 2 个pypto_*子 kernel 时优先在每个子 kernel 内设置 tile shapes分阶段局部 tileOL48S0tile 参数必须是编译期可知的 Python int 字面量或可解析到字面量的常量 Assignset_cube_tile_shapes的 m/k/n 每轴必须为 2 元素 list[L0, L1]且0L0L1、L1%L00OL49S1unroll_list只能出现在最内层pypto.loop/pypto.loop_unroll避免编译路径爆炸或寄存器拷贝精度异常OL52S1pypto.view的 shape / offsets / valid_shape 必须同 rankview 是同 rank 的 sub-view 抽取不是 reshapeOL55S0禁止使用 PyPTO 中不存在的pypto.attr对比 AST 属性访问与dir(pypto)防止 typo 如pypto.emptyOL56S0Stage 6 之前unroll_list只能含单一值默认[1]多值展开调优仅允许 Stage 7OL57S0JIT 图内只允许pypto.loop/pypto.loop_unroll/for ... in range(...)禁止while和非 range 的 Pythonfor及含 pypto 算子的推导式OL58S0Layer K wrapper 内禁止调用pypto.zeros/empty/ones/fullJIT-context creation API 在 host 调用会 runtime crashoutput buffer 必须用torch.empty/zeros/empty_like预分配后作为参数传入 JIT 入口OL61S1Experience Preflight 门禁MEMORY.md 检查 AST 扫描 4 类反模式F4 非法 cast 路径 / F2 Element 双重包装 / F1 scalar 首参 / F8 zeros dtype 位置错误OL62S0impl 内 torch 仅限 layout/alloc/cast/reshape任何 torch 张量算术torch.matmul/.exp/.sum//F.*即 FAIL封堵 dummy-JITdead JIT host torch 等作弊模式D2 工件完整性与流程合规文档/交付物与阶段依赖规则级别语义OL09S1Stage 1SPEC.md 结构化章节校验 front matter schema 校验p0_shapes / supported_dtypes / toleranceOL10S1Stage 1API_REPORT.md 结构化章节校验API 映射、约束、TilingOL11S2Stage 2{op}_golden.py必须可导入作为精度基线OL12S1Stage 3/4DESIGN.md 结构化章节校验计算图、Tiling、验证方案OL13S1Stage 5集成成品三件套完整{op}_impl.py、test_{op}.py、README.mdOL14S1进入 Stage 6 需 Stage 5含 cleanup已完成OL24S1.orchestrator_state.json结构合法OL39S1strict 模式下文档必须包含 front matterOL40S1strict 模式下 front matter 必填字段必须完整OL41S1代码工件禁止包含 lint/门禁输出文本污染OL44S1Stage 5 active Phase M_k 要求modules/op_modulesuffix_k_impl.py_golden.pytest_*三件套OL53S2MEMORY.md Golden function inventory 所有行须标记 Status ✅complete_stage 严格判定OL54S1complete_phase 时 MEMORY.md 须含## Phase M_k self-review章节6 个必须项signature 一致 / output 写出 / view rank / inventory 更新 / 无 for-range / JIT exactly once全部- [x]OL59S1Stage 2 完成时 GOLDEN_PERF_REPORT.md 必须存在且含 Op Performance section由profile_golden.py§15 生成D3 三文件分离golden / impl / test 职责隔离规则级别语义OL15S1golden 文件须为纯 torch 规范化实现禁止import pypto禁止.T/.t()须用torch.transposeOL16S1impl 文件不应导入 golden 模块OL17S1test 文件不应包含 kernel 实现代码OL18S1test 文件必须从 impl 和 golden 分别导入D4 测试规范规则级别语义OL19S1test 必须使用assert_allclose或detailed_tensor_compare做精度比对禁止手写assert max_diffOL20S1test 必须处理TILE_FWK_DEVICE_ID环境变量并调用set_deviceOL21S2test 必须有 Level 0 与 Level 1 两级测试函数_l0/level0、_l1/level1子串判定OL22S2test 应设置torch.manual_seed保证可复现OL42S1NPU 环境可用时禁止硬编码 sim 模式defaultsim或run_modesimOL60S0test 实际调用的入口在可达调用链中必须到达至少一个pypto.frontend.jit函数防测试绕过 jit 走纯 PyTorch 入口D5 跨文件一致性spec / design / impl / test / golden 对齐规则级别语义OL30S2spec 声明支持的 dtype 必须在测试文件中覆盖OL31S1design 动态轴声明须与 impl Tensor 注解中的 DYNAMIC 一致OL32S2spec 的 atol/rtol 须与 test 文件一致OL33S2golden 与 wrapper 的必需参数数量一致OL34S1spec 的 P0 测试配置 shape 须在 test 中覆盖OL43S1DESIGN.md 声明动态轴时相关 impl 的 jit 函数必须包含真实pypto.loop硬性门禁不得因 NPU 运行通过而跳过OL50S1Layer K wrapper 显式参数必须与eval/module_interfaces.yaml的 primary_inputs 顺序一致生产 ABI 不暴露 runtime/debug 参数OL51S1输出数 N 须有 N 个真实写出点pypto.assemble/out.move/out[:]且输出不得是平凡 pass-throughOL62S0见 D1跨维度封堵 dummy-JIT更精简的按维度速查表含规则语义一句话版可参考 lint-gate-rules.md其中还特别说明了 OL21 的测试级别命名坑、supported_dtypes语义只算 P0 输入/输出 tensor dtype权重 buffer 与中间计算 dtype 不算以及{op}_pypto_impl.py桥接文件豁免规则。五、阻塞行为与修复流程5.1 S0/S1 FAIL 立即阻断在 hooks.py 中_split_findings将 findings 分为 FAIL / error_failsS0、S1/ WARN / INFOpost-edit 命中 error_fails 时_blocking_reason生成包含违规文件:行号、blocking_rules列表与fix_hints的阻断消息明确要求read the fix_hints above → fix the violations pointed out by file:line → re-run Write/Edit on the [same file]. Do not use bash to bypass lint, do not move files to another path.stop 门禁命中错误级违规时返回 exit code 2并要求修复后继续。5.2 修复提示示例常用规则的内置修复提示_rule_fix_hintOL01装饰器必须原样写作pypto.frontend.jit或pypto.frontend.jit(...)每个 impl 恰好一个别名形式pt.frontend.jit、F.jit、frontend.jit、jit全部拒绝。OL02输出写回用y[:] expr/pypto.move()/pypto.assemble()。OL05/OL25张量参数带完整注解如pypto.Tensor([N, M], pypto.DT_FP32)。OL26参数必须张量在前、标量在后。OL34在 SPEC.md front matter 的p0_shapes填写 P0 形状并在 test 覆盖格式如[[1024,128]]或[{x: [4,2560]}]value 必须是 list。六、手动运行 lint 检查CLI虽然日常流程中 lint 由 hook 自动触发但 cli.py 也暴露了手动子命令便于在算子工作区op-dir内随时复查# 检查 impl 文件D1 框架约束 impl 相关规则 python3 -m pypto_op_lint --lint-impl --op-dir custom/operator_name --stage 5 # 检查 golden 文件OL15 python3 -m pypto_op_lint --lint-golden --op-dir custom/operator_name --stage 5 # 检查 test 文件D4 测试规范 python3 -m pypto_op_lint --lint-test --op-dir custom/operator_name --stage 5 # 检查跨文件一致性D5 python3 -m pypto_op_lint --lint-consistency --op-dir custom/operator_name --stage 5 # 检查当前 stage 的完整门禁 python3 -m pypto_op_lint --check-gate --op-dir custom/operator_name --stage 5 # Stage 5 phase 门禁只扫描当前 phase 累积模块 impl python3 -m pypto_op_lint --check-phase-gate --op-dir custom/operator_name --phase M1 --stage 5 # Stage 4 design 门禁Architect 之后、Verifier 之前 python3 -m pypto_op_lint --check-design-gate --op-dir custom/operator_name --stage 4其中--stage默认值为 5--check-design-gate未显式给 stage 时会自动按 4 处理。任一命令存在 S0/S1 错误级 FAIL 时以 exit code 2 结束_has_error_fail的判定逻辑见 core.py。规则分组IMPL_RULE_IDS/GOLDEN_RULE_IDS/TEST_RULE_IDS/CONSISTENCY_RULE_IDS同样定义在 core.py。七、配套调试工具extract_pypto_calls.py除了自动化布局校验pypto-op-review 还提供一个逐算子 PyPTO 调用点提取工具extract_pypto_calls.py用于定位 kernel 中每个pypto.*调用位置配合 lint 规则做行级调试python3 cannbot-skills/ops/pypto-op-review/scripts/extract_pypto_calls.py \ custom/operator_name/kernel_file.py # JSON lines 输出每行一个调用点便于脚本消费 python3 cannbot-skills/ops/pypto-op-review/scripts/extract_pypto_calls.py \ custom/operator_name/kernel_file.py --json该工具基于 AST 分析不执行代码先收集import pypto含import pypto as p别名与from pypto import matmul等短导入再遍历所有ast.Call节点解析属性链如pypto.matmul(...)、pypto.frontend.jit(...)、p.view(...)记录line、col、call表达式与调用种类attr/short_import默认按行号:列号排序输出Lline前缀的清单便于对照源码逐行审查算子实现是否符合 OL02/OL04/OL48/OL52/OL57 等规则。该脚本也被 pypto-orchestration-manual 的 rules.md 与 pypto-general-debug 参考文档引用为 op-by-op 调试的通用手段。八、工程实践小结把 lint 当编译器post-edit 的 S0/S1 阻断相当于写错即报错修复应在原文件上完成不要用 bash 绕过或迁移文件路径。理解文件类型分流impl / test / golden / gate 规则集不同*_pypto_impl.py纯 torch 桥接与test_*不要误用 kernel 规则。动态轴必须有 loopOL23 / OL43 / OL57 联动DESIGN.md 声明 dynamic_axes 后kernel 内必须有真实的pypto.loop遍历且图内禁止while与非 range 的for。tile 与 view 是最常见的 S0/S1 雷区set_cube_tile_shapes的 m/k/n 必须是[L0, L1]字面量且满足L1 % L0 0pypto.view的 shape/offsets/valid_shape 必须同 rank。跨文件一致性靠门禁兜底dtype、动态轴、容差、P0 shape、golden 与 wrapper 参数数量全部需要在 spec/design/impl/test/golden 之间对齐靠--check-gate/ stop 门禁统一收口。最终规则清单以 rules.json 为准需要快速查阅某条[OLxx][Sx]的语义时可先查 lint-gate-rules.md再回到 rules.json 看完整的stages/target/fix_effort元数据。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考