Diagram Studio
將 JSON 規格轉換為清晰的圖表。外觀可以完全配置:
- 手繪風格: 使用 rough.js 的抖動效果和手寫字體。
- 清晰向量: 無抖動,使用無襯線或襯線字體,柔和陰影。
- 兩者之間的任何風格。
所有文字都會被轉換為輪廓,因此 SVG 和 PNG 在任何地方看起來都相同。自動檢查工具會捕捉重疊、溢出文字、邊界上的標籤以及穿過方塊的箭頭。
所有功能都已打包:只需要 Node 18+,無需 npm install 且無需網路。
下方的 SKILL_DIR 指的是此技能資料夾的絕對路徑(包含此檔案的資料夾)。
node SKILL_DIR/scripts/render.mjs diagram.json --out out/ # → out/diagram.png (2x), .svg, .report.json, .tiles/
0. 在 Codex、Claude Code 或其他代理中執行
- SKILL_DIR:
- 在 Codex 中,使用技能根目錄表擴展技能的相對路徑(例如
r0/diagram-studio/SKILL.md→~/.codex/skills/diagram-studio)。 - 在 Claude Code 中,通常位於
~/.claude/skills/diagram-studio。 - 總是使用該絕對路徑來呼叫腳本。
- 在 Codex 中,使用技能根目錄表擴展技能的相對路徑(例如
- 檢視圖片是強制性的:原始圖片、網格、圖塊和比較結果。
- Codex:使用
view_image工具並指定 PNG 路徑。render.mjs會為此寫入name.preview.png(≤ 1400 px),因此無需自行調整圖片大小;如有需要,可使用name.tiles/*.png查看細節。 - Claude Code:使用 Read 工具。
- 絕不要僅根據 lint 輸出判斷渲染結果。
- Codex:使用
- 沙盒友善:
- 只需要
node。沒有網路呼叫且無需安裝。 - 輸出到
--out指定的資料夾;請將其保留在工作區內,例如./diagram-out。 - WebP/HEIC 轉換會寫入系統暫存目錄。
- 只需要
- 使用者貼了一張圖片而不是給出路徑: 如果你能看到附件路徑,請直接使用它。否則詢問檔案路徑,因為工具需要真實檔案。
- 完成後: 列出 PNG、SVG 和 JSON 的絕對路徑,以便使用者開啟。
1. 選擇任務
| 使用者需求 | 任務 | 閱讀下一步 |
|---|---|---|
| “讓這張圖片更清晰 / 更高解析度 / 更乾淨”、“重新繪製 / 重建 / 復刻 / 高清重建這個” | A. 從圖片重建。 以保真度為優先:除非另有說明,否則保持原始風格 | references/rebuild-from-image.md(必需的) |
| “美化 / 整理這個圖表” | A + 打磨。 與 A 相同,然後改善層級結構、間距和對齊 | references/rebuild-from-image.md |
| 從描述、程式碼或筆記建立新圖表 | B. 新建圖表 | references/spec.md |
| 不同的外觀(“改成手繪風格”、“扁平企業風”、“藍圖風”、“用於學術論文”) | C. 重新風格化 | references/style-guide.md |
對於給定的圖片,預設情況下需匹配其風格:手繪風格保持手繪,扁平風格保持扁平,並保留其顏色和字體類別。僅在使用者要求時才改變外觀。預設設定是起點,而非限制;styleOverrides、自訂調色板和自訂字型檔案("fonts")可以重現幾乎任何外觀。僅在請求確實模稜兩可時才詢問保真度等級,例如“美化”但沒有參考風格。否則預設為忠實還原 + 更清晰。
從 templates/ 中最接近的範本開始:將其複製到工作資料夾並編輯副本。預覽圖在 assets/gallery/ 中。範本是一種模式,而非內容:替換 所有 文字,並保持原始來源中的換行和箭頭完全一致。--expect 可以捕捉到遺漏或措辭改變。
| 範本 | 展示內容 |
|---|---|
dense-rebuild.json | 密集架構圖的重建:明確的坐標、卡片、面板、合併的連接器、內聯標籤 |
pipeline-rag.json | 由左至右的管線:使用 connect、rightOf 的列、自動調整大小的面板 |
layered-architecture-zh.json | 中文分層架構:使用 below 堆疊的列、扇入箭頭、圓柱體 |
flowchart-decision.json | 流程圖:藥丸形、菱形、是/否分支、迴圈箭頭 |
agent-loop.json | 循環:曲線箭頭、徽章、橢圓形中心樞紐 |
auto-layout.json | 無坐標:使用具有群組的 ELK 自動佈局 |
2. 循環(每個任務)
-
先盤點。 逐字列出每個文字字串(將其儲存為
texts.txt,每行一個)、每個節點、每個箭頭(從 → 到,標籤)和每個群組。不要發明或遺漏任何內容。 -
撰寫
name.json,從一個範本開始。 -
渲染:
node SKILL_DIR/scripts/render.mjs name.json --out OUT --expect texts.txt -
修正每個 ERROR;每個錯誤都有具體的
→修復方式。修正 WARN,除非是故意的,並在相應的元素或箭頭上使用"ignore": ["code"]來靜音故意產生的警告。 -
查看
OUT/name.png和OUT/name.tiles/*.png,並與原始圖片進行比較(使用scripts/compare.mjs)。執行prompts/visual-review.md中的檢查清單;linter 無法判斷意義、平衡或保真度。 -
重複步驟 3–5,直到有 0 個錯誤且看起來合理(通常需要 2–4 輪)。
-
交付:
name.png:2x;用於列印請使用--scale 3。name.svg:向量格式。name.json:保留以供後續編輯。
添加一行關於你保留了什麼以及改進了什麼的說明。
3. 60 秒規格
{
"canvas": { "width": 1600 },
"style": "marker",
"title": "Checkout Service",
"subtitle": "{blue:clients} · {purple:services} · {green:data}",
"elements": [
{ "id": "web", "title": "Web app", "icon": "app-window", "x": 120, "y": 220 },
{ "id": "api", "title": "API", "color": "purple", "emphasis": true, "rightOf": "web", "gap": 160,
"lines": ["`POST /checkout`", { "text": "validates cart", "muted": true }] },
{ "id": "db", "type": "cylinder", "title": "Orders DB", "color": "green", "below": "api", "gap": 120 },
{ "id": "core", "type": "panel", "title": "Backend", "color": "purple", "contains": ["api", "db"] },
{ "id": "n1", "type": "note", "text": "Idempotent by **order id**", "rightOf": "core", "gap": 40 }
],
"arrows": [
{ "from": "web", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "db", "label": "INSERT", "color": "green" }
]
}
-
元素類型:
box(預設)、pill、ellipse、circle、diamond、cylinder、note、card、panel、text、icon、badge、image、path(自訂 SVG 形狀),以及佈局輔助元素row、column和group。 -
定位每個元素,使用以下其中一種方式:
- 使用左上角的
x/y,或使用中心的cx/cy。 - 使用
below/above/rightOf/leftOf加上gap。 - 使用
contains,它會自動將面板調整為適合其子元素的大小。
大小會自動計算。設定
w/h以精確匹配原始圖片。 - 使用左上角的
-
文字:
title為粗體,\n會換行。lines是正文行。文字內的標記:**bold**(粗體)`code`(使用等寬字體){green:span}和{muted:span}->(繪製為箭頭字形)
中英文可以自由混合。可以為每個元素設定
size、textSize、font、textColor和align。 -
顏色 使用色系(
blue purple green orange red teal yellow pink gray navy)、色調(blue.tint)、#hex或純 CSS 名稱,如white,透過color、fill、stroke和textColor設定。 -
箭頭 連接
from到to:- 固定一側並使用
"id.right"或"id.right+20"沿該側滑動。 - 標籤:使用
label,透過labelPos(above、below、left、right或inline)放置,並使用labelAt微調位置。 - 外觀:
dash、color、width和head(end、start、both或none)。 - 路徑:使用
via點、points(精確折線)或"route": "curve"。
- 固定一側並使用
每個鍵的詳細說明請參考 references/spec.md。
4. 外觀:風格、調色板、字型、效果
-
風格預設:
- 手繪風格:
marker(預設)、neat、excalidraw、sketchy、whiteboard、pencil、blueprint、chalk。 - 清晰風格:
clean、paper。
任何預設欄位都可以透過
styleOverrides覆蓋:roughness(0 = 完美直線)和bowingfillStyle(solid、hachure、cross-hatch、dots或none)strokeScale、cornerRadiusshadow(none、soft或hard)font、cjkFont、codeFont、background
- 手繪風格:
-
調色板:
marker、pastel、excalidraw、mono、academic、colorblind、modern、blueprint、chalkboard、midnight。要精確重現原始圖片的顏色,請執行node SKILL_DIR/scripts/palette.mjs original.png並貼上結果。 -
字型:
- 手寫字型:
shantell、kalam、caveat、patrick、architects。 - 無襯線字型:
inter。襯線字型:serif。等寬字型:mono。 - 中日韓字型(CJK):
kai(手寫風格)、kuaile(俏皮風格)、sans-sc(乾淨風格)。 - 你自己的
.ttf/.otf/.woff:"fonts": {"brand": {"regular": "Brand.ttf", "bold": "Brand-Bold.ttf"}},然後使用"font": "brand"。
- 手寫字型:
-
目錄:
assets/gallery/styles.png、palettes.png和fonts.png。使用scripts/catalog.mjs重新生成它們。 -
圖示: 超過 1500 個 Lucide 圖示。使用
node SKILL_DIR/scripts/icons.mjs search 数据库 robot queue搜尋,並使用icons.mjs sheet a,b,c預覽。 -
原始圖片工具:
grid.mjs:在原始圖片上覆蓋坐標網格。請閱讀紅色軸標籤,不要讀取像素位置。fontmatch.mjs:在原始圖片的放大裁切旁顯示每種字型的範例文字。palette.mjs:提取原始圖片的顏色。crop.mjs:裁切出 Logo、照片或螢幕截圖,作為image元素嵌入。compare.mjs:並排檢視;添加--crop x,y,w,h可將兩張圖片縮放到同一區域進行比較。
-
深色或替代版本: 保持相同的規格,僅更改
palette(midnight、blueprint或chalkboard)或style,然後使用另一個--name渲染。 -
用於投影片(PPT、Keynote):
"canvas": {"aspect": "16:9"}會將圖片填充到投影片比例。"background": "transparent"會產生帶有 Alpha 通道的 PNG。SVG 也可以直接貼上。
5. 清晰度規則(始終適用)
- 嚴格保留給定的文字:標籤、程式碼識別碼和中文術語。除非被要求,否則不要發明、翻譯或遺漏文字。
- 讓層級結構可視化:
- 每個方塊使用粗體標題。
- 將識別碼作為正文或
code文字。 - 將解釋作為
muted文字。 - 章節標題使用其章節的顏色。
- 顏色代表某種意義: 每個區域或角色使用一個色系,並保持一致。箭頭標籤繼承其箭頭的顏色。
- 保留呼吸空間:
- 對於帶有標籤箭頭連接的形狀之間,間距 ≥ 60 px;否則 ≥ 24 px。
- 使用
contains來適應面板。 - 不要讓標籤位於邊界上。
- 縮小時仍然可讀:
- 文字 ≥ 18 px(預設:節點標題 30、正文 25、標籤 24)。
- 畫布寬度 1400–2200 px,長寬比在 1:2 和 3:1 之間。否則 linter 會發出警告。
- 超過 6 個節點的長鏈:將其蛇形排列成 2–3 行,或使用 ELK 的
"direction": "DOWN",而不是一個非常長的行。
- 減少交叉,避免繞路。 在添加
via之前,先進行對齊和重新排序。 - 在重建任務中,進行打磨而非重新設計: 改善對齊、間距和層級結構,但保留拓撲、閱讀順序和風格識別度。
6. 完成的定義
-
render.mjs報告 0 個錯誤。任何剩餘的警告都是故意產生並已使用ignore靜音。 - 每個盤點字串都存在且拼寫精確(
--expect texts.txt通過)。 - 你已檢視 PNG 和圖塊,並對重建的圖片與原始圖片進行了並排比較:結構相同、風格識別度相同、更清晰。
- 你已交付 PNG、SVG 和 JSON,並附帶簡短的“保留/改進”說明。
7. 疑難排解
node: command not found:請安裝 Node 18+。無需其他操作。- 當
sips、magick、dwebp、ffmpeg或 Python PIL 可用時,WebP、HEIC、BMP 或 TIFF 輸入會自動轉換。否則請向使用者索取 PNG 或 JPEG 檔案。 - 字元呈現為
?:捆綁的字型涵蓋拉丁字母、GB2312 簡體中文和常見符號。如果缺少字元,請重新措辭,或註冊包含該字元的字型。 - 有關每個 lint 代碼及其修復方式,請參閱
references/troubleshooting.md。