PyPTO-Gym 多智能体编排行为原则详解Simplicity First、Surgical Changes 与 Goal-Driven Execution【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读principles.md是 pypto-orchestration-manual 技能库中的基础行为纲领定义了本仓库所有 skill 执行时共同遵守的三条核心原则Simplicity First简洁优先、Surgical Changes外科手术式修改、Goal-Driven Execution目标驱动执行。该文档是 pypto-op-orchestrator 在每次会话首次调度子代理前必须加载的入门参考SKILL.md 明确要求 Always load before the first dispatch of any session。本文将逐条解析这三条原则的判定标准、在 PyPTO 算子开发流水线中的具体落点并结合仓库中的强制规则rules.md、子代理调度契约agents.md、lint 门禁lint-gate-rules.md与验证工具源码detailed_tensor_compare.py做纵深印证帮助读者理解多智能体协作下少写、少改、可验证的开发纪律。一、原则总览为什么编排者需要一份行为宪法在 PyPTO-Gym 仓库中算子开发不是单个 Agent 的独立行为而是由pypto-op-orchestrator 驱动的 8 智能体团队planner、mathematician、architect、coder、verifier、debugger、optimizer在 Stage 1–7 流水线上接力完成的过程见 agents.md。流水线中一份 kernel 代码会经过设计、golden 冻结、分模块实现、逐模块验证、E2E 验证、性能调优等多次交接任何过度设计顺手重构无验证目标的乱改都会被放大为后续阶段的返工成本。因此 principles.md 定义了适用于每个 skill、每个子代理的三条基础行为原则而 rules.md 在此之上叠加 PyPTO 专属的强制条款zero-tolerance 规则、三大架构禁令、停止条件等。二者关系正如原文档开篇所声明These principles apply to every skill. rules.md adds PyPTO-specific enforcement on top.换言之principles 是怎么做事的风格rules 是什么事绝对不能做。原则部分负责减少不必要的改动、降低返工率规则部分负责保证产物硬性合规。编排者在每次会话开始时按 AGENTS.md 的强制启动顺序加载先读 SKILL.md再读 principles.md → agents.mdagents.md 携带了全部子代理的输入/交付件/门禁/交接信息足够完成派发rules.md 属于按需加载的执行细节。原则是否生效的验收信号原文档在结尾给出了判断这套原则是否真正起效的四个信号可作为团队自检标准diff 中不必要的改动减少Surgical Changes 的直接效果因过度复杂化而导致的返工重写减少Simplicity First 的直接效果澄清性问题发生在实现之前而非犯错之后Goal-Driven Execution 的直接效果每个模块以更少的尝试次数通过验证三条原则综合作用的结果。二、原则一Simplicity First简洁优先2.1 原则定义与判定测试Minimum code that solves the problem. Nothing speculative.—— 用解决问题所需的最少代码不写任何投机性内容。原文档给出了明确的禁止清单不实现超出需求范围的功能不为一次性使用的代码引入抽象不添加未被要求的灵活性或可配置性不为不可能发生的场景编写错误处理如果写了 200 行而 50 行就能完成就重写。判定测试如果一位资深工程师认为这段代码过于复杂那就简化它。这条原则在仓库的 lint 规则中得到了制度化。例如 lint-gate-rules.md 中的OL56S0Stage 6 之前pypto.loop的unroll_list只能包含单一值默认[1]含 2 个及以上值会触发编译路径爆炸、拖慢编译并使开发流程超时——多值展开调优仅允许在 Stage 7 进行。这正是不做投机性优化的工程化表达在正确性未锁定前任何为性能预铺的复杂路径都被直接拦截。2.2 PyPTO 应用场景最小可行实现 detailed_tensor_compare原文档明确给出了原则在 PyPTO 算子开发中的落点Every module should be the minimum viable implementation that passesdetailed_tensor_compare. Do not add speculative optimization, extra loop unrolling, or unused tile configurations.即每个模块只做到能通过detailed_tensor_compare的最小可行实现不添加投机性优化、多余的循环展开或未被使用的 tile 配置。这里提到的detailed_tensor_compare是仓库的核心精度比对工具源码位于 cannbot-skills/ops/pypto-op-verify/scripts/detailed_tensor_compare.py。其核心逻辑是将两个张量.cpu().float()归一化后逐元素比对容差判定采用atol rtol * |expected|标准默认rtol1e-3、atol1e-3见 TensorCompareOptions返回包含all_close、out_of_tolerance_count、out_of_tolerance_ratio、max_diff、mean_diff、std_diff等字段的详细统计字典对 tuple/list/dict 等嵌套输出结构递归展开到每个张量叶子逐一比对tensor_leaf_pairs输出结构不匹配类型、数量、键不一致会直接抛AssertionError对非有限值NaN/Inf有专门处理仅当两侧同时为同符号 Inf 时才视为容忍否则计为超差源码 _build_result。在测试实践中仓库测试目录大量使用该工具。例如 tests/ops/qwen3_5/gdr_bwd/test_gdr_bwd.py 通过 import 该 helper 对 golden 与 PyPTO 输出做全叶子精度比对tests/ops/ling_3_0_flash/chunk_kda/test_chunk_kda.py 同样如此。规则 rules.md 将其固化为强制项禁止省略detailed_tensor_compare或只比对单个输出——每个 stage 的每个叶子输出都必须比对测试文件test_op.py同样如此。2.3 简洁原则与分层模板的平衡需要强调的是简洁优先不等于可以随意组织代码。仓库通过 impl_template.py.tmpl 强制 kernel 实现采用Layer G–K 分层结构Layer G 缓存桥接、Layer H PyPTO 子内核、Layer I kernel 实现、Layer Jpypto.frontend.jit入口、Layer K host wrapper并由规则 rules.md 规定每个交付物op_module1.py…op_module1…N.py及集成 kernel都必须以此为骨架。这两者并不矛盾模板解决的是代码该长在哪一层的结构问题简洁原则解决的是每一层内部该写多少逻辑的数量问题。例如 Layer Khost wrapper被严格限定为三个职责——搬张量到设备、分配输出 buffer、恰好调用一次 JIT 入口impl_template.py.tmpl任何在 wrapper 里用 Pythonfor ... in range(...)驱动 kernel 分块的行为都会被OL45S0拦截因为分块迭代必须放进 Layer I 的pypto.loop中。这就是简洁与结构合规的协同把逻辑放在它该在的位置并且每个位置只做最少的事。三、原则二Surgical Changes外科手术式修改3.1 原则定义与判定测试Touch only what you must. Clean up only your own mess.—— 只触碰必须改的部分只清理自己造成的混乱。当编辑既有代码时不顺手改进相邻代码、注释或格式不重构没有坏的东西即使你会有不同的写法也要匹配既有风格如果发现无关的死代码提出来但不要删除。而当自己的改动制造了孤儿引用orphans时移除由你的改动导致不再使用的 import/变量/函数但不删除改动前就存在的死代码除非被明确要求。判定测试每一行改动都必须能直接追溯到当前任务。这条原则的深层动机在于多智能体流水线的特殊性一份 kernel 文件会被多个 Agent 依次读写coder 写、verifier 判、debugger 查、optimizer 调任何顺手重构都可能破坏其他 Agent 对代码的预期制造无法定位的回归。3.2 PyPTO 应用场景冻结模块、golden 代码与失败边界原文档给出了三个非常具体的 PyPTO 落点不要改进已冻结的模块frozen modules。在 rules.md 中golden 文件在 Stage 2 冻结后不得无证据修改任何变更都要记录在op_golden.py头部注释中Stage 5 的变更还要额外记入custom/op/MEMORY.md。这保证了 golden 作为所有阶段精度基线的稳定性。不要重构已经工作的 golden 代码。golden 是纯 torch 规范化实现lint-gate-rules.md 的OL15要求 golden 禁止import pypto、禁止.T/.t()必须用torch.transpose它是验证 PyPTO 内核正确性的基准动它等于移动标尺。当下游模块失败时不要编辑上游 staged 文件——先检查失败的边界。这对应 rules.md 的模块边界检查纪律每个模块的 golden vs PyPTO 边界验证通过后才能进入下一个模块边界失败应定位到具体模块而非盲目回改上游。3.3 与 lint 门禁的协同OL 规则的定位作用Surgical Changes 与 lint-gate-rules.md 中的 OL 规则体系形成了精密的协同。lint 在文件写入post-edit hook与阶段/Phase 门禁submit_for_verify/complete_phase/complete_stage时自动运行其作用正是把哪里违反了哪条纪律精确指认出来让 Agent 只修改被点名的位置而非大面积返工OL 规则级别语义要点与 Surgical Changes 的关系OL45S0Layer K wrapper 禁止for ... in range(...)驱动 kernel精确锁定违规行无需重写整个 wrapperOL57S0JIT 图内只允许pypto.loop/loop_unroll/for...in range限定修改范围为 JIT 图内部OL48S0tile 参数必须是编译期字面量防止为修 bug 而引入动态 tile 的大改OL62S0impl 内 torch 仅限 layout/alloc/cast/reshape数值计算必须在 JIT 图内杜绝 dummy-JIT 全谱作弊OL50S1Layer K wrapper 显式参数必须与module_interfaces.yaml的 primary_inputs 顺序一致锁定接口契约禁止随意增删参数规则 rules.md 明确要求任何 lint 规则处于 FAIL 时不得宣称完成。这意味着外科手术式修改有了可自动执行的兜底——每次 edit 后 lint 立刻反馈哪一行违反了什么Agent 只需针对被拦截的OLxx规则做最小修补然后重新submit_for_verify。3.4 只清理自己的混乱在流水线中的体现当 verifier 报告 FAIL 时编排者遵循verifier裁判→ debugger调查→ coder应用补丁→ verifier再次裁判的固定链路agents.md。其中 debugger 被明确禁止直接写生产 kernel 代码只能向 MEMORY.template.md 的Development debug log提交补丁方案含文件行范围、当前片段、建议片段、对失败验证的预期效果生产代码的写入只有 coder 有权限。这种职责分离正是 Surgical Changes 在组织层面的延伸谁造成的混乱失败的实现由谁负责清理coder 应用补丁调查者只提供证据、不动刀。四、原则三Goal-Driven Execution目标驱动执行4.1 原则定义把任务转化为可验证的目标Define success criteria. Loop until verified.—— 定义成功标准循环直至验证通过。这是三条原则中最具操作性的它要求把模糊的任务描述转化为可机械验证的成功标准从而让 Agent 能够独立循环loop而不必频繁打扰人类澄清。原文档给出的转化示例表原始说法转化后的可验证目标Implement Phase M1M1 passesdetailed_tensor_comparewithall_close: trueon all outputsFix precisionIdentify diverging checkpoint via bisection, apply fix, re-run compareOptimize performanceReduce kernel time by N% while layout check exits 0 and all outputs pass compare4.2 多步骤任务的计划格式对多步骤任务原文档要求先陈述简短计划每一步都挂一个验证动作1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check]强成功标准让你能独立循环弱标准如make it work会导致无休止的澄清。这在多智能体场景下尤为关键编排者派发子代理后无法也不应逐行盯守靠的正是每个阶段/Phase 明确的 gate 判据。4.3 Goal-Driven 在仓库中的制度化这条原则在仓库中不是口号而是被完整制度化的状态机与门禁体系(1) Stage/Phase 状态机state_transitionAGENTS.md 定义了 Phase 状态机pending --start_phase-- in_progress in_progress / in_debug --submit_for_verify (lint PASS)-- awaiting_verify in_progress / in_debug / awaiting_verify --complete_phase (lint PASS)-- verified 任一态 --fail_phase-- in_debug 达到 max_cycles 时为 blocked每个 transition 都对应一个明确的验证动作submit_for_verify跑 Phase 范围 lintFAIL 则抛错且状态不变complete_phase再跑一遍 lint 兜底complete_stage(5)仅在所有已启动 phase 均为 verified时放行。(2) 每阶段的 verifier 检查清单AGENTS.md 列出了每个 Stage 的验证内容可视为成功标准清单的权威版本Stage成功标准verifier 检查内容1API map 干净零unsupported行或每行有文档化 workaround2goldenallclose通过、零.T、shape 注释齐全4模块拆解/契约/module_interfaces.yaml齐备L1 路径还需对抗 harness 存在且--self-test通过5 Phase M_k模块单测通过 layout check 退出码 0 --up-to-module k处 prefix-eval 报status: PASS6最终 E2Edetailed_tensor_compare全输出all_close: true layout check 退出码 0 完整 impl 的 prefix-eval PASS7调优收尾debug_options已还原 调优报告已生成 verifier 回归确认无精度/结构回归(3) MEMORY.md 的机器可读字段MEMORY.template.md 顶部即要求维护一组机器可读字段作为目标的持续追踪phase: 0|1|2|3|4|5|6 decomposition_level: L0|L1 # from DESIGN.mdL0 single module, L1 multi-module module_count: 1 # 1 for L0, ≥2 for L1 active_module: M1 # for L1 onlyL0 sets active_module: M1 (single) current_staged_file: custom/operator_name/operator_name_module1.py modules_pypto_verified: - id: M1 evidence: command or pointer to Per-module verification log row detailed_tensor_compare_ok: true # false until boundary passes next_mandatory_step: one concrete step correctness: not_started | golden_ok | sim_ok | npu_ok optimization: not_started | … | complete | skipped_user_request blockers: []其中next_mandatory_step字段正是 Goal-Driven 原则的即时体现——每一轮结束后都明确写出下一个必须步骤确保任意时刻接手流水线的 Agent 都知道当前目标是什么。4.4 目标驱动在精度问题排查中的应用原文档示例中Fix precision被转化为通过 bisection 定位发散 checkpoint应用修复重跑 compare。仓库为此提供了配套工具链detailed_tensor_compare.py 返回的字典包含out_of_tolerance_ratio、max_diff、outlier_indices超差元素索引、outlier_values1/2等字段可精确定位哪个坐标点发散、偏离多少snapshot_bisect.pypypto-op-verify 技能用于对中间快照做二分定位规则 rules.md 的Golden function inventory要求把 golden 中每个数学操作逐行列清单与 PyPTO 实现交叉核对✅ 带 pypto 调用行号 / ❌ 缺失存在任何 ❌ 时不得运行测试或推进模块——因为精度错误最常见的原因就是某个操作根本没实现。这套机制让修精度从玄学变成可定位、可验证的工程问题。五、三条原则的协同与流水线落地全景5.1 原则之间的依赖关系三条原则不是孤立的而是层层支撑的闭环Simplicity First 控制写入端产出最小可行实现减少后续需要维护和排查的代码量Surgical Changes 控制修改端后续迭代只动必须动的地方保护已冻结的 golden 与已验证模块Goal-Driven Execution 控制验证端为每一步定义机械可查的成功标准让少写、少改的成果能快速被确认或否定。三者共同服务于一个目标让每个模块以更少的尝试次数通过验证原文档的验收信号第 4 条。5.2 在 Stage 5 分模块循环中的完整示例以 L1 路径module_count ≥ 2的 Stage 5 为例三条原则如何在循环中同时起作用流程见 AGENTS.mdstart_phase(M_k)在 MEMORY.md 设置active_module: M_k——Goal-Driven明确当前目标模块派发 coder 产出op_modulesuffix_k_impl.py按 Layer A–L 模板实现最小可行版本Simplicity First不预写下一模块的逻辑规则 rules.md 要求后续阶段先 stubsubmit_for_verify(M_k)跑 Phase lintFAIL 则 coder 只修补被拦截的OLxx行Surgical Changesverifier 以 Phase scaffolding 模式验证——比对每个叶子输出Goal-Driven 的all outputs标准PASS 才complete_phaseFAIL 则携带failure_category 失败文件派发 debugger 调查、coder 应用补丁Surgical Changes 的职责分离循环上限 10 次后 phase 进入blocked编排者须上报用户或rollback_to_stageGoal-Driven 的失败出口。L0 路径module_count 1则直接跳过 staged 链coder 一次产出op_impl.pyverifier 跑单次 E2Edetailed_tensor_comparePASS 即complete_stage(5)AGENTS.md。5.3 性能调优阶段的目标形态进入 Stage 7 后Goal-Driven 原则体现为可量化的性能目标AGENTS.md 要求编排者 INIT 时计算perf_target_us若 initial prompt 已注入平台性能基线则必须原样采用并把target_met 实际us ≤ perf_target_us作为 S4 调优循环S4_FRONTEND → [S4_SWIMLANE → S4_INCORE] × ≤3 轮 → S5的退出判据同时要求perf_baseline_us/perf_target_us必须是真实数值非pending才能派发下一轮。这完全对应原文档示例表中的第三条转化Reduce kernel time by N% while layout check exits 0 and all outputs pass compare——优化轮次的最终验收仍然要由 verifier 以 Stage 7 regression mode 重跑 E2Edetailed_tensor_compare layout check 兜底agents.md确保性能目标达成不以精度/结构回归为代价。六、实践建议如何在算子开发中应用这三条原则基于原文档与仓库机制可将三条原则转化为可直接执行的开发纪律动手前先定义成功标准对每个模块把目标写成detailed_tensor_compare全输出all_close: truertol/atol 默认1e-3可经TensorCompareOptions调整而非实现这个功能多步骤任务按[Step] → verify: [check]格式列计划。写最少但合规的代码遵循 impl_template.py.tmpl 的 Layer G–K 分层不预写未验证模块的逻辑先 stub 并注释# STUB: until M2 verified; golden-fed tensor见 rules.md不添加投机性优化Stage 6 前unroll_list只用单值。改代码只动必动处被 lint 拦截时只修报出的OLxx行不重构未坏代码不修改已冻结的 golden下游失败先查失败边界不回改上游 staged 文件。让验证说话不用口头应该能过规则 rules.md 明令禁止用should pass/aligned之类表述替代真实运行——必须运行命令并把证据粘贴进日志或 stage 交付物Stage 5 同时写入custom/op/MEMORY.md。遇到晦涩错误不轻言放弃FFFFF、UNKNOWN、0x3FFFF等Errcode: F…!不是停止理由rules.md仅当参考代码缺失、golden 无法等价归一、框架根本性阻塞集成形式、缺少必要运行时日志或继续推进等于盲猜时才允许暂停Stop Conditionsrules.md。结语principles.md 虽然篇幅精炼却是整个 PyPTO 多智能体开发流水线的行为基石。Simplicity First 控制写入的量Surgical Changes 控制修改的面Goal-Driven Execution 控制验证的锚——三条原则与 rules.md 的强制规则、lint-gate-rules.md 的 OL 门禁、agents.md 的派发契约共同构成了少写、少改、可验证的完整工程闭环。理解这三条原则也就理解了 pypto-op-orchestrator 团队何以能够以可重复、可审计的方式把自然语言算子需求逐步推进为通过全输出精度验证的 PyPTO kernel 交付物。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考