rrrrrredy/research-toolkit / plugins/research-toolkit
research-toolkit
FlaggedUse for source-backed long-form research and writing in English or Chinese across fields, including revisions and continuation. Understand requirements, develop analysis through substantive research collaboration, and deliver a complete report after independent review, audit and acceptance.
docs/review-completion.zh-CN.md
View on GitHub# 独立审阅、审计与验收
[English](review-completion.md) | [简体中文](review-completion.zh-CN.md)
本页说明现有 `research_review` 与完成检查如何保留独立工作;实质方法以[角色规范](https://github.com/rrrrrredy/research-toolkit/blob/main/references/subagents-and-review-loop.zh-CN.md)为准。新研究和继续交付采用当前契约,冻结结果保留原契约与历史。
## 执行独立工作
Agent 工具运行 Agent,Toolkit 准备输入、保存产出并返回仍待完成的工作。Codex/Claude Code 子 Agent 使用 Agent 工具已有能力,无需另配 API。
| 任务 | 独立职责 |
| --- | --- |
| 三个内容评审组 | 独立于作者的上下文分别负责需求、结构深度和读者用途;证据与对抗推理;去过程化和自然表达。各组阅读完整现稿和必要原件。 |
| 领域专审 | 有会改变结论的专业判断时,按实际领域另派独立专家。 |
| 审计 | 另一位独立 Agent 检查审阅有效性、重要发现及其处置、决定性判断,并抽查已通过内容,指出仍需修正的问题。 |
| 最终复查 | 独立 Agent 先看现稿并记录自己的问题,再对照审计和实际修改逐条核对。独立复查通过后,Agent 交付成稿。 |
作者、研究贡献者和统稿者属于生产参与者,可以解释或修订自己的成果,不能审自己的成果。使用真实 Agent 任务/会话身份;在作者上下文换一个角色标签不算新 Agent,模型则可以相同。
通过现有 `research_save` 的稿件 `host_task` 登记主稿实际写作者;选择主稿时同时使用 `main: true`。旧保存输入仍可使用,但主稿作者尚未登记时,须先补上身份再准备独立审阅。之前的生产参与者继续保留在活动记录中,不能占用独立席位。
前段可对提纲、假设、计算或论证单元进行独立审阅,检查后续工作所依赖的输入,并绑定该单元的成果和来源。它不替代全稿审阅或最终验收;最终视角读取整合后的完整论证及跨章节一致性。
## 原生调用与原始结果
向 `research_review` 提供当前任务、稿件和证据路径。未选用外部执行器时,返回待完成的 Agent 工具原生任务及已保留的完整输入;Agent 工具据此启动各独立 Agent,并给予原件访问能力。
提交形式示例:
```json
{
"task": "study",
"artifact": "reports/current.md",
"evidence_paths": ["sources/primary.md"],
"host_result": {
"slot_id": "copy-the-returned-slot-id",
"host_task": "actual-independent-agent-task-id",
"response_path": "reviews/host/original-response.json",
"execution_path": "reviews/host/original-execution.json"
}
}
```
这里是占位值,不是完成记录。将实际原始回复和执行记录保存为任务内非空 UTF-8 文件;返回任务说明所需结果内容。不从作者的理解拼出有利回复,不覆盖负评,不编造 Agent 工具标识;失败和不完整尝试也保留。
返回的 `assignments` 每项提供 `slot_id`、`role`、`assignment_ref`、`assignment_version`,本次操作另有 `input_version`。原始 JSON 回复须带回两个版本。原始执行记录包含 `host_task`、`status: "completed"`、`assignment_version` 及实际观察到的 Agent 工具事件,必须来自产生该回复的实际执行。
`scope` 默认是 `full_report`。新 v3 全稿计划由三个评审组覆盖七项视角,`domains` 默认 `[]`,按报告实际需要指定专业领域。前段单元审阅将已登记 `unit_id` 作为 `scope`,用 `perspectives` 选择相关视角。接续调用省略这些可选项时沿用已有选择。全稿仍需完成自己的审阅。
单元的必要发现或有据不改回应需要独立裁定时,在同一 `research_review` 调用中使用 `audit: true`。该输入已有的内容审阅继续有效,下一项任务是单元审计。开启后,后续调用保留这项责任,不能通过 `audit: false` 撤掉;单元不会因此增加最终验收。全稿始终需要审计。单元审计核对 `applicable_requirements`,包括全局要求、明确分配给本单元或其上游依赖的要求;全部有效要求仍可回读。
同一操作接收内容结果,准备独立审计,再在必要问题解决后准备最终验收。输入未变且已有有效结果时,继续未完成工作,不重复产生一次通过。每项待完成任务在冻结 JSON `assignment_ref` 之外返回 `reading_ref` 阅读入口,完整视图见[使用说明](usage-modes.zh-CN.md)。`include_assignment` 默认 `false`,执行者仍须能够读取完整输入及来源原件。
提交后,`submission_recorded: true` 表示已保存本次结果,`delivery_ready` 表示整份报告是否已通过独立检查。MCP 的 `research_review` 可传 `summary: true`,CLI 的 `review` 可用 `--summary`,查看这两种状态、待办任务数、问题数及下一步 `action_required`。需要任务引用或问题详情时,沿用同一输入再次调用,省略本次提交的结果和摘要选项。
冻结的角色任务可以通过 `shared_input` 保存共享输入的相对路径和 SHA-256。历史任务将输入内嵌在 `assignment`,仍可读取。原生 Agent 使用 `reading_ref`;需要通过工具直接获取完整请求时,设置 `include_assignment=true`。
另配命令或端点是可选执行方式,见[使用说明](usage-modes.zh-CN.md#评审后端),同样履行独立性和当前版本要求。历史 `self` 结果继续可读,但属于作者自检,不是当前独立审阅路径。
## 输入与版本绑定
保留各任务实际使用的需求、有效补充要求、报告、来源与主张记录、相关原始材料及方法指令。支持来源和已登记的反证来源一起进入输入,网址列表或作者摘要不能替代必要原文。
计划与结果绑定稿件及所需输入版本。任务中继续保留输入、指令快照、原始回复和执行记录;文本哈希仅规范换行,不改写原研究记录。文件引用须位于任务内并匹配其哈希。
新全稿任务使用 `progress.review_contract: 3` 和 `review_plan.contract_version: 3`。已保存的 v2 任务沿用七路分派及原交付规则。原始评审回复和 v3 新阶段保留在现有审阅日志及冻结任务里。审阅契约编号与交付检查器编号分别管理。
实质修改后保存新稿或来源版本,使用 `revision: true` 处理受影响审阅,保留之前的任务和回复。最终全稿验收覆盖交付正文;历史结果表示当时检查过什么,不自动批准后来的文字。
修订任务的 `revision_context` 保留各自最后一次实际完成的原始回复和冻结输入。中间连续改稿、尚未收到新回复,或只收到部分回复时,其余角色的已有工作继续保留。`resume_host_task` 返回相同职责的原独立 Agent 标识,Agent 工具可直接继续该任务;原任务不可用时,将这些原件交给新的独立上下文。审计和验收也可回查已保留的各类原回复。
在这些接续任务中,`report_changes` 提供相对该角色实际已审稿件的改前/改后原文和行号,`changed_materials`、`changed_context` 定位相对其已审输入变化的材料和任务内容。`reviews` 内的 `input_version`、视角和领域标明原工作的范围。计划级 `changed_inputs`/`unchanged_inputs` 仍比较相邻两版的输入哈希;各角色可能读过不同版本,应以自己的原输入和上述差异继续核查。原文始终可访问,差异用于定位。
`prior_required_findings` 承接三类角色的必要问题;审计/验收缺陷保留原 `critical_checks`、`sample_checks` 或 `open_issues` 位置,以 `attempt_id/字段/序号` 接入已有审计处置键。仅在 `basis` 表达的否定判断也会保留。原输入、回复与执行记录继续绑定版本,新稿不会清除这些发现。审计在已有 `prior_findings` 中对照当前正文逐项处置,验收取得该审计及对应原件。执行者据此找回已有核查,检查受影响的推理并确认完整当前稿,不自动沿用旧 PASS。已冻结的任务说明保持原样。
## 发现与必要修正
有效审阅包含定位、依据或推理,并实质覆盖所分视角。负面判断也可完成审阅,但必要修正仍未解决。通用 PASS、截断回复或读错材料的回复不能完成任务。
保留原始结论和严重程度。作者可以提出修正或有据不改的回应,由独立裁定核对原意见是否误判、当前正文是否已经解决,或仍待处理。作者不能追加一个处置状态就关闭自己的必改项。可选偏好无需转成修改;重要的不改决定必须对照原稿和证据核查。
不反复运行同一未变版本的有效负评以求通过,继续发生变化或确实缺失的工作。某条意见错误不意味着整份实质审阅无效;保留并裁定具体发现。
## 审计与抽查
审计者读取完整当前稿、要求、审阅结果和相关原件,从这些内容中选择检查项,不只接收作者挑出的片段。
v3 的 `audit_scaffold` 自动列出实际意见编号、位置、可能重复的意见及应核查内容。审计 Agent 确认哪些意见可以共用一次裁定。对同一处提出同一个问题的意见只查一次。在 `disposition_groups` 中写一份证据和裁定,包含 `finding_ids`、`decision`、`reason`、`evidence`。旧稿意见可用 `prior_finding_groups`。工具验证每条原始编号恰好被覆盖一次,并保留意见原文和裁定。
从 v3.1.0 起,插件包内可运行此命令。审计任务的 `response_template_ref` 指向可复制的 JSON 回复骨架。要直接取得当前待办审计的骨架,运行 `python scripts/research_workflow.py review --scaffold-audit --workspace WORKSPACE --task TASK`。它输出真实评审和意见编号、每项适用要求以及稿件和派工版本。独立审计 Agent 填写判断、理由和原件位置,按证据选取抽样;如果合并意见,将对应编号从单项移入同一 `disposition_groups`。空骨架无法通过提交检查。例如任务保存在 `work/tasks/gpai`,就传 `--workspace work/tasks --task gpai`。
影响交付的分歧若还缺依据,审计 Agent 用 `verification_requests` 安排一项针对性核验。新的 Agent 先看这个问题和原件,再由审计 Agent 根据返回的依据判断。四路一致和一路提出都需要有证据。
关键要求、决定性结论、关键数字与引用、重要反证、重大问题、重要不改决定,以及会影响成果的已修正主张,都应核查。其他已通过/未报问题的内容按实际研究选择样本,覆盖支线到主稿的转换、必要限定及跨章节判断。
每个选择保留位置、原因、所看证据和结果。不用固定首尾/哈希选段或抽样比例代替判断。发现问题后按原因扩查,例如同一来源、指标、支线或改写方式,直到查清受影响工作并解决必要问题。此工作由已有审计任务承担,不新增抽查角色或评分体系。
审阅有效、报告就绪和最终验收是不同判断。审计可以确认一份负评有效,同时指出报告仍需修订。最终验收读取修订后的完整报告,不能只数通过记录。
使用 `purpose=evaluation` 时,保留样本原稿,在同一输入上完成独立评估。有效负例可以返回 `evaluation_complete: true` 和 `evaluation_verdict: "needs_revision"`,有效正例返回 `"pass"`。报告交付有单独的资格判定,使用 `purpose=report_delivery`。
## 自动运行审阅和改稿
已有登记稿件后,协调 Agent 可以用当前宿主运行:
```bash
python3 scripts/research_host.py --workspace ./tasks --task study --host codex --complete --max-active 2 --request study-review.json
```
来源和要求已保存后,把下面的 JSON 交给 `research_workflow.py save --workspace ./tasks --request save-draft.json` 登记主稿。将示例 `host_task` 换为实际写稿会话 ID。
```json
{"task":"study","draft":{"path":"reports/current.md","main":true,"complete":true,"host_task":"actual-writer-session-id"}}
```
`study-review.json` 用 `artifact` 指向同一个相对路径。请求文件支持带 BOM 的 UTF-8。
```json
{"artifact":"reports/current.md","evidence_paths":["sources/primary.md"],"domains":[]}
```
请求是 JSON 对象,可填 `artifact`、`evidence_paths` 和 `domains`。原作者上下文无法继续且已有移交授权时,使用 `writer_handoff_from`。默认同时运行两个任务;只有一个名额也能让独立上下文依次处理。每项任务照常保留真实上下文和原始回复。宿主需要具备独立执行能力。见[支持的宿主](usage-modes.zh-CN.md#agent-host-execution)。
协调 Agent 负责排队,把审计确认的修改交给一个写作者,并对改动发起独立复查。成功时,`--complete` 返回 `status: "completed"` 和 `completed: true`,随后交付已核查的报告。受阻时说明哪项工作还未完成。
第一次最终复查先盲读,再核对审计。若复查者退回修改,且范围、需求和原始资料都一致,修订稿通过当前审计后交回原复查者。它阅读完整新稿,核对差异和自己提出的问题,结论绑定新稿版本。范围或资料有变化,或原复查会话无法接续时,重新安排盲读。
## 完成与恢复
当前报告通过独立最终复查后,将 `artifact` 和交付说明 `message`(也可用 `delivery_message`)传给 `research_finish`。工具核对当前证据和独立审阅结果,写入最终回执,并返回 `completed: true`。
查看工具任务时可运行:
```bash
python3 scripts/check_review_completion.py <task-directory> --artifact reports/current.md
```
命令读取记录和版本绑定,不再启动一位评审者。实际内容判断保存在原始回复和证据中,应保留全文,不只保留解析字段。
Agent 工具取消、依赖不可用或回复格式错误时,保留失败原件,解决实际原因后继续该任务。不因固定执行时长或模型调用次数改变研究责任。同一任务写入复用已有任务锁,不另建协调服务。
## 历史记录
早期 `model_review`、`review_audit`、`sampling_audit`、处置和回执按实际使用的条件保留。1.x 自评、合并视角和可选审计记录不升级为 v2 验收。继续交付时复用原材料,完成当前独立工作,不抹去旧失败或声称这些工作早已发生。见[兼容性](compatibility.zh-CN.md)。
冻结评测和研究对照沿用其原始协议,描述当时研究,不作为新研究的默认要求。软件正负对照明确标注合成,不能代替真实 Agent 工具执行。
离线使用时可从插件根目录打开`references/subagents-and-review-loop.zh-CN.md`。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |