@realsee/vr-cli

创建如视空间应用的命令行工具。生成的 TypeScript 项目包含 Five 空间浏览、React 界面和 Node.js 服务端，可直接开发，也可交给 AI 编程助手继续完善。

环境要求

• Node.js >=22.18.0
• npm >=11.19.0

在终端中确认版本：

node --version
npm --version

快速开始

1. 创建项目

无需全局安装，直接运行：

npx --yes --package=@realsee/vr-cli@latest -- vr-cli create ./my-vrapp
cd ./my-vrapp

命令会创建项目并安装依赖。目标目录必须不存在或为空。

2. 检查并构建

默认创建已按锁文件安装依赖，无需再次执行 npm ci。先完成无凭据检查与构建：

npm run build
node .agents/skills/realsee-vr-app/scripts/verify-project.mjs .

build 已包含项目检查，无需再重复运行 check。使用 --no-install、从源码新检出项目，或依赖确有缺失/损坏时，再按工程说明安装依赖。若创建时选择 --agent-assets none，不包含上述 Agent 验证器。

3. 连接如视开放平台

npm run setup

打开终端中显示的验证链接，在浏览器中核对短码，并按页面提示完成确认。终端提示配置成功后，即可继续。

配置保存在当前项目的 .env.development 中，已默认排除在 Git 提交之外。请勿将密钥放入前端代码或发送到聊天中。

4. 启动应用

npm run dev

在浏览器中访问：

http://127.0.0.1:8087/{resourceCode}

将 {resourceCode} 替换为空间项目的资源编码。如果配置时已选择默认空间项目，也可以直接打开 http://127.0.0.1:8087/。

项目中包含什么

• Five 空间浏览，以及 Panorama、Mapview、Topview 模式切换。
• PanoTag、ModelFloorplan 插件接入和 Vapor / React 界面。
• 调用如视 OpenAPI 的 Fastify 服务端，密钥保留在服务端。
• TypeScript、ESLint、Prettier 和 Vite 开发配置。
• 供 AI 编程助手参考的项目说明和技能文件；其中 realsee-spatial-analysis 技能可盘点 Work 数据包、执行空间理解分析（v2 JSON、中文报告、图谱、预览），并把结果回装为项目的「空间智能」入口；项目 BFF 已配对时默认从 GET /api/work/<资源码> 物化 work.json/floorplan.json，在项目中发起时 <app> 默认当前目录（需要 Python 3.10+，完整分析需要 Python 3.12+ 和技能内置运行时依赖）。

常用项目命令

以下命令均在创建好的项目目录中执行：

| 命令 | 用途 | | ------------------------------ | ------------------------------------------ | | npm run setup | 配置或更换当前项目的开放平台连接 | | npm run dev | 启动本地开发服务 | | npm run check | 运行项目测试、类型检查、代码规范和格式检查 | | npm run build | 检查项目并构建浏览器应用 | | npm start | 使用服务端运行已构建的应用 |

构建与部署

在本地运行生产构建：

npm run build
npm start

部署时需要同时运行 Node.js 服务端，并配置 REALSEE_GATEWAY_APP_KEY 和 REALSEE_GATEWAY_APP_SECRET 环境变量。

如果你使用的 AI 助手带有网站发布能力，可先让它检查是否支持本工程的 Node.js 后端、实际 Node/npm 版本、监听地址和端口，以及服务端凭据配置。发布后还需在开发者凭证中允许实际发布域名，并在该地址验证真实 VR 与交互。具体要求见生成工程 README；本地运行成功不等于目标平台已兼容。

更多 CLI 用法

如需经常使用 CLI，可以全局安装：

npm install --global @realsee/vr-cli@latest

之后可直接使用以下命令；再次运行安装命令即可更新 CLI。

vr-cli create ./another-app
vr-cli doctor ./my-vrapp
vr-cli help

doctor 用于检查开发环境、项目文件和依赖配置；添加 --json 可输出供自动化处理的结果。

创建项目时支持以下选项：

| 选项 | 说明 | | ----------------------- | ----------------------------------------------------- | | --name <npm-name> | 指定项目的 npm 包名 | | --no-install | 只生成文件，稍后在项目中执行 npm ci 安装依赖 | | --agent-assets <mode> | 选择 AI 助手资料：portable（默认）、all 或 none |

需要固定模板版本时，将创建命令中的 @latest 替换为所需版本号。更新 CLI 不会自动修改已创建的项目。

在 AI 编程助手中配置

如果 AI 助手无法显示持续运行的终端输出，可以分两步完成配置。先执行：

npm run setup -- --no-wait --json

该命令返回验证链接和短码，退出码 2 表示等待用户确认。在浏览器中完成确认后，再执行：

npm run setup -- --complete

常见问题

创建失败后如何重试？

保留失败目录和错误输出，在解决报错原因后换一个新目录创建。CLI 不会覆盖已有项目。

可以在同一台设备上开发多个应用吗？

可以。为每个应用使用不同目录，分别运行 npm run setup。每个项目有独立的配置；确认配对时，请核对页面显示的项目名称。

配置没有完成怎么办？

如果已在浏览器中确认，但终端意外退出，可运行 npm run setup -- --complete 继续。

也可以在如视开放平台的空间应用创建页点击“复制本地配置”，然后执行以下命令，将配置粘贴到终端的隐藏输入中：

npm run setup -- --paste

配置完成或更换配置后，重新启动开发服务。

空间加载失败怎么办？

先确认访问地址中的 resourceCode 正确，并且当前开放平台应用有权访问该空间项目。如果直接访问根地址，请先确认已配置默认空间项目。

许可证

本包的许可证声明为 SEE LICENSE IN TERMS.txt，完整条款见 TERMS.txt。Realsee SDK、开放平台服务、品牌、客户数据及第三方资源的使用应符合相应协议与授权范围。

The Realsee-authored example/template source in templates/base and templates/viewer is licensed under the unmodified PolyForm Noncommercial License 1.0.0 (PolyForm-Noncommercial-1.0.0). See each template LICENSE and LICENSING.txt. The CLI implementation and SDK dependencies retain their separate SDK agreement. Earlier releases retain the rights previously granted for those copies.