基于 Claude Project 指令生成 draw.io 图表:drawio-mcp 无 MCP 服务器方案实战指南

原创2026-10-11 22:34:491,908 阅读
文章标签:MCP 服务AI 技能AI 插件人工智能

基于 Claude Project 指令生成 draw.io 图表:drawio-mcp 无 MCP 服务器方案实战指南

本文导读:drawio-mcp 仓库除了提供标准 MCP 服务器外,还内置了一条"零安装"替代路径——通过 project-instructions/ 目录下的 Claude Project 指令,教会 Claude 用 Python 代码生成 draw.io 的 #create= 压缩链接,并以 HTML artifact 交付。本文将完整拆解这套指令的工作原理、安装步骤、Python URL 生成脚本的逐行实现、Mermaid/XML/CSV 三种格式的编写规范,并结合 mcp-tool-server/src/index.js 的源码印证其底层协议。读完本文,你将能在不安装任何 MCP 服务器、不依赖桌面应用的前提下,让 Claude 直接产出可点击打开的 draw.io 图表。

一、方案定位:无需安装 MCP Server 的替代路径

drawio-mcp 的核心交付物是 MCP 服务器(App Server 与 Tool Server),但 project-instructions/AGENTS.md 明确提出了一条不需要安装 MCP 服务器的替代方案:把指令写进 Claude Project(Claude.ai 的项目设置),让 Claude 通过执行 Python 代码来生成 draw.io URL。这套方案不依赖仓库里的任何 MCP 基础设施,本质上是"指令即能力"——把工具逻辑编译成一段可复制的提示词。

方案的核心文件只有一个:

文件 用途
project-instructions/claude-project-instructions.txt 需要粘贴到 Claude Project 设置中的完整指令文本

配套的安装说明位于 project-instructions/README.md,与 project-instructions/AGENTS.md 形成"安装向导 + 技术说明"的互补关系。

与安装 MCP 服务器相比,该方案有四个明确优势(见 project-instructions/README.md):

  • 无需安装:直接在 Claude.ai 中即可使用,没有任何依赖;
  • 无需桌面应用:完全在浏览器内工作,不要求本机安装 draw.io Desktop;
  • 易于使用:只需把指令加入 Claude Project 即可;
  • 隐私友好:生成的 URL 使用 hash 片段(#create=...),该片段始终留在浏览器中,永远不会被发送到任何服务器。

最后一点可以从源码得到印证:在 mcp-tool-server/src/index.js 中,工具服务器同样注释说明"#create= fragment never leaves the client"——无论走 MCP 通道还是本方案的 URL 通道,图表数据都只在客户端浏览器内被解析,不会上传。

二、工作原理:从图表代码到可点击链接的四步链路

project-instructions/AGENTS.md 定义了清晰的四步工作流:

  1. Claude 生成图表代码(Mermaid、XML 或 CSV 之一);
  2. 执行 Python 代码对图表内容进行压缩与编码;
  3. 脚本输出一个完整的 HTML 页面,页面中嵌入一个可点击按钮,按钮的 href 指向最终的 draw.io URL;
  4. Claude 将 HTML 作为 artifact 呈现——用户点击按钮即可在浏览器中打开 draw.io 编辑器。

这套流程的核心思想是"把易错的 URL 构造交给确定性代码,把展示交给 artifact"。Claude 本身不生成、不复制 URL 文本,只负责执行脚本和呈现输出,从而绕开了 LLM 在逐 token 复现长字符串时的高错误率(详见下一节)。

这条链路与仓库中 MCP Tool Server 的实现同构:open_drawio_xml / open_drawio_mermaid / open_drawio_csv 三个工具最终都会调用 mcp-tool-server/src/index.js 的 generateDrawioUrl(),把图表内容压缩后塞进 #create= 参数。本方案只是把这套逻辑以 Python 形式"翻译"进了 Claude 的指令里,因此协议完全一致,生成的链接可被 draw.io 直接解析。

三、为什么必须输出 HTML:base64 损坏问题

project-instructions/AGENTS.md 专门用一节解释了 HTML 输出的动机,这也是整套方案最关键的工程决策:

生成的 URL 中包含压缩后的 base64 数据。LLM 在逐 token 复现 base64 字符串时,会静默地损坏它——即使只改一个字符,链接也会彻底失效。

project-instructions/README.md 补充了同样的警告,并给出了解法:让 Python 脚本输出一个完整 HTML 页面、把链接直接嵌入其中,这样 URL 永远不会经过 Claude 的文本生成通道。Claude 只需把脚本输出原样呈现为 artifact,链接就必然是准确的。

理解这个问题的根源需要看 URL 的实际结构。以工具服务器的实现为参照(mcp-tool-server/src/index.js):

  • compressData() 先对内容执行 encodeURIComponent(百分号编码),再用 pako.deflateRaw() 做 raw deflate 压缩(即不带头部校验和的原始 DEFLATE 流),最后 base64 编码;
  • generateDrawioUrl() 把 {"type": ..., "compressed": true, "data": <base64>} 序列化为 JSON,用 encodeURIComponent 编码后拼接到 #create= 片段上,最终 URL 形如 https://app.diagrams.net/?pv=0&grid=0#create=%7B...%7D。

base64 串长度往往达到数百字符且无任何可读结构,这正是 LLM 最容易出错的地方。本方案用 zlib 的原始 DEFLATE 与工具服务器的 pako.deflateRaw 完全等价(Python 侧的 zlib.compressobj(9, zlib.DEFLATED, -15) 中 -15 即表示 raw deflate 流),保证了两条通道产出的链接在 draw.io 端可被一致解析。

四、安装配置:如何把指令加入 Claude Project

按照 project-instructions/README.md 的安装步骤,配置过程共四步:

  1. 打开你的 Claude Project 设置(Claude.ai 中的项目配置页面);
  2. 将 project-instructions/claude-project-instructions.txt 的完整内容添加到项目指令中;
  3. 同时将 shared/xml-reference.md 的内容一并加入——这份 XML 生成参考覆盖了边缘路由(edge routing)、容器(containers)、层(layers)、标签(tags)、元数据(metadata)、暗色模式(dark mode)等完整细节;
  4. 此后直接请 Claude 创建图表,它就会生成可点击的 draw.io URL。

关于第 3 步,project-instructions/AGENTS.md 特别强调 shared/xml-reference.md 是全仓库所有提示词的"单一事实来源"(single source of truth):根目录 AGENTS.md 也确认,shared/ 下的 xml-reference.md、mermaid-reference.md、style-reference.md 会被所有交付通道(App Server、Tool Server、Claude Code 插件、Project Instructions)共同消费。因此在 Claude Project 中必须把这份参考和指令文本一起复制,缺一不可。

五、图表类型与格式选择

project-instructions/claude-project-instructions.txt 明确指出 draw.io 几乎支持任意图表类型,并按领域做了归类:

  • 标准类:流程图(flowcharts)、组织结构图(org charts)、思维导图(mind maps)、时间线(timelines)、维恩图(Venn diagrams);
  • 软件类:UML(类图、时序图、活动图、用例图)、ERD、架构图;
  • 云/基础设施:AWS、Azure、GCP、Kubernetes、网络拓扑;
  • 工程类:电路图、数字逻辑、P&ID、平面图;
  • 业务类:BPMN、价值流、客户旅程、SWOT;
  • UI/UX 类:线框图、原型、站点地图;
  • 其他:信息图、数据流、决策树等。

针对不同任务,指令要求 Claude 选择最优格式:

格式 最适合的场景
Mermaid 流程图、时序图、ERD、甘特图、状态图、类图
CSV 层级数据(组织结构图)、从电子表格批量导入
XML 复杂布局、精确定位、自定义样式、图标与形状

这一选择原则与仓库根目录 AGENTS.md 的"Quick Decision Guide"完全一致:默认优先 Mermaid(覆盖大多数类型且可靠性高);需要精确位置、自定义颜色与复杂布局时用 XML;CSV 依赖 draw.io 的服务器端处理,可靠性为中等,关键图表应尽量避免。

六、URL 生成:Python 脚本逐行解析

project-instructions/claude-project-instructions.txt 提供了完整的 Python 生成脚本,这是整套方案的技术核心。以下脚本保留了原文全部逻辑,仅将 JSON 布尔值 true 修正为 Python 字面量 True 以保证可运行,并补充了关键注释:

import json, zlib, base64
from urllib.parse import quote

# 设置这两个变量:
diagram_type = "mermaid"  # "mermaid"、"xml" 或 "csv"
diagram_code = """graph TD
    A[Start] --> B[End]"""

# 生成压缩 URL
encoded = quote(diagram_code, safe='')                     # 1. 百分号编码
c = zlib.compressobj(9, zlib.DEFLATED, -15)                # 2. raw deflate 压缩
raw_deflate = c.compress(encoded.encode('utf-8')) + c.flush()
data = base64.b64encode(raw_deflate).decode()              # 3. base64 编码

payload = json.dumps({"type": diagram_type, "compressed": True, "data": data})
url = f"https://app.diagrams.net/?pv=0&grid=0#create={quote(payload, safe='')}"

# 以 HTML 页面形式输出
print(f"""<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
  body {{
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    margin: 0;
    background: #f8f9fa;
  }}
  .card {{
    text-align: center;
    background: white;
    border-radius: 12px;
    padding: 40px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  }}
  .card h2 {{
    margin: 0 0 8px;
    color: #1a1a1a;
  }}
  .card p {{
    margin: 0 0 24px;
    color: #666;
  }}
  .btn {{
    display: inline-block;
    padding: 14px 32px;
    background: #4285f4;
    color: white;
    text-decoration: none;
    border-radius: 8px;
    font-size: 16px;
    font-weight: 500;
    transition: background 0.2s;
  }}
  .btn:hover {{
    background: #3367d6;
  }}
</style>
</head>
<body>
  <div class="card">
    <h2>Diagram Ready</h2>
    <p>Click below to open your diagram in draw.io</p>
    <a class="btn" href="{url}" target="_blank" rel="noopener noreferrer">
      Open in draw.io
    </a>
  </div>
</body>
</html>""")

逐段对照仓库源码,可以确认每个步骤的底层语义:

  1. 百分号编码(quote(diagram_code, safe='')):对应工具服务器 mcp-tool-server/src/index.js 中的 encodeURIComponent(data)。两者都把图表原文中的特殊字符(引号、尖括号、空格等)转为安全形式,防止后续压缩/解码产生歧义;
  2. raw deflate 压缩(zlib.compressobj(9, zlib.DEFLATED, -15)):-15 表示生成不带 zlib 头/校验和的原始 DEFLATE 流,与工具服务器使用的 pako.deflateRaw(mcp-tool-server/src/index.js)完全等价——draw.io 端解析 #create= 参数时按同一种格式解压;
  3. base64 编码:把二进制压缩流转为可安全放入 URL 的 ASCII 文本;
  4. payload 结构:{"type": ..., "compressed": true, "data": ...} 与工具服务器 createObj 的字段一一对应(mcp-tool-server/src/index.js)。对于 Mermaid 类型,工具服务器还会额外写入 version: "12"(MERMAID_DEFAULTS_VERSION,见 mcp-tool-server/src/index.js)以对齐 draw.io 内置解析器的 Mermaid 默认版本——指令脚本里没有这个字段,draw.io 会回退到自身的默认解析配置,对大多数场景没有影响;
  5. URL 组装:?pv=0&grid=0#create=... 中 pv=0(隐藏页面视图切换按钮)、grid=0(关闭网格)与工具服务器的参数一致(mcp-tool-server/src/index.js)。工具服务器还支持通过 dark=1 强制暗色模式、lightbox=1 只读模式、自定义 border 与 edit 行为,且 DRAWIO_BASE_URL 环境变量可覆盖默认的 https://app.diagrams.net/(mcp-tool-server/src/index.js)——指令脚本写死了默认地址,实际使用中无需改动。

重要提示:脚本输出的 HTML 只是"承载链接的容器",Claude 必须把整个 HTML 作为 artifact 呈现,绝不能把 url 变量打印到聊天文本里。这正是上一节阐述的 base64 防损坏机制。

七、三种格式的编写示例

7.1 Mermaid

Mermaid 是默认推荐格式,draw.io 的 Mermaid 解析器会在转换时自动完成布局。基础流程图为:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

更复杂的写法(含子图、节点形状、连线样式)可以参考 shared/mermaid-reference.md,其中包含流程图方向(TD/TB/BT/LR/RL)、节点括号形状、subgraph 子图、style/classDef/linkStyle 三种样式方案,以及复杂流程图(约 20 节点以上、3 个以上决策菱形、存在回边或 3 个以上终点)时切换 ELK 分层布局的建议。

7.2 XML(draw.io 原生格式)

<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Box" style="rounded=1;fillColor=#d5e8d4;" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

XML 是唯一能精确控制位置、样式与形状库的方案,也是 shared/xml-reference.md 的核心讲解对象(详见第十一节)。编写时务必遵守良构性规则(见第九节)。

7.3 CSV(层级数据)

# label: %name%
# style: rounded=1;whiteSpace=wrap;html=1;
# connect: {"from":"manager","to":"name","invert":true}
# layout: auto
name,manager
CEO,
CTO,CEO
CFO,CEO

CSV 格式通过 # 开头的头部指令声明标签字段(%name% 引用列名)、默认样式、连线规则与自动布局,最适用于组织结构图这类纯层级数据。但需注意一个已知陷阱:根目录 AGENTS.md 明确警告,不要在样式属性中使用 %column% 占位符(例如 fillColor=%color%),否则 draw.io 的 CSV 服务器端处理会抛出 "URI malformed" 错误。头部指令中的 %列名% 引用(如 # label: %name%)是合法用法,两者并不冲突。

八、完整生成流程 Instructions

project-instructions/claude-project-instructions.txt 为 Claude 定义了四条执行步骤:

  1. 用户请求图表时,先确定最佳格式(Mermaid / CSV / XML);
  2. 生成对应的图表代码;
  3. 执行 Python 脚本创建 URL;
  4. 把脚本输出创建为 HTML artifact——这是给用户的可点击链接。

在真实对话中,这四步会在一次请求内连续完成,用户最终看到的是一张带 "Open in draw.io" 按钮的卡片,点击即跳转编辑器,无需接触任何 URL 文本。

九、关键规则一:XML 良构性(CRITICAL)

生成 draw.io XML 时,输出必须是良构(well-formed)的 XML,project-instructions/claude-project-instructions.txt 为此立了两条硬性规则:

  • 严禁在输出中包含任何 XML 注释(<!-- -->)。XML 注释被严格禁止——它们浪费 token、可能引发解析错误,且对图表 XML 毫无用处;
  • 转义属性值中的特殊字符:& → &amp;,< → &lt;,> → &gt;," → &quot;。

shared/xml-reference.md 在此基础上补充了更细致的良构性要求:每条边(edge)的 mxCell 必须包含 <mxGeometry relative="1" as="geometry" /> 子元素(自闭合的 edge cell 无效、无法正确渲染);所有 id 必须唯一;mxCell id="0"(根容器)与 id="1"(默认层)两个结构性单元格必须始终存在。违反任何一条都可能导致图表空白或渲染错乱。

十、关键规则二:URL 输出纪律(CRITICAL)

这是整套方案中 Claude 最容易违反、也最致命的一条:

绝不在聊天回复中键入、重打或复现生成的 URL。

理由与第三节相同:URL 包含压缩后的 base64 数据,重打必然损坏,哪怕只改一个字符,链接也会彻底失效。正确的处理流程是:

  1. 执行 Python 脚本;
  2. 脚本输出一个包含正确链接的完整 HTML 页面;
  3. 将 HTML 输出作为 artifact 呈现(其中的链接由脚本生成,必然准确);
  4. 在聊天消息中只告诉用户"点击 artifact 中的按钮"即可。

不要把脚本输出中的 URL 复制进回复正文——artifact 本身就是链接的交付载体。这条纪律与"为什么输出 HTML"的设计动机闭环呼应:Claude 永远不碰 URL 文本,损坏就没有发生的可能。

十一、进阶:XML 生成参考核心速览

project-instructions/AGENTS.md 明确指定 shared/xml-reference.md 为所有提示词的 XML 权威参考,用户需将其内容与指令文本一并复制进 Claude Project。这份参考的核心内容可归纳为以下几点:

11.1 推理预算与刚性网格

参考文件开篇定义了"推理预算"(reasoning budget):Claude 的职责是声明图表的逻辑结构(节点、连线、标签、容器分组),而非做布局数学。为此提供了刚性网格规则,直接套用即可:

  • 列坐标 x = col_index * 180 + 40(第 0 列 = 40,第 1 列 = 220,第 2 列 = 400,依此类推);
  • 行坐标 y = row_index * 120 + 40(第 0 行 = 40,第 1 行 = 160,第 2 行 = 280,依此类推);
  • 节点尺寸:矩形 140×60、菱形 140×80、圆形 60×60、文档 120×80、圆柱 100×70。

同时明确禁止:手算坐标、添加 <Array as="points"> 路径点、设置 exitX/exitY/entryX/entryY 连接点覆盖、放置节点后回查坐标、用文字叙述"正在构建图表"。每个节点必须独占一个 (col, row) 格位,两个节点放同一格会重叠。

11.2 常见样式与样式属性表

三种最常用的单元格样式:

<!-- 圆角矩形 -->
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>

<!-- 菱形(决策) -->
<mxCell id="3" value="Condition?" style="rhombus;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="100" y="200" width="120" height="80" as="geometry"/>
</mxCell>

<!-- 箭头(边) -->
<mxCell id="4" value="" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" source="2" target="3" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

shared/xml-reference.md 的核心样式属性速查表:

属性 取值 用途
rounded=1 0 或 1 圆角
whiteSpace=wrap wrap 文本自动换行
fillColor=#dae8fc Hex 颜色 背景色
strokeColor=#6c8ebf Hex 颜色 边框色
fontColor=#333333 Hex 颜色 文字颜色
shape=cylinder3 形状名 数据库圆柱
shape=mxgraph.flowchart.document 形状名 文档形状
ellipse 样式关键字 圆形/椭圆
rhombus 样式关键字 菱形
edgeStyle=orthogonalEdgeStyle 样式关键字 直角连接线
edgeStyle=elbowEdgeStyle 样式关键字 弯肘连接线
dashed=1 0 或 1 虚线
swimlane 样式关键字 泳道容器
group 样式关键字 不可见容器(pointerEvents=0)
container=1 0 或 1 让任意形状具备容器行为
pointerEvents=0 0 或 1 阻止容器捕获子元素的连线
html=1 0 或 1 标签中启用 HTML 渲染(<b>、<br>、<font> 等必需)
shape=umlLifeline;perimeter=lifelinePerimeter;size=16 shape UML 时序图生命线(size = 头部高度)

11.3 HTML 标签与文本格式

  • 当 value 包含任何 HTML 标签时,样式必须带 html=1,否则标签会以字面文本显示;
  • 属性值中的 HTML 必须做 XML 转义(< → &lt; 等);
  • 换行用 &#xa;(html=1 与 html=0 均可用)或 &lt;br&gt;(仅 html=1),绝不能用 \n,它会被渲染成字面的反斜杠-n 文本;
  • 整段标签加粗/斜体/下划线用 fontStyle(1=加粗、2=斜体、4=下划线,可位或组合,如 fontStyle=3 即加粗+斜体);仅部分文本需要格式化时再用 HTML 标签,且二者不要混用。

11.4 边与路由

  • 边只需声明 source 和 target,不要手绘路由(不加 <mxPoint> 路径点、不设 exitX/exitY/entryX/entryY);
  • 默认的 draw.io 内置路由器是"基础型":直线或简单直角路径,不做避障——连线会径直穿过端点之间的任何形状。当边会穿越其他形状、或希望获得干净的绕障正交走线时,使用 routing: "libavoid";希望整图重排时使用 postLayout: "elk"(详见下文);
  • 边样式按图统一选择:ER 图用 entityRelationEdgeStyle,UML 类图用直线,思维导图用 curved=1,流程图/架构图/网络图用 orthogonalEdgeStyle;
  • 边标签(value)保持 1~3 个词的简短语义(Yes、async、reads),不加冗余说明。

11.5 容器、泳道与嵌套架构

三类容器(详见 shared/xml-reference.md):

类型 样式 适用场景
Group(不可见) group; 无需边框、容器本身无连接
Swimlane(带标题) swimlane;startSize=30; 需要可见标题栏,或容器自身可被连接
自定义容器 任意形状 + container=1;pointerEvents=0; 形状充当容器且自身无连接

子元素通过 parent="容器id" 挂载,坐标相对于容器。嵌套架构(VPC → AZ → EC2 实例、数据中心 → 机架 → 服务器)每层都用 swimlane;startSize=24; 容器表达,且遵循一条铁律:一条边必须归入同时容纳其两个端点的最内层容器——两个端点都在同一子网则归该子网;一端在容器外则 parent="1"。自动布局按边的父级坐标系读取坐标,文件层级放错会导致边落在错误位置。

跨职能流程图(actor × phase 网格)应使用 draw.io 的 table 形状(shape=table;childLayout=tableLayout;),由 tableLayout 自动平铺行列,跨单元格的边同样用 parent="1"。

11.6 层(Layers)

层控制可见性与 z 序:id="0" 是根、id="1" 是默认层,二者恒存在;附加层是 parent="0" 且不带 vertex/edge 属性的 mxCell。把形状的 parent 设为某层 id 即归入该层,后定义的层渲染在更上层,visible="0" 可默认隐藏某层。适合"物理基础设施 / 逻辑网络 / 安全区域"这类可切换的视觉分组。

11.7 标签(Tags)与元数据/占位符

  • 标签(Tags)是多对多的可见性过滤器(一个元素可有多个标签),必须把 mxCell 包裹在 <object> 元素中,通过 tags="critical v2" 空格分隔赋值;<object> 的 label 属性取代 mxCell 的 value。纯 mxCell 无法携带标签;
  • 元数据(Metadata)是在 <object> 上附加任意自定义属性(如 owner="Team Backend"),配合 placeholders="1" 可在标签中做 %属性名% 替换,适合显示服务器状态、负责人、IP 等数据驱动信息;预定义占位符(%id%、%date%、%page% 等)无需自定义属性即可使用,%% 输出字面百分号。

11.8 暗色模式

draw.io 支持自动暗色渲染:strokeColor/fillColor/fontColor 默认值为 "default"(浅色主题渲染为黑、暗色主题渲染为白);显式颜色在暗色模式下由 mxUtils.getInverseColor 自动反色(RGB 向反色方向混合 93% 并旋转色相 180°);需要同时指定两套颜色时用 light-dark(浅色,暗色) 函数。启用条件:mxGraphModel 必须带 adaptiveColors="auto"。多数场景无需手动指定暗色值,自动反色已够用。

11.9 边缘路由与布局 Pass:libavoid 与 ELK

两条可选的后处理通道(详见 shared/xml-reference.md):

  • routing: "libavoid"(仅 XML):避障式正交边路由。顶点位置完全不变,只重算连接线,让连线以干净直角绕开形状、并行线段自动散开。适用于精心手工布局的架构图、网络拓扑、部署图、UML、平面图;
  • postLayout: "elk":完整重排(ELK layered 分层布局)。顶点从你的位置移动到规范层级位置,边随布局一并路由;节点尺寸保持不变。适用于流程图、流程/状态图、决策流、流水线等方向性/层级性图表,可用 direction 指定垂直(默认)或水平。

四种组合的效果:

postLayout routing 结果
— — 基础内置路由器(直线/简单直角,无避障);保留你的位置
— libavoid 保留位置;连线绕障正交重排
elk — ELK 摆放顶点并路由边(自带较好路由)
elk libavoid 基本无必要——ELK 已路由,仅当 ELK 路由效果特别差时叠加

两者本质是二选一而非叠加:稀疏布局用默认路由器即可;保留手工布局但整理连线用 libavoid;需要规范重排用 elk(不要同时设置 routing)。当用户指定了精确位置(泳道、有空间语义的架构图)或布局本身编码了信息时,不要使用 postLayout。

十二、编码规范

project-instructions/AGENTS.md 声明了仓库统一的代码风格,适用于 Claude Project 方案中涉及的任何代码产出:

  • Allman 大括号风格:所有控制结构、函数、对象、回调的开括号独占一行;
  • 回调优先使用 function() 表达式而非箭头函数;
  • 完整示例见仓库根目录 AGENTS.md。
function example()
{
  if (condition)
  {
    doSomething();
  }
  else
  {
    doOther();
  }
}

十三、故障排查与常见错误

结合 project-instructions/claude-project-instructions.txt 的硬性规则与根目录 AGENTS.md 的排查表,常见问题及对策如下:

错误 原因 解决方案
输出中出现 XML 注释 生成的 XML 里带 <!-- --> 删除所有 XML 注释——这是严格禁止项
"URI malformed" CSV 样式属性中使用特殊字符 用硬编码颜色代替 %column% 占位符
"Service nicht verfügbar" draw.io 的 CSV 服务器不可用 稍后重试,或改用 Mermaid
空白图表 Mermaid/XML 语法无效 检查语法,确保特殊字符正确转义
图表与预期不符 Mermaid 版本差异 简化语法,避免边缘写法

结语

drawio-mcp 的 project-instructions/ 目录提供了一条与 MCP 服务器完全解耦的交付路径:把 project-instructions/claude-project-instructions.txt 与 shared/xml-reference.md 复制进 Claude Project,Claude 即可通过 Python 代码生成 draw.io 的 #create= 压缩链接,并以 HTML artifact 安全交付。其核心工程智慧在于"让确定性代码构造 URL,让 artifact 承载 URL,让 LLM 远离 URL 文本"——这一设计与 mcp-tool-server/src/index.js 中 compressData/generateDrawioUrl 的协议完全同构,既保证了链接 100% 准确,又维持了数据不出浏览器(hash 片段)的隐私特性。无论你是无法安装 MCP 环境的轻量用户,还是想理解 draw.io 链接协议底层机制的开发者,这条方案都值得作为首选或对照参考。

登录后查看全文
drawio-mcp