L0–L9 十层架构、节点类型与 CLI 技术参考

面向架构师与研发工具团队的 ArchRay Graph v2 技术词典:完整收录十层分层语义、三维空间分区、中英文别名及命令行全参数。

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

ArchRay Graph v2 定义了 10 个规范架构层(`client` 至 `observability`)、19 种节点类型(`kind`)与 14 种已知连接协议,支持 `tech`/`blueprint`/`glass`/`paper` 四套皮肤,内置 212 条技术栈识别提示与 167 枚离线矢量品牌徽标。

1. L0–L9 十个规范架构层与 3D 空间象限

每个模块归属的 canonical layer 不仅决定三维空间纵深与体块形态,还直接绑定斜杠命令和 CLI `--layers` 的中英文别名筛选:

层级标准层 ID可用中英文别名3D 空间分区与体块造型典型技术栈示例
L0clientfrontend, client, 前端, 客户端顶层入口 · 倾斜屏幕薄板Next.js, Vue 3, React Native, Electron
L1edgenetwork, edge, 网络, 边缘上层接入缓冲 · 宽幅接入层板Cloudflare, Nginx, Envoy, Traefik
L2gatewaysecurity, gateway, 网关, 鉴权鉴权枢纽 · 网关分流棱台Kong, Better Auth, Clerk, Keycloak
L3serviceservice, backend, 后端, 服务中央主塔 · 圆角核心方台NestJS, FastAPI, Spring Boot, Go
L4asyncasync, worker, 异步, 队列左侧任务翼 (-X) · 胶囊任务体Kafka, BullMQ, Socket.IO, Celery
L5datadata, db, 数据, 存储核心存储底座 · 三段存储圆柱PostgreSQL, Redis, Elasticsearch, S3
L6aiai, model, AI, 智能智能侧翼 (-X) · 推理核心体Gemini, Claude, Qdrant, pgvector
L7externalexternal, saas, 外部, 三方右侧独立轨 (+X) · 虚线外部边界Stripe, Resend, Twilio, OAuth SaaS
L8platformplatform, infra, 平台, 运维底层地基 · 基础设施宽台Docker, Kubernetes, Terraform, Actions
L9observabilityobservability, obs, 可观测, 监控底层遥测面 · 遥测追踪平面OpenTelemetry, Prometheus, Grafana, Sentry

2. 19 种节点类型(kind)与 14 种连线协议

212 条分类提示会优先匹配 167 枚内嵌矢量徽标;如未识别到特定产品徽标,会自动匹配对应角色的三维体块图标:

  • 19 种已知节点 kind:client、cli、gateway、service、worker、function、library、module、database、cache、queue、storage、search、external-api、ai-model、config、group、saas、archive(也允许自定义字符串)。
  • 14 种已知连接协议:http、grpc、graphql、ws、sse、amqp、kafka、sql、redis、ipc、import、fs、llm、event。
  • 4 套视觉主题(--style):tech(科技深空,默认)、blueprint(架构蓝图)、glass(极光磨砂)、paper(高对比打印白底)。
  • 3 档动效控制(--motion):full、calm、off(遵循系统减弱动效偏好)。

3. Graph v2 极简双语 JSON 示例

`.archray/graph.json` 严格禁止大模型写入像素坐标,仅表达节点、父子层级与连线关系:

最小双语 v2 图谱结构(.archray/graph.json)
{
  "schemaVersion": "2.0",
  "meta": { "name": { "zh-CN": "Acme 系统", "en": "Acme App" }, "locales": ["zh-CN", "en"], "generatedAt": "2026-11-20T00:00:00Z" },
  "layers": [
    { "id": "client", "name": { "zh-CN": "客户端", "en": "Client" }, "order": 0 },
    { "id": "service", "name": { "zh-CN": "核心服务", "en": "Services" }, "order": 3 },
    { "id": "data", "name": { "zh-CN": "数据存储", "en": "Data" }, "order": 5 }
  ],
  "nodes": [
    { "id": "web", "layer": "client", "kind": "client", "name": { "zh-CN": "Web 控制台", "en": "Web App" }, "sourcePaths": ["apps/web/src/app/page.tsx"] },
    { "id": "api", "layer": "service", "kind": "service", "name": { "zh-CN": "订单服务", "en": "Order API" }, "sourcePaths": ["apps/api/src/order.ts"] },
    { "id": "pg", "layer": "data", "kind": "database", "name": { "zh-CN": "PostgreSQL 主库", "en": "PostgreSQL" }, "tech": ["PostgreSQL"], "sourcePaths": ["prisma/schema.prisma"] }
  ],
  "edges": [
    { "id": "e1", "from": "web", "to": "api", "protocol": "http" },
    { "id": "e2", "from": "api", "to": "pg", "protocol": "sql" }
  ]
}

4. 全部 CLI 子命令速查

在项目根目录直接调用 `./.archray/archray`(Windows 下使用 `.archray\archray.cmd`):

CLI 命令功能与常用选项
./.archray/archray doctor检查 Node.js 20+、内嵌 Schema、查看器与图标资源完整性
./.archray/archray validate .archray/graph.jsonTypeBox 校验、唯一 ID 冲突检测、双语完整度与 UTF-8 无乱码检测
./.archray/archray build <json> [选项]离线构建单文件 HTML(支持 --layers、--style、--lang、--motion、--output、--force、--no-open)
./.archray/archray update [--check]只读检查新版本或 SHA-256 校验更新工具链(保留现有图谱成果)
./.archray/archray uninstall [--dry-run] [--purge]预览或卸载适配器与命令文件,加 --purge 清除全部产物

常见问题

每个仓库必须把 10 层全部填满吗?

不需要。建议按仓库真实复杂度只声明 3–6 个实际存在的层(例如官网在线沙盒 FreshMart 只使用了 5 层),同时每层归属会自动匹配十层布局规则。

子模块怎么归属到父节点实现自动折叠?

在平铺 `nodes` 数组中为子节点填写 `parent: "<父节点ID>"`,确保全库节点 ID 唯一(例如 `order/repo`),缩放到全景比例时引擎会自动折叠显示 `+N` 数量标记。

自定义调好的 3D 角度、隐藏层与筛选状态如何发给别人?

点击画布顶部工具栏导出 `view.json` 并发送,对方在你导出的同一份 `index.html` 中导入该 `view.json` 即可还原完全相同的视角与高亮状态。

内嵌的 167 枚技术栈品牌图标会走外部 CDN 请求吗?

绝对不会。所有 SVG 图标全部来自构建期封装的离线图标包,生成的单文件 HTML 断网环境下照常高清展示。

30 秒装入你的仓库实测

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

继续阅读相关指南