关系示意图:提取 → 建模 → 渲染 → 验证 → 导出
你正在绘制的图形的科学正确性将由一个 LLM 审查者对照源材料进行评判。通用图像生成的主要失败模式正是此技能拒绝执行的内容:抑制绘制为激活、上下游颠倒、包含关系绘制为并列方框、发明的基因名称或数字、无法追溯的主张。此处的每一种机制都是为了确保这些失败无法在未察觉的情况下被交付。
不可协商的原则
- 表格中不存在的内容,绝不绘制。 图形模型(
model.json)是唯一的真实来源;SVG 是根据它生成的,并会对照它进行回读验证。 - 每个实体和关系都必须附带源材料中的逐字引用+定位信息。没有引用依据的关系会被工具拒绝(
relation_no_evidence)。如果你无法引用它,你就不能绘制它。 from/to编码的是陈述内容,而非布局。 “A 抑制 B” ⇒from: A, to: B, type: inhibits。渲染器负责几何布局;验证器负责检查箭头尖端确实落在 B 上。- 未知情况就绘制为未知。 如果材料未说明方向,请使用
direction: "unknown"—— 它会以虚线加?渲染,并在result.json中被标记。切勿为了图形美观而进行猜测。 - 首先交付保底的
result.json,之后再改进。 在步骤 1,在任何抽取之前,会写入一个包含明确空值的契约式框架,这样即使崩溃也能留下一个有效的部分可交付物。
脚本位于 scripts/ 目录下(纯 Python 3 标准库 + 可选的 cairosvg/PIL;自动检测浏览器无头模式以进行导出)。符号语义位于 symbols/symbols.json 中,并记录在 references/symbol-conventions.md 中;模型格式位于 references/model-schema.md 中。在首次运行前,请阅读这两个参考文件。
工作流程(7 步)
在 /app/work 目录下工作;最终产物放在 /app/output 目录下。
步骤 1 — 搭建最低可交付成果的框架
python scripts/init_result.py --case /input/case.json --work /app/work --output /app/output
读取案例,创建目录,写入 /app/output/result.json,其中每个 output_contract 字段都存在且为 null,status: "partial",并包含 partial_reasons 条目。如果案例文件缺失或无法读取,它仍会写入框架并记录问题。同时,你自己也要阅读 task.md 和任何材料文件 —— 切勿仅根据标签或文件名来假设内容。
步骤 2 — 提取实体-关系表格(依靠你的判断,而非脚本)
阅读实际材料(通过平台工具获取的 PDF 文本、表格、案例文本),并根据 references/model-schema.md 构建 /app/work/model.json:
- 每个科学参与者作为一个实体;
label= 源材料中印刷的规范名称;type= 以小副标题形式显示的功能角色; - 每个已陈述的交互作为一个关系,
type来自符号库(activates inhibits binds modifies transports indirect precedes contains parallels),direction为(A_to_B/B_to_A/bidirectional/unknown); - 包含关系(“X 复合体由 A、B、C 组成”)成为一个包含成员的 group,加上
contains关系 —— 绝不使用边,也绝不并列放置; - 时间/过程顺序(“首先……然后……”)变成带有步骤标签的
precedes关系; evidence= 材料的逐字子字符串 + 定位信息(章节、段落、表格行、页码)+ 来源 ID(DOI/文件名)。
针对复杂情况的提取规则:
- 实体歧义(同义词/缩写,如“β-catenin” vs “CTNNB1”):视为一个实体,标签使用源材料中打印的名称,在
result.json的uncertainty中注明等价关系。源材料区分了两个名称,则保留为两个实体。 - 未明确的方向:使用
direction: "unknown"(虚线 +?)。在uncertainty中说明歧义;不要通过“合理性”来解决它。 - 间接证据(对于 X→Y 的主张,材料说“X 通过 Z 导致 Y”):对于 X→Y 的声明,使用类型
indirect(虚线)或者模拟机制链 X→Z→Y(如果每一步都有引用)。优先选择机制链 —— 审查者可以跟踪它。 - 材料中的数字/单位/浓度(例如“3.3–10.4%”):按照打印的确切内容保留在边/节点标签中,绝不四舍五入或发明。
- 如果案例要求的是 实际数据值的图表,这超出了本技能的核心范围(统计图表)—— 仍然交付适用的部分(实体表、数据到图例的映射规范),并将剩余部分标记为部分完成并说明原因。
步骤 3 — 在绘制前进行验证
python scripts/model_check.py /app/work/model.json
退出代码 0 = 干净(允许警告)。修复每个错误 —— 无论如何,渲染器在有错误时会拒绝渲染。警告(entity_no_evidence,direction_uncertain,cycle_in_rank_graph,……)是合理的科学状态:保留它们并将它们带入 result.json,而不是通过“发明”来“修复”它们。
步骤 4 — 渲染可编辑的 SVG
python scripts/make_schematic.py /app/work/model.json -o /app/work/figure.svg --report /app/work/layout.json
生成分层的 SVG:node-* / edge-* / group-* / legend 组,每个组都带有 data-evidence-quote/-locator/-source 属性。布局是自动化的(最长路径分层,因此 A_to_B 边向下指向);如果内容超过 canvas_width,画布会加宽并记录 canvas_expanded 警告 —— 任何内容都不会被裁剪。
步骤 5 — 回读图形并进行验证
python scripts/verify_svg.py /app/work/model.json /app/work/figure.svg --out /app/work/verify.json
这是核心的抗失败门禁。它检查实体/关系覆盖率、根据符号库检查标记语义、几何箭头方向(尖端必须比源节点更接近语义目标节点)、包含框是否实际包含成员(且不困住非成员)、节点重叠、标签适配度和图例覆盖率。退出代码 0 = 通过。
如果验证失败:修复 模型或编辑,重新渲染,重新验证。切勿手动修补 SVG 以使检查静默。两次迭代是正常的;如果由于材料矛盾而无法通过检查,则保留引用所支持的图形,并在 result.json 的 uncertainty 中记录冲突。
步骤 6 — 导出和合规性检查
python scripts/export_svg.py /app/work/figure.svg -o /app/output --pdf
将 <name>_300dpi.png 和 <name>.pdf 写入 /app/output,按顺序尝试后端(cairosvg → Edge 无头浏览器 → Chrome 无头浏览器 → 内置 PIL 栅格化器用于 PNG)并记录每次后端失败。报告包含每个产物的检查项(分辨率、白色背景、PDF 头部/页面宽高比、矢量内容流)。将 figure.svg 和 model.json 复制到 /app/output 作为可编辑源文件,PNG 则作为渲染预览。
步骤 7 — 最终确定 result.json(如实填写契约覆盖范围)
填写每个 output_contract 字段 —— 无法填写的字段保留为 null,并在 partial_reasons 中说明原因。典型的映射(根据案例的契约调整名称):
editable_source→{svg, model, note: "分层 SVG; 每个元素都携带 data-evidence-*"}exported_artifacts→ 导出报告的产物(路径、格式、DPI、后端、检查项结果)rendered_preview→ PNG 路径entity_relation_table→ 实体和关系,包括引用/定位信息(或指向 model.json 的路径及其计数)verification_report→ verify.json 摘要(通过/失败计数、警告)sources→ 使用的源文档/DOI,附带引用出处status→ 仅当验证通过且所有导出正常时才为complete;否则为partial并说明原因。uncertainty列出歧义项(实体识别、未知方向、未解决的冲突)。
编辑现有的 SVG(保留源文件)
当案例提供要修改的 SVG 而不是要绘制的材料时:
- 读取 SVG;定位
node-*/edge-*组及其data-*属性(此技能生成的图形完全是自描述的)。 - 局部更改(重新标记、重新着色、边类型/标签、标题、删除一个未连接的元素)→ 编写一个编辑 JSON 并运行
python scripts/edit_svg.py figure.svg edits.json -o figure_edited.svg。每个操作都需要一个reason;报告会证明未触及的元素是逐字节相同的(preserved.ok)。然后重新导出(步骤 6)。 - 结构性更改(添加/删除实体或关系、反转方向)→ 这些会被
edit_svg刻意拒绝(反转属性而不重新布线会导致画出错误的箭头)。从 SVG 的数据属性重建/扩展 model.json,编辑模型,重新渲染,重新验证。 - 如果现有的 SVG 来自其他工具(没有 data 属性),则从源材料重建模型并重新渲染 —— 不要手动修改外来的 SVG;在
result.json的change_log中记录你所做的事情。
故障应对手册(真实路径,非伪代码)
| 情况 | 检测时机 | 行动 | result.json |
|---|---|---|---|
| 案例/材料不可读 | 步骤 1 或你自己的读取过程 | 写入框架,partial_reasons 指明文件/问题 | status partial,字段为 null |
| 无法引用某个关系 | model_check 错误 relation_no_evidence | 删除该关系或找到引用;绝不绘制未引用的关系 | 图中不存在(正确) |
| 未明确的方向 | 你的提取过程 | direction: "unknown" | 虚线 + ?;uncertainty 条目 |
| 同义词/缩写实体 | 你的提取过程 | 单个实体,注明等价关系 | uncertainty 条目 |
| 矛盾的材料 | 两个引用冲突 | 绘制更强/更具体引用所支持的内容 | 两个引用 + uncertainty 中的冲突 |
| 标签溢出其框 | verify 的 text_fit 警告 | 缩短标签或添加 \n,重新渲染;框的增长是一个重新渲染决策 | 携带警告 |
| 画布太小 | canvas_expanded 警告 | 已自动加宽;或提高 canvas_width | 携带警告 |
| cairosvg DLL 缺失(Windows) | 导出的后端尝试被记录 | 自动回退到浏览器无头模式,然后是 PIL 栅格化器 | 记录后端 + 尝试次数 |
| 无浏览器,无 cairosvg | 所有后端失败 | PIL 栅格化器(框/线/文本;标记被近似处理)+ notes | PNG 质量导致 status partial,PDF 为 null 并说明原因 |
| PDF 宽高比错误 | 导出检查 | 通过 @page 大小设置修复;如果后端忽略,记录为 checks_fail | status partial |
| 验证无法通过 | verify_svg 退出码 1 | 模型级别修复循环;如果不可能,则交付引用支持的部分 | verification_report 如实显示失败项 |
完成前的自我检查
verify_svg退出码 0(或如实报告失败项);/app/output包含:result.json(所有契约键都存在,null 有解释)、figure.svg、model.json、PNG(300 dpi)、PDF;- 每个绘制的关系都是可引用的 —— 抽查三个随机的
data-evidence-quote值,对照材料进行验证; - SVG 中出现的任何实体/数字都不在 model.json 之外;
- change_log 说明了你所做的事情的来龙去脉,包括本技能的步骤。