chart

Chart — 基於專案的互動式圖表工具

使用 Apache ECharts 產生互動式圖表頁面。每個圖表都存放在 output/chart-html/ 下的專屬專案資料夾中，方便重複使用與迭代。

使用時機

只要使用者想要視覺化圖表：價格圖、比較圖、儀表板、商業分析等。

架構

• ECharts（CDN）負責渲染
• ECharts 原生匯出 (getDataURL) + canvas 合併以穩定輸出 PNG
• 基於專案儲存：每個圖表專案一個資料夾
• 無畫廊模式：所有成品都留在專案資料夾中

專案結構（必要）

每個圖表專案應遵循以下結構：

output/chart-html/
  <專案名稱>/
    index.html        # 圖表頁面
    generate.py       # 產生腳本（可重現）
    README.md         # 標題 / 描述 / 資料來源備註
    data.json         # 資料快照
    screenshot.png    # 儲存的圖片

資料夾名稱範例：btc-90d-20260401

工作流程

步驟 1：選擇範本或自訂版面

可用範本：

範本	最佳用途
line.html	時間序列趨勢、多序列比較
bar.html	類別比較、排名
pie.html	組成 / 佔比分析
candlestick.html	OHLCV 價格圖
scatter.html	相關性、分佈
dashboard.html	KPI 卡片 + 2×2 多圖網格
radar.html	多維度評分
heatmap.html	矩陣 / 日曆熱力圖
dual-axis.html	兩個尺度差異很大的序列（例如市值 vs 穩定幣供給量）— 左右 Y 軸，各有其標籤顏色
multi-panel.html	共享 X 軸的堆疊面板（例如價格 + 成交量 + RSI）— 單一 ECharts 實例，所有面板同步 tooltip/縮放
waterfall.html	增量貢獻分解（例如損益歸因、預算差異）— 正負長條堆疊在浮動基準上

步驟 2：建立專案資料夾

使用 scripts/build_chart.py 中的 create_project(name, description, data_sources)。

步驟 3：建立並儲存圖表頁面

使用以下任一方式：

• build_chart(template_name, ...)
• build_chart_custom(...)

然後儲存為專案資料夾中的 index.html：

• save_chart(html, project_dir=project_dir)

步驟 4：儲存可重現的資源

同時儲存：

• save_generate_script(script_content, project_dir) → generate.py
• save_data(data, project_dir) → data.json
• 專案 README 由 create_project(...) 建立

步驟 5：提供預覽

使用專案根目錄服務（建議）：

preview_serve(
  title="Chart Preview",
  dir="skills/chart/scripts",
  command="python3 chart_server.py /data/workspace/output/chart-html 7860",
  port=7860
)

然後開啟：/preview/<id>/<project-name>/index.html

v3.0.1 的重要行為：

• chart_server.py 現在會將預覽前綴的靜態路徑內部重寫（/preview/<id>/... → /...），再進行檔案系統查詢。
• 這確保預覽 iframe 解析到真正的專案 index.html，而不是回退到根目錄列表。
• 請將專案頁面放在 output/chart-html/<project>/index.html（不要直接將 output/chart-html 作為靜態預覽提供，而不使用 chart_server.py）。

步驟 6：匯出圖片

兩種模式：

1. 使用者想要網頁 + 圖片：點擊頁面工具列中的「💾 儲存圖片」，儲存到當前專案作為 screenshot.png
2. 使用者只要圖片：呼叫 screenshot_chart(project_dir)（Playwright）並直接傳送 screenshot.png

工具列需求

每個圖表頁面必須包含以下按鈕：

<div class="actions">
  <button onclick="downloadPNG(this)">📥 下載 PNG</button>
  <button onclick="copyToClipboard(this)">📋 複製圖片</button>
  <button onclick="saveToProject(this)">💾 儲存圖片</button>
</div>

請勿包含畫廊入口。

重要檔案

檔案	用途
skills/chart/scripts/base-styles.css	基礎深色主題 CSS
skills/chart/scripts/base-export.js	匯出輔助工具：下載/複製/儲存到專案
skills/chart/scripts/build_chart.py	專案建立、HTML 建置、資料/腳本儲存、截圖
skills/chart/scripts/chart_server.py	靜態伺服器 + /save-chart API
skills/chart/templates/*.html	可重複使用的圖表範本
output/chart-html/<project>/*	所有產生的圖表成品

備註

• 將資料直接嵌入 HTML（const DATA = ...）以避免 iframe CORS 問題。
• 對於多圖表頁面，將所有圖表實例註冊到 window.CHART_INSTANCES。
• 使用有意義的專案名稱（topic-range-date）以便於查詢。