docs: add Chinese translation of full architecture analysis (DOCUMENTATION.zh-CN.md)

DOCUMENTATION.md

@@ -1,3 +1,5 @@
+**[English](DOCUMENTATION.md)** | **[中文](DOCUMENTATION.zh-CN.md)**
+
 # Claude Code — Source Code Documentation & Analysis
 
 > **Claude Code** is Anthropic's official CLI for Claude. This document provides a comprehensive reverse-engineering analysis of its source code architecture, modules, and internal design patterns.

DOCUMENTATION.zh-CN.md

@@ -0,0 +1,801 @@
+**[English](DOCUMENTATION.md)** | **[中文](DOCUMENTATION.zh-CN.md)**
+
+# Claude Code — 源码文档与架构分析
+
+> **Claude Code** 是 Anthropic 官方的 Claude CLI 工具。本文档提供了对其源码架构、模块和内部设计模式的全面逆向工程分析。
+
+---
+
+## 如何阅读本文档
+
+本文档是对 Claude Code 源码树进行深度分析的成果。它面向希望了解 Claude Code 底层工作原理的**开发者和工程师**——包括其架构、模块边界、数据流和设计决策。
+
+**结构：** 文档采用自顶向下的组织方式，从项目概览和技术栈开始，然后深入到各个主要子系统（工具、命令、状态、服务、UI）。每个章节都是独立的；你可以通过目录跳转到任意章节。
+
+**受众：** 熟悉 TypeScript、React 和 CLI 工具的中高级开发者。有 AI/LLM 工具开发经验会有帮助，但不是必需的。
+
+**范围：** 本文档涵盖源码树结构、模块清单和架构模式。不深入涉及运行时行为，也不包含性能基准测试或安全审计。
+
+---
+
+## 目录
+
+1. [项目概览](#1-项目概览)
+2. [技术栈](#2-技术栈)
+3. [目录结构](#3-目录结构)
+4. [入口点](#4-入口点)
+5. [核心架构](#5-核心架构)
+6. [工具系统](#6-工具系统)
+7. [命令系统](#7-命令系统)
+8. [状态管理](#8-状态管理)
+9. [任务系统](#9-任务系统)
+10. [服务与集成](#10-服务与集成)
+11. [UI 层](#11-ui-层)
+12. [工具函数](#12-工具函数)
+13. [特殊模式](#13-特殊模式)
+14. [插件与技能](#14-插件与技能)
+15. [钩子与可扩展性](#15-钩子与可扩展性)
+16. [文件统计](#16-文件统计)
+17. [架构模式](#17-架构模式)
+
+---
+
+## 1. 项目概览
+
+Claude Code 是一个功能丰富的交互式终端应用，允许直接在命令行中进行 AI 辅助软件工程。它提供：
+
+- **交互式 REPL**，用于与 Claude 进行代码相关的对话
+- **40+ 工具**，用于文件操作、Shell 执行、网络搜索等
+- **100+ 斜杠命令**，用于提交、审查、调试等工作流
+- **Agent/任务系统**，用于通过子 Agent 并行处理复杂工作
+- **计划模式**，用于在编码前设计实现策略
+- **MCP（Model Context Protocol）** 集成，提供可扩展的服务端工具
+- **插件与技能系统**，用于用户自定义扩展
+- **语音模式**、**桌面/移动端桥接**和**远程会话**
+
+---
+
+## 2. 技术栈
+
+| 层级           | 技术                                                         |
+|----------------|--------------------------------------------------------------|
+| 语言           | TypeScript (`.ts` / `.tsx`)                                  |
+| 运行时         | Bun（打包工具，通过 `bun:bundle` 实现特性标志）                |
+| UI 框架        | React + [Ink](https://github.com/vadimdemedes/ink)（终端 React 渲染器）|
+| API 客户端     | `@anthropic-ai/sdk`（Anthropic SDK）                          |
+| MCP            | `@modelcontextprotocol/sdk`                                  |
+| CLI 框架       | `@commander-js/extra-typings`                                |
+| 数据验证       | Zod v4                                                       |
+| 样式           | Chalk（终端颜色）                                             |
+| 状态管理       | Zustand 风格 Store + React Context                           |
+
+---
+
+## 3. 目录结构
+
+```text
+claude-code-analysis/
+└── src/                          # 所有源码（单一顶级目录）
+    ├── main.tsx                  # 主引导与初始化
+    ├── QueryEngine.ts            # 对话循环编排器
+    ├── Tool.ts                   # 工具类型定义与接口
+    ├── Task.ts                   # 任务类型定义与生命周期
+    ├── commands.ts               # 命令注册表
+    ├── tools.ts                  # 工具注册表与工厂
+    ├── context.ts                # 系统/用户上下文构建器
+    ├── query.ts                  # 查询上下文准备
+    ├── setup.ts                  # 启动阶段编排
+    ├── history.ts                # 聊天会话历史
+    ├── cost-tracker.ts           # Token 用量与定价
+    ├── ink.ts                    # Ink 渲染封装
+    ├── replLauncher.tsx          # REPL React 组件启动器
+    ├── tasks.ts                  # 任务执行管理器
+    │
+    ├── commands/                 # 101 个命令模块（斜杠命令）
+    ├── tools/                    # 41 个工具实现
+    ├── services/                 # 核心服务（API、MCP、分析等）
+    ├── components/               # React/Ink UI 组件（130+ 文件）
+    ├── utils/                    # 工具函数（300+ 文件）
+    ├── state/                    # 应用状态管理
+    ├── types/                    # TypeScript 类型定义
+    ├── hooks/                    # React Hooks
+    ├── schemas/                  # Zod 验证模式
+    ├── tasks/                    # 任务类型实现
+    ├── entrypoints/              # 入口点定义（CLI、SDK、MCP）
+    ├── bootstrap/                # 应用启动与全局状态
+    ├── screens/                  # 全屏 UI 布局
+    ├── plugins/                  # 插件系统（内置插件）
+    ├── skills/                   # 自定义技能系统（内置技能）
+    ├── memdir/                   # 内存目录自动发现
+    ├── constants/                # 应用常量
+    ├── migrations/               # 数据/模式迁移
+    ├── ink/                      # Ink 终端自定义
+    ├── keybindings/              # 键盘绑定系统
+    ├── context/                  # React Context（信箱、通知）
+    ├── query/                    # 查询处理模块
+    ├── outputStyles/             # 输出格式化样式
+    ├── vim/                      # Vim 模式集成
+    ├── voice/                    # 语音输入/输出
+    ├── native-ts/                # 原生 TypeScript 绑定
+    ├── assistant/                # Kairos（助手）模式
+    ├── bridge/                   # Bridge 模式（常驻远程连接）
+    ├── buddy/                    # Buddy/队友系统
+    ├── coordinator/              # 多 Agent 协调
+    ├── remote/                   # 远程会话处理
+    ├── server/                   # 服务器实现
+    ├── cli/                      # CLI 参数解析
+    └── upstreamproxy/            # 上游代理设置
+```
+
+---
+
+## 4. 入口点
+
+### 主入口：`src/main.tsx`
+
+主引导文件（约 1,400 行）。执行以下操作：
+
+1. 通过 `startupProfiler.ts` 进行**启动性能分析**
+2. **MDM（移动设备管理）** 原始数据预读取
+3. **钥匙串预取**（macOS OAuth + API 密钥并行读取）
+4. 通过 Bun 的 `feature()` 进行**特性标志初始化**，实现死代码消除
+5. 通过 Commander.js 进行 **CLI 参数解析**
+6. **身份认证**（API 密钥、OAuth、AWS Bedrock、GCP Vertex、Azure）
+7. **GrowthBook** 初始化（A/B 测试与特性标志）
+8. **策略限制**和**远程托管设置**加载
+9. **工具、命令、技能和 MCP 服务器**注册
+10. 通过 `replLauncher.tsx` **启动 REPL**
+
+### 其他入口点（`src/entrypoints/`）
+
+| 文件                | 用途                                         |
+|---------------------|----------------------------------------------|
+| `cli.tsx`           | CLI 入口点，带 React/Ink UI 渲染             |
+| `init.ts`           | 引导初始化、版本检查                         |
+| `mcp.ts`            | Model Context Protocol 集成                  |
+| `agentSdkTypes.ts`  | Agent SDK 的类型定义                         |
+| `sandboxTypes.ts`   | 沙箱执行环境类型                             |
+| `sdk/`              | SDK 相关实现                                 |
+
+### 启动阶段：`src/setup.ts`
+
+负责编排：
+- Node.js 版本验证
+- 工作树初始化
+- 会话与权限模式设置
+- Git 根目录检测
+- UDS 消息服务器启动
+
+---
+
+## 5. 核心架构
+
+### 5.1 查询引擎（`src/QueryEngine.ts`）
+
+应用的核心（约 46KB）。管理用户与 Claude 之间的对话循环：
+
+- **消息管理** — 维护包含用户、助手、系统和工具消息的对话历史
+- **流式传输** — 实时 Token 流式传输与工具调用执行
+- **自动压缩** — 当接近上下文窗口限制时自动压缩上下文
+- **提示词缓存** — 通过缓存感知策略优化重复上下文
+- **重试逻辑** — 处理 API 错误、速率限制和过载，支持退避策略
+- **用量追踪** — 统计 Token 数量（输入/输出/缓存读取/缓存写入）和成本
+- **工具编排** — 分发工具调用、收集结果、管理权限
+
+### 5.2 上下文构建器（`src/context.ts`、`src/query.ts`）
+
+准备系统提示词和用户上下文：
+
+- 发现并合并 `CLAUDE.md` 文件（项目级、用户级、全局级）
+- 构建系统上下文（操作系统、Shell、平台、Git 状态）
+- 集成用户上下文（权限、工作目录）
+- 跨查询缓存上下文以提升性能
+
+### 5.3 成本追踪（`src/cost-tracker.ts`）
+
+追踪每次会话的成本：
+- 按模型统计 Token 数量（输入、输出、缓存读取/写入）
+- 通过定价表计算美元成本
+- 会话持续时间追踪
+- 网络搜索请求计数
+- 文件变更指标
+
+---
+
+## 6. 工具系统
+
+### 架构（`src/Tool.ts`、`src/tools.ts`）
+
+每个工具都是一个自包含的模块，包含：
+- **JSON Schema** 输入验证
+- **权限模型**（询问/允许/拒绝模式）
+- **进度追踪**类型
+- **错误处理**和用户提示
+
+### 完整工具清单（41 个工具）
+
+#### 文件操作
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `FileReadTool`    | 读取文件内容，支持行范围                    |
+| `FileWriteTool`   | 创建或覆盖文件                             |
+| `FileEditTool`    | 精确字符串替换编辑                         |
+| `GlobTool`        | 基于模式的文件匹配                         |
+| `GrepTool`        | 基于正则的内容搜索（基于 ripgrep）          |
+
+#### 代码执行
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `BashTool`        | 执行 Shell 命令，支持超时                   |
+| `PowerShellTool`  | 执行 PowerShell 命令（Windows）             |
+| `REPLTool`        | 执行 Python 代码（仅内部使用）              |
+| `NotebookEditTool`| Jupyter Notebook 单元格操作                |
+
+#### 网络与搜索
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `WebFetchTool`    | 获取并解析网页内容                         |
+| `WebSearchTool`   | 互联网搜索                                 |
+| `ToolSearchTool`  | 搜索可用的延迟加载工具                     |
+
+#### Agent 与任务管理
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `AgentTool`       | 生成子 Agent 进行并行工作                   |
+| `TaskCreateTool`  | 创建新的后台任务                           |
+| `TaskGetTool`     | 获取任务状态和结果                         |
+| `TaskUpdateTool`  | 更新任务状态或描述                         |
+| `TaskListTool`    | 列出所有任务及其状态                       |
+| `TaskStopTool`    | 终止正在运行的任务                         |
+| `TaskOutputTool`  | 流式读取任务输出                           |
+| `SendMessageTool` | 向运行中的 Agent 发送消息                   |
+
+#### 计划与工作流
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `EnterPlanModeTool` | 进入只读计划模式                         |
+| `ExitPlanModeTool`  | 退出计划模式并获得批准                   |
+| `EnterWorktreeTool` | 创建隔离的 Git 工作树                    |
+| `ExitWorktreeTool`  | 从工作树返回并携带变更                   |
+
+#### MCP（Model Context Protocol）
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `MCPTool`         | 调用 MCP 服务器上的工具                     |
+| `McpAuthTool`     | MCP 服务器认证                             |
+| `ListMcpResourcesTool` | 列出 MCP 服务器资源                  |
+| `ReadMcpResourceTool`  | 读取特定 MCP 资源                     |
+
+#### 配置与系统
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `ConfigTool`      | 读取/修改设置                              |
+| `SkillTool`       | 执行用户自定义技能                         |
+| `AskUserQuestionTool` | 提示用户输入/确认                      |
+| `BriefTool`       | 生成会话摘要                               |
+| `TodoWriteTool`   | 管理待办事项列表                           |
+| `SleepTool`       | 暂停执行指定时长                           |
+
+#### 团队与远程
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `TeamCreateTool`  | 创建 Agent 团队                             |
+| `TeamDeleteTool`  | 删除 Agent 团队                             |
+| `RemoteTriggerTool` | 触发远程任务执行                         |
+| `ScheduleCronTool`  | 调度定时任务                             |
+| `LSPTool`         | Language Server Protocol 集成              |
+
+#### 内部工具
+| 工具              | 用途                                       |
+|-------------------|--------------------------------------------|
+| `SyntheticOutputTool` | 用于结构化响应的合成输出               |
+
+---
+
+## 7. 命令系统
+
+### 注册表（`src/commands.ts`）
+
+命令是 `src/commands/` 下的模块化目录，每个目录包含一个 `index.ts`（或类似文件），导出一个 `Command` 定义，包含名称、描述、处理函数和可选的别名。
+
+### 完整命令清单（101 个模块）
+
+#### Git 与版本控制
+`commit`、`commit-push-pr`、`diff`、`branch`、`review`、`autofix-pr`、`pr_comments`、`teleport`、`rewind`、`tag`
+
+#### 会话与历史
+`session`、`resume`、`clear`、`compact`、`export`、`share`、`summary`、`context`
+
+#### 配置与设置
+`config`、`permissions`、`privacy-settings`、`theme`、`color`、`keybindings`、`vim`、`output-style`、`statusline`、`env`
+
+#### Agent 与任务管理
+`agents`、`tasks`、`brief`
+
+#### 文件与代码操作
+`files`、`add-dir`、`diff`、`debug-tool-call`、`copy`
+
+#### 开发与调试
+`doctor`、`heapdump`、`perf-issue`、`stats`、`bughunter`、`ctx_viz`、`ant-trace`
+
+#### 身份认证
+`login`、`logout`、`oauth-refresh`
+
+#### 扩展与插件
+`mcp`、`plugin`、`reload-plugins`、`skills`
+
+#### 工作区
+`plan`、`sandbox-toggle`、`init`
+
+#### 信息与帮助
+`help`、`version`、`cost`、`usage`、`extra-usage`、`release-notes`、`status`、`insights`
+
+#### 平台集成
+`desktop`、`mobile`、`chrome`、`ide`、`install`、`install-github-app`、`install-slack-app`
+
+#### 记忆与知识
+`memory`、`good-claude`
+
+#### 模型与性能
+`model`、`effort`、`fast`、`thinkback`、`thinkback-play`、`advisor`
+
+#### 特殊操作
+`bridge`、`voice`、`remote-setup`、`remote-env`、`stickers`、`feedback`、`onboarding`、`passes`、`ultraplan`、`rename`、`exit`
+
+---
+
+## 8. 状态管理
+
+### Store 架构（`src/state/`）
+
+| 文件              | 用途                                           |
+|-------------------|------------------------------------------------|
+| `AppState.tsx`    | React Context 提供者，带 `useAppState(selector)` Hook |
+| `AppStateStore.ts`| 中心状态结构定义                               |
+| `store.ts`        | Zustand 风格 Store 实现                        |
+
+### 关键状态字段
+
+```typescript
+{
+  settings: UserSettings           // 来自 settings.json 的用户配置
+  mainLoopModel: string            // 当前活跃的 Claude 模型
+  messages: Message[]              // 对话历史
+  tasks: TaskState[]               // 运行中/已完成的任务
+  toolPermissionContext: {         // 每个工具的权限规则
+    rules: PermissionRule[]
+    bypassMode: 'auto' | 'block' | 'ask'
+    denialTracking: DenialTrackingState
+  }
+  kairosEnabled: boolean           // 助手模式标志
+  remoteConnectionStatus: Status   // 远程会话连接状态
+  replBridgeEnabled: boolean       // 常驻桥接（CCR）状态
+  speculationState: Cache          // 内联推测缓存/预览
+}
+```
+
+---
+
+## 9. 任务系统
+
+### 任务类型（`src/Task.ts`）
+
+| 类型                  | 描述                                            |
+|-----------------------|-------------------------------------------------|
+| `local_bash`          | 本地 Shell 命令执行                              |
+| `local_agent`         | 本地子 Agent（通过 AgentTool 生成）               |
+| `remote_agent`        | 远程 Agent 执行                                  |
+| `in_process_teammate` | 进程内队友（共享内存空间）                       |
+| `local_workflow`      | 本地多步骤工作流                                 |
+| `monitor_mcp`         | MCP 服务器监控任务                               |
+| `dream`               | 自动梦境后台任务                                 |
+
+### 任务生命周期
+
+```text
+pending -> running -> completed
+                   -> failed
+                   -> killed
+```
+
+### 任务状态结构
+
+```typescript
+{
+  id: string           // 带类型前缀的唯一 ID（例如 "b-xxx" 表示 bash）
+  type: TaskType
+  status: TaskStatus
+  description: string
+  startTime: number
+  endTime?: number
+  outputFile: string   // 磁盘持久化输出
+  outputOffset: number // 当前读取位置
+  notified: boolean    // 是否已报告完成
+}
+```
+
+---
+
+## 10. 服务与集成
+
+### 10.1 API 客户端（`src/services/api/`）
+
+| 文件                        | 用途                                         |
+|-----------------------------|----------------------------------------------|
+| `client.ts`                 | Anthropic SDK 客户端，支持多提供商             |
+| `claude.ts`                 | 消息流式传输与工具调用处理                    |
+| `bootstrap.ts`              | 启动时获取引导数据                           |
+| `usage.ts`                  | Token 用量记录                               |
+| `errors.ts` / `errorUtils.ts` | 错误分类与处理                            |
+| `logging.ts`                | API 请求/响应日志                            |
+| `withRetry.ts`              | 指数退避重试逻辑                             |
+| `filesApi.ts`               | 文件上传/下载                                |
+| `sessionIngress.ts`         | 远程会话桥接                                 |
+| `grove.ts`                  | Grove 集成                                   |
+| `referral.ts`               | 推荐/通行证系统                              |
+
+**支持的提供商：**
+- Anthropic 直连 API
+- AWS Bedrock
+- Google Cloud Vertex AI
+- Azure Foundry
+
+### 10.2 MCP 集成（`src/services/mcp/`）
+
+| 文件                    | 用途                                           |
+|-------------------------|------------------------------------------------|
+| `client.ts`             | MCP 客户端实现                                 |
+| `types.ts`              | 服务器定义与连接类型                           |
+| `config.ts`             | 配置加载与验证                                 |
+| `auth.ts`               | MCP 服务器的 OAuth/认证                        |
+| `officialRegistry.ts`   | 官方 MCP 服务器注册表                          |
+| `InProcessTransport.ts` | 进程内 MCP 传输                                |
+| `normalization.ts`      | URL/配置规范化                                 |
+| `elicitationHandler.ts` | 通过 MCP 提示用户                              |
+
+### 10.3 分析与遥测（`src/services/analytics/`）
+
+| 文件                        | 用途                                       |
+|-----------------------------|--------------------------------------------|
+| `index.ts`                  | 事件日志 API                               |
+| `growthbook.ts`             | 特性标志与 A/B 测试                        |
+| `sink.ts`                   | 分析接收器配置                             |
+| `datadog.ts`                | Datadog 集成                               |
+| `firstPartyEventLogger.ts`  | 第一方分析                                 |
+| `metadata.ts`               | 事件元数据增强                             |
+
+### 10.4 上下文压缩（`src/services/compact/`）
+
+| 文件                       | 用途                                        |
+|----------------------------|---------------------------------------------|
+| `compact.ts`               | 完整上下文窗口压缩                         |
+| `autoCompact.ts`           | 自动压缩触发器                             |
+| `microCompact.ts`          | 选择性消息修剪                             |
+| `compactWarning.ts`        | 压缩用户警告                               |
+| `sessionMemoryCompact.ts`  | 跨压缩的记忆持久化                         |
+
+### 10.5 其他服务
+
+| 目录/文件                     | 用途                                      |
+|-------------------------------|-------------------------------------------|
+| `SessionMemory/`              | 会话记忆持久化与转录                      |
+| `MagicDocs/`                  | 智能文档生成                              |
+| `AgentSummary/`               | Agent 执行摘要                            |
+| `PromptSuggestion/`           | 建议的后续提示词                          |
+| `extractMemories/`            | 从对话中提取学习内容                      |
+| `plugins/`                    | 插件生命周期管理                          |
+| `oauth/`                      | OAuth 客户端流程                          |
+| `lsp/`                        | Language Server Protocol 客户端           |
+| `remoteManagedSettings/`      | 远程配置同步                              |
+| `settingsSync/`               | 设置同步                                  |
+| `teamMemorySync/`             | 团队记忆同步                              |
+| `policyLimits/`               | 速率限制与配额                            |
+| `autoDream/`                  | 自动梦境后台功能                          |
+| `tips/`                       | 上下文提示系统                            |
+| `toolUseSummary/`             | 工具使用分析                              |
+| `voice.ts` / `voiceStreamSTT.ts` | 语音输入处理                          |
+
+---
+
+## 11. UI 层
+
+### 框架
+
+UI 使用 **React** 构建，通过 **Ink** 渲染到终端。组件使用标准 React 模式（Hooks、Context、Props），但渲染为终端 ANSI 输出而非 DOM。
+
+### 核心应用组件
+
+| 组件               | 文件                          | 用途                          |
+|--------------------|-------------------------------|-------------------------------|
+| `App`              | `components/App.tsx`          | 根应用组件                    |
+| `REPL`             | `screens/REPL.tsx`            | 主 REPL 界面                  |
+| `Messages`         | `components/Messages.tsx`     | 对话消息列表                  |
+| `PromptInput`      | `components/PromptInput/`     | 带自动补全的用户输入          |
+| `StatusLine`       | `components/StatusLine.tsx`   | 底部状态栏                    |
+
+### 组件分类
+
+#### 消息展示
+`Message.tsx`、`MessageRow.tsx`、`MessageResponse.tsx`、`MessageModel.tsx`、`MessageTimestamp.tsx`、`MessageSelector.tsx`、`messages/`（专用消息类型子目录）
+
+#### 对话框与模态组件
+`TrustDialog/`、`AutoModeOptInDialog.tsx`、`BypassPermissionsModeDialog.tsx`、`CostThresholdDialog.tsx`、`BridgeDialog.tsx`、`ExportDialog.tsx`、`InvalidConfigDialog.tsx`、`InvalidSettingsDialog.tsx`、`ManagedSettingsSecurityDialog/`、`IdeAutoConnectDialog.tsx`、`IdleReturnDialog.tsx`、`WorktreeExitDialog.tsx`、`RemoteEnvironmentDialog.tsx`
+
+#### 代码展示
+`HighlightedCode/`、`StructuredDiff/`、`FileEditToolDiff.tsx`
+
+#### 设置与配置
+`Settings/`、`ThemePicker.tsx`、`OutputStylePicker.tsx`、`ModelPicker.tsx`、`LanguagePicker.tsx`
+
+#### 任务与 Agent UI
+`tasks/`、`teams/`、`agents/`、`CoordinatorAgentStatus.tsx`、`TaskListV2.tsx`、`TeammateViewHeader.tsx`
+
+#### 导航与搜索
+`GlobalSearchDialog.tsx`、`HistorySearchDialog.tsx`、`QuickOpenDialog.tsx`、`SearchBox.tsx`
+
+#### 设计系统
+`design-system/`、`Spinner/`、`CustomSelect/`、`LogoV2/`、`HelpV2/`
+
+#### 权限
+`permissions/`（基于角色的访问对话框和提示）
+
+---
+
+## 12. 工具函数
+
+`src/utils/` 目录包含 **300+ 文件**，提供底层功能。主要分类：
+
+### Git 与版本控制
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `git.ts`        | Git 命令封装                                   |
+| `git/`          | 扩展 Git 工具                                  |
+| `gitDiff.ts`    | Diff 生成与解析                                |
+| `gitSettings.ts`| Git 指令开关                                   |
+| `github/`       | GitHub API 辅助工具                            |
+| `worktree.ts`   | Git 工作树自动化                               |
+
+### Shell 与进程
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `Shell.ts`      | Shell 执行封装                                 |
+| `shell/`        | Shell 配置与辅助工具                           |
+| `bash/`         | Bash 专用工具                                  |
+| `powershell/`   | PowerShell 工具                                |
+| `execFileNoThrow.ts` | 安全进程启动                              |
+| `process.ts`    | 进程管理                                       |
+
+### 认证与安全
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `auth.ts`       | API 密钥、OAuth、AWS/GCP 凭证管理              |
+| `secureStorage/`| 钥匙串集成（macOS）                            |
+| `permissions/`  | 权限规则、文件系统沙箱                         |
+| `crypto.ts`     | 加密工具                                       |
+| `sandbox/`      | 沙箱环境                                       |
+
+### 配置
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `config.ts`     | `.claude/config.json` 管理                     |
+| `settings/`     | `settings.json` 验证与应用                     |
+| `env.ts`        | 静态环境变量                                   |
+| `envDynamic.ts` | 动态环境检测                                   |
+| `envUtils.ts`   | 环境变量解析                                   |
+| `managedEnv.ts` | 托管环境配置                                   |
+
+### 文件系统
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `claudemd.ts`   | CLAUDE.md 自动发现与解析                       |
+| `fileStateCache.ts` | 文件变更追踪                               |
+| `fileHistory.ts`| 文件快照（用于撤销）                           |
+| `filePersistence/` | 持久化文件存储                              |
+| `glob.ts`       | Glob 模式匹配                                  |
+| `ripgrep.ts`    | Ripgrep 集成                                   |
+
+### AI 与模型
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `model/`        | 模型选择与上下文窗口管理                       |
+| `modelCost.ts`  | Token 定价表                                   |
+| `thinking.ts`   | 扩展思考模式配置                               |
+| `effort.ts`     | 任务工作量级别管理                             |
+| `fastMode.ts`   | 速度优化模式                                   |
+| `advisor.ts`    | AI 顾问集成                                    |
+| `tokens.ts`     | Token 计数与估算                               |
+
+### Agent 与集群
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `swarm/`        | 多 Agent 集群协调                              |
+| `teammate.ts`   | 队友/Agent 模式工具                            |
+| `forkedAgent.ts`| 分叉 Agent 进程管理                            |
+| `agentContext.ts`| Agent 执行上下文                               |
+
+### 性能与诊断
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `startupProfiler.ts` | 启动性能监控                              |
+| `headlessProfiler.ts`| 运行时性能分析                             |
+| `fpsTracker.ts` | 帧率指标                                       |
+| `diagLogs.ts`   | 诊断日志（无 PII）                             |
+| `debug.ts`      | 调试工具                                       |
+
+### UI 辅助工具
+| 文件/目录        | 用途                                           |
+|-----------------|------------------------------------------------|
+| `theme.ts`      | 主题管理                                       |
+| `renderOptions.ts` | Ink 渲染配置                                |
+| `format.ts`     | 数字/时长格式化                                |
+| `markdown.ts`   | Markdown 处理                                  |
+| `cliHighlight.ts` | CLI 语法高亮                                 |
+
+---
+
+## 13. 特殊模式
+
+### 13.1 Bridge 模式（`src/bridge/`）
+通过基于 WebSocket 的会话入口与 Claude.ai 保持常驻连接。支持持久化后台会话和远程访问。
+
+### 13.2 Kairos / 助手模式（`src/assistant/`）
+企业助手功能：
+- 后台任务处理
+- 推送通知
+- GitHub Webhook 订阅
+- 远程任务监控
+- 通过 `KAIROS` 标志进行功能门控
+
+### 13.3 协调器模式（`src/coordinator/`）
+多 Agent 编排：
+- 任务面板管理
+- Agent 交互协调
+- 通过 `COORDINATOR_MODE` 标志进行功能门控
+
+### 13.4 语音模式（`src/voice/`）
+语音输入/输出支持：
+- 语音转文字（STT）集成
+- 文字转语音
+- 语音转录
+- 语音关键词检测
+
+### 13.5 计划模式
+用于在编码前设计实现策略的只读模式：
+- 在 `.claude/plans/` 中创建计划文件
+- 限制工具为只读操作
+- 执行前需要用户明确批准
+- 由 `EnterPlanModeTool` / `ExitPlanModeTool` 管理
+
+### 13.6 工作树模式
+用于安全实验的 Git 工作树隔离：
+- 创建临时 Git 工作树
+- 支持 tmux 会话管理
+- 临时分支创建
+- 变更可以合并或丢弃
+
+### 13.7 Vim 模式（`src/vim/`）
+终端输入的 Vim 键绑定集成。
+
+---
+
+## 14. 插件与技能
+
+### 插件系统（`src/plugins/`）
+
+- `plugins/bundled/` 中的**内置插件**（键盘快捷键、主题等）
+- 通过 `PluginInstallationManager` 管理插件生命周期
+- 用于插件管理的 CLI 命令
+- 通过 `reload-plugins` 命令支持热重载
+
+### 技能系统（`src/skills/`）
+
+- `skills/bundled/` 中的**内置技能**（提交、审查、简化等）
+- 技能是可通过 `/skill-name` 调用的命名提示词
+- 技能发现与执行引擎
+- 变更检测支持实时更新
+
+---
+
+## 15. 钩子与可扩展性
+
+### 钩子模式（`src/schemas/hooks.ts`）
+
+通过 Zod 验证定义：
+- `HookEvent` — 执行前/执行后生命周期钩子
+- `PromptRequest` / `PromptResponse` — 用户提示协议
+- 同步和异步钩子响应模式
+- 权限决策钩子
+
+### React Hooks（`src/hooks/`）
+
+| Hook                | 用途                                       |
+|---------------------|--------------------------------------------|
+| `useSettings`       | 设置变更检测                               |
+| `useTerminalSize`   | 终端尺寸追踪                               |
+| `useExitOnCtrlC`    | 信号处理                                   |
+| `useBlink`          | 光标闪烁动画                               |
+| `useDoublePress`    | 双按键检测                                 |
+| `useCanUseTool`     | 工具权限验证                               |
+
+### 工具 Hooks（`src/utils/hooks/`）
+
+用于 Shell 配置、权限状态和工具行为的额外 Hooks。
+
+---
+
+## 16. 文件统计
+
+| 分类                        | 数量    |
+|-----------------------------|---------|
+| **TypeScript 文件总数**     | 1,884   |
+| **命令模块**                | 101     |
+| **工具实现**                | 41      |
+| **UI 组件**                 | 130+    |
+| **工具函数文件**            | 300+    |
+| **服务模块**                | 35+     |
+| **顶层源文件**              | 18      |
+| **入口点**                  | 6       |
+| **`src/` 中的子目录**       | 37      |
+
+---
+
+## 17. 架构模式
+
+### 延迟加载与死代码消除
+通过 `require()` 条件导入，由 Bun 的 `feature()` 标志门控。这使得在打包时可以对整个子系统（例如 `KAIROS`、`COORDINATOR_MODE`）进行 Tree-Shaking。
+
+```typescript
+const assistantModule = feature('KAIROS')
+  ? require('./assistant/index.js')
+  : null;
+```
+
+### 基于工具的执行模型
+与外部世界的每次交互都通过已注册的 `Tool` 进行。工具具有：
+- 声明式 JSON Schema 输入
+- 执行前的权限检查
+- 执行期间的进度报告
+- 结构化结果输出
+
+### 命令模式
+斜杠命令是模块化目录，每个目录导出一个 `Command` 对象。`commands.ts` 中的注册表将它们聚合在一起，支持可选的特性门控条件。
+
+### 消息驱动架构
+对话是一系列类型化消息（`UserMessage`、`AssistantMessage`、`SystemMessage`、`ProgressMessage` 等），由 `QueryEngine` 管理。工具结果作为 `ToolResultBlockParam` 消息注入。
+
+### 上下文压缩
+当对话上下文接近模型窗口限制时，系统自动压缩旧消息，同时保留关键上下文。提供多种策略：完整压缩、微压缩（选择性修剪）和会话记忆持久化。
+
+### 权限优先安全模型
+每次工具执行都经过权限检查。模式包括：
+- **询问** — 每次操作都提示用户
+- **自动允许** — 基于信任规则允许
+- **拒绝** — 阻止特定操作
+- **文件系统沙箱** — 将文件访问限制在项目目录内
+
+### React 终端 UI
+整个 UI 是通过 Ink 渲染的 React 组件树。这使得以下特性成为可能：
+- 声明式 UI 更新
+- 组件组合与复用
+- 状态驱动渲染
+- 针对终端特定行为的 Hooks（光标、窗口调整、键盘）
+
+---
+
+---
+
+## 贡献
+
+欢迎贡献！如果你发现了额外的架构细节、发现了不准确之处，或想扩展特定子系统的覆盖范围：
+
+1. **Fork** 本仓库
+2. 为你的更改**创建分支**（`git checkout -b fix/tool-system-details`）
+3. **提交 Pull Request**，并附上清晰的描述说明你添加或修正了什么
+
+请保持贡献的事实性和技术准确性。这是一份参考文档——推测内容应明确标注。
+
+---
+
+> **免责声明：** 这是一份非官方的独立分析。Claude Code 是 [Anthropic](https://www.anthropic.com/) 的产品。所有商标归其各自所有者所有。
+
+*生成于 2025-03-31。基于对 Claude Code 源码树的分析。*

README.zh-CN.md

@@ -3,7 +3,7 @@
 # Claude Code 源码分析
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Documentation](https://img.shields.io/badge/docs-DOCUMENTATION.md-green.svg)](DOCUMENTATION.md)
+[![Documentation](https://img.shields.io/badge/docs-DOCUMENTATION.md-green.svg)](DOCUMENTATION.zh-CN.md)
 [![English](https://img.shields.io/badge/language-English-brightgreen.svg)](README.md)
 [![中文](https://img.shields.io/badge/语言-中文-orange.svg)](README.zh-CN.md)
 
@@ -73,6 +73,8 @@ open DOCUMENTATION.md
 
 ---
 
-📖 **[阅读完整分析 →](DOCUMENTATION.md)**
+📖 **[阅读完整分析（中文） →](DOCUMENTATION.zh-CN.md)**
+
+📖 **[阅读完整分析（English） →](DOCUMENTATION.md)**
 
 🇺🇸 **[English Version →](README.md)**