用 AI 撰寫
Siren 的 repo 附了一個 agent skill:skills/siren。裝上之後,Claude Code 這類 AI coding agent 就知道 Siren 支援哪些語法、timeline 的規則和目標 id 怎麼算,寫完還會自己跑驗證、修掉錯誤,交給你一份能直接渲染的 .srn。
它採用開放的 Agent Skills 格式,不綁定特定的 agent 或模型。
它會做什麼
跟 agent 說「幫我畫一張會動的架構圖」「把這張 Mermaid 圖加上逐步揭示」「這份 .srn 畫不出來,幫我修」,skill 就會被用上。agent 會照這個流程走:
- 先想故事:這張圖要說明什麼、讀者應該依什麼順序看到每個部分。timeline 是一段敘事,不是元素清單。
- 選圖表類型:流程和架構用流程圖,隨時間發生的互動用序列圖,型別用類別圖,生命週期用狀態圖,資料模型用 ER 圖。
- 寫圖表本體,只用 Siren 支援的 Mermaid 語法,顏色交給主題,除非它帶有意義(見下方)。
- 寫 timeline,遵守 Siren 的規則:出現之前不能強調、節點退場時連線也要退場、每個目標只能進場一次等等。
- 驗證:用 skill 附的腳本實際渲染,把每個錯誤和警告都修掉。
- 交付
.srn,附上每一步在演什麼。
如果你給的是現成的 Mermaid 圖,agent 會保留原本的內容,只補上 timeline。開頭的 Mermaid frontmatter 也會留著:Siren 會讀它,但目前不套用裡面的任何設定,所以 skill 會告訴 agent 每個設定會有一則警告,不是錯誤(見快速開始)。
skill 也收了最容易讓 agent 絆倒的規則:只有整行才是註解,所以每個 %% 註解都要自成一行(timeline 區塊裡則可以放在任何地方);序列圖裡 create participant X 的下一則訊息一定要是送給 X 的,destroy X 的下一則一定要是 X 送出或收到的,中間不能插別的東西,否則整份文件會被拒絕。它的常見錯誤表列了這些訊息和修法。
因為 Siren 文件拿掉 timeline 區塊之後必須是一份 Mermaid 文件,skill 也要求 agent 把產出的每一份文件拿去真的 Mermaid 檢查一次,用 Siren repo 檢查自己範例的那支腳本(在 Siren 的 checkout 裡執行 pnpm --filter siren-core check-examples -- diagram.srn)。驗證腳本的 OK 本身不能證明這件事。
顏色與樣式
圖表通常是在 agent 看不到的主題底下被看的,例如這個網站的深色模式,而在你自己的頁面用 siren-core 畫圖時,寫進文件裡的顏色會蓋過主題;在這個網站上則改由選定的風格或自訂主題接手(見主題)。所以 skill 要求 agent 預設不寫任何樣式,只在顏色帶有結構表達不了的意義時才加,而且加了就要在淺色和深色底上都能看:用半透明的底色(fill:#3b82f633)搭配不透明的中間色調外框,不用接近黑或接近白的顏色。它也要求 agent 不要對 subgraph 寫 style,而且 timeline 要強調的元素最多只寫底色,讓讀者看到的是強調本身。
安裝
把 skill 資料夾複製到 agent 讀取 skill 的目錄。以 Claude Code 為例:
git clone --depth 1 https://github.com/Ginz9013/siren.git
# 所有專案都能用
cp -r siren/skills/siren ~/.claude/skills/
# 只給目前這個專案用
cp -r siren/skills/siren .claude/skills/
其他支援 Agent Skills 的 agent 各有自己的 skill 目錄,位置請看該 agent 的文件。
不支援 skill 的 agent,把 siren/SKILL.md 和 siren/references/syntax.md 當成專案指示或對話的背景資料給它,一樣能用,只是它不會自己跑驗證。
skill 資料夾裡有三個檔案:
| 檔案 | 內容 |
|---|---|
SKILL.md |
撰寫流程、文件結構(含 frontmatter 和註解規則)、timeline 規則、具名 timeline、各圖表的目標 id、顏色與樣式建議、對真 Mermaid 的檢查、常見錯誤與修法 |
references/syntax.md |
六種圖表各自支援的語法(每種附一份完整範例),以及不支援的語法 |
scripts/validate.mjs |
驗證腳本 |
用起來像這樣
幫我畫一張 Siren 流程圖,說明瀏覽器的請求怎麼經過 API 到快取和資料庫。
先只顯示瀏覽器,再依序帶出 API、快取、資料庫,最後強調查詢資料庫的那條路。
agent 會交回像這樣的文件:
flowchart LR
Client[Browser] --> API[API server]
API --> DB[(Database)]
API --> Cache[(Cache)]
timeline:
enter API fade, enter Client-API fade
enter Cache slide-right, enter API-Cache fade
highlight Cache glow
unhighlight Cache, enter DB slide-right, enter API-DB fade
highlight API-DB outline
第 0 步只看得到 Client,因為其他元素都有 enter。接著依序是:API 和它的連線出現、快取出現、強調快取、資料庫出現、強調查詢路徑。
把它貼進 Playground 就能播放,也能從匯出面板匯出成 PPT。
驗證
skill 附的 scripts/validate.mjs 會用 siren-core 實際渲染文件,列出每個錯誤和警告的行號與欄位。agent 寫完文件會自己執行它;你也可以手動跑。它需要 Node.js 18 以上,並在執行的目錄裝好兩個套件:
npm install --no-save siren-core jsdom
node ~/.claude/skills/siren/scripts/validate.mjs diagram.srn --ids
diagram.srn: ERRORS (1 error(s), 0 warning(s), 5 step(s))
diagram.srn:12:3 error: timeline: references unknown id "API-Db"
ids: Client, API, DB, Cache, Client-API, API-DB, API-Cache
- 狀態是
OK就代表文件合法。 --ids會列出 timeline 能指到的所有 id,包括 Siren 自動產生的subgraph:1、note:1這類編號。圖一大,自己數很容易數錯,用它對照最準。- 傳
-會從 stdin 讀取;任何一份文件有錯誤時,結束代碼是 1。
驗證通過只代表「寫得對」,不代表「演得好」:第 0 步的畫面合不合理、步驟的順序順不順,還是要自己看過一遍。