QinghongLin/data2story-skill

數據記者智能體 (Data2Story)

將 $ARGUMENTS 轉換為一篇部落格。依序協調以下角色。

設定

在執行任何操作之前先解析路徑：

• 絕不硬編碼機器本機路徑，也絕不要求使用者匯出路徑變數。
• 解析 SKILL_DIR = 包含此 SKILL.md 的目錄 (.../skills/data2story)
• 解析 ARCHIVE_DIR = 包含 skills/ 的上層目錄 (相對於 SKILL_DIR 上兩層，即 SKILL_DIR/../..)
• 解析 DATA2STORY_ROOT = ARCHIVE_DIR 的父目錄
• 下面的命令使用符號佔位符，例如 ARCHIVE_DIR；在執行 Bash 之前，請將其替換為已解析並加上引號的路徑。
• DATA_NAME = 資料集資料夾名稱 (例如 pick_a_card)
• DATA_DIR = 如果 $ARGUMENTS 是現有路徑，則使用該路徑；否則使用 DATA2STORY_ROOT/data/{DATA_NAME}
• TIMESTAMP = 當前時間，格式化為 MMDD_HHMM (例如 0401_1618)：date +%m%d_%H%M (在 bash 中執行)
• PROJECT_DIR = DATA2STORY_ROOT/project/{DATA_NAME}/blog_{MODEL}_{TIMESTAMP}
• 建立 PROJECT_DIR/、PROJECT_DIR/assets/、PROJECT_DIR/code/

歸檔

在建立 PROJECT_DIR 之後立即建立當前技能的快照：

mkdir -p PROJECT_DIR/archival
cp -r ARCHIVE_DIR/skills PROJECT_DIR/archival/skills

這會保留此專案執行時所使用的精確技能版本。

可用工具

所有媒體工具都透過 OpenRouter 路由。在執行任何生成呼叫之前設定 OPENROUTER_API_KEY。

媒體生成是設計師的工作，因此媒體工具（文字轉圖片、文字轉影片、圖片轉影片、文字轉音樂、嵌入）位於 SKILL_DIR/designer/scripts/openrouter-*/ 目錄下。完整列表——預設模型和確切的 python3 ... 調用方式——在 designer/references/tools.json 中；每個工具的完整文件在其各自的 SKILL.md 中，位於 SKILL_DIR/designer/scripts/openrouter-*/ 下。

流程概述

該流程是一個單一的線性序列，從原始資料生成可追溯的 HTML 部落格：

DATA → 偵探 → 分析師 → 編輯 → 設計師 → 程式設計師 → 審計員 → 檢查員 → 最終的 index.html + viewer.html

依序執行每個階段。每個階段在開始之前都先讀取先前的成品。在當前成品完成之前，不得進入下一個階段。

階段 1 — 偵探

輸入：DATA_DIR 輸出：PROJECT_DIR/detective.json 說明：研究外部脈絡——背景知識、領域歷史、相關發現、這份資料為何重要。每個發現都有一個 det_xx ID。

階段 2 — 分析師

輸入：DATA_DIR、PROJECT_DIR/detective.json 輸出：PROJECT_DIR/code/*.py、PROJECT_DIR/analyst.json 說明：在偵探提供的脈絡基礎上，對資料進行詳盡的量化分析。所有程式碼都作為可執行腳本保存到 code/ 中。每個發現都有一個 ana_xx ID，包含 calculation（檔案 + 行號 + 輸出）和 data_table（可直接繪製圖表的資料）。

階段 3 — 編輯

輸入：PROJECT_DIR/detective.json、PROJECT_DIR/analyst.json 輸出：PROJECT_DIR/editor.md、PROJECT_DIR/editor.json 說明：編輯決策——哪些發現是重要的、敘事弧線是什麼、部落格要論證什麼。每個章節都有一個 edt_xx ID，並明確引用 ana_xx 發現和 det_xx 脈絡。不涉及視覺設計。

階段 4 — 設計師

輸入：PROJECT_DIR/editor.md、PROJECT_DIR/editor.json、PROJECT_DIR/analyst.json 輸出：PROJECT_DIR/designer.json、PROJECT_DIR/assets/* 說明：數據驅動的創意視覺決策——如何使用圖表、圖片、影片、音訊、地圖、互動元素、數據摘要、實例或純文字來呈現每個觀點。媒體組合應根據資料集的特性而定，而非固定的檢查清單。頁面預設應具備豐富的多媒體：借鑒共享的 frontend-design 技能的視覺語言，並使用所有五種管道（圖表、圖片、影片、音訊、互動/地圖），除非某個管道記錄的回退方案會是虛構的或純粹裝飾性的。每個視覺元素都有一個 des_xx ID，且當其由數據驅動時，data_source 指向 ana_xx 的 data_tables。生成選定的資產。無需產生 HTML。

階段 5 — 程式設計師

輸入：PROJECT_DIR/editor.md、PROJECT_DIR/editor.json、PROJECT_DIR/analyst.json、PROJECT_DIR/designer.json 輸出：PROJECT_DIR/index.html 說明：以 HTML 實作最終的部落格。套用 designer.json 中記錄的 page_rhythm 主題/強調色，並從 frontend-design 技能借用元件和樣式配方。從 analyst.json 的 data_tables 解析圖表數據（不允許直接存取原始數據）。為每個元素標記 data-edt、data-ana、data-det、data-des 屬性以實現可追溯性。

階段 6 — 審計員

輸入：PROJECT_DIR/index.html 輸出：PROJECT_DIR/index.html (已修改)、PROJECT_DIR/auditor.json 說明：偵測並修復版面問題（重疊、間距、對齊），但不改變內容或設計意圖。在程式設計師之後自動執行，以確保視覺元素正確包裝和間距。

呼叫：Skill auditor PROJECT_DIR

階段 7 — 檢查員

輸入：PROJECT_DIR/index.html、所有 JSON 檔案 輸出：PROJECT_DIR/inspector.json、PROJECT_DIR/viewer.html 說明：執行句子層級的可追溯性驗證，並生成互動式檢視器。包含兩個步驟：

python3 SKILL_DIR/inspector/scripts/verify.py PROJECT_DIR --log-errors
python3 SKILL_DIR/inspector/scripts/generate_viewer.py PROJECT_DIR

步驟 1 產生 inspector.json（句子→證據映射）。步驟 2 產生 viewer.html（自包含，可在 file:// 協定下運行——無需伺服器）。詳情請參閱 inspector/SKILL.md。

可追溯性：ID 在流程中的流動

det_01 ──┐
det_02 ──┤
         ├──▶ ana_01 (based_on: [det_02]) ──┐
         │    ana_02 (based_on: [])          ├──▶ edt_01 (findings: [ana_01, ana_02], context: [det_01]) ──▶ des_01 (section: edt_01, data_source: ana_01)
         │    ana_03 (based_on: [det_01])    │    edt_02 (findings: [ana_03], context: [det_02])         ──▶ des_02 (section: edt_02, data_source: ana_03)
         └────────────────────────────────────┘

最終 HTML 中的每個值都可以追溯：HTML data-des="des_01" → designer.json des_01.data_source="ana_01" → analyst.json ana_01.calculation.code → 可驗證。

交接規則

• 每個成品必須在下一階段開始前完成。
• 如果某個成品缺少必要的章節，請先修正它再繼續。
• 多媒體豐富性門檻（設計師之後、程式設計師之前）： designer.json 應使用所有五種管道（圖表、圖片、影片、音訊、互動/地圖）。對於任何標記為 used:false 的管道，請確認其記錄的回退方案確實被嘗試過，並且在 meta.media_decisions 中記錄了基於數據的理由。如果某個管道是因為方便性而非數據無法支援而被跳過，則在程式設計師執行之前將其退回給設計師。
• 所有生成的資產僅放入 PROJECT_DIR/assets/。
• 最終交付物：PROJECT_DIR/index.html、PROJECT_DIR/detective.json、PROJECT_DIR/analyst.json、PROJECT_DIR/code/*.py、PROJECT_DIR/editor.md、PROJECT_DIR/editor.json、PROJECT_DIR/designer.json、PROJECT_DIR/inspector.json、PROJECT_DIR/viewer.html。