scientific-figure

科学绘图循环

产物是一张科学图表（渲染后的图像 + 用于生成它的 plot.py）。每次迭代都会生成 → 评审并评分：生成器编写渲染脚本并渲染图表，以实现冻结的 <goals> 消息；对抗式评审者依据固定的 rubrics/rubric.md 按 0–100 分进行评分，并决定是否 pass；随后，生成器根据评审者的具体 findings 进行修改。循环会持续运行，直到分数达到 <pass_threshold> 或预算耗尽。所有工作都在沙盒中的副本上进行；用户的数据以只读方式复制，绝不修改。

角色（均位于此文件夹中）：

• roles/generator.md — 起草／修改 plot.py，通过运行 <render_cmd> 渲染 figure.png，可选通过 <lit> 为领域内容提供依据；写入 generation_notes.md。
• roles/critic.md — 对抗式评分者：独立重新推导每个评分维度，对照数据抽查图表中的数值，可选检查领域内容的文献完整性，并输出 schemas/critique.schema.json（包含评分、pass 和可执行的发现）。
• rubrics/rubric.md — 固定的评分标准（评审者绝不修改）。
• schemas/critique.schema.json — 唯一经过验证的输出。

启动子 Agent，或降级执行。 在 Claude Code 中，依次将 generator 和 critic 作为真正的 Agent 子 Agent 启动（必须按顺序，因为评审者需要生成器的图表）；否则，在当前上下文中分别扮演这两个角色。你是编排者。

为什么让评审者自行评分（诚信问题）

评审者既负责评审也负责评分，这在循环终止压力下容易导致评分膨胀，以及生成器设法钻评分标准的空子。roles/critic.md + rubrics/rubric.md 通过以下方式应对这一问题：评审者 (1) 应用自己绝不修改的固定评分标准；(2) 根据渲染后的图表、数据和冻结的 <goals> 重新推导每个维度，而不是复述生成器的说法；(3) 自行重新计算图表中的部分数值，而不是轻信“已经修好”；(4) 坚持固定且有锚点的标准，不因努力或迭代次数给予加分；(5) 应用硬性门槛（图表数值与数据矛盾、坐标轴具有误导性，或将伪造数据呈现为真实数据，都会导致图表不合格，无论平均分如何）。生成器针对具体的 findings 进行优化；评审者则依据冻结的目标进行整体评分——因此，“解决每一项发现”并不会机械地换来通过。由于两者是独立的 Agent，评审者绝不会只是照单全收生成器的意图。

适用场景

当存在科学数据（或描述这些数据的提示词），且用户希望通过对抗式评审和评分标准，将图表打磨至达到质量门槛时使用。默认情况下，运行下方完整的生成→评审循环。退出选项：如果用户只想要一张图表和一份评审意见（不进行迭代），则执行一次生成和评审，然后停止。不用于撰写论文或进行分析，也不用于润色已经定稿的图像。

设置

交互式解析绑定项。 如果工作目录中存在 loop.run.yaml，则加载它，用一行确认其中的值，然后直接进入循环。否则：在 Claude Code 中（AskUserQuestion 工具可用），推断每个绑定项的可能值，并将其作为推荐选项提供；在其他宿主中，则分别以纯文本引用形式询问。然后写入 loop.run.yaml（格式：examples/run.example.yaml），并在创建任何其他文件前确认每个值，包括提炼出的 <goals>、是否适用期刊规范，以及文献层级是实时还是降级。

绑定项	含义	默认值	推断方式
<brief>	描述要创建的图的提示词 + 必须传达的信息/主张（如果有数据，还要说明数据代表什么）	—	用户的请求；如果以粘贴的文字形式提供，请保存到 <sandbox_root>/brief.md
<data_paths>	图表可视化的数据文件（CSV/TSV/parquet/JSON…）；为空 → 示意图/概念图（此时完整性轴检查的是内部一致性，而非数据保真度）	—	扫描请求附近的工作目录；也可能为 null
<goals>	图表的传播目标，1-3 条要点——冻结；评审器按这些目标评分，生成器绝不能放弃这些目标	—	在设置阶段从 <brief> 中提炼，用一行与用户确认
<render_cmd>	运行生成器所写绘图脚本的命令/解释器（生成器会将 iter<N>/plot.py 附加到命令后），在用户的环境中运行——此技能不附带绘图依赖，与 scientific-writer 的 <plot_command> 使用相同约定	python3	pyproject.toml/.venv/README；例如 uv run python 或虚拟环境中的 python
<style>	可选的审美/风格指南或指定的目标期刊/会议——指定期刊时，会在设置阶段获取其图表规范（见下文），且两个角色都会遵循并据此评分	—	询问用户；检查 <brief> 中是否提到了会议
<pass_threshold>	评审器必须达到的 overall_score（0-100）才能停止，且不得触发任何硬性门槛	85	精致、达到发表水准的图表，无需追求完美
<budget>	最大迭代次数	6	—
<patience>	连续多少次迭代没有改进后停止	2	—
<sandbox_root>	绘图脚本、图表、评审意见和记录文件的存放位置	./sandbox	—

领域轴不是绑定项——评审器会自动检测图表是否提出外部领域主张（具名通路、基因集、经典基准、分类体系、机制或文献确立的数值），并自行启用领域轴；用户无需切换。

文献工具链（可选，仅限 S2 + arXiv）。 领域信息核验通过同级的 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 以复用缓存。仅使用无需密钥的 S2 + arXiv 核心功能（<lit> search 默认使用 --source s2、snippet、cite、fulltext）；不要使用 --source openalex|both、ask 或 bgpt。在设置阶段确认 <lit> --help 可正常运行；如果技能不存在，则将所有检索降级为 WebSearch/WebFetch。仅在 loop.run.yaml 中记录层级（只记录是否存在）。

复用已检索的内容——不要每次迭代都重新查询。 每次检索都会缓存在 --cache-dir <sandbox_root>/literature/.cache 下，每个角色都会将已确认的事实（主张 → 数值/要素 → 来源）追加到 <sandbox_root>/literature/sources.md。两个角色都应先查阅该记录和缓存，仅获取尚未掌握的论文/摘要；先前迭代已核实的数值，应重新阅读其记录的来源进行复核，而不是从头检索。文献步骤的目的是确保正确性，而非增加调用次数——论文一旦获取，就基于它开展工作。

期刊样式表（独立路径，通过网页搜索获取）。 当 <style> 指定期刊/会议时，在设置阶段通过 WebSearch/WebFetch 获取一次其图表指南 → <sandbox_root>/style/journal_spec.md （列宽，单位为 mm；最小字号；字体；线宽；色彩模式；分面标签规范；文件要求）。两个角色都读取这份单一缓存规范——生成器按规范制作，评审器据此评估审美/清晰度轴——确保双方的评分依据一致。此路径独立于 <lit>：网页搜索用于查找期刊的样式规范；<lit>（S2/arXiv）用于核查领域内容。 环境。 生成器通过在用户自己的环境中运行 <render_cmd> 来渲染图形——该代码需要第三方依赖项（matplotlib、pandas 等），因此此技能不附带任何依赖项，也绝不会安装它们；它会调用 <render_cmd>，并读取渲染后的 figure.png。渲染为 PNG 是为了让评审器能够查看图像（SVG 会被当作 XML 读取）。交付内容为 figure.png 及其 plot.py——用户可用该可复现源文件重新渲染为任意矢量格式。此技能编写的任何辅助代码都仅使用标准库。

确认绑定后，初始化沙盒一次（以只读方式复制数据；绝不编辑原始文件）：

<sandbox_root>/
├── loop.run.yaml        ← resolved bindings + <goals> + literature_tiers
├── brief.md             ← <brief> (if pasted as prose)
├── ledger.tsv           ← header only (see Ledger)
├── data/                ← read-only COPY of <data_paths>   (omit if no data)
├── style/journal_spec.md ← fetched journal figure spec     (omit if no journal named)
├── literature/.cache/   ← lit_search on-disk cache
└── iter1/               ← created by the generator
    ├── plot.py
    ├── figure.png
    ├── generation_notes.md
    └── critique.json

循环

<N> 从 1 开始。不同于评估现有基线的循环，每次迭代都先运行生成器（没有可供评审的输入图形）——第 1 次迭代从头起草，第 2 次及之后进行修订。每次迭代都重新评分：分数仅来自对当前图形的新一次评审，绝不沿用之前的分数。仅修改表面内容不会改变分数。

复制此清单并逐项勾选：

• 生成 — 启动 generator（roles/generator.md），并提供 <brief>、<data_paths>、<goals>、<style>（以及 style/journal_spec.md）、<render_cmd>、<lit>，第 2 次及之后还要提供 iter<N-1>/critique.json。 它会编写/编辑 iter<N>/plot.py，在沙盒内运行 <render_cmd> iter<N>/plot.py 以渲染 iter<N>/figure.png，通过 <lit> 核实任何领域内容，并编写 iter<N>/generation_notes.md。
• 评审并评分 — 启动一个全新的 critic（roles/critic.md），评审 iter<N>/figure.png、数据和 <goals>，并应用 rubrics/rubric.md：独立重新推导每个维度的 1–5 分，对照数据抽查图形中的数值，可选地检查领域完整性，计算 overall_score = 100 × Σscore / (5 × n_axes)，应用硬性门槛 → pass，并写入 iter<N>/critique.json（根据 schemas/critique.schema.json 验证）。
• 记录 — 在 ledger.tsv 中追加一行（见 Ledger）。
• 停止检查 — critique.pass == true，或 N == <budget>，或 overall_score 连续 <patience> 次迭代持平 → 停止（见 Stops）。
• N = N + 1 并重复（返回 Generate，此时会根据评审意见进行修订）。

critique 的示例如下（节选；完整结构见 schemas/critique.schema.json）：

{"iteration": 2, "summary": "Needs revision: honest now, but the MAPK panel omits ERK and the y-axis lacks units.",
 "axes": {"message": {"score": 4, "justification": "Up-regulation reads clearly."},
          "aesthetic": {"score": 3, "justification": "Palette not colorblind-safe (red/green)."},
          "clarity": {"score": 4, "justification": "Y-axis missing units."},
          "integrity": {"score": 4, "justification": "Bar heights match data/levels.csv."},
          "domain": {"score": 3, "justification": "MAPK cascade missing ERK node."}},
 "overall_score": 72.0, "pass": false, "gate_failures": [],
 "spotchecks": [{"target": "group-B bar = 2.4", "method": "recomputed from data/levels.csv", "result": "confirmed"}],
 "findings": [{"urgency": "must_fix", "action_type": "add", "area": "domain:incomplete",
   "finding": "MAPK cascade panel omits ERK1/2 downstream of MEK.", "proposed_action": "Add ERK node + MEK→ERK edge.",
   "target_artifact": "iter2/plot.py", "evidence": "lit snippet: canonical MAPK = RAF→MEK→ERK"}]}

Ledger

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

iter	overall_score	pass	message	aesthetic	clarity	integrity	domain	top_fix	generation_summary
1	52.0	no	3	2	2	4	-	label axes + fix palette	baseline draft
2	74.0	no	4	3	4	4	3	add missing MAPK nodes (lit)	relabeled; colorblind palette; +ERK/MEK
3	88.0	yes	5	4	5	5	4	-	rebalanced panels; legend off-data

当领域维度不启用（n_axes=4）时，在 domain 列使用 -。每次迭代的 critique.json 和 generation_notes.md 都位于 iter<N>/ 中。因预算用尽或分数持平而停止时，报告得分最高的迭代，不一定是最后一次。不要将沙盒纳入版本控制。

约束

• 绝不编辑或运行 <sandbox_root> 之外的任何内容——数据在设置时以只读方式复制；生成器的 plot.py 和 <render_cmd> 均在沙盒中运行；不得通过 ../ 路径越界。
• 绝不伪造数据、数值或领域要素。作为真实数据呈现的图形必须由 <data_paths> 渲染；没有数据时，图形必须清楚地呈现为示意图，而非伪造的数据图。通过 <lit> 添加的领域内容（基因、节点、基线、报告数值）必须来自该次迭代中的真实检索，绝不可凭空编造。
• 评分标准固定且可复现——评审器绝不会放宽评分标准中的锚点来让循环结束；无论平均分如何，只要确认触发硬性门槛，图形就不合格。
• 保护 <goals>——生成器要让相同的信息传达得更美观、更清晰；绝不会为了追求更高分而删去或扭曲预期信息。
• 每次迭代进行一组连贯的修订，优先处理阻断项/门槛，以便明确归因分数变化。
• 不安装依赖——此技能不附带绘图依赖项；<render_cmd> 在用户的环境中运行，辅助代码仅使用标准库；文献仅限无需密钥的 S2 和 arXiv 核心来源。绝不打印或提交 API 密钥（keys.env 始终保留在 gitignore 中）。

停止条件

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

• Pass — critique.pass == true。报告交付物（iter<N>/figure.png + plot.py）、分数和迭代轨迹。
• Budget — N == <budget>。报告得分最高的迭代作为交付物。
• Plateau — overall_score 连续 <patience> 次迭代持平。报告得分最高的迭代，以及当前的 gate_failures/must_fix 阻碍项。

始终以交付物（iter<N>/ 路径）、其 overall_score 和通过/未通过状态、各轴分数、ledger.tsv 中的分数轨迹结束；如果未通过，还要列出当前图表与达标之间的阻碍项（gate_failures + 未解决的 must_fix）。