10. HTML 報告產出
除了將查詢結果匯出為 CSV / Excel 等格式，Lantide Data 還支援將 Report 文件一鍵轉換為獨立 HTML 報告，直接在瀏覽器中呈現美觀的資料分析成果。
10.1 什麼是 HTML Report
HTML Report 是基於 Report 類型的 Markdown 文件產出的獨立 HTML 檔案。AI Agent 會讀取 Report 內容，根據你選擇的版面與樣式設定，生成一份包含完整排版的 HTML 報告。產出的 .html 檔案與原始 .md 檔案存放在同一目錄下，可直接以瀏覽器開啟。
10.2 產出 HTML Report
- 開啟一個 Report 類型的 Markdown 分頁。
- 在分頁工具列中，點擊 HTML Report 下拉按鈕（地球圖示）。
- 選擇 Generate Report。
- 系統會先自動儲存當前文件，然後彈出報告配置對話框。
- 調整配置選項後，點擊 Generate。
- AI 面板會自動展開，Agent 開始根據 Report 內容與你的配置生成 HTML。
- 生成完成後，工具列的 Open Report 按鈕會自動啟用。
10.3 報告配置選項
報告配置對話框提供以下選項，讓你控制 HTML 報告的呈現方式。桌面版採雙欄版面（較寬對話框）：左欄為版面與樣式選項，右欄上方為 Use CDN 與 Custom Script 開關、下方為 Other Requirements 長文輸入；手機版維持單欄堆疊，Cancel / Generate 固定於底部。
| 選項 | 可選值 | 說明 |
|---|---|---|
| Layout Mode | Standard / Presentation | Standard 為可捲動的資料報告頁面；Presentation 為投影片式全螢幕展示（左欄） |
| Style Preset | Professional / Executive / Consulting | 產出時的樣式意圖（正式報告／KPI 儀表板／策略諮詢風格）。系統會據此引導排版，但不以硬性校驗阻擋生成；產出後仍可用樣式／區塊工具微調（左欄） |
| Color Scheme | Light / Dark / Corporate Blue / Neutral | 報告的整體配色方案意圖（左欄）；同樣為軟性指引 |
| Use CDN | 開 / 關 | 位於右欄最上方。Standard + 開啟：一定載入 Chart.js（standard-chartjs）。Presentation + 開啟：reveal.js。關閉時產出完全離線的純 HTML（offline） |
| Custom Script | 開 / 關 | 允許報告內含自訂 JavaScript（D3、Plotly 等）。開啟後須每次勾選風險確認才能 Generate。Presentation 版面不可用。工具列與 Quick Edit 會顯示黃色 Custom Script 標記 |
| Other Requirements | 自由文字（上限 2000 字） | 位於開關下方；右下角顯示字數計數。額外的自訂需求，例如「加入公司 Logo」或「使用中文標題」。輸入 / 可插入 User skill 片段（與 AI 對話 slash picker 相同來源） |
提示： 若目前有 active 的 External MCP writer session，對話框底部會顯示 Copy request for external agent，可將本次配置複製給外部 Agent 在其 client 中觸發 HTML 產出。Custom Script 須先在 GUI 勾選確認，複製內容才會包含
custom_script_acknowledgment。
提示： 選擇 Presentation + CDN 會使用 reveal.js 投影片引擎；Presentation + 關閉 CDN 則使用純 CSS scroll-snap。Standard + CDN 永遠含 Chart.js 互動圖表；離線模式不含 Chart.js。Custom Script 與 Presentation 不能同時使用。
10.4 檢視與匯出 HTML Report
產出完成後，有三種方式檢視報告：
- 工具列： 點擊 HTML Report 下拉中的 Open Report，系統會以預設瀏覽器開啟 HTML 檔案。
- 工具列匯出： 點擊 Export HTML Report，透過系統「另存」對話框將專案內的
.html複製到本機任意路徑；成功後會在 Finder／檔案總管中定位該檔案。僅桌面版（Electron）支援；匯出的是當下磁碟上的 HTML 快照（含 CDN 的報告離線開啟仍需網路）。 - AI 對話中： Agent 完成生成後，對話中會出現一個 「Open HTML Report」 按鈕，點擊即可在瀏覽器中開啟。
- 側邊欄快捷按鈕： 在 Projects 區塊中，已產出 HTML report 的 Report 檔案旁會顯示一個 Globe 圖示按鈕，點擊即可直接在瀏覽器中開啟對應的 HTML 報告，無需先打開分頁。
10.5 重新產出
如果你修改了 Report 內容，或想調整配置重新生成：
- 點擊工具列的 HTML Report 下拉 → Re-generate Report。
- 系統會提示確認是否覆蓋現有的 HTML 檔案。
- 確認後重新進入配置對話框，流程與首次產出相同。
Re-generate 與區塊契約： 每次 Re-generate 會覆寫整份 .html 並建立全新的區塊編號（text_id）。若你在舊對話中讓 Agent 修改某個 text_id，Regenerate 後該編號可能已失效，需請 Agent 重新讀取報告（read_html_text）。
10.5.1 事後修改 HTML（AI 對話）
產出後可在 Project 已聚焦 且已存在對應 .html 檔（或你正透過工具列 Generate / Re-generate 觸發的 html_report 任務）時，請 Agent 微調報告。多數「改一段字、加一段分析、刪掉一節、調 CSS」不必整份 Re-generate。聊天須為 Agent 模式（Ask 下無法改 HTML；見 §12.1.1）。
- Report 分頁：在該 Report
.md分頁上直接發修改請求，Agent 會自動使用區塊／樣式工具。 - 其他分頁（SQL、聊天等）：Agent 會先呼叫
activate_html_editing解鎖編輯工具，再進行修改；若專案內有多份 report 皆有 HTML，請在訊息中指明要改哪一份（如02_report.md或02_report.html；兩者指向同一份報告）。 - 新對話／新一則訊息：與統計分析啟動器類似，每輪對話需重新 activate 或回到 Report 分頁，不會跨 turn 記住編輯模式。
- 僅有
.md、磁碟尚無.html時，Agent 僅能使用create_html_report建立報告，不會暴露區塊／樣式工具。
| 要改什麼 | Agent 做法 |
|---|---|
| 段落內少數用字、數值、標籤 | read_html_text → get_html_chunk_by_id → patch_html_chunk_by_id（mode=replace；同區塊多處用一次 replacements） |
| 整段 HTML 結構大改 | 同上，但用 mode=full 替換該區塊 inner HTML |
| 新增一節／一張圖／一段分析 | insert_html_chunk：指定參照 text_id 與 before／after，提供新 text_id、描述與 inner HTML；其餘區塊不變 |
| 刪除一整節 | delete_html_chunk（報告須至少保留一個區塊） |
Chart.js 圖表（standard-chartjs） |
讀取／修改該區塊的 data-chart-spec JSON（可含 options.plugins.datalabels／annotation）；完成後重新 Open Report（或瀏覽器重新整理）才會重繪 |
配色、.card、:root 變數等全域 CSS |
get_html_styles → patch_html_styles（改 <style id="report-styles">） |
| Custom Script 的 JavaScript | get_html_scripts → patch_html_scripts（依 data-script-id 增刪改）；不要把 <script> 寫進區塊。系統 Chart.js 腳本不可改 |
| 整體換版面、開關 CDN／Custom Script、或契約失效的舊檔 | Re-generate（會覆寫整份 HTML 並重編 text_id） |
建議先改樣式、再改區塊 HTML，避免新增 class 卻沒有對應 CSS。Chart.js 報告的圖表顏色會從 :root 的 --primary／--accent 自動套用（若 spec 未指定色盤）。Chart.js 報告可顯示常駐數值標籤與命名標註（options.plugins.datalabels／annotation 純 JSON；散點密點需 xAdjust／yAdjust 錯開並開 callout 引線，無自動避讓；截圖／投影亦可讀數）。
- 無契約的舊 HTML（沒有
data-report-contract="1"）：區塊與樣式工具皆不可用，請 Re-generate。 - 有契約但缺少
#report-styles（早期 chunk 版產物）：區塊工具（含 insert／delete）仍可用；樣式工具會失敗，請 Re-generate 以啟用樣式編輯。 - 不要為了「只加／刪一段」而 Re-generate——優先 insert／delete，以免已滿意的其他段落被整份重寫。
10.5.2 Quick Edit HTML（手動區塊編輯）
在已產出 HTML 報告後，可從 Report 分頁工具列 HTML Report → Quick Edit HTML 開啟編輯對話框，無需透過 AI 對話即可修改單一區塊內容。
操作流程：
- 左側以卡片列出各區塊（
desc、kind、文字摘要）；點選一張卡片。 - 右側 Monaco 編輯該區塊的 inner HTML（不含外層
data-text-id標籤）。 - 點 Save 或按 Cmd/Ctrl+S 寫入磁碟。保存成功後，編輯器會自動同步為服務端規範化後的 HTML（空白、標籤格式可能與你輸入的略有差異，屬正常行為）。
- 可點 Open Live Preview 在預設瀏覽器開啟本機預覽頁；Quick Edit Save、或 Agent patch／insert／delete 成功後，預覽頁會在約 2 秒內自動重新載入（需保持該分頁開啟）。
與 AI 編輯的差異：
| 項目 | Quick Edit | AI 區塊工具 |
|---|---|---|
| 改單一區塊內容 | Monaco 編輯 inner HTML + Save（須 content_hash） |
patch_html_chunk_by_id（full／replace）；不檢查 hash，可能覆寫你剛手改的內容 |
| 加／刪區塊 | 不支援（請用 AI 或 Re-generate） | insert_html_chunk／delete_html_chunk |
| Agent 執行中 | 無法開啟 Quick Edit；若對話框已開則暫停 Save | 可繼續執行 |
| 全域 CSS | 本對話框不編輯；請用 AI patch_html_styles 或 Re-generate |
支援 patch_html_styles |
Live Preview 與安全： 預覽走獨立本機 origin（http://127.0.0.1:<preview-port>/r/<token>），與主 API 不同埠。開啟前由已登入的主 API 簽發短效 capability token，只綁定該份報告。Quick Edit 會顯示 Custom Script 黃標，並提示 runtime 可能蓋掉畫面內容。請勿將主 API 暴露到公網。
Re-generate 會覆蓋手動修改並重置所有 text_id。
10.5.3 內容品質提示（Agent 產出）
HTML 契約驗證通過後，Agent 仍可能收到非阻斷的內容品質提示（回應欄位優先為 content_hints；舊別名 content_warnings 仍可能一併回傳同一內容），例如：
| 代碼 | 含義 |
|---|---|
| HTML_CONTENT_THIN | 可編輯區塊過少（Standard 僅 1 段，或 Presentation 少於 2 張 slide） |
| HTML_MISSING_EXECUTIVE_SUMMARY | 缺少 executive summary／takeaway 類段落 |
| HTML_MISSING_LIMITATIONS | 缺少 limitations／caveats／next steps 類段落 |
這些提示不會阻止工具回傳成功，但 Agent 應在視為定稿或對外 announce 前擴寫內容（必要時用 insert／patch，而非立刻整份 Re-generate）。若生成失敗或反覆契約錯誤，Agent 應先載入 html_report_design skill（load_skill → read_skill_resource），讀取 Report 原文後再重建，而非盲目重試 create_html_report。外部 Agent 可從 MCP playbook 資源 shared_skills.html_report_design 取得相同指引。
10.6 按鈕停用條件
| 情況 | 影響的按鈕 | 提示 |
|---|---|---|
| AI Agent 正在執行中 | Generate / Re-generate、Open Report、Quick Edit HTML | Agent is busy |
| 聊天為 Ask 模式 | Generate / Re-generate（以及需寫入的 Resolve Comments／Approve & Execute） | 提示切回 Agent 後再繼續 |
| Plan 處於 Executing 狀態 | Generate / Re-generate | Plan is executing |
| 尚未產出過 HTML 檔案 | Open Report、Export HTML Report、Quick Edit HTML | 無可開啟／編輯的檔案 |
注意： HTML Report 功能僅適用於 Report 類型的 Markdown 文件，不適用於 Plan。
[圖片] 報告配置對話框與 HTML Report 工具列按鈕
設計說明： HTML 交付物定位見 Agent 時代的數據分析工作流 §四；契約與工具見 AI Agent 架構 §七。