docs-reviewer

用途

docs-reviewer 用于在提交 PR 之前评审文档草稿，关注草稿的语气、风格、结构和术语。它不验证技术准确性是否与实时 SDK 源一致，那是 docs-audit 的职责。

该技能从五个维度对草稿进行评分：

语气栈合规性：检查结构（每个章节是否只回答一个问题）、叙事流（是否先说明主题为何重要及解决什么用例问题）、框架（每个章节首句是否描述开发者目标）、语域（语气是否适合内容类型）、约束（禁用短语、破折号、被动语态、模糊措辞等），以及真实性（结构多样性、可见的编辑选择、简洁性）。
术语一致性：对照术语锁定文件检查每个技术术语，标记任何非规范同义词。
代码示例质量：检查代码块是否结构完整（导入存在、变量已定义、可直接复制粘贴）、是否自解释、变量命名是否自文档化且简洁、是否聚焦单一概念、非确定性输出是否标注为“Typical output”，以及声明一致性（周围文字或代码注释中的每个声明是否由代码演示）。
人机可读性：检查顶部是否有上下文、前置条件是否明确、是否存在承重的前向/后向引用、关键术语是否在首次使用时定义或链接、代码示例是否自包含、行内代码是否使用反引号格式，以及页面是否对来自搜索的人类和 AI 助手都能独立工作。
内容类型对齐：检查结构是否符合语气指南对该类型的规定、信息是否放在正确位置、交叉引用是否指向正确类型。

用户提供草稿后，技能会读取草稿，从 frontmatter 或结构中对内容类型进行分类（教程、操作指南、解释、参考），对上述五个维度评分，然后给出裁定。

裁定系统包含三种：

Ship it：五个维度均评分良好，最多一个带有轻微措辞建议的警告，零失败评分，零术语违规，代码示例结构完整，可进入人工评审。
Tighten：两个或更多警告，或一个无需重构即可修复的失败评分。典型触发包括语气语域渗漏、3 个以上术语失误、超过 40% 的冗长、缺少“typical output”标签、结构雷同。提供具体的行级修复建议，作者处理后重新提交。
Rethink：两个或更多失败评分，或任何结构性失败，如内容类型错误、需要重新列大纲的混合目的章节、根本性的框架倒置、缺少前置条件导致读者无法跟进。提供诊断并建议正确方法，作者重新列大纲后再起草。

升级规则：如果不确定是 Tighten 还是 Rethink，问“作者能否通过就地编辑修复，还是需要重新列大纲？”就地编辑 = Tighten，重新列大纲 = Rethink。

输出格式为结构化评审，包含草稿标题、内容类型、裁定、维度评分表、具体发现（带行引用和建议修复的编号列表）以及做得好的地方（2-3 点）。

适用于文档草稿完成后、提交 PR 之前，需要检查语气一致性、结构和术语时。也适用于判断文档是否达到可提交标准。

该技能不编辑文件，只评审；不提交、推送或创建 PR；不批准或合并，裁定仅为建议性；不重写章节，只提供诊断；不验证 SDK 准确性（导入路径、方法签名、API 正确性），那是 docs-audit 的职责。

可通过追加到 .agents/review-log.md 来跟踪跨评审的模式，包括日期、草稿标题、内容类型、裁定、维度评分、重复模式和术语决策。