企业官网建设流程全解析

Dive into Claude Code 架构拆解：4个设计问题+5层21个子系统全景图

【免费下载链接】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（v2.1.88，约 51.2 万行 TypeScript）的源码级架构分析开源项目。它系统回答了每个生产级AI Agent都必须面对的 4 个核心设计问题，把整个系统拆解为5 层 21 个子系统的全景图，并提炼出 13 条设计原则与一份「构建你自己的 Agent」设计指南。

一句话总结：Claude Code 的代码库里只有1.6% 是 AI 决策逻辑，其余98.4% 都是确定性基础设施——权限门控、上下文管理、工具路由与故障恢复。Agent 循环本身只是一个 while 循环，真正的工程复杂度藏在它周围的系统里。🔍

核心数字速览：Claude Code 架构规模一览

在展开架构细节前，先用一组数字建立整体感知：

这些数字本身就传递出一个架构信号："最小脚手架，最大 harness"——与其在提示词上堆规则，不如投资运行时的确定性基础设施。

快速上手：如何阅读这份架构拆解项目

git clone https://gitcode.com/gh_mirrors/di/Dive-into-Claude-Code cd Dive-into-Claude-Code

不同背景的朋友建议不同的阅读路径：

4 个核心设计问题：编码智能体架构的起点

任何生产级 Coding Agent 都必须先回答 4 个问题，Claude Code 给出的答案构成了其架构骨架：

这套"问题 → 答案"的分析框架正是本项目的核心价值：不是逆向某个实现，而是给出可复用的设计空间。

7 大组件：Claude Code 系统结构全景

从上图可以清晰看到 7 个组件的数据流：

1. User（用户）——提交提示词、批准权限、审查输出
2. Interfaces（接口层）——交互式 CLI、无头 CLI（claude -p）、Agent SDK、IDE/桌面/浏览器
3. Agent Loop（智能体循环）——query.ts中的queryLoop异步生成器：调用模型 → 分派工具 → 收集结果 → 循环
4. Permission System（权限系统）——拒绝优先规则 + auto 模式 ML 分类器 + 钩子拦截
5. Tools（工具层）——最多 54 个内置工具 + MCP 工具，经assembleToolPool动态组装
6. State & Persistence（状态与持久化）——仅追加的 JSONL 转录、提示词历史、子智能体侧链
7. Execution Environment（执行环境）——Shell（含沙箱）、文件系统、Web 抓取、MCP 连接

关键设计：所有接口最终汇聚到同一个queryLoop——交互 CLI、无头模式、SDK 与 IDE 共用同一条代码路径，这大幅降低了多端行为不一致的维护成本。

5 层 21 个子系统：架构拆解全景图

将 21 个子系统归纳为 5 个架构层，是本项目最实用的拆解视角：

这张全景图值得打印出来贴在工位上——它把"Agent 系统到底由哪些部分构成"这个问题一次性讲透了。📐

Agent Loop 拆解：每一轮请求的 9 步管道

核心是一个ReAct 模式的 while 循环：组装上下文 → 调用模型 → 分派工具 → 检查权限 → 执行 → 重复。每个请求轮次严格走完 9 步管道：

设置解析 → 状态初始化 → 上下文组装 → 按条件执行上下文管理 → 模型调用 → 工具分派 → 权限门控 → 工具执行 → 停止条件检查

其中两个容易被忽略但极其关键的细节：

• 模型调用前有 5 个上下文管理阶段按序检查：预算缩减 → Snip → Microcompact → Context Collapse → Auto-Compact，每个阶段按自身条件触发，而非一刀切截断；
• 循环有 5 个停止条件：无工具调用、达到最大轮次、上下文溢出、钩子干预、显式中止。

故障恢复同样是内建能力：输出 token 上限逐级放宽（最多 3 次重试）、每轮至多一次的按需压缩、提示过长降级链、流式回退与备用模型切换。循环本身容易复制，这套恢复机制才难。💪

权限系统深度剖析：7 种模式与"拒绝优先"

权限系统是 Claude Code 最"较真"的部分，核心思想是deny-first（拒绝优先）：宽范围的 deny 规则永远覆盖窄范围的 allow。

7 种权限模式构成渐进式信任光谱：

在这套机制之上，论文归纳出7 个独立安全层：工具预过滤、拒绝优先规则评估、权限模式约束、auto 模式 ML 分类器、Shell 沙箱、会话级权限状态、钩子拦截。授权管道为 4 阶段流程：预过滤（剥离被拒工具）→ PreToolUse 钩子 → 规则评估 → 权限处理程序（4 个分支）。

还有一个值得安全研究者注意的发现：2 个已修复的 CVE 共享同一根因——钩子和 MCP 服务器在信任对话框弹出之前就已执行，形成了结构性特权的"预信任窗口"。🚨

上下文与记忆：把稀缺资源管成流水线

上下文窗口是整个系统最紧的资源约束。Claude Code 的做法是9 个有序来源依次构建上下文：系统提示 → 环境信息 → CLAUDE.md 层级 → 路径作用域规则 → 自动记忆 → 工具元数据 → 对话历史 → 工具结果 → 压缩摘要。

其中CLAUDE.md 采用 4 级层级，从企业级到个人级：

另一个反直觉的设计选择：记忆是纯文件式的——没有嵌入向量、没有向量数据库，靠 LLM 扫描记忆文件头按需选出最多 5 个相关文件。好处是完全可检查、可编辑、可版本控制。"透明优先于智能"再次体现。📝

子智能体委托：用上下文隔离换取专注

当任务可以拆分时，主智能体通过AgentTool把子任务委托给独立上下文的子智能体。内置 6 种类型（Explore、Plan、General-purpose、Guide、Verification、Statusline），支持通过.claude/agents/*.md自定义。

三个关键设计点：

• SkillTool vs AgentTool：前者把指导注入当前上下文，后者在分离上下文中运行子任务——中间过程不会污染父级上下文；
• 三种隔离模式：Worktree（git worktree 文件系统隔离）、Remote（远程执行）、In-process（默认，共享文件系统、隔离对话）；
• 侧链转录：每个子智能体有独立.jsonl文件，父级只接收精炼后的结果摘要，多实例协调直接复用 POSIXflock()，零外部依赖。

会话持久化：可回退、可审计、可分叉

会话历史通过 3 条通道持久化：仅追加的 JSONL 转录、全局提示词历史、子智能体侧链文件。

值得学习的工程取舍：

• 仅追加（append-only）优先于查询能力——每个事件人类可读、可版本控制、无需专门工具即可重建；
• 链补丁而非破坏性编辑：压缩边界记录headUuid/anchorUuid/tailUuid，会话加载时在读取时修补消息链，磁盘上从不破坏性修改；
• 检查点支持--rewind-files回退，存储于~/.claude/file-history/<sessionId>/；
• 注意：会话级绕过标志与应用白名单不会在恢复会话时还原——临时授权与持久策略严格区分生命周期。

可扩展性：4 种机制，3 个注入点

Hooks、Skills、Plugins、MCP 四种扩展机制，统一作用于 Agent Loop 的 3 个注入点：

工具池按 5 步管道动态组装：基础枚举（最多 54 个）→ 模式过滤 → deny 预过滤 → MCP 集成 → 去重。而 27 个钩子事件、10 种插件组件类型、SKILL.md 的 15+ 个 YAML 字段，则提供了从轻量注入到深度定制的完整梯度。"可组合的多机制扩展"——单一 API 做不到这种成本分级。🧩

延伸阅读：资料文件导览

结语：护城河是 harness，不是模型

这份架构拆解最有价值的结论是：Agent 循环谁都能抄，真正难的是横跨各层的 harness——钩子体系、ML 权限分类器、5 阶段压缩、子智能体隔离与恢复逻辑。如果你正在构建自己的 AI Agent 系统，建议按 docs/architecture.md 中的"设计问题 → Claude Code 答案 → 备选方案"对照表逐一决策：先想清楚 4 个核心问题，再谈技术选型。这正是本论文从"逆向工程"升维到"设计空间"的地方。🎯

【免费下载链接】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