mirror of
https://github.com/ComeOnOliver/claude-code-analysis.git
synced 2026-04-25 07:00:47 +09:00
ComeOnOliver
802 lines
36 KiB
Markdown
802 lines
36 KiB
Markdown
**[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 源码树的分析。*
|