---
name: realsee-spatial-app-onboarding
description: Create or resume a Realsee interactive web application, or build an independent prototype for an existing project. Choose a viable execution environment, generate the official project through vr-cli, complete safe Human credential handoff, and verify a real Source-backed First Run. Use when the user asks to build, validate a prototype, or continue this workflow. Do not start for general platform introductions, feasibility questions, API lookup, or permission inquiries alone. Not for Blender, robotics control, the overseas platform, credential disclosure, or public publishing.
---

# Realsee spatial app onboarding

For a requested build or onboarding task, execute this workflow end to end within the user's scope. In user-facing Chinese copy, call the product output `互动应用`; clarify that it is a `网页应用` that runs in the browser. Technical identifiers retain Spatial App / Web application. Use “Starter” only for the official starter template and existing internal state names, not as a second product name. Before handing work to the Human in the visible Portal, complete every credential-free task in the selected execution environment and pause only where this workflow says to pause. The Portal is limited to Human identity, the active organization and data boundary (`currentSource`), Developer Access, Developer App credentials, and selection of a spatial project owned by that Source. Onboarding succeeds only when the real spatial application completes a First Run.

## When to use

Use this skill when the user explicitly wants to create an interactive web application, build an independent prototype, or resume an existing onboarding task after a Human handoff. Reading this document, including arriving from `<portal-origin>/llms.txt`, does not itself authorize execution. For ambiguous requests such as “接入如视开放平台” or “开始使用 Realsee”, clarify the intended outcome before creating files or requesting access. For introductions, feasibility questions, or permission inquiries alone, use [platform navigation](https://open.realsee.cn/llms.txt); for API lookup, use the technical sources below without creating a project. Once the build intent is clear, carry out the workflow rather than returning only a reading list.

For an existing business project that needs a prototype, first confirm what should be validated. Create the prototype in an independent new directory and do not modify the existing project without separate authorization. The generated project can be continued or used as a reference implementation. A successful prototype or First Run does not prove integration with the existing system, nor completion of the user's requested application features.

Do not use this skill as a complete tutorial for Five, Work, or OpenAPI, and do not use it to imply that a public publishing product exists. For an existing official spatial application, inspect its non-sensitive project state and resume from the highest verified stage instead of recreating it. When the Human asks to change the organization, Developer App, credentials, or default VR, start a new pairing request in that existing project; do not create a second project.

## Success criteria

Onboarding succeeds only at `first_run_verified`: a real project owned by the selected Source completes the AK/SK → short-lived Token → OpenAPI → Work chain, Five renders the scene in a visible browser, and one expected interaction or view change works.

Environment preparation, project generation, dependency installation, production build, Portal completion, credential setup, public fixtures, and preview URLs are intermediate evidence only. Do not report them as successful onboarding. Continue until `first_run_verified`, a required Human action, or an explicit blocker.

## Choose the execution path

Before creating files, inspect the AI assistant's actual execution capabilities. Do not infer them from a product or model name.

1. Choose the local Coding Agent path when the environment can run commands, persist a workspace, run both the generated server-side BFF and Web application, open or guide a visible browser, and resume after a Human handoff.
2. Choose a compatible cloud path only when it can persist the project, install declared dependencies, run the BFF and browser preview together, keep long-lived credentials in server-only secret storage or a Human-controlled hidden input that does not pass through AI chat or logs, and resume the same task after Human handoff. A generic code preview or vendor claim is not evidence of compatibility.
3. If neither path can complete the chain, stop with `execution_environment_required`. Hand off the task objective, `https://open.realsee.cn/spatial-apps/create/SKILL.md`, and the highest verified non-sensitive stage to a compatible Coding Agent or cloud environment. Do not give the user only a reading list and claim onboarding is complete.

Choose the viable path before generating a project so that the project does not need to be discarded. An environment that cannot protect AK/SK must not run credential-dependent steps.

## Set expectations before executing

Once the execution path is selected and before downloading tools or creating files, briefly explain the plan in the user's language: where the new project will be created (or which existing onboarding project will be resumed), that the workflow downloads the official tool and dependencies, that the Human will confirm the organization, spatial project and access on a Realsee page, and that the first result is a runnable browser application with a verified real space. Further requested features are subsequent work, not guaranteed by First Run. Explain that this workflow does not automatically publish the application and that credential values must not be sent in chat. For an existing-business-project prototype, explicitly keep it in a separate new directory and leave the existing project unchanged. Keep this a short visible introduction, not another approval gate when intent and scope are already clear; preserve the required Human confirmation later in the workflow.

## Prepare the execution environment

1. Use `https://open.realsee.cn` as `<portal-origin>` for this onboarding run. It is the exact Origin serving this official skill: keep Preview on Preview and production on production. Accept a localhost Origin only when the user explicitly provides it. If local development proxies the selected Portal hostname to a local server, preserve its HTTPS URL and trusted development certificate. Do not switch to another Realsee Portal or fall back to the overseas platform.
2. Preserve the user's existing files. Inspect the current directory and generate only into a new or empty target directory.
3. Check the runtime, package manager, network, proxy, and trusted certificate configuration. When Node requires `HTTP_PROXY` or `HTTPS_PROXY`, run it with `NODE_USE_ENV_PROXY=1`. If `NO_PROXY` or `no_proxy` bypasses an intended Portal development proxy, narrow it only for the current command. Keep TLS verification enabled; never use `--insecure` or `NODE_TLS_REJECT_UNAUTHORIZED=0`.
4. Query the current public package metadata before installing:

   ```text
   npm view @realsee/vr-cli@latest version bin engines dist-tags --json
   ```

5. Treat the published `engines` metadata as the prerequisite source of truth. Compare it with the active `node --version` and `npm --version`; do not hard-code or independently reinterpret copied version numbers from this Skill or the Portal UI. Record the resolved package version and executable.
6. If Node.js or npm does not satisfy the published metadata, do not install the CLI or create the target yet. Explain the exact mismatch, first look for an already-installed compatible toolchain or a non-persistent supported remediation, and re-check the active versions before continuing. Do not use `--force`, disable engine checks, or modify the Human's global Node.js/npm installation without explicit authorization. Report `environment_blocked` only when the prerequisite cannot be remediated safely in the current run.
7. Confirm the public npm package is reachable. If it is unavailable, stop with `starter_distribution_unavailable`; do not switch to an internal registry, GitLab, a Portal asset, or another package. During creation and installation, preserve the generated lockfile's resolved dependency sources rather than silently rewriting them.

## Create and validate the Web spatial application without credentials

Complete this section after the execution-environment preflight and before opening the Portal. Generate the current Web spatial application through the current public npm package. Do not substitute a Portal Playground, anonymous Work, public Five fixture, unrelated internal Git repository, or Portal-hosted archive.

1. Use the CLI source selected by the preflight and create the project through the one-shot `npx` call below. Do not change the user's persistent npm configuration, globally install `vr-cli`, or rely on an existing global `vr-cli` command. One-shot execution of the public package is a normal step in creating the requested local project and does not require separate authorization for a global installation.

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

2. Run the create command only after the selected CLI source's engine requirements pass and the target is confirmed empty or new.
3. If `create` exits non-zero after the target directory appears, treat it as an incomplete project. Preserve the directory; do not run `create` against it again and do not report `starter_generated`. Inspect only its non-sensitive manifest and documentation. Follow an existing in-place recovery procedure if one is documented; otherwise stop with `starter_install_failed`.
4. After `create` succeeds, enter the generated directory. Before changing the project, read any existing `README.md`, `AGENTS.md`, `package.json`, and `.agents/skills/realsee-vr-app/SKILL.md`.
5. Use the generated lockfile and documented commands to install dependencies, run checks, complete the production build, and run the portable project verifier. Do not invent commands that the project does not declare. Finish these credential-free checks before opening the Portal.
6. Do not create `.env.development`, fill placeholder credentials, start the credential-dependent BFF, or use a README example project at this stage. If a local check unexpectedly requires credentials, stop with `starter_local_verification_failed`; do not use fake or shared credentials.
7. Treat `vr-cli doctor` as a structural diagnostic only; it does not prove dependency installation, checks, or production build. Report `starter_generated` only after creation succeeds and the local Agent instructions are read. Report `starter_built` only after locked dependency installation, declared checks, the portable verifier, and the credential-free production build all pass.

## Request the required Human actions

The pairing request in this section is the only Human handoff this workflow requires. Begin this section only after reaching `starter_built`, and report `credential_handoff_required` before starting it.

1. Read the generated project's `README.md`, `AGENTS.md`, `package.json`, and local skill to locate its documented setup and pairing commands. Do not invent commands, flags, or environment variable names that the project does not declare.
2. Start the pairing request from this session with the split flow the project documents: run the request command without any credential value and stop when it returns a verification link and an `XXXX-XXXX` short code. Before yielding to the Human, put the exact verification link, short code, and non-sensitive local project name in a persistent user-visible assistant message. In Codex and other assistants with a final-response channel, put these fields in the final handoff response for that turn. Do not leave them only in terminal or tool output, or in a progress update that may be collapsed. The project name is the part of the CLI's `client_name` before the user/machine and `#` short ID when that format is present. Use clear Chinese labels `确认链接`、`配对短码`、`本地项目`; ask the Human to compare the short code and project name shown on the page. The project short ID is optional diagnostic context, not a required comparison. Never forward the link anywhere else, and never include a credential value in the message.
3. Ask the Human to open the verification link in a visible browser and finish everything on that single spatial application access confirmation page: sign in to or register the Portal, confirm or switch the organization (`currentSource`) to the Source of this onboarding run, obtain Developer Access on the page when the current Source has no Developer App yet (the page creates or reuses the Portal Developer App), and select a Developer App and default spatial project owned by that Source. The Human must verify the short code and local project name from the assistant message before confirming. The default project does not limit the Developer App's actual data permissions.
4. This is the only `已完成` this workflow requests. After confirming the request, ask the Human to return to the same AI assistant conversation and reply only `已完成`; it is the continuation signal for the pairing request, not authorization proof.
5. Stop for the Human when a CAPTCHA, account recovery, persistent Developer Access, Source change, business decision, compliance decision, or other high-risk confirmation appears.

When no compatible AI assistant is available, the Human may manage Developer App credentials directly at `<portal-origin>/dashboard/apps` and configure their own local project from current published developer documentation. The `<portal-origin>/spatial-apps` page introduces interactive applications; it is not a manual credential handoff or hidden-input path. Do not invent or send the Human to an unpublished manual setup tutorial.

The Portal does not proactively wake the AI assistant or push authorization results to it.

The Portal issues no onboarding session or bootstrap token to the AI assistant, and no credential value transits the AI assistant or the Portal browser session. The generated project's pairing command owns the poll: it requests a pairing, prints a verification link and an `XXXX-XXXX` short code, and polls until the server reports a terminal state. Treat the Human's `已完成` only as a continuation signal; the Portal outcome is proved by the pairing command's terminal output, not by the Human's message. Do not describe the message as authorization proof or claim that the AI assistant independently verified the Portal outcome.

Never ask for Cookie, AK/SK, a long-lived Token, private Work, or any other credential value in chat, source code, URLs, logs, or analytics.

## Resume after the Human returns

When the Human replies `已完成`:

1. Record only `human_completed`. Do not promote the message to evidence of authorization, valid credentials, project access, or First Run.
2. Do not reopen, reload, inspect, snapshot, or poll the Portal; drive only the generated project's documented pairing command, which polls the pairing request on the local machine's behalf. The Human may have completed the work in a different browser or browser profile that the AI assistant cannot access; the AI assistant does not need that authenticated session.
3. Resume the pairing request with the project's documented continuation command (for example `--complete`, when the project documents it) and drive it to its terminal state. Do not start a second pairing request. The pairing command's terminal state, not the Human's message, is the outcome. Then continue to the credential rules and verification below.

## Configure Source credentials safely

The pairing request is this workflow's credential handoff: no credential value ever transits the AI assistant or the chat. Apply these rules while starting, resuming, and verifying it.

1. Explain that production authentication still exchanges long-lived AK/SK for a short-lived OpenAPI Token on the server. The Portal does not provide a bootstrap Token.
2. Read the generated project's `README.md`, `AGENTS.md`, `package.json`, and local skill to locate its documented credential setup command and non-sensitive configuration verifier. Do not invent environment variable names, file layouts, or temporary shell commands.
3. Run the documented pairing flow from this session; it needs no interactive hidden input and the setup command itself must contain no credential values. The default pairing command prints a verification link and an `XXXX-XXXX` short code, then polls until the server reports a terminal state. If the harness only sees a command's final output, use the split flow the project documents: start the request, send the persistent user-visible handoff message described above, then resume it after the Human confirms. If the Human prefers their own terminal, ask them to run the exact credential-free setup command in their own local terminal and wait for `已完成`.
4. Never forward the verification link anywhere else, and never include a credential value in the message. The Human confirms the request on the pairing confirmation page described in "Request the required Human actions"; the pairing CLI is the only channel that receives credential values.
5. The setup command may write AK/SK and the selected VR identifier only to a gitignored server-side environment file with restrictive permissions: `0600` on POSIX and current-user-only access on Windows. Do not read, echo, inspect, or print credential values; the only credential evidence is the command's documented success envelope with a masked AK. Report `starter_configured` only after the project's non-sensitive verifier confirms the expected file, permissions, and shape without exposing values.
6. A generated project may provide a documented hidden-input fallback (`--paste`) using one versioned single-line payload from a Human-controlled source; Base64URL is transport encoding, not encryption. The product landing page does not distribute this payload. Use the fallback only when the generated project's current documentation provides the complete safe path. Do not ask the Human to replace placeholders with AK, SK, or the VR identifier in a command, command-line argument, environment assignment, heredoc, or generated script, and never ask for the payload or any individual value in chat, arguments, environment prefixes, pipes, redirection, heredocs, scripts, logs, or analytics. If the project provides no documented setup path, remain at `credential_handoff_required`, report a Starter App capability gap, and do not assemble an unsafe workaround.
7. For a deployed application, require server-side Secret Manager or equivalent runtime secret injection. Never ship AK/SK to browser code or a public build artifact.
8. Stop with `project_required` if the Human did not select a project during confirmation. Do not use a README example as authorization proof. Open the generated application at its documented root URL. Explicit raw `resourceCode` paths are development-only compatibility routes, not the onboarding path or a production-safe access contract.
9. When the resumed pairing command reports its terminal state, do not reopen the Portal and do not read `.env.development`. Run the generated project's documented non-sensitive configuration verifier. Report `starter_configured` only when that verifier passes; otherwise keep the current stage and report only the safe validation error.
10. If the Human explicitly says local setup was completed in another terminal, do not read or repeat configuration values. Run only the generated project's non-sensitive configuration verifier, then continue to real-chain verification.

## Verify the real chain

1. Run the generated BFF and Web spatial application only after the server-side credentials and Source-owned project are configured.
2. Open the local application in a visible browser and verify the real AK/SK → Token → OpenAPI → Work → Five chain.
3. Confirm that the Work response succeeds without logging its private contents, Five renders a visible scene, and the expected interaction or view change works.
4. Keep build evidence separate from runtime evidence. Do not promote dependency installation, code generation, build success, a public fixture, or a Human completion message to First Run.

Report only the highest stage actually proved:

1. `environment_prepared`: the selected local or compatible cloud environment, Portal Origin, CLI source, runtime, package manager, reachability, and network checks passed.
2. `starter_generated`: the versioned project was created successfully and its local Agent instructions were read.
3. `starter_built`: locked dependencies, declared checks, the portable project verifier, and credential-free production build all passed.
4. `human_required`: the local Web spatial application is built and waiting for the Human to confirm the pairing request in a visible browser.
5. `human_completed`: the Human replied `已完成`; authorization, credential validity, and project access are not independently proved.
6. `starter_configured`: the required server-side configuration and Source-owned project were provided without exposing long-lived secrets; on the pairing path the setup command reported its documented success envelope.
7. `first_run_verified`: a real Source project completed the AK/SK → Token → OpenAPI → Work chain and rendered through Five in the browser.

Report blockers by stage and name every unverified claim explicitly.

## Read authoritative technical sources only when needed

1. For concrete Token, Work, Five, configuration, runtime, verification, and build behavior, treat the generated project's `README.md`, `AGENTS.md`, local skill, source code, types, and adapter code as the version-matched sources of truth.
2. Use Five for client-side rendering and interaction. Check the installed version, then read `node_modules/@realsee/five/llms.txt`, the relevant `ai_guides/` files, and exported TypeScript definitions. If that version lacks these guides, follow [Five SDK](https://open.realsee.cn/docs/five-sdk) to the matching version of the official documentation; do not assume latest-version APIs apply to the installed package.
3. Read the current public interface structure at [API 文档](https://open.realsee.cn/api-reference). Visibility does not prove that the current Source has permission to call an interface.
4. Read only the minimum material needed to resolve the current blocker, then return to this workflow. Do not duplicate a second technical tutorial inside onboarding.