Trellis 项目规范索引

本目录面向 AI 执行者，记录本仓库真实代码里的工程约束。用法说明仍放在 README；这里写的是改代码前必须知道什么。

项目边界

本仓库不是前端应用，而是 OSM → QGIS/Blender/Cesium 的资产生成管线：

scripts/lib/area-config.js 的 normalizeAreaConfig() 归一化区域配置和输出路径
scripts/build-area.js 调度阶段并写入 GLB 相关 stage manifest
scripts/lib/scene-layers.js:15 的 SCENE_LAYERS 是 osm2streets 九个 2D 图层的 JS 侧事实源
blender/osmassets/catalog.py:28 的 ROAD_LAYERS 是 Blender 侧道路图层与材质顺序事实源
scripts/lib/cesium-preview.js:1 是无构建步骤的浏览器预览 IIFE

因此有效 spec layer 只有 pipeline、blender、preview、config，另有跨层思考指南 guides。

你要改的内容	先读
`scripts/*.js`、构建阶段、QGIS/GDAL/Blender 子进程、GeoPackage 往返	pipeline
`blender/*/.py`、`osmassets` 模块、材质、几何、导出	blender
`scripts/lib/cesium-preview.js` / `.css`、预览 HTML 注入	preview
`config/areas/*.json`、`config/examples/template.json`、区域字段默认值	config
跨语言、跨进程、声称纯重构或产物不变的改动	guides

跨层改动至少读两个包的 index，再读 guides/index.md。例如：

加一个 osm2streets 图层：读 pipeline/layer-registry.md + blender/asset-generation.md + guides/artifact-parity-guide.md
改材质名：读 blender/module-structure.md + blender/asset-generation.md + guides/cross-layer-thinking-guide.md
加区域配置字段：读 config/index.md + pipeline/cli-and-stages.md

改值先 grep 本项目跨 JS、Blender Python、浏览器 JS 和 JSON，IDE 引用不可靠。改 SCENE_LAYERS、ROAD_LAYERS、材质名、stage 标记或配置字段前，先：
```
grep -rn "要改的值" scripts blender config
```
顺序可能是契约 catalog.py:16-18 明确说 ROAD_LAYERS / MATERIALS 的顺序决定导出 GLB 的材质索引。列表默认只能末尾追加；中间插入或重排必须跑 parity。
外部工具产物先 staging 后覆盖 reimport-gpkg.js:11-13 记录了 ogr2ogr 失败会留下 0 字节文件。任何从外部工具生成文件再覆盖已有产物的代码，都要先写临时目录、校验、再拷回。
纯重构必须证明产物一致 scripts/parity.js、scripts/glb-digest.js、blender/tools/scene_digest.py 是结构摘要三件套；不要用二进制字节 diff 代替。

spec layer 扫描： python3 ./.trellis/scripts/get_context.py --mode packages
纯 Python 测试： python3 -m unittest discover blender/tests
纯重构产物一致性： node scripts/parity.js capture <label>，再 node scripts/parity.js compare <before> <after>