大型 Monorepo 离线架构审计与实测基准
企业代码架构审查有两条底线:私有源码不能传给第三方画图 SaaS,面对几千个文件的 Monorepo 也不能铺成一团毫无层次的蜘蛛网。
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 & RealWorld | 43–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` 复核引用一致性;未核实代码只靠文字描述生成的内容会被列为未知项。