MapLibreParticleLab/docs/40_任务/STEP-095_V13独立严格代码与性能审查_Codex任务_v1.md

STEP-095 V13 独立严格代码与性能审查 — Codex 任务 v1

0. 工作性质与模型

• 本任务是独立、严格、全链路、以源码为最终证据的只读代码/性能调查，不是修复任务，也不是批准已有报告。
• 执行环境：Mac-mini-tei.lan，仓库 /Users/tei/dev/MapLibreParticleLab，分支 particle/main。
• 运行模型：gpt-6-astra，reasoning effort=high；由外部启动命令实际指定，报告记录实际模型。
• 最终交付物必须为中文，具体源码符号、文件路径、命令、证据可保留英文。
• 不以“编译通过”“定向单元测试通过”“已有 Codex 报告 PASS”推断 GPU 运行态、安全性、性能或跨平台一致性已经通过。

1. 源码冻结基线

• 被审查的 V13 代码提交：ee0b89e711bf01335b3aa71d36def785cd97fec3。
• V13 核心功能提交：016fd1fff6a33cf795c10d4f5c5413d308383677。
• V13 发布标识：RN 13.4.1-particle.13；iOS 6.28.0-particle.13；以实际 manifest/tag/API 核实，不假设已在 NavSea 接入。
• 前置独立审查归档提交：45c4dca84928a57a2cf0226737c34cabd7fbfbfb。
• 审查前读取 AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范/、docs/00_项目总则/README.md 与其中标记的当前有效总则。
• 同步检查 git branch、HEAD、origin/particle/main、working tree、release manifest 和相关 tag；记录所有偏差。
• 本任务自身新增文档提交不改变上述被审查的源码 commit；核查源码时固定以该提交为事实基线。

2. 审查独立性：先源码，后已有报告

• 首先依据 Git V12→V13 改动、当前调用链及实际代码独立扫描，不从旧报告结论直接生成 findings。
• 然后阅读 docs/20_调查/Particle_V13_严格代码审查报告_v1.md，逐项复核 F01–F10：确认、修正、否定或标记需动态验证。
• 不能复制上一份报告来冒充独立 review。需要发现旧报告遗漏、误判、证据不足及其他模块的潜在风险。
• 交叉阅读 STEP-088～094 的任务、设计、Step 记录、Codex 报告及相关发布/验证事实。
• 当任务书与代码冲突，分别说明“设计意图”和“实际实现”；不能把历史数据冒充 V13 测量。
• 可以读取 Integration repo 的 contract/status/compatibility，但不得修改该仓库；发现跨平台契约问题只提升级建议。

3. 强制审查范围 A：Renderer 与 V13 Segment

• 通用 RenderSegment plan、JSON parser/resolver、配置切换、missing/reorder/hidden boundary、valid/invalid/recovery。
• Style 全局 Z-order、layerIndex、LayerGroup ordinal、opaque reverse、translucent forward、depth/stencil/blending、debug/legacy/3D 与 offscreen composite 的一致性。
• 任意 R/C 交错：全 R、全 C、R-C-R、C-R-R、R-R-C、R-C-R-C-R、相邻 R-R；缓存 OFF 和资源失败的 full fallback。
• Retained cache 独立生命周期、build/reuse/invalidate/release、topology generation、content fingerprint、diagnostics counters 的归属。
• V12 连续区间兼容映射、单 Continuous Fast Path、多个 Continuous 安全 fallback，注意 silent fallback 与正常渲染的真实成本。
• 特别核查 Segment pass 分割后的 alpha/depth/stencil 语义、source/layer mutation 与下一帧 stale GPU object 风险。

4. 强制审查范围 B：GPU、粒子和时间场

• OpenGL 与 Metal OffscreenTexture、Framebuffer、Texture、render pass、commit/present/wait、resource destroy/context loss；区分通用 Core 与平台实现。
• 是否存在 CPU/GPU 同步等待、重复 GPU allocation、每帧 upload/UBO/drawable 重建、纹理引用失效和资源峰值。
• Particle State A/B、Trail、Field T0/T1/MIX、spatial sampling、forecast/playback、zoom-out reseed、viewport bounds 和 resize/orientation。
• Wind/Wave/Current/Rain 等 canonical FieldProfile；V3/V4 encoded/decoded field、QBIN decoder、projection/materialization、binding/validity/missing data。
• 检查异常或损坏输入、极大网格/时间、浮点 NaN/Inf、整数溢出、文件/缓冲区生命周期、重复/乱序/过期 field、安全失败和内存占用。
• 需要从 Source→Runtime→RenderLayer→Renderer→GPU 按真实调用链追踪，不接受只搜索名称的浅层判断。

5. 强制审查范围 C：高频、线程和 Host API

• 每帧 CPU 分配/深复制/锁竞争/字符串或 JSON 构造、LayerGroup 遍历复杂度、静态 CPU Fast Path 命中与错过原因。
• style/source/tile/image/glyph/placement 失效范围是否正确，segment-local 与全局 revision 的边界是否一致。
• map-scoped lifetime、prepared RenderTree、Runtime/renderer/control state 的并发、线程归属、异步回调、销毁后引用和重复 attach/detach。
• Android Java/Kotlin/JNI 与 iOS ObjC++/Metal 的桥接接口、错误归一化、RN TurboModule typed API、ABI/codegen 与版本锁。
• Test Host 的依赖及 lockfile、构建结果的可复现性、release manifest/npm/AAR/XCFramework 的版本一致性。
• 不将业务 provider、HTTP、Route/ETA 带入 Shared Core；不建议建立新的隐藏私有桥接或第二套协议。

6. 强制审查问题清单

• 是否存在 V13 上线后能够导致画面层级错误、透明度/遮挡错误、丢帧、黑屏、闪烁、过期 cache composite、GPU/CPU 泄漏、崩溃或错误数据的实际源码路径？
• 非法配置是否真正 fail closed？同一 index 换不同 Segment 时旧 cache/diagnostics 归属是否错误？
• Retained contentDirty 是否被误当作 GPU allocation invalid？Metal 逐 cache wait 是否可证实？需要哪些 profiler 证据才能决定修改？
• 高频 Fast Path 是否复制 full diagnostics、扫描 Style 或反复线性搜索？有无更重的热点在既有报告中遗漏？
• 多段 retained 是否存在全 viewport depth/stencil 过度分配；是否有峰值预算、安全回退及 resource accounting？
• source/tile 局部更新是否引起不必要全 retained rebuild？若建议局部化，必须给出不破坏 correctness 的依赖证据。
• 单 Continuous 与多 Continuous 的 Frame 处理在相同真实 Style 下有什么可测的差异？不能外推 STEP-090 历史 A/B 数字。
• release、Test Host、RN/iOS/Android 版本与实际产物是否能被独立复现？尚未测试的必须标 NOT RUN。

7. 审查方法

1. 建立 V12→V13 变更与模块地图，阅读入口、类型定义、状态机、调用方和析构路径。
2. 针对每个怀疑的问题制作最短触发条件和源码调用链；尝试找反例，禁止只因为名称相似就报告漏洞。
3. 按已证实缺陷、源码确定的成本、真实运行影响待验证、显式设计限制、文档/环境偏差分类。
4. 为每条 finding 写严重度 P0/P1/P2/P3、置信度、源文件精确行范围、触发场景、影响、最小安全修复方向和验收方法。
5. 独立比较上一份 F01–F10，标为 CONFIRMED / QUALIFIED / DISPROVED / NEEDS_RUNTIME，说明依据和新增发现。
6. 对潜在收益只给复杂度/估算表达和建议基准测试，不提供无 profiler 支持的 FPS/CPU/GPU 节省百分比。
7. 所有未亲自执行的测试必须标 HISTORY / NOT RUN；已有报告的 PASS 只能列为历史证据，不替代当前独立执行。

8. 运行与修改边界

• 禁止修改任何生产源码、shader、公共 API、构建配置、package/lockfile、release manifest、tag、发布产物或 Integration 文件。
• 禁止运行耗时 CMake/Xcode/Gradle 编译、安装、设备操作和大型测试；由 RDC/用户另行验证。
• 允许只读 git show/log/diff、文件检索、源码静态分析和查看既有日志、测试源码、报告。
• 如判断必须借助 profiler、真机或编译才可定论，写精确验证方案而不是擅自实施。
• 仅允许新增本 STEP 中文调查/Step/完成报告，按规定追加根目录粒子开发记录；不要顺手修复发现的问题。

9. 完成报告格式（必须实际落盘）

• 执行摘要：哪些是确定缺陷、哪些是性能成本、哪些只能动态验证；不能只给结论口号。
• 基线与范围：审查 commit、分支、release manifest、审查的主要文件/代码路径、未覆盖范围。
• Finding 总表：编号、严重度、证据类别、问题、触发、影响、代码定位、修复方向、验证方法。
• 逐条完整分析：至少包含最短可复核调用链及确认或推翻依据；新问题与旧报告重复项区分。
• V13 与 V12 架构/性能成本比较：不确定的写待测；不要虚构性能数值。
• F01～F10 独立复核矩阵：原结论、当前意见、依据、是否需补充/修正。
• 缺失测试与运行态矩阵：GPU correctness、CPU/GPU frame time、allocation/peak memory、30/60 FPS、长时间稳定性、各平台状态。
• 优先级清单：分 correctness gate、无需设备的安全优化、GPU 资源/同步、较大架构改造。
• 具体建议的下一轮 Codex 修复批次（只建议，不创建修复任务，不改源码）。
• Git：起始/最终 HEAD、docs-only diff 清单、commit SHA/message、push 结果、remote HEAD、最终 status。
• 结论状态：调查 PASS/PARTIAL/BLOCKED 与 V13 产品运行态是否通过必须分开。

10. 必做输出和固定路径

• 调查主文档：docs/20_调查/STEP-095_V13独立严格代码与性能调查_v1.md。
• 阶段记录：docs/50_Step记录/STEP-095_V13独立严格代码与性能审查_v1.md。
• Codex 完成报告：docs/报告/STEP-095_V13独立严格代码与性能审查_Codex完成报告_v1.md。
• 追加：根目录 粒子开发记录.md，短而具体地记录本次调查变化、现状及下一步，不覆盖历史。
• 若同主题相同文件已经存在，改用递增版本号并在报告写明，不覆盖旧报告。
• 以上文件全部中文；任何报告必须明确区分事实、推断和待验证。

11. Git 收尾

• 先确保用户现有 dirty/untracked 不被覆盖；只有本任务新增/追加文档允许 staged。
• 不执行 git reset --hard、git clean、force push、tag 移动或向 upstream push。
• 对所有新增文档进行路径、目录、内容、交叉引用检查；git diff --check。
• 仅 git add 上述具体文档和本次追加的开发记录；scoped commit 后 push origin particle/main。
• push 失败或 HEAD 与远端不一致时，不得写 PASS；明确失败与恢复建议。
• 记录源代码相对于原 V13 源码提交没有改变，禁止把 docs-only commit 误写成新 V13 软件发布。
• 最终由 RDC 独立检查报告证据、Git 与任务边界，Codex 不自行宣布正式产品验收。

12. 停止条件

• 无法确认当前 commit、源代码状态与所审查发布版本对应时，停止并报告 BLOCKED。
• 遇到跨项目协议变更/需要修改业务源码时，只形成接口阻塞或修复建议，不扩大任务。
• 证据不足时明确 NEEDS_RUNTIME，不应为了凑数量虚构问题。
• 重大 P0 或明确破坏性问题优先直接写进报告，但本任务仍只读，不自动修复。