Skip to content

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

Open
Open
技术纲要与路线图：evolution-kernel 从 MVP 到灵魂插件#5
Labels
meta项目元信息：路线图、纲要、设计讨论

Description

@Protocol-zero-0
Protocol-zero-0
opened on May 10, 2026

本 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

讨论

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

Activity

  1. Protocol-zero-0
    added
    meta项目元信息：路线图、纲要、设计讨论
    on May 10, 2026
  2. Protocol-zero-0
    pinned this issue on May 10, 2026

  3. Protocol-zero-0 commented on May 10, 2026

    @Protocol-zero-0
    Protocol-zero-0
    on May 10, 2026
    OwnerAuthor

    阶段 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，知道何时算赢）

  4. Protocol-zero-0 commented on May 10, 2026

    @Protocol-zero-0
    Protocol-zero-0
    on May 10, 2026
    OwnerAuthor

    路线图评审：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 实现，那么版本边界可以调整为：

    也就是说，接下来不应该继续扩展阶段 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。

  5. Protocol-zero-0 commented on May 10, 2026

    @Protocol-zero-0
    Protocol-zero-0
    on May 10, 2026
    OwnerAuthor

    状态更新 · 2026-05-05

    阶段 0 ✅ 已完成

    阶段 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 合并后开排。

  6. Protocol-zero-0 commented on May 10, 2026

    @Protocol-zero-0
    Protocol-zero-0
    on May 10, 2026
    OwnerAuthor

    ✅ 阶段 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）

  7. Protocol-zero-0 commented on May 10, 2026

    @Protocol-zero-0
    Protocol-zero-0
    on May 10, 2026
    OwnerAuthor

    命名规则更新

    为避免路线图里的"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 编号相邻，搜索任何一个都能找到对方。

  8. Protocol-zero-0 commented on May 17, 2026

    @Protocol-zero-0
    Protocol-zero-0
    on May 17, 2026
    OwnerAuthor

    v1.1 ready to publicize ✅

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

    已交付 (PR 链)

    实测 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)？或保持手动验证？

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    meta项目元信息：路线图、纲要、设计讨论

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions