ArchRay 对比 Mermaid、Structurizr 与 Eraser

架构图真正的价值在于“忠实映射真实代码、节点多了不乱线、且能在不泄密的前提下离线交付团队”。不同工具各擅胜场,以下是客观选型指南。

ArchRay v0.6.0 作者:David Yin · 更新 2026-11-20 MIT Open Source

当你需要 AI 编程助手(Claude Code、Cursor、Codex、Pi 或 Antigravity)直接通读真实仓库,输出带文件行号证据、支持 L0–L9 按层切片且可离线双击打开的 3D/2D 单文件架构图时,选择 ArchRay。文档内嵌微型流程图可选 Mermaid,强规范手工 C4 建模可选 Structurizr,前期自由草图头脑风暴可选 Excalidraw。

核心能力对比矩阵

传统 AI 制图把“理解代码语义”和“画框算坐标”混在一起,导致复杂项目一画就乱。ArchRay 将工作严格拆为两段:AI 只输出经过源码核验的 .archray/graph.json,坐标计算、端口走线与 3D/2D 投影全部交给离线确定性引擎完成。

对比维度ArchRay (v0.6.0)MermaidStructurizr DSLEraser / DiagramGPTExcalidraw / Draw.io
源码证据链强制记录 sourcePaths 与文件行号依据手写文本,无代码绑定手工维护 DSL 模型部分依赖提示词或云端解析纯手工连线
AI 编程助手集成原生适配 5 大宿主(/archray 与 $archray)大模型通用输出文本需人工编写 DSL独立网页或 IDE 插件手绘或零散插件
大仓库排版稳定性ELK 确定性路由 + 三维象限分离 + 2D Bento超过 15 个节点易交叉缠绕自动排版或手调坐标云端布局引擎人工拖拽对齐
按层切片查看支持 L0–L9 单层或逗号组合 + 一跳上下游需拆分多个代码块需提前定义 View 作用域单一平面视图需切换画布或手动隐藏
技术栈与体块识别内嵌 167 枚矢量徽标与语义 3D 体块同质普通矩形需自配样式主题云端图标库手动粘贴图标
健康度与平替评估内置热点诊断、实测/≈ 区分与迁移 Prompt无无无无
离线隐私与交付零上传 · 单文件 HTML (file:// 直接打开)依赖 Markdown 渲染器或 CLI依赖本地容器或云服务强制走 SaaS 云服务本地文件或云盘
开源协议与费用MIT 开源完全免费MIT 开源DSL 开源 / 云端收费SaaS 订阅制开源 / 商业版

为什么大模型直接画 Mermaid / SVG 容易失真?

在小型 Demo 上让大模型画一张 Mermaid 看似顺手,但在真实工程仓库里通常会遇到三个顽疾:

第一是“凭目录名脑补”:模型没核对真实 import/调用代码就编造模块依赖;第二是“平面穿线蜘蛛网”:前端、网关、消息队列与数据库挤在同一平面互相遮挡;第三是“无法局部增量审视”:前后端联调时只想看端到端核心链路,每次却要让 AI 重写整段图代码。

  • 事实与几何解耦:AI 写语义 JSON,ELK 与三维投影算几何坐标,彻底杜绝坐标重叠与标签裁切。
  • 一次扫描、按需切片:生成一次 .archray/graph.json 后,可瞬间切换 /archray:frontend、backend,data 等多层组合。
  • 诚实证据口径:TypeBox 严格校验必填字段,将未知依赖隔离到显式清单,并将静态估算指标标注为 ≈。

坦诚适用边界:哪些场景不建议用 ArchRay?

ArchRay 聚焦“基于真实代码库的拓扑透视与离线团队分享”,以下场景使用对应工具会更合适:

  • GitHub PR 或技术博客里的轻量时序图(5–8 个步骤):继续使用 Mermaid 代码块最轻量。
  • 架构委员会强制审计的纯手工 C4 架构治理模型:继续使用 Structurizr DSL 编写标准视图。
  • 尚未编写任何源码的新项目脑暴草图:使用 Excalidraw 或纸笔自由涂鸦更快捷。
  • 生产环境全链路追踪与真实 QPS 监控:ArchRay 不是 APM 探针或运行时监控系统,不采集线上流量。

30 秒装入当前项目实测对比

所有工具文件全部自包含隔离在 .archray/tool 内,零污染业务源码,支持随时一条命令干净卸载:

安装全宿主并一键切换蓝色蓝图(Blueprint)视图
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . all
# 重开 AI 会话并输入:
/archray
# 随时免重新扫描代码,仅切换配色或分层切片:
./.archray/archray build .archray/graph.json --layers frontend,backend,data --style blueprint --force

常见问题

ArchRay 生成的结果能嵌入 Confluence、飞书或设计文档吗?

可以。点击架构图顶部工具栏的“整图 PNG”可导出不裁切画布外沿的高清全景图(例如 4440×4002 级别完整包围盒重投影),或导出带开源溯源二维码的分享海报直接贴入文档。

ArchRay 的 graph.json 适合提交进 Git 仓库吗?

非常适合。推荐提交 .archray/graph.json 与 view.json 方便团队同步代码演进中的架构变更与健康度发现,离线单文件 HTML 可随时按需本地重构。

为什么 3D 全景和 2D Bento 使用同一份数据时能严格一致?

两种投影渲染同一份验证通过的 graph.json 语义节点和连线,仅改变布局与投影算法。三维视图把异步翼(-X)、外部 SaaS 轨(+X)和底层存储圆柱拉开空间层次;2D Bento 则适合印刷与平面嵌套审查。

使用 ArchRay 会把企业私有源码发到外部官网吗?

绝对不会。archray.dev 本身完全是静态站点。代码阅读仅发生于你本地已授权的 AI 编程助手会话中,CLI 离线构建,只有主动运行 update 时才会从 GitHub Releases 只读校验版本。

30 秒装入你的仓库实测

纯本地运行、零源码上传,支持 Claude Code、Cursor、Antigravity、Pi 与 Codex。

继续阅读相关指南