wonder/cs-note

Fork 0

Files

T

wonder e92c0327d9 vault backup: 2026-06-09 23:15:17

2026-06-09 23:15:17 +08:00

5.6 KiB

Raw Blame History

tags, create time

为什么写这份白皮书

概述

本文是对 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 中一行代码决定了整个系统的行为：

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 标记边界。

阅读路线图

推荐的阅读顺序，每章解决一个核心问题：

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 编程助手到底怎么工作的"

5.6 KiB Raw Blame History Unescape Escape