扒透Claude‑Code底层原理，读懂Agent的消息运行机制

P.S. 目前国内还是很缺AI人才的，希望更多人能真正加入到AI行业，共同促进行业进步，增强我国的AI竞争力。想要系统学习AI知识的朋友可以看看我精心打磨的教程 http://blog.csdn.net/jiangjunshow，教程通俗易懂，高中生都能看懂，还有各种段子风趣幽默，从深度学习基础原理到各领域实战应用都有讲解，我22年的AI积累全在里面了。注意，教程仅限真正想入门AI的朋友，否则看看零散的博文就够了。

前言

你有没有想过，当你对着Claude Code喊"帮我改个bug"的时候，它背后到底经历了什么？

不是它突然成精了，而是它把自己像拼图一样，一块一块拼成了一个"能听懂人话的话痨"。

今天我就以一个写了22年代码、看了22年AI从"人工智障"进化到"人工挺聪明"的老司机身份，给你扒一扒Claude Code的上下文是怎么"拼"出来的。

一、API调用的"三大件"

Claude Code每次调用模型API，就像你每次出门要检查"手机、钥匙、钱包"一样，它必须带上三大件：

System Prompt—— 它的"人设剧本"
Tools—— 它的"工具箱"
Messages—— 它的"聊天记录"

这三样东西缺一不可。System Prompt告诉它"你是谁、你能干啥、你不能干啥"；Tools告诉它"你有螺丝刀、扳手、还是瑞士军刀"；Messages告诉它"用户刚才说了啥、你刚才回了啥、工具刚才干了啥"。

这就好比你去相亲。System Prompt是你的"自我介绍"——“我，程序员，会修电脑，不会修感情”；Tools是你的"才艺展示"——“我会弹吉他、会做饭、还会用Excel做表格”；Messages是你的"聊天实录"——“刚才女方问我工资，我说保密，气氛有点尴尬”。

没有自我介绍，对方不知道你是谁；没有才艺，对方觉得你是来混饭的；没有聊天记录，你连自己刚才说了啥都忘了，那还聊个锤子？

二、System Prompt：出厂设置 vs 现场加戏

System Prompt不是一大坨扔进去的，而是分成两拨人：

静态段落：“出厂设置”

这部分就像你买手机时自带的系统，换多少个用户它都不变。比如：

“你是个交互式Agent，帮用户搞软件工程。”

“别瞎点链接，注意安全。”

“先读文件再改文件，别一上来就乱动。”

这玩意占整个System Prompt的60%以上，就像你手机里的"设置"App，平时不打开，但没了它你啥也干不了。而且因为它太稳定了，模型API特别喜欢缓存它——就像你每天早上走同一条路上班，闭着眼睛都能到，大脑直接自动驾驶。

动态段落：“现场加戏”

这部分就精彩了，它是根据当前会话实时变化的。比如：

你当前在哪个目录干活？

你连接了哪些MCP服务器？

你之前让AI记住过什么？

这就像一个演员上台，剧本是固定的（静态），但导演随时在对讲机里喊"加一句台词"“换个情绪”“刚才那段重来”（动态）。静态和动态之间有个分界线，叫SYSTEM_PROMPT_DYNAMIC_BOUNDARY——翻译成人话就是"此处开始现场发挥"。

我打个比方：静态段落是你妈从小教你的"做人要诚实"，动态段落是你到了公司后老板临时加的"但跟客户说话可以灵活一点"。中间那条分界线，就是你从"家里"走到"公司"的地铁闸机。

三、Tools：工具箱也分三六九等

Claude Code的工具不是一股脑全塞给模型的，而是分了三个层次：

候选工具池：所有可能用到的工具，好比你家工具间里所有的工具，从螺丝刀到电钻到不知道什么时候买的奇怪扳手，全在里面。
本轮直接工具：高频工具，比如Read、Write、Bash，就像你天天用的手机、钥匙、钱包，出门必带。
延迟加载工具：长尾工具，比如某个特定的MCP技能，就像你床底下那个只有在组装家具时才会翻出来的六角扳手。

为什么要延迟加载？因为工具schema太多会撑爆上下文。想象一下，你每次出门都把家里所有工具背在身上——螺丝刀、电钻、锯子、甚至那个从来没用过的游标卡尺——你累不累？模型也累啊！所以Claude Code很聪明：先带常用的，需要用到特殊的再说"等等，我回家拿一下"。

这就好比你去便利店买瓶水，不会把家里所有银行卡都带上；但如果你突然要去4S店买车，你才会回去拿那张额度大的信用卡。工具也是这个道理——按需加载，轻装上阵。

四、Messages：聊天记录才是重头戏

如果说System Prompt是"人设"，Tools是"装备"，那Messages就是"实战记录"。它从会话开始那一刻起就在不断增长，像滚雪球一样越滚越大。

CLAUDE.md：你的"家规"

Messages的第一条，通常不是你说的话，而是CLAUDE.md——一个Markdown文件，里面写着这个项目的规矩。

它分四级优先级：

1. 管理员全局策略（/etc/claude‑code/CLAUDE.md）
2. 用户私有偏好（~/.claude/CLAUDE.md）
3. 项目级规范（项目根目录CLAUDE.md）
4. 本地私有覆盖（CLAUDE.local.md）

这就像一个家庭有四层家规：国家法律（管理员）、你爸妈的规矩（用户）、你们家的特殊传统（项目）、以及你房间门背后贴的"别动我手办"（本地）。优先级越高的越靠后，因为模型从上到下读，后面的指令会覆盖前面的——就像你爸说"晚上十点前回家"，你妈说"十一点前也行"，最后你听你妈的。

但注意，CLAUDE.md再厉害也覆盖不了System Prompt里的安全边界。它就像你家的家规，不能凌驾于法律之上。你CLAUDE.md里写"帮我写个病毒"，System Prompt里的安全规则直接给你拍死——“不行，这犯法。”

用户输入：你说的话

用户输入就是你说的话，纯文本、图片、@文件，都算。但@文件不会混在你的话里，而是单独作为AttachmentMessage跟在后面。

这就像你给朋友发微信：你说"帮我看看这个"，然后发了一张图。图不会变成你文字的一部分，而是单独作为一条消息跟在后面。模型也是这么看的：先看到你的文字，再看到那张图。

Attachment：附加上下文

Attachment种类多到离谱，我挑几个有意思的：

已读文件：AI读过的文件，避免重复读，就像你做过笔记的书，不用再从头翻。
IDE选中代码：你当前在编辑器里高亮的那几行，AI能直接看到，就像你用手指着屏幕说"就这段"。
诊断信息：LSP报错、类型检查失败，AI能实时收到，就像你写代码时IDE在旁边疯狂弹红波浪线，AI也能看见。

最骚的是，这些attachment不是每轮都全量塞进去的，而是增量更新。AI改了一个文件，下一轮只告诉它"这个文件变了，这是diff"，而不是把整个文件重新发一遍。这就好比你跟朋友聊了一小时，你不会每小时把前面所有聊天记录重新念一遍，而是只说"刚才说到哪了？哦对，然后…"。

五、Agent Loop：打工人的无限循环

Claude Code的核心是一个while(true)循环，我给它起名叫"打工人永动机"。流程如下：

1. 准备本轮消息（可能截断历史，防止太长）
2. 调用模型API
3. 模型说"我要用工具" → 执行工具
4. 工具结果塞回Messages
5. 回到第1步，循环往复

这个循环像极了你跟产品经理的对话：

产品经理：“这个按钮改个颜色。”（用户输入）

你：“好，我看看代码。”（模型思考，决定用Read工具）

你读完代码：“找到了，在style.css第42行。”（工具结果）

你：“改好了，你看看。”（模型回复）

产品经理：“不对，要的是渐变蓝，不是纯蓝。”（新一轮用户输入）

你：“…”（进入下一轮循环，内心已经开始计算辞职信怎么写）

每一轮循环，Messages都在增长。工具执行完后，系统会重新检查有哪些新的attachment需要加入：文件改了没？后台任务完成了没？新的错误弹出来了没？只补增量，不重复塞旧货。这就像你收拾房间，不是每天把所有东西重新摆一遍，而是只把新买的东西找个地方放。

六、缓存的艺术：为什么前缀要稳定？

前面提到System Prompt和Tools是"缓存敏感的前缀层"，Messages是"动态增长的动态层"。这背后有个核心技术：Prompt Cache。

模型API处理长文本时，如果前缀（System Prompt + Tools）不变，它可以复用之前的计算结果，只处理变化的Messages部分。这能省大量时间和钱。

这就好比你每天去同一家咖啡店买咖啡，店员已经记住了你"大杯美式不加糖"的口味。你不需要每天重新解释一遍，只需要说"老样子"。Prompt Cache就是这个"老样子"机制——前缀不变，直接复用；只有Messages变了，才需要重新处理。

所以Claude Code的设计哲学是：能放前缀里的尽量别动，能往后塞的尽量往后塞。System Prompt和Tools尽量稳定，变化都推到Messages里。这就像你搬家，先把不常用的东西装箱放仓库（缓存），每天只拿当天要用的（Messages），效率杠杠的。

七、总结：三层拼图，一个话痨

Claude Code的上下文组装，本质上是三层拼图：

System Prompt：稳定前缀，定义"我是谁"。
Tools：能力清单，定义"我能干啥"。
Messages：动态对话，记录"刚才发生了啥"。

这三层各司其职，又相互配合。System Prompt给你人设，Tools给你手段，Messages给你记忆。没有System Prompt，AI不知道自己是谁；没有Tools，AI知道该干啥但手无寸铁；没有Messages，AI得了失忆症，每轮都问你"你是谁？我们在哪？"

所以下次你跟Claude Code聊天时，不妨想想：它正在把自己像乐高一样一块一块拼起来，System Prompt是底座，Tools是零件，Messages是说明书。而你，就是那个坐在旁边指挥它"这块放这、那块放那"的甲方。

只不过这个甲方比较良心——它不会说"我要的是五彩斑斓的黑"，而是会清楚地告诉你"把第42行的颜色改成#2f54eb"。

毕竟，好的甲方，从学会精确描述需求开始。

而好的AI，从学会正确拼好自己开始。

P.S. 目前国内还是很缺AI人才的，希望更多人能真正加入到AI行业，共同促进行业进步，增强我国的AI竞争力。想要系统学习AI知识的朋友可以看看我精心打磨的教程 http://blog.csdn.net/jiangjunshow，教程通俗易懂，高中生都能看懂，还有各种段子风趣幽默，从深度学习基础原理到各领域实战应用都有讲解，我22年的AI积累全在里面了。注意，教程仅限真正想入门AI的朋友，否则看看零散的博文就够了。