Kimi Code 源码解读
逐层拆读月之暗面开源的终端编码 Agent「Kimi Code CLI」的 TypeScript 源码——一边讲怎么用，一边讲怎么实现。
Kimi Code CLI（命令行叫 kimi）是月之暗面开源的终端编码 Agent：跑在终端里的全屏 TUI，能读写代码、跑 shell、搜文件、抓网页，并根据反馈决定下一步。它同时还是一个 agent 引擎——同一个 agent-core-v2 被 CLI/TUI、Web UI、Remote Control、VS Code 插件、ACP 编辑器集成与 Node SDK 复用。
整个项目用 TypeScript 写成，是一个 19 个代码单元、约 38 万行非测试代码的 pnpm monorepo（口径见下）。
这个专栏把它逐层拆开读。
源码基准
本专栏所有引用以下述快照为准：
| 项 | 值 |
|---|---|
| 仓库 | github.com/MoonshotAI/kimi-code |
| tag | @moonshot-ai/[email protected] |
| commit | ffa94fae854dedf594919acbea280d98cbe8e14e |
| 版本 | @moonshot-ai/kimi-code v0.43.0 |
| 快照日期 | 2026-09-14 |
| 许可 | MIT |
| 运行要求 | Node.js >=24.15.0（.nvmrc 为 24.15.0），pnpm 10.33.0 |
所有路径都相对仓库根，例如 packages/agent-core-v2/src/agent/loop/loopService.ts。
关于这次复核：专栏最初对照 v0.29.1（commit 0cef160，2026-07-27）写成，现已按 v0.43.0 逐篇复核。两版相隔七周，改动 5013 个文件，新增约 40 万行、删除约 39 万行——v1 引擎 packages/agent-core 就在这期间被整个删掉。
规模口径：git 跟踪的 .ts / .tsx 文件，排除 test/ 目录与 *.test.* / *.spec.*，用 wc -l 数物理行（含空行）。pnpm-workspace.yaml 展开后有 22 个 workspace 项目；把 apps/vis 与它的 server、web 子包算作一个、不计文档站 docs，得到 19 个代码单元，合计 382688 行、2293 个文件。同口径下 v0.29.1 是 20 个单元、371179 行——总量几乎持平，内部却换了一轮血，细节见 monorepo 全景。
读者预设：默认你会读 TypeScript（async、泛型、装饰器、interface），不熟的语言点会在关键处就地补一句，但不系统教 TS。读过《从 LLM 到 Coding Agent》会更顺，但不是硬前提。
这个专栏怎么读
每一章尽量走两条线：
- 怎么用——这个功能在
kimi里长什么样、怎么配置； - 怎么实现——翻到对应包的源码，看它在底层到底怎么做。
侧重结构与数据流：讲清「一件事经过哪些包、数据怎么流、边界契约是什么」，而不是逐行贴代码——关键处才引一小段源码点睛。
和站内另外三本的关系
| 专栏 | 视角 |
|---|---|
| 《从 LLM 到 Coding Agent》 | 教学最小实现：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| 《Grok Build 源码解读》 | Rust 生产实现：xAI 的终端 Agent 怎么做 |
| 《OpenCode 源码解读》 | TypeScript + Effect 生产实现：同样的语言，另一套依赖组织 |
| 本专栏 | TypeScript 生产实现：DI × Scope 引擎，一套核心喂多个前端 |
Kimi Code 与 Grok Build 选型截然不同——TS vs Rust、DI 容器 vs 显式传参、多前端复用 vs 单一 TUI；与 OpenCode 同为 TypeScript，一边是 VS Code 式 DI，一边是 Effect 的 Service 与 Layer。更巧的是两者都经历了两代引擎：Kimi Code 已经换代完毕，OpenCode 还在迁移途中。对照着读，最能看出哪些是本质约束，哪些只是工程口味。
它有什么特别的
读之前先知道这份源码值得看的地方：
- 一套引擎，多个前端。TUI 与
kimi -p、Web UI、Remote Control、VS Code 插件、ACP 编辑器集成、Node SDK 共用agent-core-v2，靠 SDK 宿主层与klient契约门面解耦。 - 一次走完的引擎换代。v0.24 起服务端先切到 v2（v1 服务端包随之删除）；v0.29.1 时两代引擎仍同仓并存；v0.33 起 CLI 默认 v2（
KIMI_CODE_LEGACY_FLAG=1可回退）；v0.40 起kimi acp不再理会这个开关；到 v0.43.0，packages/agent-core已删除，回退开关也从代码里消失。这段演进本身就值得读。 - DI 外壳 + 纯内核。服务按 App / Session / Agent 三级
LifecycleScope注册，功能经features/的 Feature 接缝挂入；agent / turn / tool 状态机与单次 LLM 请求库放在不依赖 DI 的src/human/，边界由脚本强制。 - 无注释区。
agent-core-v2、kap-server、transcript禁止任何注释，pnpm lint里有脚本把关——读引擎只能靠类型、命名与测试。 - 自带底层轮子。
pi-tui（vendored 自上游 pi-mono、带本地补丁的差分渲染 TUI 库）、minidb（嵌入式 JSON 文档库，kap-server 搜索索引的底座）、tree-sitter-bash（纯 TypeScript 的 bash 解析器）。 - transcript 独立成包。渲染数据层被抽成四级（L1 存储 / L2 幂等操作 / L3 订阅粒度 / L4 视图注册），浏览器安全、零引擎依赖。
路线图
- 第 0 部分 · 导论与全景——它是什么、装上就跑、monorepo 全景、怎么读这份源码、一条消息的生命周期。
- 第 1 部分 · Agent 引擎内核——agent 循环、回合收敛、LLM 抽象层、上下文与投影、压缩、会话与存储、system prompt 组装。
- 第 2 部分 · 工具系统——工具契约与并发调度、文件工具、Shell/PTY、后台任务、Web 工具与服务注入、权限审批。
- 第 3 部分 · 扩展机制——MCP、Skills、Hooks、子代理与 swarm、Goal 与 Plan、插件市场。
- 第 4 部分 · 终端 UI——pi-tui 差分渲染、TUI 应用层。
- 第 5 部分 · 数据与持久化——minidb、transcript 四层模型、记录与回放。
- 第 6 部分 · 服务形态——kap-server 与 REST/WS、klient 契约门面与 ACP 服务端。
- 第 7 部分 · 架构演进——agent-core-v2 的 DI × Scope 与 v1 → v2 换代、kaos 执行环境抽象、收尾复盘。
准备好了，就从 Kimi Code 是什么 开始。