基于 Claude Project 指令生成 draw.io 图表:drawio-mcp 无 MCP 服务器方案实战指南
基于 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 定义了清晰的四步工作流:
- Claude 生成图表代码(Mermaid、XML 或 CSV 之一);
- 执行 Python 代码对图表内容进行压缩与编码;
- 脚本输出一个完整的 HTML 页面,页面中嵌入一个可点击按钮,按钮的
href指向最终的 draw.io URL; - 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 的安装步骤,配置过程共四步:
- 打开你的 Claude Project 设置(Claude.ai 中的项目配置页面);
- 将 project-instructions/claude-project-instructions.txt 的完整内容添加到项目指令中;
- 同时将 shared/xml-reference.md 的内容一并加入——这份 XML 生成参考覆盖了边缘路由(edge routing)、容器(containers)、层(layers)、标签(tags)、元数据(metadata)、暗色模式(dark mode)等完整细节;
- 此后直接请 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>""")
逐段对照仓库源码,可以确认每个步骤的底层语义:
- 百分号编码(
quote(diagram_code, safe='')):对应工具服务器 mcp-tool-server/src/index.js 中的encodeURIComponent(data)。两者都把图表原文中的特殊字符(引号、尖括号、空格等)转为安全形式,防止后续压缩/解码产生歧义; - raw deflate 压缩(
zlib.compressobj(9, zlib.DEFLATED, -15)):-15表示生成不带 zlib 头/校验和的原始 DEFLATE 流,与工具服务器使用的pako.deflateRaw(mcp-tool-server/src/index.js)完全等价——draw.io 端解析#create=参数时按同一种格式解压; - base64 编码:把二进制压缩流转为可安全放入 URL 的 ASCII 文本;
- 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 会回退到自身的默认解析配置,对大多数场景没有影响; - 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 定义了四条执行步骤:
- 用户请求图表时,先确定最佳格式(Mermaid / CSV / XML);
- 生成对应的图表代码;
- 执行 Python 脚本创建 URL;
- 把脚本输出创建为 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 毫无用处; - 转义属性值中的特殊字符:
&→&,<→<,>→>,"→"。
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 数据,重打必然损坏,哪怕只改一个字符,链接也会彻底失效。正确的处理流程是:
- 执行 Python 脚本;
- 脚本输出一个包含正确链接的完整 HTML 页面;
- 将 HTML 输出作为 artifact 呈现(其中的链接由脚本生成,必然准确);
- 在聊天消息中只告诉用户"点击 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 转义(
<→<等); - 换行用

(html=1与html=0均可用)或<br>(仅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":完整重排(ELKlayered分层布局)。顶点从你的位置移动到规范层级位置,边随布局一并路由;节点尺寸保持不变。适用于流程图、流程/状态图、决策流、流水线等方向性/层级性图表,可用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 链接协议底层机制的开发者,这条方案都值得作为首选或对照参考。