Initialize Trellis project guidelines

.trellis/spec/index.md

@@ -0,0 +1,85 @@
+# Trellis 项目规范索引
+
+> 本目录面向 AI 执行者，记录本仓库真实代码里的工程约束。
+> 用法说明仍放在 README；这里写的是**改代码前必须知道什么**。
+
+---
+
+## 项目边界
+
+本仓库不是前端应用，而是 **OSM → QGIS/Blender/Cesium 的资产生成管线**：
+
+- `scripts/build-area.js:74` 的 `normalizeAreaConfig()` 归一化区域配置并调度阶段
+- `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](./pipeline/index.md) |
+| `blender/**/*.py`、`osmassets` 模块、材质、几何、导出 | [blender](./blender/index.md) |
+| `scripts/lib/cesium-preview.js` / `.css`、预览 HTML 注入 | [preview](./preview/index.md) |
+| `config/areas/*.json`、`config/examples/template.json`、区域字段默认值 | [config](./config/index.md) |
+| 跨语言、跨进程、声称纯重构或产物不变的改动 | [guides](./guides/index.md) |
+
+跨层改动至少读两个包的 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`
+
+---
+
+## 四条全仓硬约束
+
+1. **改值先 grep**
+   本项目跨 JS、Blender Python、浏览器 JS 和 JSON，IDE 引用不可靠。
+   改 `SCENE_LAYERS`、`ROAD_LAYERS`、材质名、stage 标记或配置字段前，先：
+
+   ```bash
+   grep -rn "要改的值" scripts blender config
+   ```
+
+2. **顺序可能是契约**
+   `catalog.py:16-18` 明确说 `ROAD_LAYERS` / `MATERIALS` 的顺序决定导出 GLB 的材质索引。
+   列表默认只能末尾追加；中间插入或重排必须跑 parity。
+
+3. **外部工具产物先 staging 后覆盖**
+   `reimport-gpkg.js:11-13` 记录了 `ogr2ogr` 失败会留下 0 字节文件。
+   任何从外部工具生成文件再覆盖已有产物的代码，都要先写临时目录、校验、再拷回。
+
+4. **纯重构必须证明产物一致**
+   `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>`
+
+---
+
+## 维护本目录
+
+- 每个包目录必须有 `index.md`
+- 每个规范文件至少引用两个真实项目文件或函数，优先写 `path:line` + 标识符
+- 文档语言保持中文；标识符、路径、命令和代码片段保持英文原样
+- 不写任何占位提示或未来补写标记；规范文件必须是可执行的当前约束
+- README 面向使用者，spec 面向修改者；不要把命令教程整段复制到 spec