shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

文档审校

审校、校对、勘误 AI / Agent / LLM 技术文档、教程与学习手册。当用户要求检查文档质量、修复过时 API、核对版本号、审查类比与教学逻辑，或文档涉及 LangChain、Mastra、AI SDK、MCP 等快速演进的框架时使用本技能。

person作者: HeldSiphubModelScope
download下载资源包

技术文档与学习文档审校

轮次化审校 AI/Agent/LLM 技术文档与学习计划配套文档：先机械性硬伤、后语义性判断、再实跑验证，达到质量门禁后输出报告。本文件只放流程与导航，不放框架签名等项目数据——数据一律写入 references/ 下的两个数据文件（version-baseline.md 与 runtime-semantics.md）：version-baseline.md（机器解析数据：废弃对照表 + 精确版本基线，scan.py 运行时读取，勿通读）与 runtime-semantics.md（框架行为语义核查表，R2 整表加载）（唯一出处原则：任何事实性数据在本包内只允许存在一处，其余位置只引用不复制）。

执行模式（三选一，按指令形态与连载状态选择）

| 模式 | 适用场景 | 触发指令形态 | | ---------------- | ----------------------------------------------------------- | --------------------------------------- | | 批量七轮（默认） | 整批文档一次性审校（下方 R0-R6 流程总览即本模式主体） | 「审校这周全部文档」「全面校对 Week N」 | | 单篇深审 | 逐篇连载 / 插队单篇（R0-R6 各维度收敛为单篇流水线） | 「单独审校 Day X」「续审 WeekNDayM」 | | 卷级收官复审 | 一卷逐篇全部完成后的卷末终检（W9/W10/W11/W20 四卷实证形态） | 「Week N 卷级收官复审」「收官复审」 |

单篇深审流水线（七步，每步有机械产物）

  1. 原稿基线：MD5 + 行数登记（防污染基线）；纯副本目录跑七模式扫描（不直接扫原稿位）
  2. 首查项：上篇移交清单 + 复发病灶首查（checklists.md D1「复发病灶首查项」块——同一源错误在同系列高复发，命中即全篇/全卷扫描）
  3. 实证：registry 官方源核验（npm 命令走镜像时 404 假象，陷阱 19）+ npm pack 拉包 .d.ts 逐项锚定（六步法）
  4. 编译矩阵：scripts/extract_blocks.py 提取 → 验证环境逐一 strict 编译（口径锁定，陷阱 18）→ 跨块引用（示例 2 依赖示例 1 的类）组合编译
  5. 实跑对齐：可实跑块实跑存档 → scripts/compare_expect.py 预期输出程序化逐字比对
  6. 修复：count 断言替换脚本（陷阱 21），批次 ≤7 文件门禁不变
  7. 复验交付：重提取+重编译+重实跑+七模式复扫+原稿 MD5 终验 → diff 存档（收官复审 R0 对位用）→ 交付+报告+worklog

目录约定：scripts/<篇>-review/（env/ + blocks-orig/ + blocks-fixed/ + copy/ 工作副本）、scripts/<篇>-recheck/（diff 存档）——同卷后续篇复用 env（npm 包按需增装），逐篇产物零丢失。

卷级收官复审（五道工序）

  1. R0 漂移核验：scripts/drift_check.py 三方对位（原稿 / 交付版 / 逐篇存档 diff，剥头逐字比对）+ 原稿 MD5 基线逐一比对——双证明（原稿未污染 + 交付版零未溯源漂移）
  2. R1 纯副本复扫：交付版纯目录七模式（预期零回归；修复说明文字中的旧形态命中按 R2 人工定性为溯源注记，非回潮）
  3. R2 跨篇专项：版本锚点全卷统一（bash 安装行与代码头注释双位对齐）、元数据统一（周次/阶段/前置知识——卷尾篇高发漂移）、互链链完整（逐日+W21 双向）、复发病灶清零、自我评分口径、折叠配对、术语一致、日期链连续
  4. R5 编译矩阵重放：SRC=交付版重放提取与编译——按各篇审校期原口径（esModuleInterop 差异不可统一，陷阱 18）；env 的 node_modules 被清理属常态（npm ci/install 恢复）；总块数断言防 0/0 假绿
  5. R6 收官报告：微批门禁 ≤7 文件 + 批后复验；收官原则——收官不改已定案内容（四道工序零新发现即零微批定案，W9/W20 同型；对照 W10 收官微批 4 处 P1）——逐篇深度已消化传统收官增量区时，零微批是正常结论而非失职

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

每轮开始时先逐项 grep 复验上一轮修正是否全部到位（防修正回潮与联动遗漏，见 common-pitfalls.md 陷阱 5），再进入本轮主体工作。

  • R0 预检：清点文件清单；识别文档类型（教程/手册、概念卡、测验 quiz、大纲——类型决定 D4 结构完整性检查项对号入座）；scan.py --mode format-check 检测行号前缀污染 / 粗体未闭合 / 代码围栏不配对（污染文件先净化交付）；确认参考性文档豁免清单（判断原则见 common-pitfalls.md 陷阱 9）；登记项目扩展清单（见下方「项目扩展点」）；大文件先按 common-pitfalls.md 陷阱 10 的分段读取策略装载
  • R1 基线扫描：scan.py --mode baseline + --mode version-lock + --mode version-match（静态初筛），处理 D1 硬伤；--mode fluency-check 语言流畅性机械初筛（D8 软提示只报不改，语义子集留待 R2）
  • R2 深度验证：API 签名对照官方类型定义（六步法见下），同步处理 D2 类比毒性与 D8 语言流畅性语义子集（逐段精读，与 D2 同轮，清单见 checklists.md D8）；文档中的框架行为声明逐条对照 runtime-semantics.md（框架行为语义核查表，整表加载——未收载判断需全表视野，禁止部分加载；对比表/概念卡/架构范式表的单元格同为事实声明区，逐格对照——陷阱 13），表中未收载的新声明标记待核实、留待 R5 实跑裁决（陷阱 11/12）
  • R3 版本核查：scan.py --mode version-check 联网对比 npm registry（终审；基线数据由 scan.py 运行时解析自 version-baseline.md，勿通读，查废弃 API 替代方案时按框架小节定位）；安全敏感包零容差（见 checklists.md D6 安全例外）
  • R4 一致性：scan.py --mode cross-check + D5 清单（含跨文件/跨周专项）；测验/quiz 型文档只补查解析层（答案/解析中的行为声明——解析层是回潮高发区，见 checklists.md D5；正文声明 R2 已核查，不重复全文对照）；多文档系列加跨卷同知识点对照——同一框架行为在不同篇 quiz 的结论必须同向，矛盾即 P0 送实跑裁决（陷阱 14）
  • R5 运行验证：静态审查永远无法替代实际运行——
    1. 依赖安装：按文档的 package.json 原样执行 npm install，安装失败本身即 P0
    2. 编译矩阵：scripts/extract_blocks.py 提取全部 TS 围栏 → 验证环境逐一 tsc --strict noEmit（口径锁定与块目录同层要求见陷阱 18；跨块引用做组合编译）——块级编译是逐块肉眼范式的盲区（收官实证曾捕获 4 处首轮漏检的原稿语法缺陷）；提取 0 块显式警告，禁止 0/0 假绿
    3. 代码实跑：入口代码、核心流程代码、读者第一次会运行的代码逐一执行
    4. mock LLM 探针：Agent 循环类示例用 mock 探针实跑（无需 API Key，方法见 common-pitfalls.md 陷阱 12），逐行核对"预期输出"块——可实跑块升级为 scripts/compare_expect.py 程序化逐字对齐（陷阱 12 强化形态，W21Day1 三段虚构预期输出全由此揭穿）
    5. 命令可执行性：所有命令可复制执行（无占位符、无模糊路径）
    6. 诊断规则：大面积不可运行 → 回 R3 检查版本（版本错是连锁断点的最常见根因，勿逐个修代码症状）
  • R6 终审：D4 教学逻辑与结构完整性复核 + D8 语言流畅性终审复核（低置信只报不改），按 assets/report-template.md 输出报告（含审校统计与收敛判定），过门禁后交付

审校效能准则（所有模式通用）

审校链路是一串模型调用 + 脚本验证，每轮执行遵循以下效能约束（原则：机械的归脚本、判断的归模型、无关的不入上下文）：

  1. 程序化优先：凡脚本能判定的（七模式扫描、块提取、编译、预期输出对齐、漂移核验）不占模型精读——脚本零命中的区域 R2 不展开通读，模型只聚焦代码块、类比段、事实声明区与答案解析层
  2. 轮内并行、轮间串行：R1 五个静态模式一条命令并行跑完（一次 bash 调用输出全部结果）；R3 联网核查与 R5 环境搭建（npm install / tsc 环境准备）互不依赖，可与 R2 精读并行发起；语义判断随归属轮次合并执行（D2+D8 同轮、quiz 解析随 R4），不拆成独立模型调用
  3. 批量连载保持稳定前缀：同一卷多篇审校，规则文件（本文件 + references 清单）作为稳定上下文一次加载、置于会话前部；逐篇只追加文档内容与首查项移交单；不在规则区混入篇名、日期等易变信息（保持前缀稳定以复用）
  4. 输出从简：扫描中间产物（✅ 零命中模式输出）不写进报告；问题清单无发现的优先级整节合并为一行「本节无发现」；报告固定骨架照模板填充，不让模型重写模板话术
  5. 精读聚焦四区：R2 模型精读只覆盖①代码围栏与行内代码 ②类比/前端类比段 ③事实声明区（对比表、架构范式表、版本锚点、行为声明）④quiz 答案与解析层；其余叙述区由脚本结果 + 首尾段扫读覆盖
  6. 停止条件：门禁三条件达标即停轮交付；脚本全绿且无待核实项时不做"再保险"式通读——追加审校不超过 2 轮，仍不收敛回 R1 重扫或升级人工，反复通读属过度审校（陷阱 7）

发布后：生态追踪模式（独立模式，不占轮次编号）

发布不是终点：核心依赖发布新主版本后等 1-2 周生态稳定期再复核，重跑 R5 关键代码片段确认修复未受影响，刷新基线表并清除临时标注（时机、增量节奏与动作清单的唯一出处见 version-baseline.md「持续更新」）。

维度导航

| 维度 | 内容 | 加载文件 | 加载时机 | | -------------- | ------------------------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------- | | D1-D6, D8 | 通用逐条清单（D4 含学习文档结构对号检查，D8 语言流畅性恒加载） | references/checklists.md | 进入对应轮次前 | | D7 | Agent 域专项 | references/checklists-d7.md | 题材命中 Agent / LLM 应用 / MCP / streaming / RAG 关键词时 | | 陷阱与验证方法 | 二十一类陷阱 + 6 类 AI 特殊风险 | references/common-pitfalls.md | 执行修复前 | | P0-P2 诊断 | 修复模式库 | references/diagnostic-patterns.md | 定性问题后 | | 行为语义核查表 | 框架行为语义核查表（R2 唯一语义数据源，整表加载） | references/runtime-semantics.md | R2 时 | | 版本基线数据 | 废弃对照表 + 精确版本基线（scan.py 机器解析数据源，勿通读，按需按框架小节定位） | references/version-baseline.md | scan.py 运行时 / R3 按需 | | 内置脚本 | 块提取 / 预期输出逐字对齐 / 收官漂移核验（用法见各脚本 docstring） | scripts/ | R5 / 收官复审时 |

scan.py 扫描模式

| 模式 | 用途 | 轮次 | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | baseline | 废弃 API / 版本扫描（词库运行时解析自 version-baseline.md；表格行按表头语境豁免——参考/迁移/对照表整表跳过，事实声明区命中带 [表格] 标记，陷阱 13） | R1 | | version-lock | 模糊版本号检测（7.x / ^ / ~ / latest / @next dist-tag） | R1 | | version-match | 精确版本号 vs 已验证基线（数据源 version-baseline.md「精确版本基线」表，安全敏感包零容差；覆盖 pkg@ver / pkg: ver / "pkg": "ver" 依赖行与两列依赖表 | pkg | ver |） | R1（修复批次复扫时复用） | | format-check | 格式污染检测（行号前缀 / 粗体闭合 / 围栏配对） | R0 | | fluency-check | D8 语言流畅性机械初筛（叠用标点/疑似叠词/连接词堆砌/口语化词表/中英空格与全半角标点双形态并存统计；软提示只报不改，代码块与内联代码豁免） | R1 | | version-check | 联网版本对比（需 npm 与网络；含文档驱动包发现、安全敏感包零容差、超前声明检测与包名 404 实名核查——后三项行为细节与定性口径见 checklists.md D6，软提示一律只报不改） | R3 | | cross-check | 跨文件数字漂移检测 | R4 |

scripts/ 内置脚本（v6.1.0 起，scan.py 之外的可复用工具）

| 脚本 | 用途 | 使用轮次 | | ----------------- | ----------------------------------------------------------------------------------------- | ---------------------- | | extract_blocks.py | 提取 MD 全部 TS 围栏为独立编译对象（bash 块只记行号；0 块显式警告防假绿） | R5 编译矩阵 / 收官重放 | | compare_expect.py | 「预期输出」围栏段 vs 实跑输出文件程序化逐字对齐（行级差异输出，exit code 可断言） | R5 实跑对齐 | | drift_check.py | 收官 R0 漂移核验：原稿/交付版/存档 diff 三方对位（剥 ---/+++ 头逐字比对）+ MD5 双基线打印 | 卷级收官复审 |

用法：python <script> <args...>，无参运行打印完整用法（docstring）；三者均在真实审校数据上实测（W21Day1：4 块提取 / 3 段逐字一致 / diff MATCH）。脚本不依赖第三方库，Python 3.8+。

回归验证：改动 scan.py、version-baseline.md 或 runtime-semantics.md 后必须重跑回归断言（版本史与回归口径见 CHANGELOG.md）。

优先级与门禁

  • 🔴 P0 硬伤：事实错误、API 签名错误、语法污染、数字漂移、quiz 缺答案/解析、跨篇结论矛盾——必须修复，未闭合则不得发布
  • 🟡 P1 应修复：类比毒性、概念混淆、断点缺失、结构要素缺失（如手册缺收束环节）
  • 🟢 P2 可批量后处理：一致性与格式问题
  • 发布门禁（三条件，缺一不可）：
    1. 综合评分 ≥ 8.5（D1-D8 等权平均，D7 未加载时按 7 维；评分表见 assets/report-template.md）
    2. 无 🔴 P0 未闭合项（一票否决，全维度生效）
    3. 修复批次合规：单批 ≤7 文件且批次间已用 scan.py 复扫验证（批量误修保护，见 common-pitfalls.md「6 类 AI 特殊风险」）
  • 门禁达标即发布；反复审校追求"完美"属于过度审校（陷阱 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，而非按孤例处理——含「整代版本锁定」形态（一套文档整体锁死旧主版本 API，处置流程见 checklists-d7.md D7.2）
  • 离线备用方案见 common-pitfalls.md「类型定义检查法」；ESM/CJS import 验证命令见陷阱 6（唯一出处）
  • 框架专属签名数据写入 version-baseline.md 对应表格（scan.py 自动加载），不得写进本文件

无人值守模式（agent 自动化审校，默认运行模式）

当无人工在环复核、由 agent 全自动执行审校时（典型场景：通用 AI / Agent 技术文档与学习计划配套文档——详细教程 / 概念卡片 / 测试题——的批量自动化审校）：

  1. 语义判断置信度分级（对 D2 类比毒性 / D4 教学逻辑 / D8 语言流畅性语义子集等无法机械验证的判断）：
    • 高置信 → 直接修复：唯一出处数据命中（runtime-semantics.md 语义核查表 / version-baseline.md 基线表）、实跑证据（mock 探针输出 / 命令执行结果）、机械规则命中（scan.py 扫描项）
    • 中置信 → 修复 + 留痕：官方类型定义比对结论、六步法验证、跨文件一致性的语义层判断、语法错误/病句类语言修复——修复后写入报告「置信度留痕」节
    • 低置信 → 只报不改：无实证的类比毒性判断、教学逻辑主观判断、行为语义核查表未收载且未实跑裁决的新声明、可优化但非错误的风格改写、作者通顺的原有表达风格——仅报告不改文档（防误修优先，见陷阱 4/11）
  2. 实跑职责归 AI：代码实跑（R5）、mock 探针、预期输出核对全部由 agent 执行，不等待人工
  3. 自动门禁判定：R6 输出报告时按三条件自动给出结论——「✅ 可发布」或「⛔ 需人工介入」（触发：未闭合 P0 / 中置信待复核项 >5 条 / 修复批次违规），判定依据写入报告
  4. 批量误修保护为硬性门禁：任何时刻单批修复 ≤7 文件，批次间用 scan.py 复扫验证；违反分批规则的修复批次不得进入 R6 终审

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

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

  1. 在项目工作区新建 review-extensions.md，按 D1-D8 同款格式书写项目专属检查项（如手册七要素结构、卡片「3 收获 1 疑问 1 感悟」收束等模板约定）
  2. R0 预检时将其加入本轮审校待办，在对应轮次与通用清单合并执行
  3. 项目所用框架的签名数据加入 version-baseline.md 对应表，而非本文件

人机分工

有人值守：AI 负责机械验证与实跑，人工负责语义终审；无人值守按「无人值守模式」置信度分级执行，人工降级为发布后抽检——完整分工表唯一出处见 common-pitfalls.md「人机协作分工」。