Claude Code 源码架构全流程剖析（非常详细），启动、Prompt 与权限管道从入门到精通，收藏这一篇就够了！

昨天 Claude Code 的源码泄露朋友圈和技术群基本刷了一整天。各种角度都有人写了。有盘隐藏功能的有数工具和命令数量的有人把query.ts这个胖核心拎出来讲也有人盯着 hooks 配置投毒做了实测演示。我自己也跟着翻了一晚上收获确实不少。但翻到后面会发现一个问题好文章很多信息量也够大可如果想写成一篇最后很容易变成什么都讲了、主线却不太清楚。所以这篇我想收一收只沿着一条线往下看Claude Code 这套本地 Agent Runtime从启动到上下文装配到主循环到权限管道到底是怎么一层一层搭起来的。太长不看版• 这次泄露出来的主要是 Claude Code 的工程实现层不是模型权重本身。• 如果只看架构和代码最值得看的主线不是“功能大全”而是启动、上下文装配、主循环、工具契约、编辑约束、权限管道、长任务续航这几层怎么连起来。•src/main.tsx说明它从一开始就按长期交互系统来优化而不是按一次性 CLI 来写。•src/constants/prompts.ts和src/utils/queryContext.ts说明 Prompt 在这里更像装配层不是一段静态文案。•src/QueryEngine.ts、src/utils/processUserInput/processUserInput.ts、src/query.ts共同构成了它的运行主链路。•src/Tool.ts、src/tools.ts、src/tools/FileEditTool/*这几处最能看出 Anthropic 如何把“先读再改”“默认保守”写成机制。•src/utils/permissions/permissions.ts更像权限决策管道而不只是一个确认弹窗。• 上下文压缩做了三级microcompact / autocompact / 完全压缩长期记忆和会话状态也拆开了两条线。• 但高权限也意味着更大的攻击面hooks、MCP、Skill 这些确定性执行入口一旦被项目级配置投毒就是静默的远程代码执行。先把边界讲清楚翻了一圈下来有一个感觉比较一致这次可见的价值主要在 Claude Code 这套产品实现而不在 Claude 模型本身。外界现在能看到的主要是“这套本地 Agent 系统怎么跑”而不是 Claude 模型本身怎么推理。这个区别很重要。因为如果边界没切开文章很容易一路滑向两个方向。一个方向是把它写成“模型神秘能力”的延伸。另一个方向是把它写成“功能目录大全”。但从工程上看更有价值的其实是中间这层它怎么收集上下文怎么组织主循环怎么约束工具怎么处理长任务怎么在本地高权限环境下尽量把风险往前收。主线就落在这里。别急着数功能先看主链路如果想先建立一个整体认知比起数工具数量或翻 feature flag可能更值得先顺着一条主链路看main.tsx先把启动阶段能并行的事情并起来。QueryEngine.submitMessage()收到一轮新输入准备会话级状态。fetchSystemPromptParts()拉起 system prompt、user context、system context。processUserInput()把原始输入整理成真正进入模型的一轮消息。query.ts驱动主循环处理工具调用、预算、压缩、继续执行等状态迁移。工具系统执行读、写、搜索、命令、MCP 等动作。权限系统在工具层、规则层和模式层多次参与裁决。上下文太长时进入 compact长期任务状态则交给 memory 体系续住。这条链一旦看清楚很多人说的“它为什么更重”“为什么代码会这么多”“为什么看起来不只是个终端聊天工具”就比较容易理解了。图 1Claude Code 的运行主链路main.tsx先透露出一个信号它按 Runtime 在写很多文章都拿src/main.tsx开头那几行并行预取举例这个点是成立的而且值得保留。原因不只是“并发优化很聪明”更关键的是它透露出一个工程取向。在src/main.tsx顶部系统会提前触发 profile checkpoint、MDM 读取、keychain 预取这类动作并尽量和后续 import 过程叠起来。注释里甚至直接说明了这样做和启动耗时之间的关系。这说明它一开始就在解决一个非常朴素的问题如果这个工具每天会被频繁打开启动链路就不是边角问题而是运行时体验的一部分。main.tsx未必是最复杂的文件但它能最早告诉你Anthropic 在把 Claude Code 当成什么来做。Prompt 在这里更像装配层不是一段“神奇提示词”昨天不少文章都提到了系统 Prompt 很长这个观察没问题但如果只停在这里还差一层。从src/constants/prompts.ts和src/utils/queryContext.ts看更贴近工程实际的说法应该是Claude Code 把 Prompt 做成了一层可装配、可分段、可缓存的运行时上下文。这里面有几个细节比较关键。一是getSystemPrompt()并不是返回一段大字符串而是先按 section 组织再拼成最终结果。二是SYSTEM_PROMPT_DYNAMIC_BOUNDARY明确把静态前缀和动态部分切开。三是fetchSystemPromptParts()会并行准备defaultSystemPrompt、userContext、systemContext这三块 API cache-key 前缀材料。这意味着它关心的已经不是“提示词写得漂不漂亮”而是• 哪些内容可以稳定复用• 哪些内容必须每轮重新感知• 哪些上下文属于会话状态• 哪些上下文属于系统环境上下文出问题很少只是“token 不够”更多时候是组织方式本身不够系统化。还有一个细节值得看每个工具目录下还有独立的prompt.ts比如BashTool/prompt.ts里直接写了 Git Safety Protocol——“NEVER run destructive git commands unless the user explicitly requests”。这些不是给人看的使用说明而是写给 AI 看的行为准则。工具排序也是固定的目的是保持 Prompt Cache 的字节级前缀稳定。也就是说Claude Code 把 Prompt 管理做成了一件和编译器优化类似的事。静态部分是“编译后的二进制”走缓存动态部分是“运行时参数”每次装配。缓存不是省钱手段而是约束整个上下文组织方式的底层纪律。从这个角度看Claude Code 的 Prompt 体系并不神秘。它只是比很多产品更早把“上下文装配”当成了一层正式工程对象。图 2Prompt 装配不是一段话而是一组可缓存上下文运行主链路真正承重的是QueryEngine加query.ts如果说main.tsx负责把系统拉起来那真正决定 Claude Code 气质的还是后面的运行主链路。这里我更建议把三个文件放在一起看•src/QueryEngine.ts•src/utils/processUserInput/processUserInput.ts•src/query.tsQueryEngine.submitMessage()的作用不只是“把用户输入发给模型”。从代码上看它会准备 cwd、tools、commands、mcpClients、thinkingConfig、budget、session state再去调用fetchSystemPromptParts()然后结合 memory prompt、custom prompt、append prompt 组出真正的 system prompt再构建processUserInputContext把canUseTool、readFileState、requestPrompt、session storage 这些运行期能力一并带进去。processUserInput()也不是简单做一层字符串预处理。它会先处理 slash command、attachments、图片、IDE selection、粘贴内容然后在真正继续之前执行executeUserPromptSubmitHooks()必要时把整轮执行拦下来或者附加额外上下文。到了query.ts整个系统才进入那条最核心的 Agent Loop。消息准备、工具调用、结果回填、token budget、stop hooks、continue 状态、compact 判断都在这里汇合。query.ts的“大”更像是一种刻意保留的“胖核心”。因为 Claude Code 这类系统最难管理的不是单个模块而是跨轮次状态。消息什么时候进入上下文。工具结果什么时候被裁剪。哪些中间状态要持久化。什么时候该停什么时候该继续。什么时候该压缩历史什么时候该保留原始链路。这些东西如果拆得过散表面上模块是瘦了实际复杂度往往只是转移了位置。所以query.ts好不好看可以讨论但把它放回 Agent Runtime 这个语境里它为什么长、为什么重至少是说得通的。还有一个细节。源码里能看到USER_TYPE ant的分支——Anthropic 内部员工用的版本和外部用户的版本在提示词策略上有差异。内部版本有更激进的输出策略、更详细的代码风格指引以及一些还在 A/B 测试的实验功能比如 Verification Agent、Explore Plan Agent。这说明 Anthropic 自己就是 Claude Code 最大的用户。他们用自己的产品来开发自己的产品。这个信号和 OpenAI 用 Codex 来开发 Codex 是同一个思路——最终能不能做好 Agent 产品很大程度上取决于团队自己是不是每天在用、每天在反馈、每天在迭代。工具系统真正值钱的是“先声明边界再给模型用”有些文章会先列 Claude Code 有多少工具、多少命令这些信息当然有用但可能还有一层更值得看这些工具在进入系统之前边界是不是已经被定义清楚了。这里最值得看的是src/Tool.ts和src/tools.ts。在Tool.ts里一个工具不是“能运行就行”它还得回答一组很具体的问题•isReadOnly•isConcurrencySafe•isDestructive•needsUserInteraction•checkPermissions更重要的是buildTool()背后的默认值是保守的。isConcurrencySafe默认falseisReadOnly默认false。这不是小事。它说明系统默认不信任一个“没写清楚安全属性”的工具。只要作者漏配了关键声明系统就先把它看成可能会写、可能不安全并发的那一类。很多产品的节奏是“先把工具接上规则以后慢慢补”。Claude Code 反过来先把安全属性声明清楚再暴露给模型。起步会慢一点但后面在权限和并发上欠的债会少很多。这和我们之前聊 Harness 时看到的思路很像尽量把模型能调用的东西变成有边界的工程对象而不是一堆零散外挂。FileEditTool很值得细看因为它在减少“凭感觉改文件”如果从整份仓库里挑一组最能说明 Claude Code 工程风格的文件大概是这两个•src/tools/FileEditTool/prompt.ts•src/tools/FileEditTool/FileEditTool.ts一方面prompt.ts里明确写了在编辑前至少要先用Read工具读过一次。关键在于这句话和工具本身的校验逻辑是配套的。如果模型没读过文件就直接调编辑系统会报错拦住。它在系统层把“先读再改”做成了硬约束而不只是提醒。另一方面FileEditTool.ts里的保护都很朴素但很工程• 先做路径规范化避免~、相对路径这类写法影响规则匹配• 在真正修改前做权限校验• 对 denied directory 做明确拦截• 对超大文件做保护• 对文件不存在、旧字符串不唯一、空文件等情况分开处理单看其中任何一条都不算惊艳。但放在一起你会看到一种比较一致的设计取向不要太依赖模型自觉能提前机制化的地方尽量机制化。从源码里反复能看到的也是这个倾向Claude Code 一直在把易错点往系统约束里推靠的是工程纪律不是某个神奇技巧。图 3工具调用前Claude Code 先把边界写清楚权限系统更像决策管道不只是一个弹窗安全是这次讨论里最容易跑偏的话题。因为一旦说到本地文件、命令执行、MCP、配置入口文章很容易在“很危险”三个字上停住。从src/utils/permissions/permissions.ts看Claude Code 更值得注意的地方是它把权限决策拆成了一条可治理的链路。沿着hasPermissionsToUseToolInner()往下看大致能看到这样的顺序先判断是否命中 deny tool再判断是否命中 ask tool再进入工具自己的checkPermissions再处理内容级 ask rule 和 safety check再看当前 mode比如bypassPermissions再看 always allow最后把passthrough收敛成 ask同一个文件里还能看到 classifier、PermissionRequest hooks、MCP 规则匹配、denial tracking 这些补充机制。所以如果只用一句更贴近工程的话来总结我会说Claude Code 的权限系统更像一条可以持续治理、持续插入规则的管道远不止一个弹窗确认。这也是为什么它的实现会显得比较重。因为一旦产品想在本地环境里持续跑下去权限就不太可能继续作为一层“最后再补”的界面逻辑。图 4权限决策更像一条管道长任务能不能续上还是要回到 compact 和 memory还有一层我觉得很适合和我们前面写的上下文治理系列放在一起看。那就是 Claude Code 并没有把希望都压在“大窗口模型”上而是单独做了 compact 和 memory 两套机制。src/services/compact/prompt.ts里能看到compact 阶段会用专门 prompt 约束总结方式而且明确禁止调用工具要求尽量保留用户请求、相关文件、关键代码、错误、待办、当前工作状态这些结构化信息。src/services/extractMemories/prompts.ts和src/services/SessionMemory/prompts.ts则把“长期记忆提取”和“当前会话状态维护”拆开了。后者尤其直白直接维护Current State、Task specification、Files and Functions、Errors Corrections、Worklog这些区块。背后的道理其实很朴素。长任务真正难的地方在于“状态续不上”而不只是“字数太多”。历史该怎么压是一个问题。当前任务状态该怎么续住是另一个问题。实际上Claude Code 的压缩还不止一层。从代码里可以看到它做了三级压缩microcompact只清理旧工具调用结果保留对话主线、autocompacttoken 消耗接近上下文窗口的 87% 时自动触发、以及完全压缩让 AI 对整段对话生成摘要替换历史。值得注意的是完全压缩阶段有一条非常严厉的前置指令——“CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.”——因为如果总结过程中 AI 又去调工具就会产生更多 token 消耗适得其反。Claude Code 的做法未必最轻但它至少把这两个问题拆开处理了。而且在压缩策略上它并不是简单地做摘要而是分了三个梯度尽量在每个阶段都做最小侵入的处理。单从工程完整性上看这一点是比较扎实的。图 5长任务要把“历史压缩”和“状态续写”分开处理但高权限也意味着更大的攻击面不过如果只讲工程设计多扎实还差一层。昨天的讨论里有一类值得单独说一下配置投毒。有安全研究者和 UP 主实测演示了一个场景只要 clone 一个包含恶意.claude/settings.json的仓库运行claude命令后hooks 字段里定义的脚本会静默执行——不弹窗、不确认摄像头可以被调起密码可以被窃取。问题在于当这个确定性入口对项目级配置文件也默认信任时攻击者就可以把恶意命令藏在一个看起来正常的开源项目里。投毒路径还不止 hooks 一条。.mcp.json可以配置恶意的 MCP 服务器skill 文件的 frontmatter 也可以定义 hooks。三条路径的共同点是都是 Claude Code 默认信任、不做二次确认的配置入口。Check Point Research 在 CVE-2025-59536 报告里有一句话放在这里很合适曾经作为被动数据的配置文件如今成了主动执行路径的控制器。这和我们昨天讲的观点是一回事当 Agent 开始真正动手——读文件、跑命令、调工具——安全边界到底停留在产品文案里还是已经被做成了工程现实就变成了一个必须正面回答的问题。Claude Code 的权限管道在工具层做得不少但在配置信任边界上这次暴露出来的攻击面说明还有一段路要走。对所有做 Agent 的团队来说这个教训同样适用Hooks、MCP、Skill 这些扩展入口越强大它们被投毒时的伤害也越大。确定性执行是优势但确定性信任可能是风险。这次更值得学的是这些朴素的做法昨天大家写的文章放在一起看各有各的价值。整体规模感有了风险边界的提醒有了query.ts这种“胖核心”的拆解也有了。而大家越看越清楚的一点是这次泄露出来的核心价值在工程实现不在模型权重。回到本地源码校一遍想说的其实就一句Claude Code 这次更值得借鉴的其实是它把很多原本只写在最佳实践文档里的东西一步步推进成了代码里的系统约束。Prompt 分层装配。工具先声明边界。编辑尽量先读后改。权限做成决策链。长任务把“历史压缩”和“状态续写”分开处理。这些做法看起来都不新。但它们一旦真的被写进系统产品体验通常就会稳定不少。所以没必要把 Claude Code 神化成“操作系统”或者“黑科技”。更朴素的说法可能是它只是比较认真地把一套本地 Agent Runtime 该补的工程层一层一层补起来了。而 AI Coding 产品接下来真正拉开差距的地方可能也越来越在这里。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】