---
name: reviewer-protocol
description: >-
  当某个 skill 或 agent 需要输出结构化审查意见、或需要解析他方输出的审查意见时使用：本技能定义科研工作台统一审查输出契约（review 围栏 JSON 数组），供所有核验类 skill（如 citation-verify）与发布前审查流程引用。本技能是库技能，不直接面向用户触发。契约规定：意见以 ```review 代码围栏包裹的 JSON 数组输出，元素含 level（error|warn|ok）、check（citation|number|figure|domain|integrity|source）、title、evidence、note 五个字段；全数组最多 8 条，按严重度排序，遵循 evidence-or-silence。
user-invocable: false
metadata:
  domains: [review, contract, verification]
  last_reviewed: '2026-08-18'
---

# 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 条进入交付或发布流程；交付动作本身属危险操作，需用户确认。