add diagrams to volumes 1-4

Author: T0UGH

docs/guidebookv2/volume-1/01-claude-code-what-system-is-this.md

@@ -29,6 +29,21 @@ tags:
 
 ---
 
+## 补图：Claude Code vs 普通聊天壳
+
+```mermaid
+flowchart TD
+    A[普通聊天壳] --> A1[用户输入]
+    A1 --> A2[模型回复]
+    A2 --> A3[输出结束]
+
+    B[Claude Code] --> B1[用户输入]
+    B1 --> B2[query / context / tool / agent / memory]
+    B2 --> B3[输出 + 执行 + 后续继续]
+```
+
+这张补图最想压住的不是“Claude Code 功能更多”，而是：**普通聊天壳更像一次输入对应一次回复，Claude Code 中间站着的是一层真正负责组织运行的 runtime。**
+
 ## 为什么 Claude Code 最容易先被看浅
 
 Claude Code 最先暴露给用户的，往往只是它最表面的一层：

docs/guidebookv2/volume-1/02-what-are-the-core-objects.md

@@ -88,6 +88,24 @@ flowchart TD
 
 ---
 
+## 补图：核心对象分层图
+
+```mermaid
+flowchart TD
+    A[入口层] --> A1[Prompt / Command / Slash Command]
+    B[运行层] --> B1[Runtime / Session / Context / Query]
+    C[执行层] --> C1[Tool / Agent / Subagent]
+    D[扩展层] --> D1[Skill / MCP / Plugin]
+    E[持续性层] --> E1[History / Memory / State]
+
+    A1 --> B1
+    B1 --> C1
+    B1 --> D1
+    B1 --> E1
+```
+
+这张补图的作用，是把“对象有哪些”推进成“对象分别站在哪一层”。这样后面再看主循环、工具、上下文和扩展能力时，读者更容易把它们收回同一张对象地图。
+
 ## 再把这些对象压成一张分层图
 
 如果把关系先收一收，只看它们各自站位，可以先记成下面这样：

docs/guidebookv2/volume-1/03-how-a-request-becomes-an-agent-turn.md

@@ -95,6 +95,20 @@ flowchart LR
 
 ---
 
+## 补图：request 和 agent turn 的边界
+
+```mermaid
+flowchart TD
+    A[request
+用户送进来的一次输入] --> B[运行时接入]
+    B --> C[当前 query / 当前判断形成]
+    C --> D[是否调用能力 / 是否继续]
+    D --> E[一轮 agent turn
+生成判断 → 执行动作 → 结果回流 → 再判断]
+```
+
+这张补图要切开的，是两个经常被混成一件事的对象：**request 是入口对象，agent turn 是运行单位。** 请求进来之后，只有被 runtime 组织成可持续推进的一轮工作回合，它才真正变成 turn。
+
 ## 为什么这里一定要叫 Agent Turn
 
 这里不用“单次回复”，而用“agent turn”，不是为了显得高级，而是因为两者关心的根本不是同一件事。

docs/guidebookv2/volume-2/02-what-happens-before-user-input-enters-runtime.md

@@ -65,6 +65,20 @@ flowchart TD
 
 ---
 
+## 补图：输入前处理职责图
+
+```mermaid
+flowchart TD
+    A[原始用户输入] --> B[输入预处理层]
+    B --> B1[识别输入形态]
+    B --> B2[附件 / pasted contents / 图片归位]
+    B --> B3[slash / bash / prompt 分流]
+    B --> B4[整理成 messages / metadata / permissions]
+    B4 --> C[运行时主链]
+```
+
+这张补图最重要的是把边界切开：**输入前站不是 runtime 主链本身，它先负责把原始输入整理成运行时真正能接住的请求形态。**
+
 ## 第一层：系统先识别的不是“意思”，而是输入形态
 
 这一层最容易被忽略，因为它看起来不像“核心机制”，却决定了后面的全部走向。

docs/guidebookv2/volume-2/04-how-the-current-query-is-organized.md

@@ -55,6 +55,19 @@ tags:
 
 ---
 
+## 补图：当前 query 的构成图
+
+```mermaid
+flowchart TD
+    A[当前 messages 视图] --> F[当前可工作 query]
+    B[userContext] --> F
+    C[systemPrompt] --> F
+    D[systemContext] --> F
+    E[当前输入归位后的消息结果] --> F
+```
+
+这张补图要压住的判断是：**current query 不是一句输入，也不是单独一段 prompt，而是当前 messages、userContext、systemPrompt、systemContext 与当前输入归位结果一起构成的本轮工作面。**
+
 ## 第一步：请求进入 QueryEngine 后，先被放进持续存在的消息面里
 
 从 `cc/src/QueryEngine.ts` 看，`submitMessage(...)` 处理当前请求时，最重要的背景之一，是 QueryEngine 手里已经持有一份会话级的 `mutableMessages`。

docs/guidebookv2/volume-2/06-how-results-return-to-the-current-turn.md

@@ -100,6 +100,18 @@ flowchart TD
 
 ---
 
+## 补图：result 回流责任图
+
+```mermaid
+flowchart TD
+    A[tool / action 执行] --> B[产生执行产物]
+    B --> C[包装成 tool_result]
+    C --> D[并回当前 turn 的消息链]
+    D --> E[continuation 继续组织下一轮判断]
+```
+
+这张补图补的是责任边界：**执行产物** 只是外部动作有了结果，**tool_result 并回当前 turn** 才代表主循环重新拿回了这份结果，**continuation** 则负责把它变成下一轮判断的输入。
+
 ## 关键点一：回流的对象不是“底层返回值”，而是可进入消息协议的结果块
 
 Claude Code 不是直接把某个 JavaScript 返回值塞回模型。

docs/guidebookv2/volume-3/03-why-tool-is-the-formal-runtime-execution-interface.md

@@ -69,6 +69,21 @@ Tool 的作用，就是把这些差异先压平，让 runtime 面对的不是杂
 
 也正因此，后面的文章看的都不是“一个功能怎么实现”，而是同一种执行对象在不同现实面上的职责差异。
 
+## 补图：模型 / runtime / tool 三层责任图
+
+```mermaid
+flowchart TD
+    A[模型] --> A1[形成 structured intent]
+    B[runtime] --> B1[接住 intent / 编排执行 / 继续 turn]
+    C[tool] --> C1[执行现实动作]
+
+    A1 --> B1
+    B1 --> C1
+    C1 --> B1
+```
+
+这张补图值在它能直接打掉一个最常见误读：**tool 不是模型直接调用函数；模型负责表达意图，runtime 负责接住与编排，tool 负责把现实动作真正落下去。**
+
 ## Tool 到底把什么统一了
 
 ### 第一，统一了“可被调用对象”的形态

docs/guidebookv2/volume-4/04-why-the-system-cannot-keep-sending-the-entire-history.md

@@ -85,6 +85,21 @@ flowchart TD
 
 这张图最重要的不是“预算不够”，而是：**容量问题和聚焦问题会一起出现。**
 
+## 补图：整段历史直送 vs 当前工作视图
+
+```mermaid
+flowchart TD
+    A[整段历史原样一直送模] --> A1[预算被持续挤占]
+    A --> A2[当前重点被旧材料淹没]
+    A1 --> A3[当前工作面失去可用性]
+    A2 --> A3
+
+    B[重新组织当前工作视图] --> B1[保住当前推进能力]
+    B --> B2[让注意力继续落在此刻任务上]
+```
+
+这张补图不是再说一次“历史会变长”，而是把两条路线直接摆开：系统真正要保住的不是忠实回放全部过去，而是**当前这条工作线还能继续干下去**。
+
 ## 治理的目标不是节流本身，而是保住工作能力
 
 把治理理解成“省 token 技巧”会把卷四写窄。Claude Code 真正怕的，不是单纯多花一点预算，而是：

docs/guidebookv2/volume-4/06-projection-and-collapse-govern-the-workable-view-not-the-transcript-itself.md

@@ -72,6 +72,19 @@ transcript 更靠近第一个目标，当前工作视图更靠近第二个目标
 
 一旦把这层分开，很多误读会自动消失。当前 query 不再原样带着某段旧内容，并不等于那段历史不存在了；它更可能只是在说：那段历史此刻不该再用原始密度压住当前工作面。
 
+## 补图：transcript vs workable view 边界图
+
+```mermaid
+flowchart TD
+    A[transcript
+过去发生过什么] --> C[档案层继续保留]
+    B[workable view
+这一轮拿什么继续开工] --> D[视图层继续治理]
+    E[projection / collapse] --> D
+```
+
+这张补图把本篇最该校正的东西压成最短边界：**transcript 回答“过去发生了什么”，workable view 回答“这一轮拿什么继续工作”，projection / collapse 管的是后者，不是前者。**
+
 ## projection：处理的是“旧材料怎样进入当前这一轮”
 
 projection 更像一种重投影。它不重新定义过去发生了什么，而是决定：

docs/guidebookv2/volume-4/09-why-memory-is-not-just-another-name-for-context.md

@@ -115,6 +115,21 @@ flowchart TD
 
 前者是当前工作条件，后者是跨任务持续认识。
 
+## 补图：memory / context / transcript 三分图
+
+```mermaid
+flowchart TD
+    A[transcript] --> A1[过去发生过什么]
+    B[context] --> B1[这一轮现在怎么工作]
+    C[memory] --> C1[系统长期记住了什么]
+
+    A1 --> D[当前与未来都可被引用]
+    B1 --> D
+    C1 --> D
+```
+
+这张补图最重要的作用，是把三个经常被糊成一团的对象直接分开：**transcript 更像档案，context 更像当前工作面，memory 更像跨任务持续认识。**
+
 ## 卷四前八篇已经把 context 讲得很清楚，但还没自动推出 memory
 
 这也是这篇最容易被误读的地方。