Reladraw 让你亲手调整布局，解决 Mermaid 自动排版搞不定的难题

写技术文档、架构图、时序图时，最让人头疼的是两类工具的极端：Mermaid、Graphviz 这类自动布局引擎，改个节点位置得靠改参数碰运气，稍微复杂点的拓扑结构一跑版面就崩；Draw.io、Excalidraw 这类可视化编辑器，拖拽对齐确实自由，但改一条边、增一个节点就要重新手动整理，版本管理里全是二进制 diff，CI 里根本跑不了自动化。

Reladraw 的定位很清楚：它是一个文本式图表语言，但不强制自动布局。你在代码里显式写坐标、相对位置、对齐约束，渲染器按你的指令画，想微调哪个盒子左移 20px、哪组节点强制水平对齐，改一行参数重新渲染就行。源码是纯文本，Git diff 干净，CI 里能跑快照测试，Agent 调用时也不需要解析 SVG DOM——直接生成 .rela 源码扔给 CLI 就能出图。

核心语法长这样：

// 一个简单的服务调用拓扑
service "API Gateway" as gw at (100, 50)
service "Auth Service" as auth at (100, 200)
service "User DB" as udb at (300, 200)

gw -> auth : "validate token"
auth -> udb : "lookup user"

at (x, y) 是绝对坐标；也可以用相对定位 right of gw 50、below auth 30，或者约束 align horizontal gw, auth, udb。渲染器会把这些约束当作硬性规则，不满足就报错，不会像 Graphviz 那样偷偷把节点挪到你看不见的地方。

GitHub 仓库自带一个在线 Playground（https://reladraw.com/playground），不用装东西粘贴代码就能看渲染结果。本地用法：

npm i -g @reladraw/cli
reladraw render arch.rela -o arch.svg
# 或监听模式，改源码自动刷新
reladraw watch arch.rela -o arch.svg

给 Agent 用的技能包也在仓库里（skills/claude-reladraw.json），把它塞进 Claude Desktop 的 claude_desktop_config.json 里，之后在对话里直接说「画个包含网关、认证、用户库的调用链，网关在左边，认证和用户库右边垂直对齐」，它会把 .rela 代码吐给你，你存文件跑一下就有图。

目前 0.4.2 版本支持的导出格式：SVG、PNG、PDF、Mermaid（反向导出，方便迁移旧项目）、PlantUML。不支持的：交互式拖拽编辑、实时协作、Web 组件嵌入——作者在 Issue 里明确说「不做编辑器，专注做好语言和渲染器」。

坑点提前避雷：
1. 坐标单位是像素，没有响应式缩放。导出 PNG 给 PPT 用时，得自己在代码里算好画布大小，否则 1920px 宽的图塞进 A4 会模糊。
2. 字体回退只看系统已装字体，容器里跑 CI 必须预装 fonts-dejavu-core 或 noto-fonts-cjk，否则中文会变豆腐块。
3. 循环依赖检测还没做，写 A -> B -> A 会直接死循环挂掉 CLI，得自己在生成前做拓扑排序。
4. 技能包只测过 Claude 3.5 Sonnet，GPT-4o、Gemini 1.5 Pro 能不能稳定输出合法语法没跑过基准，自己用时建议先让模型生成一段再跑 reladraw lint 校验。

适合谁：

• 把架构图、部署图、数据流图当代码管理、要进 Git、要跑 CI 的团队
• 需要让 Agent 自动生成/更新图表，但又受不了 Mermaid 乱排版的场景
• 习惯在编辑器里写文本、不想打开浏览器拖拽的工程师

不适合谁：

• 只画极简单流程图、Mermaid 已经够用的人
• 需要非技术同事也能改图的协作场景
• 要把图嵌入网页做交互（点击节点跳转、悬停 tooltip）的产品

作者在 README 里说「Reladraw 是给人和 Agent 都好用的图表语言」，目前看确实做到了「人写可读、机器生成可控、CI 可跑」三点。如果你正在把架构图纳入代码库管理、或者在折腾 Agent 自动生成技术文档，值得把 Playground 跑一遍，十分钟能判断能不能接进你的流程。