Material export contract

类型：refactor · 范围：blender · 创建：2026-08-03

Goal

把 Cesium 导出调色/覆盖规则从 blender/export_cesium.py 里的材质名字符串表迁移到 blender/osmassets/catalog.py 的材质声明中，让 Blender 场景材质自己携带 Cesium 导出契约，降低改材质名时静默断开导出效果的风险。

用户价值：后续新增或重命名材质时，只需要维护 catalog.MATERIALS 附近的材质定义； Cesium 导出器消费 .blend 中保存的契约，而不是靠另一份易漂移的字符串表猜测。

当前实际状态由代码和 spec 共同确认：

blender/osmassets/catalog.py:56 的 MATERIALS 是材质声明源；materials.py:198 的 from_spec() 把 spec 构造成真实 Blender 材质。
blender/export_cesium.py:68,80,86,95 仍维护四张以 material.name 为 key 的导出覆盖表： EXPORT_TINTS、EXPORT_METALLIC_OVERRIDES、EXPORT_BASE_COLOR_OVERRIDES、 EXPORT_EMISSION_OVERRIDES。
blender/osmassets/catalog.py:142 已有 CESIUM_EXPORT，但 .trellis/spec/blender/module-structure.md 记录它是死代码，当前导出器不会读取。
"Office White Metal Facade" 仍出现在 export_cesium.py:74,82,91,100，但当前 catalog.MATERIALS 已无对应材质；这是 docs/refactor-plan.md / spec 记录的 D1。
.trellis/spec/guides/artifact-parity-guide.md 记录 P3 未做：材质契约化仍缺失。

catalog.MATERIALS 中需要 Cesium 特殊导出的材质必须就地携带 cesium 子契约。该契约覆盖现有四张表的有效行为，包括 tint、metallic、base_color、emission。
materials.from_spec() 必须在创建材质时把 spec["cesium"] 序列化写入材质自定义属性 material["cesium_export"]，使 .blend 能保存该契约。
export_cesium.py 必须优先读取 material["cesium_export"] 并据此导出；只有旧 .blend 或缺失属性的材质才回退到现有四张表。
旧 .blend 兼容性必须保留：没有 cesium_export 自定义属性时，导出行为不应比当前更少。
alpha cut-out foliage 的特殊路径保持现状：FOLIAGE_ALBEDO_GAIN、FOLIAGE_SATURATION、 FOLIAGE_EMISSION、alpha_dilated_image() 和 diffuse-as-emissive texture 逻辑不在本任务重构。
本任务是契约迁移，不是视觉调参；目标是新生成产物的结构摘要尽量与迁移前一致。
本任务不得把 bpy 引入 catalog.py，不得把 export_cesium.py 改成直接 import catalog 再按材质名反查。
任务完成后需要更新 .trellis/spec/blender/ 中关于当前材质名字符串对接、catalog.CESIUM_EXPORT 死代码、P3 未完成状态的说明。

不修 docs/refactor-plan.md 的 D2：scene-layers.js 与 catalog.py 颜色不同步已经被 spec 定性为刻意设计。
不清理 generate_scene.py 的 tuft_density_wave 注释 D3。
不做 P2 features 注册表重构。
不改变道路图层顺序、MATERIALS 创建顺序、stage stdout 标记或 Cesium preview 运行时。
不新增依赖、lint/type 工具链或 CI。

新生成的 .blend 材质中，已有 Cesium 覆盖规则的 catalog 材质带有 cesium_export 自定义属性。
export_cesium.py 对带 cesium_export 的材质优先使用该属性；对缺失属性的旧材质仍走旧四张表回退。
"Office White Metal Facade" 不再出现在新契约源中；若旧表保留它，只能作为旧 .blend 回退兼容存在，并在代码注释中说明。
catalog.CESIUM_EXPORT 不再是死代码：要么被移除并迁入 MATERIALS[*]["cesium"]，要么被真实读取；最终 spec 与代码描述一致。
python3 -m unittest discover blender/tests 通过。
对默认 parity 样本执行改动前/改动后 capture + compare；如果结构摘要差异存在，必须逐条解释为预期差异或修复到全绿。
.trellis/spec/blender/module-structure.md 与 .trellis/spec/blender/asset-generation.md 更新为新的材质导出契约，不再把“改 catalog.CESIUM_EXPORT 不会生效”描述为当前事实。

采用材质自定义属性 cesium_export 作为跨 .blend 的契约载体，而不是让导出器 import catalog。原因：旧 .blend 没有当前 Python catalog 上下文也应该能导出；契约必须跟着场景文件走。
回退旧四张表作为兼容层保留到本任务结束，不在同一任务里删除兼容路径。
不触碰 foliage alpha 特殊路径，避免把高风险贴图处理与 contract 迁移混在一起。

无阻塞开放问题。实现前仍需要用户确认本规划摘要并允许进入 in_progress。