docs: 长章补「章内导读」+ 终章补「回头看」(YAO-149)

docs/08-PromptCache横切.md

@@ -17,6 +17,8 @@ Anthropic 的 Prompt Caching 机制可以将 **重复前缀** 的成本降低 90
 
 ---
 
+> **章内导读**：§一 缓存基本原理与标记策略 → §二 System Prompt 分块 → §三 Cached Microcompact → §四 Fork Agent 的 CacheSafeParams → §五 缓存失效检测 → §六 全景图 → §七 可迁移模式。前五节按缓存的「生命周期」展开（建立→分块→保护→共享→失效），第六节横切总览，第七节抽出可复用模式。
+
 ## 一、Prompt Cache 的基本原理与标记策略
 
 ### 1.1 `cache_control` 标记：告诉 API "请缓存到这里"

docs/09-Thinking-Effort-与-Advisor.md

@@ -19,6 +19,8 @@ Claude Code 面对的工程挑战是：**如何让用户（和系统）灵活地
 
 ---
 
+> **章内导读**：§一/§二 Extended Thinking（三种模式 + API 注入）→ §三 Effort 级别 → §四 Ultrathink 触发 → §五 Advisor 审阅 → §六/§七 Thinking 流式与 Side Query → §八 四子系统协作全景 → 番外 PromptSuggestion → §九 可迁移模式。本章是「四个相关但独立的推理控制旋钮」并列展开，按 §八 的全景图回头看，能把 §一–§五 串起来。
+
 ## 一、ThinkingConfig — Extended Thinking 的三种模式
 
 ### 1.1 类型定义

docs/11-BashTool-PowerShellTool-双shell.md

@@ -29,6 +29,8 @@
 
 ---
 
+> **章内导读**：§一 命令语义分类（让 AI 知道自己在跑什么）→ §二 权限主链路 `bashToolHasPermission` → §三 规则匹配与建议 → §四 沙箱执行 → §五 执行与输出处理 → §六 Prompt 工程 → §七 sed 特例 → §八 破坏性命令警告 → §九 可迁移模式 → §十 PowerShellTool 对照。前 5 节是主链路（分类→鉴权→规则→沙箱→执行），§六–§八 是「围绕主链路的工程克制」，§十 把 Windows 路径作为对照实现单列。
+
 ## 一、命令语义分类：AI 执行的是什么类型的命令？
 
 BashTool 的第一个设计亮点是**命令语义分类**。它不是把所有命令一视同仁，而是在多个维度上对命令进行分类，每种分类决定了不同的 UI 展示和安全策略。

docs/14-Agent系统与SubAgent调用.md

@@ -21,6 +21,8 @@ Claude Code 的解决方案是**多 Agent 协作**：主 Agent 可以按需生
 
 ---
 
+> **章内导读**：§一 AgentDefinition 数据蓝图 → §二 `runAgent()` 完整生命周期 → §三 工具解析（能力边界）→ §四 内置 Agent 类型 → §五 Fork Subagent（共享上下文分支）→ §六 异步 Agent 生命周期 → §七 Agent 记忆 → §八 AgentSummary 后台摘要 → §九 可迁移模式。§一–§三 回答「Agent 是什么、怎么跑、能用什么工具」三件事；§四–§五 是两种不同的 Agent 形态；§六–§八 是围绕 Agent 的横切服务。
+
 ## 一、AgentDefinition：Agent 的数据蓝图
 
 ### 1.1 三种 Agent 类型

docs/16-任务模型与TaskType谱系.md

@@ -20,6 +20,8 @@
 
 ---
 
+> **章内导读**：§一 架构全景（Task 接口 + TaskState 类型）→ §二 framework.ts 与输出管理基础设施 → §三 任务类型详解 → §三点五 模型侧的入口（六个 Task*Tool）→ §四 任务通知机制 → §五 三种 Agent 协作模式 → §六 `createSubagentContext()` 上下文隔离 → §七 可迁移模式。§三点五是后插入的「读源码避坑」段，澄清 `AppState.tasks` 与 `utils/tasks.ts` TodoV2 是两套同名不同实质的体系。
+
 ## 一、架构全景：Task 接口与 TaskState 类型体系
 
 ### 1.1 核心抽象：三层分离设计

docs/18-MCP协议实现.md

@@ -19,6 +19,8 @@ Claude Code 的 MCP 实现涵盖了一个完整的客户端系统，需要解决
 
 ---
 
+> **章内导读**：§一 类型系统 → §二 两阶段配置加载 → §三 六种传输方式 → §四 并发连接调度 → §五 Tool 发现与代理 → §六 连接生命周期与重连 → §七 OAuth/XAA 认证 → §八 Agent 的 MCP 扩展 → §九 React 层的 MCPConnectionManager → §十 可迁移模式。§一–§三 是「协议落地」，§四–§六 是「连接管理」，§七–§九 是「认证与上层集成」。
+
 ## 一、类型系统设计：精确建模 MCP 的一切
 
 MCP 的类型定义集中在 `services/mcp/types.ts`（258 行），这个文件是整个 MCP 子系统的**数据契约层**。

docs/19-权限系统与远程权限回灌.md

@@ -20,6 +20,8 @@ Claude Code 的权限系统用 **多层防线 + 渐进式信任** 的方式解
 
 ---
 
+> **章内导读**：§一 权限模式（全局信任级别）→ §二 规则系统（allow/deny/ask）→ §三 `hasPermissionsToUseTool()` 决策管线 → §四 Auto Mode 与 AI Classifier → §五 文件路径验证 → §六 危险权限检测 → §七 Headless Agent → §八 可迁移模式 → §九 远程权限回灌。§一–§六 是「本地权限链」由模式→规则→决策→兜底分类器逐层下行；§九 是把这条链路通过 Bridge IPC 暴露给手机/Web 的最后一段。
+
 ## 一、权限模式：用户的全局信任级别
 
 ### 1.1 七种权限模式

docs/20-Hooks系统.md

@@ -12,6 +12,8 @@ Hooks 系统正是为此而生。它是 Claude Code 的"生命周期钩子"框
 
 ---
 
+> **章内导读**：§一 27 个生命周期事件 → §二 Event → Matcher → Hook 三层配置 → §三 执行引擎 → §四 Shell 命令链路 → §五 异步 Hook → §六 Prompt/Agent Hook（用 AI 验证 AI）→ §七 权限决策协议 → §八 三级安全管控 → §九 Frontmatter 注册 → §十 Fast Path 性能优化 → §十一 Prompt Elicitation 双向对话 → 可迁移模式。§一–§三 是骨架，§四–§六 是三种 hook command 类型逐一展开，§七–§十一 是横切关注点。
+
 ## 一、事件类型全景：27 个生命周期节点
 
 Hooks 系统定义了 **27 个事件类型**，覆盖了 AI 交互的完整生命周期。这些事件在 `entrypoints/sdk/coreSchemas.ts:355-383` 中以 `as const` 数组定义：

docs/21-Skill-Plugin-OutputStyle三扩展点.md

@@ -23,6 +23,8 @@ Hook 脚本 → Skill 文件 → Agent 定义 → Plugin 包
 
 ---
 
+> **章内导读**：§一 自定义 Skill → §二 自定义 Agent → §三 Plugin 系统架构 → §四 Hook 脚本 → §五 MCP Skill 桥接 → §六 Output Style 作为第三条扩展路径 → §七 实战示例 → §八 可迁移模式。本章按「扩展点从轻量到重量」组织：Skill → Agent → Plugin → Hook → MCP → Output Style。读完前六节后 §七 是一份可直接照抄的 walkthrough。
+
 ## 一、自定义 Skill 编写
 
 ### 1.1 目录结构与发现机制

docs/22-FeatureFlag与编译期优化.md

@@ -18,6 +18,8 @@ Claude Code 面临的正是这个问题。它的解决方案是**三层 Feature
 
 ---
 
+> **章内导读**：§一 编译期 `feature()` 与 DCE（含 90 个 flag 全景与分类速查表）→ §二 构建时身份常量 `USER_TYPE` → §三 `MACRO.*` 常量注入 → §四 运行时 GrowthBook A/B → §五 三层协同的完整门控链路 → §六 防止 flag 翻转破坏系统 → §七 可迁移模式。§一–§四 是「四层门控机制」分别展开，§五 把它们串成一条链路。
+
 ## 一、编译期：`feature()` 与 Dead Code Elimination
 
 ### 1.1 核心机制

docs/32-命令系统全景.md

@@ -20,6 +20,8 @@
 
 ---
 
+> **章内导读**：§一 Command 类型体系（三种执行模型）→ §二 命令聚合（六大来源统一注册）→ §三 Skill 加载（从 markdown 到 Command）→ §四 其他命令来源 → §五 SkillTool 桥接（命令如何被模型调用）→ §六 缓存与失效 → §七 特殊命令模式 → §八 可迁移模式。§一–§三 回答「命令长什么样、从哪来、Skill 怎么变成命令」，§四–§五 补全剩余来源与桥接，§六–§七 是支撑设施。
+
 ## 一、Command 类型体系：三种执行模型的统一
 
 ### 1.1 Command 联合类型

docs/33-状态管理与跨进程桥.md

@@ -17,6 +17,8 @@ Claude Code 的答案是：**三层状态架构 + 一个 35 行的自研 Store**
 
 ---
 
+> **章内导读**：§一 三层状态架构全景 → §二 第 1 层 `bootstrap/state.ts`（Session 全局）→ §三 第 2 层 Store + AppState（React 与非 React 的桥梁）→ §四 第 3 层 `ToolUseContext`（工具执行运行时）→ §五 一次状态变更的完整旅程 → §六 可迁移模式 → §七 第 4 层 `bridge/bridgePointer.ts`（跨进程）。前四层是单进程内的状态分层，§七 把这套机制延伸到「另一台机器接管同一会话」的跨进程场景。
+
 ## 一、三层状态架构全景
 
 在深入代码之前，先建立全局认知。Claude Code 的状态分布在三个层次，各有明确的职责边界：

docs/34-架构模式总结.md

@@ -10,6 +10,22 @@
 
 本章将切换视角：不再关注 Claude Code 特有的业务逻辑，而是提取那些**跨项目可复用的架构模式**。这 11 个模式覆盖了从编译期优化到运行时状态管理、从工具注册到安全防线、从跨进程桥接到配置演化的全栈设计决策。
 
+> **章内导读**：本章不再按模块走，而是把前 33 章里反复出现的 11 个设计模式抽出来。模式 1–3 是「编译与运行时基础设施」（DCE / Store / 工具注册表），模式 4–5 是「Prompt 与配置的合并策略」，模式 6–7 是「Agent 隔离与权限防线」，模式 8–9 是「跨进程与多 Agent 协作」，模式 10–11 是「演化与扩展接口」。最后一节给出 11 个模式之间的依赖图。
+
+## 回头看：从你敲下 claude 到这本书的终点
+
+在抽出 11 个模式之前，先用一段话把前 33 章的链路重走一遍——这也是这本书按运行期生命周期组织的内在动机。
+
+你敲下 `claude`（第 1–2 章入口形态与启动链路），CLI 在毫秒级完成冷启动；它读完七层 settings（第 3–4 章配置体系与迁移），把模型偏好、权限规则、CLAUDE.md 记忆都汇成一份运行时配置；REPL 起来，QueryEngine 与 `query()` 主循环开始转（第 5 章），System Prompt 在 Cache 安全的前提下被分段拼起来、Output Style 把尾巴让给你（第 6 章），上下文压缩家族在你看不见的地方按六条链路调度（第 7–8 章），thinking 与 effort 旋钮把推理深度调到合适的档位（第 9 章）。
+
+你按下回车说话。模型从一大堆工具里挑出一个：可能是 BashTool 跑一段命令（第 10–11 章）、FileEdit 改一份代码（第 12 章）、WebFetch 抓一段事实（第 13 章）；也可能它意识到事情更复杂，spawn 一个 sub-agent 去并行做（第 14–15 章），整套并发任务由 TaskType 谱系统一管理（第 16 章），甚至在你离开的时候由 Coordinator + Cron 自己继续推进（第 17 章）。
+
+每一次工具调用都要经过权限决策链——MCP 注册的外部工具走同一条 Tool 协议（第 18 章）、规则匹配与 AI Classifier 互相兜底（第 19 章）、27 个 Hook 事件点供你注入定制逻辑（第 20 章）；用户可以用 Skill / Plugin / Output Style 三种扩展点反过来用这套架构（第 21 章）；同一份源码在编译期被 feature flag 分裂出内部版与外部版两个产品（第 22 章）。
+
+网络层把 API 请求扛过不可靠的中间链路（第 23 章），Bridge IPC 把本地 CLI 暴露给手机和浏览器（第 24 章），DirectConnect 又把它接到企业上游代理上（第 25 章）。终端 UI 这一面，forked Ink 把 React 搬进黑底白字（第 26 章），设计系统、Vim、Voice、Buddy、Doctor、Output Style 各管一种「让 CLI 不像 CLI」的体验（第 27–30 章）。最后一公里是记忆与命令系统（第 31–32 章），以及把所有这些子系统钉在一起的状态管理与跨进程桥（第 33 章）。
+
+33 章一路下来，你已经把一个生产级 AI Agent 产品从冷启动到产出再到记忆持久化的完整链路走过了一遍。这一章要做的，是把途中反复出现的工程取舍抽出来——让你下次写自己的 AI 产品时，能直接拿走可迁移的那部分。
+
 ---
 
 ## 模式 1：编译期 DCE — 同一份代码构建多版本