# MiMo Code 源码解读

> 逐层拆读小米开源的终端编码 Agent“MiMo Code”的源码——它从 OpenCode 分叉而来，这本书讲它为长程任务加了什么：检查点与上下文重建、分层记忆、防空转、Actor 与 Workflow。

- 作者：David（道雾轩）
- 最后更新：2026-09-19
- 原文：https://daiw.net/manual/mimo-code
- 转载与引用：请注明出处并附原文链接（https://daiw.net/about/copyright）

[MiMo Code](https://github.com/XiaomiMiMo/MiMo-Code)（命令行叫 `mimo`）是小米 MiMo 团队开源的终端编码 Agent：跑在终端里的全屏 TUI，能读写代码、执行命令、管理 Git，并靠持久化的记忆在多次会话之间保持对项目的理解。它不绑定模型，除了小米 MiMo 平台，也能接入各家厂商的 API。

它不是从零写的。MiMo Code 以 [OpenCode](https://daiw.net/manual/opencode) 为底座，2026 年 6 月以一个整体提交开源，按源码比对最接近 OpenCode v1.14.19（2026-04-20），此后独立演进。底座之上，它把功夫下在**长程任务**上：一个任务跑上几百步、跨越好几个上下文窗口时，怎样不丢状态、不原地打转、不过早收工。

这个专栏把这些改动**逐层拆开读**。

## 源码基准

本专栏所有引用以下述快照为准：

| 项 | 值 |
| --- | --- |
| 仓库 | [github.com/XiaomiMiMo/MiMo-Code](https://github.com/XiaomiMiMo/MiMo-Code) |
| commit | `2a0eb706e95a77cba34a319e9f11f33f26d4450c`（即 `v0.1.14` 标签） |
| 版本 | `@mimo-ai/cli` v0.1.14 |
| 快照日期 | 2026-09-02 |
| 上游基线 | OpenCode v1.14.19（2026-04-20） |
| 许可 | MIT |
| 运行要求 | 从源码开发需 Bun `1.3.14` |

所有路径都相对仓库根，例如 `packages/opencode/src/session/checkpoint.ts`。注意引擎目录仍叫 `packages/opencode`，产品层面的名字才改成了 MiMo：配置目录是 `.mimocode/`，环境变量以 `MIMOCODE_` 开头。

**规模**：git 跟踪的 `.ts`/`.tsx` 文件（不含测试）全仓 1433 个、约 30.2 万行；其中引擎所在的 `packages/opencode/src` 有 674 个文件、14.1 万行，而上游 v1.14.19 的同一目录只有 443 个文件、8 万行。多出来的部分——新增 238 个文件约 4.2 万行、改动 254 个文件，外加约 5.3 万行的内置技能包——就是本书的主题，全景见[从 OpenCode 分叉：增量全景](https://daiw.net/manual/mimo-code/fork-map)。

<Callout type="info">
  **读者预设**：默认你会读 TypeScript。MiMo 沿用了 OpenCode 的 Effect 写法，不熟的话先读[《OpenCode 源码解读》的“怎么读这份源码”](https://daiw.net/manual/opencode/reading-the-source)。上游原有的机制，本书一两句带过并链接到那本书；但那本对照的是 OpenCode v1.18.30，比 MiMo 的基线新了近五个月，细节未必相同，凡本书涉及之处都以 MiMo 的代码为准。
</Callout>

## 这个专栏怎么读

每一章尽量走**两条线**：

- **怎么用**——这个功能在 `mimo` 里长什么样、怎么开启、怎么配置；
- **怎么实现**——翻到对应模块的源码，看它在底层到底怎么做，以及相对上游 OpenCode 改了什么。

侧重**结构与数据流**：讲清“一件事经过哪些模块、数据怎么流、边界契约是什么”，而不是逐行贴代码——关键处才引一小段源码点睛。MiMo 仓库自带不少设计文档与博客说明，本书逐条对照过代码，二者不一致时写代码的实际行为，并在正文里指出出入。

## 和站内其他专栏的关系

| 专栏 | 视角 |
| --- | --- |
| [《OpenCode 源码解读》](https://daiw.net/manual/opencode) | **底座**：MiMo 沿用的服务端架构、会话引擎、工具与提供方适配 |
| [《从 LLM 到 Coding Agent》](https://daiw.net/manual/llm-to-agent) | **教学最小实现**：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| [《Grok Build 源码解读》](https://daiw.net/manual/grok-build) | **Rust 生产实现**：xAI 的终端 Agent 怎么做 |
| [《Kimi Code 源码解读》](https://daiw.net/manual/kimi-code) | **另一种 TypeScript 生产实现**：DI × Scope 引擎、vendored 的 pi-tui 与自研嵌入式数据库 |
| [《Claude Code 中文手册》](https://daiw.net/manual/claude-code)、[《Codex 中文手册》](https://daiw.net/manual/codex) | MiMo 能导入这两家的会话，也能在原地打转时把活交给它们的命令行 |
| 本专栏 | **在底座上做长程任务改造**：状态怎么跨窗口、Agent 怎么自己判断该不该停、多个 Agent 怎么协作 |

## 它有什么特别的

读之前先知道这份源码值得看的地方：

- **一个会话，多段窗口**。检查点按上下文用量分档在后台写入，由隐藏的 checkpoint-writer 子智能体按 11 节模板维护；用量越过触发线，就用检查点、用户原话和各级记忆重建上下文，写不出检查点才退回传统压缩。
- **记忆分层，定期整理**。项目 `MEMORY.md`、会话笔记、任务进展都是磁盘上的文件，FTS5 只当检索缓存；`dream` 与 `distill` 两个隐藏智能体回看近期会话（可手动触发，自动运行要在配置里打开），把知识并进记忆、把反复出现的手工流程打包成可复用的技能等资产。
- **防空转**。`/goal` 让一次单独的裁判调用决定能不能收工；Try-Best 检测器（默认关闭）发现原地打转就暂停当前轮，可交给 Codex CLI 或 Claude Code CLI 接手；n-gram 监控打断复读；实验性的 Max 模式每一步并行生成多个候选再挑一个。
- **多智能体**。actor 注册表取代了上游的 task 子代理，前台后台、同会话切片与独立子会话都能表达；持久化的收件箱把后台结果与权限请求送回父会话；实验性的 Orchestrator 用一个会话调度一群子会话。
- **可编程的编排**。Workflow（实验开关，默认关闭）把多智能体流程写成跑在 QuickJS 里的脚本，内置 compose、deep-research、fact-check、research-experiment 四个；GPT 类模型顶层只看到一个 `exec` 工具，在同一个沙箱里批量调用宿主工具。
- **为 token 与模型差异做的工程**。配置打开后，actor、task、cron、session 四个工具可以改用受限的命令行语法调用，实验开关下 bash 输出还会按形状剪裁；系统提示词按模型家族挑选；每个实例还内置一套 OpenAI 兼容的 `/v1` 接口，让技能和子进程借用已配置的模型。

## 路线图

- **第 0 部分 · 导论与全景**——它是什么、从 OpenCode 分叉的增量全景、怎么读这份源码、一条消息的旅程。
- **第 1 部分 · 长程上下文**——周期与检查点、检查点写手、上下文重建、压缩与修剪。
- **第 2 部分 · 记忆与自我进化**——分层记忆、历史轨迹检索、Dream 与 Distill。
- **第 3 部分 · 自主运行**——Goal 裁判、树状任务、Try-Best 与 Hand-off、复读检测与重试、Max 模式、定时任务。
- **第 4 部分 · 多智能体**——Actor、收件箱与进度检查、Orchestrator。
- **第 5 部分 · 编排**——Compose、Workflow 运行时、四个内置 Workflow、exec 与 QuickJS 沙箱。
- **第 6 部分 · 工具、技能与护栏**——内置技能与检索、命令行式工具调用与 Token 精简、Git 隔离与安全护栏、MCP。
- **第 7 部分 · 模型、服务与终端**——提供方与提示词路由、内置 LLM 服务、从其他 Agent 迁移、终端体验，以及全书回顾。

准备好了，就从 [MiMo Code 是什么](https://daiw.net/manual/mimo-code/what-is-mimo-code) 开始。

## 本专栏篇目

- [MiMo Code 源码解读](https://daiw.net/manual/mimo-code.md): 逐层拆读小米开源的终端编码 Agent“MiMo Code”的源码——它从 OpenCode 分叉而来，这本书讲它为长程任务加了什么：检查点与上下文重建、分层记忆、防空转、Actor 与 Workflow。

### 第 0 部分 · 导论与全景

- [MiMo Code 是什么](https://daiw.net/manual/mimo-code/what-is-mimo-code.md): 小米 MiMo 团队基于 OpenCode 改出的长程编码 Agent：安装与登录、13 个内置智能体及开关、博客三层设计对应的篇目，以及与站内其他专栏的关系。
- [从 OpenCode 分叉：增量全景](https://daiw.net/manual/mimo-code/fork-map.md): 用 blob 比对找出上游基线 v1.14.19，再按目录清点 MiMo 新增、修改、删除了哪些文件，默认开启的统计上报，以及产品层面改了哪些名字。
- [怎么读这份源码](https://daiw.net/manual/mimo-code/reading-the-source.md): 仓库布局与目录地图、AGENTS.md 约定、沿用旧版的 Effect 写法、构建期宏、开关与实验配置、新增的数据表、从源码运行，以及几条阅读路线。
- [一条消息的旅程](https://daiw.net/manual/mimo-code/message-lifecycle.md): 跟着一条用户消息从 TUI 进入服务端，走完主循环与流处理器再回到屏幕，沿途标出收件箱、检查点、Goal、Max 模式、Try-Best 等挂载点。

### 第 1 部分 · 长程上下文

- [周期：逻辑会话与物理窗口](https://daiw.net/manual/mimo-code/cycles.md): MiMo Code 怎样把一个会话切成多段上下文窗口：检查点按比例分档在后台写入，用量到达触发线就从检查点重建，写不出检查点才退回压缩。
- [检查点写手](https://daiw.net/manual/mimo-code/checkpoint-writer.md): 隐藏子智能体 checkpoint-writer 怎样被拉起、继承父请求前缀、按 11 节模板改写 checkpoint.md，以及校验钩子与写入沙箱。
- [上下文重建与预算化注入](https://daiw.net/manual/mimo-code/context-rebuild.md): 越过触发线后，MiMo Code 怎样插入重建边界，按分段预算把检查点、用户原话与各级记忆拼成一条消息，并把水位线之后的尾部折叠成活动清单。
- [压缩、修剪与请求前缀](https://daiw.net/manual/mimo-code/compaction-and-prune.md): MiMo Code 改写后的压缩流程与失败回滚、按缓存冷热与压力分级的修剪、/context-limit 与触发线的算法，以及为提示词缓存而冻结的请求前缀快照。

### 第 2 部分 · 记忆与自我进化

- [分层记忆](https://daiw.net/manual/mimo-code/memory.md): 记忆在磁盘上分哪几层、谁写谁读，写入闸门怎样把关，FTS5 索引与 memory 工具怎样检索，以及记忆经由哪几条通道进入上下文。
- [历史轨迹与全文检索](https://daiw.net/manual/mimo-code/history.md): 原始对话怎样建成 history_fts 全文索引：实时写入、启动回填、按 kind 抽取正文；history 工具怎样搜索与回看，以及插件拿到的轨迹格式。
- [Dream 与 Distill](https://daiw.net/manual/mimo-code/dream-distill.md): /dream 与 /distill 从哪里触发、自动运行的真实条件、两个隐藏智能体的权限与写入沙箱、提示词要点，以及整理出的记忆和打包出的资产落在哪里。

### 第 3 部分 · 自主运行

- [Goal：让独立裁判决定何时停](https://daiw.net/manual/mimo-code/goal.md): /goal 给会话设一个停止条件，主循环每次想收尾都先请一次单独的裁判调用读完对话再判定，未达成就把缺口写回去接着干，一个目标最多被踢回 12 次。
- [树状任务](https://daiw.net/manual/mimo-code/tasks.md): task 工具在 MiMo 里改成了持久化工作项：T1、T1.1 式编号，SQLite 两张表，宽松的状态机，子智能体完成闸门，以及与检查点、进展文件的联动。
- [Try-Best 检测与 Hand-off](https://daiw.net/manual/mimo-code/try-best-handoff.md): 用三条规则识别原地打转并暂停当前轮，再让用户选择交给 Codex CLI、Claude Code CLI 或原模型换思路，并核对设计文档里哪些模式已落地。
- [复读检测与重试](https://daiw.net/manual/mimo-code/loop-recovery.md): MiMo 怎样发现并打断模型复读（流内片段、跨步文本、重复动作、思考裁剪），怎样给单步结果分类后续跑或放弃，以及按错误种类分预算的请求重试。
- [Max 模式：多候选与裁判](https://daiw.net/manual/mimo-code/max-mode.md): 实验性的 max 智能体怎样开启，每一步怎样并行生成只提议、不执行的候选，裁判怎样挑选，赢家怎样回放进会话，以及降级、重试与成本记账。
- [定时任务与循环](https://daiw.net/manual/mimo-code/cron.md): cron 工具的固定节奏任务与自定节奏循环怎样登记，表达式与抖动怎样计算，跨进程锁与任务文件怎样工作，到点后怎样注入会话，以及进程不在时会发生什么。

### 第 4 部分 · 多智能体

- [Actor：子智能体的生成与回收](https://daiw.net/manual/mimo-code/actors.md): 用 actor 注册表与 actor 工具取代上游的 task 子代理：同会话切片与独立子会话、前后台、上下文继承、结果回传、取消与停滞检测。
- [收件箱、团队与进度检查](https://daiw.net/manual/mimo-code/inbox-team.md): 持久化的 inbox 表承载后台 actor 的通知、权限转发与追加指令：写入与唤醒、排空成合成消息、渲染格式，以及残存的 Team 模块与进度日志检查。
- [Orchestrator：一个会话管所有会话](https://daiw.net/manual/mimo-code/orchestrator.md): 实验性的 Orchestrator 模式：全局唯一的调度会话、session 工具的 12 个动作、peer 子会话与 worktree 隔离、权限转发与代批。

### 第 5 部分 · 编排

- [Compose：规格驱动的开发流程](https://daiw.net/manual/mimo-code/compose.md): 已标为 legacy 的 compose 智能体与十四个技能、Build 下的 /compose-next 契约，以及模式锁定和技能调用控制在代码里怎么实现。
- [Workflow 运行时](https://daiw.net/manual/mimo-code/workflow-runtime.md): 把多智能体编排写成跑在 QuickJS 里的脚本：宿主注入的原语、子智能体派发、并发与重试上限、日志与续跑、事件和界面。
- [四个内置 Workflow](https://daiw.net/manual/mimo-code/builtin-workflows.md): 拆读 compose、deep-research、fact-check、research-experiment 四个脚本的阶段、分工、并行、数据流与失败处理。
- [exec 与 QuickJS 沙箱](https://daiw.net/manual/mimo-code/exec-sandbox.md): GPT 类模型顶层只剩一个 exec：脚本在 QuickJS 里经 tools 调宿主工具。隔离范围、权限、排除的工具、资源上限与精简工具集。

### 第 6 部分 · 工具、技能与护栏

- [内置技能包与技能检索](https://daiw.net/manual/mimo-code/skills.md): 内置技能怎样用 Bun 宏打进产物并在首次运行时解压，同名覆盖与禁用开关，技能目录、skill_search 的 BM25 检索与中文别名，以及斜杠调用的注入。
- [命令行式工具调用与 Token 精简](https://daiw.net/manual/mimo-code/token-efficient-shell.md): 受限的命令行语法怎样代替 JSON 参数调用四个工具，工具名与参数的容错修复，以及 bash 输出的清理、按形状剪裁、截断改进与交互模式。
- [Git 隔离与安全护栏](https://daiw.net/manual/mimo-code/git-guards.md): 工作区信任、隔离子会话的 git 拦截、主工作树与合并冲突提示、删除二次确认、先读后改、SSRF 防护，以及权限求值顺序与询问超时。
- [MCP：采样与工具检索](https://daiw.net/manual/mimo-code/mcp.md): MCP 服务器请求模型补全时怎样选模型、审批与检测停滞，自管的 stdio 传输与结果规范化，轮次生命周期通知，以及工具过多时的按需检索与排序。

### 第 7 部分 · 模型、服务与终端

- [模型、提供方与提示词路由](https://daiw.net/manual/mimo-code/providers.md): 小米平台的加密回调登录与免费通道退场，xAI 与 Codex 登录，模态与附件的新规则，按模型家族挑选系统提示词，以及模型层源码的其他改动。
- [内置 LLM 服务](https://daiw.net/manual/mimo-code/llm-server.md): 每个 MiMo 实例的服务端都挂着一套 OpenAI 兼容的 /v1 接口，技能、脚本与子进程凭按目录签发的临时令牌借用已配置的模型，真实密钥始终留在进程内。
- [从 Claude Code、Codex 与 OpenCode 迁移](https://daiw.net/manual/mimo-code/imports.md): 三种外部会话怎样读进 MiMo 并按修改时间增量重导，“从 Claude Code 导入”搬走哪些凭据，以及哪些 Claude Code 资产是直接沿用的。
- [终端体验：语音、多语言与视觉](https://daiw.net/manual/mimo-code/tui.md): MiMo 在 TUI 里新增的两种语音输入模式与 voice_input 协议、七份界面词典与按时区猜语言、星空与背景图、侧栏插件和一批新斜杠命令。
- [回顾](https://daiw.net/manual/mimo-code/recap.md): 全书要点串联：一条消息沿途多出的挂载点、值得记住的设计、与上游 OpenCode 的对照、文档与代码的出入，以及可迁移的经验和这份源码的短板。