87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# 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
|