3.4 KiB
3.4 KiB
思考指南索引
目的：在改代码前补一遍"跨层会不会断、重复事实会不会漂、产物是否仍一致"。 本目录不替代包级 spec；它用于那些单看一个文件容易误判的改动。
可用指南
| 指南 | 关注点 | 什么时候读 |
|---|---|---|
| 跨层思考指南 | JS、GDAL/QGIS、Blender Python、浏览器之间的数据契约 | 改图层、材质名、配置字段、stage 输出、外部工具调用 |
| 代码复用思考指南 | 单一事实源、重复解析、可接受重复与应抽取重复的边界 | 改 parseArgs、图层表、配置归一化、几何工具 |
| 产物一致性指南 | .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
改值前的固定动作
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 定位