# Kimi Code 源码解读

> 逐层拆读月之暗面开源的终端编码 Agent「Kimi Code CLI」的 TypeScript 源码——一边讲怎么用，一边讲怎么实现。

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

[Kimi Code CLI](https://github.com/MoonshotAI/kimi-code)（命令行叫 `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](https://github.com/MoonshotAI/kimi-code) |
| tag | `@moonshot-ai/kimi-code@0.43.0` |
| 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`。

<Callout type="info">
  **关于这次复核**：专栏最初对照 v0.29.1（commit `0cef160`，2026-07-27）写成，现已按 v0.43.0 逐篇复核。两版相隔七周，改动 5013 个文件，新增约 40 万行、删除约 39 万行——v1 引擎 `packages/agent-core` 就在这期间被整个删掉。
</Callout>

**规模口径**：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 全景](https://daiw.org/manual/kimi-code/monorepo-map)。

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

## 这个专栏怎么读

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

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

侧重**结构与数据流**：讲清「一件事经过哪些包、数据怎么流、边界契约是什么」，而不是逐行贴代码——关键处才引一小段源码点睛。

## 和站内另外三本的关系

| 专栏 | 视角 |
| --- | --- |
| [《从 LLM 到 Coding Agent》](https://daiw.org/manual/llm-to-agent) | **教学最小实现**：一个 Coding Agent 在裸 LLM API 之上该做哪些事 |
| [《Grok Build 源码解读》](https://daiw.org/manual/grok-build) | **Rust 生产实现**：xAI 的终端 Agent 怎么做 |
| [《OpenCode 源码解读》](https://daiw.org/manual/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 是什么](https://daiw.org/manual/kimi-code/what-is-kimi-code) 开始。

## 本专栏篇目

- [Kimi Code 源码解读](https://daiw.org/manual/kimi-code.md): 逐层拆读月之暗面开源的终端编码 Agent「Kimi Code CLI」的 TypeScript 源码——一边讲怎么用，一边讲怎么实现。

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

- [Kimi Code 是什么](https://daiw.org/manual/kimi-code/what-is-kimi-code.md): 装上就跑、命令面、七种运行形态，以及它与「一个 CLI 工具」的区别。
- [monorepo 全景](https://daiw.org/manual/kimi-code/monorepo-map.md): 19 个代码单元的职责、规模与依赖关系，以及分层背后的约束。
- [怎么读这份源码](https://daiw.org/manual/kimi-code/reading-the-source.md): AGENTS.md 分层、设计文档与生成清单、无注释区、导入边界、实验开关、TS 设定与几条阅读捷径。
- [一条消息的生命周期](https://daiw.org/manual/kimi-code/message-lifecycle.md): 从敲下回车到屏幕上出现回复——横穿 TUI、SDK、klient、Agent 级服务、human 状态机与工具层。

### 第 1 部分 · Agent 引擎内核

- [Agent 循环：三台状态机](https://daiw.org/manual/kimi-code/agent-loop.md): v2 的循环由 human 层的 agent、turn、tool 三台状态机与 Agent 级的 AgentLoopService 组成：分工、step 门控、钩子、工具结果侧信道与并发调度。
- [回合收敛与异常吸收](https://daiw.org/manual/kimi-code/turn-convergence.md): 错误归类、step 内重试、投影降级、上下文溢出与中止路径——provider 层的失败如何被吸收成一次可完成或能明确失败的回合。
- [kosong：LLM 抽象层](https://daiw.org/manual/kimi-code/kosong.md): kosong 的 provider 适配、finish reason 归一化与 thinking 档位，以及它在 v0.43 里的新位置：v2 引擎改用自带的 human/llm 请求库。
- [上下文与投影](https://daiw.org/manual/kimi-code/context.md): ContextMessage 与线上消息的分离、投影器的配对修复与 strict 模式、工具结果渲染、动态工具与注入格式。
- [上下文压缩](https://daiw.org/manual/kimi-code/compaction.md): 触发与阻塞阈值、HEAD+TAIL 保留策略、摘要与续接提醒、指回事件日志的 Context Recovery，以及压缩请求自身的失败处理。
- [会话与存储](https://daiw.org/manual/kimi-code/session.md): Session 与 Agent 两级 scope 的分工、磁盘布局与会话索引、fork、prompt 生命周期，以及 v2 的 DI 与 Feature 接缝。
- [提示词与注入](https://daiw.org/manual/kimi-code/prompt-system.md): 提示词即资源文件的工程约定、system.md 模板与 profile 体系，以及由提醒服务统一调度的运行时注入。

### 第 2 部分 · 工具系统

- [工具契约与注册](https://daiw.org/manual/kimi-code/tool-contract.md): 两段式的 ExecutableTool 契约、zod schema 与描述模板、从贡献点到工具表的注册链路，以及一次工具调用经过的执行管线。
- [文件工具](https://daiw.org/manual/kimi-code/file-tools.md): Read 的字符预算与续读、编码与行尾处理、Edit 的唯一性校验、Grep / Glob 的 ripgrep 集成与敏感文件过滤。
- [Shell 工具](https://daiw.org/manual/kimi-code/shell-tools.md): Bash 工具的依赖注入与执行通道、跨平台 shell 选型、四条加固措施、前后台统一的任务模型，以及 tree-sitter-bash 在命令分析中的角色。
- [后台任务系统](https://daiw.org/manual/kimi-code/background.md): AgentTaskService 的开放任务类型、把「等用户回答」也建模成任务、落盘与 lost 状态、两阶段 kill、完成通知，以及四个后台工具。
- [Web 工具与服务注入](https://daiw.org/manual/kimi-code/web-tools.md): FetchURL 与 WebSearch 的「工具定接口、服务挑实现」模式，「无实现即不暴露」在 v2 里的新写法，以及加工内容的如实标注。
- [权限与审批](https://daiw.org/manual/kimi-code/permission.md): 三种权限模式、规则 DSL、13 条策略的责任链、挂在执行前事件上的审批与否决，以及基于 tree-sitter-bash 的危险命令守卫。

### 第 3 部分 · 扩展机制

- [MCP 集成](https://daiw.org/manual/kimi-code/mcp.md): 三种传输、工具命名的 64 字符约束与哈希截断、按 Scope 分层的连接管理、OAuth 授权工具与三层配置文件。
- [Skills](https://daiw.org/manual/kimi-code/skills.md): 五路来源与优先级、SKILL.md 与 frontmatter 解析、参数展开时的 XML 转义、Skill 工具与 /skill 斜杠命令，以及「能力即 Markdown」的实现路径。
- [Hooks](https://daiw.org/manual/kimi-code/hooks.md): features/externalHooks 的 20 个生命周期事件、App/Session/Agent 三层分工、退出码 2 的阻断语义，以及 Skills 与 Hooks「建议 vs 规则」的分工。
- [子代理与 swarm](https://daiw.org/manual/kimi-code/subagents.md): agent/coder/explore/plan 四个内置 profile、Agent/AgentSwarm 两个工具、swarm 模式的三种触发与提醒注入，以及防止无限委派的白名单。
- [Goal 与 Plan](https://daiw.org/manual/kimi-code/goal-plan.md): 三维预算的长程目标系统、GoalActor 归因与自动续跑，以及计划模式的文件化交接、写入守卫与审阅。
- [插件与市场](https://daiw.org/manual/kimi-code/plugins.md): 清单格式与路径逃逸检查、未支持字段的诊断、插件能带来的七类东西、tier 与三级信任标签、GitHub 直装。

### 第 4 部分 · 终端 UI

- [pi-tui：差分渲染](https://daiw.org/manual/kimi-code/pi-tui.md): 从上游 vendored 而来的终端 UI 库：三种渲染策略、CSI 2026 同步输出、主屏与全屏两套渲染器、Terminal 抽象与粘贴处理。
- [TUI 应用层](https://daiw.org/manual/kimi-code/tui-app.md): KimiTUI 协调器与控制器分工、反向 RPC 的模态协调、slash 命令注册表、流式渲染，以及只经 SDK 的引擎边界。

### 第 5 部分 · 数据与持久化

- [minidb：自研嵌入式数据库](https://daiw.org/manual/kimi-code/minidb.md): 从通用 KV 库到搜索索引与会话索引的底座——WAL + 快照、独占写锁、持久化索引代与大于内存的全文层。
- [transcript 四层模型](https://daiw.org/manual/kimi-code/transcript.md): L1 存储 / L2 幂等操作 / L3 订阅粒度 / L4 视图注册，序列号契约，以及从 wire.jsonl 冷重建的两级折叠。
- [记录、回放与撤销](https://daiw.org/manual/kimi-code/records-replay.md): wire.jsonl 的版本迁移与修复、blobref 卸载、静默回放的恢复契约，以及基于分支树的撤销与压缩边界。

### 第 6 部分 · 服务形态

- [kap-server 与协议](https://daiw.org/manual/kimi-code/kap-server.md): REST 与三条 WS 通道、反射式调试 RPC、事件分发的三层过滤，以及新增的全局搜索与 Remote Control。
- [klient、SDK 与 ACP](https://daiw.org/manual/kimi-code/klient-acp.md): 契约驱动门面的三段式 API 与两种传输、直连 v2 引擎的 acp-server、node-sdk 的 v2 客户端，以及 OAuth、遥测与迁移。

### 第 7 部分 · 架构演进

- [agent-core-v2：唯一的引擎](https://daiw.org/manual/kimi-code/agent-core-v2.md): v1 退场、v2 接管的时间线，三层作用域与工作区实例，Service/Fiber 单元层与 Feature 接缝，以及 human 内核的边界。
- [kaos：执行环境抽象](https://daiw.org/manual/kimi-code/kaos.md): 统一的文件与进程 API、本地与 SSH 两种实现、withCwd 的不可变设计，以及 v2 引擎用 os/ 与 Runtime 接过这层抽象之后 kaos 的位置。
- [收尾复盘](https://daiw.org/manual/kimi-code/recap.md): 全书要点串联、与 llm-to-agent / Grok Build / OpenCode 的四方对照，以及可迁移的工程经验。