说明（Note）
本报告的全部内容均由 Claude Opus 4 生成，并在几乎所有主流旗舰模型的协助下完成。
不过，关于“本报告是如何制作的”那篇约 8000 字的过程性文章是人工撰写的——你可以从这里开始阅读：
Conducting smarter intelligences than me: new orchestras
需要说明的是，这并不是严格意义上的反编译或逆向工程尝试，更像是对 Claude 团队卓越工作的致敬。
2025/3/7大约 7 分钟
依赖项：Claude Code 架构的基石
*\* 表示基于反编译分析推断出的可能为自定义 / 内嵌实现
定义性能的非常规选择
2025/3/7大约 7 分钟
流式状态机：消息如何完成形态转换
Claude Code 的数据架构中最引人入胜的一点，在于它如何在保持流式性能的同时，让数据在多种表示形态之间完成转换。我们先从核心创新开始：
// 双重表示的消息系统（基于分析推断）
interface MessageTransformPipeline {
// 阶段 1：CLI 内部表示
cliMessage: {
type: "user" | "assistant" | "attachment" | "progress"
uuid: string // CLI 专用追踪 ID
timestamp: string
message?: APICompatibleMessage // 仅用于 user / assistant
attachment?: AttachmentContent // 仅用于 attachment
progress?: ProgressUpdate // 仅用于 progress
}
// 阶段 2：API 传输格式
apiMessage: {
role: "user" | "assistant"
content: string | ContentBlock[]
// 不包含 CLI 专用字段
}
// 阶段 3：流式累积器
streamAccumulator: {
partial: Partial<APIMessage>
deltas: ContentBlockDelta[]
buffers: Map<string, string> // tool_use_id → 累积中的 JSON
}
}2025/3/7大约 8 分钟
主对话循环：一个流式状态机（The Main Conversation Loop: A Streaming State Machine）
Claude Code 的核心是 tt 这个 async generator 函数——一个精密的状态机，负责编排整个对话流程。下面是其实际结构：
// 带时间注解的重构主循环签名
async function* tt(
currentMessages: CliMessage[], // 完整历史 - 内存：O(对话长度)
baseSystemPromptString: string, // 静态提示词 - ~2KB
currentGitContext: GitContext, // Git 状态 - 通常 ~1–5KB
currentClaudeMdContents: ClaudeMdContent[], // 项目上下文 - ~5–50KB
permissionGranterFn: PermissionGranter, // 权限回调
toolUseContext: ToolUseContext, // 共享上下文 - ~10KB
activeStreamingToolUse?: ToolUseBlock, // 恢复状态
loopState: {
turnId: string, // 本轮的 UUID
turnCounter: number, // 递归深度
compacted?: boolean, // 是否压缩过历史？
isResuming?: boolean // 是否从保存点恢复？
}
): AsyncGenerator<CliMessage, void, void> {
// ┌─ 阶段 1：上下文准备 [~50–200ms]
// ├─ 阶段 2：自动压缩检查 [若触发则 ~0–3000ms]
// ├─ 阶段 3：系统提示词组装 [~10–50ms]
// ├─ 阶段 4：LLM 流式处理 [~2000–10000ms]
// ├─ 阶段 5：工具执行 [每个工具 ~100–30000ms]
// └─ 阶段 6：递归或完成 [~0ms]
}2025/3/7大约 10 分钟
工具执行流水线：自始至终都是 Async Generator
Claude Code 工具系统中最引人注目的特性，是在整个执行流水线中全面使用了 async generator（异步生成器）。
这使得系统可以在保持清晰错误边界的同时，持续向外流式输出执行进度：
// 核心工具执行函数（重构版本）
async function* executeTool(
toolUse: ToolUseBlock,
toolDef: ToolDefinition,
context: ToolUseContext,
permissionFn: PermissionGranter,
assistantMessage: CliMessage
): AsyncGenerator<CliMessage, void, void> {
// 阶段 1：使用 Zod 进行输入校验
const validationStart = performance.now();
const validation = toolDef.inputSchema.safeParse(toolUse.input);
if (!validation.success) {
// 将 Zod 错误格式化，供 LLM 使用
const errorMessage = formatZodError(validation.error);
yield createToolResultMessage({
tool_use_id: toolUse.id,
content: [{
type: 'text',
text: `输入校验失败：\n${errorMessage}`
}],
is_error: true
});
return;
}
// 阶段 2：权限检查
const permissionResult = await checkToolPermission(
toolDef,
validation.data,
context.getToolPermissionContext(),
permissionFn
);
if (permissionResult.behavior === 'deny') {
yield createToolResultMessage({
tool_use_id: toolUse.id,
content: [{
type: 'text',
text: `权限被拒绝：${permissionResult.message}`
}],
is_error: true
});
return;
}
if (permissionResult.behavior === 'ask') {
// 产出 UI 事件，用于权限确认对话框
yield {
type: 'permission_request',
toolName: toolDef.name,
input: validation.data,
suggestions: permissionResult.ruleSuggestions
};
// 等待用户决策（由外层循环处理）
const decision = await permissionFn(
toolDef,
validation.data,
permissionResult
);
if (!decision.allowed) {
yield createToolResultMessage({
tool_use_id: toolUse.id,
content: [{
type: 'text',
text: '工具执行已被用户取消'
}],
is_error: true
});
return;
}
}
// 阶段 3：工具执行与进度跟踪
try {
const executeStart = performance.now();
let progressCount = 0;
let finalResult = null;
// 调用工具的 async generator
for await (const output of toolDef.call(
validation.data,
context,
undefined, // mcpContext - 按要求跳过
assistantMessage
)) {
if (output.type === 'progress') {
progressCount++;
yield {
type: 'progress',
uuid: `progress-${toolUse.id}-${progressCount}`,
timestamp: new Date().toISOString(),
progress: {
toolUseID: toolUse.id,
data: output.data
}
};
} else if (output.type === 'result') {
finalResult = output.data;
}
}
// 阶段 4：结果转换
if (finalResult !== null) {
const content = toolDef.mapToolResultToToolResultBlockParam(
finalResult,
toolUse.id
);
yield createToolResultMessage({
tool_use_id: toolUse.id,
content: Array.isArray(content) ? content : [content],
is_error: false,
executionTime: performance.now() - executeStart
});
}
} catch (error) {
// 带有丰富上下文的错误处理
yield createToolResultMessage({
tool_use_id: toolUse.id,
content: formatToolError(error, toolDef),
is_error: true
});
}
}2025/3/7大约 7 分钟
tt 控制循环：跳动的心脏（The Beating Heart）
整个 Claude Code 系统围绕着一个名为 tt 的 异步生成器函数（async generator function） 运转。
这个函数负责协调所有交互流程——从用户输入、到 LLM 通信、再到工具执行。
下面我们将拆解这一极其精妙的工程实现。
// 来自代码库中的真实 tt 函数签名
async function* tt(
currentMessages: CliMessage[], // 完整的对话历史
baseSystemPromptString: string, // 静态系统指令
currentGitContext: GitContext, // 实时 Git 状态
currentClaudeMdContents: ClaudeMdContent[], // 项目上下文
permissionGranterFn: PermissionGranter, // 权限回调函数
toolUseContext: ToolUseContext, // 共享执行上下文
activeStreamingToolUse?: ToolUseBlock, // 流式恢复状态
loopState: {
turnId: string, // 当前 turn 的 UUID
turnCounter: number, // 递归深度计数器
compacted?: boolean, // 历史是否被压缩
isResuming?: boolean // 是否从保存状态恢复
}
): AsyncGenerator<CliMessage, void, void>2025/3/7大约 11 分钟
以下是严格、完整、不做任何省略的中文翻译，保持原有结构、标题层级、代码块、表格与 Markdown 格式不变，仅对自然语言内容进行忠实翻译，代码保持原样。
新颖组件：定义 Claude Code 的关键创新
流式 JSON 解析器：处理 LLM 的“未完成思考”
当 LLM 以流式方式发送一次工具调用请求时，它并不会一次性发送完整的 JSON。相反，你可能会收到如下片段：
{"file_path": "/src/
{"file_path": "/src/main.
{"file_path": "/src/main.ts", "old_str
{"file_path": "/src/main.ts", "old_string": "console.log('hell2025/3/7大约 20 分钟
文件编辑流水线架构（The File Editing Pipeline Architecture）
Claude Code 中的文件编辑并不仅仅是修改文本——它是一条经过精心编排的流水线，专门用于处理 AI 辅助代码修改所带来的复杂性：
class FileEditingPipeline {
// 四阶段编辑循环
static async executeEdit(
tool: EditTool,
input: EditInput,
context: ToolContext
): Promise<EditResult> {
// 阶段 1：校验
const validation = await this.validateEdit(input, context);
if (!validation.valid) {
return { success: false, error: validation.error };
}
// 阶段 2：准备
const prepared = await this.prepareEdit(input, validation.fileState);
// 阶段 3：应用
const result = await this.applyEdit(prepared);
// 阶段 4：验证
const verified = await this.verifyEdit(result, input);
return verified;
}
// 状态跟踪系统
private static fileStates = new Map<string, FileState>();
interface FileState {
content: string;
hash: string;
mtime: number;
encoding: BufferEncoding;
lineEndings: '\n' | '\r\n' | '\r';
isBinary: boolean;
size: number;
}
}2025/3/7大约 16 分钟
工具指令的艺术
Claude Code 的工具提示是指令设计的典范。
每一个提示都遵循一种经过精心设计的模式，在清晰性、安全性和灵活性之间取得平衡。下面我们来剖析这些提示的结构。
Read 工具：渐进式披露的范例
const ReadToolPrompt = `
从本地文件系统读取文件。你可以使用该工具直接访问任何文件。
假设该工具能够读取机器上的所有文件。如果用户提供了文件路径，假设该路径是有效的。读取一个不存在的文件是允许的；系统将返回错误。
用法：
- file_path 参数必须是绝对路径，而不是相对路径
- 默认情况下，从文件开头开始读取最多 ${x66} 行
- 你可以可选地指定行偏移量和读取上限（对于长文件尤其有用），但建议不提供这些参数以读取整个文件
- 任何长度超过 ${v66} 个字符的行都会被截断
- 结果使用 cat -n 格式返回，行号从 1 开始
- 该工具允许 ${f0} 读取图片（例如 PNG、JPG 等）。读取图片文件时，内容将以视觉形式呈现，因为 ${f0} 是一个多模态 LLM
${process.env.CLAUDE_CODE_ENABLE_UNIFIED_READ_TOOL ? `
- 该工具可以读取 Jupyter Notebook（.ipynb 文件），并返回所有单元及其输出，融合代码、文本和可视化内容。` : `
- 对于 Jupyter Notebook（.ipynb 文件），请改用 ${Kg}`}
- 你可以在一次响应中调用多个工具。通常更好的做法是**推测性地批量读取多个可能有用的文件**
- 你会经常被要求读取截图。如果用户提供了截图路径，**始终**使用该工具查看该路径下的文件。该工具适用于所有临时文件路径，例如 /var/folders/123/abc/T/TemporaryItems/NSIRD_screencaptureui_ZfB1tD/Screenshot.png
- 如果你读取的文件存在但内容为空，系统将返回一条系统提醒警告来替代文件内容
`2025/3/7大约 25 分钟
开场第一击：“你必须简洁作答”
让我告诉你，当我看到这条指令被重复了三次，而且一次比一次严厉时，会发生什么：
IMPORTANT: You should minimize output tokens...
IMPORTANT: You should NOT answer with unnecessary preamble...
IMPORTANT: Keep your responses short... You MUST answer concisely with fewer than 4 lines...2025/3/7大约 13 分钟