關係圖繪製: 提取 → 建模 → 繪製 → 驗證 → 匯出
您正在繪製的圖形,其科學正確性會由一個 LLM 審查員根據來源材料進行評判。一般圖形生成的主要失敗模式,正是這個技能刻意避免的情況:把抑制繪製成激活、上下游方向顛倒、包含關係繪製成並排方框、發明基因名稱或數字、無法追蹤的主張。這裡的每一個機制都是為了讓這些失敗無法在無聲無息中出貨。
不可妥協的原則
- 所有繪製的內容都必須在關係表中。 圖形模型(
model.json)是唯一的事實來源;SVG 從它生成,並根據它回讀驗證。 - 每個實體和關係都附帶來自來源材料的逐字引用 + 定位資訊。 沒有引用的關係會被工具拒絕(
relation_no_evidence)。如果您無法引用,就不能繪製它。 from/to編碼的是陳述本身,而非佈局。 「A 抑制 B」⇒from: A, to: B, type: inhibits。繪製器決定幾何形狀;驗證器檢查箭頭尖端是否確實落在 B 上。- 未知就繪製為未知。 如果材料沒有說明方向,請使用
direction: "unknown"——它會以虛線加?渲染,並在 result.json 中被標記。永遠不要為了讓圖形看起來更乾淨而猜測。 - 先交付最低限度的 result.json,之後再改進。 第一步在進行任何提取之前,先寫出一個帶有明確 Null 值的合約形狀支架,這樣即使崩潰仍能留下一個有效的部分交付成果。
腳本位於 scripts/(純 Python 3 標準庫 + 可選的 cairosvg/PIL;自動偵測瀏覽器 headless 模式用於匯出)。符號語義位於 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 組成」)變成一個群組,包含其成員,加上
contains關係——永遠不是一條邊,也永遠不是並列; - 時間/過程順序(「首先……然後……」)變成帶有步驟標籤的
precedes; evidence= 材料的逐字子字串 + 定位資訊(章節、段落、表格列、頁碼)+ 來源 ID(DOI/檔名)。
困難情況的提取規則:
- 實體歧義(同義詞/縮寫,「β-catenin」vs「CTNNB1」):一個實體,標籤使用來源列印的名稱,在 result.json 的
uncertainty中註明等效性。來源區分的兩個名稱則保持為兩個實體。 - 方向未說明:
direction: "unknown"(虛線 +?)。在uncertainty中說明歧義;不要透過可能性來解決它。 - 間接證據(「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 headless → Chrome headless → 內建 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-*屬性(來自此技能的圖形是完全自描述的)。 - 局部變更(重新標籤、重新著色、邊類型/標籤、標題、刪除未連接的元素)→ 寫入一個 edits JSON 並執行
python scripts/edit_svg.py figure.svg edits.json -o figure_edited.svg。 每個操作都需要一個reason;報告證明未觸及的元素是逐位元組相同的(preserved.ok)。然後重新匯出(第 6 步)。 - 結構性變更(新增/移除實體或關係、翻轉方向)→ 這些會由 edit_svg 按設計拒絕(翻轉的屬性若未重新佈線會畫出欺騙的箭頭)。從 SVG 的 data 屬性重建/擴展 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) | 匯出後端嘗試被記錄 | 自動回退到瀏覽器 headless,然後是 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 說明了您所做的一切,包括此技能的步驟。