文档 — DiagramZu

本页内容

概念

快速开始

MCP 设置

REST API

概念

DiagramZu 设计时考虑的三种工作流

审查 AI 提案

AI 提出新架构时，会在此处生成图表。无需阅读 600 行说明，几秒钟即可审核。

交接给团队

通过一个链接共享架构。版本历史记录变更时间与内容 —— 现在团队能读，将来 AI 代理也能读。

复用到演示

工程师审过的那张图，就是 CEO 或 CPO 放进幻灯片的那张。一个来源，而非三个。

图表类型

DiagramZu 背后的四个想法。让代理使用前先浏览一下。

描述就是代理的简介

图表会往返一份书面的目的。查看者在公开分享上看到它,下一个代理在 get_diagram 上看到它。

当你的 AI 创建或更新图表时,让它先写 1–2 句话的描述。该描述会作为页面副标题显示给打开公开分享链接的人,也是下一个获取图表的代理所读到的内容。把它当作简介 —— 写下「为什么」和「是什么」,而不是「怎么做」。代码本身就是「怎么做」。

一等公民

往返

1000 字符上限

公开分享链接

生成一个公开 URL,以仅查看方式呈现图表给任何持有链接的人。

分享链接是 AI 创作的图表离开 DiagramZu 的方式。链接不可猜测(22 个字符),无需登录即可使用,只显示已渲染的图表 —— 没有编辑器、没有代码。可以随时从图表的分享菜单撤销任意链接;URL 会立即停止工作。可用于团队入职文档、架构评审讨论,或 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 内的 URL 中可见)。

接口列表

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 会显示在标题旁，可一键复制。