深入解构Claude Code - 第 12 篇 · 整体串起来

最后一篇把前面所有内容缝合成整体：完整走一遍"修一个 bug"的全过程、提炼十五个关键设计选择、给出排查问题的工具箱、并对比它和同类工具的思路差异。

12.1 完整走一遍：从你说"帮我修这个 bug"到它修好的全过程

现在把前 11 篇的零件组装起来，跟着一个真实场景走一遍。

场景：你在项目目录下启动助手，说："登录接口偶尔返回 500，帮我查查。"

bash 复制代码

① 启动（第 2 篇）
   你敲命令 → 性能垫片第一时间校准计时器
   → 入口快速通道判断：不是查版本等简单业务 → 走完整启动
   → 读配置、检查登录、初始化全局档案、加载界面
   → 终端界面（第 6 篇）渲染出对话框

② 你的话进入系统（第 3、8 篇）
   输入框内容经界面状态送到调度员
   → 包装成一条「用户消息」，追加进聊天记录
   → 聊天记录同步落盘到会话档案（第 8 篇）

③ 组装资料包（第 5 篇）
   装配工逐段准备系统提示手册：
   身份规矩、环境信息（系统/路径/时间）、
   git 仓库状态（跑 git status / git log）、
   相关记忆（"这个项目用 pnpm""登录模块在重构中"------
   按相关度从记忆档案取出，第 5 篇）、
   核心工具说明书（第 4 篇）、技能和分身目录、
   当前权限模式......
   → 稳定段落放前面（命中提示缓存，省钱，第 5.2）

④ 发给模型（第 7 篇）
   资料包交给模型对接层 → 适配器翻译成当前模型的格式
   → 网络发出，开始接收流式事件

⑤ 模型开始回应，逐字显示（第 3 篇）
   事件流一块块到达：message_start、文字增量......
   → 核心循环（生成器）每收到一段就递给界面
   → 界面双缓冲 diff，只在最后一行追加新字，逐字蹦出
   → 模型说："我先看看登录相关代码和最近的报错"

⑥ 模型请求工具（第 4 篇）
   模型回复里出现工具调用块：
   "调用搜内容工具，搜 'login' 相关的错误处理"
   → 权限关卡检查（第 4.4）：搜索是只读低风险 → 放行
   → 工具执行（可并行，第 4.5）：高速搜完返回文件列表
   → 结果作为「工具结果消息」放回聊天记录

⑦ 转圈：带着结果再问模型（第 3 篇）
   核心循环带着"搜索结果"再发一轮请求
   → 模型："调用读文件工具，读 auth.ts 和 login() 函数"
   → 读文件（只读，放行）→ 返回内容
   → 再一圈......模型发现了：某个异常没被捕获，空值时崩
   → 模型可能派一个「探索分身」（第 9.4）去确认
     "这个 login() 还有没有别的调用方也受影响"，
     分身独立转圈调查，只回传一句"还有两处调用方"

⑧ 进入计划 / 或直接动手（第 10.3）
   如果开了计划模式：模型只产出修改方案，提交给你审批
   → 你看计划，批准 → 退出计划模式
   （普通模式下模型会在界面说明它要怎么改）

⑨ 改文件（第 4、8 篇）
   模型："调用改文件工具，在 auth.ts 第 42 行加空值判断"
   → 改文件工具检查：这个文件之前读过吗？读过，合规
   → 权限关卡：改文件（若在自动同意改文件模式则放行，
     否则弹窗，你点允许）
   → 改之前先给 auth.ts 拍快照（后悔药，第 8.3）
   → 执行修改 → 红绿 diff 实时显示在界面上

⑩ 验证（第 4 篇）
   模型："调用跑命令工具，跑测试"
   → 权限关卡：跑命令（pnpm test 可能已在你的"总是允许"
     规则里，放行；否则问你）
   → 命令在后台执行，输出流式回传（第 4.5，你不用干等）
   → 结果回来：测试通过；假设有一个失败 → 模型看到失败，
     再调工具调整（工具失败是正常循环的一部分，第 7.3）
   → 再跑，全绿

⑪ 收工（第 3 篇）
   模型不再调工具，只回复文字：
   "原因是 login() 在 user 为 null 时直接访问了 .id，
    我加了空值判断并补了测试，都通过了。"
   → 结束原因是 end_turn，这一轮结束
   → 记账（第 8.4）：累计本轮输入/输出字数和花费
   → 界面更新花费、待办勾选完成

⑫ 后续（第 5、8、10 篇）
   会话结束时，可能从这次经历提炼一条记忆
   （"登录模块历史上多次因空值出 bug"）存进记忆档案
   → 整个会话档案落盘，明天可 /resume 恢复、可分叉、
     可 rewind 回退（快照还在）
   → 若有后台监控任务，守护进程继续盯着（第 10.1）
   → 你也可以在手机上收到"修好了"的推送（第 7.6）

这十二个步骤里，模型只在第 ⑤⑥⑦⑨⑩ 步参与"想"，其余全是本地程序在编排、把关、记账、渲染、存档。这就是"模型出脑子、程序出手和眼"的完整含义。

12.2 十五个关键选择：它为什么这么设计、换种做法会怎样

把全书最值得记住的设计决策集中在这里，每条都对照"如果不这样会怎样"。

核心循环做成不关心使用者的"纯发动机" 因为这样，终端、SDK、编辑器、手机、子助手才能共用同一套内核。如果循环里耦合了界面逻辑，四种形态就得写四遍。
AI 只表达意图，动作全由本地程序执行 模型碰不到你的电脑，所有工具调用都经过本地程序------权限把关、审计、快照才有可能。如果让模型直接操作，安全无从谈起。
工具调用和工具结果强制配对 模型必须看到"我要了什么、结果是什么"成对出现，否则会对着缺失结果发懵。配不上时补占位符，而不是让记录残缺。
工具只给核心几样，其余按需加载（三层供给） 工具说明书占上下文、费钱、还造成选择过载。全量塞给模型会让它更笨而不是更强。
权限做成可调光谱 + 让每次点击沉淀成规则 要么全问要么全放都不合理。"永远允许这类"让程序越用越懂你的边界，该问的危险操作一次不漏。
系统提示分段拼装、稳定的放前面 为了迎合提示缓存"开头连续相同才省钱"的规则。顺序一乱缓存全失效，成本飙升。
上下文用三档水位 + 自动压缩管理 模型工作台有限，不管理就会聊爆。压缩保近期原文、远古变摘要，既省空间又不丢关键。
记忆和压缩分开 压缩是"这场对话的浓缩"，记忆是"跨会话的长期知识"。混为一谈要么长期记不住、要么短期被噪音淹没。
两套记事本（全局档案 / 界面状态）分开 低频关键数据和高频界面数据混在一起，要么界面卡顿要么全局污染。数据单向流动。
所有会话消息逐行落盘 于是崩溃不丢、可恢复、可分叉、可倒带。崩溃恢复、后悔药、历史回顾全都建立在这一个简单决定上。
改文件前自动拍快照 git 管正式提交，快照管"AI 改了一半"的中间态。有了它才敢放手让 AI 改文件。
内部统一格式，边界做翻译 多模型（适配器）、多前端（终端/编辑器/手机）、MCP 外部工具，都是"边界翻译、内部一种普通话"。加模型、加前端都不动核心。
用 React 思路做终端界面 + 自研渲染器 界面复杂度下，手动管屏幕不可维护。声明式描述 + Yoga 布局 + 双缓冲，换来可维护性和流畅度。
功能开关在打包时删代码 + 代码分割小块懒加载 两者合起来让用户下载的程序"只包含、只加载当前要用的代码"，内存差几十倍。
可替换的边界天然可测 模型层能换假实现、文件操作能用临时目录、界面能存快照------正因为核心不绑定具体外部依赖，测试才能又快又确定。

一条主线串起这 15 条：把"会变化的、外部的、具体的"东西推到边界，把"稳定的、核心的、抽象的"东西留在内部；并且永远只为"当前实际用到的"付费（无论是 token、内存还是加载时间）。

12.3 出问题怎么查：日志、诊断命令、现场回放

真用起来难免遇到问题，这里是排查工具箱。

诊断命令

健康检查（doctor）：一键体检------系统环境、网络能不能通到模型服务、登录状态、外部工具（MCP）连接是否正常、有没有已知问题。出问题先跑它，能快速定位是"网络/登录/配置/程序"哪一层的毛病。
查看花费/用量：成本异常时看各模型用量，判断是不是缓存没命中、工具结果过大。
状态/上下文查看：看当前上下文占用、水位处于哪一档，判断是不是该压缩了。

日志

程序运行有分级日志（调试信息、普通信息、警告、错误）。调试模式下输出详细的内部决策过程；
远程控制/后台任务有专门的调试日志文件，记录每一条收发的消息，出问题可以回放；
错误会带错误编号（trace id 之类），方便和服务端日志对照。

内存问题

怀疑内存泄漏或占用过高，有"导出内存快照"手段，能看到是哪部分数据占着内存不释放；
结合第 11 篇的知识：内存异常高往往和单大块加载、结果没截断、缓存没清理有关。

现场回放与会话档案

每个会话有完整档案（第 8 篇），可以完整复盘"当时它为什么这么做"------每一步的工具调用、参数、结果都在；
可以倒带回退到任意点重新观察；
远程/后台场景有消息录制回放能力（类似行车记录仪），能重放当时的完整交互。

权限和行为异常

AI"该问的不问"或"不该问的老问"：查权限模式和你积累的"总是允许/拒绝"规则，规则可能配得太宽或太窄；
工具该出现没出现：查功能开关、工具是否被懒加载、外部服务是否连上。

排查的总体思路

顺着第 12.1 的十二个步骤定位故障发生在哪一段：是界面没显示（第 6 篇）、消息没进记录（第 3 篇）、资料包没组对（第 5 篇）、模型/网络层报错（第 7 篇）、工具被权限拦了或执行失败（第 4 篇）、还是落盘/记忆的问题（第 8 篇）。架构的分层清晰，让"症状"能很快对应到"楼层"。

12.4 它和别的 AI 编程工具思路上有什么不一样

市面上 AI 编程工具不少，理解差异能反过来加深对它的认识。这里只讲思路，不评价优劣。

终端原生 vs 编辑器插件

编辑器插件（很多工具的形态）：住在 IDE 里，深度结合编辑器的代码视图、能实时拿到编辑器的语义信息（光标位置、诊断、符号），界面体验和写代码无缝；
它是终端原生：不依赖特定编辑器，在任何环境（服务器、远程、纯命令行）都能跑，天然适合自动化和远程；通过协议（第 7 篇）反过来被编辑器集成。
思路差异：一个"长在编辑器里"，一个"独立于编辑器、可被任何前端驱动"。

对话驱动 vs 代码补全

代码补全工具（自动补全下一行）：毫秒级、基于当前文件局部上下文、人主导每一行；
它是对话驱动的智能体：给一个目标，它自己规划、读多个文件、调用工具、跑命令、验证，人在关键节点把关。
思路差异：一个是"更快的输入法"，一个是"能独立干活的执行者"。本书讲的核心循环、工具、权限、子助手，都是为"执行者"这个定位服务的。

本地编排 vs 纯云端智能体

纯云端智能体：全在服务器跑，你提交任务它远程执行；
它是本地编排：核心程序在你机器上跑，能直接碰你的文件和环境，只有"思考"调远端模型。好处是数据留在本地、环境真实、离线可用部分功能；代价是本地要装运行时、占本地资源。

开放可扩展 vs 封闭一体

它把扩展做成一等公民：MCP 接外部能力、插件市场、钩子、子助手自定义、多种模型可换、多协议对外；
封闭一体的工具开箱体验更统一，但能接什么、用哪个模型由厂商决定。
思路差异：一个是"可装配的平台"，一个是"成品电器"。

共同的趋势

尽管形态各异，做得好的工具都收敛到几个共识，而这些正是本书反复讲的：工具调用要经过安全把关、上下文要主动管理（压缩/检索）、系统提示要稳定以利用缓存、能力要按需加载、核心逻辑要和具体模型/界面解耦。理解了这套共识，你看任何 AI 智能体产品都能很快看出它的架构骨架。

全书结语

回到第 1 篇那个比喻：它是一个"有钥匙的钟点工"。读完这本书你应该已经明白，这个钟点工的"能干"不来自某个神奇的魔法，而来自一整套朴素而严谨的工程安排：

一个转圈的核心循环让"想"和"做"交替进行；
一组工具把手脚的能力暴露出来，又用权限关卡管住危险动作；
一套上下文工程决定每次给大脑看什么、怎么省钱、聊长了怎么划重点；
一个终端界面层让原始的字符终端呈现出流畅的交互；
一层边界翻译让它能换大脑、接外部服务、被编辑器和手机驱动；
以及落盘、快照、记账、功能开关、代码分割这些不起眼但决定成败的基础设施。

AI 模型会不断变强，但这套"如何把一个模型变成一个可靠、安全、好用的干活伙伴"的工程方法，会长期有效。希望读完之后，你再使用任何 AI 智能体时，都能在脑子里看到它背后那个一圈圈转动的循环------甚至，能自己动手造一个。