HTML 檢視 是做什麼的?
node <skill-dir>/scripts/htmlview 是跨平台命令入口;以下用 htmlview 簡寫。需 Node.js 22+;瀏覽器檢查、截圖、匯出和獨立圖渲染還需要 Chrome 或 Chromium。找不到瀏覽器時按 error.next 處理。
已有 HTML:只換主題
- htmlview 產物:文件、報表或單圖頁用
htmlview style file.html --theme cloudmusic(htmlview style --list查主題);介面稿用--scheme或--brand。style原位更新,只重組外殼和派生圖。要輸出新檔案,先在同目錄複製到一個未使用的檔名,對副本執行style,然後用htmlview diff對照內容。 - 普通 HTML:
style不接收普通 HTML。需要使用技能外殼時,新建主題文件(見文件流程和文件元件),把現有內容遷入新檔案;不沿用舊外殼的 CSS 和腳本。只換風格時,保留原始數字、時間粒度和結論,不重算資料,也不為通過顯示檢查丟掉原圖的細節。
按任務選入口
| 使用者要的結果 | 做法 | 何時展開 |
|---|---|---|
| 便於閱讀和批註的技術方案、報告、說明、紀要或一頁紙 | 有 Markdown 用 doc build;直接編輯 HTML 用 doc new | 先讀文件流程;手寫 HTML 元件、加交叉引用或處理評論時讀文件元件 |
| 要核對經營數字、口徑和圖表的報表或 Dashboard | 從上游彙總檔案建資料包;data validate 後 data build | 先讀報表流程,改欄位、指標、圖或敘述時讀資料包;做 Dashboard 時讀看板設計 |
| 展示螢幕、狀態或互動流程的線框、高保真稿或原型 | ui new 後填每個螢幕,用真實控制項取值 | 先讀介面稿流程,選元件或寫互動時讀元件索引;定版式、配色或手寫元件時讀介面設計;畫資料看板時讀看板設計 |
| 單張 SVG 或離線圖頁 | 選下表圖族,寫宣告,再 viz render | 資料圖先讀宣告通則,再讀所選圖族;結構圖直接讀對應圖族 |
| 讀取、檢查、截圖或匯出本地 HTML | 使用 read、check、shot、export 或 embed | 參數和檢查結果見顯示與匯出 |
- 素材不是現成的頁面結構時,如零散筆記、會議記錄、JSON、CSV、日誌,或需要重排的 Markdown,寫內容前讀從材料到頁面。
- HTML 產物為單個可離線開啟的檔案。手寫時只改標題和
<!-- htmlview:content -->與<!-- /htmlview:content -->之間的內容;兩條標記各保留一次,佈局、主題和執行腳本由 CLI 組裝。 - Markdown 建構的文件改 Markdown 源;資料報表改資料包,不直接改生成的文字、圖或數字。沒有來源的資料不得編造;演示資料要標明是虛構範例。
- 覆蓋已存在的獨立成果,須確認目標後才用
--force;同源文件更新不需要--force。 - 未傳
--lang時,生成命令按標題和正文推斷圖號、目錄、圖例等外殼用語:英文詞數至少是中日韓字數的兩倍時用英文,否則用中文。其他語言或中英各半的內容顯式傳--lang。
按讀者要看什麼選圖
預設使用靜態圖。資料圖用 KChart JSON;結構關係用 Mermaid 或原生宣告。先查配置、樣式、連結和診斷通則,再查對應圖型;KChart 不照搬 Mermaid 的外觀。僅填寫資料、語義和閱讀意圖,不寫座標、字型大小、顏色或繪圖腳本。圖內放不下可滾動,頁面本身不應橫向溢出。
| 讀者問題 | 圖型入口 | 按需閱讀 |
|---|---|---|
| 怎麼變化、何時改變? | line、area、sparkline、small-multiples、stream、combo、bump、candlestick、launch-fan | 趨勢 |
| 哪個更大、差多少、離目標多遠? | bar、column、dumbbell、slope、bullet、gauge、interval、split-compare | 比較 |
| 總量怎麼組成、各步驟損失多少? | share、pie、donut、radial-share、rose、funnel、waterfall、waffle、tally、treemap、sunburst | 構成 |
| 數值如何分佈、有無離群或相關? | histogram、boxplot、violin、strip、scatter | 分佈 |
| 多維矩陣或日曆中哪裡異常? | heatmap、bubble-matrix、calendar、radar、parallel | 矩陣 |
| 誰與誰連接、量如何流轉? | network、sankey、threads | 網路 |
| 分佈在哪裡? | choropleth、geo-scatter | 地圖 |
| 如何分類、怎麼從主題展開? | KChart tree、mindmap;Mermaid mindmap、ishikawa、treeView-beta | 層級與腦圖 |
| 流程從誰到誰、狀態如何轉移? | flowchart、stateDiagram-v2、journey、swimlane-beta、eventmodeling、agentflow-beta、原生 swimlane | 流程 |
| 呼叫先後和參與者是誰? | sequenceDiagram、usecase-beta | 時序 |
| 如何排期、分欄或編號? | gantt、timeline、gitGraph、kanban、packet、quadrantChart | 時間與網格 |
| 實體、類或需求怎樣關聯? | erDiagram、classDiagram、requirementDiagram | 資料模型 |
| 一條語法規則怎樣匹配符號? | railroad-beta、railroad-ebnf-beta、railroad-abnf-beta、railroad-peg-beta | 資料模型 |
| 系統如何分層、容器和依賴在哪裡? | C4Context、C4Container、C4Component、C4Dynamic、C4Deployment、architecture-beta、block、wardley-beta、原生 layers、blocks | 架構 |
| 一頁總覽:分組裡的卡片、主流程和圖例? | 原生 blocks(卡片、徽章、圖例、強調線);已有 Mermaid 塊圖時 block | 架構 |
| 手頭已有 Mermaid 數值圖? | pie、xychart、sankey、radar-beta、treemap | Mermaid 數值圖;新資料圖用上方 KChart 圖型 |
| 集合如何重疊、情境如何分類? | venn-beta、cynefin-beta | 集合、情境 |
| 使用 ZenUML 語法的呼叫圖? | zenuml(KChart 原生渲染,無需外部外掛) | ZenUML |
| 只想確認渲染器版本? | Mermaid info(不用於交付) | Mermaid 通則 |
Markdown 用 kchart、mermaid、layers、blocks、swimlane 圍欄;手寫 HTML 用 <pre data-viz="語法">,跳脫其中的 HTML 特殊字元。文件圖題寫在宣告中:KChart title,結構圖前言 title: 或該語法支援的標題語句。圖題和圖中文字與正文用同一種語言。內建圖族放不下或表達不了時,如巢狀過深、關係過多或機制示意,先拆成總圖和分圖;仍需要手畫時讀手寫 SVG。
命令速查
| 要做什麼 | 命令 |
|---|---|
| 文件起稿/從原始檔生成 | htmlview doc new plan.html --type plan --title '容量評估計劃' 或 htmlview doc build spec.md --out spec.html --type tech-spec |
| 資料包和報表 | htmlview data init example → htmlview data validate example/report.json → htmlview data build example/report.json --out report.html |
| 介面稿骨架 | htmlview ui new prototype.html --title '申請處理' --device mobile --screens '列表,詳情' |
| 靜審、比較內容 | htmlview audit file.html;htmlview diff old.html new.html |
| 為文件或介面稿重新裝入圖模組 | htmlview style file.html(保留現有主題與內容) |
| 顯示檢查、截圖、匯出 | htmlview check file.html;htmlview shot file.html --select 'figure';htmlview export file.html --format pdf;整頁長圖 htmlview export file.html --format png |
| 讀取本文、內嵌本地資源 | htmlview read file.html [--outline 或 --section id];htmlview embed file.html |
| 獨立圖、欄位約束、主題色、手寫圖量字 | htmlview viz render spec.json --out chart.svg;htmlview viz schema bar;htmlview viz palette --theme paper;htmlview viz measure '訂單服務' --size 13 |
使用者自帶配色時用 --theme-file <JSON>,欄位和範例見主題檔案。主題隨 HTML 內嵌;介面稿使用獨立品牌配色。
htmlview <子命令> --help 給出精確參數。檢查類命令的 pass:false 是已完成檢查但發現問題;按 failures[].fix 修。ok:false 是命令沒能完成,按 error.next 處理。
驗證再交付
- 新建或修改產物後執行
audit。缺少圖模組時執行style重組,再審計;報表有證據不一致時回資料包修正。 - 對會改變顯示的改動執行
check,再shot開啟實際截圖。看標題層次、文字歸屬、留白和手機首屏;寬圖開啟完整 SVG 檢查。帶互動的原型實際點過關鍵路徑。 - 交付 PDF 時開啟實際 PDF,確認圖題和圖身同頁、邊緣完整。遇到列印提示,換合適的紙型或調整佈局,保留可讀字型大小;無法完整列印則說明限制。