reviewer-protocol

# reviewer-protocol：统一审查输出契约 ## 目的 科研工作台里有多处需要"审查"：发布前的全稿审查、citation-verify 核验引用、stage-gate 汇总风险。如果每家输出一种格式，下游（用户、stage-gate、其他 skill）就要学 N 种方言。本契约规定**唯一**的结构化审查输出格式：所有审查方说同一种话，所有消费方只用一种解析。 本技能是库技能：不被用户直接调用，由核验类 skill 与执行发布前审查的一方在各自正文中引用本文件，保证输出一致。 ## 前置检查 （对引用方而言）在输出审查意见之前确认： 1. 本次审查的对象明确（哪个文件、哪个版本、哪段内容）； 2. 已按各自的审查清单完成检查，有具体的检查证据可引用； 3. 没有证据支撑的疑虑已按 guardrail 第 3 条过滤——要么找到证据，要么不写进意见（evidence-or-silence）。 ## 输出模板 审查意见以**一个** ```` ```review ```` 代码围栏包裹的 JSON 数组输出： ````markdown ```review [ { "level": "error", "check": "citation", "title": "第 3 节引文 [12] 的 DOI 无法解析", "evidence": "papers/draft-v2.md 第 87 行：引文 [12] 标注 DOI 10.1000/xyz123；citation-verify 查询 Crossref 返回 404 [Crossref]", "note": "核对原文 PDF 确认真实 DOI；若原文无 DOI，改为引用出版方页面 URL" }, { "level": "warn", "check": "number", "title": "摘要的样本量与第 4 节不一致", "evidence": "papers/draft-v2.md 第 12 行写 n=48；第 156 行表 2 合计 n=45 [用户提供]", "note": "确认是摘要笔误还是表 2 漏了 3 个样品；改后两处同步" }, { "level": "ok", "check": "figure", "title": "全部图号连续且在正文中均被引用", "evidence": "papers/draft-v2.md 图 1-6，正文引用点逐一核对 [用户提供]", "note": "" } ] ``` ```` ### 字段语义 | 字段 | 取值 | 说明 | | --- | --- | --- | | level | `error` / `warn` / `ok` | 严重度，定义见下 | | check | `citation` / `number` / `figure` / `domain` / `integrity` / `source` | 检查类别，定义见下 | | title | string | 一句话说清问题（或通过的关键检查），不超过 40 字为宜 | | evidence | string | **必填**。证据出处：文件路径 + 行号/位置 + 必要引文，带来源标签。空 evidence 的意见不合法 | | note | string | 建议的处理方式；没有建议时留空串，不要写"建议再看看"这种空话 | ### level 定义 - **error**：不修复就不能交付。事实错误、无法解析的引用、数字前后矛盾、抄袭或伪造嫌疑、违反合规红线。 - **warn**：可以交付但用户应知情。表述歧义、覆盖度不足、来源为 `[模型知识—待核实]` 却承担关键论证、图表可读性问题。 - **ok**：关键检查项通过的确认。只用于"这项检查若失败必是 error"的项目——用 ok 告诉读者"这项查过了，没问题"。鸡毛蒜皮的通过项不占用 ok 名额。 ### check 类别定义 - **citation**：引用与参考文献相关——可追溯性、格式一致性、DOI/来源有效性。 - **number**：数字与统计相关——前后一致性、与脚本输出一致性、显著性表述是否过头。 - **figure**：图表相关——图号连续性、正文引用、时效（图是否由当前版本代码生成）、可读性。 - **domain**：领域常识相关——论断与领域共识的关系（注意：共识判断必须给出证据，不能只凭模型印象）。 - **integrity**：完整性相关——产物缺节、承诺的分析没做、stage-report 与产物不符。 - **source**：来源标注相关——guardrail 第 1 条标签的缺失、误用、出处混淆。 ## 输出规则 1. **evidence-or-silence**：每条意见必须有 evidence；找不到证据的疑虑不输出为意见，需要提示时用 `[待复核]` 写在意见之外的散文里。 2. **最多 8 条**：超过 8 条时保留最严重的 8 条，并在围栏外的总评里说明"另有 N 条次要问题未列出，完整清单见 <文件>"。8 条上限强制审查者做优先级排序，避免用意见洪水淹没用户。 3. **按严重度排序**：error 在前，warn 居中，ok 最后；同级内按文中位置排序。 4. **ok 条名额**：最多 2 条，且只给"若失败必是 error"的关键检查（如引用全核验通过、数字全一致）。 5. **一个围栏**：一次审查输出恰好一个 ```` ```review ```` 围栏；围栏外可附一段散文总评，总评里不得出现围栏中没有的新意见。 6. **JSON 必须可解析**：不允许尾随逗号、不允许注释；中文内容正常用 UTF-8。 7. **指向具体位置**：evidence 必须让接收者能跳过去看——"第 3 节有问题"不合格，"draft-v2.md 第 87 行"合格。 ## 消费方指引 - **stage-gate**：把 review 数组中的 error/warn 计数写入 stage-report 的"风险与疑虑"；存在 error 时建议用户 revise 而非 approve。 - **核验类 skill**（如 citation-verify）：输出本契约格式，title 前缀可带自家标识（如 "[citation-verify]"），便于多条意见汇聚时区分来源。 - **发布前全稿审查**：完整遵循本契约；审查清单由审查方按被审对象自行规定。 - **用户**：error 清零是交付前提（guardrail 第 7 条）；warn 的接受与否应留痕。 ## 1 · 意见合并 当多个审查方（reviewer + citation-verify + 其他）对同一产物输出意见时： 1. 合并为一个 ```` ```review ```` 数组，重新按严重度排序； 2. 合并后仍受 8 条上限约束，被挤出的次要意见写入附属文件并在总评中指路； 3. 不同审查方对同一问题的重复意见合并为一条，evidence 中列出全部出处； 4. 意见冲突时（一家说 error 一家说 ok）**并列保留两条**（guardrail 第 5 条），在总评中说明冲突点，交由用户裁决。 ## 2 · 反例（不合格输出） 以下输出**违反**本契约，消费方应拒收并要求重出： - 意见没有 evidence 字段，或 evidence 只写"见上文"； - 用散文罗列意见而不使用 ```` ```review ```` 围栏； - 12 条意见平铺直叙不分级； - error 级意见的 note 写"建议关注"而无具体处理方向； - 在围栏 JSON 里夹带 Markdown 或注释导致解析失败。 ## 3 · 输出前自检清单 审查方在发出 ```` ```review ```` 围栏前，逐项自查： 1. JSON 能被标准解析器解析（无尾随逗号、无注释、无未转义引号）？ 2. 数组长度 ≤ 8？超出的次要意见是否已在附属文件落盘并在总评指路？ 3. 每条都有非空 evidence，且含"文件路径 + 位置"与来源标签？ 4. 排序是否为 error → warn → ok？ 5. ok 条 ≤ 2，且确实属于"若失败必是 error"的关键检查？ 6. 围栏之外的总评没有夹带围栏里没有的新意见？ 7. level 为 error 的每条，note 是否给出了可操作的处理方向（或明确写明"只能删除该句"这类结论）？ 任何一项答"否"，先修正再输出。 ## 4 · 最小完整示例 一次对单文件报告的审查，全部意见如下（虚构示例）： ````markdown ```review [ { "level": "error", "check": "number", "title": "表 1 合计与分项之和不符", "evidence": "reports/monthly-2026-08.md 表 1（第 34-41 行）：分项 12+19+7=38，合计行写 40 [用户提供]", "note": "回查 scripts/aggregate.py 输出，确认是誊写错误还是脚本口径不同；修正后复核全表" }, { "level": "warn", "check": "source", "title": "第 2 节市场规模数据无来源标签", "evidence": "reports/monthly-2026-08.md 第 18-22 行，三处数字均未标注来源", "note": "补检索核实后加来源标签；无法核实的改为 [模型知识—待核实] 或删除" }, { "level": "ok", "check": "citation", "title": "全部 6 条参考文献均可追溯", "evidence": "reports/monthly-2026-08.md 文末条目 1-6，逐条比对检索记录 [OpenAlex]", "note": "" } ] ``` ```` 总评（围栏外散文）：报告结构完整、引用干净；表 1 的合计错误是硬伤，修复前不建议进入 stage-gate 审批。 ## 本技能不做什么 - 不定义审查清单本身：审什么由各审查方自行规定（发布前审查有自己的清单，citation-verify 有自己的核验项），本契约只规定"审完怎么说"。 - 不做审查：本技能是格式规范，不产出任何意见。 - 不裁决意见对错：消费方与用户对意见有异议时找输出方复核，本契约不提供仲裁机制。 - 不约束非结构化交流：日常对话中的口头反馈不需要套本格式；只有写入产物或交付物的审查意见必须遵守。 ## 收尾与下一步 - 引用方落地本契约后，用一份已知产物试跑一次审查，验证 JSON 可解析、字段齐全。 - 契约需要演进时（新增 check 类别、调整字段），通过 customize 修改本文件并同步通知所有引用方；版本变化写入本文件的 metadata。 - 审查通过（无 error）的产物，下一步按 guardrail 第 7 条进入交付或发布流程；交付动作本身属危险操作，需用户确认。