跳到主要内容

Kimi Code CLI — 架构与原理

30 秒导读: Kimi Code CLI 是一个跑在终端里的 AI 编码 agent——你用自然语言说要干什么,它读你的代码、改文件、跑 shell、搜网页,再根据每一步的反馈决定下一步,直到把活干完。核心是一个无状态的回合循环:把模型说的话精确落地成真实工具调用,拿到结果再喂回模型。本页给你零基础定义、顶层全景图、和一张通往六个深入章节的阅读地图。

1. 这是什么(零基础也能懂)​

一句话定义: Kimi Code CLI 是 Moonshot AI 做的一个终端里的 AI 编码助手——在命令行里跑,能读改代码、执行命令、联网,并自己判断下一步该干嘛(README.md:8-10)。

解决什么问题 / 给谁用: 假设你在终端里想让 AI 帮你改一个大项目的代码——不是"补全一行",而是"看懂这个 bug、改三个文件、跑测试确认修好了"。Kimi Code 就是干这个的:你打一句话,它自己读文件、grep、编辑、跑 shell、验证,一轮轮推进,直到任务闭环。给的是天天在终端里干活的工程师。

它能做什么(功能):

  • 读/改代码、按行编辑、写新文件、grep/glob 搜索(packages/agent-core/src/tools/builtin/file/)。
  • 跑 shell 命令、开后台任务、定时任务(tools/builtin/shell/bash.ts、tools/background/、tools/cron/)。
  • 联网:抓网页、web 搜索(tools/builtin/web/)。
  • 看视频:把录屏/演示片段丢进对话让它"看"(README.md:64)。
  • 派子 agent(coder/explore/plan)在隔离上下文里并行干活(README.md:67)。
  • 通过 MCP 接第三方工具、装插件/技能(packages/agent-core/src/mcp/、plugin/)。
  • 目标(goal)模式:把一个任务变成可自治多轮推进的结构化目标(GOAL.md)。

用起来什么样: 一个最小真实会话(源自 README.md:44-57):

cd your-project
kimi                       # 启动交互式 TUI
# 首次运行 /login 选 Kimi OAuth 或 API key,然后:
> Take a look at this project and explain its main directories.

一句话直觉/类比: 把它当成一个手脚齐全、会看反馈的实习工程师——模型是它的"脑子"(决定做什么),工具是它的"手脚"(真去改文件/跑命令),而 loop 是那根"神经":每做一步都把结果反馈回脑子,再决定下一步。

本节不谈底层。记住三件事就够了:脑子(模型)、手脚(工具)、神经(回合循环)。

2. 顶层全景(它大概怎么转)​

怎么读下面这张图: 从上到下是"用户 → 交付面 → 主机层 → 循环 → 两个抹平层 → 真实世界",中间那根竖线(loop)是价值所在;左右两侧(kosong / kaos)是把"各家大模型"和"各种执行环境"抹平的适配层。

          你(在终端里打一句话)
                │
   ┌────────────▼─────────────┐   交付面:TUI / CLI / SDK / 编辑器(ACP)/ REST·WS 服务器
   │  Surfaces(apps/*、node-sdk、acp-adapter、kap-server)
   └────────────┬─────────────┘
                │  一个"turn"(一次用户输入触发的一整轮工作)
   ┌────────────▼─────────────┐   Agent 主机层(packages/agent-core · agent/)
   │  拼系统提示 · 管上下文压缩 · 控权限 · 派子agent · goal/plan
   │  TurnFlow —— 把一次 turn 编排起来
   └────────────┬─────────────┘
                │  调用无状态循环
   ┌────────────▼─────────────┐   Loop(packages/agent-core/src/loop)
   │  runTurn:模型说话 → 执行工具 → 结果喂回 → 再来一步,直到停
   └───┬───────────────────┬──┘
       │ 模型这一侧          │ 工具这一侧
   ┌───▼──────────┐     ┌───▼───────────┐
   │ kosong        │     │ kaos           │
   │ 抹平大模型     │     │ 抹平执行环境    │
   │(Kimi/Claude/  │     │(本地/SSH/容器) │
   │ Gemini/OpenAI)│     │                │
   └───┬──────────┘     └───┬───────────┘
       │                    │
   各家 LLM API         你的真实文件系统 / shell

部件一句话职责:

部件干什么在哪(克隆内路径)
Loop无状态回合循环:一步步把模型输出变成工具调用再喂回packages/agent-core/src/loop/
Agent 主机层给 loop 喂系统提示/消息、跑压缩、过权限、编排一个 turnpackages/agent-core/src/agent/
kosongLLM/provider 抽象:把 Kimi/Anthropic/Gemini/OpenAI 抹成一个接口packages/kosong/
kaos执行环境抽象:把本地/SSH/容器的文件与进程抹成一个接口packages/kaos/
agent-core-v2再工程化的引擎:DI×Scope(App/Session/Agent 三层作用域)packages/agent-core-v2/
kap-server把 v2 引擎通过 REST + WebSocket(/api/v1)对外packages/kap-server/
交付面TUI/CLI(apps/kimi-code)、SDK(node-sdk)、编辑器 ACP(acp-adapter)apps/、packages/node-sdk、packages/acp-adapter

主线走一遍(高层,不进代码):

  1. 你在 TUI 里打一句话 → 交付面把它变成一次 turn 交给 Agent 主机层。
  2. 主机层的 TurnFlow 拼好系统提示、当前消息、可用工具表,调用 runTurn(packages/agent-core/src/agent/turn/index.ts:783)。
  3. loop 让模型走一步:kosong 把请求发给某家大模型,流式拿回"要调哪些工具"。
  4. loop 执行这些工具(读文件/跑命令经 kaos 落到真实环境),把结果作为消息喂回。
  5. 模型还想调工具就继续下一步(stopReason === 'tool_use' 时 continue,见 loop/run-turn.ts:183);否则这轮结束,把最终回复给你。
  6. 期间主机层随时可插手:上下文太长就压缩、危险操作弹权限、goal 模式则自动追加"继续"提示进入下一轮。

一句话记住全景:主机层编排一个 turn,loop 把 turn 收敛成一串"模型步 + 工具批",kosong/kaos 分别抹平两端的差异。

3. 阅读地图(建议顺序)​

按"由浅入深、先主线后底层"排。想快速建立心智模型就顺序读 01→02;想扎进某一层就直接跳。

  1. 这是什么 · 全景 · 阅读地图 — 你正在读的这页:零基础定义 + 顶层全景。
  2. 无状态回合循环:一次工具调用的一生 — 最该先读的一章。runTurn 如何把"模型步"和"工具批"串成收敛的一轮;停止原因、中断/压缩安全点、媒体降级重发这些精妙处都在这。
  3. Agent 主机层:拼提示 · 管上下文 · 控权限 · 派子agent — loop 外面那圈"大脑皮层":Agent/TurnFlow 怎么组装系统提示、压缩上下文、过权限、跑 goal/plan、派 subagent。
  4. 工具套件:模型的手脚如何精确落到真实目标 — 内置工具(edit/read/grep/bash/web…)如何定义、如何把模型给的参数容错地落到真实文件与进程上。
  5. 抹平两层差异:kosong 抹平大模型,kaos 抹平执行环境 — 两个适配层:ChatProvider 统一各家 LLM 的流式/停止语义;Kaos 统一本地/远程的文件与 shell。
  6. 再工程化:DI×Scope 引擎与 REST/WS 服务器 — v1 单体到 v2 引擎的迁移:LifecycleScope(App/Session/Agent)依赖注入、kap-server 的 REST+WS 面。
  7. 交付面:单二进制 TUI、CLI、SDK 与编辑器(ACP) — 同一套核心怎么以四种形态交付:TUI、kimi CLI 子命令、node-sdk 的 KimiHarness、以及 kimi acp 让 Zed/JetBrains 驱动。

4. 巧妙之处(读完要带走的精华)​

这一节先白话点"妙在哪",再给路径。想看展开论证去对应章节。

  • loop 是"无状态"的,这是整个架构的地基。 loop 不持有 session、不管 wire 传输、不做压缩执行、不弹权限 UI——这些全是主机层的活(packages/agent-core/src/loop/README.md:3-6)。好处:同一个循环能被 v1、v2、SDK、服务器复用,循环本身可被彻底单测。

  • 停止原因被拆成两套类型,精准表达"这是一步停还是一轮停"。 tool_use 是循环控制信号(执行工具后继续),其它才是终止;LoopStepStopReason(单步)和 LoopTurnStopReason(整轮)刻意分开,tool_use 不允许出现在最终结果里(loop/types.ts:30-60)。这让"turn 何时真正结束"没有歧义。

  • usage 在 LLM.chat 返回后立刻记账,而不是等工具跑完。 因为工具执行可能被中断,但那次模型调用的 token 已经花掉了——中断也必须如实上报(loop/README.md:37-39)。

  • 请求体过大/图片格式不对时,同一轮里自动降级重发。 命中 413 就把旧媒体换成文字标记只留最近的(media-degraded),图片格式被拒或再次超限就全部剥成文字(media-stripped);而且降级一旦生效,后续步直接从降级投影构建,不必每步都吃一次拒绝(loop/run-turn.ts:118-181)。

  • 并行工具调用的完成时机被刻意推迟到流结束后。 并行流会交错各调用的参数增量(tc0头→tc1头→tc0参→tc1参),中途派发就会拿到半拉参数触发解析错误——所以 onToolCall 只在流 drain 后按序触发(packages/kosong/src/generate.ts:49-61)。

  • deferred 工具的 schema 不进顶层 tools[],只为保 prompt cache 字节稳定。 渐进式披露的工具客户端可执行,但其 schema 走消息级声明,顶层工具列表保持逐字节稳定以命中缓存——这是每次 provider 调用的唯一剥离点(generate.ts:111-117)。

  • goal 模式把"技术失败"和"业务阻塞"分开处理。 用户中断、限流、连接/认证错、runtime 异常 → paused(可恢复停车);而 prompt hook 阻止、模型判断无法继续、预算耗尽 → blocked。没有 cancelled 状态——取消就是清除 goal(GOAL.md:19-25、94-109)。session 恢复时 active goal 会降级成 paused,避免重启后偷偷烧钱(GOAL.md:113-119)。

  • v2 用 VS Code 式的 DI×Scope 三层作用域重写。 LifecycleScope 只有 App/Session/Agent 三级,且子作用域的 kind 必须严格大于父级(packages/agent-core-v2/src/_base/di/scope.ts:12-16、139-154)——服务按生命周期挂在正确的层上,随作用域销毁而销毁。

  • finish reason 被归一化,但原始值总被保留。 各家 provider 的原生停止值映射到统一的 FinishReason,同时把未映射的原串塞进 rawFinishReason 当逃生舱(packages/kosong/src/provider.ts:76-121)。

5. 代码地图(导航索引)​

一张跳转表。行号可能随上游漂移,但符号名通常还在——agent 可用符号名 grep 定位。所有引用 as-of sourceCommit。

主题文件路径(克隆根)关键符号
回合循环入口packages/agent-core/src/loop/run-turn.tsrunTurn、RunTurnInput
单步执行packages/agent-core/src/loop/turn-step.tsexecuteLoopStep
工具批调度packages/agent-core/src/loop/tool-scheduler.ts(资源冲突串行/非冲突并行)
loop 契约/停止原因packages/agent-core/src/loop/types.tsLoopStepStopReason、LoopTurnStopReason、ExecutableTool
loop 设计说明packages/agent-core/src/loop/README.md(无状态边界、契约)
Agent 主机packages/agent-core/src/agent/index.tsAgent
turn 编排packages/agent-core/src/agent/turn/index.tsTurnFlow(在 :783 调 runTurn)
goal 模式packages/agent-core/src/agent/goal/GoalMode;设计见根 GOAL.md
上下文压缩packages/agent-core/src/agent/compaction/FullCompaction、MicroCompaction
权限packages/agent-core/src/agent/permission/PermissionManager
内置工具汇总packages/agent-core/src/tools/builtin/index.ts(edit/read/grep/glob/bash/web/goal/plan…)
文件编辑工具packages/agent-core/src/tools/builtin/file/edit.ts(按行/片段编辑)
shell 工具packages/agent-core/src/tools/builtin/shell/bash.ts(bash 执行)
LLM 统一接口packages/kosong/src/provider.tsChatProvider、FinishReason、StreamedMessage
单次生成循环packages/kosong/src/generate.tsgenerate、GenerateResult
provider 适配packages/kosong/src/providers/kimi.ts、anthropic.ts、google-genai.ts、openai-*.ts
执行环境接口packages/kaos/src/kaos.tsKaos
本地/SSH 实现packages/kaos/src/local.ts、ssh.tsLocalKaos
v2 DI 作用域树packages/agent-core-v2/src/_base/di/scope.tsLifecycleScope、Scope、registerScopedService
v2 引擎公开面packages/agent-core-v2/src/index.ts(聚合各域 barrel)
REST/WS 服务器packages/kap-server/src/start.ts、routes/(/api/v1、/api/v1/ws)
公开 SDKpackages/node-sdk/src/index.tsKimiHarness、Session、createKimiHarness
CLI 入口apps/kimi-code/src/main.tshandleMainCommand
ACP 适配packages/acp-adapter/src/index.ts(kimi acp 走 stdio)