georgelu-creator/diagram-skills

DiagramSkills

將圖表請求轉化為完成的可交付視覺成果，並附帶捆綁的 DiagramSpec 渲染器。首要產品是 代理生成的圖表品質：編寫可維護的 JSON，渲染 SVG/HTML 及可選的 PNG，檢查視覺效果，修正來源，並回傳結果。不要讓使用者為了完成一般工作而打開編輯器。公開的技能 ID 是 $diagram-skills；面向使用者的品牌是 DiagramSkills。

預設交付工作流程

1. 對於從散文到圖表的工作或實質性的修訂，從 templates/briefs/diagram-brief.json 建立一個簡潔的 .brief.json。它記錄目標、敘事、範圍、優先級、不確定性、內容風險和審查問題——而非私有的思考鏈。
2. 讀取 references/diagram-thinking-profiles.json 中選定的設定檔，根據情況調整至少三個品質問題，並在繪圖前執行 diagram_brief.py ... --strict。
3. 對於包含超過 14 個可見概念的層次化概覽，請閱讀 references/enterprise-board.md 並使用 layout: board。對於較小的關係圖，請使用節點/邊。
4. 從匹配的模板開始，取代其範例內容，並將簡報和來源 JSON 保留在輸出旁邊。
5. 在請求 PNG 之前執行 png-backend，然後僅在支援的本地光柵化器可用時，使用 --png 執行 render ... --strict。僅有來源檔案並不能算作完成的視覺請求。
6. 以全尺寸檢查生成的 SVG 或 1920 像素 PNG。檢查層級結構、中文文字、圖示一致性、裁剪、卡片擁擠、線條交叉以及簡報的敘事是否在視覺上佔主導地位。
7. 回答每個簡報品質問題，提供具體且明確的證據，並執行 diagram_brief.py ... --spec ... --strict --reviewed。然後使用 diagram_skills.py review ... 將已審查的簡報、來源和已檢查的 SVG 或 PNG 綁定到品質收據中。如果任何檢查失敗，請修正簡報、來源或渲染器，並重新渲染。在三輪基於證據的修正後停止；然後簡化或拆分。
8. 先交付圖片，然後連結簡報、SVG/HTML/來源/品質證據。僅在使用者要求手動編輯、匯入或向下鑽取時，才提及瀏覽器編輯器。

路由請求

1. 對於從散文到圖表的任務和實質性修訂，請閱讀 references/diagram-thinking.md。不要為了讓佈局對稱而捏造事實。
2. 當輸入是散文、不完整或需要成為可重複使用的提示時，請閱讀 references/prompt-system.md。
3. 選擇一個主要類型並閱讀其指南：
   • 系統架構
   • 代理工作流程
   • 資料流
   • 能力地圖
   • 使用者流程
   • 系統拓撲
   • 決策樹
   • 路線圖
   • 策略地圖
   • 流程圖
4. 僅讀取 references/diagram-thinking-profiles.json 中選定類型的設定檔。
5. 在創作單個圖表時閱讀 references/spec.md。使用 scripts/diagram_skills.py new 來獲得一個生產就緒的起點。
6. 對於高密度的分層架構資訊圖、區段網格、側邊清單、流程條和原則卡片，請閱讀 references/enterprise-board.md。
7. 安裝的技能是完整的生成路徑。如果完整的 DiagramSkills 儲存庫簽出也存在，references/workspaces.md、references/imports.md 和 references/editor.md 描述了可選的 Studio 專屬工作流程。在提供這些功能之前，請檢查儲存庫的 editor/ 目錄是否存在；切勿將其設為生成的前提條件。
8. 僅在選擇主題、品牌代碼、節點/邊語義或中文/英文標籤處理方式時，才閱讀 references/visual-language.md。
9. 套用 references/quality-contract.md。在內容審查、嚴格驗證和視覺審查通過之前，生成的檔案僅是候選檔案。

輸入合約

接受自然語言或結構化欄位。保留使用者提供的值；僅推斷低風險的遺漏項。

• goal：圖表應支援的問題或決策
• diagram_type：一個支援的 slug；當省略時從意圖推斷
• audience：例如高階主管、產品、工程、客戶
• narrative / scope：五秒鐘的故事和明確的內/外邊界
• must_show / emphasize / deemphasize：佈局前的內容優先級
• uncertainties / assumptions：未提供的事實和低風險的解釋
• content_risks / quality_questions：圖表可能誤導的方式和渲染後的檢查
• content：參與者、系統、步驟、能力、里程碑或決策
• relationships：資料、控制、成功、錯誤、非同步和反饋連結
• boundaries：所有權、生命週期階段、層級、領域或信任區
• composition：board 用於高密度企業概覽；graph 用於較小的關係圖
• lanes：用於泳道圖的有序所有者或角色
• rank：當自動排序不可接受時的明確非負層級
• language：預設為中文優先；保留既定的英文技術術語
• theme：paper、notion、spectrum、blueprint 或 terminal
• brand：允許清單中的十六進位顏色代碼，覆蓋於預設主題之上
• views：可選的儲存庫 Studio 概覽和詳細視圖；使用 child_view 連接
• imports：可選的儲存庫 Studio Mermaid 來源或 CSV 表格
• outputs：預設完成 SVG/HTML 加上來源 JSON 和診斷資訊；當本地光柵化器可用時包含 PNG

僅在未解決的選擇會實質性地改變含義、發布安全性或所需輸出時提問。否則，從類型指南中選擇常規佈局並陳述假設。

指令

從技能資料夾執行：

python3 scripts/diagram_brief.py work/architecture.brief.json --strict
python3 scripts/diagram_skills.py types
python3 scripts/diagram_skills.py png-backend
python3 scripts/diagram_skills.py new system-architecture --output work/architecture.json
python3 scripts/diagram_skills.py validate work/architecture.json --strict
python3 scripts/diagram_skills.py render work/architecture.json --output-dir output --strict
python3 scripts/diagram_brief.py work/architecture.brief.json --spec work/architecture.json --strict --reviewed
python3 scripts/diagram_skills.py review work/architecture.json --quality output/architecture.quality.json --brief work/architecture.brief.json --artifact output/architecture.svg

render 始終寫入 .svg、.html 和一個哈希綁定的 .quality.json 收據；當提供了 --png 且 png-backend 報告支援的光柵化器時，它也寫入 .png。結構上有效的渲染保持 pending-review 狀態，直到 review 驗證來源、檢查過的成品、已審查的簡報及其哈希值。失敗的 PNG 請求絕不會留下通過的收據。

安裝的技能是自包含的，用於生成。瀏覽器工作區、Mermaid/CSV 匯入和多視圖編輯是儲存庫的配套功能，僅當從包含 editor/ 的完整簽出目錄中執行時才可用。

不可協商的行為

• 在創作一個非平凡的圖表之前，先建立並驗證簡潔的圖表簡報。分享設計決策和證據，絕不分享私有的思考鏈。
• 偏好一個主要訊息和一個閱讀方向。將超過 14 個節點的圖形圖表拆分；結構化的企業 board 可以有意地在 3–6 個掃描帶中容納 20–45 張簡潔的卡片。
• 使用有序的 lanes 表示所有權，使用節點 rank 表示手動層級。使用 groups 表示語義圍欄；不要讓一個欄位同時具有兩種含義。
• 將密集的概覽連結到集中的 child_view 詳細資訊，而不是縮小標籤。
• 將有意的返回路徑標記為 feedback；未標記的循環將導致驗證失敗。
• 使用語義邊類型，而不是裝飾性顏色。當兩種或多種邊含義需要解釋時顯示圖例。
• 僅允許節點連結到 https、http、mailto 或頁面片段。可執行的 URL 方案將被拒絕。
• 保持中文標籤簡潔，並將穩定的英文技術術語放在副標題中。拆分過載的節點，而不是縮小文字。
• 對於流程管道、路線圖、拓撲和反饋迴圈，偏好 LR；對於層級、決策、策略和使用者旅程，偏好 TB。
• 執行簡報和圖表的嚴格驗證。檢查 SVG 或全尺寸 PNG，用具體證據回答每個類型設定檔問題，並透過 review 完成哈希綁定的品質收據。
• 當使用者要求的是圖表時，不要僅在寫完 Mermaid/JSON 就宣稱完成。渲染並回傳實際的視覺效果。
• 將 .brief.json 和來源 JSON 保留在可交付成果旁邊，以便含義和像素保持可重現和可審查。
• 當完整的儲存庫簽出提供 Studio 匯入時，將匯入的內容視為不受信任的。Mermaid 在嚴格模式下渲染，CSV 轉換為類型化欄位，任意 CSS 或可執行連結將被拒絕。

輸出選擇

• PNG：當 png-backend 報告支援的本地光柵化器時的首選預覽；否則先顯示 SVG。
• 圖表簡報 JSON：內容意圖、範圍、不確定性、優先級、風險和審查證據。
• SVG：可擴展的文件和原始碼控制。
• HTML：響應式檢視、平移/縮放、主題切換、下載和可點擊節點。
• 品質 JSON：機器可讀的驗證證據。
• 工作區 JSON：可選的儲存庫 Studio 格式，用於瀏覽器編輯、混合 Mermaid/原生視圖、離線持久化和向下鑽取。

擴展

僅當新的圖表類型具有獨特的資訊模型或佈局合約時，才添加它。將其 slug 新增到 DIAGRAM_TYPES、schema 枚舉、templates/<slug>.json、references/diagram-types/<slug>.md 和 references/diagram-thinking-profiles.json；然後添加嚴格的渲染和思考設定檔測試。在一個適配器中擴展 CSV 映射，並在 Zod 和 JSON Schema 中擴展工作區欄位。新主題必須在淺色/深色渲染中保留節點和邊的語義。