图形化摘要构建器 是做什么的?
将研究材料(PDF、笔记、记录)转化为单页图形化摘要,其每个元素都可追溯至材料,并附带一份合约完整的 result.json。
分工——您负责科学,脚本负责绘图:
- 您(智能体):阅读实际材料,提取实体/关系/数据,选择视觉编码,决定画布 vs. 图注的内容,对照材料验证图形。
- 脚本(
scripts/,纯 Python + matplotlib):布局、渲染、检查、结果组装。确定性:相同模型输入 → 相同图形输出。
环境与路径
- 技能根目录:
/skills/weekly-skill(脚本在scripts/下,模式文档在references/下)。工作目录为/app/work;最终交付件存放在/app/output。 - 输入:
/input/case.json(+ task.md;材料文件由 case 引用)。 - 需要 Python 环境并安装 matplotlib;如果缺失,PNG 导出会自动回退到 Pillow,PDF 导出会报错并提供解决方法——参见操作手册。
- 典型成本:10–20 次模型请求,远在 64 次请求 / 900 秒预算内。每次构建/验证脚本运行视为一次工具调用。
工作流
步骤 0 — 读取案例并初始化 result.json(请先执行此步骤)
完整读取 /input/case.json。注意 case_id 和 output_contract 中的每个字段——这些是您的交付义务。然后立即执行:
python scripts/make_result.py --stage init \
--case /input/case.json --out /app/output/result.json
此操作将每个合约字段写入显式 null 并附带未完成原因。从现在起,即使崩溃,也会留下一份合约完整的交付件。在步骤 6 中重新运行 --stage final 以填充它。
步骤 1 — 阅读实际材料
打开案例指向的真实文件(绝不要从标签推测内容)。对于 PDF,使用 pdf-text-tool / scientific-python;仅在需要 OCR 时才扫描页面。保存 sources.json,将每个材料文件映射到其提取的文本——后续步骤会自动验证引文是否与之匹配:
{ "materials/paper.pdf": "<完整提取的文本>" }
步骤 2 — 提取科学内容(由您判断,而非脚本)
直接从材料填写工作表(模板:templates/agent_worksheet.md):
- 问题——材料提出了什么问题?逐字引用。
- 实体——必须出现的对象(分子、细胞、设备、方法、队列...)。每个实体包括:标签、一条逐字引用、定位信息(文件 + 页/节/句)。
- 关系——材料陈述的有向连接(A 激活 B,剂量引发问题...)。记录方向及其来源语句。
- 数据——您可能绘制的每个数字:数值、单位、条件及其来源语句。如果您想要的数字不在材料中,请勿绘制它;改列在
uncertainty/limits中。 - 结论——材料本身提出的主张。
证据规则:引用是材料的逐字子字符串;定位信息精确到人类能在几秒钟内找到;任何无法追溯来源的内容都放入图注/备注,切勿作为数据出现在画布上。
步骤 3 — 编写 figure_model.json
按照 references/model_schema.md(完整工作示例:examples/transformer-1706.03762/)编写 /app/work/figure_model.json。您需做出关键决策:
- 面板规划:通常 4–6 个面板,按阅读顺序 问题 → 方法 → 结果(1–2 个) → 结论;每个面板一个发现。
- 每面板布局:
flow(实体/关系的框+箭头)、chart(柱状/水平柱状/分组柱状/折线图用于数据)、stats(2–4 个重点数值的大号数字标注)、text(要点式结论)。 - 视觉通道:长度用于具有共同单位和零基线的量值;位置用于时间序列;颜色仅用于分类系列(内置冈本-伊藤色板;绝不要使用纯红-绿对比);形状/强调用于焦点实体。每个通道一个含义,每个含义一个通道。
- 画布:默认 1800×1000 像素(≈ A4 横向 150 dpi)。保持每个字体 ≥ 12 像素(检查器会强制执行)。
- 将工作表中的引用/定位信息复制到每个元素的
source。
步骤 4 — 构建与迭代
python scripts/build_figure.py --model /app/work/figure_model.json \
--outdir /app/work/out --sources /app/work/sources.json
生成 graphical_abstract.svg(可编辑的事实来源:命名 ID、layer-* 组、每个元素上的来源 <desc>)、.png(300 dpi)、.pdf、element_map.json、export_report.json。退出码 2 = 模型无效(修复 JSON),3 = SVG 失败(按操作手册修复)。PNG/PDF 的渲染失败不会中止运行——它们会记录在 export_report.json.failures 中。
迭代:如果报告显示错误,请编辑模型(而非 SVG)并重新构建。在清除所有错误代码之前,图形是不正确的。
步骤 5 — 像评审者一样验证
python scripts/check_figure.py --outdir /app/work/out --sources /app/work/sources.json
此操作会重新运行所有检查:SVG 格式正确性、字体下限、画布边界、元素映射完整性、引文与材料比对(捕获虚构数字和错误引用)、灰度/对比度、导出完整性。然后亲自查看 PNG(阅读渲染预览)并检查:阅读顺序是否清晰?实体/箭头方向是否与材料一致?图例是否与编码匹配?每个坐标轴是否有单位?如果某个警告无法消除,请记录它——不要隐藏它。
步骤 6 — 组装最终 result.json
编写 /app/work/values.json,包含您的合约字段值(scientific_summary、uncertainty、路径列表、export_checks...)。element_source_map 和 export_checks 由构建过程自动填写。然后:
python scripts/make_result.py --stage final \
--case /input/case.json --out /app/output/result.json \
--values /app/work/values.json \
--map /app/work/out/element_map.json \
--export /app/work/out/export_report.json \
--issues /app/work/out/issues.json \
--status complete --uncertainty "<一句诚实的说明>"
匹配器按精确键名、然后按包含关系、最后按描述关键字填充合约字段;不匹配的字段保留显式 null 并附带原因。如果仍然存在错误级别的问题,状态将自动降级为 partial——切勿在检查失败的情况下声称 complete。将交付件复制到 /app/output:
graphical_abstract.svg + figure_model.json(可编辑源文件),
graphical_abstract.png(预览)+ graphical_abstract.pdf(导出),
result.json。
步骤 7 — 最终自查
- result.json:
case_id存在;每个合约字段已填充或为显式null并附带原因;状态诚实(尊重自动降级)。 - SVG 可打开(格式良好的 XML),文本是真正的
<text>(可编辑),每个元素都有 id,图层已命名。 - PNG 和 PDF 存在且非空;PNG ≥ 300 dpi。
- 画布上的每个数字都出现在
element_map.json中的一条引用内。 - 图例与颜色/系列编码完全匹配。
-
uncertainty/limits提及每个降级或无法追溯来源的项目。
出问题时
所有故障模式、其特征和解决方法(材料缺少关键数字、实体歧义、文本溢出、字体替换、画布溢出、导出失败、缺少 matplotlib...)均记录在 references/exception_playbook.md 中——遇到任何红色输出时请查阅。唯一至上的规则是:诚实记录,绝不捏造。 一份带有记录限制的 partial 结果,其评分高于一张带有虚构证据的精美图形。
参考资料
references/model_schema.md— figure_model.json 逐字段说明,含默认值和约束。references/exception_playbook.md— 失败特征 → 解决方法。references/design_notes.md— 视觉编码规则、色盲安全性、构建器使用的布局约定。templates/agent_worksheet.md— 步骤 2 提取工作表。templates/figure_model.template.json— 最小起始模型。examples/transformer-1706.03762/— 真实论文工作示例(arXiv:1706.03762,逐字引用 + sha256)。