# monorepo 全景

> 19 个代码单元的职责、规模与依赖关系，以及分层背后的约束。

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

## 规模

`pnpm-workspace.yaml` 声明的成员是 `packages/*`、`apps/*`、`apps/vis/server`、`apps/vis/web`、`docs`，展开后共 22 个 workspace 项目。下表把 `apps/vis` 与它的 server、web 子包并作一行、不计文档站，得到 19 个代码单元。口径：git 跟踪的 `.ts` / `.tsx`，排除 `test/` 目录与 `*.test.*` / `*.spec.*`，`wc -l` 物理行。

| 包 | LOC | 文件 | 职责 |
| --- | --- | --- | --- |
| `packages/agent-core-v2` | 135658 | 1037 | **唯一的 agent 引擎**（DI × Scope） |
| `apps/kimi-code` | 66699 | 338 | CLI / TUI 应用 |
| `packages/kap-server` | 38281 | 220 | REST + WS 服务端 |
| `packages/minidb` | 23215 | 81 | 嵌入式 JSON 文档库 |
| `apps/vscode` | 18284 | 127 | VS Code 插件 |
| `packages/pi-tui` | 17244 | 41 | 终端 UI 库（差分渲染） |
| `packages/node-sdk` | 12241 | 65 | TypeScript SDK 与宿主层 |
| `apps/kimi-inspect` | 11850 | 59 | kap-server 调试面的检查器 |
| `apps/vis` | 11431 | 81 | 会话可视化调试器 |
| `packages/kosong` | 9240 | 28 | LLM 抽象层（引擎已不用） |
| `packages/klient` | 8056 | 59 | 引擎之上的契约门面 |
| `packages/oauth` | 6107 | 28 | Kimi OAuth |
| `packages/acp-server` | 5647 | 28 | ACP 服务端 |
| `packages/tree-sitter-bash` | 5021 | 9 | 纯 TS 的 bash 解析器 |
| `packages/migration-legacy` | 4060 | 34 | 旧版 kimi-cli 数据迁移 |
| `packages/transcript` | 3696 | 27 | 转录渲染数据层 |
| `packages/kaos` | 3187 | 14 | 执行环境抽象（引擎已不用） |
| `packages/remote-control` | 1492 | 6 | Remote Control 隧道客户端 |
| `packages/telemetry` | 1279 | 11 | 遥测 |

合计 **382688 行、2293 个文件**（含 `agent-core-v2/docs/` 下两份生成的 `.d.ts` 清单，2212 行）。

同口径下，v0.29.1 是 20 个单元、371179 行。总量几乎持平，结构却换了一轮：`packages/agent-core`（66120 行）、`packages/acp-adapter`（5555）、`packages/protocol`（5302）整包删除，`apps/kimi-web`（25618）移出仓库——Web UI 改在另一个仓库开发，以预构建产物 `apps/kimi-code/dist-web` 随 CLI 发布；新增 `acp-server`、`tree-sitter-bash`、`remote-control`；`agent-core-v2` 从 97535 行涨到 135658 行。

## 依赖关系

内部包之间的依赖（只列 `@moonshot-ai/*`，略去仅供测试的 devDependencies）：

```text
叶子包（零内部依赖）:
  kosong   kaos   minidb   oauth   pi-tui
  telemetry   transcript   tree-sitter-bash

引擎:
  agent-core-v2    → oauth, minidb, tree-sitter-bash

围绕引擎:
  klient           → agent-core-v2
  acp-server       → agent-core-v2, klient
  kap-server       → agent-core-v2, oauth, minidb, remote-control, transcript
  remote-control   → agent-core-v2, oauth
  migration-legacy → agent-core-v2
  node-sdk         → agent-core-v2, klient, kosong, kaos, oauth  (devDeps，构建时打包)

应用层:
  apps/kimi-code    → node-sdk, pi-tui, telemetry, oauth, kap-server, acp-server,
                      agent-core-v2, minidb, remote-control, migration-legacy, vis-*
  apps/vscode       → node-sdk, oauth, migration-legacy
  apps/kimi-inspect → agent-core-v2, kap-server
```

几个值得注意的地方：

**引擎不再依赖 kosong 与 kaos。** 模型请求在 `agent-core-v2/src/human/llm/` 与 `src/llm-adapter/`，宿主文件系统与进程在 `src/os/`；这两个 v1 时代的底座包只剩 node-sdk 声明依赖（kaos 只用作类型）。引擎的导入检查脚本里干脆写着「the kosong kernel is deleted」。

**node-sdk 的 devDependencies 不是「只取类型」。** `tsdown.config.ts` 的 `alwaysBundle: [/^@moonshot-ai\//]` 让它们在构建时整体打进 SDK；运行时 SDK 在进程内 `bootstrap()` 引擎，再经 klient 内存传输调用。

**TUI 只经 SDK，CLI 另有捷径。** 根 `AGENTS.md` 的规则：

> `apps/kimi-code`: the CLI / TUI application. It consumes core capabilities through `@moonshot-ai/kimi-code-sdk` and must not depend directly on engine packages.

`src/tui/` 下确实没有一处 import 引擎。但 CLI 有 9 个源文件直接 import 了 `agent-core-v2` 或 `kap-server`：`kimi web`（`cli/sub/web/`）、print 模式（`cli/v2/run-v2-print.ts`）、配置校验（`cli/v2/validate-config.ts`），以及插件市场常量、原生搜索 worker 等；`kimi acp`、`kimi vis` 则在运行时懒加载 `acp-server` 与 `vis-server`。

## 分层

```mermaid
flowchart TB
    subgraph 前端
        TUI[apps/kimi-code<br/>TUI]
        PRINT[kimi -p]
        VSC[apps/vscode]
        WEB[Web UI<br/>dist-web]
        ACPC[ACP 编辑器]
    end
    subgraph 宿主与契约
        SDK[node-sdk]
        KL[klient<br/>门面 + zod]
        KAP[kap-server<br/>REST + WS]
        ACPS[acp-server]
        RC[remote-control]
    end
    subgraph 引擎
        DI[agent-core-v2<br/>DI × Scope 服务]
        HU[human<br/>状态机 + llm 请求库]
    end
    subgraph 基础设施
        MDB[minidb]
        TR[transcript]
    end

    TUI --> SDK
    VSC --> SDK
    PRINT --> DI
    SDK --> KL
    ACPC --> ACPS
    ACPS --> KL
    WEB --> KAP
    RC -.隧道.-> KAP
    KL --> DI
    KAP --> DI
    KAP --> TR
    DI --> HU
    DI --> MDB
```

## 核心包速览

### 引擎

- **`agent-core-v2`**——服务按 `app/scopes.ts` 的 App / Session / Agent 三级 `LifecycleScope` 注册（`registerScopedService` 共 138 处：App 75、Session 18、Agent 45）；工作区不是 DI 作用域，由 App 级的 `IWorkspaceInstanceManager` 按根目录管理。功能以 `features/` 下的 Feature 接入，经 `contribute*` 往贡献点挂配置、工具、命令。纯内核 `src/human/` 放基于 xstate 的 agent / turn / tool 状态机与单次 LLM 请求库。

<Callout type="warn">
  根 `AGENTS.md` 写的是四级 `LifecycleScope`（多一个 Workspace），枚举里实际只有三级；工作区对应的是 `WorkspaceInstance`，生成的状态清单 `packages/agent-core-v2/docs/state-manifest.d.ts` 也把 Workspace 状态单列一层。
</Callout>

### 宿主与契约

- **`node-sdk`**（`@moonshot-ai/kimi-code-sdk`）——`KimiHarness` 与 `Session` 两个主对象；TUI 与 VS Code 插件都经 `createKimiHarness` 进入。
- **`klient`**——契约驱动的门面，`global.*` / `session(id).*` / `session(id).agent(id).*` 三组方法，每次调用都做 zod 校验；schema 手工镜像引擎类型，由 `test/contract-parity.ts` 的编译期断言钉住。传输经 `/ipc` 或 `/memory` 子路径入口选定。
- **`kap-server`**——`/api/v1` REST + `/api/v1/ws`，外加 `--debug-endpoints` 打开的 `/api/v1/debug/*` 反射式 RPC 面（`apps/kimi-inspect` 是它的前端）。
- **`acp-server`**——「ACP host backed directly by the DI × Scope agent engine」，组合方式同 SDK：`bootstrap()` + klient 内存传输。
- **`remote-control`**——隧道客户端（全机单实例锁），供 kap-server 与 `kimi web --remote-control` 使用。
- **`transcript`**——同构的转录渲染数据层，零引擎依赖，也是转录契约类型的唯一所有者，见[对应章节](https://daiw.org/manual/kimi-code/transcript)。

### 基础设施

- **`minidb`**——仓库自己的包。`package.json` 描述还停在「KV 数据库」，根 `AGENTS.md` 的定位已是 kap-server 搜索索引背后的嵌入式 JSON 文档库：快照 + WAL、独占写锁、超出内存的全文检索层、持久化索引代。
- **`pi-tui`**——差分渲染终端 UI 库，不用 Ink，不用 React；是从上游 pi-mono vendored 的副本（基线 upstream 0.80.2），本地修补逐条登记在包内 `AGENTS.md`，每条都有守护测试。
- **`tree-sitter-bash`**——纯 TypeScript 的 bash 解析器（无运行时依赖、无 wasm），在确定性预算下解析；中止或出错的树由调用方当作「无法分析」降级。

## 为什么要这么多层

直接原因就一个：**同一个引擎要喂一圈前端**。只有 TUI 的话，引擎完全可以被直接 import；一旦要同时支持浏览器、编辑器、远程访问和第三方宿主，每一层就都有了理由：

| 层 | 解决的问题 |
| --- | --- |
| `node-sdk` | Node 宿主（TUI、VS Code）共用一套会话 API，审批与提问统一桥接给 UI |
| `klient` | 调用契约化、可校验；内存与 ipc 两种传输行为一致 |
| `kap-server` + `remote-control` | 浏览器与远程访问也能用 |
| `acp-server` | 编辑器走 ACP 协议 |
| `transcript` | 渲染数据层与引擎解耦，服务端与浏览器共用一份实现 |
| `human` 内核 | 状态机与请求逻辑脱离 DI，只经三个适配层接入 |

读的时候带着这个视角，很多「为什么不直接调」的疑问会自动消解。

下一篇：[怎么读这份源码](https://daiw.org/manual/kimi-code/reading-the-source)。