一种用于图表的文本语言，由你指定元素摆放位置。reladraw（reladraw）可在浏览器中试用，左侧编辑源码，右侧布局重新求解，无需安装。一张手绘的图表，以及用 reladraw 写就的相同图表从文本渲染而出，含 44 条语句，通篇无坐标。第二张图中每段距离都依据诸如 above-left of cluster.hub 与 between cluster.desktop1 and cluster.laptop1 的语句算出。没有任何事物选择排布，是文件陈述了它。

一种用于画图的文本语言，由你来决定东西放在哪里。

在浏览器里试试 → —— 左边改源码，右边看重新排版。无需安装。

在 draw.io 里手画的图：

用 reladraw 写出来并从文本渲染的同一张图 —— examples/arch.reladraw，44 条语句，全篇无坐标：

第二张图里每个距离都从诸如 above-left of cluster.hub 和 between cluster.desktop1 and cluster.laptop1 这样的语句算出来。没有东西去选布局；是文件规定的。

缺口

Mermaid、Graphviz 和 D2 让你声明实体和连接，然后替你排布一切。这是超能力，对大多数图都合适。但一旦你心里有特定画面、在意东西放哪，就不合适了。比如你正通过画图搞清一个系统，想让某模块放右边、连接也恰到好处：自动布局语言没法说这话。

另一端是绝对定位工具 —— draw.io、Excalidraw、Figma。它们给你完全控制，代价是改复杂图时全是慢手活。人对来说慢，对智能体更费：它得先从坐标倒推画面，才能决定改哪些数。

reladraw 瞄准中间地带。每个位置都相对于别的东西陈述，文件里没有任何坐标：比如写 node app "Web app"，node app.ui "Interface"，node app.api "API" below app.ui；node store "Database" right of app level with app；edge app.api -> store "queries" from: right to: left。没有嵌套，所以任一行不依赖另一行位置或缩进。

语法草案在 SYNTAX.md，完整例子在 examples/。

为什么智能体需要这个

常见情况不是画图，是改图。让认证服务左移、队列去它后面。用像素坐标，智能体得先从数字重建画面才能改哪些数。用自动布局则根本没东西可读，因为布局从没写下来 —— 只能改写源码再渲染。用陈述式布局，排布作为句子在文件里，改图就是改那句说东西放哪的话。

写图也一样。智能体吐 Mermaid 是在猜算法稍后才定的布局，它唯一弄清的办法是渲染看一眼 —— 绕一圈回来的是图片而不是错在哪的清单。

意图可确认，结果不可确认，这区别得讲精确。智能体能重读自己的文件，看到数据库在 API 下、四台机器挂在同步中枢上。它看不到两个锚定不同东西的集群现在重叠了、文字溢出节点、或一条边穿了其他四条边 —— 这些是从语句推导出来的而非写明的，所以需要下面范围章节里的诊断功能。

和智能体一起使用

reladraw 太新，没进任何模型训练数据，所以得先教智能体这语言它才会写。这个仓库带了一个 agent skill，干的正是这个 —— 语法、何时用这语言、重读自己源码能确认和不能确认什么。

运行 npx skills add reladraw/reladraw -g 会装到你用的智能体（Claude Code、Codex、Cursor、Copilot 等）各自技能目录。去掉 -g 就装到当前项目。只装一个智能体就加 -a，如 npx skills add reladraw/reladraw -g -a claude-code。语法更新后重跑命令，因为技能是安装时拷贝的，不是动态链接，不会自己刷新。

它是 纯 Markdown，旁边有语法参考，值得读，手动拷目录也一样。

状态

版本 0.5.0。早但能跑：TypeScript 写的解析器、求解器和 SVG 渲染器，无运行时依赖，还有命令行工具读文本写独立 SVG。本页顶部对比就是对该文件的流水线。明显不对的地方是排版不是位置。

全局安装用 npm install -g reladraw，然后 reladraw diagram.reladraw -o diagram.svg。从克隆装见 npm install && npm run build 和 node dist/cli.js examples/arch.reladraw -o out.svg，还能拿例子。

还没做（按缺失感排序）：

• 诊断报告。下面范围节说了用途。现在工具要么渲染要么报错，不会告诉画成功的图哪里不对。
• 绕开节点的边路由。边能指定从节点哪边出、哪边进、沿哪条缝走。没指定的边是两点中心直线，会切穿挡路的东西。
• 更多图形。图标形状是工具内路径数据画的封闭集，图里想要没有的就无处可去。

语言不稳定，语法会改。

工作原理

间距是最小距离，不是精确距离。两个并排，第三个插中间，前两个被正好推开第三所需的距离；删了第三个它们又合拢。这是作者平时手做的步骤 —— 挪开腾地，再拖回来免得图全是洞 —— 而文字变长时不会有过时的数。

所以求解器解系统而不是走链条。每轴是一组最小距离，满足全部的最紧凑排布用最长路径找出来：一个答案，不搜索，不试错。引擎算距离；东西在啥的哪边来自文件。

这也让防重叠便宜，无需任何人写就对所有节点对成立。单说“这两不能重叠”是四个方向里选，是本设计拒掉的搜索 —— 但文件通常已定下：若排布让一节点能离另一节点远去且回不来，那就只允许那种分隔。文件没在任何轴定序时，工具指名而非猜；两轴都定时，平局倾向重叠最小的轴，即最小移动，也是工具唯一自作主张处。

绝不微调。每轮推导出文件已暗示的分隔，加为普通最小距离，从头再解全盘 —— 要避免的正是原地修已解布局。

第一版的范围

• 解析器（完成）
• 确定性求解器：入最小距离，出最紧排布（完成）
• 静态 SVG 渲染器（完成）
• 命令行工具：文本进 SVG 出（完成）
• 能说真实图所需关系的布局文法：单节点多位置、两物间插一物、精确侧对齐（完成）
• 默认不重叠节点，分隔方向由陈述排布推导（完成）
• 最小避节点边路由
• 从解出的几何出机器可读诊断

诊断是实在输出而非调试辅助。它不能替代文法：检查只抓语言真留白的地方，“不能重叠”排除排布却不指名，所以永远无法摆放。几何一解，源说不清的全可算且无图参与：重叠节点、交叉边、文字超框、出画布、大块空白。所以工具报 hub overlaps laptop1 和 edge auth->db crosses 4 edges，修复用和源一样的话。智能体这样干活是读自己写的文本文件报告然后改那文件 —— 不渲染、不视觉模型、不像素算术。

诊断绝不原地修已解布局。这是设计守住的线：允许微调节点的检查器是搜索策略烂的布局算法，修一个重叠出下一个且无全局观。推导文件已暗示的约束再解全盘是另一回事，防重叠就这么干。剩下的 —— 源真没定的 —— 报出来，指名破了的语句，作者改源。开放问题是：诊断能用文字描述修法还是只指症状？描述修法意味着工具对布局有主张，即自动布局本能从侧门回来了。

三个设计问题决定要多大机制，第一个压过另两个：

说得够。基准里有文法根本表达不了的排布，所以有些节点放错地方。因此活是加语句不是限语句。表现力不危险；引擎选排布才危险。

引擎能决定啥。拒自动布局，因为算法选的图不可从源预测，而可预测正是全部意义。从作者陈述的排布算坐标是另一回事，就是本职。分界测试：引擎自由可影响距离不可影响关系。若默认能改节点在啥的哪边，就是语言少句了，工具应说明而非猜。

重叠与边路由。默认间距的相对放置，两集群相向长大就撞。先定位置再路由边且边不影响位置，正好重现本要避的失败，所以最小避节点正交路由属第一版。路由和诊断互补不替代：路由修能修的，诊断报修不了的。

前人的工作

四样东西挨着，各答问题一面。

Archify。为智能体写而建：吐类型化 JSON，校验器按 schema 查并 lint 布局，确定性编成好看自含 HTML，带步进播放和绑 git 核实源码行的节点。但定位是网格或自由坐标 —— 一边自动一边绝对像素 —— JSON 模板不谈图落哪，所以循环仍是吐、渲、看、调。

PIC 和 pikchr。无布局引擎的文本图格式，位置陈述且确定。但它是乌龟制图 —— 可动光标丢形状一步步走 —— 图是落笔序列而非命名物间关系集。没加成员会重排的组。

Graphviz rank 和 cluster。是对自动布局引擎的约束不是替换，所以输出仍涌现不可测。

Structurizr。有真手动布局，但绑 C4 模型，成了带渲染的建模记法而非通用放置语言。

许可证

Apache-2.0。这是采用即价值的复用基元，限商用违背目的。见 LICENSE。

许可覆盖代码不覆盖名：不授使用权给“reladraw”、项目 logo 或其他标。欢迎 fork 但用别名。见 NOTICE。

贡献

欢迎提 issue —— 尤其你试着写却写不出的图。PR 会读但暂不并，原因见 CONTRIBUTING.md。

社区普遍对这款摆脱 Mermaid 排版痛苦、采用相对定位的图表工具感到兴奋与欢迎，少数人则主张应直接扩展 Mermaid 或担忧依赖与渲染后端整合。

认为新工具解决了 Mermaid 的流程图定位痛点

• 不少用户受够 Mermaid 在流程图位置和格式差异上的挫败，认为该工具的相对定位思路能替换临时半成品实现（较多人） > 和 Mermaid 斗争太挫败了，尤其普通与 GitHub 格式差异，这会替换我手上几个临时半成品（@monster_truck）

认为应直接扩展 Mermaid 而非造新语言

• Mermaid 本身开源，部分人觉得将布局约束加入现有生态比新语言更合理，且代理常 hack Mermaid 或直接用 SVG，集成更优（少数人） > 既然 Mermaid 开源，我们能否把这些布局约束加进去而不是搞整套新语言？（@wrs）

认为本质是无 LaTeX 的 tikz 定位库但边路由待解

• 工具类似 tikz 定位库但免 LaTeX，然而 tikz 的痛点在于边而非节点，多条边争同侧会丑，用户关心解析器是否做路由及冲突处理（少数人） > 这基本是 tikz 的定位库而不用碰 LaTeX，但边才是痛处，解析器做路由吗还是只有起止，冲突时谁赢？（@lastscattering）

希望补充主题或实现 tikz 般强大简单

• 用户期待不同主题美化，或希望它实现不带 LaTeX 的 tikz 以兼顾简单与深度，目前未见过更好绘图库（较多人） > 希望它实现 tikz 却不带 LaTeX，还没见过既简单又能建最复杂图形的更好的库（@lighthue1）

建议布局指令转绝对位置以适配多后端

• 质疑是否需捆绑渲染器，提出节点布局最终翻译为绝对坐标，可针对任意渲染后端保持接口简单（少数人） > 更好的问题是布局指令最终是否转成绝对位置，这样能针对任意渲染后端避免生态问题（@threecheese）

发现早期可用性问题需完善

• 个别用户测试发现边不能智能弯曲，或表示需细读语法确认能力（少数人） > 加了一行边定义，但它不够聪明做曲线箭头（@recroad）

有价值的补充

• 有开发者让 AI 写 dot 图脚本，发现 AI 在布局难题上和人类手动操作犯同样错误（@aktenlage）
• Mermaid 在序列图、甘特图等固定布局表现好，但流程图位置为王时差，SVG 在文档中易笨重，相对定位反思后可能够用（@HeavyStorm）
• 类似工具已有 Pikchr 与 d2lang，可作为参照（@v9v、@zikohh）
• 有用户认为若用更少依赖的语言实现会更棒（@einpoklum）