osmWorkflow/.trellis/tasks/08-25-rc-p3-render-separation/implement.md

Phase 3 执行计划

Step 1 — 枚举现有分流逻辑（定 schema 之前）

• 读 blender/generate_scene.py:796-834 全部道路分支
• 列出每个 source 的处理方式：直接渲染 / 按属性分流 / 跳过
• 已知分流： - center_lines：color != "white" → center_lines 材质； color == "white" → native_center_line_white - lane_separators：color != "yellow" → lane_separators； color == "yellow" → native_lane_separator_yellow
• 确认 lane_centerlines / connectors 确实未被消费（→ role: "semantic"）
• 产出 research/native-layer-consumption-matrix.md

门槛：manifest schema 能表达矩阵里的每一行，无"特例硬编码"残留。

Step 2 — 定 manifest schema 并落契约

• 按父任务 design.md §3.2 定稿 schema
• 写入编译器仓库契约文档，版本标为 native-road-package/v1.1
• 记录：v1.1 起 manifest.json 为必需输出

Step 3 — 编译器侧：生成 manifest

• 编译器内建立图层注册表（单一事实源），compileGeometry 的输出键与之对应
• 写 manifest.json 到 outDir
• 编译器自校验：manifest 声明的每个 source 都必须有对应 geojson 文件， 反之亦然（缺一即报错，不静默）
• parity：此步只新增 manifest.json，其余文件应逐字节不变

# 只应多出 manifest.json
node scripts/road-parity.js --config config/areas/fengshu-er-road.json \
  --compare .../baseline/fengshu-er-road.json

Step 4 — Blender 侧：抽模块 + 读 manifest

• 新建 blender/osmassets/native_roads.py
• 把 generate_scene.py:796-834 的道路分支迁入
• 改为读 manifest 遍历；role == "semantic" 跳过
• splitBy 通用化实现，替掉两处硬编码 lambda
• 加断言：manifest 里的 materialLayer 若不在 catalog.MATERIALS / ROAD_LAYERS 中，直接 raise，不静默跳过（风险表第二条）
• 删除 catalog.NATIVE_ROAD_LAYERS
• generate_scene.py 只保留一行调用

Step 5 — 验证

# .blend 结构摘要对基线
npm run build:area -- --config config/areas/fengshu-er-road.json
# 走 artifact-parity-guide 的结构摘要比对

# 三区域跑通
for a in fengshu-er-road hanyang-block nantaizi-lake-innovation-valley; do
  npm run build:area -- --config config/areas/$a.json || echo "FAIL $a"
done

# 建筑/植被/水体未被改动
git diff --stat -- blender/osmassets/ | grep -vE "native_roads|catalog"

• 渲染预览图人工对照（结构摘要粒度不足的兜底）

Step 6 — AC3.4 实测（可扩展性证明）

这一步是整个 Phase 3 的价值证明，不可跳过。

• 编译器加一个 throwaway 图层 debug_probe.geojson（几个矩形即可） + manifest 声明 role: "marking"，复用现有材质槽
• 不改宿主任何代码，跑 blender 阶段
• 确认 Blender 场景中出现该图层几何
• 截图/记录证据到任务 research/
• 回滚 throwaway 图层

Review Gate

AC3.1–AC3.7 全绿，特别是 AC3.4 有实测证据。

Rollback

• 恢复 catalog.NATIVE_ROAD_LAYERS，generate_scene.py 恢复内联分支
• manifest.json 可保留输出（无消费方时无害）
• 编译器侧图层注册表保留（它本身是改进）