Claude-code源码学习

GitHub对应仓库：1664178416/claude-code-map-learn: claude-code源码学习

若可以请给我点个star⭐

📋 前言

Claude Code 源码泄露事件引起了广泛关注。作为 AI 编程工具的天花板，它的源码对学习 AI 应用开发来说简直是宝藏资源。本文将从工程角度深度解析其架构设计，帮助大家提升 AI 项目开发能力。

---

一、源码泄露始末

1.1 发生了什么？

Claude Code 是通过 npm 发布的开发者工具。正常情况下，代码上线前会经过压缩混淆处理，但开发时用于调试的 Source Map 文件（相当于"翻译对照表"）应该在发布时删除。

然而 Anthropic 的工程师在发布 Claude Code 2.1.88 版本时，打包工具 Bun 默认生成了 Source Map 文件，而他们忘了在发布配置里把 .map 文件排除掉。

结果：一个 59.8 MB 的 cli.js.map 文件就这么被直接发到了公开的 npm 仓库。

1.2 泄露了什么？

• 1906 个 TypeScript 源文件
• 约 51.2 万行代码
• 包括：Agent 循环引擎、40+ 内置工具完整实现、系统提示词组装逻辑、记忆系统、上下文压缩、权限管控机制等
• 不包括：服务端模型训练代码和 API 后端逻辑

1.3 这是第二次！

更有趣的是，去年 2 月 Claude Code 刚发布的时候就出过一模一样的事故。同一个错误犯了两次，属实是 Vibe Coding 上瘾了。

---

二、整体架构解析

Claude Code 使用 React Ink 框架开发（用 React 写命令行界面），整个项目分为 6 层：

┌─────────────────────────────────────────┐
│     CLI 和界面层（终端交互）            │
├─────────────────────────────────────────┤
│     Agent 循环引擎（大脑）              │
├─────────────────────────────────────────┤
│     工具系统（40+内置工具+MCP扩展）     │
├─────────────────────────────────────────┤
│     记忆系统（解决断片问题）            │
├─────────────────────────────────────────┤
│     上下文压缩系统（解决token满的问题）  │
├─────────────────────────────────────────┤
│     权限和安全系统                       │
└─────────────────────────────────────────┘

---

三、核心模块深度解析

3.1 Agent 循环：朴素而强大的 ReAct 机制

Claude Code 的核心循环出奇地朴素------就是一个 while(true) 无限循环：

// query.ts
while (true) {
  // 1. 上下文压缩（防止 token 爆炸）
  // 2. 调用大模型，流式获取响应
  // 3. 解析模型返回的工具调用
  // 4. 执行工具，获取结果
  // 5. 把结果追加到对话历史
  // 6. 如果没有新的工具调用，结束；否则继续循环
}

这 就是 AI 领域著名的 ReAct 机制 （推理 + 执行），让 AI 自己形成 思考 → 行动 → 观察 → 再思考 的闭环。

代码中还有个彩蛋------工程师留下的"巫师守则"注释：

/**
 * The rules of thinking are lengthy and fortuitous...
 * Heed these rules well, young wizard.
 * For they are the rules of thinking,
 * and the rules of thinking are the rules of the universe.
 * If ye does not heed these rules, ye will be punished
 * with an entire day of debugging and hair pulling.
 */

3.2 工具系统：fail-closed 安全哲学

Claude Code 内置 40+ 工具，每个工具都通过 buildTool 工厂函数创建，有个精妙的默认值设计：

// Tool.ts
// Defaults (fail-closed where it matters):
const TOOL_DEFAULTS = {
  isConcurrencySafe: (_input?: unknown) => false,  // 默认不安全
  isReadOnly: (_input?: unknown) => false,         // 默认会修改
  isDestructive: (_input?: unknown) => false,     // 默认有破坏性
  toAutoClassifierInput: () => '',               // 默认跳过安全检查
}

fail-closed（失败时关闭） 思想：如果你没声明"我只是读个文件"，系统就默认它危险，不让它并发执行。

💡 这就像公司门禁系统------没刷卡默认进不去，而不是默认让进。

3.3 读写分离的并发控制

Claude Code 实现了一套聪明的读写分离机制：

// 连续几个只读工具可以一起跑
// 一旦遇到写操作，就得排队等前面的都完成了
if (isConcurrencySafe && acc[acc.length - 1]?.isConcurrencySafe) {
  // 合并到并发批次
} else {
  // 新开一个批次
}

这正是数据库领域的读读并行、读写互斥思想在 AI 工具执行中的应用。

3.4 System Prompt 缓存优化

Claude Code 用 DYNAMIC_BOUNDARY 标记把提示词精确切成两半：

┌────────────────────────────────────────┐
│  静态部分（全球用户共享缓存）           │
│  角色定义、行为规范、工具说明...       │
├─ DYNAMIC_BOUNDARY ────────────────────┤
│  动态部分（每个用户各不相同）          │
│  当前时间、Git状态、CLAUDE.md配置...  │
└────────────────────────────────────────┘

效果：静态部分全球几百万用户共享同一份缓存，节省大量 token 和成本。

3.5 内容检索：不用 RAG 的智慧

业界流行 RAG（检索增强生成），但 Claude Code 压根不用！

// memdir/memdir.ts
const memSearch = `grep -rn "<search term>" ${autoMemDir} --include="*.md"`
const transcriptSearch = `grep -rn "<search term>" ${projectDir}/ --include="*.jsonl"`

创始人 Boris Cherny 在播客中说："让 AI 自己决定搜什么、怎么搜，效果远远好于 RAG。"

RAG = 帮实习生整理资料给他看

Agentic Search = 给实习生权限让他自己去找

模型能力越强，后者优势越大。

---

四、三层记忆架构（最精妙的设计）

这是 Claude Code 最值得学习的部分------Self-Healing Memory 自愈记忆：

第一层：MEMORY.md（热数据）

• 每次对话都加载

• 最多 200 行、25KB

• 只存指针不存内容

  // 截断逻辑
  export const MAX_ENTRYPOINT_LINES = 200
  export const MAX_ENTRYPOINT_BYTES = 25_000

第二层：话题文件（温数据）

• 编码偏好、项目架构约定、踩过的坑
• 用 Sonnet 小模型挑选最多 5 个相关文件
• 只记人的偏好和判断，不记代码（代码会变，但记忆不会自动更新）

第三层：历史对话（冷数据）

• 存成 .jsonl 格式

• 需要时用 Grep 搜索

  ┌─────────────────────────────────────┐
  │ 热：MEMORY.md ─ 每次都加载 │
  ├─────────────────────────────────────┤
  │ 温：话题文件 ─ 按需加载 │
  ├─────────────────────────────────────┤
  │ 冷：历史对话 ─ 搜索获取 │
  └─────────────────────────────────────┘

---

五、五级上下文压缩

Claude Code 设计了五级压缩策略，像漏斗一样层层过滤：

级别	名称	策略
1	Snip 剪裁	旧的工具调用结果只保留结构
2	Microcompact	卸载到缓存（不直接丢弃）
3	Context Collapse	对话折叠摘要
4	Autocompact	超过阈值触发全量摘要
5	Reactive Compact	413错误时紧急触发

还有断路器机制------连续失败 3 次就自动停下来，避免无限重试浪费 API 调用。

---

六、安全审查：多层防护

即使开启 --dangerously-skip-permissions（YOLO 模式），背后还有一个影子 AI 在帮你把关：

// YOLO 安全分类器
export async function classifyYoloAction(
  toolName: string,
  toolInput: Record<string, unknown>
): Promise<'allow' | 'soft_deny' | 'hard_deny'>

Bash 命令安全检查定义了 23 种规则，包括：

• Unicode 零宽空格混淆
• Zsh 危险命令（zmodload）
• IFS 变量注入
• 等等...

---

七、隐藏彩蛋：数字宠物系统

在 buddy/ 目录下，Anthropic 工程师藏了一套数字宠物系统！

// 18种物种
export const SPECIES = [
  duck, goose, blob, cat, dragon, octopus, owl, penguin,
  turtle, snail, ghost, axolotl, capybara, cactus, robot,
  rabbit, mushroom, chonk,
] as const

原计划 4 月作为彩蛋预热、5 月上线，结果源码泄露提前被发现了 😂

---

八、工程亮点总结

技术点	亮点
Agent 循环	朴素的 while(true) + ReAct 机制
工具系统	fail-closed 安全哲学
并发控制	读写分离 + 断路器
Prompt 缓存	精确的动态/静态分层
检索策略	Agentic Search > RAG
记忆系统	三层分级（热/温/冷）
上下文压缩	五级漏斗 + 断路器
安全审查	多层防护 + 影子 AI
性能优化	动态加载 + TCP 预连接

---

九、学习价值

📚 这份源码是目前最好的 AI 应用架构教材。

像以下问题的答案全在里面：

• Agent 循环怎么写？
• 工具系统怎么设计？
• 记忆怎么管理？
• 安全怎么做？

简历上如果能写上"深度阅读了 Claude Code 源码并应用于自己的项目"，绝对是加分项。

---

十、结语

看完这份源码，你会发现 Claude Code 里没什么惊天动地的新算法，用的都是程序员接触过的基础知识：并发控制、读写分离、分层缓存、断路器、功能开关...

但 Claude Code 团队把这些东西完美组合到了 AI 场景里，打造出了极其优秀的产品。

这正印证了那句话------计算机基础知识和设计思想很重要。

---

📌 本文对应GitHub仓库 ：1664178416/claude-code-map-learn: claude-code源码学习

⭐ 觉得有帮助的话，点个赞再走呗~

#AI #ClaudeCode #源码 #技术分享 #编程工具