Dive into Claude Code 核心揭秘：为什么98.4%的代码是基础设施而非AI？
【免费下载链接】Dive-into-Claude-CodeA Systematic Analysis and Discussion of Claude Code for Designing Today's and Future AI Agent Systems项目地址: https://gitcode.com/gh_mirrors/di/Dive-into-Claude-Code
Dive into Claude Code 是对 AI 编程智能体 Claude Code 源码架构的系统级分析项目：它拆解了约 1900 个 TypeScript 文件、51.2 万行代码，揭示出只有 1.6% 的代码是 AI 决策逻辑，其余 98.4% 都是权限门控、上下文管理、工具路由等确定性基础设施。如果你正在学习 AI Agent 系统如何设计，这份源码级剖析会给你一份完整的参考答案。
📌一句话结论：智能体循环只是一个简单的 while 循环，真正的工程复杂性藏在它周围的安全、状态与恢复系统里。
Claude Code 架构全景：7 大组件如何协作
从用户输入一句提示到任务完成，请求要穿越 7 个组件。下图展示了这套「用户 → 接口 → 智能体循环 → 权限系统 → 工具 → 状态持久化 → 执行环境」的高层结构：
值得注意的是，所有入口（交互式 CLI、headless 模式、SDK、IDE）最终汇聚到同一个queryLoop。不是一套引擎跑一个界面，而是一份代码路径服务所有场景——这是整个系统能保持行为一致的关键。
5 层子系统分解：基础设施代码藏在哪里
如果继续往下拆，Claude Code 由 21 个子系统组成 5 个架构层。这张分层图回答了「98.4% 的基础设施代码到底写在哪」：
| 层 | 职责 | 关键组件 |
|---|---|---|
| 表层 | 入口与渲染 | CLI、SDK、IDE（React + Ink 终端 UI） |
| 核心层 | 上下文组装与智能体循环 | queryLoop、5 阶段压缩管道、子智能体生成 |
| 安全/行动层 | 权限与工具 | 7 个权限模式、auto 模式分类器、27 个钩子事件、shell 沙箱 |
| 状态层 | 运行时状态与持久化 | JSONL 转录稿、CLAUDE.md 层级、侧链文件 |
| 后端层 | 执行环境 | Shell 执行、MCP 连接（7 种传输类型）、42 个工具子目录 |
💡 看这张图就能理解论文的核心论点：模型只负责「推理」，而「强制执行」的能力几乎全部来自核心层、安全层和状态层的配合。
Agent 循环：一个 while 循环如何跑完所有事
智能体循环本身简单得让人意外：组装上下文 → 调用模型 → 分派工具 → 权限检查 → 执行 → 重复。每个轮次遵循 9 步管道，下图展示了多轮迭代中工具请求、权限裁决与压缩机制的运行时流程：
真正费工的是循环外的保障机制：
- 五个预模型上下文整形阶段：预算削减 → 裁剪 → 微压缩 → 上下文折叠 → 自动压缩，各阶段只在满足自身条件时才生效
- 恢复机制：输出超限重试、反应式压缩、流式后备、后备模型切换
- 5 种停止条件：无工具调用、达到最大轮数、上下文溢出、钩子干预、显式中止
拒绝优先权限系统：AI Agent 如何守住安全底线
权限系统是最典型的基础设施。它的决策原则是拒绝优先（deny > ask > allow）：任何一条宽泛的 deny 规则都会覆盖具体的 allow 规则，最严格的规则永远胜出。
系统提供 7 个权限模式，形成一条渐进信任光谱：
| 模式 | 行为 | 信任级别 |
|---|---|---|
plan | 执行前批准所有计划 | 最低 |
default | 标准交互批准 | 低 |
acceptEdits | 文件编辑自动批准 | 中 |
auto | ML 分类器评估安全性 | 高 |
dontAsk | 无提示，仍强制拒绝规则 | 较高 |
bypassPermissions | 跳过大多数提示 | 最高 |
bubble | 子智能体向父级上报 | 特殊 |
其中auto模式由独立的 LLM 分类器（yoloClassifier）做两阶段评估——快速过滤加思维链。研究还发现 2 个 CVE 共享同一根因：扩展在信任对话框出现之前就已执行，暴露出「预信任窗口」这一结构性风险。
上下文管理与记忆：AI Agent 最稀缺的资源
上下文窗口是智能体最根本的资源约束。Claude Code 按 9 个有序来源构建上下文，并按 6 个可访问性等级组织：
几个反直觉的设计选择：
- 记忆是文件而非向量库：没有嵌入、没有向量相似度，由 LLM 扫描记忆文件头、最多挑 5 个相关文件。好处是你可以直接查看、编辑并纳入版本控制
- 4 级 CLAUDE.md 层级：托管（
/etc/）→ 用户（~/.claude/）→ 项目（CLAUDE.md）→ 本地（CLAUDE.local.md），指令按优先级合并 - 指令与执行约束分离：CLAUDE.md 只引导模型行为，真正的硬约束由权限检查和沙箱在执行时实施
子智能体委托：隔离复杂度，保护主上下文
当任务复杂到需要分工，Claude Code 会把工作委托给子智能体。每个子智能体拥有独立上下文沙箱，6 个内置类型（Explore、Plan、General-purpose 等）加自定义智能体：
关键设计在SkillTool 与 AgentTool 的区分：前者把技能指令注入当前对话；后者在独立上下文中执行子任务，只有精简的结果回传给父级——中间过程不会污染主上下文。多实例协调甚至直接用了 POSIXflock()，零外部依赖。
新手阅读指南：从这里开始
如果你想动手深挖，建议按以下路径阅读本仓库：
| 你的角色 | 起点 | 接着读 |
|---|---|---|
| 智能体构建者 | 架构总览 | 中文主文档 |
| 安全研究者 | 英文架构文档 | 论文 PDF |
| 产品/研究人员 | 项目主页 | 相关资源目录 |
🎯带走三个启示：
- 循环容易抄，harness 难复制——hooks、分类器、压缩与隔离机制才是护城河
- 推理归模型，执行归代码——把不确定的判断留给模型，把确定性的边界交给基础设施
- 上下文是预算，不是容器——每个阶段都有自己的触发条件，按需整形而非一刀切
这正是 Dive into Claude Code 的核心价值：它不教你某个工具怎么用，而是把生产级 AI Agent 系统的设计空间摊开给你看——5 个价值观、13 条设计原则、直至每一行源码的选择，全部可追溯。
【免费下载链接】Dive-into-Claude-CodeA Systematic Analysis and Discussion of Claude Code for Designing Today's and Future AI Agent Systems项目地址: https://gitcode.com/gh_mirrors/di/Dive-into-Claude-Code
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
