feat(pipeline): make compressed assets the default delivery

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

@@ -21,13 +21,13 @@
 全部是 CommonJS（`package.json` 的 `"type": "commonjs"`），无构建步骤、无 TypeScript、
 零运行时依赖（唯一依赖 `osm2streets-js-node` 只被 `build-osm2streets-qgis.js` 用）。
 
-## 可选 GLB 压缩阶段
+## 默认 GLB 压缩阶段
 
 ### 1. Scope / Trigger
 
-`compress` 是显式请求的替代产物阶段，不属于 `all`，也不覆盖默认 `<area-id>.glb`。
-它用于在已有 Cesium GLB 上生成并列压缩 GLB、metadata 和预览页。当前主路径是
-texture resize + WebP transcode。
+`compress` 是完整构建和 `all` 的默认末端阶段。它在已有 Cesium GLB 上执行 texture
+resize + WebP transcode，并以标准 `<area-id>.glb`、`.json` 和预览 HTML 替换未压缩导出。
+未压缩版本只在 `<areaDir>/_pipeline/compress-*` 临时目录中存在，成功或失败后都会清理。
 
 `scripts/compress-glb.js` 是该阶段调用的低层脚本，也可单独运行做实验。
 
@@ -62,15 +62,14 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
 ### 3. Contracts
 
 - 输入必须是现有 `.glb` 文件；`--output` 必须不同于 `--input`。
-- 输出是并列压缩 GLB；默认构建产物不被替换。
-- `compress` 阶段依赖默认 `glb`、`metadata` 和 `cesiumPreview` 已存在。
+- 低层脚本仍输出到与输入不同的路径；`build-area.js` 使用临时输入/输出路径，避免原地压缩。
+- `compress` 阶段依赖标准 `glb`、`metadata` 和 `cesiumPreview` 已存在，并在全部临时交付文件
+  生成和校验后以 `renameSync` 替换它们。
 - 默认链固定为 `gltf-transform resize -> gltf-transform webp`。
 - `compress` 阶段默认 `textureSize=768`；低层脚本单独运行时默认 `--texture-size 1024`。
-- `build-area.js` 默认写：
-  - `<fileStem>-compressed-webp768.glb`
-  - `<fileStem>-compressed-webp768.json`
-  - `<fileStem>-compressed-webp768-cesium-preview.html`
-- 伴生 metadata 的 `asset` 与 `id="main"` 资产 URL 改为压缩 GLB 文件名；其余资产（包括
+- `build-area.js` 最终只保留 `<fileStem>.glb`、`<fileStem>.json` 和
+  `<fileStem>-cesium-preview.html`；不会写并列 `-compressed-*` 交付物。
+- 伴生 metadata 的 `asset` 与 `id="main"` 资产 URL 保持为标准 GLB 文件名；其余资产（包括
   `category="semantic"` 的 Cesium 分类检查 GLB）必须原样保留。
 - preview HTML 只替换 `window.OSM_ASSET_PREVIEW_CONFIG` 的 `glbName` /
   `metadataName` 和 loading 文案，不改 preview runtime。
@@ -88,13 +87,12 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
 | `gltf-transform` 退出非零 | 抛错并带上 status / signal |
 | `--preview` 没有 `--metadata` | 抛错，因为 preview 必须指向存在的 metadata |
 | preview HTML 找不到配置块 | 抛错，不做猜测替换 |
-| `--stages compress` 但默认 preview 不存在 | `Cesium preview not found: <path>` |
+| `--stages compress` 但标准 preview 不存在 | `Cesium preview not found: <path>` |
 
 ### 5. Good/Base/Bad Cases
 
-- Good: `--stages cesium,compress` 先重导默认 GLB，再生成并列压缩产物。
-- Good: `--texture-size 768 --metadata --preview` 生成压缩 GLB、metadata、HTML，
-  源 GLB 保持不变。
+- Good: `all` 或默认构建先导出 Cesium，再压缩成标准交付物。
+- Good: `--stages compress` 对已有标准交付物重新压缩，临时源 GLB 不会留在输出目录。
 - Base: 只传 `--input --output` 生成压缩 GLB，不生成伴生文件。
 - Bad: 使用 `--meshopt` 后没有做 Cesium 兼容性验证就当默认产物发布。
 
@@ -104,9 +102,9 @@ npm run compress:glb -- --input in.glb --output out.glb [options]
 - `npm run test:compress-glb`：断言压缩 metadata 只替换主资产，不丢失语义资产。
 - `node --check scripts/build-area.js`
 - 对目标区域跑一次 `npm run compress:glb -- ... --metadata --preview`
-- 对目标区域跑一次 `npm run build:area -- --stages compress`
-- `node scripts/glb-digest.js <compressed.glb>` 确认可解析结构和扩展
-- 浏览器/Cesium 预览压缩 HTML，确认 `EXT_texture_webp` 在目标环境可加载
+- 对目标区域跑一次默认 `npm run build:area`
+- `node scripts/glb-digest.js <area>.glb` 确认可解析结构和扩展
+- 浏览器/Cesium 预览标准 HTML，确认 `EXT_texture_webp` 在目标环境可加载
 
 ### 7. Wrong vs Correct
 
@@ -116,10 +114,10 @@ Wrong:
 npm run compress:glb -- --input outputs/a/a.glb --output outputs/a/a.glb
 ```
 
-Correct:
+Correct for the low-level script:
 
 ```bash
-npm run compress:glb -- --input outputs/a/a.glb --output outputs/a/a-compressed-webp768.glb
+npm run compress:glb -- --input outputs/a/a.glb --output /tmp/a-compressed.glb
 ```
 
 ---
@@ -758,14 +756,11 @@ runtime 与 HTML，并写 preview manifest。预览内容实现不得回流到
 
 `compress` manifest:
 
-- `inputs.glb`
-- `inputs.metadata`
-- `inputs.cesiumPreview`
-- `outputs.compressedGlb`
-- `outputs.compressedMetadata`
-- `outputs.compressedCesiumPreview`
+- `outputs.glb`
+- `outputs.metadata`
+- `outputs.cesiumPreview`
 - `summary.sourceGlb`
-- `summary.compressedGlb`
+- `summary.glb`
 - `summary.options`
 - `summary.compressionRatio`
 - `summary.savedBytes`
@@ -931,7 +926,7 @@ gpkg: path.resolve(outputOverrides.gpkg || path.join(areaDir, `${fileStem}.gpkg`
 | `blender` | OSM + GeoJSON → 场景 | `.osm`、`osm2streets_web_out/` | `.blend`、`.png` |
 | `cesium` | 场景 → GLB + 元数据 + 预览页 | `.blend` | `.glb`、`.json`、预览 HTML 及其静态资源 |
 | `preview` | 只补生成预览页 | `.glb`、`.json` | 预览 HTML 及其静态资源 |
-| `compress` | 生成并列压缩 Cesium 产物 | `.glb`、`.json`、默认预览 HTML | `-compressed-webp*.glb/json/html` |
+| `compress` | 将 Cesium 临时导出替换为压缩交付产物 | 标准 `.glb`、`.json`、预览 HTML | 标准 `.glb/json/html` |
 
 调度是顶层的阶段 `if`（`build-area.js` 开头），顺序固定，**阶段之间不传内存状态，
 只通过磁盘产物耦合**。这就是单跑某个阶段能work 的原因。
@@ -952,11 +947,11 @@ gpkg: path.resolve(outputOverrides.gpkg || path.join(areaDir, `${fileStem}.gpkg`
 ```js
 // 'reimport' is deliberately absent from 'all': it is a recovery step for
 // hand-edited GeoPackages, never part of a full build.        build-area.js:159-160
-all: ["intermediates", "blender", "cesium"],
+all: ["intermediates", "blender", "cesium", "compress"],
 ```
 
-`preview` 同样不在 `all` 里——`cesium` 已经包含它。`compress` 也不在 `all` 里——
-它生成的是替代压缩产物，不是 baseline GLB。
+`preview` 不在 `all` 里——`cesium` 已经包含它。`compress` 在 `all` 里，确保完整构建
+以压缩后的标准路径交付。
 
 ### `intermediates` 与 `reimport` 互斥
 
@@ -966,9 +961,9 @@ all: ["intermediates", "blender", "cesium"],
 
 这是**显式拒绝而不是警告**——两者同时开，无论谁先跑，另一个的工作都白做。
 
-`normalizeAreaConfig` 里 `stages.reimport`、`stages.preview` 和 `stages.compress` 硬编码为 `false`，
-**不能从配置文件打开**，只能靠 `--stages` 显式请求。
-恢复动作、补丁动作和替代产物动作都不该被一份配置文件变成默认行为。
+`normalizeAreaConfig` 里 `stages.reimport` 和 `stages.preview` 硬编码为 `false`，
+只能靠 `--stages` 显式请求；`stages.compress` 为默认 `true`。
+恢复动作和补丁动作不该被一份配置文件变成默认行为，压缩则属于标准交付链。
 
 ---
 

.trellis/spec/pipeline/index.md

@@ -60,7 +60,7 @@ config/areas/<id>.json
       │                     + 车辆巡航路线与模型
       │                     → _pipeline/stages/preview.manifest.json
       │
-      └─[compress]──────▶ 生成并列压缩 GLB / metadata / preview
+      └─[compress]──────▶ 临时保存未压缩导出，再以标准 GLB / metadata / preview 路径交付压缩版本
                             → _pipeline/stages/compress.manifest.json
 ```