企业官网建设流程全解析

PyPTO-Gym 深度编排 Stage 5 性能优化子代理：pypto-pro-op-optimizer 的边界、执行与交接规范

【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym

本文围绕 CANN / PyPTO-Gym 仓库中 PyPTO-Pro 算子深度编排（Stage 1–5）流程的最后一个环节展开：pypto-pro-op-optimizer子代理如何对通过stage4-check的算子执行 Stage 5 性能优化，如何严守代理边界、按唯一规范pypto-pro-op-perf-tune执行优化闭环，并向编排器（orchestrator）完成可复核的 Handoff 交接。读完本文，你将掌握 Stage 5 的输入/冻结合同、优化项来源与实验闭环、异常阻断分类（env_error/stage5_contract_blocked）以及最终交付物清单，并理解该子代理与 verifier、coder 等其他角色在五阶段流水线中的职责划分。

一、Stage 5 在 PyPTO-Pro 深度编排中的位置

PyPTO-Gym 的pypto-pro-op-orchestrator插件提供了一条完整的 PyPTO-Pro 算子开发流水线：Stage 1 需求规划（planner）、Stage 2 Golden 生成（mathematician）、Stage 3 架构设计（architect）、Stage 4 Kernel 实现与验证（coder）、Stage 5 性能优化（optimizer），每个 Stage 结束由 verifier 独立验收。调度关系定义在 orchestration.md 的子代理调度协议中：

与pypto-pro-op-coder（Stage 4，coder 边界文档）、pypto-pro-op-verifier（门禁裁判，verifier 边界文档）一样，pypto-pro-op-optimizer.md 既是子代理的 system prompt，也是角色边界与全局硬性规则的载体。orchestrator 只负责调度与决策，从不亲自调优或改码；优化动作全部由 optimizer 执行，质量把关由 verifier 的stage5-check完成。

需要特别强调的是：进入 Stage 5 之前有一个"进入确认"门。Stage 4 通过后默认不直接开始 Stage 5，编排器需先确认用户已明确要求性能优化（或用户授权自主执行），并冻结本轮目标 case（optimization_target.case_ids与selection_mode），之后才能调度 optimizer。因此，optimizer 的每一次出场，都意味着：正确性已通过、目标 case 已冻结、性能合同已就绪。

二、代理边界：能做什么，绝对不能做什么

原文档用"代理边界"一节划定了 optimizer 的活动范围。这些约束是 Stage 5 可信度的根基——性能优化必须不改变任何合同、不伪造任何证据。

2.1 环境不可变（禁止改变会话环境）

除按pypto-pro-docs-search传递既定资料路径外，optimizer禁止改变会话环境，包括但不限于conda activate、source set_env.sh、export、pip install。这是所有子代理共用的硬性规则。环境异常时，正确做法是：

1. 加载pypto-pro-environment-check取证；
2. 返回env_error类别给编排器；
3. 不得自行修复环境，也不得伪造性能结论。

编排器收到env_error后按统一环境分流：硬件问题换卡重新调度，软件问题停机向用户反馈。

2.2 状态机独占（禁止触碰 Stage 状态）

• 禁止调用state_transition工具；
• 禁止读写或创建.orchestrator_state.json；
• 禁止维护其它 Stage 的状态。

.orchestrator_state.json是机器可读的进度账本（Stage 状态、重试计数、artifact 哈希、回滚历史），只有编排器能通过state_transition抽象合同写入。子代理只返回结果，由编排器推进 Stage。

2.3 不得越权调度与回退

optimizer 不得：

• 自行调度 verifier；
• 推进 Stage；
• 请求或执行rollback_to_stage；
• 把 Stage 5 内可修复的问题交回 Stage 1–4。

这一条与编排器的 Stage 5 专节设计互为表里：进入 Stage 5 后，编排流程不再允许跨 Stage 回退（rollback_to_stage仅供 Stage 1–4 使用）。Stage 5 的问题只能在 Stage 5 内部按原始证据定点修复。这与 Stage 4 不同——Stage 4 的 coder 可以按failure_category触发回退 Stage 1/2/3，而 Stage 5 的所有问题都被约束在自身阶段内收敛。

2.4 冻结输入与可更新边界（防"改口径加速"）

冻结输入、Stage 4 铁律、允许更新的源码与事实记录、生成物只读边界，完全遵循 perf Skill（即pypto-pro-op-perf-tune）。明确禁止：

• 通过改规格、case、输入、精度或计时口径制造加速。

这条红线直接对应 verifier 的反作弊门禁与performance_evidence_invalid分类：baseline/final 必须同协议可复算，禁止把单一聚合时延复制给多个 case，禁止拼接改码前后的证据。冻结内容的完整清单在 perf Skill 中有详细列举，包括 SPEC 数学语义、Golden、KB_SELECTION.json、module_interfaces.yaml、PERFORMANCE_CASES.json以及设备/seed/warm-up/repeats/Op Name/计时范围等（详见下文第四节）。

三、输入与执行：以 perf Skill 为唯一规范

3.1 调度目标与读取要求

调度目标位于custom/<op>/。optimizer 必须完整执行perf Skill 的"开始前读取"和按需路由，不得用 Stage 4 摘要或事实记录代替直接读取权威输入——这是防止"二手信息失真"的关键设计。

3.2 必需输入清单（必读，不可跳过）

本工作流的必需输入为：

• SPEC（算子规格，含数学语义、I/O、支持范围、精度、输入分布、性能 case 与用户目标）；
• 两份数学 Golden（{op}_golden.py与{op}_golden_cpu.py，后者为 CPU FP32 精度对照）；
• EXPLORE_REPORT（资料探索报告）；
• PRO_MATERIAL_INDEX（资料索引）；
• MEMORY（记忆/裁定记录）；
• DESIGN（设计文档）、DESIGN_BINDINGS（结构化 KB requirements）、module_interfaces（Module 契约）；
• 最终测试及全部 P0（性能 case）；
• 各 class 的 KB_SELECTION、已选参考和 KB_USAGE；
• $CANNBOT_CONFIG_ROOT/references/performance-constraints.md（即仓库中的 performance-constraints.md，定义两条性能强制：buffer 管理用make_tile_group+auto_mutex，Vector 数值计算默认使用 VF）。

这些输入按 perf Skill 的冻结/可更新边界处理，不能套用 perf Skill 独立使用时的"可选资料"分支跳过——在深度编排场景下，上述资料全部是权威输入，缺失即合同问题。

3.3 目标 case 的权威性与 manifest 写入

目标 case 与选择方式必须由 dispatch 预先给定并原样写入 manifest；缺失或不合法时立即返回调用方补齐，不自行重选或二次提问。

这对应 evidence-protocol.md 中PERFORMANCE_CASES.json的契约：cases覆盖全部性能 P0，optimization_target.case_ids是非空、无重复的 P0 子集，selection_mode取user_selected/single_p0/all_p0_no_questions三者之一。目标 case 只决定候选排名，全部 P0 无论是否入选，仍须完成正确性、baseline/final、时间线与逐 case 披露。这就是"不能通过挑选 case 制造加速"的机制保证。

3.4 执行流程与 Verifier FAIL 的处理

随后完整执行 perf Skill，不在本文件另建一套 Stage 5 流程、字段或验收规则。perf Skill（SKILL.md）定义的主流程为：

1. 确认输入与正确性（重跑完整正确性 + JIT/编译预热）；
2. 冻结执行合同（生成PERFORMANCE_CASES.json，确认optimization_target）；
3. 建立来源覆盖账本（五类优化项来源）；
4. 建立正式 baseline（按 manifest 逐 case、逐 repeat 采集七指标）；
5. 分析瓶颈并排序（Roofline、Vector/Cube/Scalar/MTE、分层带宽等）；
6. 闭合预置来源（kb_selected → general_method → knowledge_card → template）；
7. 进入自主优化（bottleneck_derived，前四类全部闭合后）；
8. 闭合与停止（final candidate sweep、最佳版本选择）；
9. 同步最终事实（更新 DESIGN/BINDINGS/KB_USAGE 的 as-built 记录）；
10. 最终验收（完整正确性 + 独立 final formal compare + 逐 P0 补充 timeline）。

Verifier 返回 FAIL 时，optimizer 在 Stage 5 内按原始证据定点修复，并重新执行该 Skill 要求的受影响验证和最终验收。注意编排器分流表中明确：precision_failure、runtime_failure、cheating、perf_violation等类别一律保持 Stage 5in_progress，把原始证据交 optimizer 在当前 Stage 恢复最近正确合规版本、修复代码或同步 as-built 记录并重验——不得以性能收益豁免铁律，不重派 coder/architect。

四、冻结合同与阻断分类

4.1 冻结/可更新边界

perf Skill 明确"始终冻结"的内容包括：SPEC 数学语义、I/O、支持范围、P0、输入分布、精度门与用户目标；Golden 数学实现与完整正确性测试语义；KB_SELECTION.json的选择/引用/理由/哈希；module_interfaces.yaml、staged Module、公开 wrapper 的 callable/签名/I/O/optional 语义与 host 边界合同；PERFORMANCE_CASES.json及其目标 case；以及设备、seed、warm-up、repeats、精确 Op Name 和计时范围（首次正式采集前冻结，baseline 与 Golden 合同生成后不再修改）。

可以更新的只有：最终test_{op}.py、性能交付物，以及为匹配最终接受实现所必需的DESIGN.md、DESIGN_BINDINGS.json和KB_USAGE.json（按各自 owner schema 同步最终 as-built 事实）。事实记录不得删除、降级或改写已选 KB 义务，不得用文档修改掩盖代码未落实，未接受的实验不能写成最终事实。

4.2 三类异常出口

optimizer 的返回结果必须明确区分三种情况：

关键判定规则（原文明确，值得细读）：

• 不得猜测、重建冻结输入或回退上游规避——这是与 Stage 1–4 最大的不同；
• 性能目标差距和残留瓶颈只用于发现、排序候选；全部来源、候选与 final sweep 合法闭合后，性能目标未达不构成阻断。也就是说，"目标未达"不是失败出口，证据缺失或矛盾才是；
• 冻结 SPEC 中的用户目标定义本身矛盾或不可复算 → 属于stage5_contract_blocked；
• 目标定义有效后，Stage 5 Golden 或测量证据矛盾、不可复算 → 属于待修复的性能证据错误（对应 verifier 的performance_evidence_invalid，交 optimizer 补采或纠正）；
• 用户未给数值目标且性能 Golden 合同不存在时，可如实披露"参考不可用"（unavailable），但不能把该结论升级为失败类型。

4.3 五类优化项来源

optimization-playbook.md 把优化项严格限定为五类，按顺序处理，每项都必须登记、实验、关闭：

1. kb_selected：已选 KB 中kind=obligation的未落实原子要求（前提触发但代码未落实的缺口必须真实落实，不能因无性能收益而拒绝）；
2. general_method：通用优化手段索引中的 active/eligible 原子项；
3. knowledge_card：知识卡片索引 Active 表中的条目（不扫描目录）；
4. template：模板优化项索引中的 active/eligible 项（模板只是骨架，采用前必须按当前代码适配并重新证明正确性、机制和性能）；
5. bottleneck_derived：前四类全部闭合后，根据当前接受实现的 profiler/源码/生成物/Tile DAG 证据提出的自主项（必须指向尚未尝试的具体瓶颈、与预置项去重、用新鲜分析支撑）。

实验闭环的核心纪律是：每次只改一个优化点 → 跑完整正确性 → quick 筛选 → 必要时 formal compare → 机制核对 → 接受或恢复 → 写回账本。rejected必须记录具体原因并恢复代码。账本字段含item_id/source_kind/source_ref/case_scope/applicability/expected_metric/status/evidence/relations。

4.4 baseline、测量协议与最佳版本选择

• 正式 baseline 前先做一次discovery profile确认真实 lowering Op Name（runner 只选一个已知 case、只 launch 一次 target kernel），之后才能把精确字符串传给正式 compare；
• 测量固定seed=42（manifest 协议），baseline 与 final 保持同一输入生成方式；warm-up/repeats 冻结；
• quick 只用于候选筛选，不能充当正式交付证据；正式 baseline/final 必须按 manifest 逐 case 各自完成一整套 compare（msprof 指南）；
• 无用户数值目标时，用collect_golden_reference.py冻结一次 Golden 理想参考（golden_reference_ratio只描述理想参考是否达到，不是 optimization speedup，也不是完成门禁）；
• 最佳版本选择规则（playbook 第 6 节）：在所有完成 formal compare 的正确、合规候选中，选择冻结聚合指标最优的版本。默认算法对目标 case 逐项计算case_speedup = frozen_baseline_duration / candidate_duration，取等权算术平均；并列时先以原始最高分为锚选出不可稳定区分的候选，再取顺序最小者。晋级规则、稳定性范围和并列规则不得在看到结果后修改。

五、Handoff：交付可独立复核的证据

执行到 perf Skill 允许的闭环完成或阻断交接点后，optimizer 向 orchestrator 返回结果。闭环完成结果应包含可供stage5-check独立复核的交付物和证据，具体包括：

1. 完整正确性与性能命令、退出码和逐 P0 结论——verifier 必须能重跑这些命令获得一致结果；
2. perf Skill 规定的全部交付物及原始证据路径——即四件套：PERFORMANCE_REPORT.md、PERFORMANCE_CASES.json、performance.json/performance.log/perf_report.md，以及docs/perf/round_NNN/归档（baseline/final 原始 CSV、measurement/collection 与逐 case timeline）；
3. 逐 case baseline/final、理想目标状态、性能终态与残留瓶颈摘要；
4. 来源覆盖账本、自主优化阶段、final candidate sweep、零未决状态及可复算的最佳版本选择证据；
5. 最终代码和事实记录修改（test_{op}.py及同步的 DESIGN/BINDINGS/KB_USAGE）；
6. 明确区分闭环完成、env_error与stage5_contract_blocked，并附相应原始根因和证据；闭环完成时始终如实披露目标是否达到；默认 Golden 分支还可披露参考不可用，但不把这些结论升级为失败类型。

5.1 与 stage5-check 的对接

orchestrator 收到 optimizer 结果后，调度 verifier 执行stage5-check（传入同一optimization_target.case_ids/selection_mode）。verifier 会先完整重跑 Stage 4 的 15 项门禁（import 门禁、单 kernel、未作弊、wrapper 边界、交付态 import 安全等），再核验 P1–P8 八项性能门禁：

• P1 文件完整性（四件套存在且非空）；
• P2 基线一致（manifest 覆盖每个 P0、optimization_target与调度输入一致、逐 case baseline/final）；
• P3 采集证据（baseline/final 是两次独立 formal compare，原始 CSV 与报告可对应，最终实现executable_sha256一致）；
• P4 数值可比且可复算（speedup 逐 case 独立复算）；
• P5 正确性无退化（最终代码实际执行 PASS）；
• P6 性能目标复算与披露（Golden 合同由collect_golden_reference.py在 baseline 前冻结）；
• P7 优化项与最佳版本闭合（独立重新枚举来源、核对账本、复算排名）；
• P8 Roofline、Scalar 与流水诊断（每个 P0 均有结构化roofline_terminal/pipeline_evidence/scalar_evidence）。

这八项全部 PASS 后，orchestrator 调用complete_stage(5)完成整个工作流；目标未达、默认 Golden 参考不可用或残留非理想瓶颈不改变该动作——这是五阶段流水线的"性能优化可交付"语义：优化必须真实、合规、可复算，但"是否达到理想目标"不作为完成门禁。

六、角色对比：optimizer 与 coder、verifier 的分工

为帮助理解 optimizer 在流水线中的独特位置，下表对照三个子代理的核心职责：

三者共同构成"实现→优化→验收"的闭环，而 optimizer 处于"优化"这一环，其输出质量直接决定stage5-check能否通过。

七、最佳实践小结

综合原文档与配套资料，Stage 5 optimizer 的高质量执行可归纳为以下要点：

1. 输入至上：直接读取权威输入（SPEC/Golden/DESIGN/KB 系列），不依赖 Stage 4 摘要转述；
2. 合同敬畏：目标 case 原样写入 manifest，冻结输入缺失即返回stage5_contract_blocked，绝不猜测重建；
3. 证据纪律：所有采集走 manifest 协议（seed=42、逐 case compare、同协议 baseline/final），quick 只筛选不交付；
4. 来源闭合：五类优化项按序登记实验，账本零未决状态后才进入 final sweep；
5. 诚实披露：目标是否达到、Golden 参考是否可用、残留瓶颈是什么，全部如实写入手报告与交付物，供 verifier 独立复核。

通过这套机制，PyPTO-Gym 的 Stage 5 把"性能优化"从主观尝试变成了有冻结合同、有来源账本、有可复算证据、有独立验收的工程流程。对于希望在 PyPTO-Pro 上交付可信性能结果的开发者而言，pypto-pro-op-optimizer的边界与交接规范本身就是一份可复用的性能调优工作纪律模板。

【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym