思考指南索引

目的：在改代码前补一遍"跨层会不会断、重复事实会不会漂、产物是否仍一致"。本目录不替代包级 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
改 catalog.MATERIALS[*]["cesium"]、material["cesium_export"] 或 export_cesium.py 的旧材质名回退表
改 build-area.js:74 的 normalizeAreaConfig() 或 config/examples/template.json
改任何 execFileSync / spawnSync 调起的脚本或参数
改 SCENE_DONE / CESIUM_EXPORT_DONE 的 stdout 标记

读代码复用思考指南

准备新增第二份或第三份图层、材质、配置字段枚举
修改多份重复的 parseArgs 之一： build-area.js:54、build-osm2streets-qgis.js:153、reimport-gpkg.js:93、 compress-glb.js:16、diagnose-area.js:17
多个要素模块都要做同一件几何预处理，比如 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 的新材质导出契约靠 .blend 里的 material["cesium_export"] 自定义属性，旧 .blend 仍靠 export_cesium.py 的材质名回退表。

审查 AI 结果时

先看它有没有读到对应包的 index 和本目录指南
对任何"行为没变"的结论，要求说明是否需要 parity；需要却没跑就是风险
对任何"可以合并重复"的建议，先判断重复是不是刻意边界：多份 parseArgs 目前是可接受技术债，JS/Python 图层颜色则是刻意不同步
对任何"加精度、加默认值、直接覆盖文件"的建议，回到真实代码注释验证； reimport-gpkg.js:152-156 和 reimport-gpkg.js:11-13 都是反直觉约束

维护规则

发现新的跨层坑，优先补到相关指南，再补包级 spec
指南只写本项目已发生或代码已体现的约束，不写通用工程格言
每条新约束至少带两个真实路径或函数名，方便后续 grep 定位

3.5 KiB Raw Blame History Unescape Escape