ln-811-algorithm-optimizer

路径： 文件路径（shared/、references/、../ln-*）均相对于 skills 仓库根目录。如果在 CWD 中未找到，请定位此 SKILL.md 目录，并向上一级查找仓库根目录。

ln-811-algorithm-optimizer

类型： L3 Worker 类别： 8XX 优化 上级： ln-810-performance-optimization-coordinator

通过 autoresearch 循环优化目标函数性能：建立基准测试、研究最佳实践、生成 3-7 个假设，并逐一应用且验证保留或舍弃。

---

概述

方面	详情
输入	target_file + target_function（或来自 ln-650 的审计发现）
输出	经基准测试证明的优化函数、优化报告
模式	Autoresearch：修改 → 基准测试 → 保留（≥10%）/ 舍弃

---

工作流

阶段： 预检 → 基准线 → 研究 → 提出假设 → 优化循环 → 报告

---

阶段 0：预检

检查项	必需	缺失时的操作
目标文件存在	是	阻止优化
可识别目标函数	是	阻止优化
测试基础设施	是	阻止优化（参见 ci_tool_detection.md）
目标函数的测试覆盖率	是	阻止——没有覆盖率就没有安全保障
Git 工作区干净	是	阻止（需要干净的基准线以便回滚）
基准测试基础设施	否	生成基准测试（参见 references）

必须阅读： 加载 shared/references/ci_tool_detection.md——使用 Benchmarks 和 Test Frameworks 部分。

覆盖率验证

开始优化前，请验证目标函数有测试覆盖：

步骤	操作
1	Grep 测试文件，查找目标函数名称 / 从目标模块导入的内容
2	如果 ≥1 个测试引用目标 → 继续
3	如果 0 个测试引用目标 → 阻止，并提示“no test coverage for {function}”

没有测试覆盖率，基准测试的改进就毫无意义——优化后的函数可能只是更快地产生错误结果。

Worktree 与分支隔离

必须阅读： 加载 shared/references/git_worktree_fallback.md——使用 ln-811 行。

所有工作（编辑、基准测试、KEEP 提交）都必须在 worktree 中进行。切勿修改主 worktree。

---

阶段 1：建立基准线

步骤 1.1：检测或生成基准测试

情况	操作
找到现有基准测试	按原样使用
不存在基准测试	生成最小基准测试（参见 benchmark_generation.md）

步骤 1.2：运行基准线

参数	值
运行次数	5
指标	执行时间中位数
预热	丢弃 1 次运行
输出	baseline_median、baseline_p95

保存基准线结果——所有改进都以此为基准进行衡量。

---

阶段 2：研究最佳实践

必须阅读： 加载 shared/references/research_tool_fallback.md 以了解 MCP 工具链。

研究策略

优先级	工具	查询模板
1	mcp__context7__query-docs	"{language} {algorithm_type} optimization techniques"
2	mcp__Ref__ref_search_documentation	"{language} {function_name} performance best practices"
3	WebSearch	"{algorithm_type} optimization {language} benchmark {current_year}"

研究成果

收集适用于目标函数的优化技术。对每种技术记录：

• 名称和描述
• 预期改进类别（算法复杂度、内存、缓存、并行性）
• 适用条件（数据大小、结构、语言特性）

---

阶段 3：生成假设（3-7 个）

假设来源

必须阅读： 加载 optimization_categories.md 以获取类别检查清单。

来源	优先级
研究发现（阶段 2）	1
优化类别检查清单	2
代码分析（目标代码中的反模式）	3

假设格式

字段	描述
id	H1、H2、...、H7
category	来自 optimization_categories.md
description	要更改的内容
expected_impact	预估提升百分比
risk	低 / 中 / 高
dependencies	此假设依赖的其他假设

排序

按以下顺序排序：expected_impact DESC, risk ASC。优先列出独立假设（无依赖项）。

---

第 4 阶段：优化循环（保留/舍弃）

每个假设的循环

FOR each hypothesis (H1..H7):
  1. APPLY: Edit target function (surgical change, function body only)
  2. VERIFY: Run tests
     IF tests FAIL (assertion) → DISCARD (revert) → next hypothesis
     IF tests CRASH (runtime error, OOM, import error):
       IF fixable (typo, missing import) → fix & re-run ONCE
       IF fundamental (design flaw, incompatible API) → DISCARD + log "crash: {reason}"
  3. BENCHMARK: Run 5 times, take median
  4. COMPARE: improvement = (baseline - new) / baseline * 100
     IF improvement >= 10% → KEEP:
       git add {target_file}
       git commit -m "perf(H{N}): {description} (+{improvement}%)"
       new baseline = new median
     IF improvement < 10%  → DISCARD (revert edit)
  5. LOG: Record result to experiment log + report

安全规则

规则	描述
范围	仅针对目标函数体；不更改签名
依赖项	不安装新软件包
回退	舍弃时执行 git checkout -- {target_file}
时间预算	所有假设总计 30 分钟
复合优化	每个保留的优化都会成为下一个假设的新基线
可追溯性	每个保留的优化都要单独提交 git，提交消息中包含假设 ID
隔离	所有工作都在隔离的 worktree 中进行；绝不修改主 worktree

保留/舍弃决策

条件	决策	操作
测试失败	DISCARD	回退，记录原因
提升 ≥ 10%	KEEP	更新基线
提升 10–20%，但复杂度增加	REVIEW	记录为“提升有限且复杂”，优先选择 DISCARD
提升 < 10%	DISCARD	回退，记录为“收益不足”
性能回退（变慢）	DISCARD	回退，记录回退幅度

简洁性标准（依据 autoresearch）： 如果提升有限（10–20%），且更改显著增加了代码复杂度（行数增加超过 50%、逻辑嵌套层级很深或结构难以阅读），则优先选择 DISCARD。性能相近时，选择更简洁的代码。

---

第 5 阶段：报告结果

报告结构

字段	描述
target	文件路径 + 函数名称
baseline	原始中位数基准测试结果
final	保留所有优化后的最终中位数
total_improvement	提升百分比
hypotheses_tested	假设总数
hypotheses_kept	保留的优化数量
hypotheses_discarded	数量 + 原因
optimizations[]	每项保留的优化：id、category、description、improvement%

实验日志

写入 {project_root}/.optimization/ln-811-log.tsv：

列	描述
timestamp	ISO 8601
hypothesis_id	H1..H7
category	来自 optimization_categories.md
description	更改内容
baseline_ms	此假设之前的基线中位数
result_ms	更改后的新中位数
improvement_pct	变化百分比
status	keep / discard / crash
commit	Git 提交哈希（若保留）

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

清理

操作	条件
移除生成的基准测试	基准测试为自动生成，且没有保留任何优化时
保留生成的基准测试	保留了任何优化时（作为改进的证明）

---

配置

Options:
  # Target
  target_file: ""
  target_function: ""

  # Benchmark
  benchmark_runs: 5
  improvement_threshold: 10    # percent
  warmup_runs: 1

  # Hypotheses
  max_hypotheses: 7
  min_hypotheses: 3

  # Safety
  time_budget_minutes: 30
  allow_new_deps: false
  scope: "function_body"       # function_body | module

  # Verification
  run_tests: true
  run_lint: false

---

错误处理

错误	原因	解决方案
没有基准测试框架	ci_tool_detection.md 中没有对应的技术栈	生成内联基准测试
所有假设均被舍弃	未发现有效优化	报告“未发现改进”
基准测试噪声过大	计时不一致	将运行次数增加到 10 次，使用 p50
测试偶发失败	测试不确定	重新运行一次；若再次偶发失败，则跳过该假设

---

参考资料

• benchmark_generation.md
• optimization_categories.md
• shared/references/ci_tool_detection.md（基准测试部分）
• shared/references/research_tool_fallback.md

---

完成标准

• 优化前验证目标函数的测试覆盖率
• 确定目标函数并建立基准测试结果（运行 5 次，取中位数）
• 通过 MCP 工具链（Context7/Ref/WebSearch）完成调研
• 提出 3-7 个假设，并按预期影响排序
• 测试每个假设：应用 → 测试 → 基准测试 → 保留/舍弃
• 每项保留的优化都单独提交一次 git commit，并附上假设 ID
• 保留的优化逐步累积（每项都会成为新的基准）
• 对增益较小（10-20%）但增加复杂度的优化，依据简洁性标准进行审查
• 所有保留优化完成后，测试均通过
• 将实验日志写入 .optimization/ln-811-log.tsv
• 返回包含基准值、最终值、改进百分比和各假设结果的报告
• 如果没有保留任何优化，则清理生成的基准测试
• 所有更改均在隔离分支上，并已推送到远程

---

版本： 1.0.0 最后更新： 2026-03-08