@realsee/vr-cli

@realsee/vr-cli 是面向 Realsee 空间 Viewer 应用开发的命令行工程工具，用于创建和检查标准化 TypeScript Viewer 项目，并为自动化流程提供空间能力策略。

核心能力

• 通过 create 创建 Viewer 项目并安装依赖。
• 通过 doctor 检查开发环境、项目结构、依赖配置和关键实现约束。
• 通过 policy 输出版本化的空间能力策略。

安装与执行

CLI 支持临时执行和全局安装，两种方式使用相同的 vr-cli 命令与参数。

临时执行

无需全局安装即可创建项目：

npm exec --yes \
  --package=@realsee/vr-cli@latest \
  -- vr-cli create ./my-vrapp

全局安装

安装后可直接执行 vr-cli：

npm install --global @realsee/vr-cli@latest
vr-cli create ./my-vrapp

更新全局安装：

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

CI 和自动化生成流程应使用明确版本。当前版本示例：

npm exec --yes \
  --package=@realsee/[email protected] \
  -- vr-cli create ./my-vrapp --no-install

cd ./my-vrapp
npm ci
npm run check
npm run build

快速开始

create 默认在生成目录中执行 npm ci。项目创建完成后进入目录，运行固定的本地配置入口：

cd ./my-vrapp
npm run setup

在 Realsee China Portal 的 onboarding 页面完成组织、开发者应用和空间项目选择，点击“复制本地配置”，将单行 realsee-setup:v1:... 配置包粘贴到隐藏输入中。配置包由 UTF-8 JSON 经 Base64URL 编码，兼容 Windows、macOS 和 Linux；Base64URL 仅提供稳定的单行传输格式，不是加密。不要把配置包放入聊天、命令参数、管道、重定向、Shell 历史、源码或日志。

npm run setup 校验 AK、SK 和 resourceCode 后，原子写入 gitignored 的服务端 .env.development。POSIX 系统使用 0600，Windows 使用当前用户 ACL。首次接入未成功时可以重新运行同一命令并完整覆盖本地配置；首次运行后的凭据轮换和默认项目切换属于独立管理流程。

启动开发环境：

npm run dev

访问以下地址，Starter 会使用 Setup 保存的首次运行项目：

http://127.0.0.1:8087/

开发环境由 Vite 提供浏览器应用，并将 /api 请求代理至 Fastify BFF。使用 --no-install 创建项目时，需要先在生成目录中执行 npm ci。

CLI 参考

以下示例使用全局安装后的命令形式。临时执行时，可通过 npm exec --yes --package=@realsee/vr-cli@<version> -- 调用相同命令。

create

创建 Viewer 项目：

vr-cli create <directory> [options]

| 参数 | 说明 | | --- | --- | | --name <npm-name> | 指定生成项目的 npm 包名 | | --preset viewer | 使用 viewer 项目模板 | | --no-install | 生成文件后不执行 npm ci |

目标目录必须不存在或为空。未指定 --name 时，CLI 根据目标目录名称生成 npm 包名。

doctor

检查生成项目：

vr-cli doctor ./my-vrapp
vr-cli doctor ./my-vrapp --json

doctor 检查运行环境、项目结构、依赖配置和生成文件。--json 用于 CI 或其他自动化系统。

policy

输出空间能力策略：

vr-cli policy
vr-cli policy --json

--json 输出适用于自动化处理。

其他命令

vr-cli --version
vr-cli help

生成项目

目录结构

浏览器应用
├── src/app                         应用组合
├── src/features                    Viewer 功能模块
├── src/ui                          Vapor / React 界面
└── src/vr
    ├── five                        Five 初始化与生命周期
    ├── plugins                     dnalogel 与自定义插件基础设施
    └── work                        Work 数据访问

服务端
├── server/realsee-open-api.ts      Access Token 与 OpenAPI 请求
├── server/work-service.ts          Work 服务
├── server/work-route.ts            同源 HTTP 接口
└── server/index.ts                 Fastify 服务入口

项目包含以下基础实现：

• 加载 Realsee Work 并初始化 Five Viewer。
• 切换 Panorama、Mapview 和 Topview 模式。
• 接入 PanoTag 与 ModelFloorplan 功能。
• 使用 Vapor/React 构建 Viewer 界面。
• 通过同源 Fastify BFF 调用 Realsee OpenAPI。
• 提供 TypeScript、ESLint、Prettier、Vite 和项目检查配置。

生成项目核心依赖与版本要求

| 依赖 | 版本要求 | 用途 | | --- | --- | --- | | Node.js | >=22.18.0，推荐 22.23.2 | CLI 与生成项目运行环境 | | npm | >=11.19.0 | 依赖安装与项目脚本 | | @realsee/five | >=6.8.9 | 空间 Viewer 运行时 | | @realsee/dnalogel | >=3.81.2 | Five 插件能力 | | @realsee/vapor | >=0.2.12 | Viewer 界面组件 | | three | 0.117.1 | Three.js 运行时 | | react / react-dom | >=18.3.1 | 浏览器界面运行时 | | fastify | >=5.12.1 | 服务端应用运行时 |

常见问题

Node.js 版本不满足要求

确认当前版本：

node --version

在支持 nvm 的环境中，可使用生成项目固定的版本：

nvm use

开发服务提示本地配置未完成

运行 npm run setup，从 Portal 一次复制并粘贴完整配置。配置完成后重新启动开发服务。

Work 加载失败

依次确认：

1. Setup 中选择的 resourceCode 正确；
2. 开放平台应用有权访问对应资源；
3. REALSEE_GATEWAY_ENDPOINT 配置正确；
4. BFF 日志中的上游 HTTP 状态符合预期；
5. 部署环境已配置必要的身份认证和授权。

版本与分发

• npm 包：@realsee/vr-cli。
• 可执行命令：vr-cli。
• 当前版本：0.1.5。

0.x 版本可能调整模板、检查规则和生成内容。生产环境与 CI 应固定 CLI 版本，并在升级时审查生成差异。

许可证

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