Cursor 代码库空间可视化指南

给 Cursor Composer / Agent 装上空间架构透视镜:自动读取真实调用链路、定位高耦合热点,并输出可双击离线打开的单文件 HTML 图谱。

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

在仓库根目录执行 `sh -s -- . cursor`(或 `claude,cursor`)安装后,Cursor 会获得 `.cursor/rules/archray.mdc` 规则与 `/archray`、`/archray-frontend` 等快捷指令。在 Agent 会话中触发后,即可产出经源码核验的 `.archray/graph.json` 与 3D/2D 交互式视图。

1. 部署 Cursor 规则与快捷命令

执行安装命令后,ArchRay 会把 Cursor 专用规则文件放进 `.cursor/` 目录,把运行引擎放进 `.archray/tool`,完全独立于你的项目依赖。

生成的文件路径在 Cursor 中的用途
.cursor/rules/archray.mdc工程规范规则,引导 Cursor Agent 核对真实源码路径与行号后再建模
.cursor/commands/archray*.md斜杠指令入口(/archray、/archray-frontend、/archray-backend、/archray-data)
.archray/graph.schema.jsonv2 图谱结构与双语字段强校验文件
为 Cursor(或同时为 Claude Code + Cursor)安装
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . cursor
# 多编辑器协同团队可用逗号一次安装:
curl -fsSL https://github.com/loofare/ArchRay/releases/latest/download/install.sh | sh -s -- . claude,cursor

2. Cursor 对话触发与终端零损耗切片

与 Claude Code 使用冒号不同,Cursor 命令文件采用连字符(例如 `/archray-frontend`),同时你也随时可以直接用中文自然语言向 Cursor Agent 发起指令。

在 Cursor 对话窗口触发 & 在集成终端免 Token 重构建
# 在 Cursor Chat / Agent 窗口中输入:
/archray

# 只聚焦前端与客户端层:
/archray-frontend

# 终端零大模型开销切换跨端组合与 Glass 风格:
./.archray/archray build .archray/graph.json --layers frontend,gateway,data --style glass --force --no-open

3. 适合重构与接手陌生工程的三大动作

相比阅读大段纯文本总结,Cursor 开发者通常使用以下三步快速掌握新代码库:

  • 利用右上角「健康度」透镜直击单体巨型文件或硬编码兜底配置等热点模块,直查源码路径。
  • 切换到「可替代性」透镜对比自研与托管替代方案的工作量,点击按钮直接把迁移 Prompt 复制回 Cursor Composer 执行改造。
  • 将单文件 `.archray/index.html` 或导出海报发给产品/测试同事,对方无需安装 Cursor 即可在浏览器自由缩放查阅。

常见问题

团队里有人用 Claude Code、有人用 Cursor,配置会冲突吗?

完全兼容。使用 `--agent claude,cursor` 或 `all` 安装后,两个工具共用同一套 `.archray/graph.json` 数据契约与本地引擎,互不覆盖。

ArchRay 会额外安装占内存的 MCP 常驻进程吗?

不会。它采用轻量 `.mdc` 规则 + 按需调用本地 CLI 的方式工作,平时零后台常驻资源开销。

为什么导出的图里只有单语内容,点顶部 中/EN 开关没全部翻译?

确保在 Cursor 生成阶段 `meta.locales` 为 `["zh-CN", "en"]` 且所有层、节点、连线、健康度与流程均填写了双语字段;可让 Cursor 对照 `.archray/graph.schema.json` 补全后重建。

如何验证 Cursor 环境下的 ArchRay 组件是否完整?

在集成终端执行 `./.archray/archray doctor`,可一键自检 Node.js 版本、Schema 模板、167 枚内嵌矢量徽标与查看器构建包状态。

30 秒装入你的仓库实测

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

继续阅读相关指南