ln-814-optimization-executor

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-814-optimization-executor

类型： L3 Worker
类别： 8XX Optimization

使用保留／丢弃自动研究循环执行研究者提出的优化假设。支持多文件更改、复合基线，以及任意类型的优化（算法、架构、查询、缓存、批处理）。

---

概述

方面	详情
输入	.hex-skills/optimization/{slug}/context.md 或对话上下文（独立调用）
输出	隔离分支上的优化代码、各假设的结果、实验日志
模式	先发制人：全部应用 → 测试 → 测量。仅在失败时二分排查。只有备选方案存在争议时才进行 A/B 测试

---

工作流

阶段： 预检 → 基线 → 先发制人执行 → 报告 → 差距分析

---

阶段 0：预检

Slug 解析

• 如果通过携带 slug 的 Agent 和 contextStore 调用 — 直接使用。
• 如果独立调用 — 根据 context_file 路径推导 slug，或询问用户。

步骤 1：加载上下文

从项目根目录读取 .hex-skills/optimization/{slug}/context.md。文件包含问题陈述、性能分析结果、研究假设和目标指标。

如果未找到文件：检查对话上下文中是否包含相同数据（独立调用）。

步骤 2：预检验证

检查项	必需	缺失时的操作
提供了假设（H1..H7）	是	阻止 — 无内容可执行
测试基础设施	是	阻止（参见 ci_tool_detection.md）
Git 工作区干净	是	阻止（需要干净的基线以便还原）
Worktree 隔离	是	按 git_worktree_fallback.md 创建
E2E 安全测试	否（建议）	从上下文读取；如果为 null 则发出警告 — 以完整测试套件作为备用门槛

必须读取： 加载 references/git_worktree_fallback.md — 使用优化相关条目。
必须读取： 加载 references/ci_tool_detection.md — 使用 Test Frameworks 和 Benchmarks 部分。

工具策略：遵循宿主 AGENTS.md 中的 MCP 偏好；仅当宿主策略缺失或 MCP 行为不明确时，才加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md。

在此 Worker 中，将 hex-line 作为代码／配置／脚本编辑的主要路径。性能分析器和基准测试是权威依据；此处不要将 hex-graph 视为运行时证据。

E2E 安全测试

从上下文文件中读取 e2e_test_command（由性能分析器在测试发现阶段找到）。

来源	操作
上下文中有 e2e_test_command	在阶段 2 中将其用作功能安全门槛
上下文中 e2e_test_command = null	警告：以完整测试套件作为备用门槛
独立调用（无上下文）	用户必须提供测试命令；缺失时阻止

---

阶段 1：建立基线

复用性能映射中的基线（已使用真实指标进行测量）。

来自上下文文件

从 .hex-skills/optimization/{slug}/context.md 中读取 performance_map.baseline 和 performance_map.test_command。

字段	来源
test_command	已发现／创建的测试命令
baseline	多指标快照：墙钟时间、CPU、内存、I/O

验证运行

运行一次 test_command，确认基线仍然有效（自性能分析后代码未变）：

步骤	操作
1	运行 test_command
2	如果结果与 baseline.wall_time_ms 相差在 10% 以内 → 确认基线
3	如果结果偏差 > 10% → 重新测量（运行 3 次，取中位数）作为新基线
4	如果测试失败 → 阻止：“未修改的代码测试失败”

---

阶段 2：先发制人执行

必须读取： 在实施过程中加载 optimization_categories.md 作为模式参考。

一次应用尽可能多的更改。只有当不同来源对实现方法确实意见不一时，才退而进行 A/B 测试。

第 1 步：梳理假设

将研究人员提出的假设分为两组：

分组	标准	操作
无争议	最佳方案明确，没有相互冲突的备选方案	在 strike 中直接应用
有争议	存在多种方案（例如，来源 A 建议缓存，来源 B 建议批处理），或与其他假设的 conflicts_with 字段冲突	在完整实现的基础上，对每种备选方案进行 A/B 测试

大多数假设应当是无争议的——研究人员已经根据证据为它们排定优先级。

第 2 步：Strike（应用所有无争议项）

1. APPLY all uncontested hypotheses at once (all file edits)
2. VERIFY: Run full test suite
   IF tests FAIL:
     - IF fixable (typo, missing import) → fix & re-run ONCE
     - IF fundamental → BISECT (see Step 4)
3. E2E GATE (if e2e_test_command not null):
   IF FAIL → BISECT
4. MEASURE: 5 runs, median
5. COMPARE: improvement vs baseline
   IF improvement meets target → DONE. Commit all:
     git add {all_files}
     git commit -m "perf: apply optimizations H1,H2,H3,... (+{improvement}%)"
   IF no improvement → BISECT

第 3 步：测试有争议的备选方案（在 strike 的基础上进行 A/B 测试）

对于每一组有争议的假设，在已应用所有无争议更改的基础上：

FOR each contested hypothesis group:
  1. Apply alternative A → test → measure (5 runs, median)
  2. Revert alternative A, apply alternative B → test → measure
  3. KEEP the winner. Commit.
  4. Winner becomes part of the baseline for next contested group.

第 4 步：二分排查（仅在 strike 失败时）

如果 strike 未通过测试或未显示出改进：

1. Revert all changes: git checkout -- . && git clean -fd
2. Binary search: apply first half of hypotheses → test
   - IF passes → problem in second half
   - IF fails → problem in first half
3. Narrow down to the breaking hypothesis
4. Remove it from strike, re-apply remaining → test → measure
5. Log removed hypothesis with reason

范围规则

规则	说明
文件范围	允许修改多个文件（不限于单个函数）
签名更改	只要测试仍能通过，即可进行
新文件	允许（缓存包装器、批处理适配器、工具程序）
新依赖项	如果已属于项目生态系统，则允许（例如使用已配置的 Redis）
时间预算	总计 45 分钟

还原协议

范围	命令
完整还原	git checkout -- . && git clean -fd（在工作树中安全）
单个假设	git checkout -- {files}（仅在二分排查期间）

安全规则

规则	说明
可追溯性	提交消息列出所有已应用的假设 ID
隔离	所有工作都在隔离的工作树中进行；绝不修改主工作树
仅在失败时进行二分排查	除非 strike 失败或备选方案确实冲突，否则不要单独测试各项假设
崩溃排查	运行时崩溃 → 如果修复很简单（拼写错误、导入错误），则修复一次；否则进行二分排查以找出原因

停止条件（执行循环）

条件	操作
Strike 通过 + 改进达到目标	停止 — 提交并继续撰写报告
所有有争议的备选方案均已测试	停止 — 提交最佳方案并继续撰写报告
二分排查移除了所有假设	停止 — 使用性能分析数据报告“所有假设均失败”
超出时间预算（45 分钟）	停止 — 报告部分结果及剩余假设
strike 和二分排查后所有测试仍失败	停止 — 完整还原，仅报告诊断价值

---

第 3 阶段：报告结果

报告架构

字段	说明
baseline	原始测量值（指标 + 数值）
final	优化后的最终测量值
total_improvement_pct	总体改进百分比
target_met	布尔值 — 是否达到目标指标？
strike_result	clean（全部应用）/ bisected（部分移除）/ failed
hypotheses_applied	strike 中应用的假设 ID 列表
hypotheses_removed	二分排查期间移除的假设（附原因）
contested_results	每组有争议假设的结果：已测试的备选方案、胜出方案、测量结果
branch	工作树分支名称
files_modified	所有已更改的文件
e2e_test	{ command, source, baseline_passed, final_passed } 或 null

结果对比（必填）

展示 performance_map.baseline 中每项指标的基线值与最终值。包含百分比和倍数。

| Metric | Baseline | After Strike | Improvement |
|--------|----------|-------------|-------------|
| Wall time | 7280ms | 3800ms | 47.8% (1.9x) |
| CPU time | 850ms | 720ms | 15.3% (1.2x) |
| Memory peak | 256MB | 245MB | 4.3% |
| HTTP round-trips | 13 | 2 | 84.6% (6.5x) |

Target: 5000ms → Achieved: 3800ms ✓ TARGET MET

函数级变化（如果有检测数据）

如果上下文中的 instrumented_files 非空，则在 strike 后再运行一次 test_command，使用性能分析器添加的相同检测代码，捕获各函数耗时：

| Function | Before (ms) | After (ms) | Delta |
|----------|------------|------------|-------|
| mt_translate | 3500 | 450 | -87% (7.8x) |
| tikal_extract | 2800 | 2800 | 0% (unchanged) |

然后清理：git checkout -- {instrumented_files} — 在最终提交前移除所有性能分析检测代码。

向用户展示这两张表。这是主要交付内容——用户首先看到的是这些数字。

实验日志

写入 {project_root}/.hex-skills/optimization/{slug}/ln-814-log.tsv：

列	描述
timestamp	ISO 8601
phase	strike / bisect / contested
hypotheses	本轮应用的假设 ID，以逗号分隔
baseline_ms	本轮开始前的基线值
result_ms	更改后的测量结果
improvement_pct	变化百分比
status	applied / removed / alternative_a / alternative_b
commit	Git 提交哈希
files	已修改文件，以逗号分隔
e2e_status	pass / fail / skipped

如果文件已存在，则追加内容（以便跨多次运行跟踪）。

---

第 4 阶段：差距分析（未达到目标时）

如果所有假设都已测试后仍未达到目标指标：

部分	内容
Achievement	已取得的成果（原始值 → 最终值，改进百分比）
Remaining bottlenecks	来自时间图：哪些步骤仍占主导
Remaining cycles	如果协调器运行多个周期："{remaining} optimization cycles available for remaining bottlenecks"
Infrastructure recommendations	如果瓶颈需要基础设施变更（扩缩容、缓存层、CDN）
Further research	本次运行中未探索的优化方向

---

错误处理

错误	恢复方法
Strike 未通过所有测试	通过二分查找找出导致失败的假设，移除后重试
Strike 未显示任何改进	通过二分查找找出无效假设
测量结果不一致（方差较大）	将运行次数增至 10 次，并使用中位数
创建 Worktree 失败	按 git_worktree_fallback.md 回退到按分支操作
超出时间预算	停止循环，报告部分结果及剩余假设
多文件还原失败	在 worktree 中运行 git checkout -- .（安全——worktree 相互隔离）

---

参考资料

• optimization_categories.md — 优化模式检查清单
• references/ci_tool_detection.md（测试 + 基准检测）
• references/git_worktree_fallback.md（worktree 隔离）

---

运行时摘要产物

必须阅读： 加载 references/coordinator_summary_contract.md

输出一个 optimization-worker 摘要信封。

托管模式：

• ln-810 会传入确定性的 runId 和精确的 summaryArtifactPath
• 将摘要写入提供的 summaryArtifactPath

独立模式：

• 省略 runId 和 summaryArtifactPath
• 写入 .hex-skills/runtime-artifacts/runs/{run_id}/optimization-worker/ln-814--{identifier}.json

Monitor 集成（Claude Code 2.1.98+）

必须阅读： 加载 references/monitor_integration_pattern.md

在多轮优化周期（基线 + A/B）中： Monitor(command="{test_command} 2>&1 | grep --line-buffered -E 'run|result|error|FAIL'", timeout_ms=600000, description="optimization run")

回退方案：如果 Monitor 不可用，则使用 Bash(run_in_background=true)。

完成标准

• 使用与观察到的问题相同的指标类型建立基线
• 对假设进行分类：无争议与有争议
• 执行 Strike：一次性实现所有无争议的假设
• Strike 后测试通过
• 在完整实现的基础上测试有争议的备选方案 A/B
• 仅当 Strike 失败时才执行二分查找（不提前执行）
• E2E 安全测试通过（或记录为不可用）
• 将实验日志写入 .hex-skills/optimization/{slug}/ln-814-log.tsv
• 返回报告，包含基线、最终值、改进百分比和 Strike 结果
• 所有更改均位于隔离分支，并已推送到远程
• 未达到目标指标时提供差距分析
• 将优化执行产物写入共享位置

---

版本： 2.0.0 最后更新： 2026-03-14