From c45730b02591b6992dfc8aaa3483fd01b213815e Mon Sep 17 00:00:00 2001 From: ComeOnOliver Date: Tue, 31 Mar 2026 10:44:59 -0700 Subject: [PATCH] docs: add Chinese translation of full architecture analysis (DOCUMENTATION.zh-CN.md) --- DOCUMENTATION.md | 2 + DOCUMENTATION.zh-CN.md | 801 +++++++++++++++++++++++++++++++++++++++++ README.zh-CN.md | 6 +- 3 files changed, 807 insertions(+), 2 deletions(-) create mode 100644 DOCUMENTATION.zh-CN.md diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 42863ed..01d89e4 100644 --- a/DOCUMENTATION.md +++ b/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. diff --git a/DOCUMENTATION.zh-CN.md b/DOCUMENTATION.zh-CN.md new file mode 100644 index 0000000..c336ca6 --- /dev/null +++ b/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 源码树的分析。* diff --git a/README.zh-CN.md b/README.zh-CN.md index 1370931..28023d9 100644 --- a/README.zh-CN.md +++ b/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)**