biopathway-mechanism-diagram 是做什麼的?
一張路徑圖是一個讀者會逐一挑戰每個箭頭的機制陳述。此技能的合約:畫布上的每個實體和每條邊都必須追溯到帶有位置的逐字引用;交互語義(活化/抑制/結合/修飾/運輸)在視覺上需有明顯區別且不可混淆;任何來源未陳述的內容(方向、位置、數字)必須明確標記為「未陳述」,而非猜測。交付物包括分層、可透過ID定址的編輯式SVG,加上PNG/PDF匯出,以及一份合約完整的result.json。
使用時機與不適用時機
適用於:機制圖、訊號傳遞路徑圖、受體至細胞核的級聯反應、路徑交互作用、「根據此文繪製圖N」任務,以及對現有路徑圖的編輯(新增/刪除實體或邊、重新標記)。 不適用於:統計圖表(長條圖/箱形圖/火山圖)、實驗示意圖,或純美觀修飾;這些屬於其他技能範疇。
執行合約(平台執行時期)
- 輸入:
/input/case.json(+ task.md)。在/app/work下工作;交付物置於/app/output。 - 整個執行的第一個動作(在深入閱讀案例之前):
python scripts/scaffold_result.py --input /input/case.json --outdir /app/output這會寫入一個 result.json,其中包含每個輸出合約欄位,未產生的欄位為 null + 原因。持續逐步更新它;切勿刪除任何合約欄位。 - 以下所有腳本都採用
--model/--svg類型的路徑參數,且是純 Python 3(僅使用標準函式庫),除非另有說明。references/由腳本讀取;請在步驟 1 之前自行閱讀.md檔案。
步驟 0 - 閱讀合約並建立支架(1 次請求)
執行支架腳本。略讀 task.md + case.json:確認圖形目標(何種機制、若是重製則為何圖、生成或編輯情境)、所需的匯出格式,以及證據範圍。記錄你必須填寫的合約欄位清單。預算意識:目標在 5-8 個模型步驟內完成;腳本負責繁重工作,你負責科學判斷。
步驟 1 - 提取機制模型(科學核心 - 自行完成)
閱讀實際材料(實際解析 PDF;讀取檔案,切勿根據標籤假設內容)。根據你自己的判斷,按照 references/layout-conventions.md 建立 /app/work/model.json:
- 實體 — 基因 / 蛋白質 / 受體 / RNA / 複合體 / 分子 / 細胞 / 家族。應用
references/naming-rules.md:基因符號使用斜體,基因節點與其蛋白質節點有所區別(MYC vs MYC);使用首選符號,並在別名中保留來源拼寫;家族與成員的區分;每個已陳述的複合體一個節點。每個實體攜帶source: {loc, quote}— 一個逐字引用和一個足夠精確以重新找到的位置(章節/段落/頁碼/圖說)。 - 邊 — 類型來自
references/edge-types.json中的封閉集合(活化、抑制、結合、磷酸化、泛素化、轉錄調控、轉位、複合體形成等)。directed必須明確設定。切勿猜測方向:如果引用中沒有方向提示,將directed設為 false,並記錄不確定性(references/uncertainty-policy.md)。結合/招募是無向的。轉錄調控的目標是基因節點,且需要一個正負號。 - 區室 — 細胞外 / 細胞膜 / 細胞質 / 細胞核(+ 內質網、高基氏體、胞器子區域,若機制需要)。位置未陳述的實體應放入
unspecified帶 — 切勿無聲地放入細胞質。受體錨定在細胞膜帶上。 - 順序 — 根據路徑位置設定
order(拓撲順序,非文字順序);反饋迴圈自然以向後邊的形式出現。 - 畫布上的數字(表現量、顯著性)僅在來源中以逐字形式存在時才加入;否則將資料映射明確保留為 null。
實務提取順序:第一次閱讀掌握整體流程;第二次逐句閱讀提取實體與引用;第三次閱讀提取邊,包括抑制劑、反饋與交互作用(它們通常隱藏在「然而/然而」的句子中)。
步驟 2 - 驗證模型(腳本)
python scripts/validate_model.py --model /app/work/model.json \
--report /app/work/validation-report.json
修正每個 E-* 錯誤。E-DIR-01(有向邊缺少方向提示)是核心科學防護機制:要嘛引用一個陳述方向的句子,要嘛降級為無向邊 + 不確定性。警告需要審慎決定:家族節點、受體放置、正負號與引用的不一致。重新執行直到驗證通過。如果材料無法支援某個必要的合約項目,請立即註記(它將在步驟 5 中成為 null + 原因)。
步驟 3 - 渲染 SVG 並匯出(腳本)
python scripts/render_svg.py --model /app/work/model.json \
--out /app/output/pathway.svg --report /app/work/render-report.json
python scripts/export_assets.py --svg /app/output/pathway.svg \
--outdir /app/output --model /app/work/model.json \
--png-width 2400 --report /app/work/export-report.json
閱讀渲染報告的警告(畫布限制、未知區室)。自行檢視 PNG;如果佈局遮蔽了機制(邊交叉隱藏分支、反饋跨越級聯),請調整模型中的 order/固定位置並重新渲染。SVG 是確定性的:相同的模型 → 相同的 SVG。
步驟 4 - 編輯情境(若案例要求編輯現有圖形)
首先重建目標圖形的模型(對原始圖形的來源文字執行步驟 1),然後使用保留來源的編輯——原始模型/SVG 會備份,每次編輯都會記錄在模型的 change_log 中:
python scripts/apply_edit.py --model /app/work/model.json --op add-edge \
--id e-new --src A --tgt B --type inhibition --directed true \
--sign negative --loc "..." --quote "..."
操作:新增/重新命名/移除實體(當有邊連接時,移除操作會拒絕,除非使用 --cascade,且級聯移除會記錄為不確定性)、新增/移除邊、新增區室。每個新增的實體/邊必須提供逐字的 --loc + --quote。編輯後,重新驗證(自動)並重新渲染(步驟 3)。
步驟 5 - 驗證並最終確定 result.json(腳本 + 你)
python scripts/verify_outputs.py --model /app/work/model.json \
--svg /app/output/pathway.svg --result /app/output/result.json \
--exports /app/output/pathway.png /app/output/pathway.pdf \
--report /app/output/verification-report.json
這會重新讀取 SVG,檢查節點/邊的回讀、圖例與使用的一致性(雙向)、標籤溢出、畫布限制、匯出檔案是否存在,以及 result.json 中每個 null 是否都有原因。然後自行最終確定 result.json:填寫合約欄位(editable_source 路徑、匯出檔案與後端/參數、包含引用的 entity_table/edge_table、legend_basis、包含版本的 sources、不確定性、驗證摘要、誠實的狀態)。為任何 null 保留 _unanswered_reasons。部分交付必須以簡明語言說明其限制。
例外處理(真實路徑,非裝飾)
| 失敗情況 | 偵測方式 | 處理行動 |
|---|---|---|
| PDF 無法讀取 / 無文字圖層 | 解析失敗或文字為空 | 對渲染使用 pdf-render-tool / ocr-tool,在 result.json 中標記「文字圖層缺失」 |
| 實體名稱模糊(兩種解讀) | 你的提取 | 根據上下文選擇,記錄替代方案 + 不確定性;若無法決定,則為 null + 原因 |
| 方向未陳述 | E-DIR-01 | 降級為無向邊(無箭頭)+ 不確定性。切勿猜測 |
| 區室未知 | E-CMP-01 / 佈局警告 | unspecified 帶 + 註記 |
| 缺少用於資料編碼視覺元素的數值資料 | 模型中無逐字數字 | 繪製拓撲結構,將映射標記為 null + 「來源中缺少資料」 |
| 標籤溢出 | 驗證 label_overflow | 縮短標籤 / 拆分為 label+sub / 重新排序 |
| 畫布超出限制 | 渲染警告 | 拆分為多個面板或減少分支;註記 |
| 匯出後端缺失 | 匯出報告狀態失敗 | 已嘗試備援鏈;交付 SVG,在 result.json 中記錄失敗 + 指引 |
| 空白/退化的 PNG | blank_check | 調查渲染報告;重新渲染;記錄 |
| 驗證錯誤持續存在 | 退出碼 2 | 修正模型;若材料無法修正,則交付有效子集 + 明確限制 |
品質標準(完成前自我檢查)
- 審閱者能否指向任何箭頭,並從嵌入的表格/模型中獲得其逐字依據?(可追溯性)
- 活化/抑制/結合/修飾在視覺上是否截然不同,且圖例是否與所繪內容一致——無缺失、無幽靈條目?
- 每個未陳述的事項是否都明確標示為未陳述(無向邊、unspecified 帶、null + 原因)?
- 是否有人能打開 SVG,更改一個標籤,然後重新匯出?(分層、可透過ID定址、標準字型堆疊)
- result.json 是否以誠實的狀態涵蓋每個合約欄位?
檔案
scripts/scaffold_result.py- 合約完整的 result.json,含 null+原因scripts/validate_model.py- 架構 + 方向證據 + 命名檢查scripts/render_svg.py- 從 model.json 生成確定性分層 SVGscripts/export_assets.py- PNG/PDF 匯出,帶備援鏈 + 空白檢查scripts/apply_edit.py- 保留來源、記錄的編輯scripts/verify_outputs.py- 對整個套件進行回讀驗證references/edge-types.json- 機器可讀的符號語義references/symbol-semantics.md- 視覺文法及其原理references/naming-rules.md- 基因/蛋白質/家族/複合體命名慣例references/uncertainty-policy.md- 降級規則;不猜測政策references/layout-conventions.md- model.json 架構 + 佈局演算法examples/ras-mapk-case/- 使用真實材料的實際範例(Brown & Ried 2022)README.md- 獨立使用說明文件