tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
particle/main
MapLibreParticleLab/docs/40_任务/STEP-102_RenderSegment无Placement段局部复用_Codex任务_v1.md

10 KiB
Raw Permalink Blame History

STEP-102 RenderSegment 无 Placement 段局部复用 Codex 任务 v1

1. Step 编号和目的

STEP-102：修复 full CPU 多 Retained Segment 下 placement aggregate gate 的不必要扩散，使结构上不具备 placement 能力的 Retained Segment 能在其他 placement-bearing Segment fallback/live 时继续独立 composite/reuse。

本 Step 的设计依据： docs/20_调查/RenderSegment多Retained段全局Placement门槛_粒子管理员审查说明_v3.md。

2. 当前已冻结基线

  • 仓库：/Users/tei/dev/MapLibreParticleLab-step102
  • branch：step102-placement-free-retained-locality
  • start HEAD：6df21dac38f072c5ad35b8dfc7ec5217509602bc
  • upstream base：MapLibre Native core 既有冻结基线，不升级
  • V19/V20 release worktree：冻结，只读，不修改
  • STEP-100 source-scoped locality：必须保持
  • STEP-101 teardown 修复：必须保持
  • Fast Path：本 Step 不修改
  • C-001：不升级

3. 本 Step 目标

必须实现：

  1. 增加结构性 placement-capable range 查询；
  2. full CPU 每个 Retained Segment 独立计算 placement gate；
  3. placement-free Retained 不再被其他 Segment 的 placementChanged/symbolFadeChange 纯 aggregate gate 拖入 fallback；
  4. placement-bearing Retained 继续使用现有保守 placement gate；
  5. 从 full CPU globalLiveFallback 移除纯 aggregate placement 条件；
  6. 保持真正全局 fail-closed 条件；
  7. diagnostics 增加结构 placement、per-segment gate、实际 composite/live 与全局 main-buffer execution 信息；
  8. RN diagnostics TS 类型做 additive 扩展；
  9. 增加对应 C++ 测试源码与 Android Validation 场景源码；
  10. 不改变 Style Z-order、mixed executor、C-001 和 RN method surface。

4. 非目标 / 禁止事项

禁止：

  • placement-bearing Segment 之间的局部碰撞缓存；
  • per-segment collision graph / symbol fade / placement fingerprint；
  • Fast Path 改造；
  • multi-continuous Fast Path；
  • 重写 visitRenderSegmentExecution()；
  • 修改 NavSea；
  • 新增 NavSea 私有 Native API；
  • 修改 C-001；
  • 修改 V19/V20 release worktree/tag；
  • 升级 MapLibre、NDK、Gradle、AGP、Java、Node 或其他工具链；
  • 为通过测试降低 fail-closed 门槛；
  • Android Gradle/build、APK/AAR build、ADB、设备操作；
  • Jest。用户未要求 Jest，本任务不得新增或执行 Jest。

5. 允许修改范围

生产代码优先限制在：

  • src/mbgl/renderer/render_orchestrator.hpp
  • src/mbgl/renderer/render_orchestrator.cpp
  • src/mbgl/renderer/renderer_impl.cpp
  • include/mbgl/renderer/render_segment.hpp
  • src/mbgl/renderer/retained_underlay_runtime_state.hpp
  • src/mbgl/renderer/render_segment_json.hpp
  • packages/maplibre-particle-rn/src/types.ts

测试/Validation 允许：

  • test/renderer/retained_underlay_cache.test.cpp
  • 与现有 Particle Validation 场景直接相关的最小 Android Test App 文件

文档允许：

  • 本任务书
  • docs/50_Step记录/STEP-102_RenderSegment无Placement段局部复用_v1.md
  • docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md
  • 粒子开发记录.md
  • v3 审查说明只读，除非发现明确事实错误；若需改，停止并先报告

如果实现必须扩大生产代码范围，先停止并报告原因，不得自行扩张架构。

6. 禁止修改范围

  • NavSea 仓库
  • navsea-particle-integration contract/RFC/ADR
  • Fast Path 逻辑、tryRenderParticleFastFrame()、singleContinuousSegment() 语义
  • retainedRangeUsesPlacement() 现有动态语义
  • mixed executor 算法
  • Source isLoaded() 定义
  • STEP-100 source revision/locality 语义
  • STEP-101 teardown 生命周期语义
  • renderer/backend 架构
  • release/version/tag/publish 坐标

7. 实施要求

7.1 结构性 placement-capable 查询

新增 full CPU retained 专用查询，必须基于 layer 结构，而不是当前帧 placementData。

最小保守语义：

  • range 中存在 symbol layer → placement-capable
  • 无 symbol layer → placement-free
  • custom/custom-drawable 继续由 unsupported gate 处理

不得用 needsPlacement()==false 证明 placement-free。

7.2 per-segment placement gate

每个 Retained Segment 至少形成两个明确事实：

  • structural placement capability
  • current full-CPU placement gate result

placement-free Segment 不受纯 global placement gate 阻塞。 placement-bearing Segment 本 Step 继续沿用旧保守 gate，不承诺稳定后 reuse。

变量/字段命名不得把 symbolFadeChange==0 错称为严格 placement stable。

7.3 full CPU mixed execution

segmentSupported 改为使用对应 Segment placement gate。

globalLiveFallback 仅移除纯 aggregate placement 条件，其他真正 global 条件继续保留。

不得重写 visitRenderSegmentExecution()。

7.4 fallback reason

static-placement 必须按 Segment 自身 placement capability/gate 判定，不能从 aggregate reason 无差别传播。

7.5 diagnostics

每个 Segment 最少新增等价语义：

  • placementCapable
  • placementGatePassed
  • actualExecution = composite | live

全局最少新增等价语义：

  • placementChanged
  • symbolFadeChange
  • placementTransitionActive
  • crossSourceCollisions
  • mainBufferExecutionMode = mixed | global-live
  • globalLiveFallbackReason

actualExecution 必须反映本帧 main-buffer 最终实际执行，不能根据 cache finalDecision 推导。 Diagnostics 查询必须无副作用、不得推进 revision。

7.6 RN 类型

只扩展现有 diagnostics 返回类型，不新增 method，不改变 setRenderSegmentPlan() 输入 contract。 Android/iOS Shared Core JSON 语义保持一致。

8. 构建要求

Codex 本阶段不得执行任何 Android 编译/Gradle/APK/AAR build，也不得启动长时间 CMake/Ninja/Bazel 构建。

Codex 完成代码后只需提供精确验证命令，由后续 RDC/用户按规则执行。其中 Android 编译由用户手工执行。

Codex 可执行的机械静态检查仅限：

  • git diff --check
  • 只读 grep/rg/git diff/status
  • 不产生构建产物的格式/静态检查（若仓库已有且无需安装依赖）

不得安装或升级系统依赖来制造测试 PASS。

9. 测试要求

Codex 必须新增/补强测试源码，但本阶段不执行大型测试。

至少覆盖：

  1. placement-free R0 + placement-bearing R1：R0 可 composite，R1 live；
  2. 含 symbol 但当前 placementData 为空：仍判定 placementCapable=true；
  3. 两个 placement-free Retained：持续 reuse/composite；
  4. source-local fading/mutation 回归不误伤 R0；
  5. placement-bearing 在 transition disabled / symbolFadeChange=1 等状态仍不被本 Step 放宽；
  6. 真正 global gate 继续 global-live/fail-closed；
  7. topology 变化释放旧 resource；
  8. cache decision=reuse 但 global-live 时，diagnostics 的 actualExecution 必须为 live；
  9. diagnostics JSON/TS 字段语义一致且查询无副作用。

Android Validation 场景应能在后续手工构建后明确输出 STEP-102 验收所需字段，不依赖 NavSea。

10. 验收标准

代码审计门槛：

  • 新增结构性 placement-capable 查询
  • 未改变 retainedRangeUsesPlacement() 旧语义
  • full CPU per-segment placement gate 生效
  • placement-bearing 继续保守
  • globalLiveFallback 只移除纯 aggregate placement 条件
  • 真正 global gate 保留
  • mixed executor 未重写
  • Fast Path 无语义修改
  • per-segment fallback reason 正确
  • diagnostics 有 actualExecution 与 main-buffer mode/fallback reason
  • RN method surface 不变
  • C-001 不变
  • 测试源码覆盖设计矩阵
  • git diff --check PASS

运行态 PASS 不在 Codex 阶段宣称。Android 手工编译与真机验证未完成前，STEP-102 状态只能写“代码完成 / 等待验证”或同等非 PASS 状态。

11. Git 要求

  • 工作分支：step102-placement-free-retained-locality
  • 禁止修改 particle/main 工作区
  • 禁止 git add -A、git add .、git reset --hard、git clean
  • 只 scoped staging 本任务文件
  • 不提交无关 dirty/untracked 文件
  • Codex 可在实现完成、静态检查通过后创建 scoped implementation commit，但不得 merge 到 particle/main、不得 push release 分支/tag、不得发布制品
  • 是否 push/merge 由后续独立验收决定

12. 必做输出

Codex 完成后必须交付：

  1. 生产代码修改；
  2. C++ 测试源码；
  3. Android Validation STEP-102 场景源码/日志字段；
  4. docs/50_Step记录/STEP-102_RenderSegment无Placement段局部复用_v1.md；
  5. docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md；
  6. 追加 粒子开发记录.md；
  7. 精确列出后续验证命令；
  8. 明确列出所有 NOT RUN / BLOCKED 项；
  9. Git diff/status/commit（若创建）事实。

13. 执行报告完整文件名

固定： docs/报告/STEP-102_RenderSegment无Placement段局部复用_Codex完成报告_v1.md

同主题后续报告只递增 _v2/_v3，不得另造近义文件名。

14. 执行报告固定内容

至少包含：

  1. 执行结论：只能按实际写代码完成/等待验证、PARTIAL、BLOCKED 或 FAIL；未运行 Android 不得写运行态 PASS
  2. Git 基线：branch/start HEAD/end HEAD/status
  3. 实际修改文件
  4. 新增文件
  5. 实现内容逐条对照任务书
  6. 与 v3 设计差异
  7. Fast Path / mixed executor / C-001 未修改审计
  8. diagnostics 新字段与语义
  9. 测试源码覆盖矩阵
  10. 实际执行的静态检查
  11. 未执行的 build/test/Android/设备项目
  12. 用户手工 Android 构建命令
  13. 后续 RDC/真机验收命令与硬门槛
  14. 已知风险与未完成事项
  15. Git commit 信息（若有）

15. 阻塞与停止条件

遇到以下任一情况必须停止扩大修改并报告：

  • 结构性 placement capability 不能仅靠既有 layer type 安全判定，需要新增更大公共抽象；
  • 必须修改 Fast Path 才能完成本任务；
  • 必须重写 mixed executor；
  • 必须改变 collision/Placement 核心算法；
  • 必须修改 C-001 / RN method surface；
  • 必须修改 NavSea；
  • 必须扩大到 renderer/backend 架构重构；
  • 发现 global revision 仍有未预期的 placement 推进，需要新设计；
  • 需要升级工具链/依赖；
  • 需要删除或弱化既有测试/安全门槛。

若实现范围保持在 v3 冻结边界内，可直接完成代码并停在“等待手工构建/运行验证”。

Reference in New Issue View Git Blame Copy Permalink