优化移交 (kernel-optimize) 是做什么的？
当目标是让内核逼近硬件极限（而非仅进行性能抽检）时，此文件是 Primus-Turbo 与自主优化循环（位于 ../../kernel-optimize/SKILL.md）之间的接口。它提供该循环所需的前提信息。请先阅读中心文件 ../SKILL.md。
流程
- 验证环境 —
pip show primus_turbo；如果未安装则重新以可编辑模式安装（参见中心SKILL.md→ 构建）。 - 阅读
kernel-optimize/SKILL.md的"前提信息"部分 — 了解优化循环需要什么。 - 收集目标操作的前提信息（下表 + 中心
SKILL.md中的代码映射/命令）。 - 移交给
kernel-optimize/SKILL.md；它将执行 DEFINE_TARGET → PREPARE_ENVIRONMENT → BASELINE → (ANALYZE → OPTIMIZE → VALIDATE)* → REPORT。 - 验收 — 回到项目中：运行 完整 套件
pytest tests/pytorch/ -v，审查报告，确认干净的差异/提交。
在优化循环开始之前，请先阅读 ../../../rules/iteration_rules.mdc：每轮一个假设，正确性门控先于性能，接受/回滚谱系，并且每个已接受的增益必须迁移到真实训练步骤中（禁止使用 id(...) 键控的 activation/grad_out 缓存，禁止仅使用均匀分布的 GroupGemm 快捷方式）。
前提信息（按操作）
| 要求 | 获取位置 |
|---|---|
| 内核源文件路径 | 中心 SKILL.md → 代码映射 |
| 聚焦测试命令 | 中心 SKILL.md → 测试与基准；例如 pytest tests/pytorch/ops/test_gemm_fp8.py -v -k "blockwise and TRITON" |
| 聚焦基准命令 | ../verify-performance/SKILL.md；例如 PRIMUS_TURBO_GEMM_BACKEND=TRITON python benchmark/ops/training/bench_gemm_turbo.py --dtype fp8 --granularity blockwise |
| 基准输出格式/指标 | ../verify-performance/SKILL.md（Forward/Backward TFLOPS，Check 门控） |
| 快速验证框架 | 下方的"快速验证" |
| 评分规则 | 下方的"优化评分" |
execution_mode + 重建 | 下方的"优化环境" |
优化环境
| 后端/语言 | 推荐的 execution_mode | 变更后重建 |
|---|---|---|
| Triton (Python) | repo-mode | 无（可编辑安装） |
| HIP / CK (C++)，小/参数变更 | repo-mode | GPU_ARCHS=<架构> pip install --no-build-isolation -e . -v |
| HIP / CK (C++)，新内核/大量试错 | workspace-mode | 按照 kernel-optimize/SKILL.md 中的最小栈 |
优化评分
Check 列是硬性门控——任何 FAIL/ERROR 形状都会拒绝该候选。
| 优化类型 | primary_metric（聚合 = 所有 PASS 形状的几何平均值） |
|---|---|
| 计算密集型，仅前向 | Forward TFLOPS |
| 计算密集型，前向+反向（训练） | Combined Step TFLOPS（前向/反向作为诊断保留） |
| 内存密集型（逐元素、量化） | Forward GB/s / Backward GB/s |
联合步骤推导（对于前向+反向 GEMM 类操作更优）详见 ../verify-performance/SKILL.md。在 DEFINE_TARGET 阶段与用户确认 primary_metric。
快速验证
两种工具，不同角色——不要跨工具比较绝对值（它们使用不同的计时引擎）：
quick_test_bench.py（此文件夹中，复制到优化目录内）是逐形状回归门控的权威来源，用于每轮比较。BASELINE（第一轮）和每一轮 VALIDATE 都运行此脚本，并比较其--summary-csv输出。它使用手写的time.perf_counter循环。- 完整的
bench_<op>_turbo.py（见../verify-performance/SKILL.md，torch.utils.benchmark.Timer）仅用于 (i) 从完整形状集中挑选representative_shapes，以及 (ii) 在优化结束后进行最终验收。
两个验证级别都通过 quick_test_bench.py 运行，仅在 SHAPES 上有所不同：
- 完整验证（BASELINE + 最终验收）→
SHAPES= 所有target_shapes。 - 快速验证（每一轮 VALIDATE）→
SHAPES= 3–5 个representative_shapes子集。
representative_shapes：仅包含来自 BASELINE 运行的 Check=PASS 形状，覆盖小规模（启动开销）和大规模（计算/内存）尺度，优先选择方差大的形状。记录在 manifest.yaml: representative_shapes 中。
框架： 模板 quick_test_bench.py 是权威参考。在 PREPARE_ENVIRONMENT 阶段，将其复制到 <campaign_dir>/quick_test_bench.py，设置 SHAPES 为空且 <target_backend> 为指定值；在 BASELINE 中将 SHAPES 填充为所有 target_shapes，然后在 VALIDATE 轮次中将其缩小为 representative_shapes。根据目标操作调整操作/配置；对于非 GEMM 操作，保留 --summary-csv 写入器和列架构（参见下面的架构范围注释）。
测量一致性合约： BASELINE（第一轮）和每一轮 VALIDATE 通过 --summary-csv 读取相同的权威 CSV，并使用同一 CSV 读取器在各轮之间进行解析——如果已配置，则使用可选的 mcp__turbo__parse_bench_csv MCP 辅助工具，否则使用基于以下列的直接 csv.DictReader。具体读取器无关紧要；冻结架构才是关键。架构必须逐字匹配以下列（任何偏差都会静默禁用逐形状回归门控）：
label,B,M,N,K,Check,Forward TFLOPS,Forward TFLOPS_stddev,Backward TFLOPS,Backward TFLOPS_stddev,Forward Time (ms),Backward Time (ms),out_snr,da_snr,db_snr
Check 使用 PASS / FAIL；*_stddev 是指标单位的绝对标准差。在 manifest.yaml 中记录调用命令为 quick_command: "python <campaign_dir>/quick_test_bench.py"；BASELINE 和每一轮 VALIDATE 都追加 --summary-csv <round_dir>/artifacts/benchmark.csv。
架构范围： 以上列是针对 GEMM 类特定的（M,N,K 维度，Forward/Backward TFLOPS，out_snr/da_snr/db_snr）。对于非 GEMM 操作，保留 label、Check 以及 *_stddev 约定，但将仅适用于 GEMM 的列替换为你的 primary_metric 所需的列——例如，内存密集型操作（参见"优化评分"）使用 Forward GB/s / Backward GB/s 而非 TFLOPS，而单输出操作将 out_snr/da_snr/db_snr 替换为自身的正确性度量。无论选择哪种架构，都应在 BASELINE 时冻结它，在所有轮次中保持字节相同，并更新你使用的 CSV 读取器（如果已配置，则更新 mcp__turbo__parse_bench_csv 映射，否则更新直接的 csv.DictReader）以匹配——逐形状回归门控依赖于确切的列名。