技术文档审校

轮次化审校 AI/Agent/LLM 技术文档：先机械性硬伤、后语义性判断，达到质量门禁后输出报告。本文件只放流程与导航，不放框架签名等项目数据——数据一律写入 references/version-baseline.md。

流程总览（每轮聚焦 2-3 个维度，防止注意力分散）

• R0 预检：清点文件清单；确认参考性文档豁免清单（判断原则见 common-pitfalls.md 陷阱 9）；登记项目扩展清单（见下方「项目扩展点」）
• R1 基线扫描：scan.py --mode baseline + --mode version-lock，处理 D1 硬伤
• R2 深度验证：API 签名对照官方类型定义（六步法见下），同步处理 D2 类比毒性
• R3 版本核查：scan.py --mode version-check 联网对比 npm registry，加载 version-baseline.md
• R4 一致性：scan.py --mode cross-check + D5 清单
• R5 终审：D4 教学逻辑人工复核，按 assets/report-template.md 输出报告，过门禁后交付

维度导航

| 维度 | 内容 | 加载文件 | 加载时机 | |------|------|---------|---------| | D1-D6 | 通用逐条清单 | references/checklists.md | 进入对应轮次前 | | D7 | Agent 域专项 | references/checklists-d7.md | 题材命中 Agent / LLM 应用 / MCP / streaming / RAG 关键词时 | | 陷阱与验证方法 | 十类陷阱 + 5 类 AI 特殊风险 | references/common-pitfalls.md | 执行修复前 | | P0-P2 诊断 | 修复模式库 | references/diagnostic-patterns.md | 定性问题后 | | 版本基线 | 废弃对照表（唯一数据源） | references/version-baseline.md | R3 联网核查时 |

scan.py 扫描模式

| 模式 | 用途 | 轮次 | |------|------|------| | baseline | 废弃 API / 版本扫描（词库运行时解析自 version-baseline.md） | R1 | | version-lock | 模糊版本号检测（7.x / ^ / ~ / latest / beta） | R1 | | version-check | 联网版本对比（需 npm 与网络） | R3 | | cross-check | 跨文件数字漂移检测 | R4 |

回归验证：改动 scan.py 或 version-baseline.md 后，必须重跑 python3 scripts/tests/run_tests.sh。

优先级与门禁

• 🔴 P0 硬伤：事实错误、API 签名错误、语法污染、数字漂移——必须修复，未闭合则不得发布
• 🟡 P1 应修复：类比毒性、概念混淆、断点缺失
• 🟢 P2 可批量后处理：一致性与格式问题
• 发布门禁：综合评分 ≥ 8.5 且无 🔴 P0 未闭合项（评分表见 assets/report-template.md）
• 门禁达标即发布；反复审校追求"完美"属于过度审校（陷阱 7），后续用增量追踪维护

官方类型定义对比法（API 签名验证六步）

原则：API 签名验证必须基于官方类型定义，而非文本搜索——grep 无法证明签名正确性；即使版本号正确也可能存在签名错误。

1. 取最新版本号：npm view <pkg> version
2. 下载对应类型定义：npm pack <pkg>@<version> 后解压（勿写死 /tmp 等固定路径）
3. 提取目标方法签名：grep -rn 'methodName' package/ --include='*.d.ts'
4. 批量提取文档中的调用：grep -rn 'methodName(' <docs-dir>/
5. 逐一比对参数名、参数顺序、返回值结构
6. 修复后回归验证：全文搜索旧签名应为 0 命中

注意：

• 全部文件使用同一错误模式时属系统性错误（错误率 100%），必须标 🔴 P0，而非按孤例处理
• 离线备用方案见 common-pitfalls.md「类型定义检查法」；ESM/CJS import 验证命令见陷阱 6（唯一出处）
• 框架专属签名数据写入 version-baseline.md 对应表格（scan.py 自动加载），不得写进本文件

项目扩展点（用户侧挂载）

本技能只含框架无关的通用流程。项目专属检查（如某教学计划的 SOUL.md 框架分工对齐、quiz 内容对齐、按周文件的扫描范围）不属于技能本体，按以下方式挂载：

1. 在项目工作区新建 review-extensions.md，按 D1-D7 同款格式书写项目专属检查项
2. R0 预检时将其加入本轮审校待办，在对应轮次与通用清单合并执行
3. 项目所用框架的签名数据加入 version-baseline.md 对应表，而非本文件

人机分工

AI 负责机械性验证（版本检测、import 验证、跨文件一致性、签名比对），人工负责语义终审（类比毒性、教学逻辑、代码实跑）——完整分工表见 common-pitfalls.md「人机协作分工」。