_{SOURCE-GROUNDED · TOOL-AGNOSTIC · UPDATED 2026-08-20}

Agent-Base.

拆开 Coding Agent，看见模型之外的系统。

一套面向工程师的中文源码研究手册：从 Agent Loop、Context、Tools 与 Safety， 一路读到 Hooks、Checkpoint、ACP、Team 和 Swarm。

唯一推荐阅读入口

https://giraffe-tree.github.io/agent-base/#/ ↗

_{读者只需使用在线文档；GitHub 仓库用于保存研究文档与源码索引。}

---

真正拉开 Coding Agent 差距的，往往不是模型名字，而是模型周围的系统：它看见什么、能调用什么、如何恢复、谁来验证，以及多个 Agent 怎样协作。

---

01 / CORE TOPICS

研究 Agent，而不是追逐功能清单。

本仓库不做产品宣传，也不以旧文章代替当前实现。每个结论尽量回到本地源码，并明确区分 ✅ Verified 与 ⚠️ Inferred。

01 Agent Loop 一次请求如何变成多轮推理、工具调用、观察与停止；并发、重试、循环检测和取消分别发生在哪一层。 读跨项目 Agent Loop →	02 Context & Memory 系统提示、项目规则、会话历史、压缩摘要、长期记忆和 checkpoint 如何共同决定 Agent 真正“知道”什么。 读跨项目 Context →
03 Tools & Safety 工具怎样注册、调度、授权和返回错误；沙箱、审批、策略与副作用边界如何组成可控执行环境。 读 Tools → · 读 Safety →	04 Agent Orchestration Subagent、Team、Swarm 和普通并发并不是同一种机制；关键在任务所有权、通信拓扑、调度与结果聚合。 读 Swarm / Team 对比 →

---

02 / RESEARCH LANDSCAPE

七个产品家族，八个实现表面。

Kimi 一栏同时研究旧 Python kimi-cli 与当前 TypeScript kimi-code；Claude Code 使用本地源码快照，其余项目使用独立 Git 仓库。下面不是排行榜，而是一张“最值得从哪里切入”的地图。

01 / TYPESCRIPT Claude Code 多宿主会话、Agent Teams、Tasks v2、Hooks 与 Remote 运行拓扑。 Overview · Teams	02 / RUST Codex 安全沙箱、权限策略、持久 Goal、App Server 与层级 Multi-Agent。 Overview · Goal	03 / TYPESCRIPT Gemini CLI ContextManager、并发栅栏 Scheduler、统一 AgentTool 与 Hooks。 Overview · Context	04 / PYTHON + TYPESCRIPT Kimi CLI / Code Checkpoint、D-Mail、后台任务，以及最多 128 items 的 AgentSwarm。 Overview · Swarm
05 / TYPESCRIPT OpenCode Legacy / V2 durable session 双栈，以及 TUI、Web、Desktop 事件投影。 Overview · V2 Runtime	06 / PYTHON SWE-agent 问题实例、命令解析器、History Processor、RetryAgent 与批量实验运行器。 Overview · Problem + Batch	07 / TYPESCRIPT Qwen Code Daemon、Desktop、Channels、循环检测，以及 Agent / Team / Workflow。 Overview · Subagent / Team	CROSS PROJECT Architecture Atlas 用相同问题横向对读七个家族，识别同名功能背后的不同语义。 Global Overview · All Comparisons

---

03 / THE FULL ARC

十三个切面，读完一个 Agent 的完整骨架。

每个项目尽量沿用同一组 01–13 编号。你可以纵向读完一个产品，也可以固定一个主题横向比较所有实现。

No.	研究切面	先回答的问题	跨项目入口
01	Overview	它解决什么问题，系统边界在哪里？	全局概览
02	CLI Entry	参数、配置与第一条 Session 如何建立？	入口对比
03	Session Runtime	状态、事件、持久化与恢复由谁负责？	运行时对比
04	Agent Loop	推理—行动—观察何时继续、何时停止？	Loop 对比
05	Tools	工具如何发现、校验、调度和回传？	Tools 对比
06	MCP	外部工具如何接入、隔离和生命周期管理？	MCP 对比
07	Memory Context	上下文如何组装、压缩、保留与丢弃？	Memory 对比
08	UI Interaction	流式事件怎样投影到终端、Web 或 Desktop？	UI 对比
09	Web Server	本地服务、远端控制面和客户端如何通信？	Server 对比
10	Safety Control	审批、策略、沙箱和信任边界在哪里？	Safety 对比
11	Prompt Organization	系统提示、项目规则和动态注入如何分层？	Prompt 对比
12	Logging	日志、遥测、事件和调试信息如何分流？	Logging 对比
13	ACP Integration	IDE / Host 怎样通过 ACP 驱动 Agent Session？	ACP 对比

展开项目文档地图与篇数

目录	主线	Questions	推荐入口
comm	16	8	Overview · Agent Loop · Hooks
claude-code	14	15	Onboarding · Teams
codex	14	12	Overview · Loop · Goal
gemini-cli	14	12	Overview · Context Pipeline
kimi-cli	17	15	Onboarding · Swarm
opencode	15	13	Overview · Durable Runtime
swe-agent	13	14	Overview · Problem + Batch
qwen-code	13	11	Overview · Hooks
cursor	1	2	Checkpoint 映射

完整逐篇导航见 _sidebar.md。

---

04 / QUESTIONS FIRST

从真正棘手的问题开始。

如果你已经会使用 Coding Agent，不必从 Overview 顺序读。下面这些问题更能暴露架构差异。

问题	推荐阅读	你会看到什么
多 Agent 到底是不是同一种能力？	Swarm / Team / Multi-Agent	Kimi batch swarm、Claude/Qwen team、Codex hierarchy 与普通 subagent 的边界
一个 Turn 里能并行多少工具？	Tool Concurrency	模型并发、Scheduler 并发、工具副作用与栅栏
工具失败后发生什么？	Tool Error Handling	tool result 与 provider/runtime error 两条流水线
Agent 如何避免无限循环？	Codex · Qwen	启发式检测、预算、停止条件和人工介入
Context 满了以后保留什么？	Context Compaction · Reasoning Retention	压缩、摘要、推理内容与消息保留策略
Plan 与 Execute 如何隔离？	Plan & Execute	只读模式、状态转换、审批和执行边界
Hooks 能改变运行时到什么程度？	Hooks Comparison	生命周期、阻断能力、结果合并与超时
Revert 会不会覆盖用户编辑？	Revert Conflict	对话回退、文件恢复与 Git 回退的区别
Checkpoint 是快照还是时间线？	Kimi Checkpoint · Cursor 映射	状态保存粒度、文件恢复与冲突处理
ACP、MCP、A2A 有什么不同？	什么是 ACP · MCP	Host—Agent session 与 Model—Tool 协议的边界
Agent 为什么保留 reasoning？	Reasoning Retention	Provider item、重放、一致性与审计权衡
下一代 Coding Agent 还缺什么？	Future Breakthroughs	已验证能力地基与仍未解决的工程缺口

---

05 / LEARNING PATHS

按你拥有的时间阅读。

30 MINUTES 建立全局直觉 Code Agent 全局概览 Codex Agent Loop Agent Loop 横向对比

2 HOURS 搭起架构骨架 Tools Memory Safety Plan & Execute ACP

DEEP DIVE 追一个真实问题 先从上方 Questions 选择专题 横向读七个项目的实现 回到文末源码索引验证结论 用相同问题审视自己的 Agent

---

06 / EVIDENCE

每一个结论，都应能走回源码。

研究方法

• ✅ Verified：由当前本地源码、测试、配置或官方协议直接支持。
• ⚠️ Inferred：由多个实现信号推导出的解释，明确与事实分开。
• 源码路径优先引用稳定符号与仓库相对路径，避免依赖容易漂移的裸行号。
• 同名能力不直接画等号：Subagent、Team、Swarm、普通并发、Checkpoint、Revert、ACP、MCP 分开核验。
• 每轮更新检查 Markdown 链接、代码围栏、源码路径、文档统计和嵌套仓库状态。

当前基线

最后核验：2026-08-20 17:42:49 CST（UTC+8）

Git 仓库展示 revision 的 committer time，并统一换算为 UTC+8；Claude Code 没有独立 Git 元数据，因此只记录本地快照的核验时间。

Source	Revision	Revision time（UTC+8）
Codex	3b45c29062ff	2026-08-20 02:01:14
Gemini CLI	e90c63fa158b	2026-08-20 05:20:10
Kimi CLI	cbc15c076d17	2026-08-03 15:58:11
Kimi Code	a09d904140e6	2026-08-20 16:06:59
OpenCode	fc80874f45a5	2026-08-20 10:49:11
SWE-agent	3ea751c087f3	2026-07-16 23:21:18
Qwen Code	d4b54a46ff29	2026-08-20 12:06:49
Claude Code	本地源码快照	2026-08-20 17:42:49（核验时间）

获取上游源码

git clone https://github.com/openai/codex.git
git clone https://github.com/google-gemini/gemini-cli.git
git clone https://github.com/MoonshotAI/kimi-cli.git
git clone https://github.com/MoonshotAI/kimi-code.git
git clone https://github.com/anomalyco/opencode.git
git clone https://github.com/SWE-agent/SWE-agent.git
git clone https://github.com/QwenLM/qwen-code.git

---

07 / CONTRIBUTE

把新的证据带回来。

欢迎提交 Issue 或 PR：修正事实错误和失效路径，补充高价值 Questions，或在上游架构变化后重新核验既有结论。新增文章请沿用 template/ 的证据结构，并同步维护 _sidebar.md。

Agent-Base. 不是一份工具榜单，而是一张不断更新的 Coding Agent 架构地图。

唯一推荐阅读入口： https://giraffe-tree.github.io/agent-base/#/ ↗