diff --git a/.agents/skills/argus/SKILL.md b/.agents/skills/argus/SKILL.md index 42eb902..d90f6a5 100644 --- a/.agents/skills/argus/SKILL.md +++ b/.agents/skills/argus/SKILL.md @@ -42,7 +42,7 @@ Resolve values in the existing order: && [ -n "${REALSEE_REGION:-}" ] && echo present || echo missing ``` -2. If `~/.realsee/credentials` already exists, load it into the shell and probe presence. Never display the file: +2. If configuration is incomplete and `~/.realsee/credentials` already exists, load it into the shell and probe presence. Never display the file: ```bash [ -f ~/.realsee/credentials ] && set -a && . ~/.realsee/credentials && set +a; \ @@ -77,11 +77,10 @@ The downloader publishes the directory only after every file passes its manifest Before starting, ensure the user has selected the files and consented to sending them to Realsee for remote processing. An explicit request to upload those files is sufficient; file selection alone is not consent. If either is missing, ask one question stating that the selected files will leave the machine. Reuse existing consent for the same input and scope. Do not ask a redundant second confirmation. -For repeated images: +Run lifecycle commands in a shell with credentials resolved in step 2. For repeated images: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs start \ +node /scripts/run-argus.mjs start \ --image "/absolute/path/a.jpg" \ --image "/absolute/path/b.webp" \ --workspace "/absolute/workspace-root" \ @@ -91,14 +90,13 @@ set -a; . ~/.realsee/credentials; set +a; \ For an existing ZIP: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs start \ +node /scripts/run-argus.mjs start \ --zip "/absolute/path/input.zip" \ --workspace "/absolute/workspace-root" \ --yes --json ``` -If credentials already exist in the inherited shell, omit the `source` prefix. Capture `workspace_dir` from the JSON response; it is the durable run handle for later commands. +When starting a new shell for `status` or `collect`, resolve credentials there before invoking the command. Capture `workspace_dir` from the JSON response; it is the durable run handle for later commands. `start` validates and packages locally, uploads one ZIP, submits once, persists `task_code`, and returns. It does not poll in the background. Never automatically rerun `start` after `submission_unknown`: the submit operation is not idempotent and a blind retry may create a duplicate task. @@ -107,8 +105,7 @@ If credentials already exist in the inherited shell, omit the `source` prefix. C Run one status query: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs status \ +node /scripts/run-argus.mjs status \ --workspace "" --json ``` @@ -119,8 +116,7 @@ Interpret `task_status` as `queued`, `processing`, `succeeded`, or `failed`. Whe When the task succeeds, run: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs collect \ +node /scripts/run-argus.mjs collect \ --workspace "" --json ``` diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index fde595c..106ac54 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -46,11 +46,12 @@ body: id: environment attributes: label: Environment - description: Include OS, Node.js version, npm version, and relevant sanitized configuration names. + description: Include OS and agent host; for Argus include Node.js/npm versions and sanitized configuration names, or for local reconstruction include the Blender version. placeholder: | OS: Node: - npm: + npm (Argus): + Blender (local reconstruction): REALSEE_REGION: validations: required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 9e3d1a4..375dc22 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -32,7 +32,7 @@ body: id: validation attributes: label: Runtime context - description: Explain whether this affects async mode, live mode, local installation, or agent runtime usage. + description: Explain whether this affects Argus start/status/collect, local Blender reconstruction, installation, or agent runtime usage. validations: required: true - type: checkboxes diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b34a3eb..3723b51 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,6 +14,6 @@ - [ ] The change is scoped to one problem. - [ ] Documentation reflects changed commands, configuration, release gates, or skill usage. -- [ ] Source skill changes were rebuilt into `plugins/realsee-skills/` when needed. +- [ ] Source skill changes were rebuilt into `plugins/realsee-skills/` and, for Argus, `arkclaw/argus/` when needed. - [ ] No secrets, generated credentials, account identifiers, private URLs, GLB files, or temporary workspaces are committed. - [ ] This change is a maintainer-controlled update, not an unsolicited roadmap or product feature proposal. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 0cb0b22..c216ab6 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -2,7 +2,7 @@ [English](ARCHITECTURE.md) | [简体中文](ARCHITECTURE.zh-CN.md) -Argus Skill 2.0 has one canonical source, an explicit persisted lifecycle, and generated packages for each supported agent host. +Realsee Skills keeps canonical skill sources under `.agents/skills/` and generates host-specific distribution packages. Argus provides a Node.js remote-processing runtime; Blender reconstruction is a local instruction skill. The additional instruction skill `.agents/skills/realsee-blender-reconstruction/` handles existing exports in local Blender. Claude packaging discovers canonical skill directories and checks byte consistency for all of them; it does not require an npm runtime for instruction-only skills. The Argus lifecycle and Arkclaw overlays below remain Argus-specific. @@ -22,6 +22,11 @@ The additional instruction skill `.agents/skills/realsee-blender-reconstruction/ ├── argus-output.schema.json JSON Schema 2020-12 output union └── migration-v2*.md Bilingual 1.x migration guide +.agents/skills/realsee-blender-reconstruction/ Canonical local modeling instructions +├── SKILL.md / SKILL.zh-CN.md Agent workflow +├── README.md / README.zh-CN.md User documentation +└── references/ Registration, modeling, performance, acceptance, extensions + plugins/realsee-skills/ Generated Claude plugin copy arkclaw/argus/ Generated Arkclaw copy with deterministic CN-only overlays release-channel.json Release maturity and version metadata @@ -84,24 +89,19 @@ The file-token response is an in-memory upload lease. `bucket + region + prefix` ## Distribution flow ```text - .agents/skills/argus - canonical source - ┌──────────────┼──────────────┐ - │ │ │ - ▼ ▼ ▼ - Claude plugin copy Codex / npx Arkclaw copy - byte-identical direct source canonical bytes + - CN-only overlays +.agents/skills/argus/ -> Claude plugin / npx skills / Codex installer + -> Arkclaw (CN-only overlays) +.agents/skills/realsee-blender-reconstruction/ -> Claude plugin / npx skills ``` `npm run rebuild` regenerates Claude and Arkclaw packages and checks them against canonical bytes. Deterministic Arkclaw overlays force `REALSEE_REGION=cn` in `scripts/run-argus.mjs`, restrict `scripts/download-examples.mjs` to CN, and make the generated Skill, README, and example guides state the same limitation. All remaining files must match canonical source byte-for-byte. ## Validation and release -`npm run ci` runs secret scanning, bilingual-doc checks, AI-index checks, repository-boundary checks, Skill validation, distribution regeneration and consistency checks, release metadata validation, and the full Skill test suite. +`npm run ci` runs secret scanning, bilingual-doc checks, AI-index checks, repository-boundary checks, Skill validation, distribution regeneration and consistency checks, release metadata validation, repository tests (`test:repo`), and Argus runtime tests (`test:skill`). These checks validate packaging and contracts; they do not execute a Blender reconstruction or a live Argus task. -Version `v1.0.2` remains the frozen legacy line. Version 2.0 follows this promotion order: publish uploader 0.1.1, cut `v2.0.0-rc.3`, complete real CN and global E2E (including partial/error collection), then mark `v2.0.0` stable. Until both regions pass, release metadata remains preview/development with a pending stable gate. +`release-channel.json` currently records Argus 2.0.0 as stable with a passed stable gate. It records Argus release readiness, not Blender acceptance. `v1.0.2` remains the frozen legacy line; the `v2.0.0` tag contains Argus only. See the [release guide](docs/release.md) for current gate requirements and the historical 2.0 promotion sequence. ## Generated files -Do not edit `plugins/realsee-skills/**` or `arkclaw/argus/**` by hand. Edit `.agents/skills/argus/**` and the narrow Arkclaw overlay generator, then run `npm run rebuild`. +Do not edit `plugins/realsee-skills/**` or `arkclaw/argus/**` by hand. Edit the relevant source under `.agents/skills/**`; change the Arkclaw overlay generator only for Argus-specific distribution differences. Then run `npm run rebuild`. diff --git a/ARCHITECTURE.zh-CN.md b/ARCHITECTURE.zh-CN.md index 5cbdc42..272393d 100644 --- a/ARCHITECTURE.zh-CN.md +++ b/ARCHITECTURE.zh-CN.md @@ -2,7 +2,7 @@ [English](ARCHITECTURE.md) | 简体中文 -Argus Skill 2.0 使用一个 canonical source、显式持久化生命周期，以及面向不同 agent host 的生成包。 +Realsee Skills 将所有规范 skill 源码保存在 `.agents/skills/`，并生成面向各宿主的分发包。Argus 提供 Node.js 远程处理运行时；Blender 重建是本地指令型 skill。 新增的指令 skill `.agents/skills/realsee-blender-reconstruction/` 在本地 Blender 中处理已有导出。Claude 打包发现规范 skill 目录，并逐个检查字节一致性；纯指令 skill 不要求 npm 运行时。下文 Argus 生命周期和 Arkclaw overlay 仍仅适用于 Argus。 @@ -22,6 +22,11 @@ Argus Skill 2.0 使用一个 canonical source、显式持久化生命周期， ├── argus-output.schema.json JSON Schema 2020-12 输出联合 └── migration-v2*.md 双语 1.x 迁移指南 +.agents/skills/realsee-blender-reconstruction/ 规范本地建模指令 +├── SKILL.md / SKILL.zh-CN.md Agent 工作流 +├── README.md / README.zh-CN.md 用户文档 +└── references/ 配准、建模、性能、验收与按需扩展 + plugins/realsee-skills/ 生成的 Claude plugin copy arkclaw/argus/ 带确定性 CN-only overlay 的 Arkclaw copy release-channel.json 发布成熟度与版本元数据 @@ -84,24 +89,19 @@ Gateway 基础地址与凭证/region 合同不变，只替换 Argus 接口： ## 分发流 ```text - .agents/skills/argus - canonical source - ┌──────────────┼──────────────┐ - │ │ │ - ▼ ▼ ▼ - Claude plugin copy Codex / npx Arkclaw copy - 字节一致 直接用 source canonical bytes + - CN-only overlay +.agents/skills/argus/ -> Claude plugin / npx skills / Codex installer + -> Arkclaw (CN-only overlays) +.agents/skills/realsee-blender-reconstruction/ -> Claude plugin / npx skills ``` `npm run rebuild` 重新生成 Claude 与 Arkclaw 包，并与 canonical bytes 比较。确定性的 Arkclaw overlay 会在 `scripts/run-argus.mjs` 中强制 `REALSEE_REGION=cn`、把 `scripts/download-examples.mjs` 限制为 CN，并让生成后的 Skill、README 与示例指南明确同一限制；其余文件必须与 canonical source 字节级一致。 ## 校验与发布 -`npm run ci` 依次运行 secret 扫描、双语文档、AI 索引、仓库边界、Skill 校验、分发生成与一致性检查、发布元数据校验和完整 Skill 测试。 +`npm run ci` 依次运行 secret 扫描、双语文档、AI 索引、仓库边界、Skill 校验、分发生成与一致性检查、发布元数据校验、仓库测试（`test:repo`）和 Argus 运行时测试（`test:skill`）。这些检查验证打包与合同，不执行 Blender 重建或真实 Argus 任务。 -`v1.0.2` 保持为冻结的旧版本。2.0 按以下顺序发布：先发布 uploader 0.1.1，再切 `v2.0.0-rc.3`，完成 CN/Global 真机 E2E（含 partial/error 收集），最后把 `v2.0.0` 标记为 stable。两区都通过前，release metadata 保持 preview/development，stable gate 为 pending。 +`release-channel.json` 当前记录 Argus 2.0.0 为 stable，stable gate 为 passed；它记录 Argus 发布就绪状态，不代表 Blender 验收。`v1.0.2` 保持为冻结旧版本，`v2.0.0` 标签仅包含 Argus。当前门禁要求与首次 2.0 发布历史见[发布指南](docs/zh-CN/release.md)。 ## 生成文件 -不要手工修改 `plugins/realsee-skills/**` 或 `arkclaw/argus/**`。修改 `.agents/skills/argus/**` 和窄范围 Arkclaw overlay generator，然后运行 `npm run rebuild`。 +不要手工修改 `plugins/realsee-skills/**` 或 `arkclaw/argus/**`。修改 `.agents/skills/**` 下对应源码；只有 Argus 分发差异涉及 overlay 时才修改 Arkclaw 生成器，然后运行 `npm run rebuild`。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf5f3af..ed76c9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,8 +7,8 @@ Realsee Skills is published to expose supported skill capabilities. External pul ## Before You Start 1. Read the relevant skill README under `.agents/skills/`. -2. Check `release-channel.json` for the current skill state. -3. Avoid committing generated outputs, credentials, account identifiers, private URLs, `.env` files, downloaded Argus archives, extracted artifacts, or temporary workspace files. +2. Check `release-channel.json` for Argus release readiness and the selected skill README for its scope. The release metadata does not track Blender scene acceptance. +3. Avoid committing private runtime outputs, credentials, account identifiers, private URLs, `.env` files, downloaded Argus archives, extracted artifacts, or temporary workspace files. ## Maintainer Development Flow @@ -32,6 +32,8 @@ npm run validate:docs npm run ci ``` +For Blender instruction changes, run `npm run validate:skills`, `npm run rebuild`, and `npm run ci`. When changing modeling behavior, verify the affected workflow using local evidence; documentation validation alone is not a Blender execution test. Keep English and Chinese instructions aligned. Generated Claude and Arkclaw distribution files are tracked and must be included when rebuilding changes them. + ## Pull Request Checklist - The change is scoped to one problem. @@ -45,7 +47,7 @@ npm run ci New skill packages are added by Realsee maintainers after the capability, API contract, and release gate are approved. A new skill package should include: - `SKILL.md` with accurate frontmatter -- A skill `README.md` -- Tests with injectable fakes for upload, gateway, and download paths +- Bilingual user documentation (`README.md` and `README.zh-CN.md`) and a bundled `LICENSE` +- Tests with injectable fakes for upload, gateway, and download paths when a runtime uses those services; instruction-only skills need task-relevant verification instead - References for external API contracts when remote services are involved - Explicit consent language for workflows that upload local files diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md index 0b99d6d..2bfae4d 100644 --- a/CONTRIBUTING.zh-CN.md +++ b/CONTRIBUTING.zh-CN.md @@ -7,8 +7,8 @@ Realsee Skills 用于公开受支持的 skill 能力。外部 pull request 不 ## 开始之前 1. 阅读 `.agents/skills/` 下相关 skill 的 README。 -2. 检查 `release-channel.json` 中的当前 skill 状态。 -3. 避免提交生成产物、凭证、账号标识、私有 URL、`.env` 文件、下载的 Argus 压缩包、解压产物或临时 workspace 文件。 +2. 检查 `release-channel.json` 中的 Argus 发布就绪状态，以及所选 skill README 的适用范围；发布元数据不记录 Blender 场景验收。 +3. 避免提交私有运行产物、凭证、账号标识、私有 URL、`.env` 文件、下载的 Argus 压缩包、解压产物或临时 workspace 文件。 ## 维护者开发流程 @@ -32,6 +32,8 @@ npm run validate:docs npm run ci ``` +修改 Blender 指令时，运行 `npm run validate:skills`、`npm run rebuild` 和 `npm run ci`。改变建模行为时，使用本地资料验证受影响的流程；文档校验不等于 Blender 执行测试。保持中英文指令一致。Claude 和 Arkclaw 的生成分发文件受版本控制，重建产生变化时应一并纳入修改。 + ## Pull Request 检查项 - 改动只解决一个明确问题。 @@ -45,7 +47,7 @@ npm run ci 新的 skill 包由 Realsee 维护者在能力、API 合同和发布门禁获批后加入。新的 skill 包应包含： - 带准确 frontmatter 的 `SKILL.md` -- skill `README.md` -- 对 upload、gateway、download 路径可注入假对象的测试 +- 双语用户文档（`README.md` 和 `README.zh-CN.md`）及随附 `LICENSE` +- 运行时涉及 upload、gateway、download 服务时，对相应路径提供可注入 fake 的测试；纯指令 skill 使用与实际任务相关的验证 - 涉及远程服务时的外部 API 合同引用 - 对上传本地文件流程的明确同意说明 diff --git a/README.md b/README.md index dbabad4..7e4b12a 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ English | [简体中文](README.zh-CN.md) Realsee Argus is a world-leading 3D vision foundation model. From a photo, panorama, or sparse views, it reconstructs metric 3D structure in milliseconds: pose, depth, point clouds, and renderable geometry. -Realsee Skills provides the Argus agent and CLI workflow. The Argus Skill is `argus` 2.0: it processes 1–99 exact 2:1 panoramas and produces EXR depth maps, one merged GLB point cloud, per-image camera poses, optional intrinsics, and a validated local result index. +Realsee Skills provides two workflows: Argus remote processing and local editable Blender space reconstruction. The Argus Skill is `argus` 2.0: it processes 1–99 exact 2:1 panoramas and produces EXR depth maps, one merged GLB point cloud, per-image camera poses, optional intrinsics, and a validated local result index. The Skill ID remains `argus`. Version 2.0 has no legacy single-image VGGT fallback. Pin `v1.0.2` when a workflow needs square 1:1 input, the old single-GLB-only result, or the old H5 preview behavior. @@ -33,7 +33,7 @@ The installable Skill 2.0 contract remains intentionally specific: **1–99 loca | [argus](.agents/skills/argus/SKILL.md) | Panoramas → depth, point cloud, poses | Realsee remote processing | | [realsee-blender-reconstruction](.agents/skills/realsee-blender-reconstruction/README.md) | Existing exports → editable Blender space; optional walkthrough and physics export | Local Blender, no API credentials for local inputs | -Install the Blender skill from this local checkout with `npx skills add . --skill realsee-blender-reconstruction --agent codex`. The Claude plugin includes both skills after `npm run rebuild`; Arkclaw remains the Argus-specific distribution. The Argus credential and CLI sections below apply to `argus`. +Install the Blender skill from this local checkout with `npx skills add . --skill realsee-blender-reconstruction --agent codex`. The current Claude plugin includes both skills; Arkclaw and `npm run install:codex-skills` support only Argus. The Argus credential and CLI sections below apply to `argus`. ## Credentials @@ -60,6 +60,7 @@ Codex: ```bash npx skills add realsee-developer/skills --skill argus --agent codex +npx skills add realsee-developer/skills --skill realsee-blender-reconstruction --agent codex ``` Any detected agent host: @@ -74,11 +75,15 @@ Install from a local checkout: ```bash git clone https://github.com/realsee-developer/skills.git cd skills -npm install +npm ci (cd .agents/skills/argus && npm ci --omit=dev --ignore-scripts --no-audit --no-fund) npm run rebuild +npx skills add . --skill argus --agent codex +npx skills add . --skill realsee-blender-reconstruction --agent codex ``` +The local example installs both skills into Codex; change `--agent` for another host, or follow the Claude development guide below. Argus requires a POSIX shell, Node.js 22+, npm 10+, network access, and app credentials; Blender requires working local Blender and existing source inputs. `v2.0.0` includes only Argus; install Blender from the current repository or a local checkout. See the [usage guide](docs/usage.md#credentials-and-upload-consent) for secure setup and upload consent. + See [the install overview](docs/install-guides.md), [Claude Code](docs/claude-plugin.md), and [Codex](docs/codex.md) for host-specific details. ## Official example manifest diff --git a/README.zh-CN.md b/README.zh-CN.md index 033adfb..60fe5bb 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -16,7 +16,7 @@ Realsee Argus 是全球领先的 3D 视觉基础模型。它可从照片、全景图或稀疏视图中，在毫秒级重建具备度量尺度的 3D 结构，包括位姿、深度、点云和可渲染几何。 -Realsee Skills 提供 Argus 的 Agent 与 CLI 工作流。Argus Skill 是 `argus` 2.0：处理 1–99 张严格 2:1 全景图，产出 EXR 深度图、一个合并 GLB 点云、逐图相机位姿、可选内参和经过校验的本地结果索引。 +Realsee Skills 提供 Argus 远程处理与本地 Blender 可编辑空间重建两项工作流。Argus Skill 是 `argus` 2.0：处理 1–99 张严格 2:1 全景图，产出 EXR 深度图、一个合并 GLB 点云、逐图相机位姿、可选内参和经过校验的本地结果索引。 Skill ID 仍为 `argus`。2.0 不包含旧版单图 VGGT fallback；需要 1:1 方图、旧版仅单 GLB 结果或旧 H5 preview 行为时，请固定到 `v1.0.2`。 @@ -33,7 +33,7 @@ Skill ID 仍为 `argus`。2.0 不包含旧版单图 VGGT fallback；需要 1:1 | [argus](.agents/skills/argus/SKILL.md) | 全景 → 深度、点云和位姿 | Realsee 远程处理 | | [realsee-blender-reconstruction](.agents/skills/realsee-blender-reconstruction/README.zh-CN.md) | 已有导出 → 可编辑 Blender 空间；可选漫游与物理导出 | 本地 Blender，本地资料无需 API 凭据 | -在此本地检出目录运行 `npx skills add . --skill realsee-blender-reconstruction --agent codex` 安装 Blender skill。`npm run rebuild` 后 Claude 插件包含两个 skill，Arkclaw 保持 Argus 专用分发。下方凭据和 CLI 章节适用于 `argus`。 +在此本地检出目录运行 `npx skills add . --skill realsee-blender-reconstruction --agent codex` 安装 Blender skill。当前 Claude 插件包含两个 skill；Arkclaw 和 `npm run install:codex-skills` 仅支持 Argus。下方凭据和 CLI 章节适用于 `argus`。 ## 凭证 @@ -60,6 +60,7 @@ Codex： ```bash npx skills add realsee-developer/skills --skill argus --agent codex +npx skills add realsee-developer/skills --skill realsee-blender-reconstruction --agent codex ``` 任意检测到的 agent host： @@ -74,11 +75,15 @@ npx skills add realsee-developer/skills --skill argus --agent '*' ```bash git clone https://github.com/realsee-developer/skills.git cd skills -npm install +npm ci (cd .agents/skills/argus && npm ci --omit=dev --ignore-scripts --no-audit --no-fund) npm run rebuild +npx skills add . --skill argus --agent codex +npx skills add . --skill realsee-blender-reconstruction --agent codex ``` +本地示例将两项 skill 安装到 Codex；其他宿主请替换 `--agent`，Claude 开发安装见下方指南。Argus 需要 POSIX shell、Node.js 22+、npm 10+、网络与应用凭据；Blender 需要本地可运行的 Blender 和已有资料。`v2.0.0` 仅包含 Argus，Blender 使用当前仓库或本地 checkout。安全配置与上传授权见[使用指南](docs/zh-CN/usage.md#凭据与上传授权)。 + 宿主细节见[安装总览](docs/zh-CN/install-guides.md)、[Claude Code](docs/zh-CN/claude-plugin.md) 与 [Codex](docs/zh-CN/codex.md)。 ## 官方示例清单 diff --git a/SECURITY.md b/SECURITY.md index 715842d..51d98a4 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -29,6 +29,10 @@ Never commit: The repository includes `npm run scan:secrets`, but automated scanning is not a substitute for reviewing changes before commit. +Resolve Argus configuration from the inherited environment, then an existing local credentials file. If configuration is missing, use a local shell or secure credential interface; do not request secrets in chat. Persist application credentials only with explicit user authorization, outside the repository in `~/.realsee/credentials` with mode 0600. Never persist temporary tokens or signed URLs. See [usage](docs/usage.md) for the configuration flow. + +Argus uploads require consent for the selected input and scope; selecting files alone is not upload consent. Reuse existing consent while that scope remains unchanged. Blender reconstruction uses local exports and requires no Argus credentials; keep private source exports and generated scenes out of public reports. + ## Supported Versions -The repository is in development. Security fixes target the current `main` branch unless maintainers document a stable branch policy. +Current release status is recorded in `release-channel.json` (Argus 2.0.0 is stable). Security fixes target the current `main` branch unless maintainers document a stable branch policy. diff --git a/SECURITY.zh-CN.md b/SECURITY.zh-CN.md index e90528d..c6a0a44 100644 --- a/SECURITY.zh-CN.md +++ b/SECURITY.zh-CN.md @@ -29,6 +29,10 @@ 仓库包含 `npm run scan:secrets`，但自动扫描不能替代提交前的人工审查。 +Argus 配置先读取继承的环境变量，再读取已有本地凭据文件。缺少配置时使用本地 shell 或安全凭据界面，不要要求在聊天中提供秘密。只有用户明确授权后，才能在仓库外的 `~/.realsee/credentials` 中以 0600 权限保存应用凭据。不得持久化临时令牌或签名 URL。配置流程见[使用指南](docs/zh-CN/usage.md)。 + +Argus 上传须获得针对所选输入和范围的授权；仅选择文件不等于同意上传。在范围未变时复用既有授权。Blender 重建使用本地导出且不需要 Argus 凭据；公开报告中不要附带私有源数据或生成场景。 + ## 支持版本 -仓库处于开发阶段。除非维护者另行记录稳定分支策略，安全修复面向当前 `main` 分支。 +当前发布状态记录在 `release-channel.json`（Argus 2.0.0 为 stable）。除非维护者另行记录稳定分支策略，安全修复面向当前 `main` 分支。 diff --git a/SUPPORT.md b/SUPPORT.md index 854de94..fb3eb96 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -8,14 +8,16 @@ Use this file to find the fastest channel for your situation. Open a GitHub issue at [realsee-developer/skills/issues](https://github.com/realsee-developer/skills/issues): -- **Bug** — runtime failures, install issues, doc errors. Use the `Bug report` template. Include the lifecycle command (`start`, `status`, or `collect`), sanitized error output, `node --version`, `npm --version`, OS, and the relevant `result.json` / `state.json` (redact task codes, object paths, and credentials before pasting). -- **Feature request** — use the `Feature request` template. Explain whether it affects the runtime, the skill packaging, or the install paths. +- **Bug** — runtime failures, install issues, or doc errors. Use the `Bug report` template and identify `argus` or `realsee-blender-reconstruction`, the installed revision, host, OS, reproduction steps, and sanitized error output. + - **Argus**: include the lifecycle command (`start`, `status`, or `collect`), `node --version`, `npm --version`, and relevant `result.json` / `state.json` fields. Redact task codes, object paths, credentials, and private URLs. + - **Blender**: include the Blender version, available local integration, input export types, failed reconstruction or validation step, and expected versus actual deliverables. Use sanitized descriptions or non-private examples; Argus lifecycle files and credentials are not required. +- **Feature request** — use the `Capability request` template. Explain whether it affects the Argus runtime, Blender reconstruction guidance, skill packaging, or installation. Do **not** include `REALSEE_APP_KEY`, `REALSEE_APP_SECRET`, generated credentials, internal URLs, account identifiers, or private result links in any public issue. ## Realsee Open Platform / API Capability -GitHub issues cannot grant Argus Gateway access. For account and capability questions: +Blender reconstruction does not require Argus Gateway access or credentials. GitHub issues cannot grant Argus Gateway access. For account and capability questions: - Register an account: [my.realsee.ai](https://my.realsee.ai/?utm_source=github) (global) / [my.realsee.cn](https://my.realsee.cn/?utm_source=github) (cn). - Request API capability: email [developer@realsee.com](mailto:developer@realsee.com?subject=Argus%20API%20Capability%20Request) with your account region, `UserID`, and `IdentityID`. diff --git a/SUPPORT.zh-CN.md b/SUPPORT.zh-CN.md index f04b02a..4ff6f8b 100644 --- a/SUPPORT.zh-CN.md +++ b/SUPPORT.zh-CN.md @@ -8,14 +8,16 @@ 到 [realsee-developer/skills/issues](https://github.com/realsee-developer/skills/issues) 提 issue： -- **Bug** —— 运行错误、安装问题、文档错误。用 `Bug report` 模板。附生命周期命令（`start`、`status` 或 `collect`）、脱敏错误输出、`node --version`、`npm --version`、操作系统，以及相关的 `result.json` / `state.json`（粘贴前务必脱敏 task code、对象路径和凭证）。 -- **Feature request** —— 用 `Feature request` 模板。说明影响的是 runtime、skill 打包，还是安装路径。 +- **Bug** —— 运行错误、安装问题或文档错误。使用 `Bug report` 模板，注明 `argus` 或 `realsee-blender-reconstruction`、安装的修订版本、宿主、操作系统、复现步骤和脱敏错误输出。 + - **Argus**：附生命周期命令（`start`、`status` 或 `collect`）、`node --version`、`npm --version` 和相关 `result.json` / `state.json` 字段。脱敏任务代码、对象路径、凭据和私有 URL。 + - **Blender**：附 Blender 版本、可用本地集成、输入导出类型、失败的重建或验收步骤，以及预期和实际交付物。使用脱敏描述或非私有示例；无需 Argus 生命周期文件或凭据。 +- **Feature request** —— 用 `Capability request` 模板。说明影响的是 Argus runtime、Blender 重建指南、skill 打包，还是安装路径。 **不要**在公开 issue 中包含 `REALSEE_APP_KEY`、`REALSEE_APP_SECRET`、生成凭证、内部 URL、账号标识或私有结果链接。 ## Realsee 开放平台 / API 能力 -GitHub issue 不能授予 Argus Gateway 接入。账号与能力相关问题： +Blender 重建不需要 Argus Gateway 接入或凭据。GitHub issue 不能授予 Argus Gateway 接入。账号与能力相关问题： - 注册账号：[my.realsee.ai](https://my.realsee.ai/?utm_source=github)（global）/ [my.realsee.cn](https://my.realsee.cn/?utm_source=github)（cn）。 - 申请 API 能力：邮件 [developer@realsee.com](mailto:developer@realsee.com?subject=Argus%20API%20Capability%20Request)，附账号 region、`如视ID`、`组织账号`。 @@ -26,6 +28,6 @@ GitHub issue 不能授予 Argus Gateway 接入。账号与能力相关问题： ## 各宿主安装帮助 -- Claude Code plugin 安装：[docs/claude-plugin.md](docs/claude-plugin.md) -- Codex 安装：[docs/codex.md](docs/codex.md) -- 跨宿主总览：[docs/install-guides.md](docs/install-guides.md) +- Claude Code plugin 安装：[docs/zh-CN/claude-plugin.md](docs/zh-CN/claude-plugin.md) +- Codex 安装：[docs/zh-CN/codex.md](docs/zh-CN/codex.md) +- 跨宿主总览：[docs/zh-CN/install-guides.md](docs/zh-CN/install-guides.md) diff --git a/arkclaw/argus/SKILL.md b/arkclaw/argus/SKILL.md index 0640559..cc56ad1 100644 --- a/arkclaw/argus/SKILL.md +++ b/arkclaw/argus/SKILL.md @@ -42,7 +42,7 @@ Resolve values in the existing order: && [ -n "${REALSEE_REGION:-}" ] && echo present || echo missing ``` -2. If `~/.realsee/credentials` already exists, load it into the shell and probe presence. Never display the file: +2. If configuration is incomplete and `~/.realsee/credentials` already exists, load it into the shell and probe presence. Never display the file: ```bash [ -f ~/.realsee/credentials ] && set -a && . ~/.realsee/credentials && set +a; \ @@ -77,11 +77,10 @@ The downloader publishes the directory only after every file passes its manifest Before starting, ensure the user has selected the files and consented to sending them to Realsee for remote processing. An explicit request to upload those files is sufficient; file selection alone is not consent. If either is missing, ask one question stating that the selected files will leave the machine. Reuse existing consent for the same input and scope. Do not ask a redundant second confirmation. -For repeated images: +Run lifecycle commands in a shell with credentials resolved in step 2. For repeated images: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs start \ +node /scripts/run-argus.mjs start \ --image "/absolute/path/a.jpg" \ --image "/absolute/path/b.webp" \ --workspace "/absolute/workspace-root" \ @@ -91,14 +90,13 @@ set -a; . ~/.realsee/credentials; set +a; \ For an existing ZIP: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs start \ +node /scripts/run-argus.mjs start \ --zip "/absolute/path/input.zip" \ --workspace "/absolute/workspace-root" \ --yes --json ``` -If credentials already exist in the inherited shell, omit the `source` prefix. Capture `workspace_dir` from the JSON response; it is the durable run handle for later commands. +When starting a new shell for `status` or `collect`, resolve credentials there before invoking the command. Capture `workspace_dir` from the JSON response; it is the durable run handle for later commands. `start` validates and packages locally, uploads one ZIP, submits once, persists `task_code`, and returns. It does not poll in the background. Never automatically rerun `start` after `submission_unknown`: the submit operation is not idempotent and a blind retry may create a duplicate task. @@ -107,8 +105,7 @@ If credentials already exist in the inherited shell, omit the `source` prefix. C Run one status query: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs status \ +node /scripts/run-argus.mjs status \ --workspace "" --json ``` @@ -119,8 +116,7 @@ Interpret `task_status` as `queued`, `processing`, `succeeded`, or `failed`. Whe When the task succeeds, run: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs collect \ +node /scripts/run-argus.mjs collect \ --workspace "" --json ``` diff --git a/docs/claude-plugin.md b/docs/claude-plugin.md index 7a7cd2f..6b96697 100644 --- a/docs/claude-plugin.md +++ b/docs/claude-plugin.md @@ -20,7 +20,7 @@ It carries `examples/manifest.json`, but no panorama JPEGs. To use official samp ```bash git clone https://github.com/realsee-developer/skills.git cd skills -npm install +npm ci (cd .agents/skills/argus && npm ci --omit=dev --ignore-scripts --no-audit --no-fund) npm run rebuild claude --plugin-dir ./plugins/realsee-skills @@ -33,15 +33,9 @@ node plugins/realsee-skills/scripts/validate-plugin.mjs npm run check:claude-sync ``` -## Credentials +## Credentials and consent -The existing runtime precedence remains: - -1. inherited `REALSEE_APP_KEY`, `REALSEE_APP_SECRET`, and `REALSEE_REGION`; -2. an existing `~/.realsee/credentials` loaded by the agent; -3. one-field-per-turn collection in chat. - -The agent must never echo values or place them in recorded command arguments. Credentials, upload tokens, presigned URLs, and raw provider errors are not persisted in run state. +Only Argus needs credentials. Follow the [usage guide](usage.md#credentials-and-upload-consent) to check environment variables, load an existing credential file, and configure missing values through a local shell or secure interface. Persist app credentials outside the repository with mode 0600 only when explicitly authorized; never persist upload tokens or signed URLs. File selection is not upload consent; reuse consent for the same input and scope. ## Prompt examples @@ -58,9 +52,10 @@ Or name the Skill explicitly: ```text Use realsee-skills:argus on /path/input.zip. +Use realsee-skills:realsee-blender-reconstruction with data/ to save output/reconstruction_native.blend. ``` -## Skill surface +## Argus command surface | Action | Command | | --- | --- | @@ -76,4 +71,4 @@ The agent must obtain upload consent before start. For `result_status: partial`, ## Release policy -Stable 2.0 installs use `v2.0.0` only after global and CN E2E pass. Users who require the 1.x square or single-GLB workflow pin `v1.0.2`. +`main` is the integration branch. `release-channel.json` defines the current channel; see the [release guide](release.md) for gates. `v2.0.0` contains Argus but not the Blender skill; use the current repository or a verified local checkout for Blender. Pin `v1.0.2` for the legacy square or single-GLB workflow. diff --git a/docs/codex.md b/docs/codex.md index 3f891d2..7e7fc41 100644 --- a/docs/codex.md +++ b/docs/codex.md @@ -2,12 +2,15 @@ [English](codex.md) | [简体中文](zh-CN/codex.md) -Install the canonical `argus` Skill into Codex: +Install either or both skills into Codex as needed: ```bash npx skills add realsee-developer/skills --skill argus --agent codex +npx skills add realsee-developer/skills --skill realsee-blender-reconstruction --agent codex ``` +`$argus` runs remote panorama processing; `$realsee-blender-reconstruction` builds editable scenes from existing local inputs. Blender requires a working local Blender installation and no Argus credentials; see [installation requirements](install-guides.md). + For product context, see [Argus](https://argus.realsee.ai/), its [interactive demo](https://h5.realsee.ai/argus), [research site](https://argus-paper.realsee.ai/), and the [Realsee Developer Platform](https://developer.realsee.ai/). Codex must follow the installed Skill contract rather than infer broader capabilities from those pages: Skill 2.0 accepts only 1–99 local RGB8 panoramas with exact 2:1 dimensions. Pin the stable 2.0 release: @@ -23,11 +26,14 @@ Use `@v1.0.2` instead only for legacy square 1:1 or single-GLB behavior. ```bash git clone https://github.com/realsee-developer/skills.git cd skills -npm install +npm ci (cd .agents/skills/argus && npm ci --omit=dev --ignore-scripts --no-audit --no-fund) CODEX_HOME=$HOME/.codex npm run install:codex-skills +npx skills add . --skill realsee-blender-reconstruction --agent codex ``` +`npm run install:codex-skills` installs only Argus, replacing its target directory and installing locked dependencies; install Blender separately with the `npx skills` command above. + Codex discovers the Skill at `${CODEX_HOME:-$HOME/.codex}/skills/argus`. Verify: ```bash @@ -37,19 +43,14 @@ head "${CODEX_HOME:-$HOME/.codex}/skills/argus/SKILL.md" The install includes `examples/manifest.json`, but no panorama JPEGs. To use official samples, Codex should ask for the region and a new absolute output directory outside the installed Skill, then run `node /scripts/download-examples.mjs --region --output `. The command verifies every manifest byte length and SHA-256 before publishing the directory. A later Argus run still requires separate upload consent and uses the corresponding regional Gateway. -## Credentials - -The existing runtime contract is unchanged: - -1. inherited `REALSEE_APP_KEY`, `REALSEE_APP_SECRET`, and `REALSEE_REGION`; -2. an existing `~/.realsee/credentials` loaded by the agent; -3. one-field-per-turn collection in the Codex session. +## Credentials and consent -Do not print values or put them in recorded command arguments. To avoid prompts, export the variables before launching Codex. +Only Argus needs credentials. Follow the [usage guide](usage.md#credentials-and-upload-consent) to check environment variables, load an existing credential file, and configure missing values through a local shell or secure interface. Persist app credentials outside the repository with mode 0600 only when explicitly authorized; never persist upload tokens or signed URLs. File selection is not upload consent; reuse consent for the same input and scope. ## Prompt examples ```text +Use $realsee-blender-reconstruction with data/ to reconstruct an editable space and save output/reconstruction_native.blend. Use $argus to start a batch from /path/a.jpg and /path/b.webp. Report the run workspace. Use $argus to download and verify the CN examples to /absolute/examples, then ask for upload consent before starting them. Use $argus to check the status of /workspace/ once. @@ -77,4 +78,4 @@ There is no detached poller or resume flag. A completed collect is idempotent. C ## Release policy -`main` is the integration branch. Stable installs use a Git tag. Version 2.0 is promoted only after uploader 0.1.1 and real global/CN E2E have passed. +`main` is the integration branch. `release-channel.json` defines the current channel; see the [release guide](release.md) for gates. `v2.0.0` contains Argus but not the Blender skill; use the current repository or a verified local checkout for Blender. Pin `v1.0.2` for the legacy square or single-GLB workflow. diff --git a/docs/community.md b/docs/community.md index 5b9fb2d..37d9bf0 100644 --- a/docs/community.md +++ b/docs/community.md @@ -6,25 +6,19 @@ This repository is primarily published so users can inspect, install, and run Re ## Reporting Bugs -Use the bug report issue template and include: - -- Skill name, usually `argus` -- Command that failed -- Lifecycle command that failed (`start`, `status`, or `collect`) -- Sanitized error output -- Operating system, Node.js version, and npm version +Use the `Bug report` issue template. Include the skill name, installed revision, host, OS, reproduction steps, and sanitized errors. Follow [Support](../SUPPORT.md) for skill-specific details: Argus reports need lifecycle and Node.js/npm context; Blender reports need Blender/integration versions, input export types, failed steps, and expected versus actual deliverables. Never include `REALSEE_APP_KEY`, `REALSEE_APP_SECRET`, generated credentials, internal URLs, account identifiers, or private result links. ## Capability Feedback -Use the capability request template when a supported workflow is missing a public capability, unclear documentation, or a runtime behavior blocks integration. Include: +Use the `Capability request` template when a supported workflow is missing a public capability, unclear documentation, or a runtime behavior blocks integration. Include: - User workflow - Expected input and output - Whether remote upload is required - Any relevant public API references or capability documentation -- Whether the issue is about local lifecycle state, live usage, artifact validation, or installation +- Whether the issue is about Argus lifecycle state or live usage, Blender reconstruction, artifact validation, or installation ## Pull Requests diff --git a/docs/development.md b/docs/development.md index 2fa0a3f..93320bc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -2,12 +2,13 @@ [English](development.md) | [简体中文](zh-CN/development.md) -This repository is a Node.js workspace for Realsee agent skills. Argus 2.0 runtime code and canonical contracts live under `.agents/skills/argus/`. +This repository maintains Realsee agent skills under `.agents/skills/`: Argus has a Node.js runtime and API contracts; `realsee-blender-reconstruction` contains local modeling instructions and references. ## Requirements - Node.js 22 or newer - npm 10 or newer +- Local Blender for exercising reconstruction instructions; no Realsee credentials are needed for local modeling - No committed `.env` files or generated private artifacts ## Local Checks @@ -28,6 +29,7 @@ npm run validate:repo-boundary npm run validate:skills npm run rebuild npm run validate:channel-metadata +npm run test:repo npm run test:skill ``` @@ -38,14 +40,15 @@ Use focused commands while editing: | `npm run validate:ai` | After changing `llms.txt` or repository entry points. | | `npm run validate:docs` | After changing bilingual repository docs. | | `npm run validate:skills` | After changing skill metadata, README files, or references. | +| `npm run test:repo` | After changing repository tooling or distribution behavior. | | `npm run test:skill` | After changing `argus` code. | | `npm run rebuild` | Regenerate and byte-check the Claude plugin and CN-only Arkclaw copies. | -| `npm run doctor` | Check local prerequisites through `doctor:local`. | -| `npm run doctor:live` | Check live Argus prerequisites and environment. | +| `npm run doctor` | Check Argus and repository prerequisites through `doctor:local`; does not discover Blender. | +| `npm run doctor:live -- --skill argus --channel preview` | Check required configuration presence only; the no-side-effect capability probe is not implemented. Stable mode fails without that verification. | ## Skill Workflow -The source of truth is `.agents/skills/argus/`. The Claude plugin is generated into `plugins/realsee-skills/`; the Arkclaw package is generated into `arkclaw/argus/` with deterministic CN-only overlays for runtime region, example downloads, and matching guidance. +The source of truth for all skills is `.agents/skills/`. Claude includes both canonical skills; Arkclaw includes only Argus. The Claude plugin is generated into `plugins/realsee-skills/`; the Arkclaw package is generated into `arkclaw/argus/` with deterministic CN-only overlays for runtime region, example downloads, and matching guidance. When changing `argus`: @@ -56,12 +59,14 @@ When changing `argus`: Do not edit either generated copy directly. New runtime behavior should be exercised through `ArgusTaskPort` and `ObjectTransferPort` fakes. Include focused input, lifecycle, output-contract, and idempotence tests. +For Blender instructions, edit `.agents/skills/realsee-blender-reconstruction/` and its bilingual references, then run `npm run validate:skills`, `npm run rebuild`, and `npm run ci`. Documentation checks do not prove modeling behavior: when changing the modeling workflow, exercise the affected instructions on appropriate local evidence and report the actual scope verified. No npm runtime or remote-service fake is required for this instruction-only skill. + ## Configuration -Public documentation uses only these environment variable names: +Argus configuration uses these environment variables: - `REALSEE_APP_KEY` - `REALSEE_APP_SECRET` - `REALSEE_REGION` -The existing agent-driven `~/.realsee/credentials` loading flow remains supported. Do not commit real values, account identifiers, internal URLs, generated credentials, `output.zip`, extracted artifacts, or temporary workspaces. +Follow the [Argus credential setup](usage.md#credentials-and-upload-consent) for inherited environment values, an existing `~/.realsee/credentials`, and secure local configuration of missing values. Persist app credentials only with explicit user authorization, outside the repository with mode 0600. Never persist temporary upload tokens or signed URLs. Do not commit real values, account identifiers, internal URLs, generated credentials, `output.zip`, extracted artifacts, or temporary workspaces. diff --git a/docs/install-guides.md b/docs/install-guides.md index f5a6b42..d32fe0f 100644 --- a/docs/install-guides.md +++ b/docs/install-guides.md @@ -2,14 +2,14 @@ [English](install-guides.md) | [简体中文](zh-CN/install-guides.md) -Every install path uses the same canonical `argus` Skill 2.0 source and explicit `start` / `status` / `collect` lifecycle. +This repository provides two skills: `argus` uploads panoramas to Realsee for remote processing; `realsee-blender-reconstruction` reconstructs existing local exports as editable Blender scenes. Canonical sources live under `.agents/skills/`. ## Host matrix | Host | Install | Skill handle | Guide | | --- | --- | --- | --- | -| Claude Code | `/plugin marketplace add realsee-developer/skills`, then `/plugin install realsee-skills@realsee-developer-skills` | `realsee-skills:argus` | [Claude Code](claude-plugin.md) | -| Codex | `npx skills add realsee-developer/skills --skill argus --agent codex` | `$argus` | [Codex](codex.md) | +| Claude Code | `/plugin marketplace add realsee-developer/skills`, then `/plugin install realsee-skills@realsee-developer-skills` | `realsee-skills:argus`, `realsee-skills:realsee-blender-reconstruction` | [Claude Code](claude-plugin.md) | +| Codex | `npx skills add realsee-developer/skills --skill argus --agent codex` | `$argus`, `$realsee-blender-reconstruction` | [Codex](codex.md) | | Any detected host | `npx skills add realsee-developer/skills --skill argus --agent '*'` | Host-specific | This guide | | Arkclaw | Published Arkclaw ZIP | `argus` | CN-only | @@ -19,9 +19,15 @@ For the active host only: npx skills add realsee-developer/skills --skill argus ``` +The `npx skills` commands in the table install Argus; replace `--skill argus` with `--skill realsee-blender-reconstruction` to install Blender. The current Claude plugin includes both skills; Arkclaw and `npm run install:codex-skills` install only Argus. + +## Runtime requirements + +Argus requires a POSIX shell, Node.js 22+, npm 10+, npm registry and regional Gateway access, and Argus-enabled app credentials. Before first use, the agent installs missing runtime dependencies from the lockfile as directed by the installed `SKILL.md`. The Blender skill requires a working local Blender installation and existing scan exports, point clouds, CAD, or panoramas; local reconstruction needs no Realsee credentials. + ## Reproducible versions -Use a release tag when a reproducible install matters: +Argus can be pinned to `v2.0.0`. That tag does not contain the Blender skill; install Blender from the current repository or a local checkout pinned to a verified revision containing it. ```bash npx skills add realsee-developer/skills@v2.0.0 --skill argus @@ -35,13 +41,11 @@ npx skills add realsee-developer/skills@v1.0.2 --skill argus ## Credentials -All hosts use `REALSEE_APP_KEY`, `REALSEE_APP_SECRET`, and `REALSEE_REGION` (`global` or `cn`). The existing Skill flow checks inherited shell environment first, then an agent-loaded `~/.realsee/credentials`, then asks one field per turn. Arkclaw fixes the region to `cn`. - -Never print credentials or pass them as recorded command arguments. See [SUPPORT.md](../SUPPORT.md) if the target account does not have Argus capability. +Only Argus needs app credentials; Arkclaw fixes the region to `cn`. See the [usage guide](usage.md#credentials-and-upload-consent) for environment variables, existing credential files, secure setup, and upload consent. See [SUPPORT.md](../SUPPORT.md) if the account lacks Argus capability. ## After install -The host invokes: +See the [usage guide](usage.md) for Blender invocation and deliverables. For Argus, after dependencies, credentials, and upload consent are ready, the host invokes: ```bash node /scripts/run-argus.mjs start --image /absolute/a.jpg --workspace /absolute/workspace --yes --json diff --git a/docs/public-distribution.md b/docs/public-distribution.md index fcb3ef8..ac14311 100644 --- a/docs/public-distribution.md +++ b/docs/public-distribution.md @@ -2,25 +2,26 @@ [English](public-distribution.md) | [简体中文](zh-CN/public-distribution.md) -Run this checklist before promoting Argus Skill 2.0. +Use this checklist for a planned distribution or release change. Current Argus metadata is `2.0.0` / stable / passed; the first 2.0 promotion is historical. See the [release guide](release.md) for gate conditions. Argus-specific runtime and live checks below do not apply to the instruction-only Blender skill. ## Repository and versions - [ ] `v1.0.2` remains unchanged; no `v1.0` alias exists. -- [ ] Root, Skill package, plugin package, and `release-channel.json` versions agree. -- [ ] Preview metadata remains pending until real two-region E2E passes. +- [ ] Root, Argus runtime package, plugin package, and `release-channel.json` versions agree. +- [ ] For a new preview, the tag matches `next_release_candidate` and the metadata version; metadata remains development/preview/pending until real two-region E2E passes. - [ ] `npm run ci` and the selected release gate pass on a clean clone. - [ ] Git status contains no credentials, `.env`, workspaces, output ZIPs, or extracted artifacts. ## Canonical distribution - [ ] `npm run rebuild` regenerates both `plugins/realsee-skills/` and `arkclaw/argus/`. -- [ ] Claude plugin files are byte-identical to `.agents/skills/argus/`. +- [ ] Claude plugin includes both `argus` and `realsee-blender-reconstruction`, with files byte-identical to their canonical directories under `.agents/skills/`. - [ ] Arkclaw files are canonical bytes except deterministic CN-only overlays for the runtime region, example downloader, and matching generated guidance. -- [ ] Codex install and `npx skills add . --skill argus` both resolve the same canonical Skill. +- [ ] The dedicated Codex installer and Arkclaw package support only Argus; `npx skills add . --skill argus` and `npx skills add . --skill realsee-blender-reconstruction` resolve their respective canonical skills. +- [ ] Versioned installation examples only name tags containing the selected skill; `v2.0.0` does not contain Blender. - [ ] Plugin manifest has no `userConfig` and no MCP server. -## Contracts and docs +## Argus contracts and docs - [ ] Gateway OpenAPI contains exactly the four public methods and both bases. - [ ] Bilingual algorithm I/O docs agree on auto IDs, `missing_ids`, `error`, optional normals, fixed `right-handed, Y-up`, and EXR-only stable depth. @@ -28,7 +29,7 @@ Run this checklist before promoting Argus Skill 2.0. - [ ] English/Chinese usage and migration docs explain that square/single-GLB users pin `v1.0.2`. - [ ] No document mentions detached polling, `--async`, `--resume`, or a 2.0 H5 preview as supported behavior. -## Runtime verification +## Argus runtime verification - [ ] Input tests cover 1, 99, and 100 images; JPEG/PNG/WebP; invalid ratio/RGB8; duplicate names; nested/corrupt/Zip Slip/Bomb archives. - [ ] Gateway tests cover paths, methods, envelopes, status mapping, and both region bases. @@ -36,7 +37,7 @@ Run this checklist before promoting Argus Skill 2.0. - [ ] Artifact tests cover success/partial/error, ID consistency, invalid paths, invalid GLB/EXR, missing pose/depth, optional intrinsics, and atomic recovery. - [ ] `start`, `status`, and `collect` return the documented JSON and exit codes. -## Uploader gate +## Uploader release checks - [ ] `@realsee/universal-uploader@0.1.1` is published and installable. - [ ] Unit tests, typecheck, build, `npm pack` smoke, and GitLab CI pass. @@ -45,8 +46,9 @@ Run this checklist before promoting Argus Skill 2.0. ## Real E2E and promotion -- [ ] `v2.0.0-rc.3` completes a real multi-image run in global/AWS. -- [ ] `v2.0.0-rc.3` completes a real multi-image run in CN/Tencent COS. +- [ ] The selected Argus release candidate completes a real multi-image run in global/AWS. +- [ ] The selected Argus release candidate completes a real multi-image run in CN/Tencent COS. - [ ] Both regions verify download plus success, partial, and error handling. -- [ ] Only after those checks, set `state: stable`, `stable_gate: passed`, and publish `v2.0.0`. -- [ ] Test fresh installs through Claude plugin, Codex, `npx skills`, and CN-only Arkclaw. +- [ ] Only after those checks, record stable/passed metadata for the selected version, remove `next_release_candidate`, and obtain authorization before publishing a new tag. +- [ ] Test fresh installs through Claude plugin, the Argus-only Codex installer, `npx skills` for each skill, and CN-only Arkclaw. +- [ ] For Blender guidance changes, review input prerequisites, local tool requirements, editable deliverables, and applicable acceptance checks against the canonical skill; do not claim a real reconstruction was run unless it was. diff --git a/docs/release.md b/docs/release.md index ad1743b..2156219 100644 --- a/docs/release.md +++ b/docs/release.md @@ -2,53 +2,35 @@ [English](release.md) | [简体中文](zh-CN/release.md) -Release readiness is recorded in `release-channel.json` and enforced by `scripts/release-gate.mjs`. +Release readiness is recorded in `release-channel.json` and enforced by `scripts/release-gate.mjs`. Current metadata records version `2.0.0`, channel `stable`, and Argus `state: stable` / `stable_gate: passed`; it does not declare a separate Blender release state. ## Version lines - `v1.0.2` is the frozen legacy release for square input and the old single-GLB workflow. Do not add a mutable or ambiguous `v1.0` tag. -- `v2.0.0` keeps the Skill ID `argus` and uses the multi-panorama ZIP interface. It has no 1.x fallback. +- `v2.0.0` keeps the Skill ID `argus` and uses the multi-panorama ZIP interface, without a 1.x fallback. That tag does not contain `realsee-blender-reconstruction`; use a revision that includes it for Blender installation. -During implementation, metadata stays `channel: development`, `state: preview`, and `stable_gate: pending`. Do not mark 2.0 stable based only on local tests. +## Current gates -## Gates - -Preview: - -```bash -npm run release:gate -- --channel preview --tag v2.0.0-rc.3 -``` - -Stable: +For the currently recorded stable version: ```bash npm run release:gate -- --channel stable --tag v2.0.0 ``` -Both gates run repository checks, regeneration/byte consistency for Claude and Arkclaw packages, and the complete Skill tests. Stable also requires the public four-path Gateway OpenAPI contract. - -## Required order +A preview gate requires a prerelease tag whose base version matches the metadata version and whose full value equals `skills.argus.next_release_candidate`. Metadata must also be `channel: development`, `state: preview`, and `stable_gate: pending`. Current stable metadata has no pending candidate, so it cannot pass a preview gate. Select and record the next candidate only as part of an authorized release change. -1. Keep the existing `v1.0.2` tag unchanged. -2. Publish and verify `@realsee/universal-uploader@0.1.1`. -3. Cut `v2.0.0-rc.3` and run real multi-image E2E in both CN and global. -4. In both regions verify upload, task completion, success/partial/error collection, and result download. -5. Set release metadata to stable/passed and publish `v2.0.0`. -6. Verify the bilingual migration guide and fresh installs for Claude, Codex, `npx skills`, and CN-only Arkclaw. +Both gates run secret scanning, documentation and AI index validation, repository boundary and skill validation, distribution rebuild, generated-file cleanliness, smoke checks, worktree cleanliness, channel metadata validation, `test:repo`, `test:skill`, and the Argus production dependency audit. Compared with `npm run ci`, release gates additionally check generated-file/worktree cleanliness, run smoke checks, and audit production dependencies. Run them from a clean checkout with dependencies installed; they regenerate distributions. -The uploader release gate must pass unit tests, type checking, build, `npm pack` install smoke, and production audit with no high or critical vulnerability. +Stable additionally requires the public Gateway OpenAPI contract (four required operations, required schemas, and both region bases), a matching stable version/tag, `stable/stable/passed` metadata, both CN/global regions, and no `next_release_candidate`. Metadata records maintainer approval of real two-region E2E; the gate does not perform those remote runs itself. -## Live verification record +## Historical first 2.0 promotion -Do not commit credentials, signed URLs, private task locators, or generated artifacts as evidence. Record only sanitized pass/fail results outside the public repository. Stable requires real AWS/global and Tencent COS/CN runs; local fakes are not a substitute. +The first 2.0 promotion sequence used `@realsee/universal-uploader@0.1.1`, then `v2.0.0-rc.3` for real multi-image verification in CN and global, and finally stable/passed metadata and `v2.0.0`. These are historical release steps, not instructions to recreate or overwrite existing tags. -## Tag +For an uploader release, verify unit tests, type checking, build, `npm pack` install smoke, and a production audit with no high or critical vulnerability. For an Argus promotion, verify upload, task completion, success/partial/error collection, result download, bilingual migration guidance, and fresh supported-host installs against the selected candidate. See the [distribution checklist](public-distribution.md). -After every stable condition is met: +## Live verification and publishing -```bash -git tag -a v2.0.0 -m "v2.0.0" -git push origin v2.0.0 -``` +Do not commit credentials, signed URLs, private task locators, or generated artifacts as evidence. Record only sanitized pass/fail results outside the public repository. Stable Argus promotion requires real AWS/global and Tencent COS/CN verification; local fakes are not a substitute. Obtain upload consent for those runs. -The release workflow runs the stable gate before creating the GitHub release. +Publishing requires explicit authorization and a new, approved tag; preserve existing tags. The release workflow classifies the pushed tag, runs its preview or stable gate, then rebuilds from a fresh checkout, checks committed generated files, builds and verifies the Arkclaw ZIP, and creates the GitHub release. diff --git a/docs/usage.md b/docs/usage.md index c5a4c81..7d06d81 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -16,7 +16,7 @@ Then open the modeling project and ask: > Use $realsee-blender-reconstruction with data/. Reconstruct the evidenced space, prioritizing structure and connections. Save output/reconstruction_native.blend and verify source comparisons and actual edits after reopening. -The skill includes optional walkthrough, physics/USDZ, image-and-text asset generation, and web-preview guidance when requested. `npm run install:codex-skills` remains the Argus-specific installer. The rest of this guide describes Argus remote processing. +Verify that local Blender runs and inspect its version; keep inputs, scripts, and outputs in the modeling project. The skill includes optional walkthrough, physics/USDZ, image-and-text asset generation, and web-preview guidance when requested. `npm run install:codex-skills` remains the Argus-specific installer. The rest of this guide describes Argus remote processing. Official resources: [Argus](https://argus.realsee.ai/), [interactive demo](https://h5.realsee.ai/argus), [research](https://argus-paper.realsee.ai/), and the [Realsee Developer Platform](https://developer.realsee.ai/). These sites may show broader photo and product workflows; the Argus Skill accepts only 1–99 local RGB8 panoramas with exact 2:1 dimensions. @@ -35,6 +35,14 @@ From a local checkout: npx skills add . --skill argus ``` +## Credentials and upload consent + +Only Argus requires `REALSEE_APP_KEY`, `REALSEE_APP_SECRET`, and `REALSEE_REGION` (`global` or `cn`; Arkclaw fixes it to `cn`). The agent first checks the inherited shell environment; if configuration is incomplete, it loads an existing `~/.realsee/credentials`, then requests only what is still missing. Have the user configure secrets in their local shell or a secure credential interface, rather than collecting them field by field in chat. + +Never echo credentials or put values in recorded command arguments or environment prefixes. Only when the user explicitly chooses persistent storage may app credentials be saved outside the repository in `~/.realsee/credentials` with mode 0600. Upload tokens and signed URLs must never be persisted; run state contains no credentials. + +`start` sends the selected files to Realsee. File selection and example downloads are not upload consent; an explicit request to upload those files is sufficient. Reuse existing consent for the same input and scope without another confirmation. `--yes` in the examples records that consent has been obtained; it does not replace user authorization. + ## Official example manifest The installed Skill contains `examples/manifest.json`, not the panorama JPEGs. To use a first-party sample set, choose the region matching `REALSEE_REGION` and a new absolute directory outside ``: @@ -126,4 +134,4 @@ Collection retains `output.zip`, safely extracts it, validates the manifest and - Output schema: [argus-output.schema.json](../.agents/skills/argus/references/argus-output.schema.json) - Machine index: [llms.txt](../llms.txt) -Real Argus runs are remote uploads. Obtain user consent first and do not persist credentials, upload tokens, or signed result URLs. +Follow the credential and upload-consent requirements above; use validated local artifacts as durable deliverables. diff --git a/docs/zh-CN/claude-plugin.md b/docs/zh-CN/claude-plugin.md index 74a9784..3199f0f 100644 --- a/docs/zh-CN/claude-plugin.md +++ b/docs/zh-CN/claude-plugin.md @@ -20,7 +20,7 @@ Plugin 包含 `examples/manifest.json`，但不包含全景 JPEG。需要官方 ```bash git clone https://github.com/realsee-developer/skills.git cd skills -npm install +npm ci (cd .agents/skills/argus && npm ci --omit=dev --ignore-scripts --no-audit --no-fund) npm run rebuild claude --plugin-dir ./plugins/realsee-skills @@ -33,15 +33,9 @@ node plugins/realsee-skills/scripts/validate-plugin.mjs npm run check:claude-sync ``` -## 凭证 +## 凭据与授权 -继续使用原有运行时优先级： - -1. 继承的 `REALSEE_APP_KEY`、`REALSEE_APP_SECRET`、`REALSEE_REGION`； -2. 由 agent 加载现有 `~/.realsee/credentials`； -3. 在对话中一字段一轮收集。 - -Agent 不得回显值，也不得把它们放进会被记录的命令参数。凭证、上传 token、预签名 URL 和 provider 原始错误不写入 run state。 +仅 Argus 需要凭据。按[使用指南](usage.md#凭据与上传授权)检查环境变量、加载已有凭据文件，并通过本地 shell 或安全界面补齐缺失配置。仅在明确授权后以 0600 权限在仓库外保存应用凭据；上传 token 与签名 URL 不得持久化。文件选择不等于上传同意，同一输入和范围复用已有授权。 ## 提示词示例 @@ -58,9 +52,10 @@ Agent 不得回显值，也不得把它们放进会被记录的命令参数。 ```text Use realsee-skills:argus on /path/input.zip. +Use realsee-skills:realsee-blender-reconstruction with data/ to save output/reconstruction_native.blend. ``` -## Skill 调用面 +## Argus 调用面 | 动作 | 命令 | | --- | --- | @@ -76,4 +71,4 @@ Start 前必须取得上传同意。`result_status: partial` 时，即使 CLI ## 发布策略 -Global 与 CN E2E 都通过后，stable 2.0 安装使用 `v2.0.0`。需要 1.x 方图或单 GLB 工作流的用户固定 `v1.0.2`。 +`main` 为集成分支，当前发布通道以 `release-channel.json` 为准，门禁见[发布指南](release.md)。`v2.0.0` 包含 Argus，不包含 Blender skill；Blender 使用当前仓库或已核对的本地 checkout。需要 1.x 方图或单 GLB 工作流时固定 `v1.0.2`。 diff --git a/docs/zh-CN/codex.md b/docs/zh-CN/codex.md index f9f86f8..a10f25c 100644 --- a/docs/zh-CN/codex.md +++ b/docs/zh-CN/codex.md @@ -2,12 +2,15 @@ [English](../codex.md) | 简体中文 -把 canonical `argus` Skill 安装到 Codex： +按需要安装一项或两项 skill 到 Codex： ```bash npx skills add realsee-developer/skills --skill argus --agent codex +npx skills add realsee-developer/skills --skill realsee-blender-reconstruction --agent codex ``` +`$argus` 用于远程全景处理，`$realsee-blender-reconstruction` 用于已有本地资料的可编辑场景重建。Blender 需要本地可运行的 Blender，无需 Argus 凭据；运行要求见[安装总览](install-guides.md)。 + 产品背景见 [Argus 官网](https://argus.realsee.ai/)、[交互 Demo](https://h5.realsee.ai/argus)、[研究主页](https://argus-paper.realsee.ai/)和 [Realsee Developer Platform](https://developer.realsee.ai/)。Codex 必须遵循已安装 Skill 的合同，不能从这些页面推断额外能力：Skill 2.0 只接受 1–99 张本地 RGB8 且严格 2:1 的全景图。 固定 stable 2.0 版本： @@ -23,11 +26,14 @@ npx skills add realsee-developer/skills@v2.0.0 --skill argus --agent codex ```bash git clone https://github.com/realsee-developer/skills.git cd skills -npm install +npm ci (cd .agents/skills/argus && npm ci --omit=dev --ignore-scripts --no-audit --no-fund) CODEX_HOME=$HOME/.codex npm run install:codex-skills +npx skills add . --skill realsee-blender-reconstruction --agent codex ``` +`npm run install:codex-skills` 只安装 Argus，并替换目标目录后安装锁定依赖；Blender 使用上面的 `npx skills` 命令单独安装。 + Codex 从 `${CODEX_HOME:-$HOME/.codex}/skills/argus` 发现 Skill。校验： ```bash @@ -37,19 +43,14 @@ head "${CODEX_HOME:-$HOME/.codex}/skills/argus/SKILL.md" 安装目录包含 `examples/manifest.json`，但不包含全景 JPEG。需要官方示例时，Codex 应询问区域和 Skill 目录外一个尚不存在的绝对输出路径，再运行 `node /scripts/download-examples.mjs --region --output `。命令会校验 manifest 中每个字节数与 SHA-256 后再发布目录。之后实际运行 Argus 仍须另行取得上传同意，并使用对应区域的 Gateway。 -## 凭证 - -继续使用原有运行时合同： - -1. 继承的 `REALSEE_APP_KEY`、`REALSEE_APP_SECRET`、`REALSEE_REGION`； -2. 由 agent 加载现有 `~/.realsee/credentials`； -3. 在 Codex 会话中一字段一轮收集。 +## 凭据与授权 -不要打印值，也不要放进会被记录的命令参数。要跳过提问，可在启动 Codex 前 export 环境变量。 +仅 Argus 需要凭据。按[使用指南](usage.md#凭据与上传授权)检查环境变量、加载已有凭据文件，并通过本地 shell 或安全界面补齐缺失配置。仅在明确授权后以 0600 权限在仓库外保存应用凭据；上传 token 与签名 URL 不得持久化。文件选择不等于上传同意，同一输入和范围复用已有授权。 ## 提示词示例 ```text +使用 $realsee-blender-reconstruction 读取 data/，重建可编辑空间并保存 output/reconstruction_native.blend。 Use $argus 从 /path/a.jpg 和 /path/b.webp 启动批次，并报告 run workspace。 Use $argus 把 CN 示例下载并校验到 /absolute/examples，再取得上传同意后启动它们。 Use $argus 查询一次 /workspace/ 状态。 @@ -77,4 +78,4 @@ node "${CODEX_HOME:-$HOME/.codex}/skills/argus/scripts/run-argus.mjs" collect \ ## 发布策略 -`main` 是集成分支，stable 安装使用 Git tag。2.0 只有在 uploader 0.1.1 以及 global/CN 真机 E2E 都通过后才推进 stable。 +`main` 为集成分支，当前发布通道以 `release-channel.json` 为准，门禁见[发布指南](release.md)。`v2.0.0` 包含 Argus，不包含 Blender skill；Blender 使用当前仓库或已核对的本地 checkout。需要 1.x 方图或单 GLB 工作流时固定 `v1.0.2`。 diff --git a/docs/zh-CN/community.md b/docs/zh-CN/community.md index 46e049a..1bf631a 100644 --- a/docs/zh-CN/community.md +++ b/docs/zh-CN/community.md @@ -6,25 +6,19 @@ ## 报告 Bug -使用 bug report issue template，并包含： - -- Skill 名称，通常是 `argus` -- 失败的命令 -- 失败的生命周期命令（`start`、`status` 或 `collect`） -- 已脱敏的错误输出 -- 操作系统、Node.js 版本和 npm 版本 +使用 `Bug report` issue 模板，附 skill 名称、安装的修订版本、宿主、操作系统、复现步骤和脱敏错误。具体要求见[支持指南](../../SUPPORT.zh-CN.md)：Argus 报告需要生命周期及 Node.js/npm 环境；Blender 报告需要 Blender/集成版本、输入导出类型、失败步骤及预期和实际交付物。 不要包含 `REALSEE_APP_KEY`、`REALSEE_APP_SECRET`、生成凭证、内部 URL、账号标识或私有结果链接。 ## 能力反馈 -当受支持工作流缺少公开能力、文档不清晰或 runtime 行为阻塞集成时，使用 capability request template。请包含： +当受支持工作流缺少公开能力、文档不清晰或 runtime 行为阻塞集成时，使用 `Capability request` 模板。请包含： - 用户工作流 - 期望输入和输出 - 是否需要远程上传 - 相关公开 API 参考或能力文档 -- 问题涉及本地 lifecycle state、live usage、产物校验、安装还是 agent runtime +- 问题涉及Argus 生命周期状态或真实运行、Blender 重建、产物校验还是安装 ## Pull Requests diff --git a/docs/zh-CN/development.md b/docs/zh-CN/development.md index d209593..1e9d1af 100644 --- a/docs/zh-CN/development.md +++ b/docs/zh-CN/development.md @@ -2,12 +2,13 @@ [English](../development.md) | 简体中文 -本仓库是 Realsee agent skills 的 Node.js 工作区。Argus 2.0 runtime 代码与 canonical contracts 位于 `.agents/skills/argus/`。 +本仓库在 `.agents/skills/` 下维护 Realsee agent skills：Argus 包含 Node.js 运行时与 API 合同；`realsee-blender-reconstruction` 包含本地建模指令与参考资料。 ## 要求 - Node.js 22 或更高版本 - npm 10 或更高版本 +- 实际验证重建指令需要本地 Blender；本地建模无需 Realsee 凭据 - 不提交 `.env` 文件或生成的私有产物 ## 本地检查 @@ -28,6 +29,7 @@ npm run validate:repo-boundary npm run validate:skills npm run rebuild npm run validate:channel-metadata +npm run test:repo npm run test:skill ``` @@ -38,14 +40,15 @@ npm run test:skill | `npm run validate:ai` | 修改 `llms.txt` 或仓库入口后。 | | `npm run validate:docs` | 修改双语仓库文档后。 | | `npm run validate:skills` | 修改 skill metadata、README 或 references 后。 | +| `npm run test:repo` | 修改仓库工具或分发行为后。 | | `npm run test:skill` | 修改 `argus` 代码后。 | | `npm run rebuild` | 重新生成并字节校验 Claude plugin 与 CN-only Arkclaw copy。 | -| `npm run doctor` | 通过 `doctor:local` 检查本地前置条件。 | -| `npm run doctor:live` | 检查 live Argus 前置条件和环境。 | +| `npm run doctor` | 通过 `doctor:local` 检查 Argus 与仓库前置条件，不检查 Blender。 | +| `npm run doctor:live -- --skill argus --channel preview` | 仅检查所需配置是否存在；无副作用的能力探测尚未实现，stable 模式会因缺少该验证而失败。 | ## Skill 工作流 -单一事实源是 `.agents/skills/argus/`。Claude plugin 生成到 `plugins/realsee-skills/`；Arkclaw 包生成到 `arkclaw/argus/`，对运行区域、示例下载和相应说明应用确定性的 CN-only overlay。 +所有 skill 的规范源码在 `.agents/skills/`。Claude 包含两项 skill，Arkclaw 仅包含 Argus。Claude plugin 生成到 `plugins/realsee-skills/`；Arkclaw 包生成到 `arkclaw/argus/`，对运行区域、示例下载和相应说明应用确定性的 CN-only overlay。 修改 `argus` 时： @@ -56,12 +59,14 @@ npm run test:skill 不要直接编辑两个生成 copy。新增 runtime 行为应通过 `ArgusTaskPort` 与 `ObjectTransferPort` fake 测试，并覆盖输入、生命周期、输出合同与幂等。 +修改 Blender 指令时，编辑 `.agents/skills/realsee-blender-reconstruction/` 及双语参考资料，然后运行 `npm run validate:skills`、`npm run rebuild` 和 `npm run ci`。文档检查不能证明建模行为：改变建模流程时，使用合适的本地资料验证受影响的指令，并报告实际验证范围。此纯指令 skill 不要求 npm 运行时或远程服务 fake。 + ## 配置 -公开文档只使用这些环境变量名： +Argus 配置使用以下环境变量： - `REALSEE_APP_KEY` - `REALSEE_APP_SECRET` - `REALSEE_REGION` -继续支持现有 agent-driven `~/.realsee/credentials` 加载流程。不要提交真实值、账号标识、内部 URL、生成凭证、`output.zip`、解压产物或临时 workspace。 +继承环境变量、已有 `~/.realsee/credentials` 和缺失配置的本地安全设置方式见 [Argus 凭据配置](usage.md)。只有用户明确授权才可在仓库外以 0600 权限保存应用凭据，临时上传令牌和签名 URL 不得持久化。不要提交真实值、账号标识、内部 URL、生成凭证、`output.zip`、解压产物或临时 workspace。 diff --git a/docs/zh-CN/install-guides.md b/docs/zh-CN/install-guides.md index 000426d..662cdef 100644 --- a/docs/zh-CN/install-guides.md +++ b/docs/zh-CN/install-guides.md @@ -2,14 +2,14 @@ [English](../install-guides.md) | 简体中文 -所有安装路径使用同一份 canonical `argus` Skill 2.0 source，以及显式 `start` / `status` / `collect` 生命周期。 +本仓库提供两项 skill：`argus` 将全景图上传到 Realsee 进行远程处理；`realsee-blender-reconstruction` 将已有本地导出重建为可编辑 Blender 场景。规范源码位于 `.agents/skills/`。 ## 宿主对照 | 宿主 | 安装 | Skill 句柄 | 指南 | | --- | --- | --- | --- | -| Claude Code | `/plugin marketplace add realsee-developer/skills`，然后 `/plugin install realsee-skills@realsee-developer-skills` | `realsee-skills:argus` | [Claude Code](claude-plugin.md) | -| Codex | `npx skills add realsee-developer/skills --skill argus --agent codex` | `$argus` | [Codex](codex.md) | +| Claude Code | `/plugin marketplace add realsee-developer/skills`，然后 `/plugin install realsee-skills@realsee-developer-skills` | `realsee-skills:argus`, `realsee-skills:realsee-blender-reconstruction` | [Claude Code](claude-plugin.md) | +| Codex | `npx skills add realsee-developer/skills --skill argus --agent codex` | `$argus`, `$realsee-blender-reconstruction` | [Codex](codex.md) | | 所有检测到的宿主 | `npx skills add realsee-developer/skills --skill argus --agent '*'` | 按宿主确定 | 本指南 | | Arkclaw | 发布的 Arkclaw ZIP | `argus` | 仅 CN | @@ -19,9 +19,15 @@ npx skills add realsee-developer/skills --skill argus ``` +表中 `npx skills` 命令安装 Argus；安装 Blender 时将 `--skill argus` 替换为 `--skill realsee-blender-reconstruction`。Claude 当前插件包含两项 skill；Arkclaw 与 `npm run install:codex-skills` 只安装 Argus。 + +## 运行要求 + +Argus 需要 POSIX shell、Node.js 22+、npm 10+、npm registry 与区域 Gateway 网络访问，以及启用 Argus 的应用凭据。首次运行前，agent 按已安装 `SKILL.md` 使用锁文件补齐运行依赖。Blender skill 需要可运行的本地 Blender 和已有扫描导出、点云、CAD 或全景等资料；本地重建无需 Realsee 凭据。 + ## 可复现版本 -需要可复现安装时使用 release tag： +Argus 可固定到 `v2.0.0`。该标签不包含 Blender skill；Blender 请使用当前仓库版本或固定到已核对包含它的本地 checkout。 ```bash npx skills add realsee-developer/skills@v2.0.0 --skill argus @@ -35,13 +41,11 @@ npx skills add realsee-developer/skills@v1.0.2 --skill argus ## 凭证 -所有宿主使用 `REALSEE_APP_KEY`、`REALSEE_APP_SECRET`、`REALSEE_REGION`（`global` 或 `cn`）。现有 Skill 流程先检查继承的 shell 环境，再由 agent 加载 `~/.realsee/credentials`，最后一字段一轮询问。Arkclaw 固定 region 为 `cn`。 - -不要打印凭证，也不要把它们放进会被记录的命令参数。目标账号没有 Argus 能力时见 [SUPPORT.zh-CN.md](../../SUPPORT.zh-CN.md)。 +仅 Argus 需要应用凭据；Arkclaw 固定区域为 `cn`。环境变量、已有凭据文件、安全配置与上传授权流程统一见[使用指南](usage.md#凭据与上传授权)。目标账号没有 Argus 能力时见 [SUPPORT.zh-CN.md](../../SUPPORT.zh-CN.md)。 ## 安装之后 -宿主调用： +Blender 的调用与交付要求见[使用指南](usage.md)。Argus 在依赖和凭据就绪、已取得上传同意后调用： ```bash node /scripts/run-argus.mjs start --image /absolute/a.jpg --workspace /absolute/workspace --yes --json diff --git a/docs/zh-CN/public-distribution.md b/docs/zh-CN/public-distribution.md index 18f6571..d368274 100644 --- a/docs/zh-CN/public-distribution.md +++ b/docs/zh-CN/public-distribution.md @@ -2,25 +2,26 @@ [English](../public-distribution.md) | 简体中文 -推进 Argus Skill 2.0 前逐项检查。 +计划变更分发或发布时使用此清单。当前 Argus 元数据为 `2.0.0` / stable / passed；首次 2.0 推进属于历史。门禁条件见[发布指南](release.md)。下列 Argus 专属运行时和真实运行检查不适用于纯指令型 Blender skill。 ## 仓库与版本 - [ ] `v1.0.2` 保持不变，不存在 `v1.0` 别名。 -- [ ] 根包、Skill 包、plugin 包与 `release-channel.json` 版本一致。 -- [ ] 两区真实 E2E 通过前，preview metadata 保持 pending。 +- [ ] 根包、Argus runtime 包、plugin 包与 `release-channel.json` 版本一致。 +- [ ] 新 preview 的 tag 与 `next_release_candidate` 和元数据版本匹配；两区真实 E2E 通过前，元数据保持 development/preview/pending。 - [ ] 干净 clone 上 `npm run ci` 与目标 release gate 通过。 - [ ] Git status 不含凭证、`.env`、workspace、输出 ZIP 或解压产物。 ## Canonical 分发 - [ ] `npm run rebuild` 同时生成 `plugins/realsee-skills/` 与 `arkclaw/argus/`。 -- [ ] Claude plugin 文件与 `.agents/skills/argus/` 字节一致。 +- [ ] Claude plugin 包含 `argus` 和 `realsee-blender-reconstruction`，文件与 `.agents/skills/` 下各自规范目录字节一致。 - [ ] Arkclaw 除运行区域、示例下载器和相应生成说明所需的确定性 CN-only overlay 外，均为 canonical bytes。 -- [ ] Codex 安装与 `npx skills add . --skill argus` 都解析同一 canonical Skill。 +- [ ] 专用 Codex 安装器与 Arkclaw 包仅支持 Argus；`npx skills add . --skill argus` 和 `npx skills add . --skill realsee-blender-reconstruction` 分别解析对应规范 skill。 +- [ ] 按版本安装的示例仅指定实际包含该 skill 的 tag；`v2.0.0` 不包含 Blender。 - [ ] Plugin manifest 没有 `userConfig` 或 MCP server。 -## 合同与文档 +## Argus 合同与文档 - [ ] Gateway OpenAPI 恰好包含四个公开 method 和两个基础地址。 - [ ] 双语算法 I/O 对 auto ID、`missing_ids`、`error`、可选法线、固定 `right-handed, Y-up`、stable EXR-only 深度描述一致。 @@ -28,7 +29,7 @@ - [ ] 双语使用与迁移文档说明方图/单 GLB 用户固定 `v1.0.2`。 - [ ] 文档不再把 detached polling、`--async`、`--resume` 或 2.0 H5 preview 描述成支持能力。 -## Runtime 验证 +## Argus runtime 验证 - [ ] 输入测试覆盖 1、99、100 张；JPEG/PNG/WebP；非法 ratio/RGB8；重复名；嵌套/损坏/Zip Slip/Bomb。 - [ ] Gateway 测试覆盖路径、method、envelope、状态映射和两个 region base。 @@ -36,7 +37,7 @@ - [ ] 产物测试覆盖 success/partial/error、ID 一致性、非法路径、无效 GLB/EXR、缺 pose/depth、可选 intrinsics 和原子恢复。 - [ ] `start`、`status`、`collect` 返回文档规定的 JSON 与退出码。 -## Uploader 门禁 +## Uploader 发布检查 - [ ] `@realsee/universal-uploader@0.1.1` 已发布且可安装。 - [ ] 单测、类型检查、构建、`npm pack` smoke 与 GitLab CI 通过。 @@ -45,8 +46,9 @@ ## 真实 E2E 与推进 -- [ ] `v2.0.0-rc.3` 在 global/AWS 完成真实多图运行。 -- [ ] `v2.0.0-rc.3` 在 CN/腾讯 COS 完成真实多图运行。 +- [ ] 选定的 Argus 候选版本在 global/AWS 完成真实多图运行。 +- [ ] 选定的 Argus 候选版本在 CN/腾讯 COS 完成真实多图运行。 - [ ] 两区都验证下载以及 success、partial、error 处理。 -- [ ] 上述通过后才设置 `state: stable`、`stable_gate: passed` 并发布 `v2.0.0`。 -- [ ] 通过 Claude plugin、Codex、`npx skills` 与 CN-only Arkclaw 做全新安装测试。 +- [ ] 上述通过后才为选定版本记录 stable/passed 元数据、移除 `next_release_candidate`，并在发布新 tag 前取得授权。 +- [ ] 通过 Claude plugin、仅支持 Argus 的 Codex 安装器、每项 skill 的 `npx skills` 与 CN-only Arkclaw 做全新安装测试。 +- [ ] Blender 指南变更须对照规范 skill 审核输入前提、本地工具要求、可编辑交付物和适用验收项；未执行真实重建时不得声称已验证。 diff --git a/docs/zh-CN/release.md b/docs/zh-CN/release.md index 05e3240..afc5ab7 100644 --- a/docs/zh-CN/release.md +++ b/docs/zh-CN/release.md @@ -2,53 +2,35 @@ [English](../release.md) | 简体中文 -发布就绪状态记录在 `release-channel.json`，由 `scripts/release-gate.mjs` 强制。 +发布就绪状态记录在 `release-channel.json`，由 `scripts/release-gate.mjs` 强制检查。当前元数据记录版本 `2.0.0`、通道 `stable`，以及 Argus 的 `state: stable` / `stable_gate: passed`；未单独声明 Blender 的发布状态。 ## 版本线 - `v1.0.2` 是冻结的旧版本，支持方图和旧版单 GLB 工作流。不要增加可变或含义模糊的 `v1.0` tag。 -- `v2.0.0` 保持 Skill ID 为 `argus`，使用多全景 ZIP 接口，不提供 1.x fallback。 +- `v2.0.0` 保持 Skill ID 为 `argus`，使用多全景 ZIP 接口，不提供 1.x 回退。该 tag 不含 `realsee-blender-reconstruction`；安装 Blender skill 应选择已包含它的修订版本。 -实现阶段 metadata 保持 `channel: development`、`state: preview`、`stable_gate: pending`。不能只因本地测试通过就把 2.0 标记 stable。 +## 当前门禁 -## 门禁 - -Preview： - -```bash -npm run release:gate -- --channel preview --tag v2.0.0-rc.3 -``` - -Stable： +检查当前记录的稳定版本： ```bash npm run release:gate -- --channel stable --tag v2.0.0 ``` -两个门禁都会运行仓库检查、Claude/Arkclaw 生成与字节一致性，以及完整 Skill 测试。Stable 还要求公开的 Gateway 四路径 OpenAPI 合同。 - -## 必须顺序 +Preview 门禁要求预发布 tag 的基础版本与元数据版本相同，完整 tag 等于 `skills.argus.next_release_candidate`；元数据还须为 `channel: development`、`state: preview`、`stable_gate: pending`。当前 stable 元数据没有待发布候选，因此不能通过 preview 门禁。仅在获得授权的发布变更中选择并记录下一候选版本。 -1. 保持现有 `v1.0.2` tag 不变。 -2. 发布并验证 `@realsee/universal-uploader@0.1.1`。 -3. 切 `v2.0.0-rc.3`，在 CN 与 global 各跑真实多图 E2E。 -4. 两区都验证上传、任务完成、success/partial/error 收集与结果下载。 -5. 把发布 metadata 改成 stable/passed，发布 `v2.0.0`。 -6. 验证双语迁移指南，以及 Claude、Codex、`npx skills`、CN-only Arkclaw 的全新安装。 +两个门禁都会执行秘密扫描、文档与 AI 索引校验、仓库边界与 skill 校验、分发重建、生成文件干净检查、烟测、工作区干净检查、通道元数据校验、`test:repo`、`test:skill` 和 Argus 生产依赖审计。相比 `npm run ci`，发布门禁额外检查生成文件和工作区是否干净、运行烟测并审计生产依赖。应在已安装依赖的干净检出中执行；门禁会重新生成分发文件。 -Uploader 发布门禁必须通过单测、类型检查、构建、`npm pack` 安装烟测和生产依赖 audit，并且没有 high/critical 漏洞。 +Stable 还要求公开 Gateway OpenAPI 合同（四项必需操作、必需 schema 和两个区域基础地址）、匹配的稳定版本与 tag、`stable/stable/passed` 元数据、CN/global 两个区域，且不存在 `next_release_candidate`。元数据记录维护者对真实两区 E2E 的批准；门禁本身不会执行这些远程运行。 -## Live 验证记录 +## 首次 2.0 推进的历史步骤 -不要把凭证、签名 URL、私有 task locator 或生成产物作为证据提交。只在公开仓库之外记录脱敏通过/失败结果。Stable 必须有 AWS/global 与腾讯 COS/CN 真机运行，本地 fake 不能替代。 +首次 2.0 推进使用 `@realsee/universal-uploader@0.1.1`，随后以 `v2.0.0-rc.3` 在 CN 和 global 验证真实多图流程，最终设置 stable/passed 元数据并发布 `v2.0.0`。这些是历史发布步骤，不是重新创建或覆盖既有 tag 的指令。 -## Tag +发布 uploader 时，验证单测、类型检查、构建、`npm pack` 安装烟测，以及不存在 high/critical 漏洞的生产依赖审计。推进 Argus 发布时，针对选定候选版本验证上传、任务完成、success/partial/error 收集、结果下载、双语迁移指南和受支持宿主的全新安装。见[分发检查清单](public-distribution.md)。 -所有 stable 条件满足后： +## 真实验证与发布 -```bash -git tag -a v2.0.0 -m "v2.0.0" -git push origin v2.0.0 -``` +不要把凭证、签名 URL、私有任务定位信息或生成产物作为证据提交。只在公开仓库之外记录脱敏通过/失败结果。Argus 稳定版推进要求真实 AWS/global 与腾讯 COS/CN 验证；本地模拟不能替代。运行前须取得上传授权。 -Release workflow 会先跑 stable gate，再创建 GitHub release。 +发布需要明确授权和新的已批准 tag；保留既有 tag。Release workflow 会分类推送的 tag，执行对应 preview 或 stable 门禁，然后从全新检出重建、检查生成文件已提交、构建并验证 Arkclaw ZIP，最后创建 GitHub release。 diff --git a/docs/zh-CN/usage.md b/docs/zh-CN/usage.md index 3fd2c05..dd1858a 100644 --- a/docs/zh-CN/usage.md +++ b/docs/zh-CN/usage.md @@ -16,7 +16,7 @@ npx skills add . --skill realsee-blender-reconstruction --agent codex > 使用 $realsee-blender-reconstruction 读取 data/，优先重建有证据的空间结构和连接，保存 output/reconstruction_native.blend，完成来源对照并在重开后实际验证编辑。 -该 skill 包含按需启用的漫游、物理/USDZ、图文生成资产与网页预览指导。`npm run install:codex-skills` 仍为 Argus 专用安装器。本文其余部分介绍 Argus 远程处理。 +先确认本地 Blender 可运行并检查其版本；输入、脚本与产物存放在建模项目中。该 skill 包含按需启用的漫游、物理/USDZ、图文生成资产与网页预览指导。`npm run install:codex-skills` 仍为 Argus 专用安装器。本文其余部分介绍 Argus 远程处理。 官方资料：[Argus 官网](https://argus.realsee.ai/)、[交互 Demo](https://h5.realsee.ai/argus)、[研究主页](https://argus-paper.realsee.ai/)和 [Realsee Developer Platform](https://developer.realsee.ai/)。这些站点可能展示更广的照片和产品工作流；Argus Skill 只接受 1–99 张本地 RGB8 且严格 2:1 的全景图。 @@ -35,6 +35,14 @@ npx skills add realsee-developer/skills --skill argus --agent '*' npx skills add . --skill argus ``` +## 凭据与上传授权 + +仅 Argus 需要 `REALSEE_APP_KEY`、`REALSEE_APP_SECRET` 和 `REALSEE_REGION`（`global` 或 `cn`；Arkclaw 固定为 `cn`）。Agent 先检查继承的 shell 环境；配置不足时加载已有 `~/.realsee/credentials`，仍有缺失时只请求缺失配置。秘密应由用户在本地 shell 或安全凭据界面配置，不在聊天中逐字段收集。 + +不得回显凭据或把值放入会被记录的命令参数、环境变量前缀。仅在用户明确选择持久保存时，才可将应用凭据保存在仓库外的 `~/.realsee/credentials`，权限为 0600。上传 token 和签名 URL 不得持久化；运行状态不保存凭据。 + +`start` 会把所选文件发送到 Realsee。文件选择和示例下载均不等于上传同意；用户明确要求上传这些文件即构成同意，同一输入和范围内复用已有授权，无需重复确认。示例中的 `--yes` 表示已取得同意，不能代替用户授权。 + ## 官方示例清单 安装后的 Skill 包含 `examples/manifest.json`，不包含全景 JPEG。需要第一方示例时，请选择与 `REALSEE_REGION` 一致的区域，并指定 `` 外一个尚不存在的绝对目录： @@ -126,4 +134,4 @@ Collect 会保留 `output.zip`，安全解压，校验 manifest 与产物，并 - 输出 Schema：[argus-output.schema.json](../../.agents/skills/argus/references/argus-output.schema.json) - 机器索引：[llms.txt](../../llms.txt) -真实 Argus 运行属于远程上传，必须先取得用户同意，且不得持久化凭证、上传 token 或签名结果 URL。 +运行前遵循上方凭据与上传授权要求；仅将本地已校验产物作为持久交付。 diff --git a/llms.txt b/llms.txt index c68060e..c55af28 100644 --- a/llms.txt +++ b/llms.txt @@ -1,7 +1,8 @@ # Realsee Skills Purpose: Source-available Realsee agent Skill distribution for users and agent runtimes. -Current release line: Argus Skill 2.0.0; legacy square/single-GLB workflows remain pinned at v1.0.2. +Current release line: Argus Skill 2.0.0 (stable/passed in release-channel.json); legacy square/single-GLB workflows remain pinned at v1.0.2. +Version scope: v2.0.0 contains Argus only. Install Blender reconstruction from the current repository or a checkout containing that skill; Argus release metadata does not certify Blender results. Agent priority: inspect this file, then README.md, docs/usage.md, AGENTS.md, and the selected Skill definition below. Languages: English default; Simplified Chinese in README.zh-CN.md, docs/zh-CN/, and same-directory *.zh-CN.md pairs. @@ -14,6 +15,7 @@ Local Blender Skill: - Output: editable native Blender space, source comparisons, saved-file editing verification. - Optional: walkthrough, physics/USDZ, generated secondary assets, lightweight web preview. - No credentials or remote upload needed for local inputs; Argus generation is separate. +- Repository install: npx skills add realsee-developer/skills --skill realsee-blender-reconstruction --agent codex - Local install: npx skills add . --skill realsee-blender-reconstruction --agent codex - Included in generated Claude plugin; Arkclaw and install:codex-skills remain Argus-specific. @@ -72,7 +74,8 @@ Explicit CLI lifecycle: Credential contract: - Required: REALSEE_APP_KEY, REALSEE_APP_SECRET, REALSEE_REGION. - Regions: global -> app-gateway.realsee.ai; cn -> app-gateway.realsee.cn. -- Existing precedence: inherited shell env, then agent-loaded ~/.realsee/credentials, then one-field-per-turn Q&A. +- Resolution: nonempty inherited shell environment, then an existing agent-loaded ~/.realsee/credentials; configure missing values through the local shell or a secure credential interface without echoing secrets into chat. +- Persist app credentials only with explicit user authorization, outside the repository in mode-0600 ~/.realsee/credentials. Never persist temporary upload tokens or signed URLs. - Never print values or pass them as recorded command arguments. - state.json/result.json never store credentials, upload tokens, presigned URLs, or raw provider errors. @@ -101,6 +104,8 @@ Repository map: - Codex: docs/codex.md and docs/zh-CN/codex.md - Usage: docs/usage.md and docs/zh-CN/usage.md - Public distribution: docs/public-distribution.md and docs/zh-CN/public-distribution.md +- Development: docs/development.md and docs/zh-CN/development.md +- Release gates: docs/release.md and docs/zh-CN/release.md - Generated Claude plugin: plugins/realsee-skills/ - Generated CN-only Arkclaw copy: arkclaw/argus/ - Marketplace: .claude-plugin/marketplace.json @@ -116,11 +121,12 @@ Common maintenance commands: - npm run rebuild - npm run check:claude-sync - npm run check:arkclaw-sync +- npm run test:repo - npm run test:skill - npm run ci Safety: -- Every real Argus run is a remote upload and requires user consent. +- Every real Argus run is a remote upload and requires informed user consent for the selected files. File selection alone is not consent; reuse existing authorization for the same input and scope. - Do not commit secrets, generated credentials, account identifiers, private URLs, output.zip, extracted artifacts, .env files, or temporary workspaces. - Edit .agents/skills/; Claude includes canonical skills, and Arkclaw rebuilds only the Argus source. - Do not add internal evidence, private source references, live scorecards, internal process docs, or local absolute paths. diff --git a/plugins/realsee-skills/copy-manifest.json b/plugins/realsee-skills/copy-manifest.json index 729e3d8..fd5e321 100644 --- a/plugins/realsee-skills/copy-manifest.json +++ b/plugins/realsee-skills/copy-manifest.json @@ -154,7 +154,7 @@ { "source": ".agents/skills/argus/SKILL.md", "target": "plugins/realsee-skills/skills/argus/SKILL.md", - "size": 9192 + "size": 9140 }, { "source": ".agents/skills/argus/src/archive.mjs", diff --git a/plugins/realsee-skills/skills/argus/SKILL.md b/plugins/realsee-skills/skills/argus/SKILL.md index 42eb902..d90f6a5 100644 --- a/plugins/realsee-skills/skills/argus/SKILL.md +++ b/plugins/realsee-skills/skills/argus/SKILL.md @@ -42,7 +42,7 @@ Resolve values in the existing order: && [ -n "${REALSEE_REGION:-}" ] && echo present || echo missing ``` -2. If `~/.realsee/credentials` already exists, load it into the shell and probe presence. Never display the file: +2. If configuration is incomplete and `~/.realsee/credentials` already exists, load it into the shell and probe presence. Never display the file: ```bash [ -f ~/.realsee/credentials ] && set -a && . ~/.realsee/credentials && set +a; \ @@ -77,11 +77,10 @@ The downloader publishes the directory only after every file passes its manifest Before starting, ensure the user has selected the files and consented to sending them to Realsee for remote processing. An explicit request to upload those files is sufficient; file selection alone is not consent. If either is missing, ask one question stating that the selected files will leave the machine. Reuse existing consent for the same input and scope. Do not ask a redundant second confirmation. -For repeated images: +Run lifecycle commands in a shell with credentials resolved in step 2. For repeated images: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs start \ +node /scripts/run-argus.mjs start \ --image "/absolute/path/a.jpg" \ --image "/absolute/path/b.webp" \ --workspace "/absolute/workspace-root" \ @@ -91,14 +90,13 @@ set -a; . ~/.realsee/credentials; set +a; \ For an existing ZIP: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs start \ +node /scripts/run-argus.mjs start \ --zip "/absolute/path/input.zip" \ --workspace "/absolute/workspace-root" \ --yes --json ``` -If credentials already exist in the inherited shell, omit the `source` prefix. Capture `workspace_dir` from the JSON response; it is the durable run handle for later commands. +When starting a new shell for `status` or `collect`, resolve credentials there before invoking the command. Capture `workspace_dir` from the JSON response; it is the durable run handle for later commands. `start` validates and packages locally, uploads one ZIP, submits once, persists `task_code`, and returns. It does not poll in the background. Never automatically rerun `start` after `submission_unknown`: the submit operation is not idempotent and a blind retry may create a duplicate task. @@ -107,8 +105,7 @@ If credentials already exist in the inherited shell, omit the `source` prefix. C Run one status query: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs status \ +node /scripts/run-argus.mjs status \ --workspace "" --json ``` @@ -119,8 +116,7 @@ Interpret `task_status` as `queued`, `processing`, `succeeded`, or `failed`. Whe When the task succeeds, run: ```bash -set -a; . ~/.realsee/credentials; set +a; \ - node /scripts/run-argus.mjs collect \ +node /scripts/run-argus.mjs collect \ --workspace "" --json ```