tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
particle/main
MapLibreParticleLab/docs/报告/STEP-098_QBIN_V4单帧与八帧滚动缓存_Codex完成报告_v1.md

10 KiB
Raw Permalink Blame History

STEP-098 QBIN V4 单帧与八帧滚动缓存 Codex 完成报告 v1

日期：2026-09-26（JST） 结论：IMPLEMENTED / WAITING_RDC_VALIDATION_AND_PLATFORM_RUNTIME。Codex 源码阶段已交付；未构建、未运行 T01–T17，不能标记功能 PASS。

1. 执行身份与契约

  • 执行器指定实际模型：GPT-6 Luna High。
  • 仓库：Mac 原始正式源码目录 /Users/tei/dev/MapLibreParticleLab；branch particle/main。
  • 起始/结束 HEAD：b1239ac3b1554943200e6fbf14321459ccc86527（本轮无 commit）。
  • 起始时 origin/particle/main 同为 b1239ac3b1554943200e6fbf14321459ccc86527。
  • Integration main/origin/main：1dd576d3304e267e53ed64d31f9711d2350ce10a，工作树干净。
  • 本轮依据 RFC-004、ADR-001、C-002、COORD-005。新契约状态为已接受的设计决定，非代码/设备/V15 发布验收。旧 RFC-003/COORD-004 B 已按用户指示作废删除；此事实解除 STEP-098_公共契约阻塞报告_v1.md 的历史阻塞，本轮未修改旧报告或原任务 v1。
  • 本机 Android Native/RN 版本文件仍为 13.4.1-particle.13，iOS VERSION 为 6.28.0。未更改版本锁、.13 release/tag/manifest/AAR、独立 checkpoint worktree 或远端。
  • git submodule status 与记录 SHA 一致。开工时工作树已有 STEP-097 B tracked/untracked 改动及 STEP-098 原任务等，共 29 条 status 项；均保留。没有执行 reset、clean、stage、commit 或 push。

2. 实施结果

Core、Ingress、Resolver

  • Store 按每个 fieldKey 最多 8 个帧升序存储。精确 validTime 返回真实单帧 T0=T1、mix=0；只有非精确请求且存在合法相邻 pair 时才做插值，未覆盖时间 fail-closed。
  • 分离可共存 schema 与插值身份：相同 grid/plane schema 的新 reference/profile/fieldID 批次可进入窗口并按精确时刻单帧首显；双帧插值必须匹配 fieldID、QBIN referenceTimeMs、resolved profileID/version 和 grid/plane schema。Ingress 验证后保留 profile 身份，避免同 schema 不同 profile 被混插。
  • 满额新时间插入使用临时候选有序集合：以新帧 validTime 为中心比较旧最早/最晚端点距离，远端先在候选集删除；等距按 C-002 删除原最早端。候选邻接 schema 验证成功后才 swap；失败不改 Store。满额正常有效插入仍返回既有 AcceptedInserted，RejectedCapacity 名称保留兼容。
  • Duplicate、同时间 revision/stale/identity-conflict 仍走既有分支，不触发其他时间淘汰；submit 不触碰 forecast clock。每 key 可独立达到 8 帧。
  • 增加原始 decoded 字节计数：每帧为有效性 bitset + 非 validity plane payload，Store/Series 汇总；不计 profile 元数据、Float32 物化快照、图像、GPU texture、particle/trail。

Projection、Renderer、Bridge

  • Binding 和 materialization 支持精确单帧，T0/T1 共享同一个物化 Snapshot。标量-only 帧仍不能成为向量 Particle projection。
  • Particle 与 WeatherColor 首次安装同一 endpoint 时复用 image/texture/scale；当前 bracket 不变时 Source projection 继续沿用 existing equality/materialization reuse；被淘汰的活动端点重新 resolve 后失效清除。
  • 实现位于 Shared Core/common Renderer，GL/Metal 共用语义；没有声明 Android 或 iOS runtime 通过。
  • FieldRuntime.ts、NativeWeatherRuntimeBridge.ts、Android Kotlin/JNI 与 iOS Objective-C++/Facade 静态核对：旧 submitEncodedField(...)、setEncodedForecastTime(...) 名称、签名、返回名称和调用顺序未修改；bridge 没有本轮改动。
  • ABI 说明：RN/平台 bridge 方法 ABI 未变；DecodedFieldFrame 新增内部 profile 字段，C++ 数据结构布局发生变化，需同源码重新构建 Native 消费端。未使用 .13 AAR 冒充该 ABI 验证。

3. 本轮修改文件

STEP-098 源码与测试

  • include/mbgl/particle/field/field_runtime.hpp
  • src/mbgl/particle/field/field_runtime.cpp
  • src/mbgl/particle/field/field_projection_materialization.cpp
  • src/mbgl/particle/ingress/qbin_v2_decoder.cpp
  • src/mbgl/renderer/layers/render_particle_validation_layer.cpp
  • src/mbgl/renderer/layers/render_weather_color_layer.cpp
  • test/particle/field_binding.test.cpp
  • test/particle/field_runtime.test.cpp
  • test/particle/qbin_v2_decoder.test.cpp
  • test/source/raster_array_v4_host_api.test.cpp

新增/追加文档

  • 新增 docs/30_设计/STEP-098_QBIN_V4单帧与八帧滚动缓存设计_v1.md
  • 新增 docs/50_Step记录/STEP-098_QBIN_V4单帧与八帧滚动缓存_v1.md
  • 新增本报告 docs/报告/STEP-098_QBIN_V4单帧与八帧滚动缓存_Codex完成报告_v1.md
  • 仅追加根目录 粒子开发记录.md

现存 dirty B 文件、STEP-098 原任务、旧阻塞报告与 B untracked helper/test 均保留。test/particle/field_runtime.test.cpp 和 test/source/raster_array_v4_host_api.test.cpp 开工前已有 B dirty 内容；其既有 fixture 修正未覆盖，本轮在其上增加 STEP-098 测试，并给 Source QBIN helper 加入 reference-time 参数。本轮没有新增 RN、Android/iOS bridge、Host/NavSea/Server 文件。

4. T01–T17 测试代码覆盖与真实运行状态

“代码覆盖”指对应源码测试场景已新增或由既有定向测试覆盖；所有行的实际运行状态均为 NOT RUN。没有将未运行测试写成 PASS。

项 代码覆盖 实际运行
T01 单帧精确 projection/materialization、标量-only 不产生向量、Source 色场/粒子单帧 NOT RUN
T02 第二帧加入后中点进入双帧插值 NOT RUN
T03 乱序升序；wind/wave 独立 key；批次边界不混插 NOT RUN
T04 满 8 后未来帧保留、最早端淘汰 NOT RUN
T05 满 8 后过去帧保留、最晚端淘汰 NOT RUN
T06 内部时间等距 tie 删除原最早端并维持 8 帧有序 NOT RUN
T07 新 reference/profile 批次精确首显、补帧升级、回到旧批次精确单帧 NOT RUN
T08 Duplicate、identity conflict、revision、stale 有既有 Core/Source 用例；无单个覆盖所有分支的新满额综合用例 NOT RUN
T09 损坏/合同/数值/Grid schema 拒绝及旧投影/字节计数保持；既有 Binding 覆盖错误向量 NOT RUN
T10 pair mix 0.25/0.5/0.99 与真实 validTime；精确端点使用单帧表示 NOT RUN
T11 非覆盖时间返回 WindowUnavailable NOT RUN
T12 外围滚动时活动 pair 与 requestedTime 保持 NOT RUN
T13 活动 endpoint 被淘汰后清除物化 projection NOT RUN
T14 wind 与 wave 各持 8 帧、各自字节计数 NOT RUN
T15 同帧共用 Snapshot/首次 GPU endpoint 资源的源码路径；context loss/真实 GPU 未覆盖 NOT RUN
T16 Core 120 次双向滚动、8 帧上限、clear/clearAll 与 decoded byte 回落；Runtime/GPU 长期泄漏未覆盖 NOT RUN
T17 现有 API/类型/方法顺序静态核对；自动化两步成功/失败 consumer 测试未运行 NOT RUN

5. 已执行与未执行验证

项目 实际结果
git diff --check 通过，仅为空白与 patch 格式检查
新增 C++ 编译 NOT RUN
Core/OpenGL GTest NOT RUN
Metal host GTest / iOS 编译 NOT RUN
Android Gradle、RN consumer、Test Host NOT RUN
iOS/Xcode、Metal 设备 NOT RUN
Jest/npm CI/ADB/模拟器/实体机 NOT RUN
release pipeline、artifact、commit/push NOT RUN

RDC 按顺序执行以下命令，阶段 B 通过后才进入 C：

阶段 B：Store / Ingress / Binding

ninja -C build-step088-opengl mbgl-test-runner
build-step088-opengl/mbgl-test-runner --gtest_filter='ParticleFieldRuntime.*:ParticleFieldBinding.*:ParticleEncodedFieldIngress.*'

阶段 C：Source / Projection / Renderer（OpenGL 与 Metal host）

ninja -C build-step088-opengl mbgl-test-runner
build-step088-opengl/mbgl-test-runner --gtest_filter='Particle*.*:Source.RasterArray*'
ninja -C build-step097-metal-host mbgl-test-runner
build-step097-metal-host/mbgl-test-runner --gtest_filter='Particle*.*:Source.RasterArray*'

OpenGL/Metal host 命令均未在本轮执行。Metal host 结果也不能替代 iOS device runtime。

6. 手工验收、内存与剩余事项

Windows 11 Android 手工命令和 T01–T17 一轮场景清单见 STEP-098 记录 §D。只可使用后续相同源码生成且 Native/RN 版本匹配的 V15 Host APK、RN 包和 Native AAR；命令显式使用 adb -s 192.168.200.139。本轮未启动 V15 pipeline。iOS 需由 Mac 用户在同一冻结源码手工构建并用 Metal 设备检查单帧、双帧、批次边界、双向滚动、clear/context 恢复和长时内存。

CPU decoded 原始存储字节测量 API 已加入，测试源码含 120 次循环和 clear 后归零断言，但断言未运行。Float32 物化占用、GL/Metal 纹理、trail/GPU 峰值、32 帧风险和长时间内存趋势均未测量；不能据此报告内存安全 PASS。当前没有证据显示必须增加全局 MiB 上限，后续由 RDC/设备数据判断是否另行设计预算。

7. 工作树、阻塞与停止点

  • 旧 BLOCKED_CONTRACT 不再适用，RFC-004 等新契约已正式接受。
  • 本轮剩余门槛是 RDC 尚未构建/测试。测试失败、编译失败或状态未知时，停留该阶段并保留现场；不得跳过到平台/V15。
  • STEP-097 B 的既有源码仍在本地工作树，原 Mac 工作树与 checkpoint worktree 均未重置或清理。本轮没有将 B 改动归入 STEP-098 报告修改集。
  • 当前版本锁仍是 Native/RN .13；新增 DecodedFieldFrame C++ layout 不兼容证据尚未通过同版本新构建验证。不能用旧 .13 AAR 替代。
  • 未完成：RDC Core/Renderer 构建与 GTest、Android/iOS 同源码配套编译与真实 runtime、T01–T17 逐项实际执行、长时间内存/资源验证、V15 pipeline、版本制品与 Git 收尾。
  • 本次停止点：Codex 源码交付。无 commit、push、release，也没有宣称 STEP-098 全部验收完成。
Reference in New Issue View Git Blame Copy Permalink