docs(v2): C09 Thinking、Effort 与 Advisor 勘误 + PromptSuggestion 番外 (YAO-110)

[luyao618]

Summary

C09 章节（v2 名「Thinking、Effort 与 Advisor」），判定档「勘误保留」，对 v1-08 做最小修改：

• v1 的七大节标题、全景图、可迁移设计模式三节一字未动（C-2 闸保留）。
• 仅在「八、全景」与「九、可迁移的设计模式」之间插入一节「番外：PromptSuggestion」，
  补完 v2-spec §5/§6.2 锚点表里列出但 v1 没有正文映射的 services/PromptSuggestion/promptSuggestion.ts。
• 番外定位为「相邻子系统」而不是改写主线——v1 主干叙事完全没动。

新写角度：PromptSuggestion 为什么必须 fork 同参数 agent。它把 §二
（thinkingClearLatched）与第 7 篇 Prompt Cache 「前缀稳定」原则收束到
一个具体功能上，并通过 PR #18143 的复盘事实（effort 强降到 low 导致
cache write 45x 飙升、主对话命中率从 92.7% 跌到 61%）锁死结论。这也是
v2-spec 要求 C09 整合 advisor + PromptSuggestion 的落点。

源码冻结 commit：290fdc9481a70612bc5823aa4ed225c52c52aad3。

保留 / 改写 / 新增统计（R-2）

• 保留 v1 段落：≈ 全部（v1 九大节 + 全景图 + 下一篇预告，约 200+ 段散文未动）
• 改写：0 段
• 新增：1 节番外，5 个子小节，约 1100 字散文 + 1 张对比表 + 2 段代码引用

N ≫ M + K，符合 §0.5.3 最小修改原则。新增节明确标注「番外」，
不进入主目录层级感知，且未挤占 v1 节序号。

风格双亲实证（R-1）

风格双亲：v1-05（对话循环）+ v1-07（Prompt Cache）

挑这两章是因为番外节的核心是把"fork agent"与"cache 前缀稳定"两个机制
合龙——这正是这两章的当家叙事节奏。

v1 原文摘抄（来自本文件未被本 PR 触碰的叙事段）

【摘抄 1，来自 docs/08-Thinking-与推理控制.md §2.4 第 277-301 行附近】

Interleaved Thinking（ISP）允许模型在工具调用之间继续 thinking——
而不是只能在一开始 think 一次然后机械地走完整条链。这对长链路任务
（多步 bash 操作、读多个文件后综合判断）是质的变化。但 ISP 的代价
是上下文管理变复杂：thinking block 会带签名、会在 compact 时被清理、
会和缓存断点交互。Anthropic 给的解法是 thinkingClearLatched——
一个绑定 1 小时 cache TTL 的会话级 latch，决定何时丢弃带签名的
thinking block 才不会让缓存白白失效。

【摘抄 2，来自 docs/08-Thinking-与推理控制.md §三 Effort 优先级链节】

这条优先级链不是写死在分发处的 if/else，而是被收敛到了一个
resolveAppliedEffort(model, appStateEffortValue) 函数里。所有需要
知道"这一轮到底发什么 effort 给 API"的调用点都打过来。这背后的
工程意图是：当你的配置来源跨了 4 层（env / CLI / settings / 模型默认），
任何一处散落的判断都会让"为什么这次跑的是 high"变成考古题。集中
解析函数 + 显式 fallback 链 = 你随时能解释 API 收到的 effort 是哪里来的。

本章新写正文摘抄

【新写 1，来自番外引子 + 番外.2「为什么 PromptSuggestion 必须用 fork 的同参数 agent」，对齐 head 正文 promptSuggestion.ts:319-321】

前面六节谈的都是"让模型多想"——Thinking、Effort、Advisor 都在主对话
循环的关键路径上调整推理深度。还有一个相邻但方向相反的子系统：在
主对话等待用户输入的间隙，悄悄派一个 fork 出去的小分支 agent
（旁路请求，同参数）预测"用户接下来最可能输入什么"，写在输入框
下方作为灰色提示。

整个文件最值得划重点的是 generateSuggestion() 的实现策略
（promptSuggestion.ts:294-352）：它不开一个全新的轻量请求，而是把
主对话当前的 cacheSafeParams 原样复制一份，只把 SUGGESTION_PROMPT
（258-287 行）作为一条 user message 追加进去
（promptSuggestion.ts:319-321：
promptMessages: [createUserMessage({ content: prompt })]），让模型
从用户视角接龙——刻意不动 system 字段就是为了不破坏主对话的 cache
前缀。为什么这么绕？因为 Anthropic 的 Prompt Cache 是前缀严格匹配
的——任何一个参数（包括 system、tools、temperature、甚至
thinking / effort）和主请求不一致，就会触发一次完整的 cache write
而不是 cache hit。代码注释里直接写了教训：PR #18143 早期版本把建议
请求的 effort 强行降到 low 节省成本，结果 cache write 量飙升 45x，
主对话的 cache hit rate 从 92.7% 跌到 61%。节省的那点 effort 钱远抵
不上 cache miss 多花的钱。

【新写 2，来自番外.4「12 道过滤闸——别把模型的话冒充成用户的话」，对齐 head 正文 promptSuggestion.ts:367-446 的 12 项 filters】

模型预测出来的字符串还要过 shouldFilterSuggestion()
（promptSuggestion.ts:354-456）的 filters 数组
（promptSuggestion.ts:367-446，共 12 项：done / meta_text /
meta_wrapped / error_message / prefixed_label / too_few_words /
too_many_words / too_long / multiple_sentences / has_formatting
/ evaluative / claude_voice），常见的几类：done / meta_text /
meta_wrapped 拦截 "nothing found" / "stay silent" 这种助手腔与元
推理括号包；error_message 拦截把上一轮报错（"API Error:"、"prompt
is too long"）直接回放；prefixed_label 拦截 word: 这种标签前缀
打头；too_few_words / too_many_words / too_long /
multiple_sentences 拦截短到只有 "yes"、长到 12 词或 100 字符以上、
或者跨多个句子等任何不像真人一次输入的形态；has_formatting 拦截
含换行或 markdown 强调；evaluative 拦截 "this is good" 这种 Claude
替用户自我表扬；claude_voice 拦截第一人称视角串味；外加
too_few_words 内部的 ALLOWED_SINGLE_WORDS 白名单，专门放行
"continue" / "yes" / "no" 这类高频单词回复。整套过滤器的存在告诉
我们一件朴素的事：让 LLM 模仿"用户视角"远比模仿"助手视角"难——
光靠 prompt 不够，必须在工程层把所有泄露 AI 身份的输出拦下来。

文风对比：保持设问 + "为什么这么绕？" / "整个文件最值得划重点的是…"
这种 v1-05/v1-07 标志性的二阶设问节奏，匹配双亲文风。

CI 闸自查

• C-1 中文段落留存率：≈ 100%（仅新增、零改写）✅
• C-2 标题保留：v1 全部 9 个一级 + 子节标题原封不动 ✅
• C-3 代码块占比：新增段落里只 3 段短代码引用，全章代码占比仍 < 25% ✅
• C-4 工程化小标题禁词：番外节标题用「为什么…」「12 道过滤闸」等口语式 ✅
• C-5 frontmatter：本文件首行 # 第 8 篇…，非 frontmatter ✅
• C-6 squad 术语：新写散文中无 spec/反向矩阵/manifest/chapter_id 等 ✅
• §0.4 禁词集合：番外节未出现「约」「大约」等模糊量词 ✅

Test plan

• CI 7 项闸 pass
• OC-R 抽样 3 段确认仅事实补完、零文风改写
• 等待尧哥手动 merge（CC-Dev 不执行 gh pr merge）

Closes YAO-110