# 标准空间理解任务

用户只说“用 realsee-spatial-analysis 对 `<资源码>` 做空间理解分析”，并给出项目或数据目录时，按本契约执行，不再要求用户重复长提示词。**默认输入**：给出 `<app>` 且项目 BFF 已配对时，先用 `scripts/materialize_work_inputs.py` 从项目 `GET /api/work/<RC>` 物化 `work.json`/`floorplan.json`；本地 `<data>` 只在离线、无项目或无凭据时才需要。

## 输入

| 输入 | 说明 |
| --- | --- |
| `<app>` | 基于 vr-cli 的项目；在项目目录中发起时默认当前目录（`--app` 可省略）；没有项目时只交付数据结果和报告，不创建应用 |
| `<data>` | 可省略。本地数据目录：包含 `work.json`、可选 `floorplan.json`，以及 `resources/<RC>/` 补充产物；有 `<app>` 时默认由 `materialize_work_inputs.py` 从项目 BFF 物化到 `<app>/resources/<RC>/` |
| `<RC>` | Work 的资源码；没有 Work 时用本地数据 ID，不伪造资源码 |
| `<out>` | 独立输出目录；不要写回 `<data>` 原件，除非用户明确授权 |

## 输入物化（默认）

有 `<app>` 时默认先物化，只有离线、无项目或无凭据时才直接用客户 `<data>`：

```bash
cd <app>  # 也可在任意目录运行并显式传 --app <app>
python <skill-dir>/scripts/materialize_work_inputs.py \
  --resource-code <RC>
```

首次成功获取时，脚本自动创建 `<app>/resources/<RC>/`。得到 `<app>/resources/<RC>/work.json`（BFF envelope：`work`/`workCode`/`capabilities`）与可选 `<app>/resources/<RC>/floorplan.json`（`capabilities.modelFloorplan.data`，含 `computed_data`，可直接用于 `render_result.py --floorplan`；`--floorplan` 也接受未拆分的 work-envelope.json，预览会据此补画墙体线、窗、柱并在图例列出构件数量）。脚本只访问项目本机 BFF，不接收、不打印密钥；BFF 未启动返回连接错误，未配对返回 401 提示，Work 未授权返回 403。后续命令中的 `<data>`：客户数据包模式指数据目录，默认物化模式指 `<app>/resources/<RC>/`。此处也保存同一资源码的 API 下载素材。已取得的本地输入可直接复用；刷新已有物化快照时使用 `--force`，客户原件需保留。`<out>/inputs/` 由交付步骤写入本轮输入快照。

## 默认目标

以下四项是标准任务的默认范围，不是可选项：

1. **盘点与解释**：每类产物是什么、能做什么、如何读取、需要哪些伴随文件、与哪些实体关联、哪些能力受限。
2. **坐标与空间分析**：核对点位身份/顺序/坐标变换；在输入支持时完成空间分布、物品识别、空间连通性和关键测量。
3. **结果交付**：`spatial-analysis.v2.json`、`data-graph.{json,md,html}`、`inventory.json`、`inputs/{work,floorplan}.json`、单文件 `result-preview.html`、`交付说明.md`、`data-guide.md`。
   `pipeline.py run` 只导出分析 JSON 与点云覆盖层；其余产物用一条命令补齐（幂等，缺什么补什么）：

   ```bash
   python <skill-dir>/scripts/pipeline.py deliver --resource-code <RC> \
     --workspace <输出目录> --resources-root <资源父目录> [--app <应用工程>]
   ```

   也可以让 `run` 直接接着做：`pipeline.py run ... --deliver`；交付前想确认齐不齐，加 `--check`
   只审计不写文件（缺项列表 + 退出码 1）；要确认产物没被改过，加 `--verify`（按 `delivery-manifest.json` 逐项重算 sha256，
   不一致时列出 `mismatched` 并退出码 1）。

   `run` 还会在工作区根写 `run-manifest.json`：generator/stageVersions/各阶段缓存键与耗时/输入 sha256/生效阈值/
   本次选择（档位、设备、点位子集、点云格式、房间来源）与告警。它是纯记录，不参与缓存键；换人换机器复算时先用它对齐。输出 JSON 的 `states` 逐项给出
   `written/reused/skipped/failed`，`missing` 列出仍缺的必需产物；有缺失时退出码为 1，修好输入后重跑即可。
4. **应用回装**：把结果包写入 `<app>/analysis-data/<RC>/`，刷新后确认「空间智能」入口可打开并显示结果。有 `<app>` 时这是默认步骤，不需要额外的开发授权；宿主缺消费层时按 [已有项目接入](my-app.md) 安装随包插件后继续。
   结果包同时包含同目录的 `result-preview.html`（离线结果预览页）；装好后在 Viewer 的空间智能面板右上点「数据源」即可在新标签页打开，路由是 `GET /api/analysis/<RC>/preview`。

## 执行顺序

不想记参数时，直接不带参数运行 `pipeline.py` 就会进入问答向导：它先在当前目录找 `resources/`，
列出里面的作品让你选（只有一个时自动选中），显示「本地已有什么 / Work 声明什么 / 需要下载什么」。
只有确实要下载（缺的全景图、模型、点云，或未缓存的检测权重）时才问一次「同意下载并继续」，其余情况不问；
文档档还会问一次方向：「首点位（0 号）打开全景时的初始视角对着哪个方向？」，答八方位（北/东北/…）或
0-360 的角即可，回车跳过就只写相对朝向；
自动识别当前 Viewer 工程，分析成功后回装，不再单独询问；完成后只告知用户分析与回装结果。路径和命令开关由工具内部处理，不让用户填写参数。非交互环境（管道、CI）会退回 JSON 并提示 `all` 用法，不会卡在问答上。

一条命令跑完整条链路（等价于下面 A→E 的顺序执行，只是把确认门做进了命令）：

```bash
python <skill-dir>/scripts/pipeline.py all --resource-code <RC> --resources-root <资源父目录> --workspace <输出目录>
```

`all` 先做只读预检（`inspect` 等价的本地状态 + `prepare_work_assets.py --dry-run` 的声明数量与字节数），
输出 `plan` 与 `downloads`：按**实体数据**列出（全景图 / 模型 / 点云，各自约多少 MB）以及是否要下载检测权重。
- 完整档可用或用户已明确选档，且无需下载时，脚本直接执行（输出 `autoConfirmed`）。本地已有的实体数据（包括用户自己提供的）一律直接使用，不重新下载、不覆盖。
- 有要下载的东西：**停下来问一次**，列出上面的清单；确认后加 `--yes` 再运行。不想下某一类就加 `--no-panoramas` / `--no-model` / `--no-point-cloud`，完全不下载加 `--inputs work-only`。
- 下载失败（实体数据或权重）：停止并提供重试或显式降档的选择，不自动回退到 work-only，不伪造数据。
- 本地与 Work 都补不上完整档缺的网格 / 全景时，`choose` 输出的 `choice.apiDownload` 给出第三条路：经项目 BFF 的开放平台资源下载接口获取（**计费**，见 [download-api.md](download-api.md)）。用户同意后加 `--api-download` 重跑：先出计划（要提交的任务、计费口径）；`--yes` 只确认下载清单，不含计费授权，提交还要再加 `--confirm-billing`（只加 `--yes` 会停在 `billingConfirmation`）；任务还在打包返回 `API_DOWNLOAD_PROCESSING`，同一命令重跑续查，不会重复提交。任务失败、过期或提交结果未知返回 `API_DOWNLOAD_NEEDS_DECISION`，提交结果未知时先到下载中心核对。用户明确同意重新下单后才加 `--resubmit --yes --confirm-billing`。
- 预检的 `capabilities` 说明这个空间能到哪一档（两档的最少数据见 [minimum-data.md](minimum-data.md)）。**缺数据时 `all` 不自行降档**：输出可选档位（A 用 work-only / B 补数据再跑 / C 停下）等用户决定；典型是 model 只有 `.at3d` 兼容字段（`LEGACY_AT3D_MODEL`）又没有平面图。用户选了 `--inputs work-only` 才打印 `本次走 work-only（没有平面图）` 并跳过实体下载与权重下载；`--inputs full` 表示不接受降档。连平面图与 `observers` 都没有时才以 `NO_BUILTIN_TIER` 退出 6。
- 缺少平面图与入户门信息时不要猜方位：只问一次“首点位（0 号）打开全景时的初始视角对着罗盘哪个角”，用 `--compass-deg 270` 指定（默认参考点位就是首点位；也可先跑 `scripts/orientation.py`）。报告保留“相对朝向：方位来自用户指定，未做地理北校准”的说明；用户不确认时报告与交付说明会写「方位（未指定）」并说明没有地理北、房间朝向不可用，这时只能写相对朝向。

**对话停止点**：遇到 `mode: "choose"` 或 `awaitingChoice: true`，先说明缺项和实际可选方案，直接问用户选 A 精简 / B 补数据 / C 暂缓，并结束本轮等待回复。仅有一个可用档位时也这样处理。示例「当前只能完成点位分析，缺少三角网格和平面图。你希望 A 先做点位分析、B 补齐素材后做完整分析，还是 C 暂缓？」等待期间不发起分析、下载或回装。

确认后按顺序执行 开放平台下载（如选了）→ 物化缺失实体 → 权重检查 → `run` → `deliver`（自动识别当前 Viewer 并回装），并在交付前把确认写进 `analysis-decisions.json`。引擎尚在等待选择或本次没有导出结果时，不继续交付/回装旧文件。
`--plan-only` 强制只出计划；`--max-download-mb <N>` 在实体数据预计下载超过上限时拒绝执行（退出码 2）；
`--skip-materialize` / `--skip-fetch-model` / `--no-record-decision` 分别跳过对应步骤。`--api-download`、`--api-products`、`--api-cloud-format`、`--base-url`、`--resubmit`、`--confirm-billing` 只属于开放平台下载步骤，不会转给引擎。旧的 `--choice A|B|C|D` 已取消。

需要逐步控制时按下面 A→E 手动执行。

### A. 盘点

```bash
python <skill-dir>/scripts/inventory.py --root <data> --work <data>/work.json --out <out>/inventory.json
python <skill-dir>/scripts/check_env.py --json
```

输出 `data-guide.md`：逐类说明用途、读取入口、伴随文件、关联、可用/不可用及原因。盘点只是结构候选，不是格式验证或对齐证明。

### B. 预检与物化确认（强制对话门）

先做两次只读预检，不要直接下载：

```bash
python <skill-dir>/scripts/pipeline.py inspect --resource-code <RC> --resources-root <data> --work-json <data>/work.json
python <skill-dir>/scripts/prepare_work_assets.py --work-json <data>/work.json \
  --out <资源父目录> --dry-run --json
```

`inspect` 的 `declaredNotLocal` 列出「Work 声明了、本地还没有」的全景、mesh 与点云（`type=point_cloud` 的 PLY tileset）；dry-run 给出站数、面数、mesh tile 数、点云 tile 数以及 HEAD 探测的字节数，不创建目录、不写文件。

判定（只看实体数据：全景图、模型、点云）：

- 本地已有的，直接使用，不问、不下载；用户额外提供的数据同样优先使用。
- Work 声明了、本地没有的，才需要下载；下载前确认**一次**，并与检测权重（含按需安装的完整档依赖，如 E57 读取库）合并成同一个问题。
- 下载受阻时，说明已取得和仍缺的素材，再请用户决定重试、补数据、使用可用的精简档或暂缓。
- 按本地已有数据判断最高可用档位。完整档缺素材时先等用户选择补齐、使用精简档或暂缓。
- `work.json`/`floorplan.json` 来自项目接口，不属于需要确认的下载。

问题模板（把 dry-run 的真实数字填进去，按实体列出，不用档位名；没有的实体不列）：

```
需要下载（本地没有）：
- 全景图：<N> 站（<F> 个面），约 <X> MB
- 模型：<T> 个 tile，约 <Y> MB
- 点云：<P> 个 tile，约 <Z> MB
- 检测权重：约 620 MB（并按需安装完整档依赖，含 E57 读取库）
请选择下载并继续、使用已有数据做精简分析，或暂缓。
```

确认记录（`point=inputs`）由 `pipeline.py all` 自动写入；手动运行时：

```bash
python <skill-dir>/scripts/pipeline.py decide add --resource-code <RC> --point inputs \
  --question "是否下载 Work 声明但本地缺失的实体数据与检测权重" --choice "下载缺失的实体数据" \
  --reason "用户需要物体与导航" --option "使用本地数据" --option "下载缺失的实体数据" --option work-only \
  --decided-by user --evidence 'file:$RESOURCES_ROOT/<RC>/work.json'
```

物化（按缺的实体裁剪，本地已有的不要再下）：

| 缺的实体 | 命令 |
| --- | --- |
| 全部 | `prepare_work_assets.py --work-json … --floorplan … --out <资源父目录>` |
| 只缺全景图 | 追加 `--no-model --no-point-cloud` |
| 只缺模型/点云 | 追加 `--no-panoramas` |
| 只缺模型 | 追加 `--no-panoramas --no-point-cloud` |
| 不下载 | 跳过物化，显式改跑 `run --inputs work-only`（不自动改档） |
| 小样 | 追加 `--max-panos N --max-tiles M` |

项目内的资源父目录用 `<app>/resources/`。物化输出写到 `<资源父目录>/<RC>/`，保留原件，并写 `manifest.json` 记录 origin（`work-declared`）、来源 URL、字节与 sha256。下载需要已授权访问；失败或只成功一部分时，报告「已得/缺什么/影响哪些能力」，不静默降级。

不问的事项（直接按默认处理，不向用户提问，也不自拟 A/B 菜单）：

- 补充数据（位姿、点云、本地 OBJ）是否属于该 Work：由引擎对齐阶段 A1–A4 自动核对，结果写进报告。
- 是否有高精度模型、深度图、3DGS：没有就在报告里写明哪些能力（A6、D1、G1）不可用，不阻断。
- 虚拟环境与权重放哪里：都用用户级缓存目录 `<缓存根>/realsee-spatial-analysis/{venv,hf}`（`<缓存根>`：macOS/Linux 为 `$XDG_CACHE_HOME` 或 `~/.cache`，Windows 为 `%LOCALAPPDATA%`）；权重可用 `--hf-home` / `SPATIAL_ANALYSIS_HF_HOME` 覆盖，任何工具已下载的标准 HF 缓存都会被自动复用。
- 用户明确选择精简分析后，以已有平面图和点位出房间，或仅用点位出结构结果。

不问的情形与例外：

- 没有要下载的东西（见上）：不问。
- 非交互环境（CI/批处理）：只出计划，不下载；需要时由调用方加 `--yes`。
- 一次运行只问一次；中途发现别的缺口写进报告，下一次运行前再确认。
- 同一次任务中，用户已明确选档后的重试可沿用该选择。历史 `analysis-decisions.json` 仅供追溯；新任务遇到 `choose` 时仍需用户选择。

### C. 运行分析

**先说明代价再开跑**（普通用户的机器不一定有 GPU 或已装依赖）：完整档首次需要安装 Python 依赖（约 1–3 GB，视平台）并一次性下载检测权重 `owlv2-base-ensemble`（约 620 MB，只下载这一个）；检测耗时随设备差异很大（Apple 芯片 MPS 约 1.4 s/视图；Linux/Windows/Intel Mac 只有 CPU，会慢数倍，管线按预算自动降档并写入报告；这些平台的依赖安装方式见 `references/pipeline-setup.md`「按平台准备完整档」，且未经完整验证），用 `inventory`/`check_env.py` 给出的点位数粗估。检测阶段每 30 秒打印进度与预计剩余时间；中断（关窗、超时）后用同一命令重跑会从检测缓存续跑，不要删除 `analysis-output/<RC>/cache` 或换目录从头开始。依赖安装和权重下载互不依赖，可并行。

**先拿权重，再跑 run**：`run` 的默认检测器是 `owlv2-base-ensemble`，`fetch-model` 默认值与之一致，直接运行即可（不要为“试试”下载别的模型）：

```bash
python <skill-dir>/scripts/pipeline.py fetch-model --hf-home <权重缓存目录>
```

- **下载前先检测**：`pipeline.py fetch-model --check`（不联网）按 `--hf-home` → `SPATIAL_ANALYSIS_HF_HOME` → `HF_HUB_CACHE` → `HF_HOME` → `XDG_CACHE_HOME` → 平台默认 `~/.cache/huggingface`（Windows 为 `%USERPROFILE%\.cache\huggingface`）的顺序查找锁定 revision 的 `model.safetensors`（大小必须匹配），输出 `{cached, cacheDir, searched[]}`，已缓存退出码 0、否则 1。命中时 `fetch-model` 与 `run` 直接复用，不再下载；`pipeline.py all` 的预检也会先做这一步，命中则跳过 `fetch-model`。
- `<权重缓存目录>` 默认用户级共享目录 `<缓存根>/realsee-spatial-analysis/hf`（macOS/Linux 为 `$XDG_CACHE_HOME` 或 `~/.cache`，Windows 为 `%LOCALAPPDATA%`；`pipeline.py all` 自动带上，也可用 `SPATIAL_ANALYSIS_HF_HOME` 覆盖），后续项目/资源码复用同一份，不要每次放进 `<out>`；它不能位于只读的 `resources/` 之内。
- 官方站点不可达时引擎会自动改用镜像下载并校验 sha256；用户网络受限时先报告预计体积，不要反复重试。
- 权重缺失时 `run` 在对齐、点云等重阶段之前就以 **exit 4** 和 `DETECTOR_WEIGHTS_MISSING`（含 `hint`）失败；按 `hint` 先 `fetch-model` 再重跑。只有用户不需要物体识别时才用 `--tier skip`，并在报告写明未执行。
- 同一资源码同一时间只能有一个 `run`：另一个 run 持有 `cache/<RC>/.run.lock` 时立即以 **exit 9** 退出。不要并行跑同一资源（包括“换参数再跑一份”）；要对比参数时等前一个结束，或用点云变体。
- 检测推理全部失败或失败超过 20% 时，`run` 以 **exit 8** 停止且不写检测缓存；直接重跑只会重试失败的视图。内存不足时改用 `--device cpu` 或更低档位，不要把空结果当作“没有物体”。
- 不要把 `run` 的输出接 `| tail`/`| head` 吞掉退出码；需要截断日志时用 `set -o pipefail` 或先写入文件再读取，并检查退出码。

```bash
python <skill-dir>/scripts/pipeline.py run \
  --resource-code <RC> \
  --work-json <资源父目录>/<RC>/work.json \
  --resources-root <资源父目录> \
  --workspace <out>
```

B 段选择 D（不物化）时改用 `pipeline.py run --inputs work-only --resource-code <RC> --work-json <data>/work.json --workspace <out>`，不带 `--resources-root`。没有 Work 时按本地数据 ID 运行，并把 `--work-json` 换成对应输入；不把另一项目的 Work 当主采集 Work。

分析结果必须包含 `spatial-analysis.v2.json` 和 `reports/<RC>/report.zh-CN.md`。报告至少覆盖：输入清单、点位/坐标核对、房间与面积、物品识别来源与置信度、连通性、测量、质量检查、未执行项和限制。

### D. 物品识别来源

- 默认使用随包管线的检测器；记录模型版本、tier、覆盖点位和置信度。
- 用户提供自定义 AI 或开放平台结果时，先校验资源码、点位/坐标、类别和置信度，再归一化为对象记录；不得把 2D 框说成 3D 分割，不得补造缺失字段。
- 没有可用识别输入时，`objects` 为空并明确写“未执行/输入缺失”，不能把空结果说成“现场没有物品”。

### E. 图谱与预览

```bash
python <skill-dir>/scripts/pipeline.py graph \
  --resource-code <RC> --work-json <data>/work.json \
  --resources-root <data> --workspace <out> \
  --analysis <out>/data/<RC>/spatial-analysis.v2.json \
  --out <out>/graph

python <skill-dir>/scripts/render_result.py \
  --analysis <out>/data/<RC>/spatial-analysis.v2.json \
  --floorplan <data>/floorplan.json \
  --graph <out>/graph/data-graph.json \
  --graph-html <out>/graph/data-graph.html \
  --out <out>/result-preview.html
```

预览是只读验收页，不是交互 Viewer；没有 `floorplan.json`、`data-graph` 时对应区块可省略，但要说明。

### F. 回装应用

先看写入计划（不加 `--write` 只打印，不写文件）：

```bash
python <skill-dir>/scripts/apply_analysis.py \
  --analysis <out>/data/<RC>/spatial-analysis.v2.json \
  --work <data>/work.json
```

在 `<app>` 目录中运行可省略 `--app`；跨项目时加 `--app <app>`。

回装是默认目标 4，不需要额外的开发授权：直接加 `--write` 写入（写入前会自动校验资源码、文件数、点位绑定和覆盖情况，校验不过就不写）；已安装且未被外部修改的结果会自动刷新，不让用户处理覆盖参数；如果安装记录不匹配或文件被用户改动，保留新分析并说明未回装原因。安装后刷新 `<app>`，检查：

- `GET /api/analysis/<RC>` 返回 200 且 `objects` 与报告一致；
- 「空间智能」入口可打开，概览/物品/测量/连通性页签有数据；
- 平面图、点位和对象位置与报告一致；
- 控制台无未处理异常。

宿主没有消费层时，先按 [已有项目接入](my-app.md) 安装 `@realsee/spatial-intelligence` 插件并完成文档中的最小接线，再重新运行 `apply_analysis.py --write`；插件安装和最小接线属于回装步骤。`apply_analysis.py` 本身只写结果包，不安装依赖、不启动服务、不发布，也不重建或覆盖应用源码；用户明确拒绝改代码时，改为只交付结果并写清未回装原因。

## 失败与降级

- 先区分“数据缺失”和“环境/权重缺失”；不得把依赖缺失说成数据不支持。
- `mode: "choose"`（退出 0）：声明素材尚未物化且精简档可用时，等待用户选择，当前命令不会交付或回装。没有可用精简档时，`WORK_ASSETS_NOT_MATERIALIZED`（退出 7）提示先物化缺项。
- `WORK_ONLY_NOT_READY`（退出 6）：当前 Work 缺可用点位。精简档有图纸可出房间，只有可用点位时仍可交付点位分析。
- 对齐、schema、绑定失败：停止该路径并保留日志，不手改结果通过校验。
- 对齐检查超阈值若源自**已确认的输入口径差异**（例如点云头位姿与 Work 位姿系统性差 6 cm、声明楼层与重建楼层基准不同），用 `--waive CHECK=VALUE`（可加前缀如 `A3`）放宽该条检查的通过/致命档，并用 `--waive-reason` 写明“为什么接受这个差异”（引擎导出后自动写入 `analysis-decisions.json`，不必再手动 `decide add`；用户明确同意时加 `--waive-by user`）。豁免写进 `run-manifest.json` 的 `thresholdOverrides`；不要关闭检查、不要为了过检查改引擎源码，也不要在项目里打补丁——发行包升级会丢补丁。
- 面积检查的口径：`A9.<房间>.area` 比较平面图声明的墙内净面积与轮廓按半墙厚内缩后的面积（矩形房间两者必然相同）；外皮轮廓本身的面积只作为 `A9.<房间>.area-outline`（与声明面积之比，含墙）记录，不参与判定。
- 任何未执行的步骤写“未执行”，不填估算值或占位数值。

## 验收

- `spatial-analysis.v2.json` 通过 `pipeline.py validate`，检查项和 `quality` 完整；
- 报告与 JSON 的数量、单位、坐标、误差一致；
- 预览可离线打开，图谱/平面/物品/测量/质量页签可用；
- 应用入口与 API 实际可用，不是只复制了 JSON；
- 最终回复只列实际产物、验证结果、缺失项和下一步，不重复整份报告。

### 重跑与补数据

补齐平面图后，同一工作区的点位档可以直接升级为房间档。部分全景缺失时按点位补齐，不重写有效位姿或已验证图片；盘点和数据指引随实际输入刷新。保存的方位在参考点位未变时自动复用，不能要求用户为了重跑重复确认；参考点位变化后不沿用旧校准。报告目录中的 Markdown/HTML 图片引用也必须随交付审计，缺图时不回装 Viewer。

平面图与 Work 点位不一致时，`work-only` 同样返回 `choose`。待用户选择核对图纸或仅分析点位，才继续执行。
