# MiniMax Code 源码解读

> 逐层拆读 MiniMax 开源的终端编码 Agent“MiniMax Code”的 TypeScript 源码——内置 pi-mono 的 Agent 循环、两代本地运行时、权限与沙箱、插件与账号体系，一边讲怎么用，一边讲怎么实现。

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

[MiniMax Code](https://github.com/MiniMax-AI/minimax-code)（命令行叫 `mcode`）是 MiniMax 开源的**终端编码 Agent**：在终端里读懂项目、修改代码、运行测试，可以用 MiniMax 账号的 Token Plan，也可以接入自己的模型（BYOK）。同一个进程内运行时同时服务三种入口——交互式 TUI、给脚本和 CI 用的 `mcode exec`、给编辑器用的 ACP。

它的 Agent 循环不是从零写的：仓库把开源的 [pi-mono](https://daiw.net/manual/minimax-code/pi-mono) 按源码整体放进了 `third_party`，再在上面搭了两代本地运行时、权限与沙箱、插件、账号与云端工具，以及一套自己的终端界面。整个项目用 **TypeScript** 写成，非测试代码约 **70 万行**，其中第一方约 55.6 万行。

这个专栏把它**逐层拆开读**。

## 源码基准

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

| 项 | 值 |
| --- | --- |
| 仓库 | [github.com/MiniMax-AI/minimax-code](https://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 个包根，细节见[仓库全景](https://daiw.net/manual/minimax-code/monorepo-map)。

<Callout type="info">
  **读者预设**：默认你会读 TypeScript（`async`、泛型、联合类型、`interface`），不熟的语言点会在关键处就地补一句。读过[《从 LLM 到 Coding Agent》](https://daiw.net/manual/llm-to-agent)会更顺，但不是硬前提。
</Callout>

## 这个专栏怎么读

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

- **怎么用**——这个功能在 `mcode` 里长什么样、怎么配置；
- **怎么实现**——翻到对应包的源码，看它在底层到底怎么做。

侧重**结构与数据流**：讲清“一件事经过哪些包、数据怎么流、边界契约是什么”，而不是逐行贴代码——关键处才引一小段源码点睛。仓库里不少模块服务于桌面端与云端产品，本书以命令行为主线，只在与 CLI 相关时讲它们，并说明它们主要服务哪种形态。README 与仓库文档和代码不一致时，一律写代码的实际行为，并在正文注明。

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

| 专栏 | 视角 |
| --- | --- |
| [《从 LLM 到 Coding Agent》](https://daiw.net/manual/llm-to-agent) | **教学最小实现**：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| [《Kimi Code 源码解读》](https://daiw.net/manual/kimi-code) | **同样借用 pi 的 TypeScript 实现**：它只复制了 pi 的终端库，这里连 Agent 循环与模型层都整体内置 |
| [《OpenCode 源码解读》](https://daiw.net/manual/opencode) | **另一种 TypeScript 生产实现**；MiniMax 更早的本地产品留下了以它为执行框架的痕迹，见[第一代运行时](https://daiw.net/manual/minimax-code/runtime-v1) |
| [《MiMo Code 源码解读》](https://daiw.net/manual/mimo-code) | **在 OpenCode 之上二次开发**：同为国内大模型厂商的终端 Agent，可以对照两家的取舍 |
| [《Grok Build 源码解读》](https://daiw.net/manual/grok-build) | **Rust 生产实现**：xAI 的终端 Agent 怎么做 |
| [《Claude Code 中文手册》](https://daiw.net/manual/claude-code)、[《Codex 中文手册》](https://daiw.net/manual/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](https://daiw.net/manual/minimax-code/pi-mono)）。
- **公开投影**。这个仓库是内部 monorepo 的投影：发布的每个文件都登记在清单里，私有包统一叫 `@mavis/*`，上游变更按三方合并同步进来，一组脚本守住“不能公开的东西不进仓库”（[仓库全景](https://daiw.net/manual/minimax-code/monorepo-map)）。
- **回合系统包住 pi 的循环**。每个回合新建一个 pi 的 `Agent` 来跑，外面是受理、排队、派发、租约与重试；运行中按 `Enter` 是“引导”当前响应，按 `Alt+Enter` 是“排队”下一条，在代码里是两条不同的路（[回合系统](https://daiw.net/manual/minimax-code/turn-system)）。
- **两代运行时并存**。v2 是现役的执行引擎，第一代运行时仍提供数据库、文件、权限、技能等宿主设施和只读的历史会话读取器；更早的旧会话由 v2 的导入器惰性地转成可继续执行的 pi 会话（[第一代运行时与 OpenCode 遗产](https://daiw.net/manual/minimax-code/runtime-v1)、[会话系统](https://daiw.net/manual/minimax-code/session-system)）。
- **权限、沙箱与账号是一整套**。三种权限模式、分层判定的 Bash 命令、默认关闭且打开后只在 macOS 上包住 Bash 的沙箱、OAuth 设备码登录与给工具子进程发的短期令牌，一起决定了 Agent 能碰什么（[权限](https://daiw.net/manual/minimax-code/permission)、[沙箱](https://daiw.net/manual/minimax-code/sandbox)、[账号](https://daiw.net/manual/minimax-code/accounts-and-tools)）。
- **向外兼容**。插件钩子兼容 Claude Code 与 Codex 的格式，MCP 支持按上下文占比延迟披露工具（默认没开，要把模型写进白名单），ACP 让编辑器直接驱动同一个运行时（[插件系统](https://daiw.net/manual/minimax-code/plugins)、[MCP](https://daiw.net/manual/minimax-code/mcp)、[Headless 与 ACP](https://daiw.net/manual/minimax-code/headless-and-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 是什么](https://daiw.net/manual/minimax-code/what-is-minimax-code) 开始。

## 本专栏篇目

- [MiniMax Code 源码解读](https://daiw.net/manual/minimax-code.md): 逐层拆读 MiniMax 开源的终端编码 Agent“MiniMax Code”的 TypeScript 源码——内置 pi-mono 的 Agent 循环、两代本地运行时、权限与沙箱、插件与账号体系，一边讲怎么用，一边讲怎么实现。

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

- [MiniMax Code 是什么](https://daiw.net/manual/minimax-code/what-is-minimax-code.md): MiniMax 的终端编码 Agent：三种入口、登录与 Token Plan、自带模型、常用命令与快捷键，以及它和 pi-mono、OpenCode 的渊源。
- [仓库全景：公开投影与两个上游](https://daiw.net/manual/minimax-code/monorepo-map.md): 31 个包根的职责、规模与依赖方向，@mavis 私有包名的由来，公开投影的四道关，以及 pi-mono 与 sandbox-runtime 两个上游。
- [怎么读这份源码](https://daiw.net/manual/minimax-code/reading-the-source.md): 从源码构建与运行、14 道验证门与测试登记表、类型路径怎样由包清单推导、AGENTS.md 的约定、两代运行时各自的角色，以及一条沿命令行主线的阅读路线。
- [一条消息的旅程](https://daiw.net/manual/minimax-code/message-lifecycle.md): 按下回车之后：输入经运行协调器进入 CliService，回合系统受理并开跑，pi 的 Agent 循环调模型、跑工具，事件再经会话流回到转录区。

### 第 1 部分 · 地基：pi-mono 与模型层

- [内置的 pi-mono：四个包与补丁台账](https://daiw.net/manual/minimax-code/pi-mono.md): MiniMax Code 把开源的 pi-mono 四个包按 v0.79.1 原样放进 third_party：各包规模、第一方代码实际用到哪几块、34 条本地补丁，以及为什么选择 vendor 源码。
- [pi 的 Agent 循环与回合执行器](https://daiw.net/manual/minimax-code/pi-agent.md): pi 的 runLoop 一轮怎么调模型、执行工具、停下来；agent-core 的 PiTurnRunner 与 agent-runtime 又怎样把它包成 MiniMax 运行时里的一个回合。
- [模型协议层 pi-ai](https://daiw.net/manual/minimax-code/pi-ai.md): pi-ai 用一套类型与事件统一九种模型 API：MiniMax 实际走的三种 BYOK 形态与 Codex 通道、流式事件怎么归一、思考参数怎么映射，以及落在 ai 包的补丁。
- [模型系统：目录、BYOK 与连通性测试](https://daiw.net/manual/minimax-code/model-system.md): local-runtime-v2 的模型系统怎样把模型键解析成 pi-ai 的 Model，BYOK 如何先测后存、API Key 存在哪里，以及内置的 models.dev 目录快照怎样更新。

### 第 2 部分 · 运行时 v2

- [进程内入口：CliService 与应用层](https://daiw.net/manual/minimax-code/runtime-entry.md): TUI、exec 与 ACP 共用一个进程内运行时：启动顺序与服务组装，CliService 的 86 个方法如何分派到三组应用对象，以及源码边界在代码里的落点。
- [会话系统](https://daiw.net/manual/minimax-code/session-system.md): 会话记录、两层消息、流式帧、队列与用量由谁持有，分叉、回退与旧会话导入如何分工，以及 --continue、--session、/sessions 的调用路径。
- [回合系统：受理、排队与执行](https://daiw.net/manual/minimax-code/turn-system.md): 一次提交如何经过受理、入队、派发、执行与收尾；运行中 Enter 的“引导”与 Alt+Enter 的“排队”在代码里有何不同；租约、中止与错误重试的数字。
- [Agent 服务：内置 Agent 与提示词](https://daiw.net/manual/minimax-code/agent-service.md): 四个内置 Agent 的名册与能力上限，Handlebars 模板怎样按模式与表面渲染成系统提示词，以及 AGENTS.md 等指导文件进入提示词的顺序与预算。
- [存储：SQLite、迁移与运行时归属](https://daiw.net/manual/minimax-code/storage.md): 数据目录的布局，better-sqlite3 加 Drizzle 的单库与手写迁移，多个进程共用一个数据目录时怎样用租约判定归属，以及启动后的保留与清理。
- [第一代运行时与 OpenCode 遗产](https://daiw.net/manual/minimax-code/runtime-v1.md): 第一代运行时包如今在 v2 里扮演什么角色、v2 还引用它哪些模块，旧版以 OpenCode 为执行框架的代码证据，以及旧会话怎样被导入成可继续执行的 pi 会话。

### 第 3 部分 · 工具、权限与沙箱

- [工具体系](https://daiw.net/manual/minimax-code/tool-system.md): 模型每回合拿到的工具从哪来、怎样按模型能力与 Agent 配置层层过滤、结果怎样分层截断，以及不在工具清单里的 mcode-tools。
- [文件与 Shell 工具](https://daiw.net/manual/minimax-code/file-and-shell.md): 读、写、编辑、搜索与 bash 的实现：pi 管什么、MiniMax 的包装加了哪些守卫与上限，以及一条 Shell 命令的执行路径与子进程环境清洗。
- [权限模式与规则](https://daiw.net/manual/minimax-code/permission.md): 工具调用前谁来拍板：三种权限模式的真实语义、规则写在哪与怎么写、询问怎样弹到 TUI、“始终允许”记在哪，以及 Bash 命令的分层判定。
- [沙箱：sandbox-runtime 的分叉](https://daiw.net/manual/minimax-code/sandbox.md): 仓库内置的 sandbox-runtime 分叉：上游版本与改动、三个平台各自的隔离机制，以及 v2 沙箱服务怎样只在 macOS 上包住 Bash。
- [浏览器工具](https://daiw.net/manual/minimax-code/browser-use.md): 打开 beta 开关后，MiniMax Code 经 CDP 驱动本地 headless Chrome：启动与会话隔离、给模型的语义树、24 个动作、截图产物与安全闸门。

### 第 4 部分 · Agent 模块

- [Agent 模块：扩展点与提醒](https://daiw.net/manual/minimax-code/agent-modules.md): agent-runtime 的扩展 SPI 怎样把功能挂进 pi 的回合循环，agent-modules 十二个子包各管什么，以及系统提醒、失控守卫、会话报告与引用溯源的实现。
- [上下文管理与压缩](https://daiw.net/manual/minimax-code/context-management.md): 单条工具输出的预算、自动压缩的两条阈值、先归档工具结果再写检查点摘要的流程，以及 /compact、/context 与压缩后用量重算的实现。
- [Plan 模式与目标](https://daiw.net/manual/minimax-code/plan-and-goal.md): Shift+Tab 与 /plan 怎样让会话进入只读规划、计划如何审批落地；/goal 设定的线程目标如何记账、判定完成，并驱动回合自动续跑。
- [子 Agent 与后台任务](https://daiw.net/manual/minimax-code/subagents.md): task 工具怎样新建隐藏子会话，子 Agent 看得到什么，结果怎样以工具结果或后台唤醒回到父回合，以及任务表与 TUI 的 Tasks 面板。
- [定时任务](https://daiw.net/manual/minimax-code/cron.md): 命令行版为什么没有定时任务，以及桌面端的 Cron 怎样工作：cron 命令、表达式与时区、调度器、Run 变成回合的过程、停机后的处理与三代存储。

### 第 5 部分 · 扩展与账号

- [技能](https://daiw.net/manual/minimax-code/skills.md): SKILL.md 从哪些目录被发现、同名时谁赢、内置技能怎样打包进产物，技能目录怎样按预算进入系统提示词，以及 skill 工具与斜杠命令两条调用路径。
- [插件系统](https://daiw.net/manual/minimax-code/plugins.md): 官方与本地两类插件源、四种清单格式、插件带来的技能与 MCP 与钩子等能力，快照怎样在回合之间发布，以及兼容 Claude Code 与 Codex 格式的钩子如何执行。
- [MCP](https://daiw.net/manual/minimax-code/mcp.md): 用户级 mcp.json、项目 .mcp.json 与 ACP 会话三层配置，三种传输与连接池，mcp__ 命名名册，按上下文占比决定的延迟披露，以及插件 MCP、权限与 OAuth 的现状。
- [账号、OAuth 与云端工具](https://daiw.net/manual/minimax-code/accounts-and-tools.md): MiniMax 账号的 OAuth 设备码登录、按命名空间落盘的凭据与跨进程协调、Token Plan 额度查询、工具子进程的短期令牌，以及云端工具的调用凭据。

### 第 6 部分 · 终端与接入

- [TUI 引擎](https://daiw.net/manual/minimax-code/tui-engine.md): 产品界面底下的渲染层是 pi-tui 0.84.2 的一份 fork：逐文件哈希与本地改动台账、主屏差量重绘与全屏视口、输入解析与宽字符，以及它和 third_party 里那份 pi-tui 的关系。
- [TUI 应用：控制器、功能与转录](https://daiw.net/manual/minimax-code/tui-app.md): 引擎之上的产品层：组合根怎样接起运行时端口、三层状态与十几个 flow，流式事件怎样投影成转录单元再画成终端行，以及斜杠命令、快捷键、@ 引用与审批卡片的实现。
- [Headless 与 ACP](https://daiw.net/manual/minimax-code/headless-and-acp.md): mcode exec 的参数、输出格式与退出码，无人值守时登录与权限的处理，以及 mcode acp 如何把 ACP 会话映射到运行时、把权限询问转给编辑器。
- [遥测、更新与诊断](https://daiw.net/manual/minimax-code/telemetry-and-update.md): 三个默认关闭、逐项同意的遥测通道，本地的事故记录与观测日志，签名清单与多种安装来源下的自更新，每日签到，以及排查问题用的诊断命令。
- [回顾](https://daiw.net/manual/minimax-code/recap.md): 全书要点串联：一条消息穿过的各层、值得记住的设计、与站内其他终端 Agent 的对照、文档与代码的出入，以及可迁移的经验和这份源码的短板。