claude-code/docs-outline-draft.md

Claude Code（反编译重建版）文档大纲

这份文档分两个视角并行展开：产品文档面向"想让工具跑起来并融入日常工作流"的使用者，按用户旅程组织；开发者设计探秘面向想理解内部原理、挖掘决策背后动机的工程师，按"被约束逼出的设计链"组织。两者覆盖同一套代码，但章节切分、措辞、锚点指向各不相同，让不同读者按自己的路径进入。

---

第一部分：产品文档大纲（使用者视角）

按"安装 → 配置 → 日常 → 扩展 → 进阶 → 排错"线性旅程组织。每章标题呼应用户想做什么，而非工具有什么。

1. 第一章：从零开始 —— 安装、首次启动与环境要求

章节摘要：把工具装到本机，跑通第一次对话。覆盖 Bun 运行时、Node.js 兼容产物、dev/build 两种使用方式，以及首次启动的信任对话框与初始化流程。

子章节：

• 我需要先装什么？Bun 与 Node.js 的取舍
• 三种安装方式：bun run dev、构建产物 dist/cli.js、Vite 构建链
• 第一次启动会发生什么：trust dialog、init 流程、telemetry 询问
• 快速路径命令一览（--version / -v / --help）
• 把 claude 设为全局命令：cli-bun.js 与 cli-node.js 双入口
• 环境自检：bun run health 与 claude doctor

锚点：

• docs/getting-started/installation.mdx
• docs/getting-started/quickstart.mdx
• src/entrypoints/cli.tsx、src/entrypoints/init.ts
• build.ts、scripts/dev.ts
• 命令：bun run dev / bun run build / bun run health / claude doctor / claude --version

2. 第二章：让 Claude 听你的 —— 配置 Provider 与模型

章节摘要：回答"我用哪家 API？"这个最高频问题。覆盖 7 个 Provider 的切换方式、引导式登录、环境变量清单，以及"为什么我切了 Provider 没生效"和"我改了 key 为什么没生效"两个高频排错。

子章节：

• 一张表看懂 7 个 Provider：Anthropic / OpenAI 兼容 / Gemini / Grok / Bedrock / Vertex / Foundry
• 三种切换方式：/provider 命令、/login 引导式登录、CLAUDE_CODE_USE_* 环境变量
• 中国 LLM 引导式登录：DeepSeek / 智谱 GLM / 通义千问 / Moonshot / Cerebras / Groq
• 用 ChatGPT 订阅当后端：OPENAI_AUTH_MODE=chatgpt 的设备码流程、~/.claude/openai-chatgpt-auth.json 凭证存储、与 Codex CLI 跨工具共享 ~/.codex/auth.json、5 分钟刷新偏差窗口
• 每个 Provider 的 key 配置清单（OPENAI_API_KEY / GEMINI_API_KEY / GROK_API_KEY 或 XAI_API_KEY / AWS_REGION / ANTHROPIC_VERTEX_PROJECT_ID / ANTHROPIC_FOUNDRY_*）
• 模型映射是怎么决定的：PROVIDER_MODEL > PROVIDER_DEFAULT_{FAMILY}_MODEL > ANTHROPIC_DEFAULT_* > 默认表
• 为什么切了 Provider 没生效？modelType 优先级、/provider unset 只清 Provider 不清 key、isFirstPartyAnthropicBaseUrl() TODO 陷阱（只设 OPENAI_BASE_URL 没设 ANTHROPIC_BASE_URL 会让 firstParty 行为泄漏）
• 我改了 API key 但没生效？ —— 模块级 client cache 陷阱：getOpenAIClient()/getGrokClient() 会话级缓存客户端实例，中途改 key 必须重启或调用 clearOpenAIClientCache()
• 本地模型与自托管端点：Ollama / vLLM / DeepSeek 自托管
• DeepSeek 思维模式自动检测与三格式注入；为什么必须回显 reasoning_content: ''（空字符串），否则下一次请求会被 400 拒绝
• /effort 与 CLAUDE_CODE_EFFORT_LEVEL 的取值语义：low / medium / high / xhigh 四档，以及它在 ChatGPT Responses API 上如何落地为 reasoning.effort 参数

锚点：

• docs/getting-started/model-providers.mdx
• src/commands/provider.ts、src/commands/login/login.tsx
• src/components/ConsoleOAuthFlow.tsx、src/utils/chinaLlmProviders.ts
• src/utils/model/providers.ts
• src/services/api/openai/、src/services/api/gemini/、src/services/api/grok/
• src/services/api/openai/client.ts:39（getOpenAIClient 模块级缓存）
• src/services/api/openai/responsesAdapter.ts（Responses API 适配器）
• src/services/api/client.ts（isFirstPartyAnthropicBaseUrl 陷阱）
• src/services/providerUsage/adapters/openai.ts:62（限流响应头解析）
• 命令：/provider <name> / /provider unset / /login / /model / /effort

3. 第三章：日常对话 —— 交互式 REPL 怎么用

章节摘要：装好之后每天打开 claude 会做什么。覆盖发消息、看流式回复、中断、恢复会话、切模型、切权限模式、查看 token 消耗等高频日常操作。

子章节：

• 发消息、看流式回复、Esc 中断、Ctrl+C 退出
• 会话怎么持久化：恢复上一次对话（/resume）、查看历史（/history）、清空上下文（/clear）
• 切换模型与思考强度：/model、/effort（low/medium/high/xhigh）、ultrathink 触发词
• 权限模式：默认询问 / 自动批准 / 全部拒绝 / sandbox 切换
• 看 token 与费用：/cost、/usage、/stats、状态栏显示
• 上下文管理与自动压缩：/compact、自动 compact 触发条件、/force-snip 强制剪裁
• 把对话导出与分享：/export、/share、/summary，各自的产物格式与隐私边界（谁会看到什么、是否包含凭证）
• 更换主题、输出风格、语言：/theme、/output-style、/lang
• 配置项目记忆：CLAUDE.md 与 @include 指令、/memory 命令

锚点：

• src/screens/REPL.tsx、src/query.ts、src/QueryEngine.ts、src/context.ts、src/utils/claudemd.ts
• src/commands/clear/、compact/、cost/、usage/、history/、resume/、model/、effort/、mode/、memory/、export/、share/、theme/
• 命令：claude / claude -p '...' / claude --resume

4. 第四章：slash 命令速查 —— 不用记全部，按场景找

章节摘要：把上百个 slash 命令按"我想做什么"分类，让用户能快速找到自己需要的那一个，而不是背诵命令清单。

子章节：

• 会话与上下文类：/clear /compact /resume /history /context /rewind /force-snip
• 模型与 Provider 类：/model /provider /effort /login /logout
• 费用与限额类：/cost /usage /stats /rate-limit-options（待核实是否存在） /reset-limits（待核实是否存在）；实际机制是通过响应头 x-ratelimit-*-requests/tokens 与 Reset-After 自动追踪限流
• 配置与个性化类：/theme /output-style /lang /keybindings /config /env
• 项目与文件类：/add-dir /files /diff /context /ctx_viz
• 插件与扩展类：/plugin /skills /skill-store /reload-plugins /hooks
• 工作流自动化类：/commit /commit-push-pr /review /plan /schedule /loop
• 诊断与帮助类：/help /doctor /status /version /feedback
• 隐藏与实验类：/bughunter /advisor /insights /thinkback /torch

锚点：

• src/commands/、src/commands/help/、doctor/、config/、env/
• 命令：/help / claude <cmd> --help
• 注意：/rate-limit-options 与 /reset-limits 在 findings 中没有对应锚点，应标记为"待核实是否存在"，或替换为已验证的"通过响应头追踪限流"机制

5. 第五章：扩展 Claude 的能力 —— MCP Server、插件、Skill

章节摘要：当内置工具不够用时怎么办。覆盖接入现成 MCP server、自己写一个、安装社区插件、用 Skill 沉淀工作流。

子章节：

• MCP 是什么？什么时候应该用 MCP 而不是普通工具
• 用 claude mcp add 接入现成 MCP server（stdio / SSE / HTTP）
• 管理已接入的 server：claude mcp list / remove / serve
• MCP OAuth 简化流程与认证（/mcp-auth）
• 自己写一个 MCP server 的最小骨架
• Computer Use / Chrome 控制 / 语音输入这些内置 MCP 怎么开
• 插件系统：/plugin 浏览、安装、启用、禁用、卸载
• Marketplace 浏览与插件市场
• Skill 是什么？/skills 与 /skill-store 的区别
• 怎么写一个自己的 Skill 并复用
• Skill 搜索与延迟工具加载：SearchExtraTools 与 ExecuteExtraTool

锚点：

• docs/features/tools/
• docs/features/external/chrome-control.md、computer-use.md、voice-mode.md、web-browser-tool.md
• src/commands/mcp/、plugin/、skills/、skill-store/、skill-search/
• src/services/searchExtraTools/
• packages/@ant/computer-use-mcp/、packages/@ant/claude-for-chrome-mcp/
• 命令：claude mcp add/list/remove/serve / /plugin / /skills / /skill-store

6. 第六章：让 Claude 帮你跑大任务 —— 子代理、Plan 模式、Task 系统

章节摘要：当任务超过单次对话、需要并行或分阶段执行时怎么办。覆盖 Agent 工具、Task 系统、Plan 模式、worktree 隔离。

子章节：

• 什么时候该派子代理？单线程 vs 并行 vs 分阶段
• Agent 工具：在对话里 spawn 一个子代理处理子任务
• Task 系统：TaskCreate / TaskUpdate / TaskList / TaskGet 管理任务清单
• Plan 模式：先想清楚再动手（/plan、EnterPlanMode、ExitPlanModeV2、VerifyPlanExecution）
• Goal 命令：给定目标后让 Claude 自主推进（/goal）
• Worktree 隔离：在独立 git worktree 里跑实验性改动
• Coordinator 模式：多 worker 协作（COORDINATOR_MODE feature）
• Workflow 脚本：把多步工作流固化成可重放脚本（/workflows）
• Ultra-batch 与 dispatching-parallel-agents Skill 的取舍

锚点：

• docs/features/agents/
• packages/agent-tools/
• packages/builtin-tools/src/tools/AgentTool/、TaskCreateTool/、EnterPlanModeTool/、EnterWorktreeTool/
• src/commands/plan/、goal/、workflows/、coordinator.ts
• Skill：ultra-batch / dispatching-parallel-agents / experiment-driven-research

7. 第七章：让 Claude 长时间帮你干活 —— Daemon、Background Sessions、Schedule

章节摘要：当任务需要小时级持续运行、定时触发、或后台并行多个会话时怎么办。覆盖 daemon 模式、bg sessions、cron/schedule、loop。

子章节：

• Daemon 是什么？跟普通 REPL 的区别（长驻 supervisor + worker）
• 启停 daemon：claude daemon start/stop/bg/attach/logs/kill/status
• --daemon-worker=<kind> 精简 worker 的用途
• Background Sessions：claude --bg / claude ps / claude attach / claude kill
• Template Jobs：claude job new/list/reply 模板化任务
• 定时调度：/schedule 创建远程 cron 触发器、/loop 本地循环、cron-list / cron-delete
• 用 /loop 让 Claude 每 N 分钟自动跑一次任务
• Schedule 触发器与 RCS 的关系
• 什么时候该用 daemon，什么时候用 background session，什么时候用 schedule

锚点：

• src/daemon/、src/commands/daemon/、attach/、tasks/、job/、schedule/、loop
• Skill：loop / cron-list / cron-delete / schedule
• 命令：claude daemon <subcmd> / claude --bg / claude ps / claude attach / claude kill

8. 第八章：跨机器与跨团队协作 —— Bridge、Remote Control、ACP

章节摘要：当 Claude 需要跑在远程机器、被外部客户端调用、或接入 IDE/团队工具时怎么办。覆盖 Bridge 模式、自托管 RCS、ACP 协议、IDE 桥接。

子章节：

• Bridge 模式是什么？什么时候启用（BRIDGE_MODE feature）
• Remote Control 快速路径：claude remote-control / rc / remote / sync / bridge
• 自托管 RCS：Docker 部署、Web UI 控制面板、bun run rcs
• RCS Web UI：会话管理、ACP agent 接入、SSE 事件流
• ACP 协议：把 Claude Code 暴露成 ACP agent（claude --acp）
• ACP 权限管道与 session/update plan 可视化
• acp-link：WebSocket 客户端桥接到 ACP agent
• IDE 桥接：VS Code 集成（vscode-ide-bridge/、/ide 命令）
• SSH 远程模式：SSH_REMOTE feature 与 /remote-setup、/remote-env
• 与 Codex CLI 跨工具凭证共享（~/.codex/auth.json、~/.claude/openai-chatgpt-auth.json）

锚点：

• docs/features/modes/remote-control-self-hosting.md
• docs/features/agents/acp.md、pipes-and-lan.md
• src/bridge/、src/services/acp/
• packages/remote-control-server/、packages/acp-link/、vscode-ide-bridge/
• src/commands/bridge/、remoteControlServer/、remote-setup/、remote-env/、ide/
• 命令：claude remote-control / claude rc / claude bridge / claude --acp / bun run rcs

9. 第九章：省钱、提速、定制 —— 穷鬼模式、缓存、Hooks、配置文件

章节摘要：当 token 账单偏高、响应偏慢、或想让 Claude 自动响应某些事件时怎么办。覆盖穷鬼模式、prompt 缓存、hooks、settings.json、keybindings，以及权限规则写作指南。

子章节：

• 穷鬼模式（/poor）：跳过 extract_memories / prompt_suggestion / verification_agent，对各 Provider 都生效（含兼容层），持久化到 settings.json
• Prompt 缓存怎么工作？缓存断点检测（PROMPT_CACHE_BREAK_DETECTION）
• Token 预算管理：TOKEN_BUDGET feature 与 /cost 联动
• Hooks：在 settings.json 里写"每次 X 发生就执行 Y"
• settings.json vs settings.local.json：团队共享 vs 个人覆盖
• CLAUDE.md 四层层级与优先级：Managed / User / Project / Local
• @include 指令：在 CLAUDE.md 里引用其他文件
• keybindings.json：自定义快捷键与 chord
• 权限规则配置指南：allow / deny 规则的具体语法（含工具名匹配、glob 模式、规则优先级）、/permissions 命令、沙箱模式与 bypassPermissions 在非 root/sandbox 环境的可用性检测
• Feature flag 运行时开关：FEATURE_<NAME>=1，以及已知禁用清单（CONTEXT_COLLAPSE / HISTORY_SNIP / FORK_SUBAGENT / UDS_INBOX / LAN_PIPES / REVIEW_ARTIFACT / SKILL_LEARNING / TEAMMEM）与启用后果

锚点：

• src/commands/poor/poorMode.ts
• src/commands/hooks/、permissions/、config/、keybindings/
• src/utils/claudemd.ts、src/context.ts
• Skill：update-config / keybindings-help
• 命令：/poor / /hooks / /config / /permissions / /env

10. 第十章：可观测性与排错 —— 卡住了怎么办

章节摘要：当 Claude 报错、卡住、行为异常或想理解它在做什么时怎么办。覆盖 doctor、debug、日志、Langfuse 追踪、常见错误对照表。

子章节：

• 第一步永远先跑：claude doctor 与 bun run health
• Provider 报错对照表：401（key 无效） / 403（地区限制） / 429（限流，看 x-ratelimit-* 头与 Reset-After） / overloaded_error（1305 / 上游过载） / 模型不存在
• OpenAI/Gemini/Grok 兼容层特有坑：模型映射失败（Gemini 硬抛异常）、reasoning_content 缺失导致 DeepSeek 400、限流响应头解析
• Bedrock Opus 4.7 的 400 错误与 anthropic_beta 体剥离补丁：何时打、SDK 升级后如何通过 scripts/probe-bedrock-beta-fix.ts 检测是否还需要
• MCP server 连不上：stdio 路径、SSE 超时、OAuth 失败排查清单
• 权限被拒、工具被禁用、deferred tool 没加载
• 内存膨胀与长会话：performanceShim、clearMarks、/compact、/force-snip
• 调试模式：BUN_INSPECT=<port>、--dump-system-prompt、/debug-tool-call
• Langfuse 追踪：每次查询的 provider 字段（openai / gemini / grok / getAPIProvider()）与 recordLLMObservation
• 导出会话给同事看：/export、/share、/recap 的产物格式与隐私边界
• 反馈与上报 bug：/feedback、/perf-issue、/bughunter
• 已知禁用的 feature flag 清单与启用后果

锚点：

• docs/features/tools/langfuse-monitoring.md
• src/commands/doctor/、debug-tool-call/、feedback/、perf-issue/、heapdump/
• src/utils/performanceShim.ts
• src/services/api/bedrockClient.ts:29
• src/services/providerUsage/adapters/openai.ts:62
• scripts/probe-bedrock-beta-fix.ts
• 命令：claude doctor / bun run health / BUN_INSPECT=9229 bun run dev:inspect / claude --dump-system-prompt

11. 第十一章：自动化与 CI 集成 —— 把 Claude 嵌入流水线

章节摘要：当想在 CI、脚本、cron、容器里无交互调用 Claude 时怎么办。覆盖 pipe 模式、headless、BYOC runner、容器环境变量、与 ACP/Bridge 的交汇点。

子章节：

• Pipe 模式：echo '...' | claude -p 一次性调用
• Headless 模式：无 TTY 环境下的行为差异
• BYOC runner：claude environment-runner / claude self-hosted-runner（与第八章 ACP、Bridge 的交汇点）
• 容器环境：CLAUDE_CODE_REMOTE=true 自动调内存上限（--max-old-space-size=8192）
• CLAUDE_CODE_FORCE_INTERACTIVE：嵌套 bun 启动的 TTY 欺骗
• CLAUDE_CODE_ABLATION_BASELINE：L0 消融基线的用途
• 在 GitHub Actions 里跑 claude（install-github-app、subscribe-pr、commit-push-pr）
• 定时任务：用 /schedule 或 cron + pipe 实现巡检
• 退出码与 pipe-status：脚本里判断成功失败

锚点：

• src/entrypoints/cli.tsx
• src/commands/pipe-status/、install-github-app/、subscribe-pr/、commit-push-pr.ts
• 命令：claude -p / claude environment-runner / claude self-hosted-runner / claude --bg

12. 第十二章：进阶实验性能力与社区生态

章节摘要：给愿意折腾的用户一张"还能玩什么"的地图。覆盖实验 feature、buddy、监控、advisor、teleport 等小众但强大的命令。

子章节：

• 实验性 feature flag 速览：BUDDY / KAIROS / LODESTONE / ULTRAPLAN / MONITOR_TOOL
• Skill 搜索实验：EXPERIMENTAL_SKILL_SEARCH / EXPERIMENTAL_SEARCH_EXTRA_TOOLS（编译进 build，运行时默认 OFF，SKILL_SEARCH_ENABLED=1 开启）
• Buddy 协作与 /buddy 命令
• Kairos 简报与 /brief、Away Summary、/recap
• Advisor、insights、thinkback：让 Claude 反思自己的输出
• Teleport 与 pipes：跨会话消息传递
• Local vault 与 memory stores：长期记忆的多后端
• TUI 实验、stickers、output-style 自定义
• 贡献者生态：/feedback、GitHub issues、bun run docs:dev 本地起文档站

锚点：

• src/commands/buddy/、brief.ts、recap/、advisor.ts、insights.ts、thinkback/、teleport/、pipes/、local-vault/、memory-stores/、tui/、stickers/、output-style/
• 命令：bun run docs:dev / FEATURE_<NAME>=1 bun run dev

13. 第十三章：安全 —— 凭证、权限、刷新、共享（交叉补充）

章节摘要：当前两份大纲都没有连贯的安全章节。把凭证存储、权限模式、OAuth 刷新、跨工具凭证共享集中讲清楚，让用户知道自己的密钥和令牌去了哪里。

子章节：

• 凭证存储位置清单：~/.claude/、~/.claude/openai-chatgpt-auth.json、~/.codex/auth.json、~/.claude.json、settings.json / settings.local.json
• OAuth 设备码流程：ChatGPT 订阅路径与 Anthropic OAuth 各自的设备码握手
• OAuth 令牌自动刷新的 5 分钟偏差窗口
• 权限模式语义：默认询问 / 自动批准 / 全部拒绝 / sandbox / bypassPermissions（非 root/sandbox 环境检测）
• JWT 认证（Bridge 模式）：token 签发、传输、回收
• /share 与 /export 的隐私边界：哪些字段会泄漏、是否包含凭证、给同事前要做什么
• 跨工具凭证共享的隐私影响：Codex CLI 共享 ~/.codex/auth.json 的含义

锚点：

• src/commands/login/login.tsx
• src/services/api/openai/chatgptAuth.ts:327
• src/components/ConsoleOAuthFlow.tsx:1294
• src/commands/permissions/、share/、export/
• src/services/acp/permissions.ts

---

第二部分：开发者设计探秘大纲（开发者视角）

按"被约束逼出的决策链"组织：从最戏剧性的设计动机（JSC 内存暴涨）出发，逐层剥开入口、核心循环、工具系统、Provider 抽象、UI 框架、状态管理、运行时补丁、Feature Flag、特殊模式、测试策略、反编译指纹。每章都回答"为什么这么设计？"。

1. 序章：一份被反编译重建的 CLI，为什么处处是"约束的印记"

章节摘要：开篇先回答整个项目最根本的好奇心——这不是 Anthropic 原版，而是反编译产物在 Bun/JSC 约束下的重建。点明全书主线：每一个看似奇怪的设计背后，都藏着一个具体的运行时约束或反编译痕迹。

子章节：

• 反编译的语义：为什么 stub 模块、feature-gated 代码、React Compiler 的 _c() 是正常的
• 全书的叙事主线：约束（JSC 内存、Bun DCE、运行时类型补丁）如何驱动架构
• 如何阅读本书：每章锚点都指向真实 文件:行号，请打开编辑器对照
• 两类禁用 feature 的诚实区分：反编译丢失导致的 stub（CONTEXT_COLLAPSE / HISTORY_SNIP / FORK_SUBAGENT）vs 功能原本就 stubbed 的（SKILL_LEARNING / TEAMMEM）—— 这两类经常被混淆

锚点：

• src/types/react-compiler-runtime.d.ts:1
• src/types/global.d.ts:9、global.d.ts:59
• CLAUDE.md

2. 第一章：Code Splitting 不是优化，是生存需求

章节摘要：全书最戏剧性的设计动机——单文件 17MB 产物让 Bun/JSC 全量解析导致 RSS 暴涨到 ~1GB，而 Node/V8 懒解析仅需 ~220MB。项目因此被迫切成 600+ chunks，--version 的 RSS 从 966MB 骤降到 35MB。

子章节：

• JSC 的贪婪解析 vs V8 懒解析：实验数据（17MB → 1GB vs 220MB）
• 为什么 Vite 必须代码分割而不是单文件：Bun 按需加载 chunks 的原理
• 双构建管线：Bun.build() vs Vite，各自的 chunk 布局（dist/ vs dist/chunks/）
• post-build 阶段为什么必须 patch globalThis.Bun 解构（@anthropic-ai/sandbox-runtime 在 Node.js 启动会崩）
• 构建产物同时兼容 bun/node：import.meta.require → createRequire 的运行时探测

锚点：

• build.ts:23、build.ts:43、build.ts:62
• vite.config.ts:94
• scripts/post-build.ts
• src/utils/distRoot.ts:15

3. 第二章：入口的 Fast-Path 优先级链 —— 为什么 --version 必须零模块加载

章节摘要：cli.tsx 的 main() 函数按优先级串起十几条快速路径，最极端的是 --version / -v 零模块加载。背后的设计哲学：CLI 启动延迟是用户体验第一杀手，每个子命令都应该尽可能晚地加载它真正需要的代码。

子章节：

• Fast-Path 优先级链：--version → --dump-system-prompt → MCP servers → daemon-worker → bridge → BG sessions → 默认 main.tsx
• 为什么 CLAUDE_CODE_ABLATION_BASELINE 必须 inline 在 cli.tsx 顶层：BashTool / AgentTool / PowerShellTool 在 import 时就把 DISABLE_BACKGROUND_TASKS 等环境变量捕获进模块级 const，init() 跑得太晚无法影响它们 —— 这是一条脆弱但必要的初始化顺序依赖
• MACRO 编译期注入的三层防线：dev 模式 -d flag、build Bun.build define、运行时 fallback globalThis.MACRO
• 为什么版本号单一来源在 package.json 而不是 hardcoded（避免漂移）
• 双入口 cli-bun.js / cli-node.js：同一份产物被两个运行时执行

锚点：

• src/entrypoints/cli.tsx:5、cli.tsx:11、cli.tsx:56、cli.tsx:76、cli.tsx:79
• scripts/defines.ts:18、defines.ts:39
• scripts/dev.ts:17

4. 第三章：performanceShim —— JSC 内存泄漏的运行时补丁

章节摘要：src/utils/performanceShim.ts 必须是 cli.tsx 的第一行 import。JSC 的原生 Performance 把 marks/measures 存进永不收缩的 C++ Vector，长会话累积数百 MB 死容量。这个 shim 在 React/OTel 捕获原生引用之前劫持全局 performance。

子章节：

• JSC 原生 Performance 的陷阱：C++ Vector 永不收缩
• 为什么保留 performance.now() 走原生，只劫持 mark / measure / getEntries
• 为什么必须最先 import：React reconciler 和 OTel 会捕获原生引用
• query.ts 的 finally 块兜底 clearMarks / clearMeasures —— 防 sub-agent 直接 import query 时 shim 没装上
• 为什么 dev 模式 NODE_ENV='production'：避免 6,889+ _debugStack Error 对象（12MB）

锚点：

• src/utils/performanceShim.ts:1、performanceShim.ts:18、performanceShim.ts:162
• src/query.ts:460

5. 第四章：核心 Query Loop —— 为什么 query() 是 async generator

章节摘要：src/query.ts 的 query() 是 async function*，yield StreamEvent / Message / TombstoneMessage / ToolUseSummaryMessage，最终 return Terminal。背后的设计：流式响应必须能够把"结果"与"副作用"解耦，调用方可以选择性消费。

子章节：

• async generator vs callback：为什么用 yield 而不是事件发射器
• queryLoop() 的委托模式：thinking 块的 3 条硬约束（max_thinking_length>0、不能是最后一块、跨工具轨迹保留）
• MAX_OUTPUT_TOKENS_RECOVERY_LIMIT=3：max_output_tokens 错误为什么会对调用方扣留（yield 会终止会话）
• QueryEngine 作为 query() 之上的会话编排器：messages / fileCache / usage 跨 turn 持久
• snipReplay 回调：让 feature-gated 字符串留在 gated 模块外，QueryEngine 在 bun test 下仍可测

锚点：

• src/query.ts:181、query.ts:276、query.ts:367、query.ts:393、query.ts:460
• src/QueryEngine.ts:138、QueryEngine.ts:192、QueryEngine.ts:217

6. 第五章：Feature Flag 系统的三个硬约束

章节摘要：feature() 不是普通的运行时函数——它有 Bun 编译器强加的三个硬约束：(1) 只能出现在 if 条件或三元表达式（DCE 限制）；(2) 不能赋值给变量；(3) vite 插件必须在 transform 阶段替换为字面量，否则 bundler 会尝试解析不存在的 import。

子章节：

• 为什么 feature() 不是布尔变量：Bun 编译器 DCE 的 AST 模式匹配限制
• vite-plugin-feature-flags.ts 的 transform 时机：import 解析之前的字面量替换
• REVIEW_ARTIFACT 内的 hunter.js 根本不存在：为什么 if(false) 必须在 parse 阶段可见
• Build 默认 65+ feature vs Dev 全开 vs 运行时 FEATURE_<NAME>=1：三层切换机制
• 反编译产物的 stub 陷阱：明确区分反编译丢失的 stub（CONTEXT_COLLAPSE / HISTORY_SNIP / FORK_SUBAGENT，启用会破坏核心功能）vs 功能原本就 stubbed 的（SKILL_LEARNING / TEAMMEM）

锚点：

• scripts/vite-plugin-feature-flags.ts:29
• src/types/internal-modules.d.ts:10

7. 第六章：工具系统的延迟加载与 CORE_TOOLS 白名单

章节摘要：60 个工具不会一次性全部加载——CORE_TOOLS 38 个白名单是"always-available"核心，其余通过 SearchExtraToolsTool 按需 TF-IDF 搜索。背后的设计：tool schema 本身会消耗 token，必须按对话需求动态展开。

子章节：

• CORE_TOOLS 白名单制：isDeferredTool 的判定逻辑
• SearchExtraToolsTool：用 TF-IDF 语义搜索延迟工具（复用 localSearch.ts 的 computeWeightedTf / computeIdf / cosineSimilarity）
• toolIndex.ts 的共享算法：为什么 skill prefetch 和 tool prefetch 用独立的去重 Set（discoveredToolsThisSession 互不影响）
• feature-gated 工具：feature() 条件加载模式 const x = feature('X') ? require('./x.js') : null
• SyntheticOutput：CORE_TOOLS 中用于延迟工具按需加载的特殊工具

锚点：

• src/constants/tools.ts
• src/tools.ts
• src/services/searchExtraTools/toolIndex.ts、prefetch.ts
• packages/builtin-tools/src/tools/

8. 第七章：7-Provider 抽象层的单一调度点

章节摘要：claude.ts:1344 是整个 Provider 系统的心脏——在共享预处理（消息归一化、工具过滤、媒体剔除）之后、Anthropic 特定逻辑（betas/thinking/caching）之前动态导入 Provider 路径。兼容层因此自然跳过 Prompt 缓存/beta 功能，无需 feature flag。

子章节：

• Provider 路由优先级链：modelType 参数 > CLAUDE_CODE_USE_* 环境变量 > firstParty 默认
• 为什么调度点位置这么精确：兼容层"结构性跳过"betas/thinking 的优雅
• 调度点的不对称：给 OpenAI 路径传 tools（全池）但给 gemini/grok 传 filteredTools（裁剪后）—— 因为 OpenAI 路径在内部模拟 Anthropic 延迟工具加载给 SearchExtraToolsTool，需要访问完整池。这恰恰是"调度点位置精确"论点的最强证据
• getAPIProvider() 是单一真相源：/provider 命令、Langfuse 追踪、模型映射都依赖它
• Provider 切换的原子性：/provider 命令同时清除所有 CLAUDE_CODE_USE_* 再 applyConfigEnvironmentVariables
• Anthropic 内部 4 Provider 统一伪装成 Anthropic SDK 类型——代码注释承认的"类型谎言"
• isFirstPartyAnthropicBaseUrl() 的 TODO 陷阱：firstParty 行为可能泄漏到兼容层

锚点：

• src/utils/model/providers.ts:15
• src/services/api/claude.ts:1344（调度点 + tools/filteredTools 不对称）
• src/services/api/client.ts:84
• src/services/api/claude.ts:2999
• src/commands/provider.ts:39

9. 第八章：流适配器 —— 让 OpenAI/Gemini/Grok 假装自己是 Anthropic

章节摘要：adaptOpenAIStreamToAnthropic / adaptGeminiStreamToAnthropic 是纯 async generator，把第三方流格式转换成 BetaRawMessageStreamEvent。下游 claude.ts 的 contentBlocks 累加器与原生 Anthropic 路径完全一致——零分支。这是整个多 API 兼容层最巧妙的设计。

子章节：

• 流适配器模式：async generator 作为格式翻译器
• 为什么下游零分支：contentBlocks 累加器不知道上游是什么 Provider
• message_stop 后兜底：OpenAI/Grok 适配器在内存累积 contentBlocks 仅在 message_stop 时组装，网络中断时存在重复发射风险；post-loop 安全回退在 partialMessage 未重置时重发 —— 这是"下游零分支"叙事里少数有针对性修补的点
• @ant/model-provider 作为无副作用转换器库 vs src/services/api 作为客户端实例化器
• DeepSeek 思维模式的三层兼容：官方 thinking / 自托管 enable_thinking / 小米 chat_template_kwargs
• 为什么 Grok 复用整个 OpenAI 适配器栈：只有 client 和 resolveGrokModel 是 Grok 特有
• ChatGPT 订阅路径：Responses API 是 OpenAI 内部的第二个适配器（input_text / input_image / role messages 转换 + adaptResponsesStreamToAnthropic vs Chat Completions 流适配器）

锚点：

• packages/@ant/model-provider/src/shared/openaiStreamAdapter.ts:35
• packages/@ant/model-provider/src/shared/openaiConvertMessages.ts:32
• src/services/api/openai/index.ts:214
• src/services/api/openai/requestBody.ts:70
• src/services/api/openai/responsesAdapter.ts:1
• src/services/api/gemini/client.ts:26
• src/services/api/grok/index.ts:51

10. 第九章：Usage 字段映射与模型映射的优先级链

章节摘要：三个兼容层的模型映射都用四级优先级链：PROVIDER_MODEL 环境变量 > PROVIDER_DEFAULT_{FAMILY}_MODEL > ANTHROPIC_DEFAULT_{FAMILY}_MODEL > DEFAULT_MODEL_MAP 查找表。但 Gemini 是唯一在都缺失时抛异常的。Usage 字段映射则有镜像设计 + cache 字段保留策略，是"下游零分支"叙事里唯一一个有针对性修补的例外。

子章节：

• 正则 /haiku|sonnet|opus/i 推断模型系列的设计权衡
• GROK_MODEL_MAP JSON：为什么 Grok 唯一支持用户自定义 JSON 映射
• 防御性清理：replace(/\[1m\]$/, '') 剥离终端加粗 ANSI 后缀
• getOpenAIClient / getGrokClient 的模块级缓存：会话中改 API key 必须 clearOpenAIClientCache()；对比 getAnthropicClient() 按 model/region 参数化的设计差异
• Usage 字段映射兼容性：updateOpenAIUsage 与 claude.ts:updateUsage 的镜像设计；cache_creation_input_tokens / cache_read_input_tokens 在增量省略时保留，防止适配器差异导致缓存计数器被静默清零 —— 值得专门讲，因为它是"下游零分支"的唯一例外
• BedrockClient 的针对性变通：剥离 anthropic_beta 体（SDK 0.26.4-0.28.1 漏洞）+ probe 脚本检测修复

锚点：

• packages/@ant/model-provider/src/providers/openai/modelMapping.ts:36
• packages/@ant/model-provider/src/providers/gemini/modelMapping.ts:8
• packages/@ant/model-provider/src/providers/grok/modelMapping.ts:51
• src/services/api/openai/shared.ts（updateOpenAIUsage）
• src/services/api/claude.ts（updateUsage 镜像）
• src/services/api/bedrockClient.ts:29
• src/services/api/openai/client.ts:39
• src/services/api/grok/client.ts:15

11. 第十章：自研 Fork 的 Ink 框架 —— 为什么不是 src/ink/

章节摘要：packages/@ant/ink/（package.json name: @anthropic/ink）是基于 react-reconciler 自建的终端 React 渲染器。core/ 目录有完整的 reconciler.ts、dom.ts、yoga-layout/、render-node-to-output.ts、hit-test.ts、focus.ts——这是一个完整的终端 DOM + 布局引擎，不是上游 Ink 库。

子章节：

• 为什么 fork 而非用上游 Ink：完整终端 DOM + Yoga 布局引擎的掌控需求
• react-reconciler 自建渲染器：reconciler.ts / dom.ts / yoga-layout / render-node-to-output / hit-test
• vite.config.ts 的 dedupe: ['react', 'react-reconciler', 'react-compiler-runtime'] —— 为什么必须保证单副本
• React Compiler 输出的 _c() memoization 模板 —— 为什么这是正常的
• global.d.ts 的 declare type T = unknown —— 反编译产物特有的类型补丁（编译 JSX 丢失泛型）

锚点：

• packages/@ant/ink/package.json:1
• packages/@ant/ink/src/core/reconciler.ts:1
• vite.config.ts:94
• src/types/react-compiler-runtime.d.ts:1
• src/types/global.d.ts:9、global.d.ts:59

12. 第十一章：三层状态管理 —— 为什么 bootstrap/state.ts 警告 "DO NOT ADD MORE"

章节摘要：src/bootstrap/state.ts 是模块级 singleton（sessionId、cwd、projectRoot、token counters），文件顶部警告不要再加。src/state/store.ts 是手写 33 行 zustand-style store。src/state/AppState.tsx 用 React Context 包裹 store——三层各司其职，边界严格。

子章节：

• Bootstrap state：模块级 singleton 的诱惑与陷阱（"DO NOT ADD MORE STATE HERE"）
• 手写 zustand-style store：33 行代码（createStore 返回 getState / setState / subscribe，Object.is 短路、Set<Listener>）
• AppState.tsx 的 React Context 包裹：useSyncExternalStore 订阅 slice
• USER_TYPE==='ant' 时返回根 state 会抛错：强制细粒度订阅避免全量 re-render
• HasAppStateContext 主动 throw 防嵌套："AppStateProvider can not be nested"

锚点：

• src/bootstrap/state.ts:31、state.ts:45
• src/state/store.ts:1
• src/state/AppState.tsx:59、AppState.tsx:129
• src/state/AppStateStore.ts:42

13. 第十二章：ACP / Bridge / Daemon —— 三个长驻模式的接线

章节摘要：ACP（Agent Client Protocol）、Bridge（Remote Control）、Daemon（supervisor）是三种长驻运行模式。共同特征：feature-gated、独立 entry、跨进程通信。这一章揭示它们如何共享底层 query loop 又各自增加编排层，并与产品大纲第十一章（CI / BYOC runner）形成交叉。

子章节：

• ACP agent 实现：agent.ts / bridge.ts / permissions.ts / entry.ts + createAcpCanUseTool 统一权限流水线
• acp-link 包：WebSocket 客户端桥接到 ACP agent（REST 注册 + WS identify 两步流程）
• Bridge 模式：JWT 认证、消息传输、权限回调（feature BRIDGE_MODE）
• Daemon 模式：workerRegistry.ts 管 worker，--daemon-worker=<kind> 派生精简 worker（无 analytics sink）
• 自托管 RCS：packages/remote-control-server/ Docker 部署 + Web UI（React 19 + Vite + Radix UI）
• 交叉点：claude environment-runner / self-hosted-runner BYOC runner 正是 ACP/Bridge/CI 三条线的交汇点，产品大纲第十一章与此章应建立交叉引用

锚点：

• src/services/acp/
• packages/acp-link/
• src/bridge/bridgeMain.ts
• src/daemon/main.ts、workerRegistry.ts
• packages/remote-control-server/

14. 第十三章：CLAUDE.md 四层层级与 @include 指令

章节摘要：CLAUDE.md 不是单个文件，而是四层层级：Managed → User → Project → Local，后加载的优先级更高（模型更关注）。@include 指令支持 60+ 种文本扩展名，防循环、不存在静默忽略，MAX_MEMORY_CHARACTER_COUNT=40000。

子章节：

• 为什么逆序优先：离当前目录越近的文件越晚加载，模型关注度越高
• @include 的四种路径形式：@path / @./rel / @~/home / @/abs
• @include 的边界：仅限叶子文本节点（非代码块内），防循环，不存在静默忽略
• 为什么支持 60+ 种扩展名（.md / .ts / .py / .rs / .swift / .sql / .graphql ...）
• context.ts 如何把 git status / date / CLAUDE.md / memory files 组装成系统提示

锚点：

• src/utils/claudemd.ts:1、claudemd.ts:88、claudemd.ts:95
• src/context.ts:36、context.ts:116

15. 第十四章：测试策略 —— 为什么 mock 必须从底层 HTTP 开始

章节摘要：Bun 的 mock.module 是 process-global 的（last-write-wins），不是 per-file 隔离。一个测试文件的 mock 会污染同进程所有 require/import。所以项目立下铁律：只 mock 有副作用的依赖链（log.ts / debug.ts / bun:bundle / axios），不 mock 纯函数。

子章节：

• Bun mock.module 的进程全局陷阱：last-write-wins，测试文件执行顺序不保证字母序
• 为什么不能 mock 被测模块的上层业务模块：launch*.test.ts 必须 mock axios 而非 triggersApi
• 共享 mock 文件 tests/mocks/log.ts 和 tests/mocks/debug.ts：源文件导出变更只需改一处
• 集成测试 vs 回归测试的目录布局：launch*.test.ts 和 api.test.ts 同目录的判断标准
• 排查 mock 污染的 4 步法：单独运行 / 同目录运行 / console.error milestone / specifier 解析

锚点：

• tests/mocks/log.ts、debug.ts、axios.ts
• tests/integration/

16. 第十五章：biome.json 的 42 条规则关闭 —— 反编译产物的指纹

章节摘要：biome.json 关掉了 42 条 lint 规则——suspicious 关 noExplicitAny / noConsole，style 关 useConst / useTemplate，complexity 关 noForEach / useArrowFunction，correctness 关 noUnusedVariables / useExhaustiveDependencies。这不是偷懒，而是反编译产物的必然：decompiled 代码无法逐行重构，只能保留 recommended 基线。

子章节：

• 42 条规则关闭的分类与原因：suspicious / style / complexity / correctness
• 为什么 .tsx 特殊：lineWidth 120 + 强制分号（其他文件 80 + asNeeded）
• tsc vs biome 的冲突：noUnusedPrivateClassMembers 与声明属性的两难，biome-ignore 注释保留类型
• @ts-expect-error 的维护纪律：MACRO 永真比较保留，类型系统更新后 directive 变 unused 必须移除
• CI 的 biome ci . 必须 zero warnings —— 42 条关闭之外仍守底线
• Node.js v22 不支持 using 声明的脆弱 transpile：vite 插件把 using _x = 正则替换成 const _x =，安全前提是 SLOW_OPERATION_LOGGING 未启用 —— 一条脆弱的 transpile 依赖

锚点：

• biome.json:24、biome.json:102
• .editorconfig

17. 尾声：哪些坑我们没踩 —— 读者可以继续挖掘的方向

章节摘要：本章列出探索过程中因模型过载未能深挖的子系统，邀请读者沿着锚点继续挖掘。同时也诚实交代反编译重建工作的边界。

子章节：

• 未深挖：ConsoleOAuthFlow.tsx 的 china_provider_select 表单 + CHINA_LLM_PROVIDERS 预设表
• 未深挖：ChatGPT 订阅路径与 Codex CLI 跨工具凭证共享（~/.codex/auth.json）
• 未深挖：poorMode（/poor 命令）持久化到 settings.json + 跨所有兼容层复用
• 未深挖：isFirstPartyAnthropicBaseUrl() TODO 陷阱与 clearOpenAIClientCache 模块级缓存陷阱 —— 给读者可追踪的线索
• 未深挖：vendor/ripgrep/arm64-darwin 二进制缺失的实际后果（Grep 工具 spawn 该路径 ENOENT，distRoot.ts vendor 复制逻辑就是为了解决这个）
• 反编译工作的诚实边界：哪些 stub 是因为反编译丢失，哪些是因为功能原本就 stubbed
• 邀请读者：带上编辑器，沿着锚点继续探索

锚点：

• src/components/ConsoleOAuthFlow.tsx:1294
• src/utils/chinaLlmProviders.ts:44
• src/services/api/openai/chatgptAuth.ts:327
• src/commands/poor/poorMode.ts
• src/services/api/client.ts（isFirstPartyAnthropicBaseUrl）
• src/services/api/openai/client.ts:39（clearOpenAIClientCache）
• src/utils/distRoot.ts、src/utils/vendor/ripgrep/

---

第三部分：交叉主题（两个视角都需要覆盖）

下列主题在产品与设计两个视角下都需要覆盖，但写法、深度、锚点指向各不相同。

1. 排错与错误对照

• 产品视角：作为第十章主体。给一张"Provider 报错对照表"（401 / 403 / 429 / overloaded_error 1305 / 模型不存在），配兼容层特有坑（DeepSeek reasoning_content 400、Bedrock anthropic_beta 400、Gemini 硬抛异常、OpenAI 限流头解析）。措辞用"我遇到了 X，怎么办？"
• 设计视角：当前设计大纲完全没有排错章，是最大缺口。建议补一节"排错的工程化"：为什么 Bedrock 补丁必须配 probe 脚本（scripts/probe-bedrock-beta-fix.ts）、为什么 DeepSeek 必须回显空 reasoning_content、isFirstPartyAnthropicBaseUrl TODO 为什么泄漏。措辞用"这个错误的根因是 Y 设计决策"。

2. 性能与内存

• 产品视角：第十章一笔带过即可。给"长会话变卡怎么办"的解决路径：/compact → /force-snip → 重启。RSS 数据用一句话引用。
• 设计视角：第一、三、四章是深水区。给完整数据链（17MB → 1GB vs 220MB；--version RSS 966MB → 35MB；6,889 _debugStack Error 12MB；performanceShim 兜底）。讲清 JSC C++ Vector 永不收缩的根因。

3. 安全

• 产品视角：新增第十三章（当前完全缺失）。措辞用"我的密钥去了哪里"。覆盖凭证存储路径清单、OAuth 刷新窗口、/share / /export 隐私边界、跨工具凭证共享的隐私影响。
• 设计视角：作为"反编译重建的安全约束"穿插在相关章节。措辞用"为什么这么存"。讲 bypassPermissions 在非 root/sandbox 的可用性检测、JWT 在 Bridge 的设计、HasAppStateContext 主动 throw 防嵌套的安全含义。

4. 升级与版本管理

• 产品视角：第十章的 claude doctor 子章节展开。给"我该怎么升级"工作流：claude doctor 版本检查 → bun run update → 重启。
• 设计视角：第二章的"版本号单一来源 package.json"展开。讲 MACRO 三层注入、scripts/probe-bedrock-beta-fix.ts 作为"SDK 漏洞 probe 模式"的工程实践示范（如何检测上游 SDK 修复后安全删除针对性补丁）。

5. 与其他工具集成

• 产品视角：第八章（ACP/Bridge/IDE）+ 第十一章（GitHub Actions）。给"我能在 X 里用 Claude 吗"的清单式回答。
• 设计视角：当前设计大纲完全没有跨工具集成视角，是第二大缺口。建议在第十二章（ACP/Bridge/Daemon）补一节"集成边界"：acp-link 与 Codex CLI 凭证共享、vscode-ide-bridge 的协议设计、install-github-app / subscribe-pr / commit-push-pr 的工作流契约。

6. 可观测性

• 产品视角：第十章子章节。措辞用"我想知道 Claude 在做什么"。覆盖 Langfuse 追踪、--dump-system-prompt、/debug-tool-call、BUN_INSPECT 调试。
• 设计视角：当前设计大纲仅第七章锚点提到 claude.ts:2999。建议补一节"观测的注入点"：recordLLMObservation 的 provider 字段如何从 getAPIProvider() 取值、为什么 Langfuse 追踪必须用单一真相源、performanceShim 与 OTel 的耦合关系。

7. 凭证与认证生命周期

• 产品视角：第二章 + 第十三章交叉。措辞用"我的令牌怎么刷新、什么时候过期"。覆盖 OAuth 设备码、ChatGPT 订阅 5 分钟刷新偏差、China LLM 表单写入流程、/login 与 /logout 副作用、/provider unset 只清 Provider 不清 key。
• 设计视角：在第七、八章穿插。措辞用"为什么 token 这样存"。讲模块级 client cache 的设计权衡（getAnthropicClient 参数化 vs getOpenAIClient 模块级缓存）、ChatGPT 订阅路径为何读 ~/.codex/auth.json（与 Codex CLI 复用凭证的设计决策）、5 分钟刷新偏差窗口的容错考量。

---

下一步建议

建议先写的章节（价值最高）

1. 产品第二章 + 第十章排错对照表（含"我改了 API key 但没生效"与"为什么切了 Provider 没生效"两个高频困惑）—— 这是用户最高频的痛点，写完立竿见影降低 issue 量。
2. 设计第一章（Code Splitting 是生存需求）+ 第三章（performanceShim）—— 这两章是全书的叙事引擎，"为什么这么设计"的最戏剧性证据，先写好它们能定调整本书的好奇心基调。
3. 交叉主题"安全"章（产品第十三章）—— 当前两份大纲都完全缺失，是最显眼的空白；凭证存储、权限模式、OAuth 刷新一旦写清楚，能避免大量误用。
4. 设计第七章（单一调度点）补 tools/filteredTools 不对称段 + 第九章（Usage 字段映射）新增—— 这两段是"下游零分支"叙事的核心证据与唯一例外，写好了能让设计大纲的 Provider 章节真正立住。
5. 产品第四章（slash 命令速查）按场景分类表—— 用户最常翻的一章，写好就是一张长期参考表，ROI 极高。

会因图示或代码示例受益的章节

1. 设计第一章 Code Splitting——RSS 数据柱状图（17MB 单文件 1GB / 切分后 35MB / Node 220MB）一张图胜千言。
2. 设计第七/八章 Provider 调度点 + 流适配器——一张调度流程图：消息归一化 → 工具过滤（tools vs filteredTools 分叉）→ 调度点 → 三条 Provider 路径（Anthropic 原生 / OpenAI/Grok 流适配器 / Gemini 流适配器）→ 统一 contentBlocks 累加器。
3. 产品第十章 Provider 报错对照表 + 产品第十三章凭证存储——前者是表格，后者是 ~/.claude/ 与 ~/.codex/ 的目录树图，直观显示哪些文件含密钥。