Claude Code 架构总览

一句话理解

这套系统可以粗暴理解为：

一个以 query() 为核心循环、以 Tool 为统一扩展接口、以 Task 为后台生命周期管理层的 CLI agent runtime。

主要分层

1. 入口层

• main.tsx
• QueryEngine.ts

负责：

• 接收用户输入
• 准备 system prompt / user context / tool context
• 调用主循环 query()

2. 主循环层

• query.ts

负责：

• 调用模型 API
• 接收 assistant 输出
• 识别 tool_use
• 执行工具
• 将 tool_result 回灌到消息流
• 持续 loop

3. 工具层

• Tool.ts
• tools.ts
• tools/*

负责：

• 定义工具接口
• 注册 built-in tools
• 处理 read / edit / bash / agent / mcp 等工具

4. Agent 层

• tools/AgentTool/AgentTool.tsx
• tools/AgentTool/runAgent.ts

负责：

• 把 agent 作为一种工具暴露给模型
• 决定 agent 是同步执行、后台执行、fork、worktree 还是 remote
• 为子 agent 重新组装上下文并重新进入 query()

5. Task 层

• tasks/LocalAgentTask/LocalAgentTask.tsx
• tasks/RemoteAgentTask/RemoteAgentTask.tsx

负责：

• 后台任务注册
• 进度跟踪
• 通知
• kill / completion / failure lifecycle

关键观察

Agent 不是隐藏机制，而是 Tool

在 tools.ts 中，AgentTool 和 BashTool、FileReadTool 一起注册。

这意味着对主循环而言：

• 调 agent
• 调 bash
• 调 read

本质上都是一次 tool call。

子 agent 与主 agent 共用同一个 loop

runAgent() 最终还是调用 query()。

这说明整个系统不是“主 agent 一套逻辑，子 agent 另一套逻辑”，而是：

• 一个统一主循环
• 多种不同上下文实例

Task 是生命周期层，不是推理层

LocalAgentTask / RemoteAgentTask 不是负责“思考”，而是负责：

• 后台运行管理
• 状态同步
• 通知与恢复

当前最值得继续追的地方

• tool_use 到 Tool.call() 的分发链
• createSubagentContext 如何隔离 / 继承上下文
• AgentTool 如何汇总子 agent 的结果并返回给父 agent