大海
449 lines
15 KiB
Markdown
449 lines
15 KiB
Markdown
# Claude Code 源码深度分析 (fazxes/Claude-code)
|
||
|
||
> 基于 2026年3月31日泄露源码重建版本 v2.1.88
|
||
> 源码: https://github.com/fazxes/Claude-code | ⭐218 | TypeScript | Bun
|
||
|
||
---
|
||
|
||
## 一、总览
|
||
|
||
Claude Code 是 Anthropic 的**终端 AI 编程代理工具**，核心思想是：
|
||
> "一只生活在终端里的 AI，理解你的代码库，通过自然语言帮你写代码、执行任务"
|
||
|
||
**技术栈:**
|
||
- **运行时:** Bun（不是 Node.js）
|
||
- **语言:** TypeScript
|
||
- **编译:** 单文件 `build.ts` → 打包成 `dist/cli.js`（~23MB单文件）
|
||
- **UI渲染:** 自研 Ink 分支（`src/ink/`）+ React 前端渲染
|
||
- **编排:** Commander.js CLI 框架
|
||
- **AI模型:** Anthropic Claude (通过 `@anthropic-ai/sdk`)
|
||
|
||
---
|
||
|
||
## 二、核心架构（8层解构）
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ CLI 入口 │
|
||
│ src/main.tsx → src/entrypoints/cli.tsx │
|
||
│ Commander.js 命令行解析 │
|
||
├──────────────────────────────────────────────┤
|
||
│ Session / Query 引擎 │
|
||
│ src/query.ts (68KB) — 核心对话循环 │
|
||
│ 路由、工具调用、权限、压缩、记忆 │
|
||
├──────────────────────────────────────────────┤
|
||
│ 系统提示词 (灵魂) │
|
||
│ src/constants/prompts.ts — 176行原则 │
|
||
│ 任务执行准则、工具使用、代码风格 │
|
||
├──────────────────────────────────────────────┤
|
||
│ 45个工具 (tools/) │
|
||
│ FileEdit/FileRead/FileWrite/Bash/Grep/ │
|
||
│ Glob/WebSearch/WebFetch/Agent/Task/ │
|
||
│ Skill/MCP/TodoWrite/AskUserQuestion... │
|
||
│ 每个工具独立目录，继承 Tool 基类 │
|
||
├──────────────────────────────────────────────┤
|
||
│ Hook 系统 (155文件) │
|
||
│ src/utils/hooks/ │
|
||
│ PreToolUse / PostToolUse / SessionStart │
|
||
│ / Notification / Stop / PreCompact... │
|
||
├──────────────────────────────────────────────┤
|
||
│ 插件系统 (65+文件) │
|
||
│ src/utils/plugins/ │
|
||
│ 加载 .claude/plugins/，支持bin/可执行文件 │
|
||
├──────────────────────────────────────────────┤
|
||
│ 权限系统 (精准控制) │
|
||
│ src/utils/permissions/ │
|
||
│ yoloClassifier.ts (52KB) — 自动模式逻辑 │
|
||
│ 三级权限: allow / ask / deny │
|
||
├──────────────────────────────────────────────┤
|
||
│ 服务层 (services/) │
|
||
│ MCP / LSP / 压缩 / 记忆 / 分析 / OAuth │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 三、灵魂精华：系统提示词设计 (prompts.ts)
|
||
|
||
这是整个项目最重要的文件——它告诉 Claude **怎么当一个好的编程助手**。
|
||
|
||
### 3.1 核心人格定义
|
||
|
||
```
|
||
你是一个交互式AI编程助手。
|
||
你的输出在等宽字体终端中渲染，使用 GitHub Flavored Markdown。
|
||
```
|
||
|
||
### 3.2 代码原则（最精华的 6 条）
|
||
|
||
1. **只做被要求的** — 不增加需求以外的功能、重构、文档、类型注解
|
||
2. **不做无谓防御** — 不为不可能发生的场景加错误处理/兼容代码
|
||
3. **不做过早抽象** — 三次重复才考虑提取，一次性操作用完即弃
|
||
4. **只加必要注释** — 只有 WHY 不明显时才注释，不说 WHAT（好变量名已经做到）
|
||
5. **不留历史垃圾** — 不保留未用变量、空导出、`// removed` 注释
|
||
6. **不说空话** — 不用"Great question!"、"I'd be happy to help"这样的 filler
|
||
|
||
### 3.3 风险和后果分层
|
||
|
||
| 风险级别 | 示例操作 | 策略 |
|
||
|---------|---------|------|
|
||
| 可逆+本地 | 编辑文件、跑测试 | 自由执行 |
|
||
| 中等风险 | 推送代码、修改CI/CD | 透明沟通后确认 |
|
||
| 高风险 | 删库、rm -rf、force-push | 必须确认 |
|
||
| 不可逆 | 删除分支、覆盖未提交变更 | 调查后再操作 |
|
||
|
||
### 3.4 遇到障碍时的行为准则
|
||
|
||
- 失败后先诊断原因，不盲目重试
|
||
- 不把破坏性操作当作"捷径"
|
||
- 遇到意外状态（陌生文件/分支/配置）先调查，不直接删除
|
||
- 冲突合并优先于丢弃变更
|
||
- "量两次，裁一次"(Measure twice, cut once)
|
||
|
||
### 3.5 工具使用纪律
|
||
|
||
**专用工具优先于 Bash：**
|
||
- `FileRead` 代替 `cat`
|
||
- `FileEdit` 代替 `sed/awk`
|
||
- `FileWrite` 代替 `cat > heredoc`
|
||
- `Glob` 代替 `find`
|
||
- `Grep` 代替 `grep/rg`
|
||
|
||
**并行调用:** 能并发的工具调用全部并行发送，最大化效率
|
||
|
||
### 3.6 报告诚实原则
|
||
|
||
- 测试失败 → 如实报告，附完整输出
|
||
- 没做验证 → 说没做，不假装做了
|
||
- 状态确认 → 通过就说过，失败就说失败，不捏造"全部通过"
|
||
|
||
---
|
||
|
||
## 四、工具系统设计
|
||
|
||
### 4.1 Tool 基类 (src/Tool.ts, ~29KB)
|
||
|
||
```typescript
|
||
export class Tool {
|
||
// 工具描述（发送给模型）
|
||
description(params: ToolDescriptionParams): string
|
||
|
||
// JSON Schema 输入定义
|
||
readonly inputSchema: z.ZodTypeAny
|
||
|
||
// 工具提示词（注入系统提示词）
|
||
get prompt(): string | undefined
|
||
|
||
// 权限检查
|
||
checkPermissions(input, context): PermissionResult
|
||
|
||
// 执行
|
||
call(input, context): ToolResultBlockParam[]
|
||
|
||
// 可被搜索到（ToolSearch）
|
||
isToolSearchable(): boolean
|
||
}
|
||
```
|
||
|
||
### 4.2 工具列表（45个）
|
||
|
||
| 分类 | 工具名 | 功能 |
|
||
|------|-------|------|
|
||
| **文件** | FileReadTool | 读取文件（和bash跟踪联动） |
|
||
| | FileEditTool | 精确编辑文件 |
|
||
| | FileWriteTool | 创建文件 |
|
||
| | GlobTool | 文件搜索 |
|
||
| | GrepTool | 内容搜索 |
|
||
| **代码** | BashTool | 执行shell命令 |
|
||
| | LSPTool | 语言服务器协议 |
|
||
| | NotebookEditTool | Jupyter Notebook 编辑 |
|
||
| **网络** | WebSearchTool | 网页搜索 |
|
||
| | WebFetchTool | 抓取网页内容 |
|
||
| **任务** | TaskCreateTool | 创建任务 |
|
||
| | TodoWriteTool | 写待办 |
|
||
| | TaskListTool | 列出任务 |
|
||
| | TaskUpdateTool | 更新任务 |
|
||
| | TaskOutputTool | 获取子任务输出 |
|
||
| | TaskStopTool | 停止任务 |
|
||
| **代理** | AgentTool | 创建子代理（Explore/Plan/Verify） |
|
||
| | SkillTool | 调用技能 |
|
||
| **MCP** | MCPTool | MCP协议工具 |
|
||
| | McpAuthTool | MCP认证 |
|
||
| | ReadMcpResourceTool | 读取MCP资源 |
|
||
| | ListMcpResourcesTool | 列出MCP资源 |
|
||
| **交互** | AskUserQuestionTool | 向用户提问 |
|
||
| | SendMessageTool | 发送消息 |
|
||
| **计划** | EnterPlanModeTool | 进入计划模式 |
|
||
| | ExitPlanModeTool | 退出计划模式 |
|
||
| **其他** | SleepTool | 睡眠延迟 |
|
||
| | ScheduleCronTool | 定时任务 |
|
||
| | VerifyPlanExecutionTool | 计划验证 |
|
||
| | BriefTool | 摘要 |
|
||
| | ToolSearchTool | 搜索工具 |
|
||
| | ConfigTool | 配置管理 |
|
||
| | RemoteTriggerTool | 远程触发 |
|
||
| **内部** | REPLTool | REPL模式（仅Ant-内部） |
|
||
| | TungstenTool | 调试工具（仅Ant-内部） |
|
||
| | SuggestBackgroundPRTool | 后台PR（仅Ant-内部） |
|
||
|
||
### 4.3 工具间的智能联动
|
||
|
||
**Edit工具能看见Bash读过的文件：**
|
||
```typescript
|
||
// BashTool.tsx — 跟踪 cat/sed/head/tail 的输出
|
||
// 当用户用 bash 看过文件后, Edit 不需要再 Read
|
||
// "Edit works on files viewed via Bash"
|
||
```
|
||
|
||
**子代理 Fork 模式：**
|
||
```
|
||
fork = 后台子代理，不占主对话的 context
|
||
主对话可以继续跟用户聊天，fork 在后台工作
|
||
完成后通过进度通知告知结果
|
||
```
|
||
|
||
---
|
||
|
||
## 五、Hook 系统（155文件）
|
||
|
||
### 5.1 Hook 事件类型
|
||
|
||
| Hook 事件 | 触发时机 |
|
||
|----------|---------|
|
||
| SessionStart | 会话启动 |
|
||
| PreToolUse | 工具调用前 |
|
||
| PostToolUse | 工具调用后 |
|
||
| Notification | 通知发生时 |
|
||
| Stop | 回复结束时 |
|
||
| PreCompact | 上下文压缩前 |
|
||
| SubagentStop | 子代理结束时 |
|
||
| PermissionDenied | 权限被拒时 |
|
||
| UserPromptSubmit | 用户提交提示词前 |
|
||
|
||
### 5.2 Hook 配置 (settings.json)
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PreToolUse": [
|
||
{
|
||
"matcher": "Bash",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "bun run security-check.sh"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.3 设计精髓
|
||
|
||
- **Hook 反馈被视为用户指令** — 会阻塞工具调用
|
||
- **大输出写磁盘** — >50KB 的输出写临时文件防爆 context
|
||
- **可以调整响应** — hook 拒绝了就改方案，不问用户
|
||
|
||
---
|
||
|
||
## 六、权限系统
|
||
|
||
### 6.1 三级权限模式
|
||
|
||
```
|
||
allow → 静默执行
|
||
ask → 弹窗让用户确认
|
||
deny → 直接拒绝
|
||
```
|
||
|
||
### 6.2 YOLO 分类器 (52KB)
|
||
|
||
`yoloClassifier.ts` 是自动模式的决策引擎：
|
||
- 分析 Bash 命令的风险等级
|
||
- 决定是否自动允许
|
||
- 包含网络/文件/进程操作的规则
|
||
|
||
### 6.3 权限规则范围
|
||
|
||
| 规则类型 | 说明 |
|
||
|---------|------|
|
||
| alwaysAllowRules | 永久允许 |
|
||
| alwaysDenyRules | 永久拒绝 |
|
||
| alwaysAskRules | 永远询问 |
|
||
| toolPermissionContext | 当前会话上下文 |
|
||
|
||
---
|
||
|
||
## 七、Query 引擎的对话循环 (query.ts, 68KB)
|
||
|
||
### 核心流程
|
||
|
||
```
|
||
1. 构建系统提示词 (static prefix + dynamic suffix)
|
||
├── 前缀: 人格 + 准则 + 工具文档 (缓存用 global cache)
|
||
└── 后缀: 会话特定信息 (用户语言/设置/CLAUDEmd/记忆)
|
||
|
||
2. 发送给 Claude API (Anthropic SDK)
|
||
├── 携带工具定义 (JSON Schema)
|
||
└── 流式接收回复
|
||
|
||
3. 解析回复
|
||
├── 文本 → 直接输出给用户
|
||
├── tool_use → 进入权限流程
|
||
│ ├── 触发 PreToolUse hooks
|
||
│ ├── 权限检查 (allow/ask/deny)
|
||
│ └── 执行工具调用 + PostToolUse hooks
|
||
└── system reminders → 追加到上下文
|
||
|
||
4. 上下文压缩 (当 token 接近限制)
|
||
├── 自动触发 compact
|
||
└── 旧消息 → 摘要
|
||
|
||
5. 循环 — 直到用户 stop 或任务完成
|
||
```
|
||
|
||
### 压缩策略
|
||
|
||
```
|
||
autocompact 电路：
|
||
- 接近 context window → 自动压缩
|
||
- 3次连续失败 → 触发 circuit breaker → 报错提示
|
||
- 压缩保留: 重要决策/用户反馈/未完成任务
|
||
```
|
||
|
||
---
|
||
|
||
## 八、UI渲染系统
|
||
|
||
### Ink 分支（非 npm 的 ink 包）
|
||
|
||
```
|
||
src/ink/ — 完整自研 React 终端渲染器
|
||
├── 自定义 Flexbox 布局 (src/native-ts/yoga-layout/)
|
||
├── 终端组件: Box/Text/Spinner/StatusBar
|
||
├── 权限弹窗
|
||
└── 进度条和 loading 动画
|
||
```
|
||
|
||
**不用 npm 的 ink，而是自研分支：**
|
||
- 完全控制样式
|
||
- 优化的性能
|
||
- 支持 Claude Code 特有的交互模式
|
||
|
||
---
|
||
|
||
## 九、关键技术细节
|
||
|
||
### 9.1 模型特征门控 (Feature Flags)
|
||
|
||
```typescript
|
||
import { feature } from 'bun:bundle'
|
||
|
||
// 所有内部功能用 feature() 门控
|
||
// 泄露版中 shims/bun-bundle.ts 全部返回 false
|
||
// 意味着所有未发布功能被彻底禁用
|
||
if (feature('VERIFICATION_AGENT')) {
|
||
// 验证代理 (仅Ant内部)
|
||
}
|
||
```
|
||
|
||
### 9.2 CLAUDE.md 机制
|
||
|
||
```
|
||
src/utils/claudemd.ts — CLAUDE.md 加载器
|
||
|
||
功能:
|
||
- 自动读取项目的 CLAUDE.md / .claude/CLAUDE.md
|
||
- 支持 @path 引用其他文件
|
||
- 支持 frontmatter 的 paths: glob 模式
|
||
- 自动剥离 HTML 注释
|
||
- 父子目录合并优先级: 子 > 父
|
||
```
|
||
|
||
这就是为什么 Claude Code 能"理解项目"——它把 CLAUDE.md 注入系统提示词！
|
||
|
||
### 9.3 记忆系统 (MEMORY.md)
|
||
|
||
```
|
||
src/memdir/memdir.ts — 记忆文件加载
|
||
- 读取 MEMORY.md 并注入提示词
|
||
- 支持 markdown 的上下文引用
|
||
```
|
||
|
||
### 9.4 构建系统
|
||
|
||
```typescript
|
||
// build.ts — 不是 webpack/vite，而是手写构建脚本
|
||
// 用 Bun.build() 打包
|
||
// MACRO.VERSION 硬编码为 "2.1.88"
|
||
// 输出: dist/cli.js (~23MB 单文件)
|
||
// 入口: src/entrypoints/cli.tsx
|
||
```
|
||
|
||
### 9.5 更新检测已被打补丁
|
||
|
||
```typescript
|
||
// src/utils/autoUpdater.ts 第72行有 early return
|
||
// 禁用了远程版本检查
|
||
// 防止泄露版尝试连接 Anthropic 服务器
|
||
```
|
||
|
||
### 9.6 MCP 协议集成
|
||
|
||
```
|
||
@modelcontextprotocol/sdk — MCP 标准协议
|
||
- 支持本地和远程 MCP 服务器
|
||
- MCP工具自动注册，和内置工具一样使用
|
||
- MCP_CONNECTION_NONBLOCKING=true → 5秒超时
|
||
- _meta["anthropic/maxResultSizeChars"] → 最大500K字符
|
||
```
|
||
|
||
### 9.7 运营监控集成
|
||
|
||
```
|
||
OpenTelemetry (追踪/日志/指标)
|
||
├── OTLP HTTP/gRPC/Proto 三种导出器
|
||
├── Prometheus 指标导出
|
||
└── GrowthBook 功能开关 (A/B 测试)
|
||
```
|
||
|
||
---
|
||
|
||
## 十、架构精髓总结
|
||
|
||
### 🌟 10个设计精华
|
||
|
||
1. **提示词就是产品** — prompts.ts 才是真正的产品逻辑，176条准则定义了一个"好AI助手"的一切
|
||
2. **工具分层清晰** — 每个工具继承 Tool 基类，独立目录，description + inputSchema + call + prompt 四合一
|
||
3. **Hook 系统在工具之上** — 不是后加的，是核心架构的一部分，每个工具调用都被Hook包围
|
||
4. **权限在工具之下** — 每次调用前都要过权限检查，分三级(allow/ask/deny)，有52KB的自动决策引擎
|
||
5. **Context 管理是关键** — 自动压缩、claude.md机制、记忆文件、会话管理全部围绕"不丢上下文"
|
||
6. **UI 自研不是炫技** — 终端里的 React 渲染器有自己独特的需求（权限弹窗、进度、状态栏）
|
||
7. **子代理是叉子不是线程** — Fork 模式让子代理不占主 context，异步执行
|
||
8. **工具可以互相感知** — Bash 读过的文件 Edit 就知道，不需要重复 Read
|
||
9. **所有内部功能都被门控** — Feature flags 让泄露代码安全可运行，同时保留完整架构供学习
|
||
10. **Bun 不是 Node.js** — 用 Bun 的构建、Bun 的类型系统、Bun 的 API，比 Node.js 更快更现代
|
||
|
||
### 不适合学习的部分
|
||
|
||
- 27个 stub 文件（占位代码，不影响架构理解）
|
||
- Anthropic 内部工具（REPL/Tungsten/SuggestBackgroundPR）
|
||
- Computer Use（需要本机 Swift/Rust 二进制）
|
||
- 运营分析（GrowthBook/OpenTelemetry 配置）
|
||
|
||
### 最适合学习的部分
|
||
|
||
1. **系统提示词设计** — `prompts.ts` 是 AI Agent 提示词工程的教科书
|
||
2. **工具抽象** — `Tool.ts` 基类 + 45个工具，展示了如何构建Agent工具系统
|
||
3. **Hook 系统** — 155个文件的事件驱动架构
|
||
4. **权限系统** — 三级权限 + 自动分类器
|
||
5. **Query 引擎** — 对话循环、token管理、上下文压缩
|
||
6. **CLAUDE.md 机制** — 如何让 AI 理解项目
|
||
|
||
---
|
||
|
||
*分析时间: 2026-05-30*
|
||
*分析者: 小龙 (Xiao Long) 🐉*
|