Kimi CLI — 架构与原理
30 秒导读: Kimi CLI 是 Moonshot AI 出的终端里的 AI 编码智能体——你在命令行敲自然语言，它读代码、改文件、跑 shell、搜网页，自己规划并逐步执行。它的内核只有一件事:反复执行"一次 LLM 步 + 把模型要调的工具异步跑掉",直到模型不再调工具为止。有意思的是它把这个循环做成了**可断点(每步存检查点)、可回退(给过去的自己发 D-Mail)、可插拔(换 LLM provider 不动主循环)**的形态。
本页是这个子库的书架卡片——只做一件事:一句话说清 Kimi 是什么,再把你导向真正的内容页。 全景总览(架构图、部件表、机制指针、全局代码地图)在下面的全景页里,深入细节分散在 6 个章节里。本页不重复它们,避免你读两遍同样的东西。
先读这里:全景页
这是本子库的主总览页:讲清"它是什么、大盘怎么转、这是个 monorepo(一库四包)、一条输入如何变成一轮对话",并附一张顶层架构图 + 部件职责表 + 巧妙之处清单 + 全局代码地图。想系统了解 Kimi,从它开始。
这是什么(一句话)
Kimi CLI 是一个跑在终端里的编码智能体(coding agent)——把大语言模型接上"手脚"(读写文件、执行命令、访问网络),让它替你在项目目录里完成软件开发任务。你直接在命令行对话,它能真的动手改文件、跑测试、查资料,并在过程中自己调整计划。
一句话直觉: 把它想成一个会用工具的实习生 + 一台录像机——实习生(LLM)每一步只做"想一下、动个手";录像机(Context 的 JSONL + 检查点)把每一步都存到磁盘,任何时刻都能倒带重来。这条"倒带"能力(D-Mail,電話レンジ / 电话微波炉)是 Kimi 最有辨识度的设计。
一次最小交互:
# 在你的项目目录里
kimi # 启动交互式 shell
> 把 utils.py 里的 print 全部换成 logging，并加上单测
# 它会：读文件 → 改文件 → 跑测试 → 汇报，中间需要时向你请求批准
也可以接进 IDE(README 里的 ACP 集成),或非交互跑一条命令:kimi --print "..."。
章节地图(往下钻哪一章)
这个子库按"由浅入深、从主干到枝节"拆成 6 章。建议顺序从上到下;赶时间只读全景页 + 第 02 章主循环即可抓住精髓。
| 顺序 | 章节 | 讲什么 | 何时读 |
|---|---|---|---|
| 1 | 从命令到智能体:入口、Session 与装配 | kimi 命令如何一路装配出 KimiSoul;Runtime、Agent、Config、Session 的角色 | 想搞清"程序怎么起来的" |
| 2 | 智能体主循环:Soul、Wire 与 kosong 一步 | _agent_loop/_step 的完整生命周期;Soul↔Wire 解耦;kosong 的 step/generate | 核心章,理解 Kimi 必读 |
| 3 | 上下文与记忆:JSONL 检查点与压缩 | Context 的追加式 JSONL、检查点、revert_to、自动压缩 compaction | 关心"记忆怎么存、怎么倒带" |
| 4 | 工具系统:加载、去重调度、审批与 MCP | 工具依赖注入装载、同步/跨步去重、审批闸门、MCP 延迟加载 | 关心"手脚怎么长出来、怎么安全" |
| 5 | 巧妙之处:D-Mail 时间回溯、动态注入与自动循环 | D-Mail(電話レンジ)回退、动态注入、Ralph 自动循环、Flow | 想带走"可借鉴的精华" |
| 6 | 子智能体与后台任务:委派、劳务市场与并发 | Agent 工具委派、LaborMarket 类型注册、前台/后台 runner、后台任务管理 | 关心"多 agent / 并发" |
一分钟看点(三个最值得带走的设计)
每条只点破妙在哪,深入见对应章节:
- D-Mail 时间回溯(電話レンジ / 电话微波炉) —— 模型能给"过去的自己"发一封信,声明"退回到某个检查点重来",系统随即把上下文折叠回该检查点。命名致敬《命运石之门》;它只回退对话、不回退文件系统。→ 第 05 章
- 检查点 = 一行 JSONL,不是一份快照 —— Context 是纯追加日志,检查点只是插入
{"role":"_checkpoint","id":N}一行,回退就是"重放到目标那行"。廉价、崩溃安全、可grep。→ 第 03 章 - kosong:把"一次 LLM 步"抽成独立库 —— LLM 调用 + 工具分派被抽到独立包
kosong,Soul 只依赖kosong.step抽象,底层换 Kimi/OpenAI/Anthropic/Google provider 主循环零改动。→ 第 02 章
想要完整的"巧妙之处"清 单、顶层架构图与全局代码地图,请看上面的**全景页**。