# 补全 Trellis 项目规范文档

**类型**：docs · **负责人**：dingkang · **创建**：2026-08-03

---

## 背景

`trellis init` 在本仓库生成了 `.trellis/` 脚手架（v0.6.12），但把项目误判成了前端项目：

- `.trellis/spec/frontend/` 下 6 个文件全是 React/TypeScript 的空模板，状态栏统一写着 "To fill"
- 本仓库实际是 **OSM → QGIS/Blender/Cesium 的资产生成管线**，没有任何前端代码
- `task.json` 的 `notes` 直接写着 "First-time setup task created by trellis init (frontend project)"

后果是具体的：`trellis-implement` / `trellis-check` 子代理会按 `implement.jsonl` / `check.jsonl` 自动加载 spec 文件。当前 spec 为空且方向错误，等于子代理在无约束下写代码——而这个项目有大量**违反直觉、必须遵守**的约定（详见下方"关键约定"），一旦被子代理无意破坏，产物会静默出错而不是报错。

## 目标

用真实代码中提取的约定，替换错配的 spec 脚手架，使任何 AI 会话在动手前就能拿到本项目的实际工程约束。

## 非目标

- **不改动任何业务代码**。本任务只写 `.trellis/` 下的文档
- **不修复代码中的已知缺陷**。`docs/refactor-plan.md` 记录的 D1/D2/D3 只做记录，不在此任务修
- **不重写 README/changelog**。它们面向人类使用者，spec 面向 AI 执行者，两者共存不合并
- **不引入新的检查脚本或 CI**

## 交付物

| # | 交付物 | 说明 |
|---|---|---|
| D1 | 删除 `.trellis/spec/frontend/` | 6 个空的 React 模板文件，全部移除 |
| D2 | `.trellis/spec/pipeline/` | Node 构建管线约定，4 个文件 |
| D3 | `.trellis/spec/blender/` | Blender Python 约定，4 个文件 |
| D4 | `.trellis/spec/preview/` | Cesium 预览层约定，1 个文件 |
| D5 | `.trellis/spec/config/` | 区域配置 JSON 约定，1 个文件 |
| D6 | `.trellis/spec/guides/` 本地化 | 更新 index，新增产物一致性指南 |
| D7 | `.trellis/spec/index.md` | 顶层索引 |
| D8 | `task.json` 元数据修正 | `relatedFiles` / `notes` 去掉 frontend 误判 |

结构详见 `design.md`。

## 关键约定（必须被 spec 覆盖）

这些是从代码注释和 `docs/refactor-plan.md` 中确认的、**违反直觉且破坏后果静默**的约束。spec 的价值主要在这里：

1. **图层表跨语言单一事实源** — 九个 osm2streets 图层的顺序在 `scripts/lib/scene-layers.js`（JS 侧）和 `blender/osmassets/catalog.py`（Python 侧）各存一份，靠 `catalog.check_layers()` 运行时校验。颜色**故意不同步**（QGIS sRGB 调试色 vs Blender 线性场景色）。
2. **顺序是承重的** — `ROAD_LAYERS` / `MATERIALS` 是 list 不是 dict，因为材质创建顺序决定导出 GLB 里的材质索引。只能追加。
3. **`ogr2ogr` 不能设 `COORDINATE_PRECISION`** — 显式设置会触发 GDAL 的精度裁剪，实测丢失 7 个箭头多边形的 28 个顶点。
4. **`ogr2ogr` 导出失败会留下 0 字节文件** — 所以 `reimport` 必须先导到临时目录、全部校验通过才拷回，不能直接写目标目录。
5. **`intermediates` 与 `reimport` 互斥** — 前者从 OSM 重建 gpkg，正好抹掉后者要读回的手工修改。代码里是显式抛错，不是警告。
6. **`osmassets` 按依赖分包，不按功能** — `osm.py` / `geom.py` 是纯 Python（可用系统 python 测试），其余可以 import `bpy`。这条线一旦被破坏，`blender/tests/test_pure.py` 就跑不起来。
7. **测试的期望值必须从几何推导** — `test_pure.py` 开头明确写着"记录当前输出的测试会把 bug 固化成规范"。
8. **重构必须过 parity 校验** — `scripts/parity.js` + `glb-digest.js` + `scene_digest.py` 三件套，比对的是结构摘要而非字节。哪些字段天然不稳定已经用 control 实验确定并列入忽略名单。

## 验收标准

- [ ] `.trellis/spec/frontend/` 已删除，`python3 ./.trellis/scripts/get_context.py --mode packages` 输出的 Spec layers 为 `blender, config, pipeline, preview`
- [ ] 每个 spec 文件都包含**至少 2 处指向真实文件的引用**（`path:line` 或 `path` + 函数名），没有假想路径
- [ ] 上方"关键约定" 8 条全部落到具体 spec 文件中，可通过 grep 定位
- [ ] 没有任何文件残留 "To fill" / "TODO" / 模板占位文本
- [ ] 文档语言为中文；标识符、路径、代码示例保持英文原样
- [ ] 每个包目录有 `index.md`，且顶层 `.trellis/spec/index.md` 能索引到全部包
- [ ] `blender/tests/test_pure.py` 仍能通过（确认本任务未误改代码）

## 完成后

```bash
python3 ./.trellis/scripts/task.py finish
python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
```

归档后，新加入的开发者会拿到 `00-join-<slug>` 引导任务而不是这个 bootstrap 任务。