大型 Monorepo 离线架构审计与实测基准

企业代码架构审查有两条底线:私有源码不能传给第三方画图 SaaS,面对几千个文件的 Monorepo 也不能铺成一团毫无层次的蜘蛛网。

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

ArchRay 在 `.archray/tool` 内完全本地离线完成图谱校验与单文件 HTML 构建,零遥测、零服务器外传。在真实开源大仓 `calcom/cal.com`(7,712 个跟踪文件)实测中,ArchRay 将架构收敛为 33 个核心模块、75 条边与 7 层,ELK 确定性布局仅耗时 196ms,同时清晰标出实测值与 ≈ 静态估算值并强制 UTF-8 无 BOM 校验。

1. 真实工程仓库实测数据

以下基准均直接采集自真实工程仓库,而非拼接假图。高密子包在全景视角会自动折叠显示 `+N` 标记,需要时可单点或分层下钻:

实测仓库架构体量与模块数布局与构建耗时关键工程发现
calcom/cal.com (commit ae027bb)7,712 跟踪文件 → 33 模块 · 75 边 · 7 层Node ELK 布局 196ms · 60fps 流畅交互高密子包默认 +N 自动折叠,标签零重叠
FreshMart Commerce(官网在线沙盒)16 模块 · 19 边 · 5 层 · Checkout 6 步链路本地毫秒级单文件交付精确定位 6,200 行订单同步锁热点并生成 Passport → Clerk 迁移方案
SaaS Starter & RealWorld43–49 源文件0.03s CLI 快速构建清晰串起 App Router、Prisma、Stripe,并揪出硬编码 JWT_SECRET 回退风险

2. 100% 离线零外传安全边界

在线 AI 画图平台通常需要把源码目录、接口关系传到平台云端再生成图片。ArchRay 彻底切断云端画图链路:

  • 官网零代码存储:archray.dev 本身是纯静态网站,没有任何接收源码或架构图谱的后端接口。
  • 会话边界透明:源码审查仅发生在你主动授权使用的 AI 编程助手(如 Claude Code、Cursor、Codex)本地会话中。
  • 纯本地便携交付:生成的 `.archray/index.html` 内嵌查看器、167 枚技术栈徽标及离线二维码海报生成器,内网隔离电脑也可通过 `file://` 直接打开。
  • 仅在人为运行 `./.archray/archray update` 时只读连接 GitHub Releases 校验 SHA-256。

3. 实测与 ≈ 估算严格区隔 + v0.6.0 Windows 乱码防护

ArchRay 拒绝用大模型猜的数字冒充监控指标。Graph v2 规范要求指标必须标注 `origin: "measured"`(实测)或 `estimated`(前端以 `≈` 前缀高亮呈现),不虚构 QPS、延时或运行时调用统计。

同时自 v0.6.0 起,针对朋友在 Windows 环境下遇到的中文变 ??? 问题,CLI 在 `validate` 阶段新增“孤立问号占位与 U+FFFD 替换符”检测、支持自动解码 GB18030/UTF-16 编码文件,并在 Skill 规范中禁止用 PowerShell 默认编码重定向写入中文 JSON。

生成后本地离线校验与重建命令
./.archray/archray validate .archray/graph.json
./.archray/archray build .archray/graph.json --force --no-open

常见问题

ArchRay 能代替 Prometheus / OpenTelemetry 等生产可观测平台吗?

不能。ArchRay 定位是静态源码与仓库结构可视化分析,不会向线上业务注入 APM 探针,也不会抓取生产真实 QPS/延迟数据。

导出的高清整图 PNG 会不会像浏览器截图那样把两边切掉?

不会。ArchRay 的整图 PNG 导出会根据所有节点和楼层的完整三维/二维世界坐标包围盒重新投影绘制,无论仓库多宽都能完整保留。

`validate` 命令除了 JSON 格式还校验哪些规则?

会基于 TypeBox 校验节点 ID 全局唯一性、边端点与流步骤引用完整性、双语仓库下所有字段的多语言对齐度,以及 UTF-8 无 BOM 与乱码损坏检查。

如何验证我手里生成的旧图是安全可靠的?

可以在查看器右侧检查每个节点附带的 sourcePaths 文件路径,并用本地 `./.archray/archray validate .archray/graph.json` 复核引用一致性;未核实代码只靠文字描述生成的内容会被列为未知项。

30 秒装入你的仓库实测

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

继续阅读相关指南