vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,28 +1,30 @@
|
||||
---
|
||||
title: "为什么写这份白皮书 - Claude Code 逆向工程分析"
|
||||
description: "对 Anthropic 官方 Claude Code CLI 的逆向工程分析白皮书。通过反编译 TypeScript 单文件 bundle，深入解析运行时行为与源码结构。"
|
||||
keywords: ["Claude Code", "逆向工程", "白皮书", "反编译", "TypeScript"]
|
||||
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 运行时执行，但意味着我们的分析基于运行时行为 + 残留源码结构，而非原始源码。
|
||||
|
||||
**这不是：**
|
||||
- 官方文档或使用教程
|
||||
- API 参考手册
|
||||
- Claude Code 的功能推销
|
||||
> [!warning] 边界声明
|
||||
> **这不是**官方文档、使用教程或 API 参考手册，也不是 Claude Code 的功能推销。
|
||||
>
|
||||
> **这是一个**生产级 agentic system 的架构解构——每个设计决策背后的"为什么"，以及可复用的工程模式：agentic loop、工具抽象、上下文工程、安全纵深防御。
|
||||
|
||||
**这是：**
|
||||
- 一个生产级 agentic system 的架构解构
|
||||
- 每个设计决策背后的"为什么"
|
||||
- 可复用的工程模式：agentic loop、工具抽象、上下文工程、安全纵深防御
|
||||
### 逆向过程中最精妙的设计决策
|
||||
|
||||
## 逆向过程中最精妙的设计决策
|
||||
|
||||
### 1. Agentic Loop 的自愈能力
|
||||
#### 1. Agentic Loop 的自愈能力
|
||||
|
||||
`src/query.ts` 实现的核心循环不是简单的"发请求→收响应"。它是一个**自愈的状态机**：
|
||||
|
||||
@@ -31,9 +33,10 @@ keywords: ["Claude Code", "逆向工程", "白皮书", "反编译", "TypeScript"
|
||||
- 对话过长触发 compaction → 压缩历史后无缝继续
|
||||
- 用户中断 → 生成 `UserInterruptionMessage` 让 AI 理解发生了什么
|
||||
|
||||
这不是"if-else 堆叠"，而是让 AI 自己根据上下文决定下一步——即使发生了意外。
|
||||
> [!tip] 设计洞察
|
||||
> 这不是"if-else 堆叠"，而是让 AI 自己根据上下文决定下一步——即使发生了意外。自愈的本质是把异常处理的决策权交给了 AI 本身。
|
||||
|
||||
### 2. 上下文工程的分层策略
|
||||
#### 2. 上下文工程的分层策略
|
||||
|
||||
AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉：
|
||||
|
||||
@@ -47,16 +50,17 @@ AI 没有真正的"记忆"，Claude Code 通过精心分层营造了这个幻觉
|
||||
|
||||
`src/context.ts` 组装 System Prompt 时的策略是：**不变内容在前、变化内容在后**——这利用了 API 的缓存机制，前缀不变时可以复用缓存 token。
|
||||
|
||||
### 3. 工具系统的权限双轨制
|
||||
#### 3. 工具系统的权限双轨制
|
||||
|
||||
`packages/builtin-tools/src/tools/BashTool/shouldUseSandbox.ts` 展示了一个精巧的双重安全模型：
|
||||
|
||||
- **应用层**：权限规则决定"能不能执行"（白名单/黑名单/用户确认）
|
||||
- **OS 层**：沙箱决定"执行时能做什么"（文件系统/网络/进程隔离）
|
||||
|
||||
两层的信任假设不同：应用层信任用户配置，OS 层不信任任何东西。即使 AI 绕过了应用层权限（理论上不可能，但纵深防御），OS 层沙箱仍然限制实际危害。
|
||||
> [!warning] 纵深防御
|
||||
> 两层的信任假设不同：应用层信任用户配置，OS 层不信任任何东西。即使 AI 绕过了应用层权限（理论上不可能，但纵深防御），OS 层沙箱仍然限制实际危害。
|
||||
|
||||
### 4. Feature Flag 的全局开关
|
||||
#### 4. Feature Flag 的全局开关
|
||||
|
||||
`src/entrypoints/cli.tsx` 中一行代码决定了整个系统的行为：
|
||||
|
||||
@@ -68,7 +72,7 @@ const feature = (_name: string) => false;
|
||||
|
||||
这是一个**渐进式发布架构**：同一个代码库，通过 feature flag 控制功能可见性，而不需要维护多个分支。
|
||||
|
||||
### 5. Compaction 的分档策略
|
||||
#### 5. Compaction 的分档策略
|
||||
|
||||
`src/services/compact/` 实现了三种压缩策略：
|
||||
|
||||
@@ -76,46 +80,47 @@ const feature = (_name: string) => false;
|
||||
- **Auto-compact**：对话 token 接近上限时，自动压缩历史
|
||||
- **Reactive-compact**：API 返回 token 超限错误时，紧急压缩后重试
|
||||
|
||||
这不是简单的"砍掉旧消息"——而是用 AI 自身来总结之前的对话，保留语义信息。压缩后插入一条 `TombstoneMessage` 标记边界。
|
||||
> [!tip] 语义保留
|
||||
> 这不是简单的"砍掉旧消息"——而是用 AI 自身来总结之前的对话，保留语义信息。压缩后插入一条 `TombstoneMessage` 标记边界。
|
||||
|
||||
## 阅读路线图
|
||||
### 阅读路线图
|
||||
|
||||
推荐的阅读顺序，每章解决一个核心问题：
|
||||
|
||||
```
|
||||
什么是 Claude Code (你在读的) ← 建立直觉
|
||||
│
|
||||
├── 架构全景 ← 五层架构 + 数据流
|
||||
│
|
||||
├── 安全体系 ← 信任与控制
|
||||
│ ├── 权限模型 ← 应用层安全
|
||||
│ ├── 沙箱机制 ← OS 层安全
|
||||
│ └── Plan Mode ← 用户主导模式
|
||||
│
|
||||
├── 对话引擎 ← AI 如何思考
|
||||
│ ├── Agentic Loop ← 核心循环
|
||||
│ ├── 流式响应 ← 实时通信
|
||||
│ └── 多轮对话 ← 上下文管理
|
||||
│
|
||||
├── 上下文工程 ← 记忆与预算
|
||||
│ ├── System Prompt ← 上下文组装
|
||||
│ ├── Token 预算 ← 预算管理
|
||||
│ └── 项目记忆 ← 跨会话持久化
|
||||
│
|
||||
├── 工具系统 ← AI 的双手
|
||||
│ ├── 工具概览 ← 统一接口
|
||||
│ ├── Shell 执行 ← Bash 工具
|
||||
│ └── 搜索与导航 ← Glob/Grep
|
||||
│
|
||||
└── Agent 与扩展 ← 能力扩展
|
||||
├── 子 Agent ← 并行任务
|
||||
├── 自定义 Agent ← 用户定义
|
||||
└── MCP 协议 ← 外部工具接入
|
||||
```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]]
|
||||
|
||||
Reference in New Issue
Block a user