Refactor Cesium material export contract

.trellis/spec/guides/cross-layer-thinking-guide.md

@@ -18,7 +18,7 @@ build-osm2streets-qgis.js    Node + osm2streets WASM
 ogr2ogr / ogrinfo / QGIS Python   GDAL/QGIS 运行时
       ↓ ④  GeoJSON / GeoPackage 文件
 generate_scene.py            Blender 内嵌 Python
-      ↓ ⑤  .blend 文件 + 材质名字符串
+      ↓ ⑤  .blend 文件 + 材质自定义属性
 export_cesium.py             Blender 内嵌 Python
       ↓ ⑥  GLB + JSON
 cesium-preview.js            浏览器
@@ -30,7 +30,7 @@ cesium-preview.js            浏览器
 | ② | 两层配置 | 低层脚本读错配置源 |
 | ③ | Node → 外部进程 | 环境变量缺失、退出码与信号、0 字节产物 |
 | ④ | 文件交换 | 图层集合/顺序漂移、精度丢失 |
-| ⑤ | Python → Python | **材质名字符串**，无校验 |
+| ⑤ | Python → Python | 新场景靠 `material["cesium_export"]`，旧场景靠材质名回退表 |
 | ⑥ | Blender → 浏览器 | 坐标系约定、材质在两种光照下的差异 |
 
 ---
@@ -65,7 +65,7 @@ cesium-preview.js            浏览器
 | 边界 | 靠什么连接 | 有没有校验 |
 |---|---|---|
 | `scene-layers.js` ↔ `catalog.py` | 图层 `id` 的集合与顺序 | ✅ `check_layers()`（warn） |
-| `generate_scene.py` ↔ `export_cesium.py` | **材质名字符串** | ❌ **无** |
+| `generate_scene.py` ↔ `export_cesium.py` | `.blend` 材质自定义属性 `cesium_export` | 部分（旧 `.blend` 仍靠材质名回退表） |
 | GeoJSON 文件名 ↔ 图层 id | `layerFile()` 拼 `<id>.geojson` | 部分（reimport 会检查 gpkg 图层是否齐全） |
 | stage stdout ↔ `parity.js` | `SCENE_DONE` / `CESIUM_EXPORT_DONE` 字面量 | ❌ 无 |
 | GLB 材质索引 ↔ `MATERIALS` 顺序 | 隐式的创建顺序 | ❌ 无（靠 parity 事后发现） |
@@ -118,13 +118,17 @@ cesium-preview.js            浏览器
 
 → [资产生成](../blender/asset-generation.md#为什么新资产总是发黑)
 
-### 坑 5：两个 Python 脚本靠字符串对接
+### 坑 5：新旧 `.blend` 的材质导出契约不同
 
-`export_cesium.py` 不 import `catalog`，靠材质名字符串匹配四张覆盖表。
-改个材质名，Cesium 侧的调色**静默失效**。`catalog.CESIUM_EXPORT` 想解决这个问题，
-但迁移没做完，它现在是死代码。
+新生成场景把 Cesium 导出契约写进材质自定义属性 `material["cesium_export"]`：
+`catalog.MATERIALS[*]["cesium"]` → `materials.from_spec()` → `.blend` →
+`export_cesium.py`。导出器仍不 import `catalog`，这是为了让契约跟着 `.blend`
+走，而不是用当前源码按材质名反查。
 
-**教训**：**字符串键的跨模块耦合必须配一个对账机制**，否则重命名就是定时炸弹。
+旧 `.blend` 没有这个属性，所以 `export_cesium.py` 仍保留四张材质名回退表。改材质名时，
+新场景和旧场景两条路都要想清楚。
+
+**教训**：**跨阶段契约必须随产物保存；兼容旧产物的字符串回退也要被审查**。
 
 ---
 
@@ -141,7 +145,8 @@ cesium-preview.js            浏览器
 ### 加一个材质
 
 - [ ] `catalog.MATERIALS` **末尾**追加（中间插入会平移 GLB 材质索引）
-- [ ] 若在 Cesium 里需要调色，去 `export_cesium.py` 的四张表加
+- [ ] 若在 Cesium 里需要调色，写 `catalog.MATERIALS[*]["cesium"]`，不要只改旧回退表
+- [ ] 若要兼容旧 `.blend` 的同名材质，再审查 `export_cesium.py` 四张回退表
 - [ ] 跑 parity
 
 ### 加一个配置字段