@realsee/vr-cli 0.1.5 → 0.2.0

package/README.md

@@ -5,7 +5,8 @@
 ## 核心能力
 
 - 通过 `create` 创建 Viewer 项目并安装依赖。
-- 通过 `doctor` 检查开发环境、项目结构、依赖配置和关键实现约束。
+- 生成项目通过 `npm run package:vibe-release` 完成干净构建并输出可上传的 Vibe Release 源码 ZIP。
+- 通过 `doctor` 检查开发环境、项目结构、发布清单、依赖配置和关键实现约束。
 - 通过 `policy` 输出版本化的空间能力策略。
 
 ## 安装与执行
@@ -41,13 +42,14 @@ CI 和自动化生成流程应使用明确版本。当前版本示例：
 
 ```bash
 npm exec --yes \
-  --package=@realsee/vr-cli@0.1.5 \
+  --package=@realsee/vr-cli@0.2.0 \
   -- vr-cli create ./my-vrapp --no-install
 
 cd ./my-vrapp
 npm ci
 npm run check
 npm run build
+npm run package:vibe-release
 ```
 
 ## 快速开始
@@ -59,9 +61,18 @@ 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` 默认走 Portal 配对：命令打印验证链接与 `XXXX-XXXX` 短码，用户在浏览器中打开链接核对并确认，命令轮询到服务端终态后原子写入 gitignored 的服务端 `.env.development`。只把命令最终输出交给用户的 Agent harness 必须使用分段流程：
 
-`npm run setup` 校验 AK、SK 和 `resourceCode` 后，原子写入 gitignored 的服务端 `.env.development`。POSIX 系统使用 `0600`，Windows 使用当前用户 ACL。首次接入未成功时可以重新运行同一命令并完整覆盖本地配置；首次运行后的凭据轮换和默认项目切换属于独立管理流程。
+```bash
+npm run setup -- --no-wait --json   # 输出 {ok:true,data:{status:"pending",...}}，退出码 2
+npm run setup -- --complete         # 用户确认后执行，轮询到终态并写盘
+```
+
+`poll_secret` 不进入 stdout、日志或命令行参数，只存在于进程内存与 `0600`、已 gitignore 的 `.realsee/pairing-continuation.json`。成功以 stdout 的 `{"ok":true,...}` 表示，判定必须用 `ok===true`（不能看 `code` 字段）；失败在 stderr 输出 `{"ok":false,"error":{code,message,hint}}`，退出码：`0` 已写入、`2` pending、`3` 用户拒绝（不得自动重发）、`4` 请求过期、`5` 网络或服务端不可用、`1` 其他错误。输出中只会出现掩码后的 AK。
+
+CI 或无人值守环境可直接提供 `REALSEE_GATEWAY_APP_KEY`/`REALSEE_GATEWAY_APP_SECRET` 环境变量：它们优先级最高，设置后跳过配对直接写盘。回退路径 `npm run setup -- --paste` 保留隐藏输入：在 Realsee China Portal 的空间应用创建页完成组织、开发者应用和空间项目选择，点击“复制本地配置”，将单行 `realsee-setup:v1:...` 配置包粘贴到隐藏输入中。配置包由 UTF-8 JSON 经 Base64URL 编码，兼容 Windows、macOS 和 Linux；Base64URL 仅提供稳定的单行传输格式，不是加密。不要把配置包放入聊天、命令参数、管道、重定向、Shell 历史、源码或日志。
+
+配对与回退路径都必须校验 AK、SK，并在提供时校验可选的 `resourceCode` fallback，然后原子写入 gitignored 的服务端 `.env.development`；省略或留空 `resourceCode` 时不会写入 `REALSEE_DEFAULT_RESOURCE_CODE`。现有三字段 v1 payload 继续兼容。POSIX 系统使用 `0600`，Windows 使用当前用户 ACL。首次接入未成功时可以重新运行同一命令并完整覆盖本地配置；首次运行后的凭据轮换和默认项目切换属于独立管理流程。
 
 启动开发环境：
 
@@ -69,14 +80,24 @@ npm run setup
 npm run dev
 ```
 
-访问以下地址，Starter 会使用 Setup 保存的首次运行项目：
+显式资源路由始终可用，建议访问：
 
 ```text
-http://127.0.0.1:8087/
+http://127.0.0.1:8087/{resourceCode}
 ```
 
+只有 setup payload 提供了可选 fallback 时，根地址 `http://127.0.0.1:8087/` 才会通过 `GET /api/work` 加载该资源；未配置 fallback 时根 Work 请求返回清晰的受控 400，且不会请求上游。
+
 开发环境由 Vite 提供浏览器应用，并将 `/api` 请求代理至 Fastify BFF。使用 `--no-install` 创建项目时，需要先在生成目录中执行 `npm ci`。
 
+生成 Vibe Release 可上传源码包：
+
+```bash
+npm run package:vibe-release
+```
+
+命令会重新执行 `npm ci` 和标准生产构建，然后生成 `release/<项目名>-node-vite-bff-v1.zip`。本地 `dist`、`node_modules`、`.env*`、凭据及编辑器/Agent 状态不会进入 ZIP；运行配置值应在 Vibe Release 中单独配置。默认 `deploy.json.requiredEnv` 仅包含 `REALSEE_GATEWAY_APP_KEY` 和 `REALSEE_GATEWAY_APP_SECRET`；`REALSEE_DEFAULT_RESOURCE_CODE` 只是可选的根路由 fallback。
+
 ## CLI 参考
 
 以下示例使用全局安装后的命令形式。临时执行时，可通过 `npm exec --yes --package=@realsee/vr-cli@<version> --` 调用相同命令。
@@ -89,11 +110,11 @@ http://127.0.0.1:8087/
 vr-cli create <directory> [options]
 ```
 
-| 参数 | 说明 |
-| --- | --- |
-| `--name <npm-name>` | 指定生成项目的 npm 包名 |
-| `--preset viewer` | 使用 `viewer` 项目模板 |
-| `--no-install` | 生成文件后不执行 `npm ci` |
+| 参数                | 说明                      |
+| ------------------- | ------------------------- |
+| `--name <npm-name>` | 指定生成项目的 npm 包名   |
+| `--preset viewer`   | 使用 `viewer` 项目模板    |
+| `--no-install`      | 生成文件后不执行 `npm ci` |
 
 目标目录必须不存在或为空。未指定 `--name` 时，CLI 根据目标目录名称生成 npm 包名。
 
@@ -158,16 +179,16 @@ vr-cli help
 
 ## 生成项目核心依赖与版本要求
 
-| 依赖 | 版本要求 | 用途 |
-| --- | --- | --- |
-| 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               | `>=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`                  | 服务端应用运行时       |
 
 ## 常见问题
 
@@ -187,13 +208,13 @@ nvm use
 
 ### 开发服务提示本地配置未完成
 
-运行 `npm run setup`，从 Portal 一次复制并粘贴完整配置。配置完成后重新启动开发服务。
+运行 `npm run setup`，在浏览器中打开打印出的验证链接并确认配对（无法轮询时用 `npm run setup -- --paste` 粘贴 Portal 配置）。配置完成后重新启动开发服务。
 
 ### Work 加载失败
 
 依次确认：
 
-1. Setup 中选择的 `resourceCode` 正确；
+1. URL 中的显式 `resourceCode` 是否正确，或根路由是否确实配置了可选的 `REALSEE_DEFAULT_RESOURCE_CODE` fallback；
 2. 开放平台应用有权访问对应资源；
 3. `REALSEE_GATEWAY_ENDPOINT` 配置正确；
 4. BFF 日志中的上游 HTTP 状态符合预期；
@@ -203,7 +224,7 @@ nvm use
 
 - npm 包：`@realsee/vr-cli`。
 - 可执行命令：`vr-cli`。
-- 当前版本：`0.1.5`。
+- 当前版本：`0.2.0`。
 
 `0.x` 版本可能调整模板、检查规则和生成内容。生产环境与 CI 应固定 CLI 版本，并在升级时审查生成差异。
 

package/agent-assets/AGENTS.md

@@ -13,13 +13,14 @@ npm run lint
 npm run format:check
 npm run check
 npm run build
+npm run package:vibe-release
 npm start
 node .agents/skills/realsee-vr-app/scripts/verify-project.mjs .
 ```
 
 Use Node.js 22.23.2 from `.nvmrc`/`.node-version`, with `engines.node` set to the oldest supported runtime floor `>=22.18.0`; the generated BFF relies on native TypeScript type stripping being enabled by default. Use npm 11.19.0 from `packageManager`. Keep `package-lock.json` authoritative, use `npm ci` for clean installs, and do not bypass `typecheck`, ESLint or Prettier.
 
-Every direct dependency except `three` must use an open `>=` minimum no lower than the generated baseline. Use `npm update` to move the lockfile to newer releases, or `npm install <pkg>@latest` to raise one declared minimum; then run `npm run check` and `npm run build`. Keep `package-lock.json` authoritative and use `npm ci` for clean installs. `three` is the only hard-locked dependency and must stay exactly at the generated version because Five targets that Three release. Updating Five, dnalogel or Vapor requires re-checking the versioned contract fixtures and validating spatial behavior in a browser. Never run `npm audit fix --force`.
+Every application dependency except `three` must use an open `>=` minimum no lower than the generated baseline. The release-only `adm-zip` development dependency must remain exactly `0.6.0`. Use `npm update` to move the application lockfile to newer releases, or `npm install <pkg>@latest` to raise one declared minimum; then run `npm run check`, `npm run build` and `npm run package:vibe-release`. Keep `package-lock.json` authoritative and use `npm ci` for clean installs. `three` must stay exactly at the generated version because Five targets that Three release. Updating Five, dnalogel or Vapor requires re-checking the versioned contract fixtures and validating spatial behavior in a browser. Never run `npm audit fix --force`.
 
 ## TypeScript rules
 
@@ -92,9 +93,10 @@ Every direct dependency except `three` must use an open `>=` minimum no lower th
 - `Mapview` is the three-dimensional overview; `Topview` is the map/floor structure.
 - Never directly edit `work.json`, downloaded Work, or customer Work. The default Viewer is read-only; persistence needs an authoritative editor/API/BFF/source contract and user confirmation. Otherwise propose a typed patch or keep the feature runtime-only.
 - Use only Work-provided, approved API/CDN or user-authorized media/model assets; never introduce an unrelated third-party URL.
-- Resolve the onboarding Work from `/` through same-origin `/api/work`, backed by the server-only `REALSEE_DEFAULT_RESOURCE_CODE`. Keep `/{resourceCode}` and `/api/work/{resourceCode}` only as explicit development compatibility routes. Never add `VITE_WORK_URL`, a local `/work.json` fallback or browser-side OpenAPI credentials.
-- The generated Fastify BFF is an example adapter: `realsee-open-api.ts` owns token exchange/cache and upstream calls, `work-service.ts` owns the framework-neutral envelope, and `work-route.ts` owns HTTP. Preserve `GET /api/work` when replacing it with Go or another backend.
-- The generated project has one `.env.example`; `npm run setup` is the only first-onboarding writer for `.env.development`. It accepts one hidden, versioned Portal payload containing AK, SK and `resourceCode`. Only the server reads `REALSEE_GATEWAY_ENDPOINT`, `REALSEE_GATEWAY_APP_KEY`, `REALSEE_GATEWAY_APP_SECRET` and `REALSEE_DEFAULT_RESOURCE_CODE`. `APP_ID` and `REALSEE_SOURCE` are optional deployment metadata.
+- Resolve Work identity from `/{resourceCode}` and call same-origin `/api/work/{resourceCode}`; this explicit route always works independently of fallback configuration. `/` and `/api/work` may use the optional server-only `REALSEE_DEFAULT_RESOURCE_CODE`; without it, the root Work route returns a controlled `RESOURCE_CODE_REQUIRED` 4xx before any upstream request. Never add `VITE_WORK_URL`, a local `/work.json` fallback or browser-side OpenAPI credentials.
+- The generated Fastify BFF is an example adapter: `realsee-open-api.ts` owns token exchange/cache and upstream calls, `work-service.ts` owns the framework-neutral envelope, and `work-route.ts` owns HTTP. Preserve `GET /api/work/{resourceCode}` and the optional root fallback contract when replacing it with Go or another backend.
+- The generated project has one `.env.example`; `npm run setup` is the only first-onboarding writer for `.env.development`. The default path pairs this machine with the Portal: it prints a verification link plus a short code, polls until the server reports a terminal state, then atomically writes the gitignored, server-only file (`0600` on POSIX, current-user ACL on Windows). `npm run setup -- --no-wait --json` starts the same request, prints one `{"ok":true,"data":{"status":"pending",...}}` envelope, and exits `2`; `poll_secret` never reaches stdout, logs or arguments, and is kept only in memory plus the 0600, gitignored `.realsee/pairing-continuation.json`. `npm run setup -- --complete` resumes that request after the user confirms in the Portal. `npm run setup -- --paste` keeps the hidden-input fallback for one versioned `realsee-setup:v1:` payload containing AK, SK and an optional `resourceCode`; existing three-field v1 payloads remain supported. `REALSEE_GATEWAY_APP_KEY`/`REALSEE_GATEWAY_APP_SECRET` environment variables take precedence over both paths and skip pairing. Success prints `{"ok":true,...}` on stdout — judge it with `ok===true`, never a `code` field — and only a masked AK appears anywhere in the output; failures print `{"ok":false,"error":{code,message,hint}}` on stderr with exit code `0` written, `2` pending, `3` denied, `4` expired, `5` service unavailable, `1` otherwise. Never re-send a denied request automatically.
+- Only the server reads `REALSEE_GATEWAY_ENDPOINT`, `REALSEE_GATEWAY_APP_KEY`, `REALSEE_GATEWAY_APP_SECRET` and optional `REALSEE_DEFAULT_RESOURCE_CODE`. The default `deploy.json.requiredEnv` contains only AK/SK; `APP_ID` and `REALSEE_SOURCE` are optional deployment metadata.
 - Keep the real `REALSEE_GATEWAY_APP_SECRET`, AK/SK and token in the BFF environment or secret manager. They must not enter `VITE_*`, `src/`, Vite `define/envPrefix`, browser requests, logs or bundles.
 - AK/SK authorize the BFF's upstream access. If an internet-facing deployment requires caller or tenant authorization, enforce it before the Work route; never satisfy that requirement by exposing AK/SK to the browser.
 - Construct and append Five only after its host has positive dimensions; use `five.refresh` for later positive resizes.
@@ -104,7 +106,7 @@ Every direct dependency except `three` must use an open `>=` minimum no lower th
 
 ## Validation
 
-Run type checking and production build. For spatial changes, validate at `http://127.0.0.1:8087/` in a real browser; the template uses local IPv4 loopback and non-privileged port 8087, not privileged port 517. Inspect Five state/readiness, native surface dimensions, spatial-tag anchors/renderers, Three coordinates/resources, plugin lifecycle, layer rectangles and hit targets rather than relying only on screenshots.
+Run type checking and production build. For spatial changes, validate at `http://127.0.0.1:8087/{resourceCode}` in a real browser; use `/` only when the optional server fallback is configured. The template uses local IPv4 loopback and non-privileged port 8087, not privileged port 517. Inspect Five state/readiness, native surface dimensions, spatial-tag anchors/renderers, Three coordinates/resources, plugin lifecycle, layer rectangles and hit targets rather than relying only on screenshots.
 
 ## Model floorplan contract