文件 — DiagramZu

本頁內容

概念

快速開始

MCP 設定

REST API

概念

DiagramZu 設計時考量的三種工作流

審查 AI 提案

AI 提出新架構時，會在此處生成圖表。無需閱讀 600 行說明，幾秒鐘即可審核。

交接給團隊

透過一個連結共享架構。版本歷程記錄變更時間與內容 —— 現在團隊能讀，將來 AI 代理也能讀。

重複用於簡報

工程師審過的那張圖，就是 CEO 或 CPO 放進簡報的那張。一個來源，而非三個。

圖表類型

DiagramZu 背後的四個想法。讓代理人使用之前先瀏覽一下。

說明就是代理人的簡介

圖表會往返一份書面目的。檢視者在公開分享上看到它,下一個代理人在 get_diagram 上看到它。

當你的 AI 建立或更新圖表時,讓它先寫 1–2 句的說明。該說明會以頁面副標題的形式顯示給打開公開分享連結的人,也是下一個取得圖表的代理人會讀到的內容。把它當成簡介 —— 寫下「為什麼」和「是什麼」,而不是「怎麼做」。程式碼本身就是「怎麼做」。

一等公民

往返

1000 字元上限

公開分享連結

產生一個公開網址,以僅檢視方式呈現圖表給任何持有連結的人。

分享連結是 AI 創作的圖表離開 DiagramZu 的方式。連結無法猜測(22 個字元),不需登入即可使用,只顯示已渲染的圖表 —— 沒有編輯器、沒有程式碼。可以隨時從圖表的分享選單撤銷任何連結;網址會立即停止運作。可用於團隊到職文件、架構審查討論串,或 README 中的「查看範例」連結。

僅檢視

可撤銷

免登入

版本歷史

快照是手動的。你的 AI 在 update_diagram 上傳 createVersion: true,你在工具列點擊儲存版本。

沒有針對每次按鍵的自動版本控管 —— 那只會被雜訊淹沒。版本是有意識地擷取的:由人類的檢查點,或剛剛做了有意義變更的代理人。還原過去的版本時,會先寫一份當前狀態的安全快照,所以你永遠不會弄丟工作。「另存為新圖表」會把版本複製成另一個圖表,原圖表不動。

手動

還原時自動安全快照

另存為新圖表

layout: "auto"

設定 layout: "auto",確定性分類器會依據圖的形狀從六種具體配置中挑一種。

樹狀圖解析為 elk.mrtree,密集循環圖解析為 elk.force,乾淨的 DAG 解析為 dagre,以此類推。分類器在儲存時執行一次並把解析後的值持久化 —— 圖表中永遠不會儲存 "auto",所以你看到的圖是可重現的。也可以隨時從工具列明確選擇某種配置來覆寫。

一次性

6 種配置

伺服器端解析

快速開始

三步讓你的 AI 與 DiagramZu 對話。

STEP 01

註冊

建立你的空間並邀請隊友。

STEP 02

建立 API 權杖

前往 /app/settings/tokens 建立一組權杖。複製後立即保存 — 之後不會再顯示。

STEP 03

加入 AI 工具

把下方的設定貼到你的 Claude / Cursor / ChatGPT 設定檔中。

MCP 設定

DiagramZu 透過 HTTP 傳輸公開 8 個工具。安裝一次,你的代理人就能跨圖表、資料夾與版本歷史使用讀取、寫入與分析的基本能力。

安裝

Claude Code

在終端機執行下方指令，將 dz_live_xxx 替換為你的 API 權杖。

Bash

claude mcp add --scope user --transport http diagramzu https://mcp.diagramzu.ai/mcp \
  --header "Authorization: Bearer dz_live_xxx"

Claude Desktop

編輯 Claude 設定檔(macOS:~/Library/Application Support/Claude/claude_desktop_config.json,Windows:%APPDATA%\Claude\claude_desktop_config.json),然後重新啟動應用。

JSON

{
  "mcpServers": {
    "diagramzu": {
      "type": "http",
      "url": "https://mcp.diagramzu.ai/mcp",
      "headers": {
        "Authorization": "Bearer dz_live_xxx"
      }
    }
  }
}

Cursor

編輯 ~/.cursor/mcp.json 並重新啟動 Cursor。

JSON

{
  "mcpServers": {
    "diagramzu": {
      "type": "http",
      "url": "https://mcp.diagramzu.ai/mcp",
      "headers": {
        "Authorization": "Bearer dz_live_xxx"
      }
    }
  }
}

工具參考

讀取工具

list_diagrams

搜尋 Space 中的圖表。

使用時機在 create_diagram 之前呼叫以避免與同名圖表重複,或在之後呼叫以找到最新符合的項目。

範例

{
  "query": "DB schema",
  "sortBy": "updatedAt",
  "sortDir": "desc"
}

list_folders

列出 Space 中的資料夾。

使用時機當你可能把新圖表放到某個特定位置時呼叫。如果有名為「Infra」或「Schema」的資料夾,優先放在那裡而不是根目錄。

範例

{}

get_diagram

依 id 取得一個圖表,包含說明。

使用時機在決定要改什麼之前,把說明當成簡介來讀。

範例

{
  "id": "dgm_abc123"
}

list_versions

依由新到舊列出圖表的手動快照。

使用時機在有風險的覆寫之前使用,以了解有哪些還原點。

範例

{
  "id": "dgm_abc123"
}

get_version

取得圖表的一個歷史版本。

使用時機讀取過去的快照以了解圖表的演變,或還原當前版本不再具有的內容。

範例

{
  "id": "dgm_abc123",
  "versionId": "ver_xyz789"
}

寫入工具

create_diagram

在 Space 中建立圖表。

使用時機永遠先寫說明 —— 它會成為未來呼叫的代理人簡介。設定 folderId 把圖表歸入由人類管理的資料夾。

範例

{
  "title": "User signup flow",
  "description": "Auth path from /signup → verify → first login.",
  "code": "graph TD; A-->B-->C",
  "folderId": "fld_..."
}

update_diagram

更新既有圖表的標題、說明、程式碼或 styleOptions。

使用時機變更有意義時傳 createVersion: true —— 未來的你會想要一個還原點。versionLabel 會在歷史抽屜中顯示。

範例

{
  "id": "dgm_abc123",
  "code": "graph LR; A-->B-->C-->D",
  "createVersion": true,
  "versionLabel": "added retry path"
}

分析

analyze_diagram

回傳圖表的結構性評述 —— 孤立節點、高次數樞紐、循環、不相連的連通分量。

使用時機在簡化複雜圖表之前使用,或作為對生成程式碼是否產出乾淨圖的合理性檢查。

範例

{
  "id": "dgm_abc123"
}

REST API

每個請求都使用 Bearer 權杖驗證。基本網址是 https://diagramzu.ai。請把 $SPACE_ID 替換成你的空間 ID(在 app 內的網址中可看到)。

端點清單

curl · 列出

# List diagrams in your Space
curl -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams

curl · 建立

# Create a new diagram
curl -X POST -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"My diagram","code":"graph TD; A-->B"}' \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams

curl · 更新

# Update a diagram
curl -X PATCH -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"graph LR; A-->B-->C"}' \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams/<DIAGRAM_ID>

DIAGRAMS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams`	List diagrams. Same filters as list_diagrams.
POST	`/api/spaces/[spaceId]/diagrams`	Create a diagram.
GET	`/api/spaces/[spaceId]/diagrams/[id]`	Fetch one diagram.
PATCH	`/api/spaces/[spaceId]/diagrams/[id]`	Update title, code, description, or styleOptions.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]`	Delete a diagram.
GET	`/api/spaces/[spaceId]/diagrams/[id]/thumbnail`	Rendered thumbnail.
GET	`/api/spaces/[spaceId]/diagrams/[id]/analysis`	Structural analysis (same as analyze_diagram).
POST	`/api/spaces/[spaceId]/diagrams/export/png`	Render arbitrary Mermaid code to PNG.

FOLDERS

Method	Path	Description
GET	`/api/spaces/[spaceId]/folders`	List folders.
POST	`/api/spaces/[spaceId]/folders`	Create a folder.
PATCH	`/api/spaces/[spaceId]/folders/[id]`	Rename or reparent a folder.
DELETE	`/api/spaces/[spaceId]/folders/[id]`	Delete a folder.

VERSIONS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/versions`	List versions, newest first.
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions`	Snapshot the current state.
GET	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]`	Fetch one version.
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]/restore`	Restore a version (auto-snapshots first).
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]/fork`	Fork a version into a new diagram.

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/shares`	List active share links.
POST	`/api/spaces/[spaceId]/diagrams/[id]/shares`	Mint a new share link.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]/shares/[shareId]`	Revoke a share link.
GET	`/public/share/[slug]`	Public read endpoint (no auth).

TOKENS

Method	Path	Description
GET	`/api/spaces/[spaceId]/tokens`	List API tokens (no secrets).
POST	`/api/spaces/[spaceId]/tokens`	Create a token. Secret returned ONCE.
DELETE	`/api/spaces/[spaceId]/tokens/[id]`	Revoke a token.

找出你的 Space ID

登入後開啟 API 權杖頁面 — 你目前空間的 ID 會顯示在標題旁邊，可一鍵複製。