monorepo 全景

规模

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 物理行。

合计 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）：

叶子包（零内部依赖）:
  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。

分层

核心包速览

引擎

• 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 请求库。

宿主与契约

• 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——同构的转录渲染数据层，零引擎依赖，也是转录契约类型的唯一所有者，见对应章节。

基础设施

• 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；一旦要同时支持浏览器、编辑器、远程访问和第三方宿主，每一层就都有了理由：

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

下一篇：怎么读这份源码。