Flowy,AI 原生圖表技能
Flowy 產生自包含的 HTML 檔案,用來渲染互動式 SVG 圖表。每個檔案都包含了內嵌的 CSS、JavaScript 和圖表資料,完全零依賴,只要雙擊就能在任何瀏覽器中開啟。
檔案位置
- 圖表:
docs/diagrams/*.html(例如docs/diagrams/upload-flow.html)。 在首次使用時建立此資料夾;它可能還不存在。如果專案已將圖表放在其他地方,請改為遵循該專案的慣例。 - HTML 模板:
${CLAUDE_SKILL_DIR}/references/html-template.html, 這是標準的渲染器,也是此技能提供的唯一參考檔案。此路徑會解析到技能本身的資料夾(無論是安裝在插件、個人或專案中),因此它不依賴於目前專案。
此技能刻意不提供 schema 檔案、範例資料夾或視覺編輯器。這個技能的早期版本指向了 flowy/schema.ts、flowy/examples/、flowy/editor.html 以及磁碟上的 Flowy 原始碼儲存庫。那些檔案都不存在,路徑已經過時,遵循它們只是浪費時間。上述的 HTML 模板才是結構的唯一真相來源;在開始撰寫圖表之前,請先閱讀它。
前置檢查
在建立或編輯 Flowy 圖表之前:
- 讀取
${CLAUDE_SKILL_DIR}/references/html-template.html以取得最新的渲染器程式碼 - 列出
docs/diagrams/中的現有圖表以避免命名衝突 - 如果要更新現有圖表,請先讀取它並提取
DIAGRAM物件
資料結構
每個圖表都是一個包含三個欄位的 JavaScript 物件:
{
meta: { title, description, type, tags[], created, updated },
nodes: [...],
edges: [...]
}
meta
| 欄位 | 型別 | 必填 | 備註 |
|---|---|---|---|
| title | string | 是 | 可讀的標題 |
| description | string | 否 | 圖表說明了什麼 |
| type | string | 是 | "flowchart" 或 "ui-mockup" |
| tags | string[] | 否 | 用於組織分類 |
| created | string | 否 | ISO 日期 (YYYY-MM-DD) |
| updated | string | 否 | ISO 日期,建立或更新時設為今天 |
nodes
| 欄位 | 型別 | 必填 | 備註 |
|---|---|---|---|
| id | string | 是 | 唯一,小寫蛇形命名 (例如 "step1_upload") |
| type | string | 是 | "box"、"circle"、"diamond"、"note"、"group" |
| label | string | 是 | 顯示在形狀內的主要文字 |
| sublabel | string | 否 | 在懸浮提示中顯示的次要文字 |
| position | { x, y } | 是 | 左上角像素座標 |
| size | { width, height } | 是 | 像素尺寸 |
| style | object | 否 | 參見下方的節點樣式欄位 |
| group | string | 否 | 父容器群組節點的 id(僅視覺分組) |
節點樣式欄位:fill、stroke、strokeWidth、color(文字)、fontSize、borderRadius、opacity
edges
| 欄位 | 型別 | 必填 | 備註 |
|---|---|---|---|
| id | string | 是 | 唯一 (例如 "e_upload_to_extract") |
| source | string | 是 | 來源節點 id |
| target | string | 是 | 目標節點 id |
| label | string | 否 | 箭頭上的文字 (例如 "是"、"錯誤") |
| sourceHandle | string | 否 | "top"、"right"、"bottom"(預設)、"left" |
| targetHandle | string | 否 | "top"(預設)、"right"、"bottom"、"left" |
| style | object | 否 | 參見下方的邊緣樣式欄位 |
邊緣樣式欄位:stroke、strokeWidth、strokeDasharray、markerEnd
節點渲染規則
| 型別 | SVG 元素 | 詳細說明 |
|---|---|---|
| box | <rect> | 透過 rx/ry 屬性從 borderRadius 取得圓角。預設值:8px |
| circle | <ellipse> | cx = x + width/2,cy = y + height/2,rx = width/2,ry = height/2 |
| diamond | <polygon> | 4 個點:頂部中央、右側中央、底部中央、左側中央 |
| note | <path> | 帶有摺角(右上角)的矩形。摺角尺寸:12px |
| group | <rect> | 虛線邊框 (stroke-dasharray: 6,3)。渲染在所有其他節點的後方。標籤位於左上角。低不透明度 |
邊緣渲染規則
- 計算來源點:來源節點指定把手側的中心點(預設:底部)
- 計算目標點:目標節點指定把手側的中心點(預設:頂部)
- 繪製一條立方貝茲曲線(
C指令),控制點沿把手方向偏移 50px - 使用 SVG
<marker>定義來添加箭頭 - 如果設定了
strokeDasharray,則渲染為虛線 - 如果
label存在,則在貝茲曲線的中點渲染,並在其後放置一個小的白色背景矩形
佈局規則
流向
- 流程圖:由上到下(預設)
- UI 模型:在群組容器內由上到下,註釋在右側
間距
- 節點中心之間最小 70px 垂直距離
- 平行節點之間最小 60px 水平距離
- 群組內邊距:群組邊界內 40px
決策菱形
- 左側分支 = 主要/是 路徑
- 右側分支 = 次要/否/錯誤 路徑
錯誤/警告註釋
- 放置在主流程的右側
- 使用紅色虛線邊緣連接(
strokeDasharray: "6,3",stroke:#991b1b)
標準尺寸
| 型別 | 寬度 | 高度 |
|---|---|---|
| box | 200 | 50 |
| circle | 90 | 40 |
| diamond | 120 | 60 |
| note | 180 | 44 |
色彩調色盤
| 用途 | 填充 | 筆畫 | 文字 |
|---|---|---|---|
| 動作 | #ffffff | #2d6a4f | #1f2937 |
| 主要動作 | #d1fae5 | #065f46 | #065f46 |
| 決策 | #fef3c7 | #92400e | #1f2937 |
| 錯誤 | #fee2e2 | #991b1b | #991b1b |
| 終止節點 | #40916c | #2d6a4f | #ffffff |
| 群組 | #f5f5f2 | #e6e4df | #374151 |
| 資訊/次要 | #dbeafe | #1e40af | #1e40af |
| 預設邊緣 | , | #6b7280 | , |
HTML 檔案結構
每個 Flowy HTML 檔案都遵循以下結構。請閱讀 HTML 模板參考以取得完整的運作程式碼。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{圖表標題}</title>
<style>
/* 所有 CSS 皆為內嵌:工具列、畫布、工具提示、選取高亮 */
</style>
</head>
<body>
<div id="toolbar">
<!-- [縮放至適宜] [-] 100% [+] 標題 徽章 [下載 JSON] -->
</div>
<div id="canvas-wrap">
<svg id="canvas">
<defs><!-- 箭頭標記 --></defs>
<g id="diagram-root"></g>
</svg>
</div>
<div id="tooltip"></div>
<script>
const DIAGRAM = { meta: {...}, nodes: [...], edges: [...] };
// 渲染 + 互動性程式碼
</script>
</body>
</html>
工具列
- 固定在頂部,高度 48px,白色背景,底部邊框
- 左側:縮放至適宜按鈕、縮小、縮放 %、放大
- 中央:圖表標題(粗體)+ 類型徽章(灰色藥丸形狀)
- 右側:下載 JSON 按鈕(藍色)
互動性(全部使用原生 JavaScript)
- 縮放:滑鼠滾輪縮放 SVG viewBox。範圍:0.2 倍至 5 倍。朝游標位置縮放。
- 平移:在空白畫布上點擊並拖曳以平移 viewBox。
- 懸浮:將滑鼠懸停在節點上,會在游標附近顯示其
sublabel的工具提示。 - 點擊:點擊節點會將其高亮(藍色邊框)並顯示所有連接的邊緣。點擊空白區域取消選取。
- 縮放至適宜:按鈕會計算所有節點的邊界框,並設定帶有 60px 內邊距的 viewBox。
- 下載 JSON:將
DIAGRAM物件序列化為格式化的 JSON 並觸發檔案下載。
建立新圖表
當使用者要求新的流程圖或 UI 模型時:
- 讀取模板:讀取 HTML 模板參考檔案以取得最新的渲染器程式碼
- 分析請求:識別節點(步驟、決策、錯誤)和邊緣(連接)
- 分配位置:使用佈局規則(由上下到下的網格、標準間距)
- 套用顏色:使用色彩調色盤(終止節點 = 綠色、決策 = 琥珀色、錯誤 = 紅色等)
- 產生完整的 HTML 檔案:複製模板結構,將
DIAGRAM物件替換為新的資料 - 儲存到
docs/diagrams/{kebab-case-name}.html - 告知使用者:「請在瀏覽器中開啟
docs/diagrams/{name}.html以檢視圖表。」
檔案命名
- 位置:
docs/diagrams/{name}.html - 格式:
kebab-case.html(例如docs/diagrams/upload-flow.html、docs/diagrams/checkout-screen.html) - 將
meta.updated設為今天的 ISO 日期
更新現有圖表
當使用者要求修改圖表時:
- 讀取現有的 HTML 檔案
- 提取
<script>區塊中的DIAGRAM物件 - 修改節點/邊緣
- 更新
meta.updated為今天的日期 - 重新產生完整的 HTML 檔案(重新讀取模板以取得最新的渲染器)
- 儲存回同一路徑
讀取圖表
當被要求分析或描述圖表時:
- 讀取 HTML 檔案
- 找到
const DIAGRAM = { ... };區塊 - 依類型和標籤列出節點
- 追蹤邊緣以用自然語言描述流程
- 高亮決策點及其分支
範例
「為登入流程建立流程圖」
動作:建立 docs/diagrams/login-flow.html,內含:
start(圓形,綠色)→enter_credentials(方塊)→validate(菱形,琥珀色)validate→ 是/左 →dashboard(圓形,綠色)validate→ 否/右 →show_error(註釋,紅色)→ 虛線箭頭返回enter_credentials
「更新設定模型以加入深色模式切換開關」
動作:讀取 docs/diagrams/settings-screen.html,提取 DIAGRAM,在「主題」區段之後新增一個標籤為「深色模式」的新方塊節點 "section_dark_mode",更新 meta.updated,重新產生 HTML。
「為上傳流程的第 3 個步驟加入錯誤處理」
動作:讀取 HTML,在節點陣列中找到步驟 3,在右側新增一個錯誤註釋節點,從步驟 3 到錯誤註釋新增一條紅色虛線邊緣,重新產生。
重要限制
- 零依賴:無 npm、無 CDN 連結、無外部腳本/樣式
- 可離線運作:必須能在無網路存取的情況下渲染
- 單一檔案:每個圖表是一個
.html檔案 - 瀏覽器原生:僅使用標準 HTML5、CSS3、SVG 和原生 ES6+ JavaScript
- 對 LLM 友善:DIAGRAM JSON 必須是格式清晰、未壓縮的
自我維護
如果你在建立圖表時發現有用的模式、新的佈局技巧、對於特定用途效果良好的顏色、或是渲染的改進,請更新此技能檔案以納入這些內容。保持技能的正確性和可操作性。