Initialize Trellis project guidelines

.trellis/spec/guides/index.md

@@ -0,0 +1,76 @@
+# 思考指南索引
+
+> 目的：在改代码前补一遍"跨层会不会断、重复事实会不会漂、产物是否仍一致"。
+> 本目录不替代包级 spec；它用于那些单看一个文件容易误判的改动。
+
+---
+
+## 可用指南
+
+| 指南 | 关注点 | 什么时候读 |
+|---|---|---|
+| [跨层思考指南](./cross-layer-thinking-guide.md) | JS、GDAL/QGIS、Blender Python、浏览器之间的数据契约 | 改图层、材质名、配置字段、stage 输出、外部工具调用 |
+| [代码复用思考指南](./code-reuse-thinking-guide.md) | 单一事实源、重复解析、可接受重复与应抽取重复的边界 | 改 `parseArgs`、图层表、配置归一化、几何工具 |
+| [产物一致性指南](./artifact-parity-guide.md) | `.blend` / `.glb` / metadata 的结构摘要校验 | 任何声称"纯重构、产物不变"的改动 |
+
+---
+
+## 本项目触发点
+
+### 读跨层思考指南
+
+- [ ] 改 `scripts/lib/scene-layers.js:15` 的 `SCENE_LAYERS`
+- [ ] 改 `blender/osmassets/catalog.py:28` 的 `ROAD_LAYERS` 或 `catalog.py:56` 的 `MATERIALS`
+- [ ] 改 `blender/export_cesium.py:68` 等四张按材质名字符串匹配的覆盖表
+- [ ] 改 `build-area.js:74` 的 `normalizeAreaConfig()` 或 `config/examples/template.json`
+- [ ] 改任何 `execFileSync` / `spawnSync` 调起的脚本或参数
+- [ ] 改 `SCENE_DONE` / `CESIUM_EXPORT_DONE` 的 stdout 标记
+
+### 读代码复用思考指南
+
+- [ ] 准备新增第二份或第三份图层、材质、配置字段枚举
+- [ ] 修改三份重复的 `parseArgs` 之一：
+  `build-area.js:50`、`build-osm2streets-qgis.js:153`、`reimport-gpkg.js:93`
+- [ ] 多个要素模块都要做同一件几何预处理，比如
+  `water.py:9`、`grass.py:9`、`scrub.py:8` 都先 `clip_polygon`
+- [ ] 低层脚本想直接读取 `config/areas/*.json`，绕开派生配置
+- [ ] 新增 helper 前没有先 `grep -rn` 找现有函数
+
+### 读产物一致性指南
+
+- [ ] 挪函数、拆模块、改导入，且声称产物不变
+- [ ] 重排 `ROAD_LAYERS` / `MATERIALS`
+- [ ] 改材质名或导出调色逻辑
+- [ ] 改几何、采样、实例化、UV、材质构建
+- [ ] 改 `scripts/parity.js`、`scripts/glb-digest.js`、`blender/tools/scene_digest.py`
+
+---
+
+## 改值前的固定动作
+
+```bash
+grep -rn "要改的值" scripts blender config
+```
+
+本仓库跨 JS、Blender Python、浏览器 JS 和 JSON，很多连接靠字符串或文件名约定。
+例如 `scene-layers.js` 与 `catalog.py` 只靠 `id` 集合和顺序对账；
+`generate_scene.py` 与 `export_cesium.py` 的材质覆盖目前靠材质名字符串，没有自动校验。
+
+---
+
+## 审查 AI 结果时
+
+- 先看它有没有读到对应包的 index 和本目录指南
+- 对任何"行为没变"的结论，要求说明是否需要 parity；需要却没跑就是风险
+- 对任何"可以合并重复"的建议，先判断重复是不是刻意边界：
+  三份 `parseArgs` 目前是可接受技术债，JS/Python 图层颜色则是刻意不同步
+- 对任何"加精度、加默认值、直接覆盖文件"的建议，回到真实代码注释验证；
+  `reimport-gpkg.js:152-156` 和 `reimport-gpkg.js:11-13` 都是反直觉约束
+
+---
+
+## 维护规则
+
+- 发现新的跨层坑，优先补到相关指南，再补包级 spec
+- 指南只写本项目已发生或代码已体现的约束，不写通用工程格言
+- 每条新约束至少带两个真实路径或函数名，方便后续 grep 定位