如视
控制台

通过终端创建

本页目录

如果你希望自己运行命令,可以用官方命令行工具创建同一套互动应用工程。后续仍可让 AI 继续开发。

环境要求

安装 Node.js 和 npm,并确认版本:

node --version
npm --version

查询当前公开版本及其环境要求:

npm view @realsee/vr-cli@latest version engines --json

按返回的 engines 检查 Node.js 和 npm。遇到版本不兼容时,先调整运行环境,再继续安装;生成后以工程 package.json 的声明为准。

创建工程

在希望保存项目的位置运行。将 <resolved-version> 替换为上一步查到的具体版本号,将 my-vrapp 替换为新目录名;目录应为空或尚不存在:

npx --yes --package=@realsee/vr-cli@<resolved-version> -- vr-cli create ./my-vrapp
cd my-vrapp

默认创建流程会安装依赖,成功后无需再次安装。若使用了 --no-install,或拿到的是尚未安装依赖的源码副本,再执行 npm ci。

安装失败后继续

目标目录已经生成时,保留它并按 CLI 的提示在原目录恢复,不要重新执行 create。支持分阶段结果的 CLI 会用退出码 3 表示“工程已生成、依赖安装失败”;支持 create --json 时,还会返回 scaffold: "ok"、install: "failed" 以及错误分类和恢复步骤。先用该版本的 help 确认参数支持情况。

按实际原因处理环境版本、磁盘或网络问题,再按恢复指引运行 npm ci。若运行环境拒绝写入或删除,保留现场并使用允许的恢复方式,不要反复重试。其他非零退出不能仅凭目录存在就认定生成成功,应检查非敏感的工程说明和错误信息。恢复后运行工程声明的检查与构建,通过后再配置空间。

升级已有工程

已有工程可以继续使用;需要新版 Skill 或执行流程时,再进行升级。让 AI 读取 .vr-cli.json、AGENTS.md 和工程内的 Skill,确认当前版本与需求。安装新版 CLI 不会自动更新旧工程。

查询目标版本及环境要求后,使用同一个具体版本执行以下命令。先看 help 是否列出 upgrade;若没有,保留当前工程,使用该版本已支持的能力,不执行后续升级命令。

npx --yes --package=@realsee/vr-cli@<resolved-version> -- vr-cli help

支持升级时,先预览变更:

npx --yes --package=@realsee/vr-cli@<resolved-version> -- vr-cli upgrade ./my-vrapp --dry-run --json

升级会刷新 AGENTS.md、Skills 等工具文件。先把其中的定制内容保存在待替换目录之外,并核对预览中的脚本更新与数据迁移;不要假设所有文件都有自动备份。确认变更适用于当前工程后执行:

npx --yes --package=@realsee/vr-cli@<resolved-version> -- vr-cli upgrade ./my-vrapp --json

随后按更新后的工程说明安装依赖、合并定制指引,并运行构建与工程验证器。升级会保留已有依赖;若新版验证器要求的固定工具依赖与旧锁文件不一致,按更新后的工程要求只调整对应依赖及锁文件,再重新验证。

例如,从 0.3.0 升级到 0.3.1 后,若验证器提示 adm-zip 必须为 0.6.1,在工程目录执行:

npm install --save-dev --save-exact adm-zip@0.6.1
npm run build
node .agents/skills/realsee-vr-app/scripts/verify-project.mjs .

若分析数据目录迁移出现冲突,保留两份数据,核对服务端实际读取路径后再完成迁移。已有有效配置可以复用,无需因工具升级重新创建工程或发起网页确认;继续分析前重新读取工程内对应版本的 Skill。

配置与运行

选择配置与启动中的一种接入方式。默认方式是在项目目录运行:

npm run setup

按终端提示打开如视网页并完成确认。配置成功后运行:

npm run dev

打开终端显示的本地地址,确认空间正常展示并能完成一次交互。常见配置问题见配置检查。

下一步

让 AI 读取当前工程并实现你需要的功能,或参考 Five SDK和 API 文档(在新标签页中打开)自行开发。需要在线分享时,阅读发布与分享。