如何用 AI 智能体绘制架构图（MCP）

AI 助手很擅长把一段描述变成一张图。麻烦从第二天开始。以 PNG 形式留在聊天记录里、或以 Mermaid 片段形式留在 pull request 里的图，只是一份副本。没人会去更新副本，一个月后，它就和它所描述的系统对不上了。

Model Context Protocol（MCP）改变了智能体工作的地方。通过 MCP 连接到 Archboard 的智能体不是交给你一张图片，而是直接读取和编辑你的团队在浏览器中打开的同一张结构化图表。它的改动会实时出现在画布上，并标明它代表谁工作，而这个人可以一步撤销这些改动。

本文介绍如何把 AI 应用连接到 Archboard，用一个完整示例走一遍从初稿到评审的过程，并说明实践中要注意的提示词、权限和限制。

智能体能用 Archboard 做什么

Archboard 的图由节点包中带类型的节点组成：Kubernetes Deployment、云数据库、C4 容器或 BPMN 任务，都是带有端口和属性的节点，而不是贴着标签的方框。通过 MCP，智能体可以：

• 列出和读取它有权访问的图，形式可以是概要（框、数量、谁在编辑），也可以是完整的节点和连线记录。
• 创建图：根据一段描述、一组操作，或一张映射到真实节点类型的 Mermaid 流程图。
• 编辑图：把一批操作作为一次改动应用，包括添加节点、连接端口、移动、修改样式或删除。
• 检查自己的工作：渲染一张 PNG 快照；在支持 MCP Apps 的应用中，还能在对话里展示这张图。
• 撤销自己的某次改动。

Archboard 没有内置自己的 AI 模型。智能体由你自己提供：Claude、Cursor、VS Code，或其他能够添加带 OAuth 登录的远程 MCP 服务器的应用。AI 智能体页面有一个简短的概览。

连接你的 AI 应用

Archboard 的 MCP 服务器地址是 https://getarchboard.app/mcp。它使用 Streamable HTTP 和 OAuth，所以不需要复制任何 API 密钥。你的应用连接时，会打开 Archboard 的登录页面；你用 Google 或 GitHub 登录，然后批准应用请求的访问权限。

在授权同意页面上，你可以选择应用能使用哪些组织和工作区，以及在每一处能做什么：读取、编辑或删除（把图移到回收站）。之后你可以在 设置 > 已连接的应用 中重命名应用、更改它能使用的范围和能做的事，或移除它的访问权限。

几个常用应用的配置方法：

Claude（网页版和桌面版）。 打开 Customize > Connectors，选择 Add custom connector，然后输入 https://getarchboard.app/mcp。在 Team 和 Enterprise 方案中，需要先由 Owner 在 Organization settings > Connectors 中添加，之后你再从 Customize > Connectors 连接。

Claude Code。

claude mcp add --transport http archboard https://getarchboard.app/mcp

然后在会话中运行 /mcp 完成登录。

Cursor。 把服务器添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "archboard": { "url": "https://getarchboard.app/mcp" }
  }
}

VS Code。 把它添加到你的 mcp.json（VS Code 使用 servers 键）：

{
  "servers": {
    "archboard": { "type": "http", "url": "https://getarchboard.app/mcp" }
  }
}

其他应用。 在你的方案允许的情况下，在应用的连接器或 MCP 设置中把 https://getarchboard.app/mcp 添加为远程 MCP 服务器。应用需要支持不带客户端密钥（client secret）的 OAuth 登录；面向客户端开发者的详细说明见 MCP 文档。

完整示例：一个在线商店，从初稿到评审

下面是与一个已连接 Archboard 的智能体进行的一次会话。提示词就是你平时会输入的那种；括号里的工具名是智能体在后台调用的。

1. 先要一份初稿

为我们的在线商店画一张 C4 容器图：一个 Web 应用、一个 API、一个通过我们的邮件服务商发送订单邮件的后台 worker、一个 PostgreSQL 数据库，以及负责支付的 Stripe。把所有由我们自己运行的部分都放进一个系统边界里。

智能体会选择一个工作区（list_workspaces），查找所需的 C4 节点类型（search_node_types），然后创建图（create_diagram）。接着它会渲染一张快照（render_snapshot），检查没有元素重叠、每条连线都有标签，再在对话中展示结果（show_diagram）。

初稿只是起点。智能体是根据你的那句话选出这些容器的；除非你说明，否则它无从得知 worker 也会读取数据库。

2. 用文字修改，在画布上评审

worker 也会从数据库读取订单。在 API 和 PostgreSQL 之间加一个 Redis 缓存，并给每条连线标上协议。

智能体读取当前的图（get_canvas），然后应用一批操作（apply_ops）。如果你开着这张图，会看到新节点出现在一个标有应用名和你名字的光标旁边。开着这张图的同事也会看到同样的画面。

这是前两条提示词之后的图：

3. 撤销你不满意的改动

撤销上一次改动。

智能体的每次改动都是一步。智能体可以撤回自己的改动（revert_change），你也可以通过改动后立即出现在编辑器中的撤销提示一步撤销。在此期间被其他人修改过的字段会被保留。

4. 就现有的图提问

哪些容器和 PostgreSQL 通信？用的是什么协议？

对于这类问题，智能体只做读取（get_canvas）。向新同事讲解一张现有的图，是智能体最有用的用途之一，而且完全不需要写权限。

好用的提示词

• 说明图的类型。 “C4 容器图”“每个 namespace 一个框的 Kubernetes 图”“每个团队一条泳道的 BPMN 流程”。这样智能体会使用对应的节点包，而不是通用的方框。
• 说明每个边界里放什么。 框、namespace 和 VPC 都有含义，所以要告诉智能体什么放在哪里。
• 要求给连线加标签。 “给每条连线标上协议和端口”能把箭头变成文档。
• 让每次改动保持小规模。 每次改动只提一个请求，比整体重写更容易评审，也更容易撤销。
• 让智能体检查自己的工作。 “渲染一张快照并修复所有重叠”能在你查看之前发现布局问题。
• 要一份总结。 “列出你改了什么”能给你一段评审说明，可用于 pull request 或团队聊天。

谁能控制什么

把 AI 应用连接到团队正在使用的图，自然会引出一些合理的问题。以下是 Archboard 执行的规则：

• 范围由你决定。 应用只能看到你允许的组织和工作区，并且在那里只能做你允许的事：读取、编辑或删除。它实际能做的事，取决于这项设置、授予它的 scope、你的角色和你的方案中最严格的那一项。
• 改动可见，且能追溯到人。 智能体的光标和改动都会标明应用以及它代表的人，在画布上和版本历史中都是如此。
• 撤销只需一步。 你可以通过编辑器中的撤销提示撤销你的智能体所做的改动，也可以在 7 天内让智能体撤回。组织的所有者和管理员也可以撤销。
• 删除可以恢复。 智能体需要删除权限才能把图移到回收站，而且 Archboard 会要求智能体只在你要求时才这样做。你可以从回收站恢复图。
• 图中的文字是数据。 Archboard 会要求智能体把图中的标签、注释和名称当作数据，绝不当作指令，并且只在你要求时才添加图片。

什么时候用智能体，什么时候手绘

智能体擅长画初稿、做重复性修改（“把所有 orders-* 服务重命名为 checkout-*”）、让图跟上你本来就在做的改动，以及讲解别人画的图。刚改完某个服务的编程智能体，可以在同一个会话里更新架构图。

要决定什么重要，手绘仍然更合适。一张图是关于系统的一种论证，选择省略什么需要判断。让智能体负责敲字，判断留给你自己。

需要了解的限制

• 方案限制同样适用。 MCP 在所有方案中可用，方案限制与编辑器相同。Free 方案最多 3 张图，每张图 15 个图表节点，外加 150 个便签、文本、贴纸和思维导图主题。
• 工具调用有每分钟速率限制。 智能体触及上限时，Archboard 会告诉它需要等待多久再重试。
• 智能体只知道你告诉它的内容和图中的内容。 它无法通过 Archboard 看到你正在运行的集群或你的代码库。如果某个依赖很重要，就直接说明，或者让编程智能体去读代码。

常见问题

哪些 AI 应用可以连接 Archboard？ 能够添加带 OAuth 登录的远程 MCP 服务器、且不要求客户端密钥的应用。AI 智能体页面提供 Claude、Cursor、VS Code、Claude Code 等应用的快速设置。

Archboard 使用自己的 AI 模型吗？ 不使用。Archboard 是图表工作区；推理由你连接的 AI 应用完成。

智能体能看到我所有的图吗？ 只能看到你连接时允许的组织和工作区，权限是你为每一项选择的那一级。默认是全部，包括你以后加入的，权限为删除；你可以在授权同意页面上缩小范围，也可以之后在 设置 > 已连接的应用 中调整。

我能撤销智能体做的事吗？ 可以。智能体的每次改动都是一步，你可以通过编辑器中的撤销提示撤销；应用也可以撤回自己最近 7 天内的改动。

Free 方案能用吗？ 可以。MCP 在所有方案中可用，方案限制与编辑器相同。

免费开始 — 1 个席位，无需信用卡。