diagonaldiagrams

diagonaldiagrams

diagonaldiagrams 是一个 Python 库和 MCP 服务，可让 AI Agent 将图表和图形绘制为 SVG，并在展示之前检查是否存在文本重叠、箭头穿过方框或文本溢出等问题。

网站：录制示例、基准测试和图库。

工作原理

1. 描述。 Agent 用 Mermaid、JSON 或 CSV 编写简短的图形描述。
2. 绘制。 diagonaldiagrams 排版并保存为 SVG。
3. 检查。 它会审核图形并输出一行 JSON：要么一切正常，要么说明问题所在及修复方法。Agent 读取这一行，而不是截图。

$ diagonaldiagrams mermaid flow.mmd -o flow.svg
{"ok": true, "svg": "flow.svg", ..., "items": 3,
 "layout": ["row 1: Start", "row 2: Ready? (decision)", "row 3: Done"]}

当 ok 为 false 时，每个错误都会附带一个 fix。

安装

需要 Python 3.11 或更高版本。

命令行

pip install diagonaldiagrams

MCP（Cursor、Claude Desktop 和其他 MCP 应用）。将以下内容添加到应用的 MCP 设置中；这需要 uv。该服务已在官方 MCP 注册表中登记为 io.github.lucas19919/diagonaldiagrams。

{
  "mcpServers": {
    "diagonaldiagrams": { "command": "uvx", "args": ["diagonaldiagrams", "mcp"] }
  }
}

Claude Desktop 也可以打开最新版本中的 .mcpb 文件。

Claude Code

/plugin marketplace add lucas19919/diagonaldiagrams
/plugin install diagonaldiagrams@diagonaldiagrams

其他 Agent： 告诉它 Install diagonaldiagrams from https://github.com/lucas19919/diagonaldiagrams。它会按照安装技能进行安装，然后使用绘图技能绘图。供模型使用的简短版本见 llms.txt。

可绘制内容

命令	输入	绘制内容
mermaid	flowchart、sequenceDiagram、erDiagram	流程图、时序图或架构图
flow、arch、seq、schema	JSON	根据规范绘制上述四种图
iso	JSON	以等距 3D 形式绘制层叠结构，并显示层间链接
bar、line、scatter	CSV	对比、趋势或关系图
geo	CSV 或 GeoJSON	在内置海岸线上标出地点
chart <type>	CSV 或 JSON	约 60 种其他图表

• describe <type> 会输出任意图形类型的规范格式。
• --fit column 会将图形调整为适合 README 或文档页面的大小。默认值为 slide，打印时使用 page。
• story 会将一个图形转为同一页面上的多个视图；安装 ffmpeg 后，--gif 可将其录制为动画。
• apply 使用 JSON 补丁编辑规范；export 可导出 PNG、PDF、draw.io 或 Excalidraw 文件。

对比

于 2026-10-19 使用版本 0.8.0，对 Mermaid CLI 和 Pele 进行测量，测试对象是相同的 4 个包含 5 到 40 个步骤的流程图。

• 速度。 一个包含 20 个步骤的流程图耗时 152 ms，比 Mermaid CLI（2,340 ms）快约 15 倍，比 Pele（101 ms）慢约 1.5 倍。
• Token 数。 在各种尺寸下，Agent 每张图使用 4.4k 到 6.4k 个 Token。对于 5 到 20 个步骤的图，Pele 和 Mermaid CLI 使用更少（1.3k 到 4.0k）。对于 40 个步骤的图，diagonaldiagrams 使用 6.4k，Pele 使用 6.3k，Mermaid CLI 使用 15.4k。这是两次运行的结果，因此样本量较小，仅供参考。
• 质量。 在盲测对比中，对于适合幻灯片尺寸的图，diagonaldiagrams 被认为比 Pele 更清晰的比例为 85%，比 Mermaid CLI 更清晰的比例为 97%。它在架构图从 Mermaid 转换而来且尺寸适合窄栏的情况下表现较差：与 Pele 对比，8 次中 0 次胜出。

完整表格、测试方法和重跑测试所需的脚本见 bench/。

开发

python -m unittest discover tests/unit   # unit tests
python tests_smoke.py                    # the command-line contract
python scripts/golden.py                 # the reference figures, byte for byte

引擎的组成方式见：docs/ARCHITECTURE.md。发布方式见：PUBLISHING.md。

许可证

MIT。参见 LICENSE。