que01/osmWorkflow

Fork 0

Files

que01 4c5981c555 Initialize Trellis project guidelines

2026-08-03 10:56:21 +08:00

5.4 KiB

Raw Blame History

执行计划：Trellis spec 重建

对应 prd.md / design.md。按序执行，每步带验证命令。

前置校验

# 确认当前 spec layers 是错的（预期输出含 frontend）
python3 ./.trellis/scripts/get_context.py --mode packages

# 确认纯 Python 测试基线是绿的（本任务不该改代码，收尾要复验）
python3 -m unittest discover blender/tests -v 2>&1 | tail -5

记录测试基线的用例数，收尾时比对。

Step 1 — 删除错配脚手架

删除 .trellis/spec/frontend/（7 个文件：index + 6 个模板）

只删这一个目录，guides/ 必须保留。

rm -rf .trellis/spec/frontend
python3 ./.trellis/scripts/get_context.py --mode packages   # Spec layers 应为空

Step 2 — `pipeline/` 包（4 个文件）

按依赖顺序写，layer-registry.md 是核心，先写它。

2.1 pipeline/layer-registry.md — 取材 scene-layers.js 全文 + catalog.py:1-19,25-47,162-195
2.2 pipeline/external-tools.md — 取材 reimport-gpkg.js 全文 + build-area.js:237-311
2.3 pipeline/cli-and-stages.md — 取材 build-area.js:1-50,74-215
2.4 pipeline/index.md — 包索引 + 五个 stage 的数据流全景

写 2.3 前需补读：build-osm2streets-qgis.js（1468 行，尚未通读）确认 stage 内部细节与 normalize-lane-arrows.py 的调用方式。

验证：

grep -c "scripts/" .trellis/spec/pipeline/*.md    # 每个文件应 >= 2
grep -rn "To fill\|TODO\|待填" .trellis/spec/pipeline/ ; echo "exit=$?"   # 应为 1（无匹配）

Step 3 — `blender/` 包（4 个文件）

3.1 blender/module-structure.md — 取材 osmassets/__init__.py + 各模块 docstring
3.2 blender/testing.md — 取材 test_pure.py:1-11 + 各 test_degenerate_*
3.3 blender/asset-generation.md — 取材 mesh.py, materials.py, tree.py, catalog.py + changelog 2026-07-31
3.4 blender/index.md — 包索引 + 依赖分层图（纯 Python / bpy 两层）

写 3.3 前需补读：generate_scene.py（999 行）与 export_cesium.py（624 行）的结构，确认材质名跨文件对接的实际方式。

验证：

grep -c "blender/" .trellis/spec/blender/*.md
grep -rn "To fill\|TODO\|待填" .trellis/spec/blender/ ; echo "exit=$?"

Step 4 — `preview/` 与 `config/`（各 1 个文件）

4.1 preview/index.md — 取材 cesium-preview.js + build-area.js:697-767
4.2 config/index.md — 取材 config/examples/template.json + build-area.js:74-142 + README 配置节

写 4.1 前需补读：cesium-preview.js（672 行）主体，目前只读了前 30 行。

Step 5 — `guides/` 本地化 + 新增

5.1 新增 guides/artifact-parity-guide.md — 取材 docs/refactor-plan.md + parity.js + glb-digest.js + scene_digest.py
5.2 更新 guides/cross-layer-thinking-guide.md 的触发点清单（保留通用内容）
5.3 更新 guides/code-reuse-thinking-guide.md 的触发点清单
5.4 更新 guides/index.md 的指南表格，加入新指南

Step 6 — 顶层索引与任务元数据

6.1 新增 .trellis/spec/index.md — 四包路由表
6.2 修正 task.json：relatedFiles 改为四个新包目录，notes 去掉 "(frontend project)"

python3 ./.trellis/scripts/task.py set-meta ...   # 或直接编辑 task.json

Step 7 — 全量验收

对照 prd.md 验收标准逐条过：

# 1. spec layers 正确
python3 ./.trellis/scripts/get_context.py --mode packages
#    预期：Spec layers: blender, config, pipeline, preview

# 2. 无占位文本
grep -rn "To fill\|TODO\|待填\|FIXME\|<!-- fill" .trellis/spec/ ; echo "exit=$? (1=clean)"

# 3. frontend 已清除
test -d .trellis/spec/frontend && echo "FAIL: still exists" || echo "OK: removed"

# 4. 每个包有 index.md
for d in pipeline blender preview config; do
  test -f ".trellis/spec/$d/index.md" && echo "OK $d" || echo "FAIL $d"
done

# 5. 关键约定可 grep 定位（8 条）
grep -rl "COORDINATE_PRECISION" .trellis/spec/          # 约定 3
grep -rl "check_layers" .trellis/spec/                  # 约定 1
grep -rl "PROJ_LIB\|GDAL_DATA" .trellis/spec/           # 约定 4 相关
grep -rl "互斥" .trellis/spec/                           # 约定 5
grep -rl "bpy" .trellis/spec/blender/                   # 约定 6
grep -rl "parity" .trellis/spec/                        # 约定 8

# 6. 代码未被误改
git status --porcelain -- scripts/ blender/ config/     # 应为空
python3 -m unittest discover blender/tests 2>&1 | tail -3

回滚点

本任务只新增/删除 .trellis/spec/ 下的文件，且删除的 frontend/ 是未提交的未跟踪文件（.trellis/ 整体尚未入库）。

回滚代价：frontend/ 的 7 个空模板删掉后无法从 git 恢复。但它们是 trellis init 生成的、内容为纯占位符，可用 trellis init 重新生成，或直接接受丢失——PRD 已确认它们对本项目无价值。

保险起见：Step 1 执行前先把 .trellis/spec/frontend/ 打包到 /tmp/trellis-frontend-backup.tar.gz，任务归档后再删。

审查门

Step 2 完成后暂停，让用户看 pipeline/layer-registry.md——这篇最能反映 spec 的目标风格。风格若不对，后面 7 个文件不必按同样方式写完再返工。
Step 7 全部通过后再报告完成。

5.4 KiB Raw Blame History Unescape Escape