Claude Code 生成 3D 架构图实战教程

在仓库根目录安装一次 ArchRay,让 Claude Code 从纯文本问答升级为“先读真实源码证据、再生成可旋转立体架构图”的工程助手。

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

在项目根目录运行针对 claude 的 install.sh 安装脚本后,重开一次 Claude Code 会话输入 `/archray`,Claude 会核查仓库代码、写入带源码证据的 `.archray/graph.json`,再由确定性引擎构建零依赖的 `.archray/index.html` 单文件视图。后续可通过 `/archray:frontend` 或 `/archray frontend,data` 秒级按层切片。

1. 一键安装到 Claude Code 仓库目录

在目标仓库根目录执行下方命令(需 Node.js 20+、curl 与 tar;Windows 用户建议在 Git Bash 或 WSL 内执行)。整个过程完全隔离在 .archray/ 与 .claude/ 目录,不会修改一行应用业务源码。

写入文件/目录作用说明修改业务源码?
.claude/skills/archray/Claude Code Skill 规范与 v2 Schema 约束否
.claude/commands/archray*.md预置斜杠命令(/archray、/archray:frontend 等)否
.archray/tool/ 与 .archray/archray离线 CLI 封装、ELK 排版引擎与前端查看器否
.archray/graph.json 与 index.html执行 /archray 后生成的语义图与离线单文件图谱否
在目标项目根目录运行
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . claude

2. 常用 Claude Code 斜杠命令速查

安装完毕请重启或新开一个 Claude Code 会话以确保命令清单被加载。首次全库分析只需跑一次 `/archray`,后续切层无需浪费 Token 重新扫描整库。

斜杠命令高亮涵盖层适用研发场景
/archray 或 /archray:full全部存在的层 (L0–L9)新接手项目全景摸底、全栈架构评审
/archray:frontendclient (L0)排查前端页面、移动客户端及一跳直连接口
/archray:backendservice + async (L3 + L4)聚焦核心领域服务、RPC 链路与异步队列
/archray:datadata (L5)数据库扇入分析、Redis 缓存与对象存储依赖
/archray:networkedge + gateway (L1 + L2)CDN、WAF 与反向代理入口流量汇聚审查
/archray:securitygateway (L2)OAuth/OIDC 鉴权、JWT 校验与限流边界审计
/archray frontend,backend逗号拼接多层自由组合前后端联调,其它基础设施层保留半透明上下文

3. 工程最佳实践与无损升级

为了确保生成质量与团队协作效率,推荐搭配以下命令习惯:

  • 零 Token 切换视觉皮肤:已在本地生成 graph.json 后,可直接执行 `./.archray/archray build .archray/graph.json --style blueprint --lang zh-CN --force` 秒换蓝图、极光玻璃或纸质风格。
  • 排查问号乱码问题(v0.6.0+):Windows 用户已内置 UTF-8 无 BOM 强制校验与 GB18030/UTF-16 解码兜底,避免旧版 PowerShell 重定向导致的中文变成 ???。
  • 保留成果安全升级:执行 `./.archray/archray update` 会通过 SHA-256 校验更新工具链,完整保留你原有的 graph.json、view.json 与导出页面。

常见问题

为什么刚跑完 install.sh,在原有 Claude 会话里输入 /archray 没提示?

Claude Code 会在会话启动时索引 .claude/commands/ 与 skills。重开一次 Claude Code 会话即可在斜杠菜单看到 /archray 及所有分层预设命令。

切换 `/archray:data` 或更换风格会重新消耗大模型读取全库吗?

不会。语义事实一旦写入 `.archray/graph.json`,按层过滤和样式重构全部由本地 CLI 确定性引擎秒级重渲染完成。

双语仓库的中英文切换只翻译层名不翻译模块怎么办?

v0.6.0 Skill 已强化双语字段覆盖率检查;如发现缺漏,只需让 Claude 对照 `meta.locales` 补全 nodes/edges/flows 的双语对象并重新 `validate` + `build` 即可。

不再需要时如何彻底清除 ArchRay?

先执行 `./.archray/archray uninstall --dry-run` 预览清理清单,确认后运行 `uninstall` 保留图谱产物,或加 `--purge` 连同 .archray 目录一并清除。

30 秒装入你的仓库实测

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

继续阅读相关指南