# 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](./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