momo-code 源码结构全解：53+个TypeScript模块如何协同构建自进化代理

momo-code 源码结构是理解这个 AI coding agent 如何"与你一起进化"的最佳入口。momo-code 是一个基于 TypeScript 构建的自进化代理（self-evolving agent）项目：它不只是帮你写代码，还会从每次任务中提炼可复用的"战术"，并在后台持续微调自己的模型。本文将带你用 10 分钟看懂它的源码结构——27 个功能模块目录、120+ 个 TypeScript 文件如何分层协同，构建出这套双速自进化系统。

一、鸟瞰仓库：momo-code 的代码都放在哪

如果你刚 clone 了仓库，先别急着钻进代码，看一下目录骨架就能建立全局印象：

git clone https://gitcode.com/gh_mirrors/mo/momo-code

momo-code/ ├── packages/opencode/src/ # ⭐ 全部核心源码都在这里 ├── packages/opencode/python/ # Python 侧：Genesis 物理仿真世界、语音录音 ├── docs/ # 设计文档（优化笔记、自进化方案） ├── pic/ # 架构图 └── README.md # 项目主文档，强烈建议先读

核心逻辑几乎全部集中在 packages/opencode/src/ 目录，按职责拆成27 个功能模块目录（外加 4 个顶层入口文件）。这种"一个目录 = 一个能力域"的切分方式，是阅读本项目源码最重要的心法：先认目录，再读文件。

二、四层架构：53+个 TypeScript 模块一图看懂

momo-code 的源码遵循清晰的四层架构（如上图所示），从下到上依次是：

1️⃣ 基础设施层：模型接入

这一层把各家模型 API 的差异屏蔽掉，上层代码只需要"统一请求/统一响应"，想换模型改配置即可。

2️⃣ Agent 核心层：编排与运行时

3️⃣ 经验层：双速自进化（本项目灵魂所在）

4️⃣ 接口层：命令与服务

💡 快速验证四层关系：你敲一条命令（接口层）→ 核心层编排会话 → 经验层悄悄注入历史战术 → 基础设施层调用模型。

三、自进化引擎深解：快慢双循环如何配合

上图展示了 momo-code 最独特的设计——双速进化算法：快循环在分钟级迭代"提示词战术"，慢循环在小时级微调"模型权重"，两者共享同一个经验库。

🚀 快循环（KEP）：5 步战术进化

experience/index.ts 定义了5 步闭环：

1. Signal（发现）：采集错误、异常、用户反馈等信号
2. Distill（蒸馏）：从成功会话中提炼最小可复用"战术"卡片
3. Select（采样）：用 Thompson 采样（贝叶斯）选出本次要尝试的战术
4. Inject（注入）：把战术写进上下文，让模型立刻用上
5. Solidify（固化）+ Gate（门禁）：验证成败、更新胜率统计，胜出的战术晋升到慢循环

经验全部落盘到~/.momo/experience/下的tactics.json（战术库）和ledger.jsonl（审计日志），完全本地化、可审计。

🐢 慢循环（MCGS）：10 个组件的模型进化

evolve/index.ts 用 10 个协作组件实现蒙特卡洛图搜索（MCGS）自动微调：

• miner从历史会话挖掘失败模式 →curriculum构建"黄金样本 + 难负例 + 回放"三片训练数据
• search执行 MCGS 图搜索（展开/评分/融合/剪枝），policy按胜率决定重建、调参还是外科手术式修改
• trainer调度训练后端，evaluator用棘轮门禁验证（基线只升不降），registry管理模型版本热切换
• provenance留下数据审计轨迹，guard负责安全与隐私脱敏

🛡️ 三道安全闸

自进化系统的最大风险是"自己改坏自己"，momo-code 用三个模块设防：

• jev/：JEV 决策层以影子模式并行记录决策，校准误差（ECE < 0.05）才允许接管 5 个关键决策门
• momo-bench/：评估数据按 60/30/10 切分，10% 的 canary 集永不被自动管线看到，晋升还要过 7 个反向测试防作弊
• rsi/：预算护栏（日限额、成本上限）+ 安全开关——touch ~/.momo/STOP可立即停掉所有自进化活动

四、模块如何协同：数据流动全景

理解模块协同，看三条数据流就够了：

① 经验流（纵向贯通）：快循环产出的战术经experience/bridge.ts晋升为慢循环的课程数据，模型微调后的新版本又由registry热切换回核心层——形成"使用 → 学习 → 更强"的螺旋。

② 任务流（横向编排）：graph/engine.ts把长任务规划成 DAG，每个节点是一个子momo进程并行跑；subagent/orchestrate.ts则负责"计划 → 并行 → 汇总"的递归拆解。

③ 跨界流（TypeScript ↔ Python）：sim/bridge.ts用 NDJSON JSON-RPC 驱动常驻的 Python 仿真进程 genesis_world/server.py，让 Agent 像写 RL 代码一样"操控物理世界"；voice/stt.ts则把语音转文字后接入编码会话。

测试体系同样可观：test/ 下 30+ 个测试文件，几乎每个核心模块都有对应测试，改代码前先跑一遍npm run smoke心里更有底。

五、新手源码阅读路线图：5 步上手

按这个顺序读，每步大约 20~30 分钟：

1. 入口：main.ts → cli/main.ts，看清命令如何分发
2. 界面：repl/index.ts，看会话如何渲染
3. 模型层：provider/index.ts，看统一 API 如何屏蔽 25+ 家模型差异
4. 快循环：experience/index.ts，体会"信号 → 战术 → 注入"的最短进化路径
5. 慢循环：evolve/index.ts + evolve/curriculum.ts，理解 MCGS 微调全链路

📖 配套文档：README.md（总览）、docs/self-evolution.md（自进化设计）、docs/optim.md（优化笔记）。

六、总结

momo-code 源码结构的精髓在于：每个目录都是一个可独立理解的能力域，而"经验层"让所有模块通过共享的战术库连成一个会学习的整体。读懂这 27 个模块目录的职责边界，你就掌握了这个自进化代理 80% 的设计思想——剩下的，交给它自己进化吧。