Show HN: Reladraw – A diagram language where you decide where to place things

GitHub - reladraw/reladraw · GitHub

reladraw

一种用于图表的文本语言，您可以指定元素的位置。

在浏览器中尝试 → — 在左侧编辑源代码，右侧会实时更新布局。无需安装任何软件。

在 draw.io 中手绘的图表：

以及用 reladraw 描述并从文本渲染出的相同图表 —— examples/arch.reladraw ，44 条语句，整个文件中没有任何坐标：

第二张图中的所有距离都是根据类似 "位于 cluster.hub 的左上方" 和 "cluster.desktop1 与 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 太新，尚未被任何模型的训练数据收录，因此必须先告知代理该语言，才能使用它。本仓库提供了一个代理技能，可实现这一功能——它包含语法、何时使用该语言，以及重新阅读自身源代码能确认和无法确认的内容。

npx skills add reladraw/reladraw -g

这会将该技能安装到你使用的任意代理中——Claude Code、Codex、Cursor、Copilot 等——每个代理都会安装到自己的技能目录中。若省略 -g 参数，则会将技能安装到当前项目目录中。

若只想为某个特定代理安装，可使用 -a 参数指定代理名称：

npx skills add reladraw/reladraw -g -a claude-code

在语法发生变更的版本发布后，需要重新运行对应的安装命令。该技能是安装时的静态副本，而非实时链接，因此不会自动刷新。

它采用纯 Markdown 格式，并附有语法参考，因此无论使用哪个工具都值得阅读。手动复制目录同样可以正常工作。

状态

版本 0.7.1。处于早期阶段，但已能运行：包含 TypeScript 编写的解析器、解析器和 SVG 渲染器，无运行时依赖，还有一个命令行工具，可读取文本文件并生成独立 SVG。本页顶部的对比示例即使用该工具对 examples/arch.reladraw 进行处理。目前仍可见的差异在于字体排版，而非元素位置。

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，验证器将其与模式进行校验并检查布局，最终确定性地编译为美观且自包含的 HTML 文件，支持分步回放并能将节点固定到 Git 验证的源代码行。但其定位方式为网格或自由坐标——一侧是自动排列，另一侧是绝对像素定位——JSON 模板对图像最终位置没有任何说明，因此流程仍是生成、渲染、查看、调整的循环。

PIC 和 pikchr。一种没有布局引擎的文本图表格式，其中位置声明是确定性的。但它是海龟绘图方式——一个可移动的光标在移动时放置形状——因此图表是一系列笔的移动动作，而不是一组命名实体之间的声明关系。没有在添加成员时能自动重新排列的组。

Graphviz 的 rank 和 cluster。对自动布局引擎的约束，而非替代方案，因此输出仍然保持从源代码中涌现且不可预测。

Structurizr。具有真正的手动布局功能，但受限于 C4 模型，使其成为一种带有渲染器的建模符号，而非通用的定位语言。

许可证

Apache-2.0。这是一个可复用的基础组件，其价值在于被采用，因此限制商业用途会违背初衷。详见 LICENSE。

许可证适用于代码，不适用于名称：它不授予使用 "reladraw"、项目标志或项目其他标识的权利。欢迎分叉，但应使用不同的名称。详见 NOTICE。

贡献

欢迎提出问题——特别是你尝试编写但未能完成的图表。尽管语言发展迅速，但问题报告比拉取请求更有价值；原因详见 CONTRIBUTING.md。