Claude Code （泄漏）源码概要设计文档
·
Claude Code 概要设计文档
1. 系统概述
1.1 系统定位
Claude Code 是一个基于 AI 的终端助手系统，通过自然语言界面帮助用户完成软件工程任务。系统采用 CLI 形式，支持跨平台运行（Windows/macOS/Linux），基于 Node.js/Bun 运行时。
1.2 核心目标
- 自然语言交互: 用户通过自然语言描述任务，系统自动理解并执行
- 工具编排: 提供丰富的工具集（文件操作、Shell 执行、代码搜索等），支持 AI 调用
- 可扩展架构: 通过插件、技能、MCP 协议支持第三方扩展
- 安全可靠: 完善的权限系统，敏感操作需用户确认
2. 系统架构
2.1 整体架构图
┌─────────────────────────────────────────────────────────────────────────┐
│ 用户界面层 (UI Layer) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Terminal │ │ REPL │ │ Ink UI │ │ SDK/Print │ │
│ │ (Interactive) │ │ (Read-Eval-Print) │ │ (React-based) │ │ (Non-interactive) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 核心引擎层 (Core Engine) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Query Loop (query.ts) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Message │ │ Tool │ │ Token │ │ │
│ │ │ Construction │─▶│ Execution │─▶│ Budget │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 服务层 (Services Layer) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Tool │ │ Command │ │ Skill │ │ MCP │ │ Plugin │ │
│ │ System │ │ System │ │ System │ │ Protocol│ │ System │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ State │ │ Permission│ │ Session │ │ Analytics│ │ Config │ │
│ │ Mgmt │ │ System │ │ Mgmt │ │ Service │ │ Service │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 基础设施层 (Infrastructure) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ File │ │ Shell │ │ Network │ │
│ │ System │ │ Executor │ │ Client │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Git │ │ Process │ │ Database │ │
│ │ Integration │ │ Management │ │ (SQLite) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 外部集成层 (External Integration) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Anthropic │ │ MCP │ │ LSP │ │
│ │ API │ │ Servers │ │ Servers │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 技术栈
| 层次 | 技术选型 | 说明 |
|---|---|---|
| 运行时 | Bun / Node.js 18+ | JavaScript/TypeScript 运行环境 |
| 语言 | TypeScript | 类型安全的 JavaScript 超集 |
| UI 框架 | React + Ink | 终端 UI 渲染 |
| 状态管理 | 自定义 Store | 轻量级状态管理 |
| ** Schema 验证** | Zod | 运行时类型验证 |
| MCP 协议 | @modelcontextprotocol/sdk | 外部服务集成 |
| AI API | @anthropic-ai/sdk | Claude API 客户端 |
3. 核心模块设计
3.1 工具系统 (Tool System)
3.1.1 职责
- 提供统一的工具接口规范
- 管理工具的注册、发现和执行
- 处理工具权限验证
- 渲染工具执行结果
3.1.2 核心接口
interface Tool<Input, Output, Progress> {
// 基本属性
name: string
description: (input, options) => Promise<string>
inputSchema: Zod Schema
outputSchema?: Zod Schema
// 执行方法
call(args, context, canUseTool, onProgress): Promise<ToolResult<Output>>
// 安全验证
validateInput?(input, context): Promise<ValidationResult>
checkPermissions?(input, context): Promise<PermissionResult>
isConcurrencySafe(input): boolean
isReadOnly(input): boolean
isDestructive?(input): boolean
// UI 渲染
renderToolUseMessage(input, options): React.ReactNode
renderToolResultMessage(content, progress, options): React.ReactNode
}
3.1.3 工具分类
| 类别 | 工具 | 数量 |
|---|---|---|
| 核心工具 | Bash, FileRead, FileEdit, FileWrite | 4 |
| 搜索工具 | Grep, Glob, WebSearch | 3 |
| 任务工具 | TaskCreate, TaskUpdate, TaskList, TaskStop | 4 |
| 代理工具 | Agent, Skill | 2 |
| MCP 工具 | ListMcpResources, ReadMcpResource | 2 |
| 扩展工具 | LSP, WebBrowser, TerminalCapture | 可变 |
3.2 命令系统 (Command System)
3.2.1 职责
- 管理用户可执行的 CLI 命令（以
/开头） - 支持内置命令、插件命令、技能命令
- 处理命令的加载、解析和执行
3.2.2 命令类型
type Command =
| { type: 'prompt' } // 扩展为文本发送给模型
| { type: 'local' } // 本地执行，输出文本
| { type: 'local-jsx' } // 本地执行，渲染 Ink UI
3.2.3 命令来源
| 来源 | 路径 | 示例 |
|---|---|---|
| builtIn | cli/src/commands/ | /help, /config, /mcp |
| bundled | cli/src/skills/bundled/ | 内置技能 |
| skills | ~/.claude/skills/, .claude/skills/ | 用户技能 |
| plugin | 插件目录 | 插件命令 |
| mcp | MCP 服务器 | MCP 技能 |
3.3 技能系统 (Skill System)
3.3.1 职责
- 提供领域专用的预定义工作流
- 支持 Markdown 文件定义技能
- 支持参数替换和 Shell 命令执行
3.3.2 技能定义格式
---
name: code-review
description: Review code changes
whenToUse: When user asks for code review
allowedTools: Read, Grep, Bash
argumentNames: [file]
---
请审查以下文件的代码：{{file}}
审查要点：
1. 代码规范
2. 潜在 bug
3. 性能问题
3.4 MCP 系统 (Model Context Protocol)
3.4.1 职责
- 实现 MCP 客户端协议
- 连接外部 MCP 服务器
- 将 MCP 工具/资源转换为内部格式
3.4.2 支持的传输方式
| 类型 | 配置 | 示例 |
|---|---|---|
| stdio | command, args, env | npx -y mcp-server |
| sse | url, headers | http://localhost:8080/sse |
| http | url, headers | https://api.example.com/mcp |
| ws | url, headers | ws://localhost:9000 |
| sdk | name | 内部 SDK 集成 |
3.4.3 MCP 服务器状态
type MCPServerConnection =
| { type: 'connected' } // 已连接
| { type: 'failed' } // 连接失败
| { type: 'needs-auth' } // 需要认证
| { type: 'pending' } // 连接中
| { type: 'disabled' } // 已禁用
3.5 上下文管理 (Context Management)
3.5.1 系统上下文
由 getSystemContext() 生成，包括：
- Git 状态（分支、提交、变更）
- 平台信息
- 系统提示注入（cache breaker）
3.5.2 用户上下文
由 getUserContext() 生成，包括：
- CLAUDE.md 文档内容
- 当前日期
- 用户配置
3.5.3 上下文缓存
使用 memoize 缓存上下文，避免重复计算：
export const getSystemContext = memoize(async (): Promise<...> => {...})
export const getUserContext = memoize(async (): Promise<...> => {...})
3.6 状态管理 (State Management)
3.6.1 状态存储
type Store<T> = {
getState: () => T
setState: (updater: (prev: T) => T) => void
subscribe: (listener: Listener) => () => void
}
3.6.2 应用状态 (AppState)
核心状态包括：
settings: 用户配置tasks: 任务状态mcp: MCP 连接状态plugins: 插件状态toolPermissionContext: 权限上下文speculation: 推测执行状态
3.7 权限系统 (Permission System)
3.7.1 权限模式
| 模式 | 行为 |
|---|---|
| default | 默认模式，危险操作需确认 |
| bypassPermissions | 跳过权限确认 |
| acceptEdits | 自动接受文件编辑 |
| plan | 仅规划，不执行 |
| auto | 自动模式（基于分类器） |
| dontAsk | 拒绝危险操作，不询问 |
3.7.2 权限规则
type PermissionRule = {
source: 'userSettings' | 'projectSettings' | 'session' | ...
ruleBehavior: 'allow' | 'deny' | 'ask'
ruleValue: { toolName: string, ruleContent?: string }
}
4. 核心流程
4.1 Query Loop 流程
┌─────────────────────────────────────────────────────────────┐
│ Query Loop (query.ts) │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ 1. Build│ │ 2. Call │ │ 3. Process│
│ Prompt │──────────▶│ API │──────────▶│ Response│
└─────────┘ └─────────┘ └─────────┘
│
┌────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Check for Tool Uses │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Parse Tool │───▶│ Permission │───▶│ Execute │ │
│ │ Use Blocks │ │ Check │ │ Tool │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ 5. Add │ │ 6. Check│ │ 7. Loop │
│ Results │──────────▶│ Continue│──────────▶│ or Exit │
│ to Msgs │ │ Conditions│ │ │
└─────────┘ └─────────┘ └─────────┘
4.2 工具执行流程
用户请求
│
▼
模型输出 Tool Use
│
▼
解析工具参数
│
▼
validateInput() ────失败───▶ 返回错误
│ 成功
▼
checkPermissions() ──拒绝───▶ 显示权限对话框
│ 允许
▼
canUseTool() ──────拒绝───▶ 返回错误
│ 允许
▼
执行 tool.call()
│
▼
渲染结果
│
▼
返回给模型
4.3 命令加载流程
启动时
│
▼
加载内置命令 (COMMANDS)
│
▼
加载技能命令 (getSkills)
│ ├── bundledSkills
│ ├── skillDirCommands
│ └── pluginSkills
│
▼
加载插件命令 (getPluginCommands)
│
▼
合并并过滤 (getCommands)
│ ├── meetsAvailabilityRequirement()
│ └── isCommandEnabled()
│
▼
返回可用命令列表
5. 部署架构
5.1 单机部署
┌─────────────────────────────────────┐
│ 用户计算机 │
│ ┌─────────────────────────────┐ │
│ │ Claude Code CLI │ │
│ │ ┌───────────────────────┐ │ │
│ │ │ Node.js/Bun Runtime │ │ │
│ │ └───────────────────────┘ │ │
│ │ ┌───────────────────────┐ │ │
│ │ │ Local Tools │ │ │
│ │ │ - Shell │ │ │
│ │ │ - File System │ │ │
│ │ │ - Git │ │ │
│ │ └───────────────────────┘ │ │
│ └─────────────────────────────┘ │
│ │ │
│ │ HTTPS │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Anthropic API │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
5.2 远程模式部署
┌──────────────────┐ ┌──────────────────┐
│ 本地终端 │ │ 远程服务器 │
│ (Viewer Mode) │◀───────▶│ (Daemon Mode) │
│ │ WebSocket│ │
│ - 显示 UI │ │ - 执行工具 │
│ - 接收输入 │ │ - 管理会话 │
│ - 无工具执行 │ │ - 完整工具集 │
└──────────────────┘ └──────────────────┘
6. 安全设计
6.1 权限控制
- 所有写操作默认需要用户确认
- 支持基于路径的权限规则
- 支持基于命令模式的权限规则
6.2 沙箱执行
- Bash 工具支持沙箱模式
- 可通过配置禁用特定命令的沙箱
- 支持完全禁用沙箱（需显式授权）
6.3 数据保护
- 敏感信息存储在安全存储（Keychain/凭据管理器）
- OAuth 令牌加密存储
- 支持隐私模式（禁用遥测）
7. 扩展性设计
7.1 插件扩展点
| 扩展点 | 描述 | 示例 |
|---|---|---|
| commands | 自定义命令 | /deploy, /test |
| skills | 领域技能 | code-review, debug |
| agents | 自定义代理 | reviewer, tester |
| hooks | 生命周期钩子 | pre_tool_use |
| mcpServers | MCP 服务器 | 数据库连接 |
7.2 MCP 扩展
任何支持 MCP 协议的服务都可以集成：
- 数据库工具
- IDE 集成
- 云服务管理
- 自定义 API
8. 性能优化
8.1 启动优化
- 并行预取（MDM 设置、Keychain、OAuth）
- Lazy require 延迟加载大模块
- 命令和技能缓存
8.2 运行时优化
- Token 预算管理和自动压缩
- 工具结果持久化（避免重复读取）
- 上下文缓存和微压缩
8.3 内存优化
- LRU 缓存文件状态
- 大输出流式处理
- 后台任务输出按需读取
9. 错误处理
9.1 错误分类
| 类别 | 处理策略 |
|---|---|
| API 错误 | 重试 + 降级模型 |
| 工具错误 | 显示错误信息，允许修正 |
| 权限错误 | 显示权限对话框 |
| 系统错误 | 优雅降级，保存状态 |
9.2 恢复机制
- 会话恢复（/resume 命令）
- 自动保存关键点
- 错误日志和诊断
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
6
0- 0
已为社区贡献1条内容
所有评论(0)