Communitygithub.com

Flowy - AI 原生圖表技能

設計技能。用來建立、讀取與更新 Flowy 圖表 HTML 檔案,適用於流程圖、系統架構圖及 UI 線稿/模型。當使用者要求繪製流程、視覺化架構、繪製 UI 草圖、規劃功能、建立線稿、繪製流程圖、建立 HTML 圖表,或提及「flowy」時,請使用此技能。同時,當使用者參考 `docs/diagrams/` 目錄中的現有 .html 圖表檔案,或要求更新/修改圖表時,也應使用此技能。

Flowy - AI 原生圖表技能 是什麼?

Flowy 是一個專門用於生成互動式 SVG 圖表 HTML 檔案的 AI 技能。它將圖表的結構、佈局和資料全部封裝在一個獨立的 HTML 檔案中,無需任何外部依賴,只需在瀏覽器中雙擊即可開啟。此技能適用於 Claude Code、Cursor 等支援 SKILL.md 的 AI 代理,用於建立流程圖、系統架構圖以及 UI 線稿。運作方式基於一個定義明確的資料結構,包含 `meta`、`nodes` 和 `edges` 三個部分,並提供一系列確切的節點/邊緣渲染規則、佈局規則和色彩調色盤。它遵循一個 HTML 模板,透過讀取模板 (`${CLAUDE_SKILL_DIR}/references/html-template.html`) 來保證渲染器程式碼的準確性,並支援建立、更新和讀取圖表。檔案儲存在專案的 `docs/diagrams/` 目錄下。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/vandezand-ctrl/workflow-automation-skills/tree/HEAD/skills/flowy

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 圖表之前:

  1. 讀取 ${CLAUDE_SKILL_DIR}/references/html-template.html 以取得最新的渲染器程式碼
  2. 列出 docs/diagrams/ 中的現有圖表以避免命名衝突
  3. 如果要更新現有圖表,請先讀取它並提取 DIAGRAM 物件

資料結構

每個圖表都是一個包含三個欄位的 JavaScript 物件:

{
  meta: { title, description, type, tags[], created, updated },
  nodes: [...],
  edges: [...]
}

meta

欄位型別必填備註
titlestring是可讀的標題
descriptionstring否圖表說明了什麼
typestring是"flowchart" 或 "ui-mockup"
tagsstring[]否用於組織分類
createdstring否ISO 日期 (YYYY-MM-DD)
updatedstring否ISO 日期,建立或更新時設為今天

nodes

欄位型別必填備註
idstring是唯一,小寫蛇形命名 (例如 "step1_upload")
typestring是"box"、"circle"、"diamond"、"note"、"group"
labelstring是顯示在形狀內的主要文字
sublabelstring否在懸浮提示中顯示的次要文字
position{ x, y }是左上角像素座標
size{ width, height }是像素尺寸
styleobject否參見下方的節點樣式欄位
groupstring否父容器群組節點的 id(僅視覺分組)

節點樣式欄位:fill、stroke、strokeWidth、color(文字)、fontSize、borderRadius、opacity

edges

欄位型別必填備註
idstring是唯一 (例如 "e_upload_to_extract")
sourcestring是來源節點 id
targetstring是目標節點 id
labelstring否箭頭上的文字 (例如 "是"、"錯誤")
sourceHandlestring否"top"、"right"、"bottom"(預設)、"left"
targetHandlestring否"top"(預設)、"right"、"bottom"、"left"
styleobject否參見下方的邊緣樣式欄位

邊緣樣式欄位: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)。渲染在所有其他節點的後方。標籤位於左上角。低不透明度

邊緣渲染規則

  1. 計算來源點:來源節點指定把手側的中心點(預設:底部)
  2. 計算目標點:目標節點指定把手側的中心點(預設:頂部)
  3. 繪製一條立方貝茲曲線(C 指令),控制點沿把手方向偏移 50px
  4. 使用 SVG <marker> 定義來添加箭頭
  5. 如果設定了 strokeDasharray,則渲染為虛線
  6. 如果 label 存在,則在貝茲曲線的中點渲染,並在其後放置一個小的白色背景矩形

佈局規則

流向

  • 流程圖:由上到下(預設)
  • UI 模型:在群組容器內由上到下,註釋在右側

間距

  • 節點中心之間最小 70px 垂直距離
  • 平行節點之間最小 60px 水平距離
  • 群組內邊距:群組邊界內 40px

決策菱形

  • 左側分支 = 主要/是 路徑
  • 右側分支 = 次要/否/錯誤 路徑

錯誤/警告註釋

  • 放置在主流程的右側
  • 使用紅色虛線邊緣連接(strokeDasharray: "6,3",stroke: #991b1b)

標準尺寸

型別寬度高度
box20050
circle9040
diamond12060
note18044

色彩調色盤

用途填充筆畫文字
動作#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)

  1. 縮放:滑鼠滾輪縮放 SVG viewBox。範圍:0.2 倍至 5 倍。朝游標位置縮放。
  2. 平移:在空白畫布上點擊並拖曳以平移 viewBox。
  3. 懸浮:將滑鼠懸停在節點上,會在游標附近顯示其 sublabel 的工具提示。
  4. 點擊:點擊節點會將其高亮(藍色邊框)並顯示所有連接的邊緣。點擊空白區域取消選取。
  5. 縮放至適宜:按鈕會計算所有節點的邊界框,並設定帶有 60px 內邊距的 viewBox。
  6. 下載 JSON:將 DIAGRAM 物件序列化為格式化的 JSON 並觸發檔案下載。

建立新圖表

當使用者要求新的流程圖或 UI 模型時:

  1. 讀取模板:讀取 HTML 模板參考檔案以取得最新的渲染器程式碼
  2. 分析請求:識別節點(步驟、決策、錯誤)和邊緣(連接)
  3. 分配位置:使用佈局規則(由上下到下的網格、標準間距)
  4. 套用顏色:使用色彩調色盤(終止節點 = 綠色、決策 = 琥珀色、錯誤 = 紅色等)
  5. 產生完整的 HTML 檔案:複製模板結構,將 DIAGRAM 物件替換為新的資料
  6. 儲存到 docs/diagrams/{kebab-case-name}.html
  7. 告知使用者:「請在瀏覽器中開啟 docs/diagrams/{name}.html 以檢視圖表。」

檔案命名

  • 位置:docs/diagrams/{name}.html
  • 格式:kebab-case.html(例如 docs/diagrams/upload-flow.html、docs/diagrams/checkout-screen.html)
  • 將 meta.updated 設為今天的 ISO 日期

更新現有圖表

當使用者要求修改圖表時:

  1. 讀取現有的 HTML 檔案
  2. 提取 <script> 區塊中的 DIAGRAM 物件
  3. 修改節點/邊緣
  4. 更新 meta.updated 為今天的日期
  5. 重新產生完整的 HTML 檔案(重新讀取模板以取得最新的渲染器)
  6. 儲存回同一路徑

讀取圖表

當被要求分析或描述圖表時:

  1. 讀取 HTML 檔案
  2. 找到 const DIAGRAM = { ... }; 區塊
  3. 依類型和標籤列出節點
  4. 追蹤邊緣以用自然語言描述流程
  5. 高亮決策點及其分支

範例

「為登入流程建立流程圖」

動作:建立 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 必須是格式清晰、未壓縮的

自我維護

如果你在建立圖表時發現有用的模式、新的佈局技巧、對於特定用途效果良好的顏色、或是渲染的改進,請更新此技能檔案以納入這些內容。保持技能的正確性和可操作性。

相關技能