chore: consolidate heicode workspace into single repository

Import cc-haha and new-api into a single repository layout for unified delivery.

Made-with: Cursor

cc-haha/docs/agent/01-usage-guide.md

@@ -0,0 +1,443 @@
+# Claude Code 多 Agent 系统 — 使用指南
+
+> 让 Claude Code 同时调度多个专业代理，并行处理复杂任务。
+
+<p align="center">
+<a href="#一什么是多-agent-系统">多 Agent 系统</a> · <a href="#二六种内置-agent">六种内置 Agent</a> · <a href="#三如何生成-agent">如何生成 Agent</a> · <a href="#四后台任务管理">后台任务管理</a> · <a href="#五agent-teams--多代理协作">Agent Teams</a> · <a href="#六自定义-agent">自定义 Agent</a> · <a href="#七权限模式">权限模式</a> · <a href="#八快速参考">快速参考</a>
+</p>
+
+![多 Agent 系统概览](./images/01-agent-overview.png)
+
+---
+
+## 一、什么是多 Agent 系统？
+
+Claude Code 的多 Agent 系统是一套**智能任务编排框架**，让主代理能够生成多个专业化的子代理（Subagent），各自独立执行不同的任务，最终将结果汇总给用户。
+
+核心理念：**把大任务拆分为多个专业小任务，并行执行，提高效率。**
+
+| 场景 | 传统方式 | 多 Agent 方式 |
+|------|----------|---------------|
+| 调研 5 个模块的架构 | 逐个串行探索 | 5 个 Explore agent 并行扫描 |
+| 实现 + 测试 + 文档 | 顺序完成 | Team 成员各自负责一块 |
+| 代码审查 | 单线程逐文件看 | 多个 reviewer 并行审查 |
+| 调试复杂 bug | 一个假设一个假设试 | 多个 debugger 并行验证 |
+
+---
+
+## 二、六种内置 Agent
+
+![六种内置 Agent](./images/02-agent-types.png)
+
+Claude Code 内置了 6 种专业代理，每种都有特定的工具池和适用场景：
+
+### 1. general-purpose（通用代理）
+
+**适用场景**：复杂的多步骤研究、代码搜索、需要完整工具访问的任务。
+
+```
+Agent({
+  description: "调研认证模块",
+  prompt: "分析 src/auth/ 下所有文件的认证流程...",
+  subagent_type: "general-purpose"
+})
+```
+
+- **工具池**：全部工具（`*`）
+- **模型**：继承父代理
+- **特点**：万能型，不确定用哪个 agent 时选它
+
+### 2. Explore（探索代理）
+
+**适用场景**：快速搜索文件、搜索代码模式、回答代码库结构问题。
+
+```
+Agent({
+  description: "搜索 API 端点",
+  prompt: "找到所有 REST API 端点的定义...",
+  subagent_type: "Explore"
+})
+```
+
+- **工具池**：只读工具（Glob、Grep、Read、Bash）
+- **模型**：Haiku（快速低成本）
+- **特点**：不能修改文件，速度快，适合调研
+
+### 3. Plan（规划代理）
+
+**适用场景**：设计实现方案、分析架构权衡、生成分步计划。
+
+```
+Agent({
+  description: "规划重构方案",
+  prompt: "设计将 monolith 拆分为微服务的方案...",
+  subagent_type: "Plan"
+})
+```
+
+- **工具池**：只读工具（同 Explore）
+- **模型**：继承父代理（需要强推理能力）
+- **特点**：输出结构化计划，包含关键文件和依赖分析
+
+### 4. verification（验证代理）
+
+**适用场景**：独立验证实现是否正确，运行测试，边界检查。
+
+```
+Agent({
+  description: "验证登录功能",
+  prompt: "验证新实现的登录功能是否正确...",
+  subagent_type: "verification"
+})
+```
+
+- **工具池**：只读工具
+- **模型**：继承父代理
+- **特点**：始终在后台运行，输出 PASS/FAIL/PARTIAL 判定，红色标识
+
+### 5. claude-code-guide（指南代理）
+
+**适用场景**：回答关于 Claude Code、Agent SDK、Claude API 的问题。
+
+```
+Agent({
+  description: "查询 Claude API 用法",
+  prompt: "如何使用 tool_use 功能...",
+  subagent_type: "claude-code-guide"
+})
+```
+
+- **工具池**：Bash、Read、WebFetch、WebSearch
+- **模型**：Haiku
+- **特点**：专注文档查询，dontAsk 权限模式
+
+### 6. statusline-setup（状态栏配置代理）
+
+**适用场景**：配置 Claude Code 状态栏显示。
+
+- **工具池**：仅 Read + Edit
+- **模型**：Sonnet
+- **特点**：高度专业化，范围极小
+
+### Agent 类型对比表
+
+| Agent | 读写 | 工具池 | 模型 | 用途 |
+|-------|------|--------|------|------|
+| general-purpose | 读写 | 全部 | 继承 | 通用任务 |
+| Explore | 只读 | 搜索+读取 | Haiku | 快速探索 |
+| Plan | 只读 | 搜索+读取 | 继承 | 架构规划 |
+| verification | 只读 | 搜索+读取 | 继承 | 独立验证 |
+| claude-code-guide | 只读 | 搜索+网络 | Haiku | 文档指南 |
+| statusline-setup | 读写 | Read+Edit | Sonnet | 状态栏配置 |
+
+---
+
+## 三、如何生成 Agent
+
+### 基本参数
+
+Agent 工具接受以下参数：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `description` | string | 是 | 3-5 词任务简述 |
+| `prompt` | string | 是 | 完整的任务描述 |
+| `subagent_type` | string | 否 | Agent 类型（见上表） |
+| `model` | string | 否 | 模型覆盖：sonnet/opus/haiku |
+| `run_in_background` | boolean | 否 | 是否后台运行 |
+| `name` | string | 否 | 命名后可通过 SendMessage 寻址 |
+| `team_name` | string | 否 | 加入指定团队 |
+| `mode` | string | 否 | 权限模式 |
+| `isolation` | string | 否 | 隔离模式：worktree |
+
+### 前台同步执行（默认）
+
+最简单的用法，Agent 执行完毕后返回结果：
+
+```
+Agent({
+  description: "分析错误日志",
+  prompt: "读取 logs/ 下最近的错误日志，总结常见错误模式"
+})
+```
+
+主代理会等待子代理完成，然后收到结果继续工作。
+
+### 后台异步执行
+
+适合耗时任务，主代理可以继续做其他事情：
+
+```
+Agent({
+  description: "全面代码审查",
+  prompt: "审查 src/ 下所有 TypeScript 文件的代码质量...",
+  run_in_background: true
+})
+```
+
+- Agent 立即返回 `async_launched` 状态和 taskId
+- 主代理继续工作，不需要等待
+- Agent 完成后自动收到 `<task-notification>` 通知
+- 通知包含任务状态、输出文件路径和结果摘要
+
+### 并行生成多个 Agent
+
+在一条消息中生成多个独立的 Agent，实现真正的并行：
+
+```
+// 同时启动 3 个探索 agent
+Agent({ description: "探索前端", prompt: "...", subagent_type: "Explore", run_in_background: true })
+Agent({ description: "探索后端", prompt: "...", subagent_type: "Explore", run_in_background: true })
+Agent({ description: "探索数据库", prompt: "...", subagent_type: "Explore", run_in_background: true })
+```
+
+### Worktree 隔离
+
+让 Agent 在独立的 git worktree 中工作，不影响主工作区：
+
+```
+Agent({
+  description: "实验性重构",
+  prompt: "尝试将模块 X 重构为...",
+  isolation: "worktree"
+})
+```
+
+- 自动创建 git worktree（独立分支）
+- Agent 在隔离环境中自由修改文件
+- 完成后如有改动，返回 worktree 路径和分支名
+- 无改动则自动清理
+
+---
+
+## 四、后台任务管理
+
+![Agent 生成流程](./images/03-spawn-flow.png)
+
+### 任务状态
+
+后台 Agent 有四种状态：
+
+| 状态 | 说明 |
+|------|------|
+| `running` | 正在执行中 |
+| `completed` | 执行成功 |
+| `failed` | 执行失败 |
+| `killed` | 被手动终止 |
+
+### 进度追踪
+
+后台 Agent 的进度实时更新：
+
+- **Token 消耗**：输入/输出 token 计数
+- **工具使用**：已使用的工具次数
+- **最近活动**：最近 5 个工具调用描述（循环缓冲区）
+- **最后活动时间**：用于检测卡住的任务
+
+### 完成通知
+
+当后台 Agent 完成时，主代理收到 XML 格式的通知：
+
+```xml
+<task-notification>
+  <task-id>abc123</task-id>
+  <status>completed</status>
+  <summary>Agent "探索前端" completed</summary>
+  <output-file>~/.claude/temp/.../tasks/abc123.output</output-file>
+</task-notification>
+```
+
+### 自动后台化
+
+当 `tengu_auto_background_agents` 特性开启时，前台 Agent 运行超过 **120 秒**会自动转为后台执行，释放主代理继续工作。
+
+---
+
+## 五、Agent Teams — 多代理协作
+
+![Agent Teams 协作](./images/04-agent-teams.png)
+
+Agent Teams 是更高级的多代理协作模式，多个代理以团队形式工作，通过消息通信协调任务。
+
+### 创建团队
+
+```
+TeamCreate({
+  team_name: "feature-team",
+  description: "开发用户认证功能"
+})
+```
+
+团队创建后：
+- 生成团队配置文件：`~/.claude/teams/{team_name}/config.json`
+- 创建共享任务目录：`~/.claude/tasks/{team_name}/`
+- 当前代理自动成为 **Team Lead**（团队负责人）
+
+### 添加团队成员
+
+通过 Agent 工具指定 `name` 和 `team_name` 生成队友：
+
+```
+Agent({
+  description: "前端开发",
+  prompt: "负责实现登录页面的 React 组件...",
+  name: "frontend-dev",
+  team_name: "feature-team"
+})
+
+Agent({
+  description: "后端开发",
+  prompt: "负责实现认证 API 端点...",
+  name: "backend-dev",
+  team_name: "feature-team"
+})
+```
+
+### 队友通信
+
+通过 SendMessage 工具发送消息：
+
+```
+// 发送给特定队友
+SendMessage({
+  to: "frontend-dev",
+  message: "API 接口已就绪，格式是...",
+  summary: "通知 API 接口格式"
+})
+
+// 广播给所有队友
+SendMessage({
+  to: "*",
+  message: "大家暂停，需求变更了...",
+  summary: "广播需求变更"
+})
+```
+
+### 关停协调
+
+当任务完成后，Team Lead 请求队友关停：
+
+```
+// 1. 发送关停请求
+SendMessage({
+  to: "frontend-dev",
+  message: { type: "shutdown_request", reason: "任务已完成" }
+})
+
+// 2. 队友回复批准
+SendMessage({
+  to: "team-lead",
+  message: { type: "shutdown_response", request_id: "...", approve: true }
+})
+
+// 3. 所有队友关停后，清理团队
+TeamDelete()
+```
+
+### 执行后端
+
+Agent Teams 支持两种执行后端：
+
+| 后端 | 说明 | 适用场景 |
+|------|------|----------|
+| **in-process** | 同进程运行，AsyncLocalStorage 隔离 | 默认模式，轻量高效 |
+| **tmux** | 独立 tmux pane 运行 | 需要独立终端视图 |
+| **iTerm2** | 独立 iTerm2 窗口运行 | macOS iTerm2 用户 |
+
+---
+
+## 六、自定义 Agent
+
+除了内置 Agent，你还可以创建自己的专业代理。
+
+### 定义格式
+
+在 `.claude/agents/` 目录下创建 `.md` 文件：
+
+```markdown
+---
+name: code-reviewer
+description: 专业代码审查代理
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+model: sonnet
+permissionMode: dontAsk
+maxTurns: 10
+---
+
+你是一个专业的代码审查员。请检查以下方面：
+
+1. 代码质量和可读性
+2. 潜在的安全漏洞
+3. 性能问题
+4. 最佳实践遵循
+```
+
+### 可配置字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | Agent 类型名称 |
+| `description` | string | 何时使用的说明 |
+| `tools` | string[] | 允许的工具列表（`['*']` 表示全部） |
+| `disallowedTools` | string[] | 禁止的工具列表 |
+| `model` | string | 使用的模型（sonnet/opus/haiku/inherit） |
+| `permissionMode` | string | 权限模式 |
+| `maxTurns` | number | 最大对话轮数 |
+| `mcpServers` | object[] | 需要的 MCP 服务器 |
+| `hooks` | object | Agent 特定的钩子 |
+| `skills` | string[] | 可使用的技能 |
+| `memory` | string | 记忆作用域（user/project/local） |
+| `isolation` | string | 隔离模式（worktree/remote） |
+| `background` | boolean | 是否默认后台运行 |
+
+### 加载优先级
+
+自定义 Agent 的加载遵循优先级：
+
+1. **内置 Agent**（built-in）— 系统预定义
+2. **插件 Agent**（plugin）— 通过插件注册
+3. **用户 Agent**（user）— `~/.claude/agents/`
+4. **项目 Agent**（project）— `.claude/agents/`（项目级）
+5. **标记 Agent**（flag）— 通过 API 注册
+6. **策略 Agent**（policy）— 组织策略
+
+同名 Agent 按优先级覆盖。
+
+---
+
+## 七、权限模式
+
+每个 Agent 可以设置不同的权限模式：
+
+| 模式 | 说明 |
+|------|------|
+| `default` | 正常权限请求，需要用户确认 |
+| `plan` | 所有操作需要显式审批 |
+| `acceptEdits` | 自动接受文件编辑，其他操作需确认 |
+| `bypassPermissions` | 跳过所有权限检查 |
+| `dontAsk` | 拒绝所有未预批准的操作 |
+| `auto` | AI 驱动的权限分类（仅 Ant 内部） |
+| `bubble` | 权限提示冒泡到父代理终端 |
+
+---
+
+## 八、快速参考
+
+| 操作 | 方法 |
+|------|------|
+| 生成子代理 | `Agent({ prompt: "...", subagent_type: "Explore" })` |
+| 后台运行 | `Agent({ ..., run_in_background: true })` |
+| 并行生成 | 单条消息中发送多个 Agent 调用 |
+| Worktree 隔离 | `Agent({ ..., isolation: "worktree" })` |
+| 创建团队 | `TeamCreate({ team_name: "..." })` |
+| 发送消息 | `SendMessage({ to: "name", message: "..." })` |
+| 广播消息 | `SendMessage({ to: "*", message: "..." })` |
+| 请求关停 | `SendMessage({ to: "name", message: { type: "shutdown_request" } })` |
+| 删除团队 | `TeamDelete()` |
+| 自定义 Agent | 在 `.claude/agents/*.md` 创建定义文件 |
+| 指定模型 | `Agent({ ..., model: "haiku" })` |
+| 命名 Agent | `Agent({ ..., name: "researcher" })` |

cc-haha/docs/agent/02-implementation.md

@@ -0,0 +1,852 @@
+# Claude Code 多 Agent 系统 — 实现原理
+
+> 深入剖析多 Agent 编排的架构设计、生成流程、上下文传递和协作机制。
+
+<p align="center">
+<a href="#一架构总览">架构总览</a> · <a href="#二agent-生成流程--四条路径">生成流程</a> · <a href="#三工具池系统--三层过滤">工具池系统</a> · <a href="#四上下文传递机制">上下文传递</a> · <a href="#五agent-teams-内部机制">Teams 内部机制</a> · <a href="#六后台任务引擎">后台任务引擎</a> · <a href="#七dreamtask--自动记忆整合">DreamTask</a> · <a href="#八worktree-隔离实现">Worktree 隔离</a> · <a href="#九权限同步机制">权限同步</a> · <a href="#十agent-生命周期完整数据流">生命周期数据流</a> · <a href="#十一关键源文件索引">源文件索引</a> · <a href="#十二feature-flags">Feature Flags</a>
+</p>
+
+![实现架构总览](./images/05-architecture.png)
+
+---
+
+## 一、架构总览
+
+Claude Code 的多 Agent 系统由以下核心模块组成：
+
+### 5 大核心模块
+
+| 模块 | 职责 | 关键文件 |
+|------|------|----------|
+| **Agent Tool** | 主入口，路由分发，参数解析 | `src/tools/AgentTool/AgentTool.tsx` |
+| **执行引擎** | Agent 生命周期管理，查询循环 | `src/tools/AgentTool/runAgent.ts` |
+| **上下文管理** | 系统提示词构建，缓存安全参数 | `src/utils/forkedAgent.ts` |
+| **任务系统** | 状态追踪，进度更新，通知队列 | `src/tasks/LocalAgentTask/` |
+| **Swarm 基础设施** | 团队管理，邮箱通信，权限同步 | `src/utils/swarm/` |
+
+### 5 大 Agent 类别
+
+```
+┌─────────────────────────────────────────────────┐
+│                  Agent Tool                      │
+│              (入口 & 路由分发)                    │
+├───────────┬───────────┬───────────┬─────────────┤
+│  Subagent │  Fork     │ Teammate  │   Remote    │
+│  (子代理)  │ (分叉)    │ (队友)    │   (远程)    │
+│           │           │           │             │
+│ 独立上下文 │ 继承上下文 │ 团队协作   │ CCR 环境   │
+│ 按类型过滤 │ 缓存共享   │ 邮箱通信   │ 远程执行   │
+│ 工具池     │ 字节一致   │ 权限同步   │ 轮询结果   │
+└───────────┴───────────┴───────────┴─────────────┘
+                        │
+                  ┌─────┴─────┐
+                  │ DreamTask │
+                  │ (记忆整合)  │
+                  │ 定时后台   │
+                  └───────────┘
+```
+
+---
+
+## 二、Agent 生成流程 — 四条路径
+
+### 入口：`AgentTool.call()`
+
+`src/tools/AgentTool/AgentTool.tsx` 中的 `call()` 函数是所有 Agent 生成的入口。根据输入参数，路由到四条不同的生成路径：
+
+```
+AgentTool.call(input)
+  │
+  ├─ team_name + name? ──────→ 路径1: spawnTeammate()
+  │
+  ├─ run_in_background?  ────→ 路径2: registerAsyncAgent()
+  │     └─ agent.background?
+  │
+  ├─ 省略 subagent_type? ───→ 路径3: Fork (buildForkedMessages())
+  │     └─ fork 实验开启?
+  │
+  └─ 默认 ───────────────────→ 路径4: runAgent() 同步执行
+```
+
+### 路径 1：Teammate 生成
+
+**触发条件**：`team_name` 和 `name` 同时存在
+
+**入口函数**：`spawnTeammate()` — `src/tools/shared/spawnMultiAgent.ts`
+
+**流程**：
+
+1. 检测执行后端（tmux / iTerm2 / in-process）
+2. 为队友生成唯一 `agentId`：`formatAgentId(name, teamName)`
+3. 分配颜色（从预定义调色板）
+4. 创建执行环境：
+   - **in-process**：通过 `spawnInProcessTeammate()` 在同进程中启动
+   - **tmux**：通过 `TmuxBackend` 创建新 pane
+   - **iTerm2**：通过 `ITerm2Backend` 创建新窗口
+5. 写入 TeamFile 成员列表
+6. 返回 `TeammateSpawnedOutput`（包含 pane ID、agent ID 等）
+
+**In-Process 队友的隔离**：
+
+```typescript
+// src/utils/swarm/spawnInProcess.ts
+export async function spawnInProcessTeammate(config, context) {
+  // 1. 独立的 AbortController（不随 leader 中断）
+  const abortController = new AbortController()
+  
+  // 2. AsyncLocalStorage 上下文隔离
+  runWithTeammateContext(teammateContext, async () => {
+    // 3. 独立的任务状态
+    // 4. 独立的消息循环
+    // 5. 共享的权限管道（通过 mailbox）
+  })
+}
+```
+
+### 路径 2：异步 Subagent
+
+**触发条件**：`run_in_background=true` 或 Agent 定义中 `background: true`
+
+**流程**：
+
+```
+registerAsyncAgent()
+  │
+  ├─ 创建 LocalAgentTask（status: 'running'）
+  ├─ 注册到 agentNameRegistry（如有 name）
+  ├─ 创建输出文件符号链接
+  ├─ 创建 AbortController（链接到父代理）
+  ├─ 发射 SDK event: task_started
+  │
+  └─ void runAsyncAgentLifecycle()  ← 异步分离执行
+       │
+       ├─ 创建 ProgressTracker
+       ├─ 遍历 makeStream() 生成器
+       │   ├─ 追加消息到 agentMessages[]
+       │   ├─ 更新进度（tokens、tools、activities）
+       │   └─ 发射 SDK progress events
+       │
+       └─ 完成时：
+           ├─ finalizeAgentTool()（提取结果）
+           ├─ completeAgentTask()（标记完成）
+           ├─ 清理 worktree（如有隔离）
+           └─ enqueuePendingNotification()（通知主代理）
+```
+
+**关键实现**：`src/tools/AgentTool/agentToolUtils.ts` — `runAsyncAgentLifecycle()`
+
+### 路径 3：Fork Subagent
+
+**触发条件**：省略 `subagent_type` 且 Fork 实验开启
+
+**核心优化**：通过字节级一致的 API 请求前缀，实现 **prompt cache 命中**。
+
+![Fork 缓存优化](./images/10-fork-cache.png)
+
+**流程**：
+
+```
+buildForkedMessages(directive, assistantMessage)
+  │
+  ├─ 保留父代理完整的 assistant message（所有 tool_use 块）
+  ├─ 构建 user message：
+  │   ├─ 对每个 tool_use 创建占位 tool_result（字节一致）
+  │   └─ 追加 per-child directive（唯一差异部分）
+  │
+  └─ 结果：字节级一致的 API 前缀 → prompt cache 命中！
+```
+
+**Fork 子代理的行为约束**（通过 `FORK_BOILERPLATE_TAG` 注入）：
+
+```
+1. 你是分叉的工作进程，不是主代理
+2. 不要对话、提问或建议后续步骤
+3. 直接使用工具（Bash、Read、Write 等）
+4. 如修改文件，在报告前提交更改
+5. 工具调用之间不要输出文本
+6. 严格限制在指令范围内
+7. 报告控制在 500 词以内
+8. 响应必须以 "Scope:" 开头
+```
+
+**防递归保护**：`isInForkChild()` 检测是否在 fork 子进程中，防止嵌套 fork。
+
+### 路径 4：同步 Subagent
+
+**触发条件**：默认路径（无 team_name、无 background、非 fork）
+
+**流程**：
+
+```
+runAgent(promptMessages, toolUseContext, options)
+  │
+  ├─ 解析 Agent 定义（getSystemPrompt、tools、permissions）
+  ├─ 构建系统提示词（buildEffectiveSystemPrompt）
+  ├─ 创建隔离的 ToolUseContext（createSubagentContext）
+  ├─ 启动查询循环（query() async generator）
+  │   ├─ 发送 API 请求
+  │   ├─ 处理流式事件
+  │   ├─ 执行工具调用
+  │   └─ 累积消息和 usage
+  │
+  └─ 返回 AgentToolResult
+       ├─ content: 最后 assistant 消息的文本
+       ├─ totalToolUseCount
+       ├─ totalDurationMs
+       └─ totalTokens
+```
+
+---
+
+## 三、工具池系统 — 三层过滤
+
+![工具池系统](./images/07-tool-pool.png)
+
+### 第一层：全局禁止
+
+`ALL_AGENT_DISALLOWED_TOOLS` — 对所有 Agent 禁止的工具：
+
+| 工具 | 禁止原因 |
+|------|----------|
+| TaskOutput | 仅主代理可读取任务输出 |
+| ExitPlanMode | 仅主代理可退出计划模式 |
+| EnterPlanMode | 仅主代理可进入计划模式 |
+| AskUserQuestion | 子代理不应直接问用户 |
+| TaskStop | 仅主代理可终止任务 |
+| Agent | 防止递归生成（Ant 内部例外） |
+
+### 第二层：Agent 类型过滤
+
+`filterToolsForAgent()` — 基于 Agent 类型的工具过滤：
+
+```typescript
+// src/tools/AgentTool/agentToolUtils.ts
+function filterToolsForAgent(tools, agentDef) {
+  // 1. 移除 ALL_AGENT_DISALLOWED_TOOLS
+  // 2. 如果非内置 Agent，额外移除 CUSTOM_AGENT_DISALLOWED_TOOLS
+  // 3. 如果是异步 Agent，限制为 ASYNC_AGENT_ALLOWED_TOOLS
+  // 4. MCP 工具始终允许
+}
+```
+
+**ASYNC_AGENT_ALLOWED_TOOLS**（15 个）：
+
+```
+Read, WebSearch, TodoWrite, Grep, WebFetch, Glob,
+Bash/PowerShell, FileEdit, FileWrite, NotebookEdit,
+Skill, SyntheticOutput, ToolSearch, EnterWorktree, ExitWorktree
+```
+
+### 第三层：Agent 定义过滤
+
+`resolveAgentTools()` — 基于 Agent 定义的工具解析：
+
+```typescript
+function resolveAgentTools(agentDef, availableTools) {
+  if (tools === ['*'] || undefined)  → 通配符，全部允许
+  if (tools === ['Read', 'Grep'])    → 仅允许列表中的工具
+  if (disallowedTools === ['Agent']) → 从可用工具中减去
+}
+```
+
+**过滤流程图**：
+
+```
+所有可用工具
+  │
+  ├─ 减去 ALL_AGENT_DISALLOWED_TOOLS ──→ 通用禁止
+  │
+  ├─ 非内置？减去 CUSTOM_AGENT_DISALLOWED_TOOLS ──→ 自定义限制
+  │
+  ├─ 异步？限制为 ASYNC_AGENT_ALLOWED_TOOLS ──→ 异步白名单
+  │
+  ├─ 有 tools 列表？取交集 ──→ Agent 白名单
+  │
+  ├─ 有 disallowedTools？取差集 ──→ Agent 黑名单
+  │
+  └─ 最终工具池
+```
+
+---
+
+## 四、上下文传递机制
+
+![上下文传递](./images/06-context-passing.png)
+
+### CacheSafeParams — 缓存安全参数
+
+```typescript
+// src/utils/forkedAgent.ts
+export type CacheSafeParams = {
+  systemPrompt: SystemPrompt       // 系统提示词
+  userContext: { [k: string]: string }  // 目录结构、CLAUDE.md 等
+  systemContext: { [k: string]: string } // git status、环境信息
+  toolUseContext: ToolUseContext    // 工具配置、模型、选项
+  forkContextMessages: Message[]   // Fork 上下文消息（用于缓存共享）
+}
+```
+
+**缓存共享原理**：
+
+Fork Agent 通过保持 API 请求前缀字节级一致来复用 prompt cache：
+
+```
+┌─────────────────────────────────────────┐
+│         共享前缀（字节一致）              │
+│  ┌──────────────────────────────────┐   │
+│  │ System Prompt                    │   │
+│  │ User Context                     │   │
+│  │ System Context                   │   │
+│  │ Tool Use Context                 │   │
+│  │ 对话历史 Messages                │   │
+│  │ Assistant Message (all tool_use) │   │
+│  │ User Message (placeholder results│)  │
+│  └──────────────────────────────────┘   │
+├─────────────────────────────────────────┤
+│  唯一差异：per-child directive text      │
+└─────────────────────────────────────────┘
+```
+
+### 系统提示词构建
+
+`buildEffectiveSystemPrompt()` — `src/utils/systemPrompt.ts`
+
+**优先级链**（从高到低）：
+
+```
+Override System Prompt     ← 最高优先级，完全替换
+  ↓
+Coordinator System Prompt  ← 协调器模式专用
+  ↓
+Agent System Prompt        ← agentDefinition.getSystemPrompt()
+  ↓                          - proactive 模式：追加到默认
+  ↓                          - 其他：替换默认
+Custom System Prompt       ← --system-prompt 参数
+  ↓
+Default System Prompt      ← Claude Code 标准提示词
+  ↓
+Append System Prompt       ← 追加到末尾
+```
+
+**Agent 特有的系统提示词增强**：
+
+```typescript
+// src/tools/AgentTool/runAgent.ts
+function getAgentSystemPrompt(agentDef, toolUseContext) {
+  let prompt = agentDef.getSystemPrompt({ toolUseContext })
+  prompt = enhanceSystemPromptWithEnvDetails(prompt)
+  // 添加：工作目录、启用工具列表、模型信息、环境变量
+  return prompt
+}
+```
+
+### SubagentContext — 子代理上下文隔离
+
+```typescript
+// src/utils/forkedAgent.ts
+export type SubagentContextOverrides = {
+  options?: ToolUseContext['options']           // 自定义工具、模型
+  agentId?: AgentId                            // 子代理 ID
+  agentType?: string                           // Agent 类型
+  messages?: Message[]                         // 自定义消息历史
+  readFileState?: ToolUseContext['readFileState'] // 文件读取缓存
+  abortController?: AbortController            // 中止控制器
+
+  // 显式 opt-in 共享（默认隔离）
+  shareSetAppState?: boolean                   // 共享 AppState 写入
+  shareSetResponseLength?: boolean             // 共享响应长度度量
+  shareAbortController?: boolean               // 共享中止控制器
+
+  // 实验性注入
+  criticalSystemReminder_EXPERIMENTAL?: string // 每轮重新注入的提醒
+  contentReplacementState?: ContentReplacementState
+}
+```
+
+**隔离 vs 共享**：
+
+| 资源 | 默认 | 说明 |
+|------|------|------|
+| readFileState | 克隆 | 文件读取缓存独立 |
+| messages | 新建 | 消息历史独立 |
+| abortController | 新建（链接父） | 父取消时子也取消 |
+| setAppState | No-op | 默认不影响父状态 |
+| contentReplacementState | 克隆 | 内容替换状态独立 |
+
+### 模型解析
+
+`getAgentModel()` — `src/utils/model/agent.ts`
+
+**优先级链**：
+
+```
+CLAUDE_CODE_SUBAGENT_MODEL 环境变量  ← 最高
+  ↓
+Agent({ model: 'opus' }) 参数       ← 工具指定
+  ↓
+agentDefinition.model               ← Agent 定义
+  ↓
+'inherit'                           ← 继承父代理模型
+```
+
+---
+
+## 五、Agent Teams 内部机制
+
+### TeamFile 结构
+
+```typescript
+// 存储路径：~/.claude/teams/{team_name}/config.json
+{
+  name: string                        // 团队名称
+  description?: string                // 团队描述
+  createdAt: number                   // 创建时间戳
+  leadAgentId: string                 // Team Lead 的 Agent ID
+  leadSessionId?: string              // Lead 的会话 UUID
+  hiddenPaneIds?: string[]            // UI 中隐藏的 pane
+  teamAllowedPaths?: TeamAllowedPath[] // 团队级共享权限
+  members: Array<{
+    agentId: string                   // 成员 Agent ID
+    name: string                      // 显示名称
+    agentType?: string                // 角色类型
+    model?: string                    // 使用的模型
+    prompt?: string                   // 初始任务
+    color?: string                    // UI 颜色
+    planModeRequired?: boolean        // 是否需要 plan 审批
+    joinedAt: number                  // 加入时间
+    tmuxPaneId: string                // 终端 pane ID
+    cwd: string                       // 工作目录
+    worktreePath?: string             // Worktree 路径
+    sessionId?: string                // 会话 ID
+    subscriptions: string[]           // 消息订阅
+    backendType?: 'tmux'|'iterm2'|'in-process'
+    isActive?: boolean                // false=空闲, true/undefined=活跃
+    mode?: PermissionMode             // 当前权限模式
+  }>
+}
+```
+
+### 邮箱系统
+
+![Teams 邮箱系统](./images/09-teams-mailbox.png)
+
+**存储路径**：`~/.claude/teams/{team_name}/inboxes/{agent_name}.json`
+
+```typescript
+// src/utils/teammateMailbox.ts
+type TeammateMessage = {
+  from: string        // 发送者名称
+  text: string        // 消息内容（纯文本或 JSON）
+  timestamp: string   // ISO 时间戳
+  read: boolean       // 是否已读
+  color?: string      // 发送者颜色
+  summary?: string    // 5-10 词摘要
+}
+```
+
+**并发安全**：使用 `proper-lockfile` 文件锁，10 次重试，5-100ms 指数退避。
+
+**消息类型**：
+
+| 消息 | 格式 | 用途 |
+|------|------|------|
+| 纯文本 | `string` | 普通对话消息 |
+| shutdown_request | `{ type, reason }` | 请求队友关停 |
+| shutdown_response | `{ type, request_id, approve }` | 批准/拒绝关停 |
+| plan_approval_response | `{ type, request_id, approve }` | 审批 plan |
+| permission_request | `{ type, toolName, path }` | 权限请求 |
+| idle_notification | 特殊格式 | 空闲通知 |
+
+### 收件箱轮询
+
+```typescript
+// src/hooks/useInboxPoller.ts
+// 轮询间隔：1000ms
+
+useEffect(() => {
+  const interval = setInterval(async () => {
+    const messages = await readUnreadMessages(agentName, teamName)
+    
+    for (const msg of messages) {
+      if (isShutdownRequest(msg.text)) {
+        // 处理关停请求
+      } else if (isPlanApprovalResponse(msg.text)) {
+        // 处理 plan 审批
+      } else if (isPermissionRequest(msg.text)) {
+        // 路由到权限系统
+      } else {
+        // 纯文本消息 → 提交为新对话轮
+        onSubmitMessage(formatted)
+      }
+    }
+  }, INBOX_POLL_INTERVAL_MS)
+}, [])
+```
+
+**消息处理状态**：
+
+| 状态 | 说明 |
+|------|------|
+| `pending` | 新收到，等待处理 |
+| `processing` | 正在处理（权限请求等） |
+| `processed` | 已处理完毕 |
+
+### 消息路由
+
+```
+SendMessage({ to, message })
+  │
+  ├─ to === "*" → 广播
+  │   └─ 遍历所有队友，逐个写入 mailbox
+  │
+  ├─ agentNameRegistry.has(to) → in-process 子代理
+  │   └─ 通过 AppState pending messages 队列路由
+  │
+  ├─ teamFile.members.find(to) → 进程级队友
+  │   └─ writeToMailbox(to, message, teamName)
+  │
+  ├─ to.startsWith("bridge:") → 远程会话
+  │   └─ postInterClaudeMessage(sessionId, message)
+  │
+  └─ to.startsWith("uds:") → Unix Domain Socket
+      └─ sendToUdsSocket(socketPath, message)
+```
+
+---
+
+## 六、后台任务引擎
+
+![后台任务引擎](./images/08-background-task.png)
+
+### LocalAgentTask 状态机
+
+```typescript
+// src/tasks/LocalAgentTask/LocalAgentTask.tsx
+type LocalAgentTaskState = {
+  type: 'local_agent'
+  agentId: AgentId                // 唯一标识
+  status: 'running' | 'completed' | 'failed' | 'killed'
+  isBackgrounded: boolean         // 前台 vs 后台
+  
+  progress: {
+    latestInputTokens: number     // 最新输入 tokens
+    cumulativeOutputTokens: number // 累计输出 tokens
+    toolUseCount: number          // 工具使用次数
+    recentActivities: ToolActivity[] // 最近 5 个活动
+    lastActivity: number          // 最后活动时间戳
+  }
+  
+  result?: AgentToolResult        // 最终结果
+  abortController: AbortController // 中止控制器
+  retain: boolean                 // UI 保持标志
+  evictAfter?: number             // 延迟清除时间戳
+}
+```
+
+**状态转换**：
+
+```
+              ┌──────────────────────────┐
+              │                          │
+  register    │    ┌──── killed ←── abort()
+    │         │    │
+    ▼         │    │
+ running ─────┼────┼──── completed ← finalizeAgentTool()
+              │    │
+              │    └──── failed ← error / timeout
+              │
+              └──── evict ← notified && endTime > grace
+```
+
+### 进度追踪
+
+```typescript
+// ProgressTracker
+function updateProgressFromMessage(tracker, message) {
+  // 1. 累积输入 tokens（取最新值）
+  tracker.latestInputTokens = message.usage?.input_tokens
+  
+  // 2. 累加输出 tokens
+  tracker.cumulativeOutputTokens += message.usage?.output_tokens
+  
+  // 3. 统计工具使用
+  tracker.toolUseCount += countToolUses(message)
+  
+  // 4. 维护最近活动（循环缓冲区，max 5）
+  tracker.recentActivities = [...activities].slice(-5)
+}
+```
+
+### 通知系统
+
+```typescript
+// src/utils/messageQueueManager.ts
+function enqueuePendingNotification(taskId, result) {
+  // 1. 原子设置 notified 标志（防重复）
+  if (task.notified) return
+  task.notified = true
+  
+  // 2. 格式化 XML 通知
+  const notification = `
+    <task-notification>
+      <task-id>${taskId}</task-id>
+      <status>${status}</status>
+      <summary>${summary}</summary>
+      <output-file>${outputPath}</output-file>
+    </task-notification>
+  `
+  
+  // 3. 入队等待主代理消费
+  pendingNotifications.push(notification)
+}
+```
+
+### 输出管理
+
+**存储路径**：`~/.claude/temp/{sessionId}/tasks/{taskId}.output`
+
+| 参数 | 值 |
+|------|----|
+| 最大容量 | 5GB / 文件 |
+| 循环缓冲区 | 1000 行 |
+| 轮询间隔 | 1 秒 |
+| 终态保持时间 | 3 秒（任务面板 30 秒） |
+| 写入方式 | 队列异步写入，防内存堆积 |
+| 安全措施 | O_NOFOLLOW 防符号链接攻击 |
+
+---
+
+## 七、DreamTask — 自动记忆整合
+
+DreamTask 是特殊的后台 Agent，用于跨会话记忆整合。
+
+### 触发条件
+
+```typescript
+// src/services/autoDream/autoDream.ts
+function executeAutoDream() {
+  // 四重门控：
+  if (hoursSinceLastConsolidation < minHours) return  // 时间门：默认 24h
+  if (sessionsSinceLastConsolidation < minSessions) return // 会话门：默认 5 次
+  if (otherProcessConsolidating) return               // 锁门：互斥
+  if (timeSinceLastScan < 10min) return               // 扫描节流：10 分钟
+}
+```
+
+### DreamTask 状态
+
+```typescript
+type DreamTaskState = {
+  type: 'dream'
+  phase: 'starting' | 'updating'  // updating = 已开始编辑文件
+  sessionsReviewing: number       // 正在审查的会话数
+  filesTouched: string[]          // 编辑过的文件路径
+  turns: DreamTurn[]              // 对话轮次记录
+}
+```
+
+---
+
+## 八、Worktree 隔离实现
+
+### 创建流程
+
+```typescript
+// src/utils/worktree.ts
+async function createAgentWorktree(slug) {
+  // 1. 校验 slug（防目录逃逸攻击）
+  validateWorktreeSlug(slug)
+  
+  // 2. 创建 git worktree
+  git worktree add {path} -b {branch}
+  
+  // 3. 符号链接大目录（节省磁盘）
+  symlink(node_modules, worktree/node_modules)
+  
+  // 4. 应用 sparse-checkout（如配置）
+  if (sparseCheckoutPaths) {
+    git sparse-checkout set {paths}
+  }
+  
+  // 5. 返回 WorktreeSession
+  return { worktreePath, worktreeBranch, headCommit }
+}
+```
+
+### 清理机制
+
+- Agent 完成后自动检测是否有改动（`hasWorktreeChanges()`）
+- 有改动：返回 worktree 路径和分支名给用户
+- 无改动：自动删除 worktree（`removeAgentWorktree()`）
+- 异常退出：通过 `registerTeamForSessionCleanup()` 确保清理
+
+---
+
+## 九、权限同步机制
+
+### 团队级权限
+
+```typescript
+type TeamAllowedPath = {
+  path: string        // 绝对目录路径
+  toolName: string    // 适用的工具（如 "Edit", "Write"）
+  addedBy: string     // 添加者名称
+  addedAt: number     // 添加时间
+}
+```
+
+队友启动时，自动继承团队级权限规则。
+
+### Bubble 模式
+
+Fork Agent 使用 `bubble` 权限模式 — 权限提示冒泡到父代理终端：
+
+```
+Fork Agent 需要权限
+  │
+  └─ bubble 模式 → 权限请求发送到父代理
+       │
+       └─ 父代理的 ToolUseConfirm 对话框显示
+            │
+            ├─ 用户批准 → 结果回传给 Fork Agent
+            └─ 用户拒绝 → Fork Agent 收到拒绝
+```
+
+### In-Process 队友权限
+
+```
+队友需要权限
+  │
+  ├─ 有 UI bridge → 直接显示在 Leader 的确认对话框
+  │     └─ 带 worker badge 标识来源
+  │
+  └─ 无 UI bridge → 通过 mailbox 排队
+        └─ Leader 的 useSwarmPermissionPoller 处理
+```
+
+---
+
+## 十、Agent 生命周期完整数据流
+
+```
+1. 用户触发 Agent Tool
+   │
+2. AgentTool.call() 路由分发
+   │
+3. 解析 Agent 定义
+   ├─ 查找 Agent 类型（内置 > 插件 > 用户 > 项目）
+   ├─ 加载系统提示词
+   ├─ 解析工具池（三层过滤）
+   └─ 确定权限模式和模型
+   │
+4. 创建隔离上下文
+   ├─ createSubagentContext()（克隆 readFileState）
+   ├─ 生成 agentId
+   ├─ 创建 AbortController
+   └─ 可选：创建 worktree
+   │
+5. 注册任务状态
+   ├─ registerAsyncAgent() 或 registerAgentForeground()
+   ├─ 发射 SDK event: task_started
+   └─ Perfetto trace 注册
+   │
+6. 执行查询循环
+   ├─ query() async generator
+   │   ├─ 构建 API 请求（含 CacheSafeParams）
+   │   ├─ 流式处理响应
+   │   ├─ 执行工具调用
+   │   └─ 累积 usage 指标
+   ├─ 更新进度（ProgressTracker）
+   └─ 记录 transcript
+   │
+7. 完成处理
+   ├─ finalizeAgentTool()（提取结果文本）
+   ├─ completeAgentTask()（标记完成）
+   ├─ 清理资源
+   │   ├─ 释放文件状态缓存
+   │   ├─ 关闭 MCP 连接
+   │   └─ 删除 worktree（如有）
+   ├─ enqueuePendingNotification()（通知主代理）
+   └─ 发射 SDK event: task_completed
+   │
+8. 主代理消费结果
+   ├─ 同步：直接获取 AgentToolResult
+   └─ 异步：收到 <task-notification> 后处理
+```
+
+---
+
+## 十一、关键源文件索引
+
+### Agent Tool 核心
+
+| 文件 | 职责 |
+|------|------|
+| `src/tools/AgentTool/AgentTool.tsx` | 主工具实现，路由分发 |
+| `src/tools/AgentTool/runAgent.ts` | 执行引擎，查询循环 |
+| `src/tools/AgentTool/agentToolUtils.ts` | 工具池解析，结果终结 |
+| `src/tools/AgentTool/forkSubagent.ts` | Fork 语义，消息继承 |
+| `src/tools/AgentTool/loadAgentsDir.ts` | Agent 定义类型，解析加载 |
+| `src/tools/AgentTool/builtInAgents.ts` | 内置 Agent 注册表 |
+| `src/tools/AgentTool/prompt.ts` | Agent 工具 schema 和文档 |
+| `src/tools/AgentTool/agentMemory.ts` | Agent 持久记忆 |
+
+### Swarm 基础设施
+
+| 文件 | 职责 |
+|------|------|
+| `src/tools/TeamCreateTool/TeamCreateTool.ts` | 团队创建 |
+| `src/tools/TeamDeleteTool/TeamDeleteTool.ts` | 团队清理 |
+| `src/tools/SendMessageTool/SendMessageTool.ts` | 代理间通信 |
+| `src/tools/shared/spawnMultiAgent.ts` | 队友生成入口 |
+| `src/utils/swarm/spawnInProcess.ts` | 进程内队友生成 |
+| `src/utils/swarm/teamHelpers.ts` | 团队文件读写 |
+| `src/utils/swarm/constants.ts` | 常量定义 |
+| `src/utils/swarm/teammateInit.ts` | 队友初始化 |
+| `src/utils/swarm/permissionSync.ts` | 权限同步 |
+| `src/utils/teammate.ts` | 队友身份解析 |
+| `src/utils/teammateMailbox.ts` | 邮箱消息队列 |
+| `src/utils/teamDiscovery.ts` | 团队发现 |
+| `src/hooks/useInboxPoller.ts` | 收件箱轮询 |
+
+### 上下文管理
+
+| 文件 | 职责 |
+|------|------|
+| `src/utils/forkedAgent.ts` | 缓存安全参数，子代理上下文 |
+| `src/utils/systemPrompt.ts` | 系统提示词优先级构建 |
+| `src/utils/model/agent.ts` | Agent 模型解析 |
+| `src/utils/worktree.ts` | Git worktree 隔离 |
+
+### 任务系统
+
+| 文件 | 职责 |
+|------|------|
+| `src/tasks/LocalAgentTask/LocalAgentTask.tsx` | 本地 Agent 任务 |
+| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` | 远程 Agent 任务 |
+| `src/tasks/InProcessTeammateTask/` | 进程内队友任务 |
+| `src/tasks/DreamTask/DreamTask.ts` | 记忆整合任务 |
+| `src/utils/task/framework.ts` | 任务注册、状态更新 |
+| `src/utils/task/diskOutput.ts` | 任务输出文件管理 |
+| `src/utils/messageQueueManager.ts` | 通知队列 |
+
+### 协调器
+
+| 文件 | 职责 |
+|------|------|
+| `src/coordinator/coordinatorMode.ts` | 协调器模式配置 |
+
+---
+
+## 十二、Feature Flags
+
+| Flag | 控制内容 |
+|------|----------|
+| `FORK_SUBAGENT` | 启用 Fork 路径（省略 subagent_type） |
+| `BUILTIN_EXPLORE_PLAN_AGENTS` | 启用 Explore/Plan Agent |
+| `VERIFICATION_AGENT` | 启用 verification Agent |
+| `COORDINATOR_MODE` | 启用协调器模式 |
+| `KAIROS` | 启用 cwd 参数 |
+| `tengu_auto_background_agents` | 120 秒后自动后台化 |
+| `tengu_slim_subagent_claudemd` | 只读 Agent 省略 CLAUDE.md |
+| `tengu_agent_list_attach` | Agent 列表通过 attachment 注入 |

cc-haha/docs/agent/03-agent-framework.md

@@ -0,0 +1,790 @@
+# Claude Code Agent 框架深度解析
+
+> 从源码视角剖析全球最流行 AI Code Editor 背后的 Agent 架构设计哲学。
+
+<p align="center">
+<a href="#一核心-agent-循环">核心循环</a> · <a href="#二系统提示词工程">提示词工程</a> · <a href="#三工具系统设计">工具系统</a> · <a href="#四上下文管理与压缩">上下文管理</a> · <a href="#五技能与插件生态">技能与插件</a> · <a href="#六权限与安全体系">权限与安全</a> · <a href="#七故障恢复机制">故障恢复</a> · <a href="#八与-langchain-react-的本质区别">对比分析</a> · <a href="#九为什么-claude-code-能做到这么好">成功之道</a>
+</p>
+
+![Agent 框架架构总览](./images/11-agent-framework-overview.png)
+
+---
+
+## 导读：一个根本性的问题
+
+如果你仔细观察 Claude Code 的行为，会发现一些非常有趣的现象：
+
+- 它能在一次对话中修改几十个文件，且极少出错
+- 它能自动恢复各种边界情况（token 溢出、API 超时、工具失败）
+- 它能同时管理多个子代理协作完成复杂任务
+- 长对话不会退化，反而能越来越精准
+
+这些能力的背后，是一套精心设计的 Agent 框架。本文从源码层面，完整解构这套框架的设计哲学。
+
+---
+
+## 一、核心 Agent 循环
+
+### 1.1 不是 ReAct，而是 Async Generator 状态机
+
+大多数 Agent 框架（包括 LangChain）采用经典的 **ReAct** 模式：
+
+```
+思考(Thought) → 行动(Action) → 观察(Observation) → 思考 → ...
+```
+
+Claude Code **没有**采用这个模式。它的核心是一个 **异步生成器（Async Generator）驱动的状态机**，定义在 `src/query.ts`（约 1730 行）：
+
+```typescript
+// src/query.ts:219
+export async function* query(params: QueryParams): AsyncGenerator<...>
+```
+
+这个函数是整个 Agent 的心脏。它不是简单的"想-做-看"循环，而是一个**流式状态机**，通过 `yield` 实时产出消息，通过状态赋值（而非递归调用）驱动循环。
+
+### 1.2 状态结构
+
+```typescript
+// src/query.ts:204-217
+type State = {
+  messages: Message[]                    // 完整对话历史
+  toolUseContext: ToolUseContext          // 工具执行上下文
+  autoCompactTracking: AutoCompactTracking  // 自动压缩追踪
+  maxOutputTokensRecoveryCount: number   // 输出恢复计数
+  hasAttemptedReactiveCompact: boolean   // 是否已尝试反应式压缩
+  maxOutputTokensOverride: number        // 输出 token 覆盖值
+  pendingToolUseSummary: Promise<...>    // 待处理的工具摘要
+  stopHookActive: boolean               // 停止钩子状态
+  turnCount: number                      // 对话轮数
+  transition: Continue | undefined       // 状态转换原因
+}
+```
+
+### 1.3 核心循环的五个阶段
+
+整个 `while (true)` 循环（`src/query.ts:307-1728`）分为五个阶段：
+
+![Agent 核心循环](./images/12-agent-core-loop.png)
+
+#### 阶段 1：消息准备与智能压缩（第 365-543 行）
+
+在调用 API 之前，对话历史会经过四层压缩处理：
+
+| 压缩策略 | 原理 | 触发时机 |
+|----------|------|----------|
+| **Snip 压缩** | 智能删除旧消息中的冗余 token | 每轮自动 |
+| **Micro 压缩** | 修改已缓存消息的内容 | 每轮自动 |
+| **上下文折叠** | 分阶段摘要历史消息 | 上下文接近限制时 |
+| **Auto Compact** | 通过 Claude 生成完整摘要 | 上下文严重不足时 |
+
+这是 Claude Code 能处理**极长对话**而不退化的关键——它不会简单地截断历史，而是**智能地压缩和保留关键信息**。
+
+#### 阶段 2：流式 API 调用（第 652-954 行）
+
+```typescript
+// src/query.ts:659-708
+for await (const message of deps.callModel({
+  messages: prependUserContext(messagesForQuery, userContext),
+  systemPrompt: fullSystemPrompt,
+  thinkingConfig,
+  tools: toolUseContext.options.tools,
+  signal: abortController.signal,
+}))
+```
+
+关键设计：**工具在流式传输过程中就开始执行**，而不是等模型生成完整响应。这通过 `StreamingToolExecutor` 实现——当模型生成 `tool_use` 块时，工具立即开始运行。
+
+#### 阶段 3：决策点（第 1062-1358 行）
+
+```
+模型响应完成
+  │
+  ├─ 有工具调用？ ──→ 继续循环（阶段 4）
+  │
+  └─ 无工具调用？ ──→ 运行 Stop 钩子 → 检查 token 预算 → 返回结果
+```
+
+#### 阶段 4：工具编排执行（第 1363-1409 行）
+
+工具执行不是简单的逐个运行，而是有精心设计的**编排策略**（`src/services/tools/toolOrchestration.ts`）：
+
+```
+工具调用列表
+  │
+  ├─ 分区：只读 vs 写入
+  │
+  ├─ 只读工具 ──→ 并行执行（最多 10 个并发）
+  │
+  └─ 写入工具 ──→ 串行执行（防止竞态条件）
+```
+
+#### 阶段 5：状态更新与循环（第 1704-1728 行）
+
+这是整个设计最优雅的部分——**通过状态赋值而非递归调用驱动循环**：
+
+```typescript
+// src/query.ts:1715-1728
+const next: State = {
+  messages: [...messagesForQuery, ...assistantMessages, ...toolResults],
+  toolUseContext: toolUseContextWithQueryTracking,
+  autoCompactTracking: tracking,
+  turnCount: nextTurnCount,
+  transition: { reason: 'next_turn' },
+}
+state = next
+// 回到 while(true) 循环顶部
+```
+
+没有递归，没有回调地狱，只是简单的 `state = next` 然后 `continue`。这保证了：
+- **内存稳定**：不会因为深度递归导致栈溢出
+- **状态可追溯**：每一轮的状态转换原因都被记录
+- **恢复可控**：任何阶段的错误都可以通过修改 state 来恢复
+
+---
+
+## 二、系统提示词工程
+
+### 2.1 分层构建架构
+
+系统提示词不是一个静态字符串，而是通过**分层管道**动态组装的（`src/constants/prompts.ts:444-577`）：
+
+![系统提示词构建流程](./images/13-system-prompt-pipeline.png)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    静态可缓存区域                              │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │ 角色定义  │  系统规则  │  任务指导  │  工具说明  │  风格  │  │
+│  └───────────────────────────────────────────────────────┘  │
+├─────────────────────── 缓存边界 ────────────────────────────┤
+│                    动态可变区域                                │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │ 会话指引 │ 记忆系统 │ 环境信息 │ MCP 指令 │ Token 预算 │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+这里的**缓存边界（`SYSTEM_PROMPT_DYNAMIC_BOUNDARY`）**是一个关键设计：
+
+- **边界之上**：跨用户、跨组织通用的内容，使用 `scope: 'global'` 缓存
+- **边界之下**：用户/会话特定的内容，使用 `scope: 'ephemeral'` 缓存
+
+这意味着 Claude Code 的系统提示词**不需要每次都重新处理**——静态部分在全球范围内共享缓存，大幅降低延迟和成本。
+
+### 2.2 两种 Section 类型
+
+```typescript
+// src/constants/systemPromptSections.ts
+
+// 类型 1：缓存 Section（计算一次，整个会话复用）
+systemPromptSection('memory', async () => {
+  return buildMemoryLines()  // 读取 CLAUDE.md、记忆文件等
+})
+
+// 类型 2：缓存破坏 Section（每轮重新计算）
+DANGEROUS_uncachedSystemPromptSection('mcp_instructions', async () => {
+  return getMcpInstructions()  // MCP 服务器可能中途连接/断开
+}, 'MCP servers can connect/disconnect mid-session')
+```
+
+### 2.3 CLAUDE.md 的加载机制
+
+CLAUDE.md 是用户自定义指令系统，按**优先级从低到高**加载（`src/utils/claudemd.ts`）：
+
+```
+/etc/claude-code/CLAUDE.md          ← 全局管理配置（最低优先级）
+  ↓
+~/.claude/CLAUDE.md                 ← 用户全局指令
+  ↓
+项目根目录/CLAUDE.md                 ← 项目级指令
+项目根目录/.claude/CLAUDE.md
+项目根目录/.claude/rules/*.md
+  ↓
+项目根目录/CLAUDE.local.md           ← 本地私有指令（最高优先级）
+```
+
+支持 `@path` 语法递归引用其他文件，并自动防止循环引用。
+
+### 2.4 系统提示词的优先级解析
+
+最终的系统提示词通过 `buildEffectiveSystemPrompt()`（`src/utils/systemPrompt.ts:41-123`）按优先级决定：
+
+1. **Override 提示词** — 完全替换（Loop 模式使用）
+2. **Coordinator 提示词** — 协调者模式
+3. **Agent 提示词** — 自定义 Agent 定义
+4. **Custom 提示词** — `--system-prompt` 命令行参数
+5. **默认提示词** — 标准系统提示词
+6. **Append 提示词** — 始终追加到末尾
+
+---
+
+## 三、工具系统设计
+
+### 3.1 工具接口：不只是函数调用
+
+Claude Code 的工具不是简单的"名称 + 参数 + 执行"。每个工具是一个**完整的生命周期管理单元**（`src/Tool.ts:362-695`）：
+
+```typescript
+type Tool<Input, Output> = {
+  // 身份
+  name: string
+  aliases?: string[]        // 向后兼容的旧名称
+  searchHint?: string       // ToolSearch 关键词匹配
+
+  // 能力声明
+  isEnabled(): boolean
+  isConcurrencySafe(input): boolean   // 是否可并行
+  isReadOnly(input): boolean          // 是否只读
+  isDestructive(input): boolean       // 是否破坏性
+
+  // 生命周期
+  validateInput(input, context)       // 输入验证
+  checkPermissions(input, context)    // 权限检查
+  call(input, context, ...)           // 实际执行
+
+  // 输出与渲染
+  renderToolUseMessage(input)         // 渲染调用信息
+  renderToolResultMessage(content)    // 渲染结果信息
+  renderToolUseProgressMessage(...)   // 渲染进度
+  mapToolResultToToolResultBlockParam()  // 映射为 API 格式
+
+  // 智能特性
+  inputSchema: Zod schema             // Zod 类型验证
+  maxResultSizeChars: number           // 结果大小阈值
+  toAutoClassifierInput(input)         // 安全分类器输入
+  getToolUseSummary?(input): string    // 工具使用摘要
+}
+```
+
+这种设计使得每个工具都是**自描述、自验证、自渲染**的——框架不需要了解工具的内部逻辑，只需调用标准接口。
+
+### 3.2 工具注册：三阶段流水线
+
+工具的发现和注册分三个阶段（`src/tools.ts`）：
+
+```
+阶段 1：基础工具池（getAllBaseTools）
+  │  ~48 个内置工具
+  │  + Feature Flag 控制的条件工具
+  │
+阶段 2：过滤（getTools）
+  │  按权限模式过滤
+  │  按 REPL 模式过滤
+  │  按 isEnabled() 过滤
+  │
+阶段 3：MCP 合并（assembleToolPool）
+     + MCP 服务器提供的动态工具
+     去重（内置优先）
+     排序（缓存稳定性）
+```
+
+### 3.3 工具执行管道
+
+一次工具调用要经过**7 步管道**（`src/services/tools/toolExecution.ts`）：
+
+```
+1. 工具查找 ─→ 2. 输入解析（Zod） ─→ 3. 自定义验证
+       │
+4. Pre-Tool 钩子 ─→ 5. 权限检查 ─→ 6. 实际执行 ─→ 7. Post-Tool 钩子
+```
+
+每一步都可以**中断、修改或增强**执行流程。这不是简单的 `try { tool.call(input) } catch`，而是一个完整的中间件管道。
+
+### 3.4 工具延迟加载（Tool Deferred Loading）
+
+Claude Code 有 48+ 个内置工具。如果每次 API 调用都把所有工具定义发给模型，会浪费大量 token。解决方案：
+
+```typescript
+// 工具可以标记为"延迟加载"
+{
+  shouldDefer: true,       // 只在 ToolSearch 中列出名称
+  alwaysLoad: false,       // 不在初始提示词中包含完整 schema
+  searchHint: "notebook"   // 搜索关键词
+}
+```
+
+模型需要时通过 `ToolSearch` 工具动态获取完整定义。这大幅减少了系统提示词的大小。
+
+---
+
+## 四、上下文管理与压缩
+
+### 4.1 无限对话的秘密
+
+Claude Code 宣称"对话没有上下文限制"，这背后是一套**四级压缩系统**：
+
+![上下文压缩策略](./images/14-context-compression.png)
+
+#### 第 1 级：Snip 压缩
+
+对已处理的消息进行智能裁剪——移除重复的文件内容、过长的工具输出等。
+
+#### 第 2 级：Micro 压缩
+
+修改已缓存消息的内容，而不改变缓存键。这是一种"原地优化"策略。
+
+#### 第 3 级：上下文折叠（Context Collapse）
+
+将历史消息分阶段摘要。不是一次性摘要全部，而是**渐进式折叠**——先摘要最旧的消息，保留最近的细节。
+
+#### 第 4 级：Auto Compact
+
+当所有局部优化都不够时，通过 Claude 自身生成一个完整的对话摘要，替换所有历史消息。
+
+### 4.2 系统上下文注入
+
+每次 API 调用前，自动注入两种上下文（`src/context.ts`）：
+
+```typescript
+// 系统上下文（memoized，整个会话缓存）
+getSystemContext() → {
+  gitStatus,           // 当前分支、最近提交、文件状态
+  cacheBreakerInjection  // 系统级注入
+}
+
+// 用户上下文（memoized，CLAUDE.md 变化时清除）
+getUserContext() → {
+  claudeMdContent,     // 所有 CLAUDE.md 合并内容
+  currentDate,         // 当前日期
+  mcpInstructions      // MCP 服务器指令
+}
+```
+
+### 4.3 系统提醒（System Reminders）
+
+系统提醒是一种特殊的**附件消息**，注入到工具结果或用户消息中（`src/utils/attachments.ts`）：
+
+```xml
+<system-reminder>
+  这里是系统级的上下文信息，与具体的工具结果无关。
+</system-reminder>
+```
+
+用途包括：
+- 文件读取时的安全警告
+- 记忆系统的时效提醒
+- 用户侧问的附带信息
+- Deferred 工具的可用通知
+
+---
+
+## 五、技能与插件生态
+
+### 5.1 技能系统（Skills）
+
+技能是 Claude Code 最强大的扩展机制之一。它不是简单的"命令别名"，而是**完整的 AI 行为定义**。
+
+#### 技能定义结构
+
+```typescript
+type BundledSkillDefinition = {
+  name: string
+  description: string
+  whenToUse?: string           // 模型自动判断何时使用
+  allowedTools?: string[]      // 限制工具池
+  model?: string               // 指定模型
+  hooks?: HooksSettings        // 生命周期钩子
+  context?: 'inline' | 'fork'  // 内联 or 独立上下文
+  agent?: string               // 关联的 Agent 类型
+  getPromptForCommand: (args, context) => Promise<ContentBlockParam[]>
+}
+```
+
+#### 两种执行上下文
+
+| 上下文 | 行为 | 适用场景 |
+|--------|------|----------|
+| `inline` | 技能内容直接展开到当前对话 | 简单指令、格式模板 |
+| `fork` | 技能作为子代理在独立上下文中运行 | 复杂工作流、需要独立 token 预算 |
+
+#### 技能发现来源
+
+```
+内置技能（bundled）         ← 编译到 CLI 中，15+ 个
+  ↓
+插件技能（plugin）          ← 插件注册
+  ↓
+用户技能（~/.claude/skills/） ← 用户全局
+  ↓
+项目技能（.claude/skills/）   ← 项目级
+  ↓
+策略技能（policy）           ← 组织管理
+```
+
+### 5.2 插件系统（Plugins）
+
+插件是更高层级的扩展单元，可以包含**技能、钩子、MCP 服务器、LSP 服务器**：
+
+```typescript
+type BuiltinPluginDefinition = {
+  name: string
+  description: string
+  skills?: BundledSkillDefinition[]     // 技能集合
+  hooks?: HooksSettings                  // 生命周期钩子
+  mcpServers?: Record<string, McpServerConfig>  // MCP 服务器
+  lspServers?: Record<string, LspServerConfig>  // LSP 服务器
+  isAvailable?: () => boolean            // 可用性检查
+  defaultEnabled?: boolean               // 默认启用
+}
+```
+
+插件的关键设计：**用户可切换启用/禁用**，这与直接注册的技能不同。
+
+### 5.3 钩子系统（Hooks）
+
+钩子是整个生命周期的**可编程拦截点**：
+
+```
+SessionStart ─→ UserPromptSubmit ─→ PreToolUse ─→ [工具执行]
+       │                                              │
+       │                                          PostToolUse
+       │                                              │
+       └─ SubagentStart ←─── Stop ←─── TaskCompleted ←┘
+              │
+          SubagentStop ─→ SessionEnd
+```
+
+钩子通过 shell 命令执行，退出码控制行为：
+- **0**：成功，stdout 内容按事件类型处理
+- **2**：stderr 内容展示给模型或用户
+- **其他**：仅展示给用户
+
+### 5.4 MCP：模型上下文协议
+
+MCP 是 Claude Code 与外部世界交互的标准协议。工具命名规范：
+
+```
+mcp__{标准化服务器名}__{工具名}
+例如：mcp__chrome_devtools__take_screenshot
+```
+
+支持的传输方式：`stdio`、`sse`、`http`、`websocket`、`sdk`
+
+MCP 工具在运行时动态发现，与内置工具**无缝合并**到统一的工具池中。
+
+---
+
+## 六、权限与安全体系
+
+### 6.1 分层权限模型
+
+```
+┌─────────────────────────────────────┐
+│         权限规则（Rules）             │
+│  来源：userSettings, projectSettings │
+│        flagSettings, policySettings  │
+├─────────────────────────────────────┤
+│        权限模式（Modes）              │
+│  default | plan | acceptEdits       │
+│  bypassPermissions | auto | bubble  │
+├─────────────────────────────────────┤
+│         钩子（Hooks）                │
+│  PreToolUse 可拦截或修改            │
+├─────────────────────────────────────┤
+│      安全分类器（Classifier）         │
+│  ML 模型评估工具调用安全性           │
+└─────────────────────────────────────┘
+```
+
+### 6.2 权限决策流
+
+每次工具调用的权限检查：
+
+```typescript
+type PermissionResult =
+  | { behavior: 'allow', updatedInput?, decisionReason }
+  | { behavior: 'ask',  message, suggestions }
+  | { behavior: 'deny', message, decisionReason }
+  | { behavior: 'passthrough', message }
+```
+
+决策原因追溯：
+- `type: 'rule'` — 匹配了权限规则
+- `type: 'mode'` — 权限模式决定
+- `type: 'hook'` — 钩子拦截
+- `type: 'classifier'` — ML 分类器判定
+
+### 6.3 权限规则模式匹配
+
+```javascript
+// 精确匹配
+{ tool: 'Bash', behavior: 'deny' }
+
+// 参数模式匹配
+{ tool: 'Bash(git *)', behavior: 'allow' }   // 允许所有 git 命令
+{ tool: 'Bash(rm -rf *)', behavior: 'deny' }  // 禁止 rm -rf
+
+// 通配符
+{ tool: 'File*', behavior: 'allow' }          // 允许所有 File 开头的工具
+```
+
+---
+
+## 七、故障恢复机制
+
+这是 Claude Code 最精妙的设计之一。`src/query.ts` 的核心循环内置了**6 种恢复策略**：
+
+| 恢复策略 | 触发条件 | 恢复方式 |
+|----------|----------|----------|
+| `collapse_drain_retry` | prompt 过长 | 排空已暂存的上下文折叠，重试 |
+| `reactive_compact_retry` | 仍然过长 | 通过 Claude 生成摘要，重试 |
+| `max_output_tokens_escalate` | 触及 8k 默认限制 | 升级到 64k 限制重试 |
+| `max_output_tokens_recovery` | 触及任何限制 | 注入"继续"提示，重试（最多 3 次） |
+| `stop_hook_blocking` | Stop 钩子阻塞 | 将阻塞错误注入上下文，重试 |
+| `token_budget_continuation` | 预算尚余 | 注入预算提示，继续执行 |
+
+每种恢复都通过修改 `state` 实现：
+
+```typescript
+// 例：prompt 过长恢复
+if (error.type === 'prompt_too_long') {
+  // 排空所有暂存的折叠
+  const compacted = drainStagedCollapses(state.messages)
+  state = { ...state, messages: compacted, transition: { reason: 'collapse_drain_retry' } }
+  continue  // 回到循环顶部重试
+}
+```
+
+### 7.1 模型降级
+
+当主模型流式传输失败时，系统会：
+1. 清理孤立的未完成消息
+2. 切换到备用模型
+3. 用新模型重试
+
+### 7.2 媒体大小恢复
+
+当图片等媒体内容导致 token 超限时：
+- 触发反应式压缩
+- 自动剥离图片内容
+- 保留文本信息重试
+
+---
+
+## 八、与 LangChain/ReAct 的本质区别
+
+### 8.1 架构范式对比
+
+| 维度 | LangChain | Claude Code |
+|------|-----------|-------------|
+| **核心模式** | ReAct（Think→Act→Observe） | Async Generator 状态机 |
+| **执行模型** | 同步阻塞 | 流式非阻塞 |
+| **工具执行** | 等待模型完整响应后执行 | 流式传输中即时执行 |
+| **状态管理** | 外部 Memory 对象 | 内置状态赋值 + 循环 |
+| **错误恢复** | 需要手动编排 | 6 种内置恢复策略 |
+| **上下文压缩** | 简单截断或摘要 | 四级渐进式压缩 |
+| **多 Agent** | Chain/Graph 显式编排 | 统一工具接口 + 状态机 |
+| **扩展机制** | Python 类继承 | 技能 + 插件 + 钩子 + MCP |
+| **缓存策略** | 无 | 全局/会话/按轮三级缓存 |
+
+### 8.2 为什么不用 ReAct？
+
+ReAct 模式有几个固有限制：
+
+1. **串行瓶颈**：每一步必须等待完整的"思考→行动→观察"循环
+2. **无流式能力**：模型生成完整响应后才能开始执行工具
+3. **恢复困难**：没有统一的状态表示，难以实现自动恢复
+4. **缓存不友好**：每次循环的 prompt 结构变化大，难以利用缓存
+
+Claude Code 的 Async Generator 模式解决了所有这些问题：
+
+- **流式执行**：工具在模型生成过程中就开始运行
+- **状态可控**：`State` 对象包含所有需要的信息，恢复只需修改状态
+- **缓存优化**：静态提示词全局缓存，动态部分最小化
+- **并行能力**：只读工具自动并行，写入工具串行保序
+
+### 8.3 与 LangChain Agent 的具体差异
+
+```
+LangChain Agent:
+  agent = initialize_agent(tools, llm, agent="zero-shot-react-description")
+  result = agent.run("do something")
+  # 内部：LLM → parse → tool → LLM → parse → tool → ... → final answer
+  # 每一步都是独立的 LLM 调用
+
+Claude Code Agent:
+  for await (const msg of query({ messages, tools, systemPrompt })) {
+    yield msg  // 实时产出消息
+    // 内部：流式 LLM → 流式工具执行 → 状态更新 → 继续
+    // 单次 API 调用可以触发多个工具，工具在流式中执行
+  }
+```
+
+关键差异：
+- LangChain 的每一"步"是一次完整的 LLM 调用
+- Claude Code 的每一"轮"可以包含多个工具调用，且工具在流式传输中执行
+- LangChain 需要 OutputParser 解析模型输出中的工具调用
+- Claude Code 直接使用 Anthropic API 的原生 `tool_use` 能力，无需解析
+
+### 8.4 与 LangGraph 的对比
+
+LangGraph 是 LangChain 的升级版，引入了图结构：
+
+| 维度 | LangGraph | Claude Code |
+|------|-----------|-------------|
+| **状态流转** | 显式图节点 + 边 | 隐式状态机（while + continue） |
+| **可视化** | 可导出为图 | 状态转换原因可追溯 |
+| **持久化** | Checkpoint + State | 文件系统 + 消息历史 |
+| **人机交互** | interrupt_before/after | 权限系统 + 钩子 |
+| **多 Agent** | 需要显式编排 | AgentTool 统一接口 |
+
+Claude Code 的优势在于**简单性**——不需要定义图结构，一个 while 循环就能处理所有情况。
+
+---
+
+## 九、为什么 Claude Code 能做到这么好？
+
+从源码分析中，我们可以总结出以下核心设计原则：
+
+### 9.1 流式优先（Streaming First）
+
+整个架构围绕 `AsyncGenerator` 设计，一切都是流式的：
+- 模型响应是流式的
+- 工具在流式中执行
+- 进度实时更新
+- 压缩策略是渐进式的
+
+这意味着用户**永远不需要等待**——看到模型在思考、工具在执行、结果在产出。
+
+### 9.2 智能缓存（Intelligent Caching）
+
+三级提示词缓存系统（`src/services/api/claude.ts:3213-3237`）：
+
+```
+Global Cache（跨组织）    ← 静态系统提示词
+  ↓
+Ephemeral Cache（会话级） ← 动态系统提示词
+  ↓
+Section Cache（轮级）     ← systemPromptSection 记忆化
+```
+
+这大幅降低了每次 API 调用的延迟和成本。
+
+### 9.3 优雅降级（Graceful Degradation）
+
+6 种恢复策略确保 Claude Code **几乎不会因为技术问题中断用户的工作流**：
+- Token 超限？自动压缩
+- API 超时？自动重试
+- 模型失败？降级到备用模型
+- 工具失败？记录错误，继续对话
+
+### 9.4 最小抽象原则（Minimal Abstraction）
+
+与 LangChain 的"万物皆抽象"不同，Claude Code 的核心只有：
+- **一个循环**（`while (true)` in `query()`）
+- **一个状态**（`State` 对象）
+- **一个接口**（`Tool` 类型）
+
+没有 Agent → AgentExecutor → Chain → Memory → Callback 的嵌套抽象层。这使得代码**易于理解、调试和扩展**。
+
+### 9.5 原生 API 集成（Native API Integration）
+
+Claude Code 直接使用 Anthropic API 的原生能力：
+- **原生工具调用**：无需 OutputParser，直接使用 `tool_use` 块
+- **原生流式传输**：无需包装层，直接消费 SSE 流
+- **原生缓存**：利用 API 的 prompt caching 特性
+- **原生思维链**：直接使用 extended thinking
+
+这避免了"框架税"——LangChain 等框架在 LLM 和开发者之间增加的抽象层。
+
+### 9.6 工具驱动的 Agent（Tool-Driven Agent）
+
+Claude Code 的哲学是：**Agent 的能力等于其工具的能力**。
+
+- 子代理生成？是一个工具（`AgentTool`）
+- 团队管理？是一个工具（`TeamCreate`/`SendMessage`）
+- 文件编辑？是一个工具（`FileEdit`）
+- 技能执行？是一个工具（`SkillTool`）
+
+这意味着**所有能力都通过统一的工具接口暴露**，模型通过自然语言推理来决定使用哪个工具。不需要显式的编排逻辑——模型本身就是编排器。
+
+### 9.7 深度集成的开发体验
+
+Claude Code 不是"通用 Agent + 代码插件"，而是**从底层为编码场景深度优化**：
+
+- **Git 感知**：自动注入 git 状态，理解分支、提交、diff
+- **文件系统感知**：理解项目结构，智能搜索文件
+- **Worktree 隔离**：安全的实验性修改环境
+- **LSP 集成**：语言服务器协议提供类型信息和诊断
+- **MCP 生态**：通过标准协议连接各种外部工具
+
+---
+
+## 十、架构总结
+
+### 核心组件关系
+
+```
+用户输入
+  │
+  ▼
+QueryEngine（src/QueryEngine.ts）
+  │
+  ├─ 构建系统提示词（prompts.ts + context.ts + claudemd.ts）
+  ├─ 组装工具池（tools.ts + MCP）
+  │
+  ▼
+query() 异步生成器循环（src/query.ts）
+  │
+  ├─ 阶段1: 消息压缩（snip → micro → collapse → compact）
+  ├─ 阶段2: 流式 API 调用（callModel + StreamingToolExecutor）
+  ├─ 阶段3: 决策点（继续 or 完成）
+  ├─ 阶段4: 工具编排（并行只读 + 串行写入）
+  └─ 阶段5: 状态更新（state = next → continue）
+       │
+       ├─ 恢复策略（6种）
+       ├─ 钩子系统（PreToolUse / PostToolUse / Stop / ...）
+       └─ 子代理生成（AgentTool → runAgent → 新的 query() 实例）
+            │
+            ├─ 同步前台
+            ├─ 异步后台（LocalAgentTask）
+            ├─ Fork（继承上下文）
+            └─ Teammate（邮箱通信）
+```
+
+### 一句话总结
+
+> **Claude Code 的 Agent 框架是一个以 AsyncGenerator 为核心的流式状态机，通过统一的工具接口暴露所有能力，配合四级上下文压缩、三级提示词缓存、六种故障恢复策略，实现了一个无需显式编排即可自主完成复杂编程任务的 AI 系统。**
+
+---
+
+## 十一、关键源文件索引
+
+| 组件 | 文件路径 | 说明 |
+|------|----------|------|
+| 核心循环 | `src/query.ts` | Agent 主循环（~1730 行） |
+| 查询引擎 | `src/QueryEngine.ts` | 高层封装（~687 行） |
+| 工具定义 | `src/Tool.ts` | Tool 类型系统（~792 行） |
+| 工具注册 | `src/tools.ts` | 工具发现和注册（~389 行） |
+| 工具执行 | `src/services/tools/toolExecution.ts` | 执行管道（~1500 行） |
+| 工具编排 | `src/services/tools/toolOrchestration.ts` | 并行/串行策略 |
+| 系统提示词 | `src/constants/prompts.ts` | 提示词组装（~577 行） |
+| 提示词 Sections | `src/constants/systemPromptSections.ts` | 分段缓存 |
+| 上下文管理 | `src/context.ts` | 系统/用户上下文 |
+| CLAUDE.md | `src/utils/claudemd.ts` | 用户指令加载 |
+| 记忆系统 | `src/memdir/memdir.ts` | 持久化记忆 |
+| Agent 生成 | `src/tools/AgentTool/AgentTool.tsx` | Agent 工具入口 |
+| Agent 运行 | `src/tools/AgentTool/runAgent.ts` | Agent 执行逻辑 |
+| Fork 代理 | `src/tools/AgentTool/forkSubagent.ts` | Fork 缓存优化 |
+| 团队管理 | `src/utils/swarm/teamHelpers.ts` | Teams 基础设施 |
+| 邮箱通信 | `src/utils/teammateMailbox.ts` | 异步消息队列 |
+| 技能系统 | `src/skills/bundledSkills.ts` | 技能注册与管理 |
+| 插件系统 | `src/plugins/builtinPlugins.ts` | 插件框架 |
+| 钩子系统 | `src/utils/hooks/hooksConfigManager.ts` | 钩子管理 |
+| 权限系统 | `src/utils/permissions/permissions.ts` | 权限检查 |
+| 状态管理 | `src/state/AppStateStore.ts` | 全局状态 |
+| 成本追踪 | `src/cost-tracker.ts` | API 成本计算 |
+| API 客户端 | `src/services/api/claude.ts` | Anthropic API 封装 |
+| MCP 客户端 | `src/services/mcp/client.ts` | MCP 协议实现 |
+| 协调者模式 | `src/coordinator/coordinatorMode.ts` | 多 Agent 编排 |
+| 远程会话 | `src/remote/RemoteSessionManager.ts` | CCR 连接管理 |
+| Bridge | `src/bridge/bridgeMain.ts` | 远程桥接 |
+
+---
+
+## 十二、进一步阅读
+
+- [使用指南](./01-usage-guide.md) — 面向用户的多 Agent 使用手册
+- [实现原理](./02-implementation.md) — 多 Agent 编排的技术细节
+- [Anthropic API 文档](https://docs.anthropic.com/) — 原生 API 能力
+- [MCP 协议规范](https://modelcontextprotocol.io/) — 模型上下文协议

cc-haha/docs/agent/index.md

@@ -0,0 +1,129 @@
+# Claude Code 多 Agent 系统文档
+
+> 完整的多 Agent 编排使用指南和实现原理文档
+
+---
+
+## 📚 文档目录
+
+### [01-usage-guide.md](./01-usage-guide.md) — 使用指南
+
+面向用户的完整使用手册，涵盖：
+
+- **Agent 工具**：参数详解、生成方式、后台运行
+- **六种内置 Agent**：general-purpose、Explore、Plan、verification、claude-code-guide、statusline-setup
+- **后台任务**：异步执行、进度追踪、完成通知
+- **Agent Teams**：团队创建、成员协作、消息通信
+- **Worktree 隔离**：独立环境、分支管理、安全上下文
+- **自定义 Agent**：定义格式、工具池配置、系统提示词
+
+**适合人群**：所有 Claude Code 用户
+
+---
+
+### [02-implementation.md](./02-implementation.md) — 实现原理
+
+面向开发者的技术深度解析，涵盖：
+
+- **架构总览**：5 大 Agent 类别、4 条生成路径
+- **Agent 生成流程**：同步/异步/Fork/Teammate 四种路径详解
+- **工具池系统**：三层过滤、常量定义、权限映射
+- **上下文传递**：CacheSafeParams、系统提示词构建、Fork 缓存优化
+- **Teams 内部机制**：TeamFile 结构、邮箱系统、收件箱轮询、消息路由
+- **后台任务引擎**：LocalAgentTask 生命周期、进度追踪、通知队列
+- **权限同步**：团队级权限、模式传播、bubble 模式
+- **完整数据流**：从 Agent Tool 调用到结果回传
+
+**适合人群**：贡献者、架构师、想深入了解实现的开发者
+
+---
+
+### [03-agent-framework.md](./03-agent-framework.md) — Agent 框架深度解析
+
+从源码视角剖析 Claude Code 底层 Agent 架构的设计哲学，涵盖：
+
+- **核心 Agent 循环**：AsyncGenerator 状态机、五阶段 while(true) 循环
+- **系统提示词工程**：分层构建、缓存边界、CLAUDE.md 加载机制
+- **工具系统设计**：完整生命周期管理、三阶段注册、七步执行管道
+- **上下文管理与压缩**：四级渐进式压缩、系统上下文注入、系统提醒
+- **技能与插件生态**：技能定义与发现、插件系统、钩子系统、MCP 集成
+- **权限与安全体系**：分层权限模型、规则模式匹配
+- **故障恢复机制**：6 种内置恢复策略、模型降级
+- **与 LangChain/ReAct 对比**：架构范式差异、为什么不用 ReAct
+- **为什么 Claude Code 能做到这么好**：7 大核心设计原则
+
+**适合人群**：想理解 AI Agent 框架设计的架构师、AI 应用开发者、技术研究者
+
+---
+
+## 🖼️ 配图说明
+
+所有配图采用深色背景（#1a1a2e）+ Anthropic 品牌橙铜色（#D97757）风格，与 Claude Code 官方文档一致。
+
+| 图片 | 说明 | 所属文档 |
+|------|------|----------|
+| `01-agent-overview.png` | 多 Agent 系统概览 — 架构全景 | 使用指南 |
+| `02-agent-types.png` | 六种内置 Agent — 类型对比矩阵 | 使用指南 |
+| `03-spawn-flow.png` | Agent 生成流程 — 四条路径决策树 | 使用指南 |
+| `04-agent-teams.png` | Agent Teams 协作 — 团队通信拓扑 | 使用指南 |
+| `05-architecture.png` | 实现架构总览 — 核心模块关系 | 实现原理 |
+| `06-context-passing.png` | 上下文传递 — CacheSafeParams 数据流 | 实现原理 |
+| `07-tool-pool.png` | 工具池系统 — 三层过滤流程 | 实现原理 |
+| `08-background-task.png` | 后台任务引擎 — 生命周期状态机 | 实现原理 |
+| `09-teams-mailbox.png` | Teams 邮箱系统 — 消息路由拓扑 | 实现原理 |
+| `10-fork-cache.png` | Fork 缓存优化 — 字节级一致共享 | 实现原理 |
+| `11-agent-framework-overview.png` | Agent 框架架构总览 — 核心组件关系 | 框架解析 |
+| `12-agent-core-loop.png` | 核心 Agent 循环 — 五阶段状态机 | 框架解析 |
+| `13-system-prompt-pipeline.png` | 系统提示词构建 — 分层缓存流水线 | 框架解析 |
+| `14-context-compression.png` | 上下文压缩 — 四级渐进式策略 | 框架解析 |
+
+---
+
+## 🚀 快速开始
+
+### 用户
+
+1. 阅读 [使用指南](./01-usage-guide.md)
+2. 了解六种内置 Agent 及其适用场景
+3. 尝试在对话中使用 Agent 工具生成子代理
+4. 探索 Agent Teams 多代理协作
+
+### 开发者
+
+1. 阅读 [实现原理](./02-implementation.md)
+2. 查看源码位置：
+   - `src/tools/AgentTool/` — Agent 工具实现
+   - `src/tools/TeamCreateTool/` — 团队创建
+   - `src/tools/SendMessageTool/` — 代理间通信
+   - `src/utils/swarm/` — Swarm 协作基础设施
+   - `src/utils/forkedAgent.ts` — Fork 代理上下文
+   - `src/tasks/` — 任务管理系统
+3. 理解四条生成路径和上下文传递机制
+
+---
+
+## 📝 核心概念速查
+
+| 概念 | 说明 |
+|------|------|
+| **Agent Tool** | 主入口工具，接受 prompt + subagent_type 生成子代理 |
+| **Subagent** | 独立执行任务的子代理，有自己的工具池和权限 |
+| **Fork Agent** | 继承父代理完整上下文的分叉代理，共享 prompt cache |
+| **Teammate** | Agent Teams 中的协作成员，通过邮箱通信 |
+| **Worktree** | Git worktree 隔离模式，独立文件环境 |
+| **LocalAgentTask** | 本地代理任务状态，追踪 running/completed/failed |
+| **DreamTask** | 自动记忆整合任务，定期后台运行 |
+| **CacheSafeParams** | 缓存安全参数，确保 API 请求前缀字节级一致 |
+| **TeamFile** | 团队配置文件，存储成员列表和权限 |
+| **Mailbox** | 基于文件的消息队列，支持队友间异步通信 |
+
+---
+
+## 🔗 相关资源
+
+- [Claude Code Haha 主页](/)
+- [记忆系统文档](/memory/01-usage-guide)
+- [Agent Tool 源码](https://github.com/NanmiCoder/cc-haha/tree/main/src/tools/AgentTool/)
+- [Swarm 基础设施](https://github.com/NanmiCoder/cc-haha/tree/main/src/utils/swarm/)
+- [任务管理系统](https://github.com/NanmiCoder/cc-haha/tree/main/src/tasks/)
+- [GitHub Issues](https://github.com/NanmiCoder/cc-haha/issues)