先说说项目定位。kimi-code 是 Moonshot AI 开源的一个 AI 编程 Agent。它直接运行在终端里。但别把它当成一个简单的代码生成工具——它能读写代码、执行 shell 命令、搜索文件、抓取网页。更关键的是，它会根据执行结果自主决策下一步动作。你可以把它想象成一个住在你终端里的 AI 工程师。它能理解你的意图，在你的文件系统里自由行动，然后根据结果调整策略。

从技术架构来看，这是一个 TypeScript monorepo，用 pnpm workspace 管理，要求 Node.js >= 24.15.0。根包名是 @moonshot-ai/monorepo，采用 MIT 许可。整个项目由 5 个应用和 15 个包组成，代码组织清晰、职责分明。

它的设计目标不是“又一个 AI 编程助手”，而是构建一个可扩展的 Agent 平台。从最初 V1 的单体 Agent 架构，到正在演进的 V2 DI x Scope 架构，kimi-code 正在从“能用”走向“可组合、可隔离、可持久化”的工程化 Agent 基础设施。

关键理念：kimi-code 认为代码本身才是真相之源（“Treat code, not documentation, as the source of truth”）。文档是辅助，代码才是权威。这个理念贯穿整个项目的设计与开发流程。

Monorepo 全景结构

工作空间定义

项目的 pnpm-workspace.yaml 定义了整个 monorepo 的边界：

packages:
  - packages/*
  - apps/*
  - apps/vis/server
  - apps/vis/web
  - docs

catalog:
  zod: 4.3.6

除了 packages/* 和 apps/* 的标准 glob 模式，这里特别把 apps/vis 的 server 和 web 拆成了两个独立工作空间。这说明 vis 模块本身就是一个小型 monorepo，server 端和 web 端有各自独立的依赖和构建流程。

catalog 字段是 pnpm workspace 的版本统一机制。这里把 zod 锁定在 4.3.6，确保整个项目中所有包使用相同版本的 schema 验证库。这在 TypeScript monorepo 中是一种常见的最佳实践，能避免多版本并存导致的类型冲突。

5 个应用

• apps/kimi-code：核心终端应用。技术栈：TypeScript CLI/TUI。使用自研的 @moonshot-ai/pi-tui 差分渲染终端 UI 库，支持 ACP (Agent Client Protocol) 协议，可打包为 SEA (Single Executable Application) 独立二进制文件。作为 kimi 命令的入口，同时驱动 V1 和 V2 两条通路：V1 直连 node-sdk → agent-core，V2 作为 kap-server 的宿主进程。
• apps/kimi-web：浏览器端 UI。技术栈：Vue 3 + Vite + vue-i18n。通过 REST + WebSocket 与后端 kap-server 通信，完全不依赖 agent-core（wire types 在本地重新实现），保证前后端解耦。支持 xterm 终端渲染、Mermaid 图表、KaTeX 公式、Shiki 代码高亮。
• apps/vscode：VS Code Extension。将 kimi-code 的能力集成到 IDE 中。
• apps/vis：会话回放与调试可视化工具。拆分为 apps/vis/server 和 apps/vis/web 两个独立工作空间，用于可视化和分析 agent 会话的执行过程。
• apps/kimi-inspect：Web 检查器。技术栈：React 19 + Tailwind。调试 kap-server 的 /api/v1/debug RPC 接口。通过 VS Code 风格的 ProxyChannel 模型与后端通信，可浏览 workspace/session、查看模型目录（Model Catalog）、检查 App Services。左侧 NavRail 切换 Chat、Model Catalog、App Services 三个视图。

15 个包

这 15 个包按功能可以划分为六个层次：

核心引擎

• agent-core (v0.15.6)：V1 统一智能体引擎。包含完整的 Agent 生命周期管理、Session 管理、工具系统（tools）、技能系统（skills）、计划系统（plan）、权限控制（permission）、后台任务（background）、上下文压缩（compaction）、多袋里协作（swarm）、MCP 集成、插件系统（plugin）、profile 管理等。这是当前生产环境的主力引擎。
• agent-core-v2 (v0.2.0)：V2 DI x Scope 引擎。基于依赖注入容器和服务作用域的下一代架构，将 V1 中耦合在 Agent 类中的子系统拆解为 app/、session/、agent/ 三个生命週期层级的独立 Service。这是项目的战略演进方向。

SDK 与客户端

• node-sdk（发布名 @moonshot-ai/kimi-code-sdk, v0.14.0）：公共 TypeScript SDK，是 apps 和 agent-core 之间的中间层。所有 apps 必须通过 node-sdk 间接使用引擎能力，不能直接依赖 agent-core。
• klient (v0.1.0)：V2 客户端门面。提供 global.* / session(id).* / agent(id).* 三层聚合 API，每个调用经过 zod 验证，支持 IPC 和内存两种 transport。这是面向 V2 引擎的规范客户端。

LLM 抽象

• kosong (v0.5.5)：供应商中立的 LLM 抽象层。封装了 Anthropic、OpenAI（含 Legacy Chat Completions 和新的 Responses API）、Google GenAI、Kimi 等多个 provider，提供统一的 generate / tool-call / streaming 接口。这是整个 Agent 系统与外部大模型通信的唯一通道。

执行环境

• kaos (v0.1.6)：文件系统和进程执行的抽象层。将底层 I/O（文件读写、shell 执行）从业务逻辑中抽离，同时支持本地和 SSH 远程两种执行模式（导出 ./ssh 子路径）。设计上借鉴了 AsyncLocalStorage 模式传递实例，避免在函数签名中显式传递执行上下文。

数据与协议

• transcript (v0.0.1)：同构会话记录数据模型。四层架构：L1 按 agent 粒度存储、L2 幂等操作、L3 按 off/turn/block/delta 粒度订阅、L4 视图注册。纯 TypeScript（browser-safe），不依赖引擎。同时管理 plan 内容的持久化（将 ExitPlanMode 的 review submission 存入 agents/{agentId}/plan/{planId}/v{N}.md）。
• protocol (v0.5.0)：共享的 REST + WebSocket 协议 schema。定义了 envelope、error codes、pagination、ws-control 等标准约定，使用 zod 做运行时校验。
• minidb (v0.2.0)：纯 Node.js 嵌入式 KV 数据库。结合了 Redis 风格的内存 KV 操作和 SQLite 风格的持久化（WAL + snapshot），支持 compound index、text index、skiplist、cluster 模式。V2 引擎通过它实现完整的数据持久化。

服务器

• kap-server (v0.1.0)：基于 Fastify 的 REST + WebSocket 服务器，暴露 V2 引擎的能力。提供 /api/v1 的 REST 接口和 /api/v1/ws 的 WebSocket 通道。debug 模式下可开启 /api/v1/debug/* 反射路由，动态调用 DI 容器中注册的所有 Service——这是一个非常强大的调试能力。

UI 库

• pi-tui (v0.80.8)：自研的终端 UI 库。核心特性是差分渲染——只更新终端中变化的部分，避免全屏重绘带来的闪烁和性能问题。支持 xterm headless 模式，是这个项目中最具技术特色的基础设施之一。

集成与工具

• acp-adapter (v0.3.5)：Agent Client Protocol 适配器，将 kimi-code 的 Agent 暴露为 ACP 兼容的服务，实现跨平台的 Agent 互操作。
• oauth：Kimi OAuth 认证工具集。
• migration-legacy：旧版数据迁移工具。
• telemetry (v0.1.1)：客户端遥测基础设施，共享的事件上报机制。

两代引擎架构（核心）

理解 kimi-code 的关键，在于理解它正在经历一场从 V1 到 V2 的架构演进。这不是简单的代码重构，而是 Agent 架构哲学的根本转变。

V1 通路：单体 Agent 引擎（当前生产环境）

V1 的数据通路如下：

apps/kimi-code (CLI/TUI)
└── @moonshot-ai/kimi-code-sdk (node-sdk) ← 强制依赖边界：apps 不能直接依赖 agent-core
    └── @moonshot-ai/agent-core ← 统一智能体引擎
        ├── @moonshot-ai/kosong ← LLM 提供者抽象（Anthropic/OpenAI/Google/Kimi）
        ├── @moonshot-ai/kaos ← 文件系统 + 进程执行 + SSH 抽象
        └── @moonshot-ai/protocol ← REST + WS 模式定义

V1 的设计思路是 “把所有能力组装进一个 Agent 类”。在 packages/agent-core/src/agent/ 目录下，你能看到所有子系统——tool、skill、plan、permission、compaction、swarm、background、goal、cron——都是作为 Agent 的直接组合成员存在的。这是一个典型的单体 Agent 架构。

V1 的 Agent 类必须自给自足——AGENTS.md 明确要求：“The Agent class must be usable on its own. The constructor must not force the caller to create a Session instance.” 这意味着 Agent 是一个独立的、可单独实例化的单元，不强制绑定 Session 生命周期。

这种设计的优势是简单直接：对于 CLI 这种单一用户、单一会话、单一执行上下文的场景，单体架构足够了。所有状态都在内存中，不需要复杂的生命周期管理。

但它的局限也很明显：

• 耦合度高：所有子系统直接组合在 Agent 类中，难以独立测试或替换
• 无持久化：状态存于内存，进程重启即丢失
• 无法隔离：多个 Agent 实例之间无法做资源或权限隔离
• 扩展受限：添加新的能力维度需要修改 Agent 核心类

V2 通路：DI x Scope 架构（下一代）

V2 的数据通路发生了根本变化：

apps/kimi-code (宿主进程，启动后端服务器)
└── @moonshot-ai/kap-server (Fastify REST + WS)
    └── @moonshot-ai/agent-core-v2 (DI x Scope 引擎)
        ├── @moonshot-ai/minidb ← 持久化（WAL + Snapshot）
        └── 内联 kosong 提供者 ← 直接在 engine 内管理 provider

apps/kimi-web (Vue 3 浏览器 UI) ──REST/WS──→ kap-server
apps/kimi-inspect (React 调试 UI) ──debug──→ kap-server

V2 架构的核心变化是引入 DI (Dependency Injection) 容器 + Scope 生命周期。这是从 VS Code 的 createDecorator 模式借鉴来的设计模式，将整个 Agent 系统划分为三个生命週期层级：

• App Scope（目录 src/app/）：进程级，随服务器启动创建。典型 Service：agentFileCatalog、auth、config、cron、flag、gateway、plugin、sessionIndex、telemetry、workspace。
• Session Scope（目录 src/session/）：会话级，随会话创建/销毁。典型 Service：agentLifecycle、approval、interaction、sessionContext、sessionFs、sessionMetadata、swarm、terminal、todo。
• Agent Scope（目录 src/agent/）：Agent 实例级，随 Agent 创建/销毁。典型 Service：activityView、contextInjector、contextMemory、goal、llmRequester、loop、mcp、permissionGate、plan、prompt、skill、task、toolExecutor、toolRegistry、usage。

每一层通过 DI 容器管理依赖关系，Service 通过接口声明依赖，由容器负责注入和生命周期管理。基础 DI 设施在 src/_base/di/ 中实现，包含 InstantiationService、ServiceCollection、scope 管理等核心组件。

这种架构带来的关键改进：

• 关注点分离：50+ 个 Service 各有明确的职责边界（每个都有 domain 注释标注责任），不再是一个巨大的 Agent 类
• 多租户隔离：不同 Session、不同 Agent 通过独立的 Scope 实例天然隔离，互不干扰
• 持久化层：通过 IAppendLogStore、IAtomicDocumentStore、IBlobStore 等抽象接口引入 minidb 作为持久化后端，实现数据不丢失（WAL + Snapshot 机制）
• 可测试性：每个 Service 可以独立测试，有专门的 TestInstantiationService 和 createScopedTestHost 测试工具
• 可观察性：debug 模式下，kap-server 通过 /api/v1/debug/* 反射路由暴露整个 DI 注册表，所有 Service 都可以远程调用检查——这是 V1 无法做到的
• 事件驱动：V2 提供了 async event queue，Service 之间通过类型化事件通信，解耦度更高

架构洞察：V2 的 DI x Scope 架构本质上是在回答一个问题—— “如何让一个 Agent 系统像操作系统一样运行？” App Scope 相当于内核空间（进程级常驻服务），Session Scope 相当于用户会话，Agent Scope 相当于进程实例。minidb 的 WAL + Snapshot 持久化机制让人联想到数据库的崩溃恢复，整个设计有浓厚的系统软件美学。

为什么要做 V2 重写？

这不是简单的“新技术更好”式的重写。V1 的单体 Agent 架构在以下场景中暴露了结构性瓶颈：

1. 多会话并存：CLI 场景下用户只有一个活动会话，但 kimi-web 需要同时管理多个会话。V1 没有“会话”这个生命週期概念，所有状态混在 Agent 中。
2. 状态持久化：V1 的会话状态完全在内存中。用户关闭终端再重新打开，所有上下文丢失。V2 通过 minidb 的 WAL + Snapshot 机制实现崩溃恢复和会话持久化。
3. 多 Agent 协作：V1 的 swarm 模块是 Agent 内部的一个子系统，无法真正实现 Agent 间的独立隔离。V2 中每个 Agent 有独立的 Scope，Swarm 管理多个 Agent Scope，隔离是架构层面的。
4. 调试与可观察性：V1 是一个黑盒。V2 的 debug 端点允许通过 HTTP 直接查询任何 Service 的内部状态。

V2 目前版本号为 0.2.0，文档中标注为 “work-in-progress port of packages/agent-core”，参考设计文档在 plan/PLAN.md，迁移状态在 GAP_ANALYSIS.md。这说明团队正在有计划地、逐步地将 V1 的能力迁移到 V2 架构下。

构建与开发工作流

kimi-code 的工程化程度相当高，体现了专业团队的标准实践。

技术选型一览

• 构建工具：tsdown(v0.22.0)，基于 rolldown 的 TypeScript 构建器，替代 tsup
• TypeScript：6.0.2，项目级别统一版本
• 代码检查：oxlint(v1.59.0)，Rust 实现的 ESLint 替代，速度极快
• lint-staged：16.4.0，仅对 staged 文件做检查
• 测试：vitest(v4.1.4)，Vite 原生的测试框架
• 版本管理：changesets(v2.30.0)，管理 changelog 和版本发布
• 包管理：pnpm(v10.33.0)，workspace 协议管理 monorepo
• Git hooks：simple-git-hooks，替代 husky 的轻量方案
• 包检查：publint + arethetypeswrong，发布前验证包的完整性和类型正确性

开发命令

# CLI 终端应用（V1 通路）
pnpm dev:cli

# Web 浏览器 UI
pnpm dev:web

# kap-server 后端（V2 通路）
pnpm dev:kap-server

# 多会话测试（V2 通路）
pnpm dev:v2

# 可视化调试工具
pnpm vis

# 类型检查（构建所有 packages 后逐包检查）
pnpm typecheck

# lint（使用 oxlint）
pnpm lint
pnpm lint:fix

# 测试（vitest）
pnpm test
pnpm test:watch
pnpm test:coverage

TypeScript 严格配置

项目的 tsconfig 非常严格，体现了对代码质量的重视：

{
  "compilerOptions": {
    "target": "ES2024",
    "module": "preserve",
    "moduleResolution": "bundler",
    "strict": true,
    "isolatedModules": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "verbatimModuleSyntax": true,
    "experimentalDecorators": true,
    "declaration": true,
    "noEmit": true
  }
}

几个值得注意的选项：

• "module": "preserve"：保持源码中的 import/export 不变，由 bundler 处理模块解析——这是面向现代构建工具链的标准实践
• "noUncheckedIndexedAccess": true：索引访问返回 T | undefined，强制处理可能不存在的键——这是 TypeScript 中最严格也最有价值的选项之一
• "experimentalDecorators": true：启用了装饰器支持，这是 V1 和 V2 中 DI 装饰器语法（如 @IService）的基础
• "verbatimModuleSyntax": true：禁止类型导入被意外抹除，确保代码的运行时语义清晰

发布流程

通过 pnpm publish 可以看到完整的发布质量门禁：typecheck → lint → sherif（workspace 一致性检查）→ test → build → lint:pkg（publint + arethetypeswrong）→ changeset publish。七步检查，一步失败则中止发布。这种严谨程度在开源项目中属于上游水平。

关键设计哲学

“代码是真相之源”

来自 AGENTS.md 的核心理念：“Treat code, not documentation, as the source of truth.” 这不仅是文档规范，更是工程信仰。在这个项目中，代码结构本身就是文档——AGENTS.md 中不描述实现细节，只描述“是什么”和“约束是什么”，具体怎么做，看代码。

严格的依赖方向

apps → node-sdk → agent-core 是一条铁律。apps 绝不能直接依赖 agent-core，必须通过 node-sdk 间接使用。kimi-web 甚至更进一步——完全重新实现了 wire types，与 agent-core 零依赖。这种分层不是多余的抽象，而是确保 UI 层和引擎层可以独立演进的关键设计。

类似的，V2 中 business domains “do not implement persistence themselves”——业务代码通过 IAppendLogStore、IAtomicDocumentStore、IBlobStore 等接口表达“存什么/取什么”，从不直接操作 fs 或写 SQL。

组合优于继承

Agent 类通过组合而非继承来组装子系统。V1 的 agent 目录下每个子系统（tool、skill、plan、permission 等）都是独立的模块，Agent 类将它们组合在一起。V2 进一步将这种思想推进到 Service + DI 的模式：每个 Service 通过接口声明依赖，由 DI 容器完成组合。

DI 容器模式：借鉴 VS Code

V1 和 V2 的 DI 容器设计直接借鉴了 VS Code 的 createDecorator 模式。Service 通过装饰器声明依赖，容器解析依赖图并自动注入。V2 更进一步引入了 Scope 概念：App / Session / Agent 三层 Scope，每层有独立的 Service 实例。这种分层来自对 Agent 系统本质的深刻理解——不是所有状态都应该全局共享。

AsyncLocalStorage 传递执行上下文

kaos 包使用 Node.js 的 AsyncLocalStorage 来隐式传递文件系统和进程执行的上下文，而不是显式地在每个函数签名中传递。这是一种优雅的横切关注点处理方式——业务代码不需要感知自己是在本地运行还是通过 SSH 远程运行，上下文通过异步存储自动传递。

实验特性通过 Flag 管理

未公开的功能通过 packages/agent-core/src/flags/registry.ts 中的实验性 flag 控制，默认关闭。通过环境变量 KIMI_CODE_EXPERIMENTAL_ 单独启用，或 KIMI_CODE_EXPERIMENTAL_FLAG 全部启用。发布时只需将对应 flag 的 default 改为 true。这是一个教科书级别的特性开关方案。

可观察性内建

从第一天起就考虑了可调试性：kap-server 的 /api/v1/debug/* 反射路由、kimi-inspect 的完整调试 UI、transcript 的 op-batch 序列化与回放机制。telemetry 模块更是提供了类型安全的事件系统——业务事件通过 ITelemetryService.track2 发送，事件名和属性在 telemetryEventDefinitions 注册表中做编译期校验，错误的属性名在编译时就会被发现。