AI 校对与审稿 SOP（工具无关）¶

目标：让 AI 做校对、找漏洞、补桥接、查一致性，而不是替代作者决策；所有建议必须能回到可验收的改动。

0) 三层思考框架（固定用法）¶

定位：把 AI 当成写作 linter，不是共同作者，也不是 co-author。
第 1 层：读者目标与问题：读者带着什么困惑来？读完能完成什么动作？
第 2 层：论证链条：本文的步骤是否构成闭环？每一步是否都解释了为什么需要它？
第 3 层：落地与验收：输出是否能直接转化为补丁？验收标准是否明确、可复现、可回滚？

1) 最小输入原则（避免上下文过载）¶

只给与任务直接相关的段落（通常 30–200 行），附带：章节目标、读者预期、约束（术语/结构/输出格式）。
优先以标题为边界切片：尽量按 ## 小节切，不要截断代码块、长表格或引用块。
涉及隐私/机密信息先脱敏：别把不该外发的内容塞进 Prompt。
对代码类内容：附验证命令/失败判定/禁止改动范围（例如禁止改实现，只能补测试）。
做一致性检查时，额外提供“真值表”摘录：style-guide.md 的关键约束 + glossary.md 的相关条目索引（只摘与本段相关的部分，避免塞全书）。

2) 工具链准备（减少重复、提高可维护性）¶

2.1 通用命令模板（建议只保留这一段 Shell）¶

ai_review() {
  local target_file=$1  # e.g. docs/books/ai-assisted-software-product/02-discovery.md
  local lines=$2        # e.g. 1,160p
  local llm_cmd=${3:-${LLM_CMD:-<LLM_CLI>}}
  local context_files=${4:-} # 可选：额外上下文文件（空格分隔）

  {
    cat
    if [ -n "$context_files" ]; then
      printf '\n\n上下文约束（可选）：\n<<<\n'
      for f in $context_files; do
        printf '\n# %s\n' "$f"
        sed -n '1,200p' "$f"
      done
      printf '\n>>>\n'
    fi

    printf '\n\n章节摘录（带行号）：\n<<<\n'
    sed -n $lines $target_file | nl -ba -w 4
    printf '\n>>>\n'
  } | "$llm_cmd"
}

# 用法示例：
# ai_review docs/books/ai-assisted-software-product/02-discovery.md 1,160p "<LLM_CLI>" <<'EOF'
# 你是中文技术书编辑。请做结构完整性检查。
# 输出：缺失项列表 + 每项一条补写建议（带验收标准）。
# EOF
#
# 带“真值表”示例（术语/格式一致性检查常用）：
# ai_review docs/books/ai-assisted-software-product/02-discovery.md 1,160p "<LLM_CLI>" \
#   "docs/books/ai-assisted-software-product/style-guide.md docs/books/ai-assisted-software-product/glossary.md" <<'EOF'
# <...>
# EOF

2.2 多章改动的做法（避免打地鼠）¶

当你要对多章做同一类改动（补“复现步骤/门禁/回滚”、统一术语、补桥接），建议按章节分批次输出补丁，每一批都先跑一次文档门禁，再继续下一批。这样可以尽早发现死链、引用编号与格式问题，避免在最后一刻返工。

bash skills/check_docs.sh

注意：本书的引用编号是硬门禁。批量改写后务必跑 python3 tools/check_citations.py，别把“看着像引用”的方括号数字写进代码块或正文里。

3) 常用审稿任务（Prompt 模板：复制即用）¶

用法：把下面任意一个 instruction 复制出来，通过 heredoc 传给 ai_review；除 Prompt 主体外，其余 Shell 逻辑不再重复展示。

统一输出约束（强烈建议写进每个 Prompt）： - 如果没有问题，输出 PASS； - 如果要改，必须输出“可直接粘贴的补丁块”：给出位置（标题或行号范围）+ 替换前/替换后（Markdown 代码块）。不要只给泛泛建议。

3.1 任务：结构完整性检查¶

你是中文技术书编辑。请检查以下章节是否缺少关键构件：
- 章节定位 / 你将收获什么 / 方法论速览
- 实战路径（步骤）/ 复现检查清单 / 交付物与验收标准
- 常见陷阱（按失败样本写）/ 延伸练习

要求：
- 不要为了凑数而建议无关小节；只指出会导致读者无法推进或无法验收的缺口。
- 输出为缺失项列表 + 每项 1 条补写建议（带验收标准）。

3.2 任务：逻辑漏洞与反例补全¶

你是资深审稿人。请针对下面文本找出：
- 隐含前提（读者不一定同意/不一定成立的假设）
- 可能反例（什么情况下结论不成立）
- 易误用表达（会导致读者在错误场景套用）

输出要求：
- 最多 8 条；
- 每条包含：问题一句话 + 建议替换句（一行就能让表达更严谨）+ 验收标准（读者怎么判断改对了）。

3.3 任务：为某小节补一个可复制示例（只在确有必要时）¶

你是中文技术书写作者。请基于下面的小节内容，补 1 个示例（可复制），必须包含：
- 目标 / 前置条件 / 上下文 / 约束
- 输出格式 / 步骤 / 验证命令 / 失败判定 / 回滚

要求：
- 输出为可直接粘贴进 Markdown 的一个小节；
- 不要出现需要联网或依赖未声明工具的步骤；
- 如果原文已经有足够示例，请改为指出示例的缺口 + 最小补丁建议，不要重复造轮子。

3.4 任务：术语表与链接一致性检查（首次出现应链接）¶

建议额外提供 glossary 的条目索引（例如 grep '^## ' docs/books/ai-assisted-software-product/glossary.md 的输出），用于缩短上下文并减少遗漏。

你是中文技术书编辑。请检查下面章节摘录的术语一致性与链接一致性：
1) 哪些概念应在首次出现处链接到 glossary（给出建议锚点，如 glossary.md#authn-authz）；
2) 哪些概念在正文里出现了同义词/多译混用（给出统一用法建议）；
3) 哪些概念应补进 glossary（给出建议条目名：中文 + 英文）。

输出要求：
- 只列影响理解/影响检索/影响一致性的术语，避免穷举。
- 每条建议给出：正文用法 -> 统一用法 -> 推荐链接锚点（或新增 glossary 条目名）。

3.5 任务：把常见陷阱改写为失败样本驱动模板¶

你是资深技术审稿人。请把下面的常见陷阱按统一模板改写为至少 3 条：
- 现象（读者会看到什么）
- 根因（为什么会发生）
- 复现（最小复现步骤/条件）
- 修复（怎么改）
- 回归验证（怎么确认修好了：命令/日志/指标）

要求：
- 输出为可直接粘贴的 Markdown；
- 不要引入未在文本中声明的外部工具。

3.6 任务：生成纯文本流程图/表格（不依赖 Mermaid）¶

你是中文技术书编辑。请基于下面内容，生成 1 张纯文本流程图/表格（二选一）来表达关键闭环：
- 流程图：用缩进 + 箭头表示分支与回路；或
- 表格：列出步骤 / 输入 / 输出 / 验证 / 失败判定。

要求：
- 能直接粘贴进 Markdown；
- 内容必须覆盖边界条件 / 失败回退 / 验证动作。

3.7 任务：图片 / 引用 / 占位符门禁检查（发布前必做）¶

你是文档交付审稿人。请检查下面章节摘录中的以下问题，并输出可直接粘贴的补丁块：

1) 图片是否“信息增益不足”（更像装饰）：若是，建议删图或改成表格/纯文本流程图，并说明替代内容放在哪。
2) 图片 alt 是否缺失/过泛：必须补成一句可读描述，并建议正文首次出现处加一句“这图用于证明什么”。
3) 是否存在占位图/占位词（如 TODO、placeholder）：命中即列为 L0 阻断，并给出替换策略（删掉/补齐/降级为文字）。
4) 是否违反“无文字底图”原则：图片若承载关键文字信息，必须改为无文字底图 + 后期叠字；配图规范参考 `G-image-prompts.md`。
5) 引用编号 `[n]` 是否可疑（断号/重复/突然跳号）：列出本段出现的编号集合，并提示需要跑 `python3 tools/check_citations.py` 做最终裁决。

输出要求：
- 若无问题输出 `PASS`；
- 若有问题：按条输出补丁块，包含位置（标题或行号范围）+ 替换前/替换后（Markdown 代码块）。

4) 采纳规则（作者作为裁判）¶

只采纳能落到可验收改动的建议（补桥接、补约束、补步骤、补验收标准、补失败判定）。
无补丁不采纳：建议要么给出可直接替换的一句话/一段话，要么给出明确的标题与要点清单；只给泛泛而谈视为无效。
对工具/框架推荐默认谨慎：优先保留范式与可迁移原则，工具清单放附录。
任何涉及安全/合规的建议：必须补一句边界条件/前置假设，避免被当成通用结论。
格式与标点约束：默认遵循写作风格与格式约定。重点：正文避免英文双引号（U+0022、U+201C、U+201D）等修辞性标点；代码块里可使用引号以保证可复制；不要用过量的加粗/代码格式/括号堆叠去代替解释；模板占位符少而统一，并说明替换点。
人工介入触发条件：同一段落连续两次输出互相矛盾的建议、或建议引入与本章无关的依赖/技术栈时，立即终止自动化并由作者裁决。

5) 实用提醒¶

长文本分块：对整章审阅，优先按小节分块（sed -n 取 100–200 行），避免提示过长导致输出发散或命令行参数过大。
切片边界：尽量以 ## 小节为边界取段，避免截断代码块或长表格；跨度很大的章节，宁可多次调用，也不要一次塞满。
保存审稿结果：需要留档时用 | tee 保存输出；建议纳入复现包目录（例如 reports/YYYY-MM-DD/<change-id>/ai-review/<file>_<section>.md），至少记录：文件、行号范围/标题、模型名、Prompt 版本、采纳/拒绝结论。