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

Show HN: Reladraw – 一种由你决定元素位置的图表语言

reladraw A text language for diagrams where you say where things go. Try it in your browser → — edit the source on the left, watch the layout re-solve on the right. Nothing to install. reladraw 是一种用于绘制图表的文本语言，你可以通过它指定元素的位置。请在浏览器中尝试 → ——在左侧编辑源代码，右侧即可实时查看布局的重新计算结果。无需安装任何软件。

A diagram drawn by hand in draw.io: And the same diagram written down in reladraw and rendered from the text — examples/arch.reladraw, 44 statements, no coordinates anywhere in it: 这是在 draw.io 中手绘的图表：以及用 reladraw 编写并从文本渲染出的同一图表 —— 示例文件 examples/arch.reladraw，包含 44 条语句，其中没有任何坐标信息：

Every distance in the second picture was worked out from statements like above-left of cluster.hub and between cluster.desktop1 and cluster.laptop1. Nothing chose the arrangement; the file states it. 第二张图中的每一个距离都是根据诸如“在 cluster.hub 的左上方”以及“在 cluster.desktop1 和 cluster.laptop1 之间”这样的语句计算出来的。没有任何算法自动决定布局；布局完全由文件内容定义。

The gap Mermaid, Graphviz and D2 have you declare entities and connections, and then place everything for you. That is a superpower, and for most diagrams it is the right one. It stops being the right one as soon as you have a particular picture in mind and care where things go. 差距 Mermaid、Graphviz 和 D2 等工具让你声明实体和连接，然后自动为你放置所有内容。这是一种强大的能力，对于大多数图表来说，这确实是正确的选择。但一旦你心中有了特定的构图，并且在意元素具体放置的位置时，这种方式就不再适用了。

Say you are actively building your understanding of a system by diagramming it, and you want some module over to the right with its connections placed just so: the auto-layout languages have no way to say it. 假设你正在通过绘图来加深对系统的理解，并且希望某个模块位于右侧，同时其连接线以特定的方式放置：自动布局语言无法实现这种需求。

On the other end of the spectrum are the absolute-positioning tools — draw.io, Excalidraw, Figma. They give you total control of placement, at the cost of making every edit to a complex diagram slow hand-work. And it is slow for a human but expensive for an agent, which has to work the picture out from the coordinates before it can decide which ones to change. 在光谱的另一端是绝对定位工具 —— 如 draw.io、Excalidraw、Figma。它们赋予你对位置的完全控制权，但代价是让复杂图表的每一次编辑都变成缓慢的手动操作。这对人类来说很慢，而对 AI 智能体来说则成本高昂，因为智能体必须先从坐标中解析出图像，才能决定修改哪些坐标。

reladraw aims at the middle. Every position is stated relative to something else, and nothing in the file is a coordinate: 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

Nothing is nested, so no line depends on another line’s position or indentation. The draft is in SYNTAX.md, with a worked example in examples/. 没有任何嵌套，因此没有任何一行依赖于另一行的位置或缩进。草案位于 SYNTAX.md 中，examples/ 目录下提供了详细示例。

Why an agent needs this The common case is not drawing a diagram, it is changing one. Ask for the auth service to move left and a queue to go behind it. With pixel coordinates, an agent has to rebuild the picture from the numbers before it can work out which numbers to change. 为什么智能体需要这个 常见的情况不是绘制图表，而是修改图表。比如要求将认证服务向左移动，并将队列放在它后面。如果使用像素坐标，智能体必须先根据数字重建图像，才能计算出需要修改哪些数字。

With auto-layout there is nothing to read at all, because the arrangement was never written down — it can only reword the source and re-render. With stated placement the arrangement is in the file as sentences, and changing the picture is changing the sentence that says where the thing goes. 使用自动布局则完全没有可读性，因为布局从未被记录下来 —— 它只能重写源代码并重新渲染。而使用声明式布局，布局以句子的形式存在于文件中，修改图片就是修改描述元素位置的句子。

Writing has the same shape. An agent emitting Mermaid is guessing at a layout that an algorithm settles later, and its only way to find out is to render and look — a round trip that comes back as a picture rather than as a list of what is wrong. Intent is confirmable, outcomes are not, and the difference is worth being precise about. 写作也是同样的逻辑。智能体生成 Mermaid 代码时是在猜测布局，而布局最终由算法决定，它唯一的验证方式是渲染并查看 —— 这是一个往返过程，返回的是图片而不是错误列表。意图是可以确认的，但结果往往不可控，这种区别值得我们精确对待。

An agent can re-read its own file and see that the database is under the API and all four machines hang off the sync hub. It cannot see that two clusters anchored to different things now overlap, that a text overflowed its node, or that an edge crosses four others — those are resolved from the statements rather than stated, so they need the diagnostics in the scope section below. 智能体可以重新读取自己的文件，看到数据库位于 API 下方，且四台机器都挂载在同步中心上。但它无法直接看到两个锚定在不同位置的集群是否重叠、文本是否溢出节点，或者连线是否穿过了其他四条线 —— 这些问题是根据语句计算出来的，而不是直接声明的，因此需要下文“范围”部分提到的诊断功能。

Using it with an agent reladraw is too new to be in any model’s training data, so an agent has to be told the language before it can write it. This repository ships an agent skill that does exactly that — the syntax, when to reach for the language, and what re-reading its own source can and cannot confirm. 与智能体配合使用 reladraw 太新了，尚未进入任何模型的训练数据，因此在智能体编写它之前，必须先向其传授该语言。本仓库提供了一个智能体技能（agent skill），专门用于实现这一点 —— 包括语法、何时使用该语言，以及重新读取源代码时能确认和不能确认的内容。

npx skills add reladraw/reladraw -g That installs it for whichever agent you use — Claude Code, Codex, Cursor, Copilot and others — each into its own skills directory. Drop the -g to install it into the current project instead. To install it for one agent rather than all of them, name it with -a: 这会为你使用的任何智能体（Claude Code、Codex、Cursor、Copilot 等）安装该技能，每个智能体都有自己的技能目录。去掉 -g 可以将其安装到当前项目中。若只想为某个特定智能体安装，请使用 -a 指定名称：

npx skills add reladraw/reladraw -g -a claude-code Re-run whichever command you used after a release that changes the syntax. The skill is a copy taken at install time, not a live link, so nothing refreshes it on its own. It is plain Markdown with the syntax reference beside it, so it is worth reading whatever you use, and copying the directory by hand works just as well. 在语法发生变更的版本发布后，请重新运行你使用的安装命令。该技能是安装时获取的副本，而非实时链接，因此它不会自动更新。它只是带有语法参考的纯 Markdown 文件，无论你使用什么工具，阅读它都很有价值，手动复制目录效果也一样。

Status Version 0.5.0. Early, but it runs: a parser, resolver and SVG renderer in TypeScript with no runtime dependencies, and a command-line tool that takes a text file and writes a standalone SVG. The comparison at the top of this page is that pipeline run on examples/arch.reladraw. What is still visibly off there is typography, not placement. 状态 版本 0.5.0。虽然处于早期阶段，但已经可以运行：包含一个用 TypeScript 编写的解析器、求解器和 SVG 渲染器，没有运行时依赖，并提供了一个命令行工具，可以将文本文件转换为独立的 SVG。本页顶部的对比图就是通过该流水线处理 examples/arch.reladraw 生成的。目前视觉上仍有瑕疵的是排版，而不是位置。

npm install -g reladraw reladraw diagram.reladraw -o diagram.svg Or from a clone, which also gets you the examples: 或者通过克隆仓库安装，这样你也能获得示例文件：

npm install && npm run build node dist/cli.js examples/arch.reladraw -o out.svg

Not built yet, roughly in the order they are missed: 尚未实现的功能，按需求紧迫程度排序：

1. The diagnostics report. The scope section below says what it is for. Today the tool either renders or fails; it will not tell you what is wrong with a picture it drew successfully.
2. 诊断报告。下文“范围”部分说明了其用途。目前工具要么渲染成功，要么失败；它不会告诉你一张成功绘制的图表哪里有问题。
3. Edge routing around nodes. An edge can be told which side of a node to leave and arrive on, and which gap to run down on the way. An edge that says none of that is a straight line between two centers, and it will cut through whatever stands in the way.
4. 绕过节点的连线路由。可以指定连线从节点的哪一侧出发和到达，以及沿途经过的间隙。如果未指定，连线将是连接两个中心点的直线，并会穿过挡在路上的任何东西。
5. More pictures. Icons and shapes are closed sets drawn from path data inside the tool, so a diagram wanting one that is not there has nowhere to go.
6. 更多图形。图标和形状是工具内部基于路径数据绘制的封闭集合，因此如果图表需要一个不存在的形状，目前还无法实现。
7. The language is not stable. Expect the syntax to change.
8. 语言尚不稳定。语法可能会发生变化。

How it works A gap is a minimum distance, never an exact one. Say two things sit side by side, then say a third goes between them, and the first two are pushed apart by exactly what the third needs; delete the third and they close back up. That is the step an author otherwise does by hand — shove things apart to make room, then drag everything back so the diagram is not full of holes — and no number goes stale when a text grows. 工作原理 间隙是最小距离，而不是精确距离。假设两个元素并排摆放，然后你在它们中间插入第三个元素，前两个元素会被推开，距离刚好满足第三个元素的需求；删除第三个元素，它们又会靠拢。这是作者通常需要手动完成的步骤 —— 挪开元素腾出空间，然后再拖动所有东西以确保图表不会留有空洞 —— 这样当文本内容增加时，没有任何数字会失效。

So the resolver solves a system rather than walking a chain. Each axis is a set of minimum distances, and the tightest arrangement satisfying all of them is found by longest paths: one answer, no sets. 因此，求解器是在解决一个系统问题，而不是遍历链条。每个轴都是一组最小距离的集合，满足所有约束的最紧凑布局是通过最长路径算法找到的：只有一个答案，没有多余的集合。