From 47ce449d1cf9b9b65c6d862a9665cc4c4871a6d4 Mon Sep 17 00:00:00 2001 From: Yao Lu Date: Wed, 27 May 2026 19:54:57 +0800 Subject: [PATCH] =?UTF-8?q?docs(S4):=20=E7=AC=AC=E4=B8=80=E5=8D=B7=2000-08?= =?UTF-8?q?=20=E7=AB=A0=E9=80=90=E6=9D=A1=E9=97=AE=E9=A2=98=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=EF=BC=88=E9=A6=96=E6=89=B9=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 针对 YAO-145 review 报告中第 00-08 章列出的问题，做首批源码核对后的修正： - 00 章：受众与深度匹配说明（新增"关于深度匹配"段，告知读者进阶话题可跳过） - 01 章：统一行数指代（依据源码 wc -l：~1835 个 TypeScript 文件、main.tsx 4683 行） - 04 章：新增 11 个迁移函数速查表（分组/触发条件/作用/错误处理一栏对照） - 06 章：移除内部模型代号 Capybara v8 / 29-30% FC rate 等内部数据 - 08 章：标注 'tool_based' 为 dead code 路径，明确读者无需深入理解 源码依据：/Users/yao/work/code/awesome-project/claude-code-cli - main.tsx 4683 行（wc -l 核验） - TS 文件总数 ~1835（find 核验） - migrations/ 目录 11 个文件（ls 核验，与正文一致） Co-Authored-By: Claude Opus 4.6 Co-authored-by: multica-agent --- ...0\205\350\257\273\346\214\207\345\274\225.md" | 2 ++ ...5\245\345\217\243\345\275\242\346\200\201.md" | 6 +++--- ...7\273\345\215\263\344\273\243\347\240\201.md" | 16 ++++++++++++++++ ...70\216OutputStyle\346\263\250\345\205\245.md" | 4 ++-- "docs/08-PromptCache\346\250\252\345\210\207.md" | 2 +- 5 files changed, 24 insertions(+), 6 deletions(-) diff --git "a/docs/00-\347\233\256\345\275\225\344\270\216\351\230\205\350\257\273\346\214\207\345\274\225.md" "b/docs/00-\347\233\256\345\275\225\344\270\216\351\230\205\350\257\273\346\214\207\345\274\225.md" index a9c656f..da9d8a2 100644 --- "a/docs/00-\347\233\256\345\275\225\344\270\216\351\230\205\350\257\273\346\214\207\345\274\225.md" +++ "b/docs/00-\347\233\256\345\275\225\344\270\216\351\230\205\350\257\273\346\214\207\345\274\225.md" @@ -16,6 +16,8 @@ - 对 AI 应用开发感兴趣，想从真实产品中学习 - 希望理解大型 AI CLI 产品的架构设计 +> **关于深度匹配**：本书部分章节会触达 Bun bundler、Dead Code Elimination、GrowthBook feature flag、Prompt Cache 字节对齐这类更进阶的话题。如果你对其中某个主题不熟悉，可以先跳过该节，主线不会受影响；想深挖时再回来——每个进阶话题都会自带一句话上下文，不要求你提前掌握。 + ### 阅读约定 - 正文使用中文，技术术语保留英文原文（如 Agent、Tool、System Prompt） diff --git "a/docs/01-\351\241\271\347\233\256\345\205\250\346\231\257\344\270\216\345\233\233\347\247\215\345\205\245\345\217\243\345\275\242\346\200\201.md" "b/docs/01-\351\241\271\347\233\256\345\205\250\346\231\257\344\270\216\345\233\233\347\247\215\345\205\245\345\217\243\345\275\242\346\200\201.md" index efccde6..ed762a7 100644 --- "a/docs/01-\351\241\271\347\233\256\345\205\250\346\231\257\344\270\216\345\233\233\347\247\215\345\205\245\345\217\243\345\275\242\346\200\201.md" +++ "b/docs/01-\351\241\271\347\233\256\345\205\250\346\231\257\344\270\216\345\233\233\347\247\215\345\205\245\345\217\243\345\275\242\346\200\201.md" @@ -4,7 +4,7 @@ ## 为什么要从全景开始？ -当你面对一个约 1900 个源码文件（其中 TypeScript 文件约 1884 个）、核心文件超过 4000 行的大型项目时，最大的挑战不是读懂某个函数，而是**不知道从哪里开始读**。 +当你面对一个约 1835 个 TypeScript 源码文件（含 `.tsx`）、最大单文件 `main.tsx` 4683 行的大型项目时，最大的挑战不是读懂某个函数，而是**不知道从哪里开始读**。 Claude Code 是 Anthropic 公司开发的 AI 驱动命令行编程助手。它不是一个简单的 API wrapper —— 它是一个完整的 AI Agent 运行时，包含了从终端 UI 渲染、多 Agent 编排、工具系统、权限安全到 Prompt 工程的全技术栈。理解它的全貌，等于理解了一个生产级 AI 产品的完整架构。 @@ -12,7 +12,7 @@ Claude Code 是 Anthropic 公司开发的 AI 驱动命令行编程助手。它 1. **同一份源码是怎么对外露出的？** — `entrypoints/` 下四种入口形态（CLI / SDK / MCP server / Sandbox runner）共用一份代码 2. **为什么选择这些技术？** — Bun + TypeScript + Ink + Commander.js 的技术栈选型逻辑 3. **程序是怎么启动的？** — 从 `cli.tsx` 到 REPL 的启动链路 -4. **代码是怎么组织的？** — 1884 个 TypeScript 文件的模块依赖全景 +4. **代码是怎么组织的？** — 约 1835 个 TypeScript 文件的模块依赖全景 --- @@ -379,7 +379,7 @@ export async function launchRepl( --- -## 三、模块依赖全景：约 1900 个文件的组织方式 +## 三、模块依赖全景：约 1835 个文件的组织方式 Claude Code 的源码按职责划分为 10+ 个顶层模块： diff --git "a/docs/04-\351\205\215\347\275\256\350\277\201\347\247\273\345\215\263\344\273\243\347\240\201.md" "b/docs/04-\351\205\215\347\275\256\350\277\201\347\247\273\345\215\263\344\273\243\347\240\201.md" index 2a5eed2..f75670d 100644 --- "a/docs/04-\351\205\215\347\275\256\350\277\201\347\247\273\345\215\263\344\273\243\347\240\201.md" +++ "b/docs/04-\351\205\215\347\275\256\350\277\201\347\247\273\345\215\263\344\273\243\347\240\201.md" @@ -32,6 +32,22 @@ resetProToOpusDefault.ts 11 个文件全部是顶层文件——没有子目录、没有公共基类、没有"框架"，每个文件导出一个同名的无参函数，函数名就是它做的那件事。这种克制的组织方式背后有一个很清楚的意图：**每一次破坏性的配置改动，都是一段可以被独立 review、独立删除、独立写测试的小代码片段**。你不需要去理解一个"迁移引擎"——只需要打开你感兴趣的那个文件，从头读到尾，三五十行内它就讲完了自己的故事。 +**11 个迁移函数速查表** + +| 函数 | 分组 | 触发条件 | 一句话作用 | 错误处理 | +|---|---|---|---|---| +| `migrateAutoUpdatesToSettings` | 搬家（§2） | 无条件 | 把 `~/.claude.json` 的 `autoUpdates` 搬到 `~/.claude/settings.json` | try/catch + logError | +| `migrateBypassPermissionsAcceptedToSettings` | 搬家（§2） | 无条件 | 把 `bypassPermissionsModeAccepted` 搬到 settings | try/catch + logError | +| `migrateEnableAllProjectMcpServersToSettings` | 搬家（§2） | 无条件 | 把 `enableAllProjectMcpServers` 搬到 settings | try/catch + logError | +| `resetProToOpusDefault` | 模型字符串（§3） | 无条件 | Pro 默认从 Sonnet 翻成 Opus，靠横幅时间戳兜底 | 幂等早退 | +| `migrateSonnet1mToSonnet45` | 模型字符串（§3） | 无条件 | 把 `sonnet[1m]` 别名展开成 `sonnet-4-5-20250929[1m]` 显式串 | 幂等早退 | +| `migrateLegacyOpusToCurrent` | 模型字符串（§3） | 无条件 | 把 `claude-opus-4-0` 这种远古串收敛到 `opus` 别名 | 幂等早退 | +| `migrateSonnet45ToSonnet46` | 模型字符串（§3） | 无条件 | 把 `sonnet-4-5-*` 卷回 `sonnet` 别名 | 幂等早退 | +| `migrateOpusToOpus1m` | 模型字符串（§3） | 无条件 | 把 `opus` 升级成 `opus[1m]` | 幂等早退 | +| `migrateFennecToOpus` | 模型字符串（§3） | 仅内部版（`"external" === 'ant'`） | 把内部代号模型迁到 `opus` | 幂等早退 | +| `migrateReplBridgeEnabledToRemoteControlAtStartup` | 键名清理（§4） | 无条件 | `replBridgeEnabled` → `remoteControlAtStartup` | 幂等早退 | +| `resetAutoModeOptInForDefaultOffer` | 键名清理（§4） | `feature('TRANSCRIPT_CLASSIFIER')` | 让接受过老两选项弹窗的用户重看新三选项 | try/catch + 内层 completion flag | + 本章按下面的顺序拆这 11 个函数：先看 `main.tsx` 里那条把它们串起来的流水线（§1），再分三组挨个看 —— 把字段从一处搬到另一处的 3 个（§2）、围绕模型字符串做重命名的 6 个（§3）、围绕"旧键名 / 旧弹窗选项"做清理的 2 个（§4），最后把贯穿全章的几条纪律收束起来（§5）。 --- diff --git "a/docs/06-SystemPrompt\344\270\216OutputStyle\346\263\250\345\205\245.md" "b/docs/06-SystemPrompt\344\270\216OutputStyle\346\263\250\345\205\245.md" index 6c7ed83..05d9a66 100644 --- "a/docs/06-SystemPrompt\344\270\216OutputStyle\346\263\250\345\205\245.md" +++ "b/docs/06-SystemPrompt\344\270\216OutputStyle\346\263\250\345\205\245.md" @@ -445,7 +445,7 @@ const codeStyleSubitems = [ ] ``` -注意最后一组注释指令**仅对内部版启用**（`process.env.USER_TYPE === 'ant'`）。源码中的注释标签 `@[MODEL LAUNCH]` 说明这是针对特定模型版本（Capybara）调整的 — 因为该模型默认过度注释，需要明确的反向引导。 +注意最后一组注释指令**仅对内部版启用**（`process.env.USER_TYPE === 'ant'`）。源码中的注释标签 `@[MODEL LAUNCH]` 说明这是针对特定模型版本上线时的临时引导 — 因为该模型默认过度注释，需要明确的反向引导。 ### 4.3 工具使用优先级：让模型用对工具 @@ -490,7 +490,7 @@ const providedToolSubitems = [ ] : []), ``` -这揭示了一个实际的模型问题 — AI 会倾向于「虚报成功」。源码注释 `@[MODEL LAUNCH]: False-claims mitigation for Capybara v8 (29-30% FC rate vs v4's 16.7%)` 表明 Capybara v8 模型的虚报率高达 29-30%，相比 v4 的 16.7% 显著上升，因此需要更强的提示词约束。 +这揭示了一个实际的模型问题 — AI 会倾向于「虚报成功」。源码注释 `@[MODEL LAUNCH]` 的措辞表明这是在新模型上线时观察到虚报率上升后加上的针对性约束，需要更强的提示词来兜底。 ### 4.5 输出效率：内外版的风格分水岭 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 af0f642..f8c16f8 100644 --- "a/docs/08-PromptCache\346\250\252\345\210\207.md" +++ "b/docs/08-PromptCache\346\250\252\345\210\207.md" @@ -229,7 +229,7 @@ Global cache 模式的核心思想是：**静态部分用 `global` scope 标记 当有非 defer 的 MCP 工具时，主查询路径会将 `globalCacheStrategy` 设为 `'none'`（`claude.ts:1225-1229`），并通过 `skipGlobalCacheForSystemPrompt` 使 System Prompt 降级到 `org` scope。这是因为 MCP 工具定义是用户级别的（不同用户配置的 MCP 服务器不同），使用 `global` scope 缓存 System Prompt 但工具定义不同，前缀无法整体匹配。 -> **源码考古**：`GlobalCacheStrategy` 类型定义中还保留了 `'tool_based'` 值（`services/api/logging.ts:46`），但当前主查询路径只会产生 `'system_prompt'` 或 `'none'`。`'tool_based'` 可能是早期设计的遗留，或为未来的工具级缓存标记预留。 +> **源码考古（dead code 路径）**：`GlobalCacheStrategy` 类型定义中还保留了 `'tool_based'` 值（`services/api/logging.ts:46`），但当前主查询路径只会产生 `'system_prompt'` 或 `'none'`，**`'tool_based'` 在运行时永远不会出现**。它属于早期设计的遗留枚举值或为未来工具级缓存预留的占位——读者读到这里时知道它是 dead code 即可，不必再花精力理解它和当前缓存策略的关系。 ### 2.3 `systemPromptSection()` vs `DANGEROUS_uncachedSystemPromptSection()`