返回首页

Claude Code 架构设计指南

IT周瑜Claude CodeAgent架构

2026 年 3 月，一个 source map 文件让 Claude Code 的完整源码离开了 Anthropic 的服务器。构建管线漏排了一个 *.map 文件，sourcesContent 字段里躺着压缩前的全部原始代码。这份备份给了我们一个难得的机会：完整阅读一个生产级、被数百万人日常使用的 Agent Harness 的源码。

这个系列按模块逐章拆解它。你会看到一个 while(true) 的 async generator 如何驱动全部核心逻辑，五十多个工具如何靠一份统一契约装进同一个调度器，权限系统的决策链如何在工作流中守住最后一道闸门，上下文如何在五层压缩下不失控，以及 Hook、MCP、终端里的 React 这些设计各自解决了什么问题。

如果你读过我写的 DeepSeek Harness 架构设计指南，可以把这个系列当作对照实验：一个是开源社区的全插件化方案，一个是闭源商业产品的工程实现，两家在几乎相同的问题空间里做出了哪些相同与不同的取舍。

面向对 Agent 架构有兴趣的工程师，不要求读过 Claude Code 的源码，但假定你写过 TypeScript 或类似语言。

全部章节（12 章）

  1. 01Harness 是什么，从泄露源码说起

    Claude Code 的 npm 包里为何躺着完整源码，source map 泄露的来龙去脉与这份备份的价值。

  2. 02主循环，一个 while(true) 驱动整个 Agent

    queryLoop 如何用一个 async generator 管住全部核心逻辑，以及不可变 State 的干净重置。

  3. 03消息的生命周期

    内部十来种 Message 类型如何规整成 API 认识的样子，tool_result 为何挂在 user 轮下。

  4. 04工具的统一契约

    五十多个工具装进同一个系统的关键：Tool 接口的描述、执行、权限、渲染四块契约。

  5. 05工具执行，流式与并发分区

    runTools 与 StreamingToolExecutor 两条路，并发安全工具的分区与调度策略。

  6. 06权限系统，规则、模式与分类器

    allow/deny/ask 三种裁决背后的有序决策链与模式转换。

  7. 07子代理，递归的主循环

    子代理如何复用主循环的全部机制，上下文隔离与结果回传。

  8. 08上下文管理，五层压缩

    从 tool_result 截断到 auto-compact，长会话上下文的五层压缩设计。

  9. 09Hook 系统，可编程的挂点

    把生命周期事件开放给用户脚本的挂点设计，以及它撑起的自动化生态。

  10. 10MCP 集成，外部能力的统一收编

    MCP 服务器如何被转译成内部工具契约，与原生工具同池调度。

  11. 11UI 层，终端里的 React

    用 React 渲染终端界面的架构选择，流式更新与组件化输出。

  12. 12彩蛋与实验田

    源码里那些有趣的小设计、实验性功能与值得玩味的工程取舍。