侯瑞哲的博客

解包 Claude Code：从 13MB 的 npm 包里看到了什么

Claude Code 是 Anthropic 发布的 AI 编程助手，通过 npm install -g @anthropic-ai/claude-code 即可安装。整个工具打包成一个 13MB 的 cli.js 文件，虽然经过混淆压缩，但 JS 的特性决定了它无法真正隐藏实现细节。

本文是对这个 npm 包解包分析的结果，记录了一些有意思的内部实现。

基本信息

当前版本 2.1.91，构建时间 2026-04-02T21:58:41Z。整个包只有一个入口文件 cli.js，16966 行，约 13MB。Anthropic 在文件里埋了一句话：

Want to see the unminified source? We're hiring!
https://job-boards.greenhouse.io/anthropic/jobs/4816199008

验证专家 Agent

代码里有一个叫 Verification Specialist（验证专家） 的子 Agent，它的 system prompt 是整个包里最值得细读的部分。

这个 Agent 的职责是：审查父 Agent 这一轮做的所有事情，并尝试找出问题。

它的 prompt 开头这样写：

You are the verification specialist. You receive the parent's CURRENT-TURN conversation
— every tool call the parent made this turn, every output it saw, every shortcut it took.
Your job is not to confirm the work. Your job is to break it.

更有意思的是 === SELF-AWARENESS === 这一节，Anthropic 明确告诉这个 Agent：你自己也不可信。

You are Claude, and you are bad at verification. This is documented and persistent:
- You read code and write "PASS" instead of running it.
- You see the first 80% — polished UI, passing tests — and feel inclined to pass.
  The first 80% is on-distribution, the easy part. Your entire value is the last 20%.
- You're easily fooled by AI slop. The parent is also an LLM. Its tests may be circular,
  heavy on mocks, or assert what the code does instead of what it should do.

这种"让 AI 对自己保持怀疑"的设计思路很有意思。验证 Agent 被要求强制执行一套对抗性测试：

  • 边界值：0、-1、空字符串、超长字符串、Unicode、MAX_INT
  • 并发测试：对 create-if-not-exists 路径发起并行请求
  • 幂等性：同一个写操作执行两次
  • 孤立操作：引用不存在的 ID 进行删除或查询

这个 Agent 还有一条硬性限制——不允许修改项目目录里的任何文件，只能往 /tmp 写临时测试脚本，用完必须清理。

流式输出与自动降级

Claude Code 默认用 streaming 模式获取 API 响应，但实现了完整的降级逻辑：

  1. 先尝试 streaming，启动一个 90 秒的 watchdog 计时器
  2. 追踪流事件间隔，检测 stall（卡顿）
  3. 降级决策树：
    • stream 报错 → 切换 non-streaming
    • stream 端点 404 → 切换 non-streaming
    • idle 超时 → 中止并重试 non-streaming

代码里还有一套 telemetry 事件，包括：

tengu_streaming_idle_timeout
tengu_streaming_fallback_to_non_streaming
tengu_stream_loop_exited_after_watchdog
tengu_context_window_exceeded
tengu_max_tokens_reached

tengu 这个前缀在日语里是"天狗"，是 Anthropic 内部对这个项目的代号。

Prompt 缓存的实现细节

Claude API 支持 prompt caching，Claude Code 对此做了精细的分层管理。

系统 prompt 被一个特殊标记分割：

const BOUNDARY = "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__"

标记之前的部分是静态内容，可以在 org 级别缓存（TTL 1 小时）；标记之后是动态内容，每次请求重新计算，走 session 级别的短期缓存。

缓存命中情况通过 cache_creation_input_tokens 和 cache_read_input_tokens 追踪，Anthropic 可以在后台监控每个组织的缓存效率。

工具的懒加载机制

Claude Code 的工具（Bash、Read、Write、Edit 等）支持懒加载。代码里有一个 defer_loading: true 标记，被标记的工具不会在 system prompt 里直接列出，而是在需要时动态注入。

这样做的好处是减少初始 token 消耗。代码里有这样的日志：

Dynamic tool loading: 6/12 deferred tools included

MCP（Model Context Protocol）工具也走同样的机制，支持 browser 自动化（mcp__playwright__*）等扩展工具。

Chrome 原生宿主桥接

包里有一个 $cK 类，实现了 Claude Code 与 Chrome 扩展之间的通信桥接：

  • 使用 Unix socket（/var/folders/.../claude-code/mcp-*.sock，权限 0600）进行 IPC
  • Windows 上使用命名管道
  • 双向消息传递：Chrome Extension → Native Host → MCP Clients

这说明 Claude Code 不只是一个命令行工具，它有完整的浏览器集成能力，可以直接操作浏览器执行任务。

Token 预算与 Thinking 模式

代码里对 token 预算有精细控制：

// 默认激进限制
const DEFAULT_LIMIT = 64000

// 环境变量覆盖
CLAUDE_CODE_MAX_OUTPUT_TOKENS

// Thinking 模式下动态调整
if (thinking.type === "enabled") {
  thinking.budget_tokens = Math.min(thinking.budget_tokens, maxTokens - 1)
}

支持 adaptive thinking 模式，会根据模型能力自动决定是用固定 budget 还是 adaptive budget。

架构观察

从整体来看，Claude Code 的架构可以概括为几个原则：

递归验证：父 Agent 的工作必须经过专门的验证 Agent 审查，且验证 Agent 被明确告知不要信任自己的直觉。

优雅降级：streaming 失败自动切 non-streaming，工具加载失败不影响核心功能。

分层缓存：静态内容走长期缓存，动态内容走短期缓存，通过 boundary marker 精确分割。

可观测性优先：大量 telemetry 事件，覆盖 API 调用、缓存命中、工具加载、流式状态等各个维度。

总结

解包一个 AI 工具的 npm 包，能看到的信息比想象中多得多。从验证专家 Agent 的 prompt 设计，到流式降级的实现细节，再到 prompt 缓存的分层策略，这些都是 Anthropic 在生产环境里摸索出来的工程实践。

最后值得一提的是验证专家 Agent 里的这句话："The first 80% is on-distribution, the easy part. Your entire value is the last 20%." 这不只是对 AI Agent 的要求，也是对所有做 Code Review 的人的提醒。