邓文兵
0686f1969c
- 新增 008 号文章《51 万行源码意外曝光！我扒完了 Claude Code 的全部家底》 - 添加 8 个 Mermaid 架构图文件，涵盖整体架构、启动流程、查询循环等 - 新增项目配置文件 CLAUDE.md，定义自媒体写作规范 - 创建详细的架构分析文档 claude-arch-by-claude.md - 包含权限系统、工具调度、多智能体等核心技术解析 - 记录反蒸馏机制、KAIROS 守护进程等隐藏功能发现 - 提供完整的工具清单及安全防护措施说明
797 lines
28 KiB
Markdown
797 lines
28 KiB
Markdown
# Claude Code 源码泄漏深度架构分析
|
||
|
||
> 2026年3月31日，Anthropic 在 npm 发布 `@anthropic-ai/claude-code@2.1.88` 时，意外将一个 59.8MB 的 JavaScript Source Map 文件打包在内。这个 `.map` 文件指向了 Anthropic 自家 Cloudflare R2 存储桶上的完整 TypeScript 源码压缩包。安全研究员 Chaofan Shou 率先发现并公开了这个链接，数小时内，1,900 个 TypeScript 文件、512,664 行代码被完整镜像到了 GitHub 上。
|
||
>
|
||
> 本文将从架构层面，深入拆解这个"可能是当前最复杂的 AI 编程智能体"的内部实现。
|
||
|
||
---
|
||
|
||
## 一、技术栈总览
|
||
|
||
| 维度 | 技术选型 |
|
||
|------|---------|
|
||
| 语言 | TypeScript（1,884 个 `.ts/.tsx` 文件） |
|
||
| 运行时 | Bun（非 Node.js） |
|
||
| 终端 UI | 自研 Ink 分支 + React + Yoga Layout |
|
||
| Schema 校验 | Zod v4 |
|
||
| API 通信 | Anthropic SDK + SSE 流式传输 |
|
||
| 构建系统 | Bun Bundler（`bun:bundle` 特性开关） |
|
||
| 实验平台 | GrowthBook（`tengu_*` 前缀） |
|
||
| 可观测性 | OpenTelemetry + Datadog + Perfetto |
|
||
|
||
---
|
||
|
||
## 二、整体架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Entry["入口层"]
|
||
CLI["cli.tsx<br/>CLI 入口"]
|
||
MCP_ENTRY["mcp.ts<br/>MCP Server 入口"]
|
||
SDK["agentSdkTypes.ts<br/>SDK 入口"]
|
||
end
|
||
|
||
subgraph Core["核心引擎"]
|
||
MAIN["main.tsx<br/>4,683 行<br/>REPL 编排器"]
|
||
QE["QueryEngine.ts<br/>1,295 行<br/>会话管理器"]
|
||
QUERY["query.ts<br/>1,729 行<br/>流式查询循环"]
|
||
API["claude.ts<br/>3,419 行<br/>Anthropic API 客户端"]
|
||
end
|
||
|
||
subgraph Tools["工具系统"]
|
||
TOOL_DEF["Tool.ts<br/>792 行<br/>工具接口定义"]
|
||
TOOL_REG["tools.ts<br/>389 行<br/>工具注册表"]
|
||
TOOL_ORCH["toolOrchestration.ts<br/>并发调度"]
|
||
TOOL_EXEC["toolExecution.ts<br/>1,745 行<br/>执行引擎"]
|
||
end
|
||
|
||
subgraph Agent["多智能体"]
|
||
COORD["coordinatorMode.ts<br/>协调器"]
|
||
AGENT_RUN["runAgent.ts<br/>973 行<br/>子智能体启动器"]
|
||
TASKS["tasks/<br/>任务状态机"]
|
||
end
|
||
|
||
subgraph Infra["基础设施"]
|
||
PERM["permissions/<br/>24 个文件<br/>权限系统"]
|
||
MCP_CLIENT["mcp/client.ts<br/>3,348 行<br/>MCP 客户端"]
|
||
BRIDGE["bridge/<br/>27 个文件<br/>IDE 桥接"]
|
||
MEMDIR["memdir/<br/>9 个文件<br/>记忆系统"]
|
||
INK["ink/<br/>终端渲染引擎"]
|
||
end
|
||
|
||
CLI --> MAIN
|
||
MCP_ENTRY --> MAIN
|
||
SDK --> QE
|
||
|
||
MAIN --> QE
|
||
QE --> QUERY
|
||
QUERY --> API
|
||
QUERY --> TOOL_ORCH
|
||
|
||
TOOL_ORCH --> TOOL_EXEC
|
||
TOOL_EXEC --> TOOL_DEF
|
||
TOOL_REG --> TOOL_DEF
|
||
|
||
TOOL_EXEC --> AGENT_RUN
|
||
COORD --> AGENT_RUN
|
||
AGENT_RUN --> TASKS
|
||
AGENT_RUN --> QUERY
|
||
|
||
TOOL_EXEC --> PERM
|
||
MAIN --> MCP_CLIENT
|
||
MAIN --> BRIDGE
|
||
QE --> MEMDIR
|
||
MAIN --> INK
|
||
```
|
||
|
||
---
|
||
|
||
## 三、启动流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户终端
|
||
participant CLI as cli.tsx
|
||
participant Main as main.tsx
|
||
participant GB as GrowthBook
|
||
participant MCP as MCP Servers
|
||
participant REPL as REPL 循环
|
||
|
||
User->>CLI: claude 命令
|
||
CLI->>CLI: 快速路径检查<br/>(--version, --dump-system-prompt)
|
||
CLI->>Main: 动态 import main.tsx
|
||
|
||
par 并行初始化
|
||
Main->>GB: 加载特性开关
|
||
Main->>Main: 读取 settings / MDM / keychain
|
||
Main->>MCP: 连接 MCP 服务器
|
||
Main->>Main: 加载工具 & 命令
|
||
end
|
||
|
||
Main->>Main: 构建系统提示词
|
||
Main->>REPL: launchRepl()
|
||
REPL->>User: 就绪，等待输入
|
||
```
|
||
|
||
**关键设计**：`cli.tsx` 仅 302 行，通过动态 `import()` 延迟加载 `main.tsx`（4,683 行），确保 `--version` 等快速路径毫秒级响应。所有重量级依赖（MCP、GrowthBook、keychain）都通过并行初始化加载。
|
||
|
||
---
|
||
|
||
## 四、核心查询循环
|
||
|
||
### 4.1 QueryEngine — 会话管理器
|
||
|
||
`QueryEngine` 是 SDK/headless 模式下的会话管理器，一个实例管理一次完整对话：
|
||
|
||
```
|
||
QueryEngine
|
||
├── mutableMessages: Message[] // 消息历史（随对话增长）
|
||
├── abortController: AbortController // 会话级中止控制
|
||
├── permissionDenials: SDKPermissionDenial[] // 权限拒绝记录
|
||
├── totalUsage: NonNullableUsage // Token 用量聚合
|
||
├── discoveredSkillNames: Set<string> // 每轮发现的技能
|
||
└── loadedNestedMemoryPaths: Set<string> // 已加载的 CLAUDE.md 路径
|
||
```
|
||
|
||
核心方法 `submitMessage()` 是一个 `AsyncGenerator<SDKMessage>`，每次调用经历：
|
||
|
||
1. 构建系统提示词（`fetchSystemPromptParts()`）
|
||
2. 处理斜杠命令（`processUserInput()`）
|
||
3. 持久化用户消息到 transcript
|
||
4. 进入流式查询循环（`query()`），yield 出 `SDKMessage`
|
||
5. 处理上下文压缩、权限、最大轮次限制
|
||
|
||
### 4.2 query.ts — 流式查询循环
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
START["用户消息"] --> BUILD["构建查询配置"]
|
||
BUILD --> CALL["queryModelWithStreaming()<br/>调用 Anthropic API"]
|
||
CALL --> STREAM["流式接收响应"]
|
||
STREAM --> CHECK{是否有工具调用?}
|
||
|
||
CHECK -->|有| RUN_TOOLS["runTools()<br/>执行工具"]
|
||
RUN_TOOLS --> BUDGET["applyToolResultBudget()<br/>结果预算控制"]
|
||
BUDGET --> HOOKS["executePostSamplingHooks()"]
|
||
HOOKS --> COMPACT{"需要压缩?"}
|
||
COMPACT -->|是| AUTO_COMPACT["autoCompactIfNeeded()"]
|
||
AUTO_COMPACT --> CALL
|
||
COMPACT -->|否| CALL
|
||
|
||
CHECK -->|无| RECOVERY{max_output_tokens<br/>恢复?}
|
||
RECOVERY -->|是,≤3次| CALL
|
||
RECOVERY -->|否| STOP_HOOKS["handleStopHooks()"]
|
||
STOP_HOOKS --> END["返回结果"]
|
||
```
|
||
|
||
**关键机制**：
|
||
- **Output Recovery**：当模型因 `max_output_tokens` 截断时，自动重试最多 3 次
|
||
- **工具结果预算**：大结果持久化到磁盘，用文件路径 + 预览替代，防止上下文窗口膨胀
|
||
- **自动压缩**：接近上下文窗口限制时触发对话摘要压缩
|
||
- **依赖注入**：`QueryDeps` 接口注入 `callModel`、`microcompact`、`autocompact`、`uuid`，方便单元测试
|
||
|
||
---
|
||
|
||
## 五、工具系统
|
||
|
||
### 5.1 Tool 接口
|
||
|
||
`Tool<Input, Output, P>` 是一个功能丰富的接口，定义了工具的完整生命周期：
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class Tool {
|
||
+name: string
|
||
+description(input, options): string
|
||
+inputSchema: ZodSchema
|
||
+call(args, context, canUseTool, parentMessage, onProgress?)
|
||
+checkPermissions(input, context): PermissionResult
|
||
+validateInput(input, context): ValidationResult
|
||
+isReadOnly(input): boolean
|
||
+isConcurrencySafe(input): boolean
|
||
+isDestructive(input): boolean
|
||
+maxResultSizeChars: number
|
||
+shouldDefer: boolean
|
||
+renderToolUseMessage(input, options): ReactNode
|
||
+renderToolResultMessage(...): ReactNode
|
||
+toAutoClassifierInput(input): string
|
||
}
|
||
|
||
class ToolUseContext {
|
||
+options: Options
|
||
+abortController: AbortController
|
||
+appState: AppState
|
||
+permissionContext: PermissionContext
|
||
+fileStateCache: FileStateCache
|
||
+sessionMetadata: SessionMetadata
|
||
}
|
||
|
||
Tool --> ToolUseContext : 接收
|
||
```
|
||
|
||
### 5.2 完整工具清单
|
||
|
||
源码中注册了 **40+ 个工具**，按功能分类：
|
||
|
||
| 分类 | 工具名 | 说明 |
|
||
|------|--------|------|
|
||
| **文件操作** | FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool, NotebookEditTool | 文件读写、搜索、编辑 |
|
||
| **系统执行** | BashTool, PowerShellTool | Shell 命令执行 |
|
||
| **网络访问** | WebFetchTool, WebSearchTool | 网页抓取、搜索 |
|
||
| **智能体** | AgentTool, SendMessageTool, TeamCreateTool, TeamDeleteTool | 多智能体生成与协调 |
|
||
| **任务管理** | TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskStopTool, TaskOutputTool | 后台任务管理 |
|
||
| **规划模式** | EnterPlanModeTool, ExitPlanModeTool | 只读规划模式切换 |
|
||
| **Worktree** | EnterWorktreeTool, ExitWorktreeTool | Git Worktree 隔离 |
|
||
| **MCP** | MCPTool, ListMcpResourcesTool, ReadMcpResourceTool | MCP 协议交互 |
|
||
| **其他** | ToolSearchTool, SkillTool, AskUserQuestionTool, ConfigTool, BriefTool, LSPTool, TodoWriteTool | 工具搜索、技能、配置等 |
|
||
| **KAIROS 专属** | SleepTool, CronCreateTool, CronDeleteTool, CronListTool, MonitorTool, PushNotificationTool | 自主守护模式工具 |
|
||
|
||
### 5.3 工具执行调度
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph Parallel["并发批次"]
|
||
direction TB
|
||
G1["GlobTool ✓"]
|
||
G2["GrepTool ✓"]
|
||
G3["FileReadTool ✓"]
|
||
end
|
||
|
||
subgraph Serial["串行执行"]
|
||
direction TB
|
||
S1["FileEditTool"]
|
||
S2["BashTool"]
|
||
end
|
||
|
||
INPUT["工具调用列表"] --> PARTITION{"isConcurrencySafe?"}
|
||
PARTITION -->|true| Parallel
|
||
PARTITION -->|false| Serial
|
||
Parallel --> MERGE["合并结果"]
|
||
Serial --> MERGE
|
||
```
|
||
|
||
`toolOrchestration.ts` 将工具调用分为两类：
|
||
- **只读工具**（`isConcurrencySafe=true`）：`GlobTool`、`GrepTool`、`FileReadTool` 等，最多 10 个并发执行
|
||
- **写入工具**（`isConcurrencySafe=false`）：`FileEditTool`、`BashTool` 等，严格串行执行
|
||
|
||
---
|
||
|
||
## 六、权限系统
|
||
|
||
权限系统由 24 个文件组成，是 Claude Code 安全模型的核心。
|
||
|
||
### 6.1 权限模式
|
||
|
||
| 模式 | 说明 |
|
||
|------|------|
|
||
| `default` | 每次新操作提示用户确认 |
|
||
| `plan` | 只读规划模式，禁止写操作 |
|
||
| `acceptEdits` | 自动接受文件编辑 |
|
||
| `bypassPermissions` | 绕过所有权限检查 |
|
||
| `dontAsk` | 从不询问（自动拒绝未允许的操作） |
|
||
| `auto` | AI 驱动的自动审批（Anthropic 内部专用） |
|
||
|
||
### 6.2 权限决策流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
REQ["工具调用请求"] --> DENY{"在 alwaysDeny 规则中?"}
|
||
DENY -->|是| BLOCKED["❌ 拒绝"]
|
||
DENY -->|否| ALLOW{"在 alwaysAllow 规则中?"}
|
||
ALLOW -->|是| PASS["✅ 允许"]
|
||
ALLOW -->|否| TOOL_CHECK{"工具自身<br/>checkPermissions()"}
|
||
TOOL_CHECK -->|拒绝| BLOCKED
|
||
TOOL_CHECK -->|允许| CLASSIFIER{"AI 分类器<br/>(auto 模式)"}
|
||
CLASSIFIER -->|安全| PASS
|
||
CLASSIFIER -->|危险| DIALOG{"shouldAvoidPermissionPrompts?"}
|
||
DIALOG -->|是| BLOCKED
|
||
DIALOG -->|否| USER["🔔 提示用户确认"]
|
||
USER -->|允许| PASS
|
||
USER -->|拒绝| BLOCKED
|
||
```
|
||
|
||
权限规则支持 glob 模式匹配，例如 `Bash(git *)` 允许所有 `git` 开头的 bash 命令。`denialTracking.ts` 追踪连续拒绝次数，超过阈值后触发降级到手动确认模式。
|
||
|
||
---
|
||
|
||
## 七、多智能体架构
|
||
|
||
### 7.1 协调器模式
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Coordinator["协调器 (Coordinator)"]
|
||
C["协调器智能体<br/>全局视角 + 任务分配"]
|
||
end
|
||
|
||
subgraph Workers["工作智能体 (Workers)"]
|
||
W1["Worker 1<br/>文件探索"]
|
||
W2["Worker 2<br/>代码修改"]
|
||
W3["Worker 3<br/>测试验证"]
|
||
end
|
||
|
||
C -->|"AgentTool<br/>生成"| W1
|
||
C -->|"AgentTool<br/>生成"| W2
|
||
C -->|"SendMessageTool<br/>追加指令"| W1
|
||
W1 -->|"task-notification<br/>XML 回报"| C
|
||
W2 -->|"task-notification<br/>XML 回报"| C
|
||
C -->|"AgentTool<br/>生成"| W3
|
||
W3 -->|"task-notification<br/>XML 回报"| C
|
||
C -->|"TaskStopTool<br/>终止"| W1
|
||
```
|
||
|
||
协调器系统提示词（300+ 行）定义了 **四阶段工作流**：
|
||
|
||
1. **Research** — 探索代码库，理解上下文
|
||
2. **Synthesis** — 综合发现，制定方案
|
||
3. **Implementation** — 并行执行代码修改
|
||
4. **Verification** — 验证结果，运行测试
|
||
|
||
关键原则写在 prompt 里而非代码里：
|
||
- *"Do not rubber-stamp weak work"*（不要草率通过低质量工作）
|
||
- *"You must understand findings before directing follow-up work"*（在指导后续工作前必须理解发现）
|
||
|
||
### 7.2 子智能体启动流程
|
||
|
||
`runAgent.ts`（973 行）是子智能体的核心启动器：
|
||
|
||
1. 生成唯一 `AgentId`
|
||
2. 创建独立的 `FileStateCache`
|
||
3. 通过 `createSubagentContext()` fork 父级的 `ToolUseContext`
|
||
4. 初始化智能体专属 MCP 服务器（来自 frontmatter）
|
||
5. 运行独立的 `query()` 流式循环
|
||
6. 注册 Perfetto tracing（性能追踪）
|
||
7. 写入智能体元数据和 sidechain transcript
|
||
|
||
### 7.3 任务类型
|
||
|
||
```mermaid
|
||
classDiagram
|
||
class TaskType {
|
||
<<enumeration>>
|
||
local_bash
|
||
local_agent
|
||
remote_agent
|
||
in_process_teammate
|
||
local_workflow
|
||
monitor_mcp
|
||
dream
|
||
}
|
||
|
||
class TaskStatus {
|
||
<<enumeration>>
|
||
pending
|
||
running
|
||
completed
|
||
failed
|
||
killed
|
||
}
|
||
|
||
class LocalAgentTask
|
||
class InProcessTeammateTask
|
||
class RemoteAgentTask
|
||
class LocalShellTask
|
||
class DreamTask
|
||
|
||
TaskType <-- LocalAgentTask
|
||
TaskType <-- InProcessTeammateTask
|
||
TaskType <-- RemoteAgentTask
|
||
TaskType <-- LocalShellTask
|
||
TaskType <-- DreamTask
|
||
```
|
||
|
||
---
|
||
|
||
## 八、MCP（Model Context Protocol）集成
|
||
|
||
Claude Code 既是 MCP **客户端**（连接外部 MCP 服务器），也可以作为 MCP **服务器**运行。
|
||
|
||
### 8.1 支持的传输类型
|
||
|
||
| 传输方式 | 配置类型 | 说明 |
|
||
|----------|---------|------|
|
||
| `stdio` | `McpStdioServerConfig` | 标准进程通信 |
|
||
| `sse` | `McpSSEServerConfig` | Server-Sent Events |
|
||
| `sse-ide` | — | IDE 专用 SSE |
|
||
| `http` | `McpHTTPServerConfig` | HTTP 直连 |
|
||
| `ws` | `McpWebSocketServerConfig` | WebSocket |
|
||
| `sdk` | `McpSdkServerConfig` | SDK 内嵌 |
|
||
|
||
### 8.2 MCP 连接状态机
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Pending: 初始化
|
||
Pending --> Connected: 连接成功
|
||
Pending --> Failed: 连接失败
|
||
Pending --> NeedsAuth: 需要认证
|
||
NeedsAuth --> Connected: OAuth 完成
|
||
Connected --> Failed: 断开连接
|
||
Connected --> Disabled: 用户禁用
|
||
Failed --> Pending: 重连
|
||
```
|
||
|
||
`mcp/client.ts`（3,348 行）是最大的 MCP 相关文件，负责连接管理、工具发现、资源预取和认证流程（支持 OAuth 和 XAA 跨应用访问）。
|
||
|
||
---
|
||
|
||
## 九、记忆系统
|
||
|
||
```mermaid
|
||
graph LR
|
||
MEMORY_MD["MEMORY.md<br/>记忆索引<br/>(≤200 行 / 25KB)"] --> NOTE1["user_role.md"]
|
||
MEMORY_MD --> NOTE2["feedback_testing.md"]
|
||
MEMORY_MD --> NOTE3["project_auth.md"]
|
||
|
||
SYSTEM_PROMPT["系统提示词"] --> MEMORY_MD
|
||
SYSTEM_PROMPT --> TYPES["记忆类型指令"]
|
||
SYSTEM_PROMPT --> RULES["存取规则"]
|
||
|
||
NOTE1 --> SEMANTIC["语义搜索<br/>findRelevantMemories()"]
|
||
NOTE2 --> SEMANTIC
|
||
NOTE3 --> SEMANTIC
|
||
SEMANTIC --> INJECT["注入上下文"]
|
||
```
|
||
|
||
记忆系统（`memdir/`，9 个文件）采用**文件驱动**的设计：
|
||
|
||
- `MEMORY.md` 作为入口索引文件，限制 200 行 / 25KB，注入到系统提示词中
|
||
- 每条记忆是独立的 Markdown 文件，带有 frontmatter（name、description、type）
|
||
- 支持语义搜索（`findRelevantMemories()`）
|
||
- 记忆老化/淘汰机制（`memoryAge.ts`）
|
||
- 团队共享记忆支持（`teamMemPaths.ts`，TEAMMEM 特性开关后）
|
||
|
||
---
|
||
|
||
## 十、终端渲染引擎
|
||
|
||
Claude Code 使用**自研的 Ink 分支**（非 npm 上的 Ink 库），基于 React + Yoga Layout 实现终端 UI。
|
||
|
||
```
|
||
ink/
|
||
├── root.ts — render() / createRoot() 入口
|
||
├── dom.ts — 虚拟 DOM 实现
|
||
├── frame.ts — 渲染帧管理，防闪烁
|
||
├── focus.ts — 键盘焦点管理
|
||
├── components/
|
||
│ ├── App.tsx — 根组件
|
||
│ ├── Box.tsx — 布局容器
|
||
│ ├── Text.tsx — 文本组件
|
||
│ ├── ScrollBox.tsx — 滚动区域
|
||
│ └── AlternateScreen.tsx — 全屏覆盖
|
||
├── events/ — 自定义事件系统
|
||
├── hooks/ — use-input, use-app, use-animation-frame 等
|
||
├── termio/ — 原始终端 I/O
|
||
└── Ansi.tsx — ANSI 转义码渲染组件
|
||
```
|
||
|
||
据泄漏分析文章指出，其终端渲染使用了 `Int32Array` 支持的 ASCII 字符池和位掩码编码的样式元数据，声称"在 token 流式传输期间将 `stringWidth` 调用减少约 50 倍"。
|
||
|
||
---
|
||
|
||
## 十一、系统提示词构建
|
||
|
||
系统提示词是分段动态组装的，带有缓存边界标记：
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph Static["静态段（全局可缓存 scope='global'）"]
|
||
INTRO["getSimpleIntroSection()<br/>智能体身份 + 安全指令"]
|
||
SYSTEM["getSimpleSystemSection()<br/>工具使用 + 权限模式"]
|
||
TASKS_SEC["getSimpleDoingTasksSection()<br/>软件工程行为规范"]
|
||
ACTIONS["getActionsSection()<br/>操作可逆性策略"]
|
||
TOOL_GUIDE["getUsingYourToolsSection()<br/>工具使用指南"]
|
||
end
|
||
|
||
BOUNDARY["═══ SYSTEM_PROMPT_DYNAMIC_BOUNDARY ═══"]
|
||
|
||
subgraph Dynamic["动态段（用户/会话级，不跨组织缓存）"]
|
||
HOOKS_SEC["getHooksSection()<br/>用户钩子指令"]
|
||
UNDERCOVER["Undercover 指令<br/>(ant-only)"]
|
||
MEMORY["loadMemoryPrompt()<br/>记忆内容"]
|
||
LANG["语言偏好"]
|
||
CONTEXT["getUserContext()<br/>Git 状态 / CLAUDE.md / 平台信息"]
|
||
MCP_INST["MCP 指令"]
|
||
end
|
||
|
||
Static --> BOUNDARY
|
||
BOUNDARY --> Dynamic
|
||
```
|
||
|
||
这种设计让静态段可以跨会话缓存（通过 Anthropic API 的 `cache_control` 参数），而动态段每次重新构建。
|
||
|
||
---
|
||
|
||
## 十二、隐藏特性与彩蛋
|
||
|
||
### 12.1 反蒸馏机制（Anti-Distillation）
|
||
|
||
```typescript
|
||
// services/api/claude.ts (301-313)
|
||
if (
|
||
feature('ANTI_DISTILLATION_CC')
|
||
? process.env.CLAUDE_CODE_ENTRYPOINT === 'cli' &&
|
||
shouldIncludeFirstPartyOnlyBetas() &&
|
||
getFeatureValue_CACHED_MAY_BE_STALE(
|
||
'tengu_anti_distill_fake_tool_injection', false)
|
||
: false
|
||
) {
|
||
result.anti_distillation = ['fake_tools']
|
||
}
|
||
```
|
||
|
||
当启用时，向 API 请求注入 `anti_distillation: ['fake_tools']`，服务端会在工具调用中混入虚假工具响应。目的：如果竞争对手录制 Claude Code 的 API 流量来训练模型，虚假工具数据会污染训练集。
|
||
|
||
**绕过分析**：MITM 代理可在请求到达 API 前剥离该字段；设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 环境变量可禁用；第三方 SDK 入口完全绕过。正如分析者所言："真正的保护可能是法律而非技术"。
|
||
|
||
### 12.2 伪装模式（Undercover Mode）
|
||
|
||
`utils/undercover.ts` — Anthropic 内部员工在外部开源仓库工作时自动启用：
|
||
|
||
- 禁止提及内部代码名（Capybara、Tengu 等）
|
||
- 隐藏内部 Slack 频道和仓库名称
|
||
- 删除所有 "Co-Authored-By" 标识
|
||
- 不暴露未发布的模型版本号
|
||
|
||
**关键限制**：**没有强制关闭开关**。注释明确写道：*"There is NO force-OFF. This guards against model codename leaks."* 这是一扇单向门。
|
||
|
||
### 12.3 挫折感检测
|
||
|
||
```typescript
|
||
// utils/userPromptKeywords.ts
|
||
const negativePattern =
|
||
/\b(wtf|wth|ffs|omfg|shit(ty|tiest)?|dumbass|horrible|awful|
|
||
piss(ed|ing)? off|piece of (shit|crap|junk)|what the (fuck|hell)|
|
||
fucking? (broken|useless|terrible|awful|horrible)|fuck you|
|
||
screw (this|you)|so frustrating|this sucks|damn it)\b/
|
||
```
|
||
|
||
仅在 Anthropic 内部版本中启用（外部构建通过死代码消除移除）。当检测到用户情绪消极时，弹出 transcript 分享提示，方便内部员工快速提交反馈。选用正则而非 LLM 的原因：比模型推理调用更快更便宜。
|
||
|
||
### 12.4 KAIROS — 自主守护智能体
|
||
|
||
**KAIROS**（古希腊语"恰当的时机"）是一个被提及 150+ 次的特性开关，代表着一个全新的交互范式——**始终在线的后台智能体**。
|
||
|
||
核心能力：
|
||
- `/dream` 技能 — "夜间记忆蒸馏"
|
||
- `autoDream` 守护进程 — 用户空闲时自动进行记忆整合
|
||
- GitHub webhook 订阅 — 监听仓库事件
|
||
- Cron 定时任务 — 每 5 分钟计划刷新
|
||
- 推送通知 — 主动通知用户
|
||
|
||
**autoDream 触发条件**：
|
||
1. 距离上次整合 ≥ 24 小时
|
||
2. 至少 5 个新会话
|
||
3. 进程锁（同一时间只有一个进程执行整合）
|
||
|
||
### 12.5 Buddy 伴侣系统（愚人节彩蛋）
|
||
|
||
```
|
||
buddy/
|
||
├── companion.ts — Mulberry32 PRNG 确定性生成
|
||
├── types.ts — 物种、稀有度、属性定义
|
||
├── CompanionSprite.tsx — 500ms 刷新的终端动画精灵
|
||
├── sprites.ts — ASCII 艺术帧
|
||
├── prompt.ts — 系统提示词注入
|
||
└── useBuddyNotification.tsx — 预告逻辑
|
||
```
|
||
|
||
一个 Tamagotchi 风格的虚拟宠物系统：
|
||
|
||
- **18 种物种**：鸭子、鹅、blob、猫、龙、章鱼、猫头鹰、企鹅、海龟、蜗牛、幽灵、美西螈、水豚、仙人掌、机器人、兔子、蘑菇、胖墩。物种名用十六进制字符数组编码，避免触发内部代码名扫描器
|
||
- **稀有度**：普通(60%)、非凡(25%)、稀有(10%)、史诗(4%)、传说(1%)
|
||
- **RPG 属性**：DEBUGGING、PATIENCE、CHAOS、WISDOM、SNARK
|
||
- **防篡改**：骨骼数据（物种、稀有度、闪光）从 `hash(userId)` 确定性生成，不存储在配置中，无法伪造传说级
|
||
- **活跃窗口**：2026 年 4 月 1-7 日（跨时区滚动上线）
|
||
|
||
---
|
||
|
||
## 十三、Bash 安全检查
|
||
|
||
`tools/BashTool/bashSecurity.ts` 实现了 **23 项编号安全检查**：
|
||
|
||
| 检查项 | 防御内容 |
|
||
|--------|---------|
|
||
| 命令替换 | `$()`、`${}`、进程替换 `<()`、`>()` |
|
||
| Zsh 危险内置 | `zmodload`、`emulate`、`sysopen`、`ztcp`、`zsocket`、`zf_rm` 等 18 个 |
|
||
| Zsh 等号展开 | `=curl` 绕过 curl 权限检查 |
|
||
| Unicode 攻击 | 零宽空格注入、Unicode 空白字符 |
|
||
| IFS 注入 | 空字节 IFS 注入 |
|
||
| Shell 元字符 | 混淆标志、花括号展开、中间单词哈希 |
|
||
| 控制字符 | 不可见控制字符注入 |
|
||
| 注释/引号错位 | 注释与引号边界不对齐攻击 |
|
||
| PowerShell | PowerShell 语法检测 |
|
||
| HackerOne 发现 | 格式错误 token 绕过（安全审计中发现） |
|
||
|
||
每次触发的检查都会记录 `tengu_bash_security_check_triggered` 事件（带数字 ID），用于安全监控和统计。
|
||
|
||
---
|
||
|
||
## 十四、Prompt 缓存经济学
|
||
|
||
`services/api/promptCacheBreakDetection.ts` 追踪 **12+ 个缓存破坏维度**：
|
||
|
||
```
|
||
系统提示词哈希 | 工具 Schema 哈希 | cache_control 哈希
|
||
单工具 Schema 变更 | 模型切换 | 快速模式
|
||
全局缓存策略 | Beta 头部 | effort 值
|
||
Auto 模式状态 | 超限状态 | 微压缩状态
|
||
```
|
||
|
||
当检测到缓存破坏（>5% 缓存读取 token 下降 且 >2,000 绝对 token 下降）时：
|
||
- 触发 `tengu_prompt_cache_break` 分析事件
|
||
- 写入 diff 文件到 `~/.claude/tmp/cache-break-*.diff`
|
||
- 区分服务端破坏 vs TTL 过期
|
||
|
||
正如源码注释所言：*"在按 token 付费时，缓存失效不再是计算机科学笑话，而是会计问题。"*
|
||
|
||
---
|
||
|
||
## 十五、自动压缩与 250K API 调用浪费
|
||
|
||
`services/compact/autoCompact.ts` 中有一段引人注目的注释：
|
||
|
||
> 2026-03-10：BQ 分析显示 1,279 个会话在单次会话中有 50+ 连续自动压缩失败（最高达 3,272 次），全球每日浪费约 250,000 次 API 调用。
|
||
|
||
修复方案：**三行代码**。
|
||
|
||
```typescript
|
||
const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3
|
||
```
|
||
|
||
添加一个断路器，连续失败 3 次后停止重试。
|
||
|
||
自动压缩参数：
|
||
- 缓冲区：13,000 tokens（`AUTOCOMPACT_BUFFER_TOKENS`）
|
||
- 警告阈值：上下文窗口 - 20,000 tokens
|
||
- 摘要输出预留：20,000 tokens（基于 p99.99 实际摘要为 17,387 tokens）
|
||
|
||
---
|
||
|
||
## 十六、IDE 桥接（Bridge）
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph IDE["IDE 端"]
|
||
VSCODE["VS Code 扩展"]
|
||
JETBRAINS["JetBrains 插件"]
|
||
end
|
||
|
||
subgraph Bridge["桥接层 (27 个文件)"]
|
||
BRIDGE_MAIN["bridgeMain.ts<br/>2,999 行<br/>CCR WebSocket 服务器"]
|
||
REPL_BRIDGE["replBridge.ts<br/>2,406 行<br/>REPL 远程模式"]
|
||
end
|
||
|
||
subgraph Cloud["claude.ai"]
|
||
CCR["Claude Code Remote"]
|
||
end
|
||
|
||
subgraph Local["本地 CLI"]
|
||
CLAUDE["claude 进程"]
|
||
end
|
||
|
||
VSCODE <-->|JWT 认证| BRIDGE_MAIN
|
||
JETBRAINS <-->|JWT 认证| BRIDGE_MAIN
|
||
BRIDGE_MAIN <-->|WebSocket| CCR
|
||
REPL_BRIDGE <-->|WebSocket| CCR
|
||
BRIDGE_MAIN --> CLAUDE
|
||
REPL_BRIDGE --> CLAUDE
|
||
```
|
||
|
||
桥接系统支持：
|
||
- WebSocket 双向通信
|
||
- JWT 认证 + Token 刷新调度
|
||
- 指数退避重连
|
||
- 可信设备 Token 管理
|
||
- 容量感知唤醒（`capacityWake.ts`）
|
||
- 消息流控门（`flushGate.ts`）
|
||
|
||
---
|
||
|
||
## 十七、构建时特性开关系统
|
||
|
||
Claude Code 最精妙的设计之一是其构建时特性开关系统：
|
||
|
||
```typescript
|
||
// 使用 bun:bundle 的 feature() 函数
|
||
if (feature('KAIROS')) {
|
||
// 此代码在外部构建中被完整删除
|
||
loadKairosModule()
|
||
}
|
||
|
||
// 用户类型检查也会被常量折叠
|
||
if ("external" === 'ant') {
|
||
// 外部构建：编译为 if (false) → 死代码消除
|
||
loadInternalOnlyFeature()
|
||
}
|
||
```
|
||
|
||
**已知特性开关**（44 个，部分列表）：
|
||
|
||
| 开关名 | 功能 |
|
||
|--------|------|
|
||
| `KAIROS` / `PROACTIVE` | 自主守护智能体 |
|
||
| `ANTI_DISTILLATION_CC` | 反蒸馏保护 |
|
||
| `COORDINATOR_MODE` | 多智能体协调 |
|
||
| `BRIDGE_MODE` | IDE 桥接 |
|
||
| `DAEMON` | 后台守护进程 |
|
||
| `VOICE_MODE` | 语音输入 |
|
||
| `BUDDY` | 伴侣系统 |
|
||
| `HISTORY_SNIP` | 历史裁剪 |
|
||
| `WORKFLOW_SCRIPTS` | 工作流脚本 |
|
||
| `AGENT_TRIGGERS` | 智能体触发器 |
|
||
| `FORK_SUBAGENT` | 分叉子智能体 |
|
||
| `REACTIVE_COMPACT` | 响应式压缩 |
|
||
| `CONTEXT_COLLAPSE` | 上下文折叠 |
|
||
| `TRANSCRIPT_CLASSIFIER` | 转录分类器 |
|
||
| `NATIVE_CLIENT_ATTESTATION` | 原生客户端证明 |
|
||
| `TEMPLATES` | 模板系统 |
|
||
| `TORCH` / `ULTRAPLAN` / `UDS_INBOX` | 未知内部功能 |
|
||
|
||
---
|
||
|
||
## 十八、语音输入
|
||
|
||
`hooks/useVoice.ts` 实现了**按住说话**的语音输入：
|
||
|
||
- 使用 Anthropic 的 `voice_stream` STT 端点（Deepgram 后端）
|
||
- macOS 原生音频或 SoX 录制
|
||
- WebSocket 连接到 `conversation_engine` 端点
|
||
- 支持多语言（BCP-47 编码，从系统 locale 自动检测）
|
||
- "Keyterms" 注入提升识别准确度
|
||
- 5 次快速按键激活阈值（防止正常打字误触发）
|
||
- 通过 `VOICE_MODE` 构建开关完整移除
|
||
|
||
---
|
||
|
||
## 十九、关键架构模式总结
|
||
|
||
### 19.1 流式优先（Streaming-First）
|
||
|
||
从 `submitMessage()` 到 `query()` 到 `queryModelWithStreaming()`，整个链路都是 `AsyncGenerator<SDKMessage>`。工具执行期间通过 `onProgress` 回调发出进度消息。
|
||
|
||
### 19.2 依赖注入测试
|
||
|
||
`QueryDeps` 接口注入 `callModel`、`microcompact`、`autocompact`、`uuid`，避免测试中使用 `spyOn`。
|
||
|
||
### 19.3 上下文穿透
|
||
|
||
`ToolUseContext` 是贯穿整个工具执行链路的"胖上下文"对象。子智能体通过 `createSubagentContext()` 获得 fork 的副本。
|
||
|
||
### 19.4 双层特性门控
|
||
|
||
- **构建时**：`feature()` 从 `bun:bundle` 常量折叠，死代码消除
|
||
- **运行时**：GrowthBook 远程开关（`tengu_*`），支持灰度发布和 A/B 测试
|
||
|
||
### 19.5 分叉子智能体
|
||
|
||
后台任务（autoDream、压缩、会话记忆、推测执行）都通过 `runForkedAgent()` 运行——隔离的子智能体，有自己的查询来源，防止递归并共享父级的缓存安全参数。
|
||
|
||
---
|
||
|
||
## 二十、代码质量观察
|
||
|
||
| 指标 | 数据 |
|
||
|------|------|
|
||
| 总代码量 | 512,664 行 TypeScript |
|
||
| 文件数 | 1,884 个 `.ts/.tsx` |
|
||
| 最大文件 | `cli/print.ts`（5,594 行，单函数 3,167 行，12 层嵌套） |
|
||
| 第二大文件 | `main.tsx`（4,683 行） |
|
||
| API 客户端 | `claude.ts`（3,419 行） |
|
||
| MCP 客户端 | `mcp/client.ts`（3,348 行） |
|
||
| 桥接主模块 | `bridgeMain.ts`（2,999 行） |
|
||
|
||
一些值得注意的代码风格：
|
||
- 偏好单文件大函数而非过度抽象（`print.ts` 是极端案例）
|
||
- 大量使用 `feature()` 门控保持外部构建精简
|
||
- 独创的 analytics 安全类型：`AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS`——防止开发者意外将文件路径或代码片段发送到分析系统
|
||
- `tengu_` 前缀统一所有实验名和事件名（Tengu 是内部代号，讽刺的是在 Undercover Mode 的注释中被列为"不应暴露的代码名"示例）
|
||
|
||
---
|
||
|
||
## 结语
|
||
|
||
Claude Code 的 512,664 行源码揭示了一个工程复杂度远超预期的系统。它不仅仅是一个"LLM 套壳"——从自研终端渲染引擎到 23 项 Bash 安全检查，从多智能体协调到 prompt 缓存经济学，每一个模块都体现了在真实生产环境中打磨 AI 编程工具的深度工程投入。
|
||
|
||
最具战略意义的发现不是源码本身（它可以被重构），而是那 44 个特性开关背后的产品路线图：KAIROS 自主守护智能体、语音输入、团队协作记忆……这些代表着 Anthropic 对 AI 编程工具未来形态的判断。而这种战略意外，无法被 DMCA 撤回。
|