Revise-Sci
Overview
Use this skill to turn reviewer comments, the original manuscript, SI, and attachments into two deliverables: a revised manuscript and a structured Response to Reviewers. Both come out in Markdown and Word.
The workflow is script-gated. Do not skip steps. Do not fabricate experiments, data, statistics, or references.
The comment parser accepts both atomic comment-unit HTML and reviewer-simulator style report HTML with critique lists.
The manuscript atomizer recognizes numbered section headings such as 1, 1.1, and 2.3.4 even when the source Word paragraph style is not a formal heading style.
开场监工卡(每次启动须原样输出给用户)
返修改稿最易在以下环节出错,AI 可执行但结果是否正确只有用户能核对。启动本技能时须原样输出此卡:
- 意见拆解须用户核对完整性:拆解完成后 AI 会输出意见清单,须对照原始审稿信逐条核对:是否存在被合并或整条遗漏的情况。条数不一致即存在遗漏。
- 改动须逐处核对:每处改动 AI 应提供「原句 → 改后句」对照,用户须确认语义未变、未夹带未经同意的新结论。未见对照不应放行。
- 覆盖须查对照表:交付前 AI 应提供「意见 × 是否回复 × 是否改稿 × 结局」对照表。「改稿」列为空**但结局标
push_back(有意驳回不改)**的属于正常,非遗漏;真正的遗漏是:某条既无回复、结局又不属于completed/push_back/需作者确认。须区分「有意不改」与「遗漏」。- 标注"需作者确认"属于正常行为:AI 无法获取用户的数据/实验时应标注「需作者确认」等待补充,此为设计行为而非故障,须由用户逐项补齐。
- 门禁通过仅保证形式合规:门禁仅检查格式、覆盖率与红线等机械项,改动是否正确、说理是否通顺须用户自行核对,不应将门禁通过等同于"改对了"。
【Python 解释器探测:启动前置,一次探测全程沿用】 本文档中的 python3 / python 仅为 macOS/Linux 的习惯写法,并非硬性要求。启动前执行一次 python3 --version:
- 输出正常版本号 → 本次会话所有命令统一使用
python3。 - 报 command not found、无任何输出、或弹出应用商店 → 改为执行
python --version,能输出版本号则将后续所有命令中的解释器统一替换为python。注意 Windows 自带一个 0 字节的python3占位程序,python3 --version弹出商店或无输出即表示命中该占位程序,不视为已安装 python3,按"未安装"处理(用户也可在 设置 → 应用 → 应用执行别名 中关闭python3.exe)。 - 反之
python无法输出版本号则改用python3(macOS 12.3 起系统不再预装python)。 - 两者均无法输出版本号,表明该机器未安装 Python,须停止并告知用户先行安装,不得强行执行。
- 探测仅执行一次,后续所有命令沿用同一解释器名称,无需每条命令重复探测。
跨会话接续(每次开局前置,与监工卡是两件事)
监工卡是「启动提醒」,接续报告是「恢复上一会话的进度」。每次进入本技能、且 project_root 已存在时,须先执行接续命令后方可继续:
python "<技能>/scripts/session_journal.py" resume --root <project_root>
env_preflight.py 会将此命令输出为 RESUME_CMD(连同 LOG_CMD / CITATION_CHECK_CMD,均为解析好的绝对路径)。读取接续报告后,据其与用户进行接续确认:复述当前 phase、已处理的 comment、以及 decisions_log.md 中用户历次要求,询问「继续执行 <下一步>,是否正确?如有新要求请先提出」等待用户确认后方可继续。
用户在会话中途插入任何临时要求(改哪节、换策略、加/撤某条意见的处理方式)时,当场 log,后续会话必读必守:
python "<技能>/scripts/session_journal.py" log --root <project_root> --note "<用户要求原话>"
Mandatory Intake Before Any Full Pipeline Run
When the user provides a comments_path, a manuscript_docx_path, or both, do not jump straight into run_pipeline.py.
First, env precheck (soft gate, before any pipeline run): python scripts/env_preflight.py <project_root> --cli esearch --py docx; it writes env_status.json, and the last line prints PRECHECK: OK|ASK|BLOCKED. BLOCKED (Python too old) → stop and guide upgrade; ASK (missing optional tools like esearch/python-docx) → ask the user per tool whether to install, give guidance, continue only after the user answers installed/skip; OK → continue. Rollback uses state_manager.py snapshot + Patch-hash (no git checkpoints).
Always run:
python scripts/intake_router.py --comments <comments_path> --manuscript <manuscript_docx_path>
Before any substantive revise work, report to the user:
- which
comments_input_modewas detected; - which branch-specific workflow will be used next;
- that the workflow preserves the same atomicization, fragment-only rewrite, anti-AI polish, state-window, anti-forgetfulness, and hard-gate rules;
- then ask the user to confirm that routing decision together with the desired
project_root/ output path.
If the input does not match any supported branch:
- do not proceed silently;
- ask the user whether to map the input to an existing branch or create a new branch;
- any new branch must still preserve the same atomicization, fragment-only rewrite, anti-AI polish, state-window, anti-forgetfulness, and hard-gate rules.
If the user has no reviewer comments and only provides the manuscript:
- run
python scripts/intake_router.py --manuscript <manuscript_docx_path>; - ask whether to use
reviewer-simulatorfirst to generate reviewer comments; - check global availability using
python scripts/ensure_global_skill.py --skill-name reviewer-simulator; - if the skill is missing and the user confirms installation, install it from your own skills backup repository (reviewer-simulator subdirectory) before invoking that branch.
Comment Input Modes
六种模式:docx-review-comments / docx-review-letter / reviewer-simulator-html / reviewer-response-sci-html / atomic-comment-html / no-comments-manuscript-only。intake_router.py 报出 comments_input_mode 后、向用户汇报分支前,先 Read references/comment-input-modes.md(各模式的解析器行为,以及 docx-review-letter 与 reviewer-response-sci-html 两个分支的专属要求)。
Required Inputs
comments_pathmanuscript_docx_pathproject_rootoutput_md_pathoutput_docx_path
Optional but supported:
si_docx_pathattachments_dir_pathreference_docx_pathjournal_stylepaper_search_results_pathreferences_source_pathexpected_comments_modecontext_token_budgetcontext_tail_lines
Output Contract
固定交付:response_to_reviewers.md / response_to_reviewers.docx、改后稿 output_md_path / output_docx_path(原稿为 .docx 时默认 in-place 保原稿格式,定位失败硬停退出码 3;可选 --track-changes 词级修订痕迹)、各类报告与 data/ 索引。向用户说明交付物前、以及运行 export_docx.py 前,先 Read references/output-contract.md(完整产物清单、in-place / --allow-rebuild-fallback / --track-changes 的语义)。
Pipeline
执行 Pipeline 任何一步前,先 Read references/pipeline.md(逐脚本顺序与参数说明、export_docx.py in-place / --track-changes 细则、三层核查的四步细则与逐字极性模板、round22 一键 pipeline 状态机与退出码)。骨架顺序如下,脚本名与参数以该文件为准:
- 原子化与索引:
intake_router.py→preflight.py→atomize_comments.py→atomize_manuscript.py→manuscript_index.py→extract_docx_images.py→build_issue_matrix.py→state_manager.py refresh→citation_guard.py(有 paper-search 结果时)。 - 🔴 [意见清单核对·必停](见下节)→ [通读定策略] 给每条 unit 填
revision_strategy(见下节)→revise_units.py→build_literature_index.py→matrix_manager.py bootstrap/audit→merge_manuscript.py→reference_sync.py→build_reference_registry.py→export_docx.py。 - 收口核查:
final_consistency_report.py→ 三层核查(numeric_candidates.py数值一致性 →structure_outline.py交叉引用 →methods_terms.py方法学漏写,综述稿跳过方法学;每层 = 第 1 层确定性锚 + 第 2 层独立检测子代理 + 第 3 层delegate_review.py反向验证,命中 confirmed 即 HALT 交用户裁决;主 agent 忽略 verify 退出码、只读逐条 verdict)→ DoD 盲检(见下文)→strict_gate.py。
单入口(run_pipeline.py 内置 round22 状态机:退出码 3 为预期人工暂停并打印 PIPELINE_PAUSED phase=<phase>,用 --resume --confirm-* 续跑):
python scripts/run_pipeline.py --comments <comments_path> --manuscript <manuscript_docx_path> --project-root <project_root> --output-md <output_md_path> --output-docx <output_docx_path> [--journal-style journal-manuscript|nature-review|cell-press|lancet-review] [--expected-comments-mode <comments_input_mode>] [--context-token-budget 4200] [--context-tail-lines 80] [--paper-search-results <paper_search_results_path>] [--resume] [--resume-from <step>] [--resume-keep-unaffected] [--force-rebuild] [--allow-rebuild-fallback]
[意见清单核对·必停](拆意见后、改写前的强制关卡)
位置:atomize_comments.py 拆完审稿意见之后、revise_units.py 开始改写之前。这是流程内部的硬关卡,与开场监工卡不同:监工卡是启动时提醒,这一步是拆完意见后的当场核对。
拆完审稿意见后,立即停下,把每条 comment_id + 该条前 30 字列成清单打给用户,并原样问:
「请拿原始审稿信对照数一遍,条数对不对?有没有哪条被合并成一条、或整段漏掉?(尤其审稿人用连续散文、
(i)(ii)、罗马数字、或一段里塞多个要求时最容易漏)」
用户确认"都在、没漏"后才继续改写。用户指出漏掉或被合并的,回去把它补成独立 comment(补进 units/、重新原子化)后再继续,不得跳过这一步直接跑 revise_units.py。
[通读定策略·前置阶段](清单核对通过后、逐条改写前)
实际返修的第一步不是逐条修改,而是先将所有意见通读一遍、确定每条的应对策略。本流程同理:意见清单核对通过后、revise_units.py 开始逐条改写之前,须先做一轮 triage,不得从 atomize 直接跳至逐条改写。
对每条 comment 定四选一的策略,并写进该 unit 的 revision_strategy 字段(units/*.json):
| 策略 | revision_strategy 值 |
含义 | 结局 |
|---|---|---|---|
| 照做 | comply |
认可意见,按要求改正文 | 走正常改写 → completed / needs_author_confirmation |
| 部分让 | partial |
部分采纳,改一部分并说明取舍 | 正常改写 + 回复信说明界限 |
| 驳回 | push_back(或 驳回/reject) |
不采纳、正文不动,在回复信据理反驳 | 一等结局 push_back(见下节) |
| 补数据 | needs_data |
需新增实验/数据/图,当前材料不足 | 落 needs_author_confirmation,等作者补 |
硬规则:revise_units.py 逐条改写前,每条 unit 的 revision_strategy 必须先填(该字段已存在也要强制先确认/覆盖,不能留空跳过)。通读定策略是本阶段的产出,把结论落到字段里再进逐条改写。
[驳回/不改] 是一等合法结局(不是漏改)
除 completed / needs_author_confirmation 外,新增第三个合法结局 push_back:认定某条意见不应采纳,正文一个字不动,只在回复信里据理反驳。这是真实返修的常态(审稿人误解、超范围要求、与本文定位冲突等),不是缺陷。
- 怎么触发:该 unit 的
revision_strategy设为push_back(或驳回/reject等,见上表)。revise_units.py即把该条status置为push_back:正文不改、revised_excerpt记为「N/A — manuscript unchanged」、回复信生成据理反驳的中英回应。反驳理由填 unit 的push_back_rationale_zh/push_back_rationale_en(不填则回复信留占位提示作者补)。 - 覆盖判定别误报:
issue_matrix.md的「修改动作」列会显示「不改(驳回)」、状态列显示push_back;监工卡第 3 条的对照表里,某条「改稿」列为空但结局是push_back的,是「有意不改」,不得判成「漏改」。判漏改的唯一标准是:status既非completed、又非push_back、又非needs_author_confirmation,或该 comment_id 在回复信里根本没有回应。 - 不阻断交付:
push_back是已决结局,delivery_status只被needs_author_confirmation卡;push_back计入project_state.json的counts.push_back,不进待办。 - 红线仍在:驳回≠可以不回应。回复信里该条必须有据理反驳的 response(中英),否则仍算漏回。
[合并意见] 允许多条相关意见协调回应
原子架构默认每条意见一个密封 state window,但相关意见(同一处、同一诉求的不同侧面)应允许合并成一处协调回应 + 交叉引用,而不是各写各的、自相矛盾。
- 最小用法:给相关的几条 unit 设同一个
merge_group(任意稳定 id,如MG-limitations),并指定其中一条为merge_lead(主回应所在的 comment_id)。主条写完整协调回应;其余成员条的 response 里交叉引用主条(如「详见 R2.3 的统一回应」/ "see our unified response to R2.3"),不重复长篇。 - 窗口不封死:
state/comment_windows/<id>.json会带上merge_group/merge_lead,据此从comment_registry.json找到同组兄弟条一起看,避免协同时上下文被切断。 - 不拆原子架构:合并只是「分组 + 交叉引用」,每条仍是独立 unit、独立 comment_id、独立覆盖核验,绝不把多条塞进一条。
Anti-Forgetfulness And Token-Budget Protocol
本技能不把全稿和全部意见塞进一个上下文窗,而是按 comment 逐条加载 state window。处理任何一条 comment 前,先 Read references/anti-forgetfulness.md(七条防遗忘原则:intake 先路由、节/段原子化、comment 级 state window、section digest、token 预算压缩、cycle log、snapshot)。每条 comment 的推荐加载命令:
python scripts/state_manager.py --project-root <project_root> write-cycle --comment-id <comment_id> --token-budget 4200 --tail-lines 80 --json-summary
外置契约(按需 Read,主文件只留索引)
- 需要锁定块级字节不变的确定性修订(anchorize → patch → apply)时,动手前先 Read
references/patch-protocol.md。 - 改写任何句子、删句或新引术语前,先 Read
references/abbreviations.md(缩略语首展一致性规则与abbreviation_index.json的硬错/软警告口径)。 - 生成
response_to_reviewers.md前,先 Readreferences/response-format.md(标题层级与每条 comment 的 5 个固定小节)。 - 进入
revise_units.py改写、文献补充、--resume、polish 或strict_gate.py任一环节前,先 Readreferences/rules.md(全部 Rules:引文双验与引文核证、reference 搜索治理、定位保守规则、resume 规则、polish 去 AI 五项与片段级守卫)。 - 撰写或改写任何正文片段、回复信英文前,先 Read
references/typography.md(斜体/上标/下标/加粗行内标记与全半角规则;标记与[n]同等承重)。 - 每轮改写前与收口前,先 Read
references/anti-patterns.md(反例黑名单,命中任一即停)。
Definition-of-Done (DoD) 自检清单(改稿收口)
位置:polish 完成后、strict_gate.py 运行前。硬规则:清单未逐项确认通过,不得向用户声明"改稿完成"。
🔴 委托盲检(不得主 agent 自评):改稿完成后自评容易默认通过且漏项。strict_gate.py 运行前必须把 DoD 清单委托给独立上下文的subagent盲检,不得自己直接打勾:
- 生成任务包:
python scripts/delegate_review.py pack --checklist references/dod_checklist.json --gate revision-dod --files <改稿相关文件> --comments <comments_path>(--comments传本次审稿信原文,盲检子代理据原信逐条点名核对漏回/答非所问;同一comments_path与run_pipeline.py --comments一致) - 派一个独立subagent(Claude Code 用
academic-blind-reviewer;其他平台派通用subagent),把任务包原样给它、不要给它本次改稿的写作上下文,要求按任务包返回 JSON 数组。 - 校验返回:
python scripts/delegate_review.py verify --checklist references/dod_checklist.json --gate revision-dod --return <subagent返回.json>;退出码非 0(任一缺项/fail/无证据)= fail-closed,据subagent证据修复后重跑,未过不得声明改稿完成。
⚠️ 盲检降级告警:若当前环境派不出真正独立的subagent(非 Claude Code 客户端、provider 不支持 Task/子会话),绝不能用同一个 AI 自问自答冒充盲检(那就是自证)。此时明确告诉用户:「本环境盲检不可靠,请你亲自复核这几点:(列出该盲检本应查的关键点,如 RV-G1 引文↔参考一一对应、RV-G3 改动是否跑题、RV-G5 去AI五项、RV-G7 缩略语首展、RV-G8 常识/事实错误等)」,把判断权交回用户,不得伪造一份"通过"的盲检返回。
下列清单与 references/dod_checklist.json 逐项对应(改清单先改 JSON,再同步此处散文);能脚本核的项subagent会先跑脚本:
逐项清单(通用 RV-G1G8 / 特有 RV-R1R12 / 投稿前作者自检)见 references/dod-items.md:生成盲检任务包前、向用户摆逐项结论前,必须先 Read 它。
🔴 收口前置闸口:delegate_review verify 必须 exit 0(含 RV-R8 结构完整性),否则不得声明改稿完成。任一项 fail 均为阻断。
🛑 DoD 停·摆结论等确认(strict_gate 前的最后一道人工闸):盲检 delegate_review verify exit 0 之后、strict_gate.py 之前,不得直接收口。先把逐项结论摆给用户,每条 DoD(RV-G1G8 / RV-R1R12)是 pass / na / 🟡soft-report,软项(RV-G8 常识、RV-R12 拉丁斜体、去AI软提示、句长)列出但标明不阻断;同时给「意见 × 是否回复 × 是否改稿 × 结局(completed/push_back/需作者确认)」对照表。打印后 HALT,等用户明确说「可以收口」再跑 strict_gate.py 并交付。用户没确认就继续 = 违规。这与开场监工卡、清单核对是三道不同的人工闸:开场提醒 → 拆完核对 → 收口前摆结论。
流程跳步的用户干预方法
发现 AI 遗漏意见、改稿偏离原意或将半成品作为成品交付时,可将以下指令直接发送给 AI:
- 「审稿信里 Reviewer X 第 N 点你没拆出来,回去把它作为独立 comment 加进
units/,重新原子化再重跑revise_units.py。」 - 「把第 X 条对应的原句和你改后的句子并排贴给我,我要确认意思没变、没夹带我没同意的新结论。」
- 「给我一张表:每条审稿意见 × 有没有回复 × 正文改了哪句(引用
manuscript_edit_plan.md的 revised_excerpt)。哪条空着就是漏了,当场补。」 - 「先别跑完整 pipeline,先只跑到
atomize_comments.py把意见清单给我看,我对照原始审稿信确认条数无误了再往下。」 - 「你这环境派不出独立subagent就别假装盲检通过了。把这轮该盲检的关键点列给我,我自己核。」