From 5865ca7ff75bc245cf305a44ee1febcf733f6cbf Mon Sep 17 00:00:00 2001 From: luyao618 <364939526@qq.com> Date: Thu, 28 May 2026 01:39:17 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=95=BF=E7=AB=A0=E8=A1=A5=E3=80=8C?= =?UTF-8?q?=E7=AB=A0=E5=86=85=E5=AF=BC=E8=AF=BB=E3=80=8D+=20=E7=BB=88?= =?UTF-8?q?=E7=AB=A0=E8=A1=A5=E3=80=8C=E5=9B=9E=E5=A4=B4=E7=9C=8B=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 事件 1：≥800 行的 13 章统一在「## 一、...」第一节前补一段 > **章内导读**：§一 ... → §二 ... → ... 块，给读者一条「这一章我要怎么走」的明示路径。 涵盖：08/09/11/14/16/18/19/20/21/22/32/33/34。 事件 3：第 34 章（终章）补一段「回头看：从你敲下 claude 到这本书的终点」， 按运行期生命周期把前 33 章串成一条 300+ 字的回顾链路，再进入 11 个模式提炼。 不改正文实质，只动模板段（最小修改原则）。 Co-Authored-By: Claude Opus 4.6 --- "docs/08-PromptCache\346\250\252\345\210\207.md" | 2 ++ .../09-Thinking-Effort-\344\270\216-Advisor.md" | 2 ++ ...BashTool-PowerShellTool-\345\217\214shell.md" | 2 ++ ...4\270\216SubAgent\350\260\203\347\224\250.md" | 2 ++ ...4\270\216TaskType\350\260\261\347\263\273.md" | 2 ++ ...5\217\350\256\256\345\256\236\347\216\260.md" | 2 ++ ...5\203\351\231\220\345\233\236\347\201\214.md" | 2 ++ "docs/20-Hooks\347\263\273\347\273\237.md" | 2 ++ ...0\211\346\211\251\345\261\225\347\202\271.md" | 2 ++ ...7\221\346\234\237\344\274\230\345\214\226.md" | 2 ++ ...3\273\347\273\237\345\205\250\346\231\257.md" | 2 ++ ...7\250\350\277\233\347\250\213\346\241\245.md" | 2 ++ ...0\241\345\274\217\346\200\273\347\273\223.md" | 16 ++++++++++++++++ 13 files changed, 40 insertions(+) diff --git "a/docs/08-PromptCache\346\250\252\345\210\207.md" "b/docs/08-PromptCache\346\250\252\345\210\207.md" index f8c16f8..d1a8c68 100644 --- "a/docs/08-PromptCache\346\250\252\345\210\207.md" +++ "b/docs/08-PromptCache\346\250\252\345\210\207.md" @@ -17,6 +17,8 @@ Anthropic 的 Prompt Caching 机制可以将 **重复前缀** 的成本降低 90 --- +> **章内导读**：§一 缓存基本原理与标记策略 → §二 System Prompt 分块 → §三 Cached Microcompact → §四 Fork Agent 的 CacheSafeParams → §五 缓存失效检测 → §六 全景图 → §七 可迁移模式。前五节按缓存的「生命周期」展开（建立→分块→保护→共享→失效），第六节横切总览，第七节抽出可复用模式。 + ## 一、Prompt Cache 的基本原理与标记策略 ### 1.1 `cache_control` 标记：告诉 API "请缓存到这里" diff --git "a/docs/09-Thinking-Effort-\344\270\216-Advisor.md" "b/docs/09-Thinking-Effort-\344\270\216-Advisor.md" index ab38bf1..b42a389 100644 --- "a/docs/09-Thinking-Effort-\344\270\216-Advisor.md" +++ "b/docs/09-Thinking-Effort-\344\270\216-Advisor.md" @@ -19,6 +19,8 @@ Claude Code 面对的工程挑战是：**如何让用户（和系统）灵活地 --- +> **章内导读**：§一/§二 Extended Thinking（三种模式 + API 注入）→ §三 Effort 级别 → §四 Ultrathink 触发 → §五 Advisor 审阅 → §六/§七 Thinking 流式与 Side Query → §八 四子系统协作全景 → 番外 PromptSuggestion → §九 可迁移模式。本章是「四个相关但独立的推理控制旋钮」并列展开，按 §八 的全景图回头看，能把 §一–§五 串起来。 + ## 一、ThinkingConfig — Extended Thinking 的三种模式 ### 1.1 类型定义 diff --git "a/docs/11-BashTool-PowerShellTool-\345\217\214shell.md" "b/docs/11-BashTool-PowerShellTool-\345\217\214shell.md" index e1f59d8..bed1455 100644 --- "a/docs/11-BashTool-PowerShellTool-\345\217\214shell.md" +++ "b/docs/11-BashTool-PowerShellTool-\345\217\214shell.md" @@ -29,6 +29,8 @@ --- +> **章内导读**：§一 命令语义分类（让 AI 知道自己在跑什么）→ §二 权限主链路 `bashToolHasPermission` → §三 规则匹配与建议 → §四 沙箱执行 → §五 执行与输出处理 → §六 Prompt 工程 → §七 sed 特例 → §八 破坏性命令警告 → §九 可迁移模式 → §十 PowerShellTool 对照。前 5 节是主链路（分类→鉴权→规则→沙箱→执行），§六–§八 是「围绕主链路的工程克制」，§十 把 Windows 路径作为对照实现单列。 + ## 一、命令语义分类：AI 执行的是什么类型的命令？ BashTool 的第一个设计亮点是**命令语义分类**。它不是把所有命令一视同仁，而是在多个维度上对命令进行分类，每种分类决定了不同的 UI 展示和安全策略。 diff --git "a/docs/14-Agent\347\263\273\347\273\237\344\270\216SubAgent\350\260\203\347\224\250.md" "b/docs/14-Agent\347\263\273\347\273\237\344\270\216SubAgent\350\260\203\347\224\250.md" index bc57060..ba444e5 100644 --- "a/docs/14-Agent\347\263\273\347\273\237\344\270\216SubAgent\350\260\203\347\224\250.md" +++ "b/docs/14-Agent\347\263\273\347\273\237\344\270\216SubAgent\350\260\203\347\224\250.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 类型 diff --git "a/docs/16-\344\273\273\345\212\241\346\250\241\345\236\213\344\270\216TaskType\350\260\261\347\263\273.md" "b/docs/16-\344\273\273\345\212\241\346\250\241\345\236\213\344\270\216TaskType\350\260\261\347\263\273.md" index 9f66ee9..ab568d2 100644 --- "a/docs/16-\344\273\273\345\212\241\346\250\241\345\236\213\344\270\216TaskType\350\260\261\347\263\273.md" +++ "b/docs/16-\344\273\273\345\212\241\346\250\241\345\236\213\344\270\216TaskType\350\260\261\347\263\273.md" @@ -20,6 +20,8 @@ --- +> **章内导读**：§一 架构全景（Task 接口 + TaskState 类型）→ §二 framework.ts 与输出管理基础设施 → §三 任务类型详解 → §三点五 模型侧的入口（六个 Task*Tool）→ §四 任务通知机制 → §五 三种 Agent 协作模式 → §六 `createSubagentContext()` 上下文隔离 → §七 可迁移模式。§三点五是后插入的「读源码避坑」段，澄清 `AppState.tasks` 与 `utils/tasks.ts` TodoV2 是两套同名不同实质的体系。 + ## 一、架构全景：Task 接口与 TaskState 类型体系 ### 1.1 核心抽象：三层分离设计 diff --git "a/docs/18-MCP\345\215\217\350\256\256\345\256\236\347\216\260.md" "b/docs/18-MCP\345\215\217\350\256\256\345\256\236\347\216\260.md" index 17c6c75..1e8c20b 100644 --- "a/docs/18-MCP\345\215\217\350\256\256\345\256\236\347\216\260.md" +++ "b/docs/18-MCP\345\215\217\350\256\256\345\256\236\347\216\260.md" @@ -19,6 +19,8 @@ Claude Code 的 MCP 实现涵盖了一个完整的客户端系统，需要解决 --- +> **章内导读**：§一 类型系统 → §二 两阶段配置加载 → §三 六种传输方式 → §四 并发连接调度 → §五 Tool 发现与代理 → §六 连接生命周期与重连 → §七 OAuth/XAA 认证 → §八 Agent 的 MCP 扩展 → §九 React 层的 MCPConnectionManager → §十 可迁移模式。§一–§三 是「协议落地」，§四–§六 是「连接管理」，§七–§九 是「认证与上层集成」。 + ## 一、类型系统设计：精确建模 MCP 的一切 MCP 的类型定义集中在 `services/mcp/types.ts`（258 行），这个文件是整个 MCP 子系统的**数据契约层**。 diff --git "a/docs/19-\346\235\203\351\231\220\347\263\273\347\273\237\344\270\216\350\277\234\347\250\213\346\235\203\351\231\220\345\233\236\347\201\214.md" "b/docs/19-\346\235\203\351\231\220\347\263\273\347\273\237\344\270\216\350\277\234\347\250\213\346\235\203\351\231\220\345\233\236\347\201\214.md" index 37558d6..e6e807d 100644 --- "a/docs/19-\346\235\203\351\231\220\347\263\273\347\273\237\344\270\216\350\277\234\347\250\213\346\235\203\351\231\220\345\233\236\347\201\214.md" +++ "b/docs/19-\346\235\203\351\231\220\347\263\273\347\273\237\344\270\216\350\277\234\347\250\213\346\235\203\351\231\220\345\233\236\347\201\214.md" @@ -20,6 +20,8 @@ Claude Code 的权限系统用 **多层防线 + 渐进式信任** 的方式解 --- +> **章内导读**：§一 权限模式（全局信任级别）→ §二 规则系统（allow/deny/ask）→ §三 `hasPermissionsToUseTool()` 决策管线 → §四 Auto Mode 与 AI Classifier → §五 文件路径验证 → §六 危险权限检测 → §七 Headless Agent → §八 可迁移模式 → §九 远程权限回灌。§一–§六 是「本地权限链」由模式→规则→决策→兜底分类器逐层下行；§九 是把这条链路通过 Bridge IPC 暴露给手机/Web 的最后一段。 + ## 一、权限模式：用户的全局信任级别 ### 1.1 七种权限模式 diff --git "a/docs/20-Hooks\347\263\273\347\273\237.md" "b/docs/20-Hooks\347\263\273\347\273\237.md" index 0b48e85..4954b2e 100644 --- "a/docs/20-Hooks\347\263\273\347\273\237.md" +++ "b/docs/20-Hooks\347\263\273\347\273\237.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` 数组定义： diff --git "a/docs/21-Skill-Plugin-OutputStyle\344\270\211\346\211\251\345\261\225\347\202\271.md" "b/docs/21-Skill-Plugin-OutputStyle\344\270\211\346\211\251\345\261\225\347\202\271.md" index 812fda6..47e8720 100644 --- "a/docs/21-Skill-Plugin-OutputStyle\344\270\211\346\211\251\345\261\225\347\202\271.md" +++ "b/docs/21-Skill-Plugin-OutputStyle\344\270\211\346\211\251\345\261\225\347\202\271.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 目录结构与发现机制 diff --git "a/docs/22-FeatureFlag\344\270\216\347\274\226\350\257\221\346\234\237\344\274\230\345\214\226.md" "b/docs/22-FeatureFlag\344\270\216\347\274\226\350\257\221\346\234\237\344\274\230\345\214\226.md" index d539fec..94b86a0 100644 --- "a/docs/22-FeatureFlag\344\270\216\347\274\226\350\257\221\346\234\237\344\274\230\345\214\226.md" +++ "b/docs/22-FeatureFlag\344\270\216\347\274\226\350\257\221\346\234\237\344\274\230\345\214\226.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 核心机制 diff --git "a/docs/32-\345\221\275\344\273\244\347\263\273\347\273\237\345\205\250\346\231\257.md" "b/docs/32-\345\221\275\344\273\244\347\263\273\347\273\237\345\205\250\346\231\257.md" index b73948d..1e00753 100644 --- "a/docs/32-\345\221\275\344\273\244\347\263\273\347\273\237\345\205\250\346\231\257.md" +++ "b/docs/32-\345\221\275\344\273\244\347\263\273\347\273\237\345\205\250\346\231\257.md" @@ -20,6 +20,8 @@ --- +> **章内导读**：§一 Command 类型体系（三种执行模型）→ §二 命令聚合（六大来源统一注册）→ §三 Skill 加载（从 markdown 到 Command）→ §四 其他命令来源 → §五 SkillTool 桥接（命令如何被模型调用）→ §六 缓存与失效 → §七 特殊命令模式 → §八 可迁移模式。§一–§三 回答「命令长什么样、从哪来、Skill 怎么变成命令」，§四–§五 补全剩余来源与桥接，§六–§七 是支撑设施。 + ## 一、Command 类型体系：三种执行模型的统一 ### 1.1 Command 联合类型 diff --git "a/docs/33-\347\212\266\346\200\201\347\256\241\347\220\206\344\270\216\350\267\250\350\277\233\347\250\213\346\241\245.md" "b/docs/33-\347\212\266\346\200\201\347\256\241\347\220\206\344\270\216\350\267\250\350\277\233\347\250\213\346\241\245.md" index eaaf33f..7d536b2 100644 --- "a/docs/33-\347\212\266\346\200\201\347\256\241\347\220\206\344\270\216\350\267\250\350\277\233\347\250\213\346\241\245.md" +++ "b/docs/33-\347\212\266\346\200\201\347\256\241\347\220\206\344\270\216\350\267\250\350\277\233\347\250\213\346\241\245.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 的状态分布在三个层次，各有明确的职责边界： diff --git "a/docs/34-\346\236\266\346\236\204\346\250\241\345\274\217\346\200\273\347\273\223.md" "b/docs/34-\346\236\266\346\236\204\346\250\241\345\274\217\346\200\273\347\273\223.md" index 600b9d1..578bf34 100644 --- "a/docs/34-\346\236\266\346\236\204\346\250\241\345\274\217\346\200\273\347\273\223.md" +++ "b/docs/34-\346\236\266\346\236\204\346\250\241\345\274\217\346\200\273\347\273\223.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 — 同一份代码构建多版本