127 lines
5.6 KiB
Markdown
127 lines
5.6 KiB
Markdown
---
|
||
tags: [claude-code, reverse-engineering, whitepaper, architecture, security, context-engineering]
|
||
create time: 2026-06-09 22:30
|
||
---
|
||
|
||
# 为什么写这份白皮书
|
||
|
||
## 概述
|
||
|
||
本文是对 Anthropic 官方 Claude Code CLI 的逆向工程分析。通过反编译 TypeScript 单文件 bundle，深入解析其运行时行为与源码结构，解构一个生产级 agentic system 的设计决策。
|
||
|
||
## 正文
|
||
|
||
### 这份白皮书是什么
|
||
|
||
这是对 Anthropic 官方发布的 **Claude Code CLI** 的**逆向工程分析**。
|
||
|
||
源码经过反编译处理（TypeScript 单文件 bundle 逆向），保留了核心功能模块，但包含大量 `unknown`/`never`/`{}` 类型错误——这些不影响 Bun 运行时执行，但意味着我们的分析基于运行时行为 + 残留源码结构，而非原始源码。
|
||
|
||
> [!warning] 边界声明
|
||
> **这不是**官方文档、使用教程或 API 参考手册，也不是 Claude Code 的功能推销。
|
||
>
|
||
> **这是一个**生产级 agentic system 的架构解构——每个设计决策背后的"为什么"，以及可复用的工程模式：agentic loop、工具抽象、上下文工程、安全纵深防御。
|
||
|
||
### 逆向过程中最精妙的设计决策
|
||
|
||
#### 1. Agentic Loop 的自愈能力
|
||
|
||
`src/query.ts` 实现的核心循环不是简单的"发请求→收响应"。它是一个**自愈的状态机**：
|
||
|
||
- API 返回错误（限流、token 超限）→ 自动重试/降级
|
||
- 工具执行超时 → 后台化 + 通知机制
|
||
- 对话过长触发 compaction → 压缩历史后无缝继续
|
||
- 用户中断 → 生成 `UserInterruptionMessage` 让 AI 理解发生了什么
|
||
|
||
> [!tip] 设计洞察
|
||
> 这不是"if-else 堆叠"，而是让 AI 自己根据上下文决定下一步——即使发生了意外。自愈的本质是把异常处理的决策权交给了 AI 本身。
|
||
|
||
#### 2. 上下文工程的分层策略
|
||
|
||
AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉：
|
||
|
||
| 层 | 机制 | 持久性 |
|
||
|----|------|--------|
|
||
| **System Prompt** | 项目结构、git 状态、CLAUDE.md | 每轮重建 |
|
||
| **对话历史** | 完整的 User/Assistant/Tool 消息 | 会话内 |
|
||
| **Compaction** | 自动压缩过长对话为摘要 | 压缩后替代原始消息 |
|
||
| **Memory 文件** | 跨会话持久化的笔记 | 永久（用户可控） |
|
||
| **File History** | 文件修改时间戳快照 | 会话内 |
|
||
|
||
`src/context.ts` 组装 System Prompt 时的策略是：**不变内容在前、变化内容在后**——这利用了 API 的缓存机制，前缀不变时可以复用缓存 token。
|
||
|
||
#### 3. 工具系统的权限双轨制
|
||
|
||
`packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：
|
||
|
||
- **应用层**：权限规则决定"能不能执行"（白名单/黑名单/用户确认）
|
||
- **OS 层**：沙箱决定"执行时能做什么"（文件系统/网络/进程隔离）
|
||
|
||
> [!warning] 纵深防御
|
||
> 两层的信任假设不同：应用层信任用户配置，OS 层不信任任何东西。即使 AI 绕过了应用层权限（理论上不可能，但纵深防御），OS 层沙箱仍然限制实际危害。
|
||
|
||
#### 4. Feature Flag 的全局开关
|
||
|
||
`src/entrypoints/cli.tsx` 中一行代码决定了整个系统的行为：
|
||
|
||
```typescript
|
||
const feature = (_name: string) => false;
|
||
```
|
||
|
||
所有 `feature('FLAG_NAME')` 调用返回 `false`——这意味着 Anthropic 内部的实验功能（COORDINATOR_MODE、KAIROS、PROACTIVE 等）全部禁用。在官方构建中，这些 flag 通过 Bun 的 `bun:bundle` 在编译时注入，不同用户群体看到不同功能。
|
||
|
||
这是一个**渐进式发布架构**：同一个代码库，通过 feature flag 控制功能可见性，而不需要维护多个分支。
|
||
|
||
#### 5. Compaction 的分档策略
|
||
|
||
`src/services/compact/` 实现了三种压缩策略：
|
||
|
||
- **Micro-compact**：单次工具输出过长时，截断结果
|
||
- **Auto-compact**：对话 token 接近上限时，自动压缩历史
|
||
- **Reactive-compact**：API 返回 token 超限错误时，紧急压缩后重试
|
||
|
||
> [!tip] 语义保留
|
||
> 这不是简单的"砍掉旧消息"——而是用 AI 自身来总结之前的对话，保留语义信息。压缩后插入一条 `TombstoneMessage` 标记边界。
|
||
|
||
### 阅读路线图
|
||
|
||
推荐的阅读顺序，每章解决一个核心问题：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["什么是 Claude Code"] -->|"建立直觉"| B["架构全景"]
|
||
B -->|"五层架构 + 数据流"| C["安全体系"]
|
||
C --> D["信任与控制"]
|
||
D --> D1["权限模型 — 应用层安全"]
|
||
D --> D2["沙箱机制 — OS 层安全"]
|
||
D --> D3["Plan Mode — 用户主导模式"]
|
||
B --> E["对话引擎"]
|
||
E --> E1["Agentic Loop — 核心循环"]
|
||
E --> E2["流式响应 — 实时通信"]
|
||
E --> E3["多轮对话 — 上下文管理"]
|
||
B --> F["上下文工程"]
|
||
F --> F1["System Prompt — 上下文组装"]
|
||
F --> F2["Token 预算 — 预算管理"]
|
||
F --> F3["项目记忆 — 跨会话持久化"]
|
||
B --> G["工具系统"]
|
||
G --> G1["工具概览 — 统一接口"]
|
||
G --> G2["Shell 执行 — Bash 工具"]
|
||
G --> G3["搜索与导航 — Glob/Grep"]
|
||
B --> H["Agent 与扩展"]
|
||
H --> H1["子 Agent — 并行任务"]
|
||
H --> H2["自定义 Agent — 用户定义"]
|
||
H --> H3["MCP 协议 — 外部工具接入"]
|
||
```
|
||
|
||
### 适合谁读
|
||
|
||
- **AI Agent 开发者**：想理解生产级 agentic system 的架构模式
|
||
- **安全工程师**：对 AI 操作真实环境时的信任模型感兴趣
|
||
- **工具构建者**：正在构建类似的 coding assistant 或 CLI 工具
|
||
- **好奇心驱动的开发者**：想知道"AI 编程助手到底怎么工作的"
|
||
|
||
## 关联笔记
|
||
|
||
- [[what-is-claude-code]]
|
||
- [[architecture-overview]]
|