技术纲要与路线图：evolution-kernel 从 MVP 到灵魂插件

[Protocol-zero-0]

本 issue 是项目技术纲要，随开发进展持续更新。所有实现细节见各阶段对应的 issue/PR。

---

总目标："灵魂插件"

只要把这个系统装到任意目标 repo 并给出初始配置，它就能对目标代码持续不断地进化、观察，直到达到进化目标。如果目标设置得足够长远、约束条件足够宽松，系统就能持续改良这个代码仓库。

一句话定性：一个可以被信任地放着自己跑的、有记忆的、会自动停的、每一步都可回滚的、面向单一目标仓库的 AI 代码进化 runtime。

---

内核设计原则

这些原则在所有 PR 中保持不变：

1. 内核只路由智能，不嵌入智能（Unix 哲学）——kernel 本身不含 LLM，只负责调度角色
2. 角色是外部命令——planner / executor / evaluator 通过 JSON 文件 I/O 与 kernel 通信，可插拔替换，LLM 的选择由角色决定而非 kernel
3. 代码规模信念——~1000 行是心理锚点，好的机制内核应当简洁
4. 执行层要规划 + 检测每轮效果 + 辅助收敛——每轮不是盲目尝试，而是有记忆、有方向的改进
5. 复用现成 coding agent——executor 调用 Aider / Claude Code headless，不重造

---

闭环流程

config → observe → plan → execute → evaluate → accept/reject → ledger
                   ↑_________________history___________________|

每一轮结果写入 ledger，下一轮 planner 读取 history，形成有记忆的持续进化。

---

阶段路线图

✅ 阶段 0 — 地基（PR #2 · PR #3）

• PR #2（hitome0123）：MVP 闭环 + 严格 scope check + 完整 ledger（含 scope violation 路径）→ 推荐合并，作为主线地基
• PR #3（AndrosEt）：MVP 闭环 + Observer + YAML config → 功能跑通，但 scope violation 路径审计不完整

里程碑：可以跑一次完整闭环，ledger 可审计，scope 严格控制。角色为 stub，无 LLM。

---

🔧 阶段 1 — 第一个真正可用版本（Issue #4 · PR4）

核心交付：接入真 LLM + 多轮进化循环 + History 注入 + Cost Guard

功能块	描述	规模
三角色接真 LLM	planner/executor/evaluator 调用真实 LLM 或 coding agent	~170 行
run_until_done()	多轮循环原语，触发 hard stops 才停	~30 行
History 注入	planner 每轮读前 N 轮记录，不再是布朗运动	~50 行
Cost guard	max_total_usd / max_total_tokens 安全闸	~30 行

里程碑：第一个可演示版本。给一个 repo + 一个目标，放着不管，多轮后 repo 真实发生变化，全程可审计，预算可控。

PR4 完成后的能力边界：

• ✅ 多轮 LLM 反复尝试改进
• ✅ 每轮基于前几轮历史调整方向
• ✅ 失败不污染主分支（worktree 隔离）
• ✅ 每次成功 git commit 可单独回滚
• ✅ 自动撞预算/迭代上限停止
• ❌ 不知道何时算"成功"（跑到上限才停）
• ❌ 无整体方向感（单维渐进，不会多阶段战略）
• ❌ 无进程级 sandbox（LLM 可执行任意 shell）

---

🔧 阶段 2 — 知道何时算赢（PR5，待 issue）

核心交付：Goal Evaluator + Strategist

功能块	描述
Goal Evaluator	独立角色，判断 mission 整体是否达成，可自动停止进化
Strategist	每 N 轮触发一次，输出当前阶段/下一里程碑/禁忌方向，注入 planner
run_until_done 升级	增加 goal_reached 作为终止条件

里程碑：进化过程有目标感，知道何时算赢，不再依赖人工设置 max_iterations。

---

🔧 阶段 3 — 逃出局部最优（PR6，待 issue）

核心交付：k-branch 并行探索（FunSearch / AlphaEvolve 模式）

功能块	描述
k 个并行 worktree	同一轮起 k 个分支，各自 plan → execute
Fitness 评分	evaluator 返回浮点分数而非 accept/reject
选择合并	选最优 branch 推进 accepted，其余淘汰

里程碑：不会因为一个错误方向走死，具备种群级别的探索能力。

---

🔧 阶段 4 — 生产级安全（PR7，待 issue）

核心交付：Process Sandbox + Remote Observer

功能块	描述
Process sandbox	firejail / bwrap / 容器，限制 executor 的 shell 权限
Remote observer	读取 GitHub Actions 状态、外部 metric API 等

里程碑：可以放进真实生产 repo 无人值守跑，executor 无法破坏宿主环境。

---

发版节点建议

版本	对应阶段	特征
v0.1	PR2 合并后	机制可用，stub 角色，适合工程演示
v0.2	PR4 完成后	第一个真正可用版本，LLM 接入，多轮有记忆
v0.3	PR5 完成后	知道何时停，完整"灵魂插件"体验
v1.0	PR7 完成后	生产级安全，可信放入真实 repo

---

讨论

欢迎在评论区提出对路线图的意见、对某阶段功能的设计建议、或对原则的质疑。

[Protocol-zero-0]

阶段 1（PR4）进展更新

PR #6 已提交，实现：

• ✅ 三角色接入真 LLM（planner.py / executor.sh / evaluator.py），provider/model/tool 全部配置驱动
• ✅ --loop 多轮循环，直到 hard stops 触发
• ✅ History 注入（planner 每轮读前 N 条 reflection）
• ✅ Cost guard（max_total_usd / max_total_tokens）
• ✅ 39/39 测试通过

下一里程碑：PR5（goal evaluator + strategist，知道何时算赢）

[Protocol-zero-0]

路线图评审：PR #6 后的阶段判断

我重新看了本 issue 的总纲、Issue #4 和 PR #6。基于当前状态，我的判断是：

Issue #5 的技术路线是可行的，而且比保守 MVP 更适合当前项目节奏。
原因是 PR #2 已经把地基做稳，PR #6 又把阶段 1 的关键能力补上：真实 LLM / coding agent 角色、多轮循环、history 注入、cost guard。项目已经从“一次性受限代码实验”进入“可演示的多轮进化 runtime”阶段。

我本地验证了 PR #6：

/usr/bin/python3.12 -m unittest discover -s tests -v

结果：39/39 tests passed。

补充说明：我用当前环境的 pytest tests/ -v 会遇到 adapters 导入路径问题，建议后续在 README / PR 里统一官方测试命令，避免贡献者用不同 test runner 得到不一致结果。

对 Issue #5 路线的评价

当前路线的优点：

1. 方向正确：kernel 只路由智能，不嵌入智能；planner / executor / evaluator 作为外部命令接入。这能避免项目膨胀成又一个 agent framework。
2. 阶段拆分合理：阶段 0 是可靠地基，阶段 1 是第一个可演示版本，阶段 2 再解决“知道何时算赢”，阶段 3 再做 k-branch，阶段 4 再补生产级 sandbox。
3. MVP 不是过度保守：现在 PR PR4: LLM roles + multi-round loop + history injection + cost guard #6 已证明，只要验收标准清楚，AI 辅助开发可以很快推进。关键不是少做，而是每个阶段都必须有硬验收。
4. 适合创业节奏：每个阶段都能形成一个可展示、可运行、可继续迭代的版本，而不是长期停留在设计文档。

当前阶段重新定位

如果 PR #6 被接受为阶段 1 实现，那么版本边界可以调整为：

• v0.1：PR MVP closed loop: observer + scope + hard stops + ledger (issue #1) #2 后，单轮闭环、scope、ledger、hard stop，stub roles。
• v0.2：PR PR4: LLM roles + multi-round loop + history injection + cost guard #6 后，真实角色、多轮循环、history、cost guard，已经是第一个可演示 runtime。
• v0.3：下一阶段应解决 Goal Evaluator + Strategist，让系统知道何时成功、下一阶段怎么走。

也就是说，接下来不应该继续扩展阶段 1，而应该进入阶段 2。

下一阶段建议：PR5 / Issue X 应该写成验收驱动任务

我建议阶段 2 不要只写“实现 Goal Evaluator + Strategist”，而是写成可执行验收标准：

1. goal_evaluator 返回 goal_reached=true 时，--loop 必须停止，并在 final state / ledger 中记录 goal_reached。
2. goal_evaluator 返回 goal_reached=false 时，系统继续运行，直到 hard stop / cost guard。
3. goal_evaluator 执行失败时，不允许误判成功，必须记录 error 并按配置选择 continue / halt。
4. 每 N 轮触发一次 strategist，生成 strategy.json。
5. 后续 planner input 必须包含最近一次 strategy。
6. demo 必须证明：系统不是因为 max_iterations 停止，而是因为 goal evaluator 判定目标达成而提前停止。
7. ledger 至少新增或明确记录：goal_evaluation.json、strategy.json、最终停止原因。

这样做的好处是：功能范围可以大胆推进，但不会变成“看起来做了很多，实际不可验收”。

需要继续保持的边界

阶段 2 仍然不建议引入：

• dashboard
• daemon / 后台常驻
• GitHub PR router
• 多 repo 支持
• k-branch 并行探索
• 生产级 process sandbox

这些都可以做，但不应该挤进 Goal Evaluator + Strategist 这一阶段。

总结

Issue #5 可以继续作为项目总纲。当前最重要的执行原则是：

路线可以积极，验收必须具体。

PR #6 之后，项目已经具备第一个真正可演示的 runtime 雏形。下一步最有价值的不是继续横向堆功能，而是让 runtime 具备“目标达成判断”和“阶段性策略感”，也就是进入 v0.3 / PR5。

[Protocol-zero-0]

状态更新 · 2026-05-05

阶段 0 ✅ 已完成

• PR MVP closed loop: observer + scope + hard stops + ledger (issue #1) #2 已合并（hitome0123）
• PR Feat: add Observer, mutation scope, hard stops, and YAML config to Evolution Kernel MVP #3 已关闭（scope audit 不完整，见关闭 comment）

阶段 1 🔄 PR 已提交，待合并

• PR #6 已提交，CI 绿（Python 3.10 + 3.12，39/39 测试通过）
• Copilot 自动审查 8 条 issue 全部已修复（2 次 commit）
• 新增测试：20 个 PR4 专项测试（config / cost guard / history injection / --loop flag）

本次 PR 交付内容清单：

• evolution_kernel/config.py — 新增 LLMConfig、CodingAgentConfig、HistoryConfig；HardStops 新增 max_total_usd/max_total_tokens
• evolution_kernel/hard_stops.py — cost accumulation + cost guard precheck
• evolution_kernel/governor.py — history injection（_build_history() + planner_input.history[]）
• evolution_kernel/cli.py — --loop flag + exit code 3 on halt + _safe_cost() + halted audit
• roles/planner.py — 真 LLM 角色（anthropic / openai，config-driven）
• roles/executor.sh — coding agent dispatcher（aider / claude-code）
• roles/evaluator.py — LLM 评估角色，返回 cost_usd + tokens_used
• examples/evolution.yml — 更新完整配置示例

PR4 完成后可立即做的事（下方有完整示例）

阶段 2–4 ⏳ 待规划

PR5（Goal Evaluator + Strategist）、PR6（k-branch 并行）、PR7（sandbox）待 PR #6 合并后开排。

[Protocol-zero-0]

✅ 阶段 1 完成 — v0.2 已发布

PR #6 已合并（squash merge，commit cf06eee）

交付清单（已全部落地）：

• roles/planner.py — 真 LLM 角色（Anthropic / OpenAI，config-driven）
• roles/executor.sh — coding agent dispatcher（aider / claude-code），jq 安全编码
• roles/evaluator.py — LLM 评估角色，返回 cost_usd + tokens_used
• evolution_kernel/config.py — 新增 LLMConfig、CodingAgentConfig、HistoryConfig；HardStops 新增 max_total_usd/max_total_tokens
• evolution_kernel/hard_stops.py — cost accumulation + precheck
• evolution_kernel/governor.py — history injection（_build_history() + planner_input.history[]）
• evolution_kernel/cli.py — --loop flag + exit 3 on halt + _safe_cost() + halted audit
• README.md — 完整重写，覆盖价值主张 + 完整示例 + 配置参考
• 20 个 PR4 专项测试，39 个测试全过，CI 绿（Python 3.10 + 3.12）

当前版本边界（v0.2）：

• ✅ 可以给一个 repo 指定目标，--loop 放着不管，多轮后 repo 真实改变
• ✅ 每轮基于前几轮历史调整方向，不再是随机游走
• ✅ 预算可控（max_total_usd / max_total_tokens），撞限自动停
• ✅ 每次 accepted 变更都是可回滚的 git commit
• ❌ 不知道何时算"赢"（跑到上限才停）→ PR 技术纲要与路线图：evolution-kernel 从 MVP 到灵魂插件 #5

下一步：阶段 2 — PR #5（Goal Evaluator + Strategist）

[Protocol-zero-0]

命名规则更新

为避免路线图里的"PR5/PR6/PR7"与 GitHub 实际 PR 编号混淆，后续统一用 Issue 编号 追踪各阶段，实现 PR 在 issue 标题里注明。

阶段	功能	追踪 Issue	实现 PR
阶段 0	MVP 闭环	—（已完成）	PR #2 合并
阶段 1	LLM + loop + history + cost guard	—（已完成）	PR #6 合并
阶段 2	Goal Evaluator + Strategist	Issue #10	待开发
阶段 3	k-branch 并行探索	待创建（Issue #1x）	待开发
阶段 4	Process Sandbox	待创建（Issue #1x）	待开发

规则：每个阶段先开 Issue（定义目标/验收标准），PR 引用并 close 该 Issue。Issue 编号和 PR 编号相邻，搜索任何一个都能找到对方。

[Protocol-zero-0]

v1.1 ready to publicize ✅

跟踪 issue 收尾。今日 (2026-05-17) 把 v1.0 "工程完成" 推到 "ready to publicize"——四件交付物 + v1.1.0 GH Release 已全部 main 合并。

已交付 (PR 链)

• feat: evolution-kernel init subcommand + 5 YAML templates #28 — evolution-kernel init + 5 YAML 模板 (lint / coverage / perf / benchmark / custom)
• feat: examples/quickstart/ — 10-minute zero-cost ruff cleanup demo #30 — examples/quickstart/ 10-min zero-cost ruff cleanup demo · E2E: 1.4 s · $0 · 无 API key
• feat: examples/oss_fix_demo/ — real OSS fix via claude CLI #32 — examples/oss_fix_demo/ 真实 OSS (python-slugify v8.0.4) 经 claude -p 修复 · E2E: 48 s · 1.4k 行 OSS · 实际 evolution/accepted 上 commit bae97a8
• docs: README hero — ▶ Try in 10 minutes + ASCII workflow #34 — README 顶部 "▶ Try in 10 minutes" hero + ASCII workflow 图 (英文 + 中文 parity)
• v1.1.0 Release — 完整 changelog + 数字

实测 LLM 花费

本次 v1.1 全部工程化在 Claude Pro 订阅下完成（无 ANTHROPIC_API_KEY / OPENAI_API_KEY），按订阅 flat fee 计 → 边际 $0。oss_fix_demo 的 claude executor 单次 wall-clock 34 s，可作为 "一次小型真实修复" 成本锚定。

工程数字

• evolution_kernel/*.py: 1,969 行 (cap 2,089；baseline 1,889；margin 120)
• 102 测试通过 (99 baseline + 3 init wizard) on Py 3.10 / 3.12
• 单依赖 PyYAML 保留
• 无任何 kernel 重构 —— v1.0 冻结的 runtime 字节级保留

过程上一处偏差（透明披露）

PR #28 之后我直接在 main 上推了一次 commit 943922d (fix(tests): convert test_init_wizard to unittest so CI picks it up)。原因：本地用 pytest 跑通了，但忽略了 CI workflow 用的是 python -m unittest discover —— pytest fixture 风格的测试会被静默跳过。auto-merge 把 feature branch 删掉后我落在了 main 上，没切回新分支就提交修正了。下不为例 —— 任何后续修正会先 fork branch 走 PR。

待 Jim 决策事项

1. kernel 层小修：roles/executor.sh 的 claude-code 分支默认不带 --permission-mode acceptEdits，导致 claude -p 非交互模式不肯改文件。examples/oss_fix_demo/ 用自定义 executor 绕过，但这是真 bug，建议开 follow-up issue (post-v1.1)。
2. 公开节奏：v1.1 现在站得住宣传——是直接发 HN / X，还是先等 Stage-5（multi-agent / web UI / 自托管 dashboard 等）？我倾向先发 v1.1，因为 onboarding 路径已经齐了，Stage-5 是锦上添花。
3. CHANGELOG.md：仓库目前没有专门的 CHANGELOG 文件，所有版本史都在 GH Releases 里。是否建一份？(我倾向不建，GH Releases 已经够用。)
4. examples/oss_fix_demo/ 进入 CI：当前不进——CI 没装 claude CLI 也没 Pro 凭证。是否在 CI 里只 lint 这些 example 文件 (不跑 e2e)？或保持手动验证？

随时叫，可立刻继续推进任何一条。