MiniMax Code 源码解读
逐层拆读 MiniMax 开源的终端编码 Agent“MiniMax Code”的 TypeScript 源码——内置 pi-mono 的 Agent 循环、两代本地运行时、权限与沙箱、插件与账号体系，一边讲怎么用，一边讲怎么实现。
MiniMax Code（命令行叫 mcode）是 MiniMax 开源的终端编码 Agent：在终端里读懂项目、修改代码、运行测试，可以用 MiniMax 账号的 Token Plan，也可以接入自己的模型（BYOK）。同一个进程内运行时同时服务三种入口——交互式 TUI、给脚本和 CI 用的 mcode exec、给编辑器用的 ACP。
它的 Agent 循环不是从零写的：仓库把开源的 pi-mono 按源码整体放进了 third_party，再在上面搭了两代本地运行时、权限与沙箱、插件、账号与云端工具，以及一套自己的终端界面。整个项目用 TypeScript 写成，非测试代码约 70 万行，其中第一方约 55.6 万行。
这个专栏把它逐层拆开读。
源码基准
本专栏所有引用以下述快照为准：
| 项 | 值 |
|---|---|
| 仓库 | github.com/MiniMax-AI/minimax-code |
| commit | e3724a13d72d61c9bdc68a1a72b5c020f065ba26（main 分支，仓库没有打任何 tag） |
| 版本 | 0.4.12（npm 包名 @minimax-ai/code） |
| 快照日期 | 2026-09-19 |
| 许可 | 第一方代码默认 MIT；third_party 下的上游保留各自许可（sandbox-runtime 为 Apache-2.0） |
| 运行要求 | Node.js 22.19+（22.x）或 24.2 到 26；从源码开发用 pnpm 9.12.0 |
所有路径都相对仓库根，例如 packages/local-runtime-v2/src/service/turn-system/queue.dispatcher.ts。这份源码是 2026-09-18 以一个提交整体导入的，此前仓库只是 issue 追踪器；导入后修复仍在频繁合入，读时以当前 main 为准。
规模口径：git 跟踪的 .ts/.tsx/.mts 文件，排除测试目录与 *.test.*、*.spec.*，用 wc -l 数物理行。全仓 2758 个文件、695432 行；第一方 packages/ 2348 个文件、556219 行，third_party/ 410 个文件、139213 行。release/extraction.json 登记了 31 个包根，细节见仓库全景。
读者预设：默认你会读 TypeScript（async、泛型、联合类型、interface），不熟的语言点会在关键处就地补一句。读过《从 LLM 到 Coding Agent》会更顺，但不是硬前提。
这个专栏怎么读
每一章尽量走两条线：
- 怎么用——这个功能在
mcode里长什么样、怎么配置； - 怎么实现——翻到对应包的源码，看它在底层到底怎么做。
侧重结构与数据流：讲清“一件事经过哪些包、数据怎么流、边界契约是什么”，而不是逐行贴代码——关键处才引一小段源码点睛。仓库里不少模块服务于桌面端与云端产品，本书以命令行为主线，只在与 CLI 相关时讲它们，并说明它们主要服务哪种形态。README 与仓库文档和代码不一致时，一律写代码的实际行为，并在正文注明。
和站内其他专栏的关系
| 专栏 | 视角 |
|---|---|
| 《从 LLM 到 Coding Agent》 | 教学最小实现：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| 《Kimi Code 源码解读》 | 同样借用 pi 的 TypeScript 实现：它只复制了 pi 的终端库，这里连 Agent 循环与模型层都整体内置 |
| 《OpenCode 源码解读》 | 另一种 TypeScript 生产实现；MiniMax 更早的本地产品留下了以它为执行框架的痕迹，见第一代运行时 |
| 《MiMo Code 源码解读》 | 在 OpenCode 之上二次开发：同为国内大模型厂商的终端 Agent，可以对照两家的取舍 |
| 《Grok Build 源码解读》 | Rust 生产实现：xAI 的终端 Agent 怎么做 |
| 《Claude Code 中文手册》、《Codex 中文手册》 | MiniMax Code 的沙箱是 Anthropic 开源 sandbox-runtime 的分叉，插件钩子兼容这两家的格式 |
| 本专栏 | vendor 上游源码、自建运行时：在 pi 的循环外面包一层回合系统，把权限、沙箱、插件、账号接进来 |
它有什么特别的
读之前先知道这份源码值得看的地方：
- 把上游搬进仓库。pi-mono 的
agent、ai、coding-agent、tui四个包按 v0.79.1 原样放进third_party，本地改动逐条记在补丁台账里；产品界面用的却是另一份基于 pi-tui 0.84.2 的 fork。两代上游并存、改动全有账，是本书的第一条线索（内置的 pi-mono）。 - 公开投影。这个仓库是内部 monorepo 的投影：发布的每个文件都登记在清单里，私有包统一叫
@mavis/*，上游变更按三方合并同步进来，一组脚本守住“不能公开的东西不进仓库”（仓库全景）。 - 回合系统包住 pi 的循环。每个回合新建一个 pi 的
Agent来跑，外面是受理、排队、派发、租约与重试；运行中按Enter是“引导”当前响应，按Alt+Enter是“排队”下一条，在代码里是两条不同的路（回合系统）。 - 两代运行时并存。v2 是现役的执行引擎，第一代运行时仍提供数据库、文件、权限、技能等宿主设施和只读的历史会话读取器；更早的旧会话由 v2 的导入器惰性地转成可继续执行的 pi 会话（第一代运行时与 OpenCode 遗产、会话系统）。
- 权限、沙箱与账号是一整套。三种权限模式、分层判定的 Bash 命令、默认关闭且打开后只在 macOS 上包住 Bash 的沙箱、OAuth 设备码登录与给工具子进程发的短期令牌，一起决定了 Agent 能碰什么（权限、沙箱、账号）。
- 向外兼容。插件钩子兼容 Claude Code 与 Codex 的格式，MCP 支持按上下文占比延迟披露工具（默认没开，要把模型写进白名单），ACP 让编辑器直接驱动同一个运行时（插件系统、MCP、Headless 与 ACP）。
路线图
- 第 0 部分 · 导论与全景——它是什么、仓库全景、怎么读这份源码、一条消息的旅程。
- 第 1 部分 · 地基：pi-mono 与模型层——内置的 pi-mono、Agent 循环与回合执行器、模型协议层 pi-ai、模型系统与 BYOK。
- 第 2 部分 · 运行时 v2——进程内入口、会话系统、回合系统、Agent 服务与提示词、存储、第一代运行时与 OpenCode 遗产。
- 第 3 部分 · 工具、权限与沙箱——工具体系、文件与 Shell、权限模式与规则、沙箱、浏览器工具。
- 第 4 部分 · Agent 模块——扩展点与提醒、上下文管理与压缩、Plan 模式与目标、子 Agent 与后台任务、定时任务。
- 第 5 部分 · 扩展与账号——技能、插件系统、MCP、账号与云端工具。
- 第 6 部分 · 终端与接入——TUI 引擎、TUI 应用、Headless 与 ACP、遥测与更新，以及全书回顾。
准备好了，就从 MiniMax Code 是什么 开始。