Route A: Agent 框架设计解读

Metadata

• repo: claude-code-sourcemap
• scope: 全仓库架构级解读（路线 A：Agent 内核优先）
• last_verified_at: 2026-03-31
• confidence: high

解读路线

按「Agent 内核优先」顺序，从核心循环出发，逐层向外扩展：

Layer 1 (Agent Loop) → Layer 2 (Tool 系统) → Layer 6 (子 Agent / Swarm)
→ Layer 3 (权限系统) → Layer 5 (上下文管理)

核心洞察

Claude Code 不是一个简单的 CLI wrapper，而是一个完整的 Agent Runtime 系统。 其架构可以用「洋葱模型」理解——以 Agent Loop 为核心，每一层解决一个关键工程问题：

         ┌─────────────────────────────────┐
   L5    │  Context Window 管理 & 会话持久化  │  ← 长对话怎么不爆窗口？
         ├─────────────────────────────────┤
   L3    │  权限系统 & 安全模型              │  ← 自主性 vs 安全性？
         ├─────────────────────────────────┤
   L6    │  Sub-agent / Swarm 协作系统      │  ← 多 Agent 怎么协作？
         ├─────────────────────────────────┤
   L2    │  Tool 系统 (定义/注册/调度/执行)   │  ← Agent 怎么获得能力？
         ├─────────────────────────────────┤
   L1    │  Agent Loop (Query Engine)      │  ← 核心引擎怎么运转？
         └─────────────────────────────────┘

文档索引

序号	层	主题	文档	核心问题
01	L1	Agent Loop	01-agent-loop.md	Agent 循环是怎么实现「思考→执行→观察→继续」的？
02	L2	工具系统	02-tool-system.md	50+ 工具怎么标准化定义、安全调度、并发执行？
03	L6	子 Agent 协作	03-subagent-swarm.md	多 Agent 怎么生成、隔离、通信、协调？
04	L3	权限系统	04-permission-system.md	能执行 shell 命令的 Agent 怎么保证安全？
05	L5	上下文管理	05-context-management.md	上下文窗口有限，长对话怎么不丢信息？
06	L4	Hook & MCP 扩展	06-hook-mcp-extension.md	如何在安全框架中设计可扩展点？
07	—	设计原则提炼	07-design-principles.md	13 条可复用的 Agent 工程设计原则

仓库概况

维度	数据
语言	TypeScript / TSX
文件数	~1,900
代码行数	~500,000 LOC
构建工具	Bun（feature() 编译时条件编译）
UI 框架	自定义 Ink（React + Yoga 终端渲染）
状态管理	React Context + Zustand-like Store

横切关注点

每篇文档末尾会标注与其他层的交互点，形成完整的知识网络。此外有几个贯穿所有层的工程实践：

• 流式架构：API streaming → 增量消息重建 → 流式工具执行 → 实时 UI 更新
• Feature Gates：feature() 编译时条件编译，同一代码库出不同构建产物
• 依赖注入：query/deps.ts 定义窄接口，支持测试 mock
• Async Generator：全链路使用 async generator 实现流式输出