scientific-writer

Scientific Writer Loop

该工件是一份科学写作作品（草稿 + 其数据集 + 图表 + 可选代码）。 每次迭代都会评议 → 评分 → 修订：五位专业评审给出具体发现， 独立的 peer_reviewer 按相同维度将论文评为 0–100 分，而 scientific_writer 则修正文稿、图表和代码，并运行用户的 <plot_command> 来 重新生成图表。循环持续进行，直到分数超过 <pass_threshold> 或预算用尽。所有 工作都在沙盒内的副本上进行；绝不会修改用户的原始文件。

参与者（都在此文件夹中）：

• roles/figures_judge.md、roles/scientific_judge.md、roles/style_judge.md、 roles/formatting_judge.md、roles/code_reviewer.md——五位评审；每位都会生成共享的 schemas/finding.schema.json。
• roles/peer_reviewer.md——总结性评分者（遵循自身的诚实规则）；生成 schemas/peer_review.schema.json 并决定是否 pass。
• roles/scientific_writer.md——修订者；修复代码 → 重新生成图表 → 更新文稿。
• schemas/finding.schema.json、schemas/peer_review.schema.json——两种经过验证的输出。

无法启动则降级处理。 在 Claude Code 中，将当前启用的评审者作为真正的 Agent 子 Agent 并行启动，然后启动一个全新的 peer_reviewer，再启动 scientific_writer；否则在行内 分别扮演各个角色。你是编排者。

为什么评分者要这样设计（诚实性问题）

peer_reviewer 按照评审者提出批评的相同维度评分——这容易导致附和、在循环终止压力下抬高分数， 以及修订者钻评分标准的空子。roles/peer_reviewer.md 对此作出应对：(1) 独立评分，在阅读评审意见前，先根据论文 + 数据集重新推导各项维度的评分； (2) 自行核验部分数字/引文，而不是相信“已经修好了”；(3) 必须指出评审者遗漏的问题； (4) 坚持固定、有锚点、可复现的标准，不因投入精力或迭代次数而加分； (5) 采用硬性门槛（确认存在阻断性问题时，无论平均分如何，论文都不通过）；(6) 通过 实质性检查，识别仅满足表面要求的情况。修订者针对评审者提出的具体发现进行优化；评分者 则进行整体评判——因此，“解决每一项发现”并不能机械地保证通过。

适用场景

当已有科学论文草稿，且用户希望通过多位评审的批评和独立的同行评审评分，将其提升到指定质量标准以上时使用。默认情况下，运行下面完整的评议→评分→修订循环。备选方案：如果用户只需要评议（不需要重写），则运行一轮评审者 + peer_reviewer，然后停止。不适用于从空白页开始撰写论文，也不适用于独立的文献综述。

设置

以交互方式解析绑定项。 如果工作目录中存在 loop.run.yaml，则加载它，用一行确认各项值，然后跳转到循环。否则：在 Claude Code 上（可使用 AskUserQuestion 工具）推断每个绑定项的可能值，并将其作为推荐选项呈现；在其他宿主上，则分别以引用的纯文本提示询问。然后写入 loop.run.yaml（格式参见 examples/run.example.yaml），并确认每项值——包括启用的轴数量（4 个还是 5 个）以及文献检索层级（实时或降级）——之后再创建任何其他文件。

绑定项	含义	默认值	推断方式
<draft_path>	要改进的草稿（markdown/text/tex）	—	扫描工作目录，查找可能的草稿
<dataset_paths>	声明/图表所依据的数据文件——用于核验数字	—	在草稿附近扫描数据文件
<figures_dir>	草稿引用的图像目录	—	在草稿附近扫描；也可以为 null
<code_paths>	生成图表/结果的源文件；为空 → 移除代码轴（n_axes=4，不含 code_reviewer）	—	扫描绘图/分析脚本
<plot_command>	根据代码重新生成图表/结果的命令；为 null → 图表/代码仅编辑，不会重新生成（标记为“需要重新生成”）	—	查看 pyproject.toml/.venv/README；例如 python3 code/make_figures.py
<citation_style>	formatting_judge 强制执行的唯一格式（APA|MLA）	APA	询问用户
<target_venue>	可选的目标发表平台，其格式和篇幅规范将适用	—	询问用户
<length_limits>	可选的摘要/论文字数目标	—	询问用户
<intent>	论文的核心发现/贡献，用 1-2 句话表述——冻结；撰写者不得更改	—	阅读草稿，提取核心内容并与用户确认
<pass_threshold>	peer_reviewer 必须达到的 overall_score（0-100）才能停止（且不得触发任何硬性门槛）	85	一篇扎实的论文，无须追求完美
<budget>	最大迭代次数	6	—
<patience>	连续多少次迭代未改进后停止	2	—
<sandbox_root>	工作副本、评审意见、审核结果和记录文件的存放位置	./sandbox	—

文献工具链。 引用依据（撰写者）和核验（scientific_judge、peer_reviewer）均通过同级的 literature-search 技能完成——解析 <lit_skill_dir>（该技能作为同级目录安装，例如 ~/.claude/skills/literature-search/）、<lit_py> = python3 和 <lit> = <lit_skill_dir>/tools/lit_search.py；在子命令后追加 --cache-dir <sandbox_root>/literature/.cache 以复用缓存。在设置时确认 <lit> --help 可正常运行；如果缺少该技能，告知用户，并选择安装它（将仓库中的 loops/literature-search 文件夹复制到 ~/.claude/skills/），或将所有检索降级为 WebSearch/WebFetch。无需密钥即可使用 S2 + arXiv 核心功能；免费的 S2_API_KEY 可让 snippet/cite 可靠运行——执行 <lit> keys --init，让用户自行填写打印出的 keys.env，并且绝不要将密钥粘贴到聊天中。在 loop.run.yaml 中记录层级（仅记录是否存在）。

环境。 撰写者会在用户自己的环境中运行用户的 <plot_command> 以重新生成图表——这些代码可能需要第三方依赖项（matplotlib、pandas 等），因此该技能不会附带任何依赖项，也绝不会安装它们；它会调用用户的命令，并读取重新生成的输出。该技能编写的辅助代码仅使用标准库。同级技能中的 tools/lit_search.py 也仅使用标准库。

确认绑定项后，初始化沙盒（复制原始文件；绝不就地修改）：

<sandbox_root>/
├── loop.run.yaml        ← resolved bindings + <intent> + literature_tiers
├── ledger.tsv           ← header only (see Ledger)
├── literature/.cache/   ← lit_search on-disk cache
└── iter1/
    ├── draft.md         ← COPY of <draft_path>
    ├── figures/         ← COPY of <figures_dir>
    └── code/            ← COPY of <code_paths>   (omit if no code)

循环

<N> 从 1 开始；第 1 次迭代评审并评分未经修改的草稿（即基线版本——此前不进行修订）。每次迭代都要重新评分：分数只能来自对修订后论文进行的全新同行评审，绝不能沿用之前的分数。只做表面修改不会提高分数。

复制此清单并逐项勾选：

• 评审 — 并行启动当前启用的评审员（启动失败则降级处理），每位评审员使用 iter<N>/ 工作副本和数据集；每位评审员都写入 iter<N>/critiques/<reviewer>.json（根据 schemas/finding.schema.json 验证）。没有代码时跳过 code_reviewer。
• 评分 — 启动一位全新的 peer_reviewer（roles/peer_reviewer.md）：先独立评分（先自行阅读，再结合评审意见进行协调；抽查数字和引用；指出遗漏的问题），写入 iter<N>/peer_review.json（根据 schemas/peer_review.schema.json 验证）：每个启用的维度评分为 1-5，overall_score = 100 × Σscore / (5 × n_axes)，硬性门槛 → pass。
• 记录 — 追加一行到 ledger.tsv（见 Ledger）。
• 停止检查 — 满足 peer_review.pass == true、N == <budget> 或 overall_score 连续 <patience> 次迭代持平 → 停止（见 Stops）。
• 修订 — 启动 scientific_writer（roles/scientific_writer.md），并提供评审意见、同行评审结果、<lit>、<plot_command>、<citation_style> 和 <intent>。它会先修复阻断项和门槛问题，再修复代码 → 重新生成图表（在沙箱内运行复制的 <plot_command>）→ 更新正文，使用 <lit> 核实新引用，并写入 iter<N+1>/{draft.md,figures/,code/} + iter<N+1>/revision_notes.md。
• N = N + 1 并重复执行。

评审员的 finding 和 peer_review 格式如下（内容经过删节；完整格式见 schemas/）：

{"reviewer": "code_reviewer", "iteration": 1, "overall": "block",
 "summary": "Block: make_figures.py sorts the two columns independently, fabricating r=0.98 (true r≈0.62).",
 "findings": [{"urgency": "must_fix", "action_type": "replace", "area": "make_figures:broken-pairing",
   "finding": "xs=sorted(study); ys=sorted(score) destroys per-row pairing; r inflated to 0.98 (real ≈0.62).",
   "proposed_action": "Correlate the paired arrays; re-render Fig 1; update r everywhere.",
   "target_artifact": "iter1/code/make_figures.py", "evidence": "code/make_figures.py:~70; paired r=0.62"}]}

{"iteration": 1,
 "axes": {"figures": {"score": 1, "justification": "Fig 1 plots bug-sorted data; numbers != data.", "blocking_issues": ["fig r=0.98 != paired r=0.62"]},
          "scientific": {"score": 1, "justification": "Causal claim from one correlation; r unreproducible."},
          "style": {"score": 2, "justification": "Promotional, AI-flavored prose."},
          "formatting": {"score": 2, "justification": "Mixed APA/MLA; Results before Methods."},
          "code": {"score": 1, "justification": "Independent column sort fabricates r=0.98."}},
 "overall_score": 28.0, "pass": false,
 "gate_failures": ["make_figures.py sort bug makes r=0.98 an artifact (true 0.62)"],
 "issues_judges_missed": ["Methods omits the test used and n."],
 "spotchecks": [{"target": "paired Pearson r", "method": "recomputed from data", "result": "refuted"}],
 "substance_check": "Baseline iteration — nothing revised yet."}

Ledger

<sandbox_root>/ledger.tsv，以制表符分隔，自由文本中不得使用逗号：

iter	overall_score	pass	figures	scientific	style	formatting	code	top_fix	revision_summary
1	28.0	no	1	1	2	2	1	fix make_figures sort bug	baseline (no revision)
2	61.0	no	3	3	3	3	4	report honest r, de-causalize	fixed bug+claims; relabeled fig1
3	88.0	yes	4	5	4	4	5	-	unified APA; trimmed abstract; balanced sleep claim

如果没有代码维度，则在 code 列中使用 -。每次迭代的 critiques/*.json、peer_review.json 和 revision_notes.md 均保存在 iter<N>/ 中。如果因预算用尽或进入平台期而停止，应报告得分最高的迭代，不一定是最后一次迭代。不要将沙箱纳入版本控制。

约束

• 绝不编辑或运行 <sandbox_root> 之外的任何内容——在设置时读取一次原始文件，将其复制进沙箱，然后只处理副本；<plot_command> 也要复制到沙箱中，并从沙箱运行。
• 绝不编造数据、数字、图表或引用——新引用必须来自真实的 <lit> / WebFetch 检索，并逐字引用；遇到 {"error","fallback"} 时，改用 WebSearch/WebFetch。
• 评分标准固定且可复现——peer_reviewer 绝不会放宽标准以让循环结束；一旦确认存在硬性门槛问题，无论平均分如何，论文都不合格。
• 保护 <intent>——写作者要强化同一项研究发现，绝不能更改核心结果，也不能为了规避评审意见而删除真实发现，因为为提高分数而删除结果属于弄虚作假。
• 每次迭代只进行一批连贯的修订，优先处理阻断项和门槛问题，以便明确判断分数变化的原因。
• 不安装任何内容——此技能不附带依赖项；<plot_command> 在用户环境中运行，辅助代码仅使用标准库。绝不打印或提交 API 密钥（keys.env 保持在 gitignore 忽略范围内）。

停止条件

循环在以下任一条件首次满足时停止：

• 通过 — peer_review.pass == true。报告交付物（iter<N>/ 中的产物）、分数和分数变化轨迹。
• 预算用尽 — N == <budget>。报告得分最高的迭代作为交付物。
• 进入平台期 — overall_score 连续 <patience> 次迭代持平。报告最佳迭代，以及尚未解决的 gate_failures / must_fix 阻断项。

结束时务必提供交付物（iter<N>/ 路径）、其 overall_score 和通过/未通过状态、各维度分数、ledger.tsv 中的分数变化轨迹；如果未通过，还要列出论文尚未达到标准的阻断项（gate_failures + 未解决的 must_fix）。