docs: 文档优化完成

docs/introduction/architecture-overview.mdx

@@ -1,7 +1,7 @@
 ---
 title: "架构全景 - Claude Code 五层架构详解"
-description: "从交互层到基础设施层，详解 Claude Code 的五层架构设计。涵盖 React/Ink UI、QueryEngine 编排、Agentic Loop 核心循环、Tool 系统和 API 层。"
-keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop", "系统设计"]
+description: "从交互层到基础设施层，详解 Claude Code 的五层架构设计。基于 src/main.tsx、src/QueryEngine.ts、src/query.ts、src/tools.ts、src/services/api/claude.ts 的源码级数据流分析。"
+keywords: ["Claude Code 架构", "五层架构", "QueryEngine", "Agentic Loop", "数据流"]
 ---
 
 {/* 本章目标：一张图讲清楚整体架构，为后续章节建立坐标系 */}
@@ -14,53 +14,99 @@ Claude Code 从上到下分为五个层次，每一层职责清晰、边界分
   <img src="/docs/images/architecture-layers.png" alt="Claude Code 五层架构图" />
 </Frame>
 
-| 层次 | 职责 | 关键词 |
-|------|------|--------|
-| **交互层** | 终端 UI、用户输入、消息展示 | React/Ink、REPL |
-| **编排层** | 管理多轮对话、会话生命周期、成本追踪 | QueryEngine、会话持久化 |
-| **核心循环层** | 单轮对话：发请求 → 拿响应 → 执行工具 → 再发请求 | Agentic Loop |
-| **工具层** | AI 的"双手"——读写文件、执行命令、搜索代码 | Tool System、MCP |
-| **通信层** | 与 Claude API 的流式通信、多云 Provider 适配 | Streaming、Bedrock/Vertex |
+| 层次 | 职责 | 入口源码 | 关键词 |
+|------|------|---------|--------|
+| **交互层** | 终端 UI、用户输入、消息展示 | `src/screens/REPL.tsx` | React/Ink、PromptInput |
+| **编排层** | 多轮对话、会话持久化、成本追踪 | `src/QueryEngine.ts` | QueryEngine、transcript |
+| **核心循环层** | 单轮：发请求 → 拿响应 → 执行工具 → 循环 | `src/query.ts` | Agentic Loop、State |
+| **工具层** | AI 的"双手"——读写文件、执行命令 | `src/tools.ts` → `src/Tool.ts` | Tool 接口、MCP |
+| **通信层** | 与 Claude API 的流式通信 | `src/services/api/claude.ts` | Streaming、Provider |
 
-## 一条主数据流
+## 一条主数据流的源码追踪
 
 <Frame caption="核心数据流">
   <img src="/docs/images/data-flow.png" alt="Claude Code 核心数据流" />
 </Frame>
 
-整个系统的运转可以浓缩为一条核心数据流：
+整个系统的运转可以浓缩为一条核心数据流，以下是每一步对应的源码路径：
 
-<Steps>
-  <Step title="用户输入">
-    用户在终端键入自然语言需求
-  </Step>
-  <Step title="上下文组装">
-    系统自动拼接项目信息、git 状态、配置文件、记忆，形成完整的 System Prompt
-  </Step>
-  <Step title="API 调用">
-    将 System Prompt + 对话历史发送给 Claude API，流式接收响应
-  </Step>
-  <Step title="工具调用循环">
-    若 AI 返回工具调用请求 → 权限检查 → 执行工具 → 结果回传 → AI 继续思考 → 循环
-  </Step>
-  <Step title="任务完成">
-    AI 不再调用工具，输出最终回答，等待用户下一条输入
-  </Step>
-</Steps>
+### 1. 用户输入 → REPL
+
+`src/screens/REPL.tsx` 是基于 React/Ink 的终端 UI 组件。用户输入经 `processUserInput()`（`src/utils/processUserInput/processUserInput.ts`）处理，支持斜杠命令、文件附件、图片等。
+
+### 2. QueryEngine 编排
+
+`src/QueryEngine.ts` 是 REPL 与 `query()` 之间的中间层，管理：
+- **会话状态**：消息数组、工具权限上下文（`ToolPermissionContext`）、文件历史快照
+- **成本追踪**：`accumulateUsage()` / `getTotalCost()` 累计 token 用量
+- **Transcript 持久化**：`recordTranscript()` 将对话序列化到磁盘，支持 `--resume`
+- **文件历史**：`fileHistoryMakeSnapshot()` 在修改前创建快照，支持 undo
+
+关键方法：`queryEngine.query()` 构造 `QueryParams`，调用 `query()` 异步生成器。
+
+### 3. Agentic Loop（`src/query.ts`）
+
+`query()` 是一个 `AsyncGenerator`，`while(true)` 循环的每次迭代包含：
+
+```
+① 上下文预处理管道：
+   applyToolResultBudget → snipCompact → microcompact → contextCollapse → autocompact
+
+② 流式 API 调用：
+   deps.callModel() → AsyncGenerator<StreamEvent | Message>
+   收集 assistantMessages[]、toolUseBlocks[]
+
+③ 工具执行：
+   StreamingToolExecutor（并行） 或 runTools（串行）
+   → toolResults[]
+
+④ 终止/继续判定：
+   needsFollowUp ? continue : return { reason }
+```
+
+完整的状态机通过 `State` 类型（`src/query.ts:204`）在迭代间传递，包含 10 个字段（messages、autoCompactTracking、maxOutputTokensRecoveryCount 等）。
+
+### 4. 工具层（`src/tools.ts` → `src/Tool.ts`）
+
+`getAllBaseTools()`（`src/tools.ts:191`）组装 50+ 工具列表，经过 `filterToolsByDenyRules()` 权限过滤后传给 API。
+
+每个工具实现 `Tool<Input, Output, Progress>` 接口（`src/Tool.ts:362`），核心方法链：
+```
+validateInput() → canUseTool()（UI 层）→ checkPermissions() → call() → ToolResult
+```
+
+### 5. 通信层（`src/services/api/claude.ts`）
+
+API 客户端支持 4 种 Provider：
+- **Anthropic Direct**：默认
+- **AWS Bedrock**：`ANTHROPIC_BEDROCK_BASE_URL`
+- **Google Vertex**：`ANTHROPIC_VERTEX_PROJECT_ID`
+- **Azure**：通过自定义 base URL
+
+`deps.callModel()` 发起流式请求，返回 `BetaRawMessageStreamEvent` 事件流。支持 Prompt Cache（`cache_control`）、thinking blocks、multi-turn tool use。
 
 ## 四个核心设计原则
 
 <AccordionGroup>
   <Accordion title="流式优先 (Streaming-first)">
-    所有 API 通信都是流式的——用户看到 AI "逐字打出"回答，而不是等待完整响应。工具执行结果也实时反馈。这不仅提升体验，更是处理长时间任务的工程必需。
+    所有 API 通信都是流式的——`deps.callModel()` 返回 AsyncGenerator，用户看到 AI "逐字打出"回答。StreamingToolExecutor 在流式过程中就开始并行执行工具，不等流结束。模型降级（Fallback）时，已收集的 assistantMessages 被标记为 tombstone 并清空，重试整个流式请求。
   </Accordion>
   <Accordion title="工具即能力 (Tool as Capability)">
-    AI 的每一项"动手能力"都被抽象为一个 Tool。想让 AI 能做新事情？注册一个新 Tool 就好。统一的接口让能力可插拔、可组合。
+    每个工具是 `Tool<Input, Output, Progress>` 结构化类型，通过 `buildTool()` 工厂创建。`getTools()` 在每次 API 调用时组装（非全局缓存），因为 `isEnabled()` 可能随运行时状态变化。MCP 工具通过 `mcpInfo` 字段标记来源，支持 server 级别的 blanket deny。
   </Accordion>
   <Accordion title="权限即边界 (Permission as Boundary)">
-    AI 能操作真实环境是强大的，也是危险的。每个工具调用都经过权限系统的裁决——该放行的自动放行，该拦截的坚决拦截。
+    每次工具调用经过 `validateInput() → checkPermissions()` 双重检查。权限规则从 5 个来源汇聚（session → project → user → managed → default），支持工具名、命令模式、路径前缀等匹配方式。Plan Mode 通过 `prepareContextForPlanMode()` 切换为只读模式，退出时自动恢复。
   </Accordion>
   <Accordion title="上下文即记忆 (Context as Memory)">
-    AI 没有真正的记忆，但通过精心的 System Prompt 组装、对话压缩、持久化记忆文件，系统营造出"AI 理解你的项目"的效果。这是上下文工程的核心。
+    System Prompt 由 `fetchSystemPromptParts()` 动态组装，包含 CLAUDE.md、git 状态、日期、MCP 服务器列表。Auto-compact 在每轮迭代前评估 token 阈值，超出时触发压缩。压缩后的摘要通过 `buildPostCompactMessages()` 替换原始消息，`taskBudgetRemaining` 跨压缩边界累计。
   </Accordion>
 </AccordionGroup>
+
+## 入口与引导
+
+| 入口 | 文件 | 说明 |
+|------|------|------|
+| CLI 启动 | `src/entrypoints/cli.tsx` | 注入 `feature()` polyfill（始终返回 false）、MACRO 全局变量 |
+| 命令定义 | `src/main.tsx` | Commander.js 解析参数，初始化 auth/analytics/policy |
+| 一次性初始化 | `src/entrypoints/init.ts` | 遥测配置、信任对话框 |
+| 管道模式 | `src/main.tsx` `-p` flag | `echo "say hello" \| bun run dev -p` |