feat: add Cesium semantic inspection mode

.trellis/spec/pipeline/cli-and-stages.md

@@ -70,7 +70,8 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
   - `<fileStem>-compressed-webp768.glb`
   - `<fileStem>-compressed-webp768.json`
   - `<fileStem>-compressed-webp768-cesium-preview.html`
-- 伴生 metadata 的 `asset` 和 `assets[0].url` 改为压缩 GLB 文件名。
+- 伴生 metadata 的 `asset` 与 `id="main"` 资产 URL 改为压缩 GLB 文件名；其余资产（包括
+  `category="semantic"` 的 Cesium 分类检查 GLB）必须原样保留。
 - preview HTML 只替换 `window.OSM_ASSET_PREVIEW_CONFIG` 的 `glbName` /
   `metadataName` 和 loading 文案，不改 preview runtime。
 - 成功时 stdout 打印 `GLB_COMPRESS_DONE <json>`，包含压缩前后大小、image /
@@ -100,6 +101,7 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
 ### 6. Tests Required
 
 - `node --check scripts/compress-glb.js`
+- `npm run test:compress-glb`：断言压缩 metadata 只替换主资产，不丢失语义资产。
 - `node --check scripts/build-area.js`
 - 对目标区域跑一次 `npm run compress:glb -- ... --metadata --preview`
 - 对目标区域跑一次 `npm run build:area -- --stages compress`

.trellis/spec/preview/index.md

@@ -201,6 +201,73 @@ GLB 停留在**局部 ENU 坐标系**（X 东、Y 北、Z 上），靠伴生 JSO
 
 `scenePlacement(metadata)`（`:131`）负责这一步。**改动导出侧的坐标约定必须同步改这里。**
 
+## 语义检查资产
+
+### 1. 范围与触发条件
+
+`cesium` 阶段除完整主 GLB 外，会按 Blender 顶层集合导出可选检查资产：道路、建筑、
+绿化与设施、水体。它们只服务于预览检查；主 GLB 仍是下游兼容基线，不能被替换。
+
+### 2. 调用形式
+
+不新增 CLI 参数。正常运行 Cesium 阶段即可：
+
+```bash
+npm run build:area -- --config config/areas/<area>.json --stages cesium
+```
+
+### 3. 契约
+
+- `blender/export_cesium.py:SEMANTIC_ASSETS` 是集合名、稳定资产 ID 与展示名的唯一映射：
+  `03_Roads → roads`、`04_Buildings → buildings`、`02_Green + 05_Props → vegetation`、
+  `01_Water → water`。
+- 每个有几何的类别额外写 `<stem>-<id>.glb`，且必须保留与主 GLB 相同的局部 ENU 坐标和
+  已处理的 Cesium 材质。
+- metadata 的主资产保持 `id="main"`、`enabled=true`；辅助项设
+  `category="semantic"`、`enabled=false`，并提供 `id`、`label`、`type="model"`、`url`。
+- `build-area.js:semanticAssetRecords()` 必须验证 metadata 声明的每个语义文件存在后才写
+  Cesium manifest。
+- 浏览器先加载非语义资产；只有点 `Inspect` 才加载辅助 GLB。检查模式必须隐藏主场景，
+  返回 `Scene` 必须隐藏辅助模型，禁止两套几何重叠渲染。
+- 没有 `category="semantic"` 的旧 metadata 仍按单资产预览打开，`Inspect` 按钮禁用。
+
+### 4. 校验与错误矩阵
+
+| 条件 | 结果 |
+|---|---|
+| 类别集合没有可导出 mesh | metadata 不声明该类别，预览不显示该开关 |
+| metadata 声明语义资产但文件不存在 | Cesium 阶段失败，不能写成功 manifest |
+| 辅助 GLB 浏览器加载失败 | 该开关禁用并写入诊断；主场景继续可用 |
+| 旧 metadata 没有语义项 | 完整场景照常显示，`Inspect` 不可点击 |
+
+### 5. 正常、基础与错误示例
+
+- 正常：进入 `Inspect` 后道路、建筑、绿化与设施、水体全部显示，再单独取消任一类别。
+- 基础：旧的只有 `main` 资产的 metadata 不展示分类控件，所有原有控制仍可用。
+- 错误：主 GLB 和语义 GLB 同时可见，导致道路、建筑等重复渲染和闪烁。
+
+### 6. 必需测试
+
+- `node scripts/test-preview-assets.js`：断言生成页包含模式切换与语义开关挂载点。
+- `node --check scripts/build-area.js`、`node --check scripts/lib/area-preview.js`、
+  `node --check scripts/lib/cesium-preview.js`。
+- 目标区域运行 `--stages cesium`，确认 metadata 的语义 `assets` 与同名辅助 GLB 一一对应。
+- 浏览器在桌面及窄屏分别切换 `Scene` / `Inspect`，确认不重叠且控制不溢出。
+
+### 7. 错误与正确写法
+
+错误：把辅助模型标为默认启用，页面加载时把它们与主 GLB 一起绘制。
+
+```json
+{ "id": "roads", "enabled": true, "category": "semantic" }
+```
+
+正确：默认关闭并在检查模式按需加载。
+
+```json
+{ "id": "roads", "enabled": false, "category": "semantic" }
+```
+
 ---
 
 ## 本地预览必须走 HTTP