1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | reladraw(项目自述名称同为 reladraw) |
| 作者/维护者 | reladraw 组织(作者署名 Joe Walsh,个人项目) |
| 来源链接 | https://github.com/reladraw/reladraw |
| 许可证 | Apache-2.0(NOTICE 声明许可不含 “reladraw” 名称与标志的商标权) |
| GitHub Stars | 784(GitHub API) |
| Forks | 14(GitHub API) |
| 最新版本 | v0.9.0(2026-09-27 发布,npm 同步发布;语法尚未稳定) |
| 安装方式 | npx skills add reladraw/reladraw -g;配套渲染命令 npm install -g reladraw(或直接 npx reladraw),需 Node ≥ 18 |
数据来源:仓库指标、发布信息、Issue 来自 GitHub API;npm 下载量来自 npm 公开接口(近 7 天 471 次);社区讨论来自 Hacker News 公开接口。
2. 功能介绍与亮点
这个 skill 教会 agent 用 reladraw 文本图语言画节点连线图(架构图、数据流、部署图、目录结构、PR 改动示意),输出独立 SVG。核心思路是把“东西放哪”写成人话:right of api、between web and worker、level with queue,由工具只计算间距。
- 位置写在源码里:不同于 Mermaid、Graphviz 由布局引擎决定落点,reladraw 的排布就在你写下的句子里,agent 看不到 SVG 时,重读自己写的源码就能知道每个元素在哪。
- 含糊即报错:没交代清楚的相对位置不会被“猜”出来,而是报错并指出哪一行、哪对节点冲突,agent 据此修正。
- 无坐标:间隙是最小距离而非固定数值,改文字长度不会让别处错位。
- 表达力:容器嵌套、边的走向(
from:/to:/between)、圆角直角折线、虚线粗细、图标与徽标、亮暗主题色,均有语法支持。 - 诚实的边界说明:SKILL.md 明确写出“重读源码只能确认意图、不能确认渲染结果”,对大图建议如实说明未验证渲染,并把“不适用于数据图表”写进触发条件。
- 零运行时依赖:渲染器用 TypeScript 实现,本地运行、不联网;附完整语法参考(约 100 KB)和 27 个示例文件。
3. 适用场景
所属分类:数据分析与可视化(示意图/架构图生成)。
- 需要“按自己想法摆放”的架构图、系统数据流、部署拓扑,又不想手改 draw.io 的冗长 XML。
- 让 agent 在 README、设计文档、PR 说明里生成可版本管理的文本图源文件。
- 受益人群:写架构文档的工程师、技术写作者、常让 agent 画图的开发者。
- 不适合:柱线饼等数据图表;非“节点+连线”的插画;对语法稳定性要求高的长期归档(语言仍在快速变化)。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 技能目录为 .claude/skills/reladraw/,npx skills add 支持 claude-code 目标 |
| Codex | 需适配 | README 称同一命令可装入 Codex;安装器的 Codex 目标为 .agents/skills/,自动发现行为未实测 |
| OpenClaw | 未验证 | 安装器列有 OpenClaw 目标目录(~/.openclaw/skills/),SKILL.md 为标准格式,未实测 |
| Hermes Agent | 未验证 | 安装器列有 .hermes/skills/ 目标目录,未实测 |
所有平台都要求本机可运行 Node(≥ 18)来执行 reladraw 渲染命令。
5. 推荐理由
- 解决了 agent 画图的老问题:自动布局“画完不知道长什么样”,手写坐标又太啰嗦;reladraw 让 agent 用相对位置语言表达布局,源码即可核对意图。
- 上手成本低:
npx skills add一条命令装 skill,npx reladraw即用,无需配置、无需 API key。 - 出错反馈清晰,agent 能自行修正;输出是标准 SVG,可嵌入文档。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | 建仓约三周即达 784 stars;Show HN 帖获 387 分、113 条评论;npm 周下载 471;项目仍在早期 |
| 可用性 | 8 | 两条命令即可用,SKILL.md 与语法参考完整,含示例与常见错误清单,发布节奏密集;扣分点是语法未稳定(v0.9.0)且已知缺陷在参考文档中列明 |
| 安全性 | 8 | 纯本地渲染、无网络外联、无密钥;代码可审计、零运行时依赖;License 明确;作者为新建组织的个人开发者 |
综合 = 三项均值 7.33。
安全检查清单:
- shell 命令与权限:技能仅让 agent 运行
reladraw命令(可用npx临时执行),读取.reladraw文件并写出 SVG;无其他 shell 权限要求。 - 联网外发:已检查发布包,渲染代码中无网络请求与子进程调用;运行时不外联。
- 凭据:不需要任何 API key 或凭据。
- 可疑指令:SKILL.md 与语法文档通读,未发现夹带推广、越权或注入迹象。
- 作者/组织信誉:组织与仓库均为近三周新建,作者公开署名并在 HN 帖中持续答复用户、及时修复反馈的缺陷;fork 账号多为长期活跃老账号。
- License:Apache-2.0。
- 维护:最近一次推送在 2026-09-27,近一天内连续发布多个版本。
7. 跟同类 Skills 相比的优势
| 工具 | 定位 | 与 reladraw 的差异 |
|---|---|---|
| Mermaid | 声明节点与连接,由引擎自动布局 | 复杂流程图时落点不可控;reladraw 由作者用相对位置决定排布 |
| Graphviz / D2 | 同为自动布局的图语言 | 同上,布局是输出而非输入 |
| draw.io / Excalidraw | 图形界面绝对定位,表达力强 | 人手拖拽费时,agent 改冗长 XML 易出错;reladraw 用简短文本表达同类排布 |
| Pikchr | 类“海龟绘图”,光标依次画形状 | 靠绘制顺序推位置;reladraw 直接声明元素之间的相对关系,容器加子元素无需调整 |
| TikZ(LaTeX) | 相对定位库,功能强大 | 需要 LaTeX 环境,边的处理较繁琐;reladraw 专注框、分组、箭头,无需 LaTeX |
核心差异:在“自动布局”与“绝对坐标”之间取中间路线——保留文本语言的简洁,同时让排布完全由作者掌控。代价是需要学一套新语法,且暂不做绕障自动布线。
8. 用户评价
- Hacker News(Show HN,2026-09-26):帖子获 387 分、113 条评论。用户 monster_truck 称它能取代自己手头几个临时拼凑的画图实现;用户 tetris11 表示自己对 Mermaid 的问题很多、认同这一方向;用户 kinduff 称 agent 常常直接手写 SVG,希望这个思路能成为 Mermaid 的一部分;用户 HeavyStorm 认为流程图里位置最关键,Mermaid 在这点上不足。
- 批评意见:用户 recroad 反馈不想为图表指定这么细的位置、更愿只描述要表达的内容;同一用户报告的一处边曲线渲染缺陷,作者当日已在演示页修复。
- 链接:https://news.ycombinator.com/item?id=49858513
9. 其他补充
- 提供浏览器在线演示页(reladraw.github.io/reladraw)与
llms.txt,便于 agent 直接获取语法说明。 - 项目欢迎以 Issue 提交“reladraw 画不出的图”,作者称当前语法变动快,Issue 比 PR 更有帮助。
- 更新 skill 需重新运行安装命令,安装到项目里的是安装时刻的副本。
10. 安装使用方式
# 安装 skill(所有已检测到的 agent;去掉 -g 则仅装到当前项目)
npx skills add reladraw/reladraw -g
# 只装给某个 agent
npx skills add reladraw/reladraw -g -a claude-code
# 渲染命令(二选一)
npm install -g reladraw
npx reladraw diagram.reladraw -o diagram.svg
安装后无需重启,对 agent 说“画一张架构图”或提及 reladraw 即可触发。
11. 注意事项
- 语言版本 0.9.0,作者明确表示语法会变,旧的
.reladraw文件在新版本中可能需要调整。 - 不会自动绕开障碍布线,边的走向需用
between、below <节点>、from:/to:显式说明。 - agent 无法看到渲染结果,大型或密集图的溢出、交叉需人工查看 SVG;诊断报告功能尚在计划中。
- 每个文件只允许一个未定位节点,其余节点须直接或间接相对它定位,否则报错。
- 不适用数据图表(柱、线、饼、散点)。