圖形化摘要建構器 是做什麼的?
將研究資料(PDF、筆記、記錄)轉換為一頁圖形化摘要,其每個元素皆可追溯到材料,加上一份 contract-complete 的 result.json。
分工模式 — 你負責科學,腳本負責繪圖:
- 你(代理):閱讀實際材料、提取實體/關係/數據、選擇視覺編碼、決定畫布上與圖說中的內容、根據材料驗證圖表。
- 腳本(
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 — 讀取案例並建立 scaffold 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 並附上待處理原因。從此刻起,即使崩潰仍會留下 contract-complete 的交付物。稍後重新執行 --stage final(步驟 6)以填入內容。
步驟 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
將 /app/work/figure_model.json 按照 references/model_schema.md 中的模式編寫(完整範例:examples/transformer-1706.03762/)。您需做出的關鍵決策:
- 面板規劃:通常 4–6 個面板,按閱讀順序 問題 → 方法 → 結果 (1–2) → 結論;每個面板一個發現。
- 每個面板的佈局:
flow(用於實體/關係的方框+箭頭)、chart(用於資料的 bar/hbar/grouped_bar/line)、stats(用於 2–4 個頭條數值的大數字圖標)、text(條列式結論)。 - 視覺通道:長度用於具有共同單位和零基線的量值;位置用於時間序列;顏色僅用於類別序列(內建 Okabe–Ito 調色板;絕不使用純紅對比純綠);形狀/強調用於焦點實體。每個通道一個含義,每個含義一個通道。
- 畫布:預設 1800×1000 px(約 A4 橫向,150 dpi)。所有字型 ≥ 12 px(檢查器會強制執行)。
- 將工作表內的引用和定位器複製到每個元素的
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
使用您的合約欄位值(scientific_summary、uncertainty、路徑列表、export_checks…)編寫 /app/work/values.json。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)。