Claude Code 源码架构深度解析V2.0

从4756个文件里读懂Agent系统工程 Xiao Tan X (Twitter):x.com/tvytlx公众号:Xiao Tan AI小红书:tvytlx邮箱:tvytlx@gmail.com Contents 1全局视角：CLI工具vs Agent Operating System4 1.1你在看什么. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41.2代码库规模. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41.3入口层暴露的设计意图. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51.4命令系统不是装饰品. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 2引擎：主循环与Prompt编排5 Xiao Tan AI2.1一个请求怎么跑起来的. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52.2query.ts：1729行的状态机. . . . . . . . . . . . . . . . . . . . . . . . . . . . .62.3Streaming Tool Execution：边收边跑. . . . . . . . . . . . . . . . . . . . . .72.4Prompt组装：一台精密的拼装机器. . . . . . . . . . . . . . . . . . . . . . .72.5Prompt Cache经济学. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82.6行为规范：怎么让AI工程师不乱来. . . . . . . . . . . . . . . . . . . . . . .8 3工具系统：42个工具和一条治理流水线9 3.1Tool接口设计. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93.242个工具的分类. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93.3工具执行Pipeline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 4多Agent体系：分工和调度11 4.1为什么需要多个Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114.2Explore Agent：裁剪出来的只读专家. . . . . . . . . . . . . . . . . . . . . . .114.3Verification Agent：整个系统里最狠的prompt. . . . . . . . . . . . . . . . .124.4AgentTool.tsx：调度总控. . . . . . . . . . . . . . . . . . . . . . . . . . . . .124.5Fork path的cache优化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134.6runAgent.ts：子Agent的完整运行时. . . . . . . . . . . . . . . . . . . . . .134.7任务系统. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 Xiao Tan AI5安全层：权限、Hook和三层防护网14 5.1权限系统概览. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145.2Hook系统：不只是事件钩子. . . . . . . . . . . . . . . . . . . . . . . . . . .145.3resolveHookPermissionDecision：安全的关键粘合层. . . . . . . . . . . . . . .155.4三层防护网. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 6生态：Skill、Plugin、MCP16 6.1Skill：带元数据的workflow package. . . . . . . . . . . . . . . . . . . . . . .166.2Plugin：模型行为层面的扩展. . . . . . . . . . . . . . . . . . . . . . . . . . .16 6.3MCP：工具桥+行为说明注入. . . . . . . . . . . . . . . . . . . . . . . . . .166.4生态的关键：模型”感知到”自己的能力. . . . . . . . . . . . . . . . . . . . .17 7上下文经济学：Token就是预算17 7.1四道压缩机制. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177.2Reactive Compact：API 413的兜底. . . . . . . . . . . . . . . . . . . . . . .177.3Token Budget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177.4其他上下文优化. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17 8产品化：从prototype到product18 8.1生命周期管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188.2Bridge系统. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188.3State管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188.4UI层. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188.5Telemetry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 Xiao Tan AI9从源码里提炼出的设计原则19 9.1原则1：不信任模型的自觉性. . . . . . . . . . . . . . . . . . . . . . . . . . .199.2原则2：把角色拆开. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199.3原则3：工具调用要有治理. . . . . . . . . . . . . . . . . . . . . . . . . . . .199.4原则4：上下文是预算. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199.5原则5：安全层要互不绕过. . . . . . . . . . . . . . . . . . . . . . . . . . . .199.6原则6：生态的关键是模型感知. . . . . . . . . . . . . . . . . . . . . . . . . .209.7原则7：产品化在于处理第二天. . . . . . . . . . . . . . . . . . . . . . . . . .20 10附录：核心文件索引20 Xiao Tan AI10.1入口与主循环. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2010.2 Prompt系统. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2010.3工具执行. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2010.4 Agent系统. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2110.5权限与安全. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2110.6生态扩展. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2110.7上下文管理. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21 1全局视角：CLI工具vs Agent Operating System 1.1你在看什么 这份报告的素材，来自Claude Code的npm包。包里有一个cli.js.map文件，里面的sourcesContent字段存着完整的TypeScript源码。把它提取出来，你会得到将近4756个文件。 这个数字本身就说明了很多。市面上大部分开源coding agent，你打开src/目录，会看到一个main文件、一个prompt文件、几个tool文件、一个utils。Claude Code的src/顶层有超过50个模块目录。 1.2代码库规模 先看几个数字，有个直观感受： 关键文件的行数也很有说服力： 1.3入口层暴露的设计意图 Claude Code有多个入口：cli.tsx、init.ts、mcp.ts、sdk/。同一个agent运行时，能服务CLI终端、MCP协议、SDK调用、IDE插件。这就是平台化设计。 cli.tsx本身值得看一眼。它不是简单地加载main.tsx然后跑。它有一套fast-path分发逻辑： •--version：零模块加载，直接打印版本号退出•remote-control：走bridge模式，不进主REPL•daemon：走长驻进程模式•ps / logs / attach / kill：走后台会话管理•--worktree --tmu