Skip to content

README_CN.md

Latest commit

 

History

History
272 lines (200 loc) · 12.6 KB

README_CN.md

File metadata and controls

272 lines (200 loc) · 12.6 KB

Decode Claude Code

深度解剖 Anthropic AI 编程 Agent 的架构设计与实现原理

1,906 个源文件 · 515,029 行代码 · 从 npm source map 完整提取

GitHub stars License: MIT

English Version →

Claude Code 拥有 85k+ GitHub Stars，每天驱动数百万次编程会话。 但从你输入 prompt 到收到响应之间，内部到底发生了什么？

我们逐层拆解了所有细节 — 你不用再猜了。

这个项目是什么

2026 年 3 月 31 日，Anthropic 发布的 @anthropic-ai/claude-code@2.1.88 npm 包中包含了一个 59.8MB 的 source map 文件（cli.js.map）。这个文件内含完整的、未混淆的 TypeScript 源码 — 1,906 个文件，515,029 行代码。

本项目不是代码转储。它是一份结构化的、逐章节的架构分析，回答的是 Claude Code 怎么工作、为什么这样设计。

核心问题包括：

  • System Prompt 为什么用 __DYNAMIC_BOUNDARY__ 标记分割静态区和动态区？
  • 核心循环为什么只是 while(tool_call)，没有 DAG 也没有规划器？
  • 92% 的 Prompt Cache 命中率 是怎么做到的？
  • KAIROS、PROACTIVE、COORDINATOR_MODE 等 Feature Flag 揭示了哪些未发布功能？
  • 7,000+ 行 Bash 安全代码在防什么？

架构全景

  你的终端
       │
       ▼
  ┌─────────────────────────────────────────────┐
  │        Claude Code CLI  (Bun + React/Ink)    │
  │                                              │
  │  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
  │  │ System   │  │  Agent   │  │  权限      │  │
  │  │ Prompt   │  │  Loop    │  │  系统      │  │
  │  │ 组装     │  │ (while)  │  │ (5 种模式) │  │
  │  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
  │       │             │              │          │
  │  ┌────┴─────────────┴──────────────┴───────┐  │
  │  │        40+ 工具 · 90+ 斜杠命令           │  │
  │  │   Bash│Read│Write│Edit│Grep│Glob│Agent   │  │
  │  └────────────────────┬────────────────────┘  │
  │                       │                       │
  │  ┌────────────────────┴────────────────────┐  │
  │  │  上下文管理 (200K tokens)                 │  │
  │  │  75-92% 容量时自动压缩                    │  │
  │  └────────────────────┬────────────────────┘  │
  └───────────────────────┼───────────────────────┘
                          │
                          ▼
              Anthropic Messages API
             (Prompt Cache: 92% 命中率)

核心数据：

指标 数值
源文件数 1,906
代码行数 515,029
内置工具 40+
斜杠命令 90+
上下文窗口 200K tokens
Prompt Cache 命中率 92%
Bash 安全代码 7,000+ 行

目录

每章都是独立的深度分析。可以按顺序阅读，也可以跳到感兴趣的部分。

# 章节 核心问题 链接
00 全局架构概览 Claude Code 的整体设计哲学是什么？ 阅读 →
01 System Prompt 分层设计 为什么分静态区和动态区？怎么做到 92% 缓存命中？ 阅读 →
02 Agent Loop 核心循环 一次请求从输入到输出，内部发生了什么？ 阅读 →
03 工具系统架构 40+ 工具如何注册、调度、执行？ 阅读 →
04 权限安全模型 5 种权限模式怎么运作？Bash 命令如何做安全检查？ 阅读 →
05 上下文管理与压缩 200K 窗口不够用怎么办？自动压缩策略是什么？ 阅读 →
06 Prompt Cache 优化 怎样设计 prompt 才能最大化缓存命中？ 阅读 →
07 多 Agent 协作 子 Agent 怎么生成？Team 模式怎么并行？ 阅读 →
08 MCP 协议集成 如何通过 MCP 无限扩展工具能力？ 阅读 →
09 启动性能优化 并行预取、懒加载、死代码消除怎么配合？ 阅读 →
10 Feature Flag 体系 KAIROS、PROACTIVE 等隐藏功能揭秘 阅读 →
11 安全机制深度分析 命令注入防护、沙箱隔离、只读模式怎么实现？ 阅读 →

你在别处看不到的亮点

🔥 内部员工 vs 外部用户 — Anthropic 员工用的是不一样的 Claude 
// 外部用户版本：
"Go straight to the point. Try the simplest approach first."

// 内部用户版本 (USER_TYPE === 'ant')：
"Write user-facing text in flowing prose while eschewing fragments,
 excessive em dashes, symbols and notation..."
// + 数字化长度锚定："工具调用间 ≤25 词"
// + 主动反馈："发现用户的请求基于误解时，直接指出"

内部版更啰嗦、更有主见、会主动挑战用户假设。外部版简洁且顺从。

→ 完整分析见第 01 章

🔥 10.2% 缓存灾难 — 一个动态列表烧掉了数百万 token

Agent 列表嵌入在 AgentTool 的工具描述中。MCP 连接变化 → Agent 列表变化 → 工具 schema 变化 → 整个 prompt cache 失效。

这一个问题消耗了平台级 10.2% 的 cache 创建 token。

修复方案：将 Agent 列表移到消息附件（agent_listing_delta），从可缓存的 schema 中移除。

→ 完整分析见第 06 章

🔥 KAIROS — Claude Code 未发布的「助理模式」

隐藏在 KAIROS Feature Flag 后面，这个模式将 Claude Code 从被动工具变成主动助手：

  • 定时休眠和唤醒（SleepTool）
  • 向手机推送通知（PushNotificationTool）
  • 订阅 PR 变更（SubscribePRTool）
  • 向用户发送文件（SendUserFileTool）
  • 生成每日简报（BriefTool）

→ 完整分析见第 10 章

🔥 20 行代码省 65ms 的启动优化黑魔法 
// main.tsx 前 20 行，在所有其他 import 之前：
profileCheckpoint('main_tsx_entry');
startMdmRawRead();      // 启动 MDM 子进程
startKeychainPrefetch(); // 并行启动 2 个 keychain 读取
// ... 然后 135ms 的重量级模块 import 开始 ...
// 等 import 完成时，I/O 结果已经就绪了

利用 JavaScript 的 import 求值顺序，将 I/O 操作与模块加载并行执行。

→ 完整分析见第 09 章

🔥 Auto Dream 自动梦境 — Claude 在你离开时「做梦」，像人类一样整合记忆

src/services/autoDream/ 实现了后台记忆整合。当你超过 24 小时未使用 Claude Code，且积累了 5 个以上会话时，它会自动启动子 Agent 执行「做梦」：

  1. 定向 — 阅读现有记忆目录
  2. 收集 — 扫描日志，grep 会话转录寻找新信号
  3. 整合 — 合并新信息，将相对日期转为绝对日期，删除过时事实
  4. 修剪 — 保持索引文件 < 25KB

梦境 Agent 用只读 Bash（能 grep 不能 rm），有文件锁防并发，进度显示在任务管理器 UI 中。

const DEFAULTS = { minHours: 24, minSessions: 5 }

→ 完整分析见第 10 章

🔥 Undercover 卧底模式 — Anthropic 员工在公开仓库中自动隐身

src/utils/undercover.ts 揭示了一个当 Anthropic 员工操作公开仓库时自动激活的模式。它会清除所有 AI 归因标记，并注入这段 prompt：

UNDERCOVER MODE — CRITICAL
你正在公开/开源仓库中执行卧底任务。
绝不包含：「Claude Code」、模型代号、Co-Authored-By 行、
或任何你是 AI 的提示。
以人类开发者的方式写 commit message。

没有手动关闭选项。只要不在白名单内部仓库中，卧底模式就保持开启。也就是说，Anthropic 员工的开源贡献，你永远无法从提交历史中判断是否由 AI 完成。

→ 完整分析见第 10 章

🔥 Buddy System — 编程工具里藏了一个完整的电子宠物

src/buddy/ 包含了一套完整的虚拟宠物系统：

  • 18 个物种：duck、goose、blob、cat、dragon、octopus、owl、penguin、turtle、snail、ghost、axolotl、capybara、cactus、robot、rabbit、mushroom、chonk
  • 5 档稀有度：Common (60%) → Legendary (1%)，还有 1% 概率的 Shiny 闪光变体
  • ASCII art 精灵，每个物种 3 帧待机动画
  • 属性：DEBUGGING / PATIENCE / CHAOS / WISDOM / SNARK
  • 帽子：crown、tophat、propeller、halo、wizard、beanie、tinyduck

基于 hash(userId) 确定性生成 — 每个用户永远对应同一只宠物。宠物坐在输入框旁边，偶尔用语音气泡评论。

→ 完整分析见第 10 章

源码提取方法

# 1. 下载 npm 包
npm pack @anthropic-ai/claude-code@2.1.88 --registry https://registry.npmjs.org

# 2. 解压
tar -xzf anthropic-ai-claude-code-2.1.88.tgz

# 3. 从 source map 提取源码
node scripts/extract-sources.js ./package/cli.js.map ./extracted-src
# → 1,906 个文件，515,029 行代码

事件时间线

日期 事件
2025-02-24 v0.2.8 包含 inline base64 source map — 被开发者通过 Sublime Text undo 恢复
2025-03 Anthropic 紧急推送更新移除 source map，并从 npm 删除旧版本
2026-03-06 Agent SDK 意外包含完整 CLI（v2.1.71，13,800 行混淆代码）
2026-03-27 CMS 配置错误泄露 ~3,000 份内部文档，含 Claude Mythos 模型信息
2026-03-31 v2.1.88 包含 cli.js.map（59.8MB）— 全部 1,906 个源文件可提取

相关项目

源码与逆向工程：

分析文章：

贡献

欢迎 PR，特别是以下方向：

  • 深化骨架/WIP 状态的章节
  • 添加架构图
  • 纠正技术错误
  • 多语言翻译

声明

本项目仅用于教育和研究目的。Claude Code 的所有知识产权归 Anthropic 所有。本仓库不包含任何原始源码，仅包含架构分析和设计解读。

觉得有用的话，给个 ⭐ 吧

Built by agenmod