tei/MapLibreParticleLab

Fork 0

Files

OpenAI Codex 74be2a5052

validate-scripts / validate-scripts (push) Has been cancelled

Details

docs: freeze particle architecture investigation and design

2026-08-29 12:33:09 +08:00

16 KiB

Raw Blame History

MapLibreParticleLab 10_架构调查指令书 v1

1. 任务基本信息

项目：MapLibreParticleLab
大阶段：10_架构调查
当前基线分支：particle/main
当前前置状态：总则 v1 已提交并推送
任务性质：只读架构调查
是否允许修改业务代码：否
是否允许升级或安装依赖：否
是否允许顺手修复发现的问题：否

2. 任务目标

对 MapLibreParticleLab 当前真实代码、依赖、原生工程、MapLibre 接入方式和渲染架构进行一次完整调查。

本阶段的目的不是设计最终粒子系统，而是回答：

当前项目实际上是怎样运行的，MapLibre 实际经过哪些层完成地图渲染，未来粒子系统有哪些真实可用的接入位置，以及当前仍有哪些关键问题无法仅通过现有代码确认。

最终必须形成一份基于实际仓库源码和配置的中文架构调查报告，为下一阶段 20_架构设计 提供事实基础。

3. 核心原则

3.1 以实际代码为唯一事实来源

不得根据：

记忆
MapLibre 一般架构
React Native 常见做法
网上其他项目的实现
对新版 MapLibre 的印象

推断当前项目架构。

所有结论必须优先来自当前 particle/main 实际源码、配置、依赖锁定文件和原生工程。

如果某项无法通过仓库确认，必须明确标记为：

未确认

不得自行补全。

3.2 本任务只调查，不设计

本任务不得直接决定：

最终粒子渲染技术路线
CPU 粒子还是 GPU 粒子
CustomLayer 是否作为最终方案
是否修改 MapLibre Native
是否自行创建原生 Renderer
是否使用 Metal / OpenGL / Vulkan
最终数据纹理格式
最终 Shader 架构
最终线程模型

可以列出候选扩展位置和现有限制，但不得提前作最终技术选型。

3.3 不预设多个调查任务

本次应尽可能一次完成整个 10_架构调查。

只有在调查后发现某个关键问题同时满足以下条件时，才建议追加新的调查任务：

无法依靠当前项目源码确认；
该问题会直接影响下一阶段技术路线；
需要额外读取第三方源码、编译验证、最小实验或平台专项验证。

不得为了形式完整主动拆出大量 10-01 / 10-02 / 10-03 子任务。

4. 开始前检查

开始调查后先确认以下信息：

当前仓库确实为 MapLibreParticleLab
当前分支为 particle/main
读取当前 Git 状态
确认工作区是否干净
找到并完整阅读当前“总则 v1”
确认项目根目录结构
确认主要源码目录
确认 Android / iOS 原生目录是否存在
确认依赖清单及 lock 文件

如果当前分支或代码状态与上述基线明显不符：

不要修改仓库状态。

继续进行能够完成的只读调查，并在报告中明确记录实际状态。

5. 必做调查内容

5.1 项目整体架构

调查当前项目的真实目录与模块组织。

至少确认：

项目入口
React Native / Expo / Bare RN 等实际工程形态
TypeScript / JavaScript 使用情况
Android 工程
iOS 工程
公共源码目录
地图相关源码目录
实验代码目录
数据处理目录
Shader 或图形相关资源目录
assets
scripts
docs
测试目录
构建配置
Metro 配置
Babel 配置
TypeScript 配置

报告中需要给出简化的当前项目结构图。

只列架构相关目录，不需要机械复制整个文件树。

5.2 当前依赖与版本

读取实际：

package.json
lock 文件
Android Gradle 相关配置
iOS Pod 相关配置
与地图和图形渲染相关的依赖配置

重点确认：

React Native 版本
React 版本
MapLibre React Native 包及实际版本
MapLibre Android / iOS Native 版本，如能够从当前工程确认
Skia 或其他图形库是否存在
Reanimated 等与渲染相关的辅助依赖
OpenGL / Metal / WebGL / GPU 相关第三方库
Native Module / TurboModule / Fabric 相关配置

必须区分：

直接依赖
间接依赖
原生 MapLibre 底层实际版本

如果底层版本无法确认，明确写“未确认”。

6. MapLibre 当前接入链调查

这是本任务重点。

必须从项目实际地图页面或地图 Host 开始向下追踪。

调查：

业务/页面 ↓ React Native Map 组件 ↓ MapLibre React Native 封装 ↓ Android / iOS Native View ↓ MapLibre Native

需要确认当前代码实际使用的：

MapView
Camera
Style
Source
Layer
ShapeSource
RasterSource
ImageSource
CustomLayer，如存在
地图事件
地图生命周期事件
onPress
camera change
style load
render/frame 相关事件

报告中必须给出一张文字形式的实际调用关系图。

例如：

Screen → MapHost → MapView → RN MapLibre Binding → Native Map View

但最终结构必须根据当前代码得出，不得照抄该例子。

7. 地图生命周期调查

调查当前代码能够观察或控制哪些生命周期阶段。

至少关注：

地图组件创建
Native Map 创建
Style 加载开始
Style Ready
地图 Ready
Camera 变化
地图移动
地图缩放
地图旋转
每帧刷新能力
App 前后台
MapView unmount
Native 资源释放

明确：

当前 TS/RN 层已经直接获得哪些生命周期事件

以及：

哪些生命周期只存在 Native 或 MapLibre 内部，目前 JS 层拿不到

8. 自定义渲染扩展点调查

调查当前工程和当前依赖版本实际存在的自定义渲染能力。

重点寻找：

CustomLayer
CustomLayerHost
Native Layer
Render Layer
MapLibre 自定义 layer 接口
自定义 View Overlay
Surface
Texture
GL Context
Metal Context
Renderer hook
Render pass
Native callback
Frame callback

每个发现必须分类。

A. 当前项目已经直接使用

B. 当前依赖已经暴露，但项目尚未使用

C. MapLibre Native 可能支持，但 RN 封装当前未暴露

D. 当前代码无法确认

不要把 B/C/D 写成“当前已经支持”。

9. Android 渲染架构调查

单独调查 Android。

至少确认：

MapLibre Android Native 如何被当前 RN 包引入
MapView 对应原生 View
renderer 所处代码边界
当前工程是否显式涉及 OpenGL
是否能够找到 render thread 相关实现或接口
地图帧刷新由谁驱动
Camera / transform 数据当前在哪一层
Native Module 是否能够接触 MapView 实例
是否存在可插入自定义渲染的明确入口
JS 与 Native 的当前桥接方式

如果当前项目使用 New Architecture，也需要说明其实际启用状态。

10. iOS 渲染架构调查

Android 与 iOS 不得合并推断。

单独确认：

iOS MapLibre Native 依赖
MapView 原生类型
Metal / OpenGL 实际情况
renderer 生命周期
Camera / transform 数据
RN 到 Native 的连接方式
是否能够确认自定义渲染接口
当前 Native 层能够访问的 MapLibre 对象范围

如果 Android 与 iOS 能力不一致，必须明确列出。

11. JS / UI / Native / Render / GPU 边界

基于当前工程实际情况，整理线程和执行层级。

至少区分：

JavaScript Thread
React Native UI/Main Thread
Android/iOS Native 层
MapLibre 内部 Worker
MapLibre Render Thread
GPU

如果某个平台实际名称有所不同，使用项目和 MapLibre 当前版本对应的真实名称。

重点调查：

当前高频数据从 JS 传 Native 会经过什么链路
地图 Camera 高频变化如何传播
是否存在 JS 每帧回调
是否存在 Native 每帧回调
是否存在直接 GPU 资源更新的位置
哪些数据如果每帧跨 JS Bridge 会形成明显风险

这里只描述架构事实和风险，不提前设计最终优化方案。

12. Camera 与坐标变换能力

粒子系统未来必须与地图同步，因此重点调查当前代码能够获得哪些：

center
zoom
bearing
pitch
bounds
viewport size
screen coordinate
geographic coordinate
projection / unprojection
camera matrix
projection matrix
view matrix
transform matrix

区分：

JS API 可以直接获取
Native API 可以获取
MapLibre 内部存在但当前封装未暴露
无法确认

尤其要明确：

当前是否可以获得足够信息，使自定义粒子渲染与 MapLibre 地图的平移、缩放、旋转、pitch 保持严格同步。

如果不能确认，不得猜测。

13. 帧驱动能力

调查未来粒子动画最关键的问题：

谁负责下一帧？

确认当前可利用的：

requestAnimationFrame
RN animation frame
Reanimated frame callback
Native Choreographer / DisplayLink
MapLibre render loop
CustomLayer render callback
GPU render callback

需要说明：

哪些帧驱动来自地图 Renderer 本身
哪些与地图 Renderer 独立
如果使用独立动画循环，理论上可能出现什么同步问题

这里只进行架构分析。

14. 当前数据与实验代码调查

搜索当前仓库内已经存在的：

particle
wind
current
wave
grid
vector field
raster
interpolation
texture
shader
velocity
animation
GPU
GL
Metal
MapLibre custom rendering

以及相关实验代码。

对发现的代码进行分类：

可复用基础代码
仅实验用途
与最终架构可能无关
已弃用
状态不明确

不得因为文件名相似就判定“可复用”。

需要查看真实实现。

15. 海洋/气象格点数据未来可能经过的现有层

本任务不设计数据系统，只调查当前项目有哪些已经存在的基础设施。

关注未来可能涉及：

原始格点数据 → 解析 → 内存结构 → 插值 → 渲染资源 → 地图显示

调查当前是否已经存在：

数据 Fetch 层
ArrayBuffer
TypedArray
二进制解码
Grid 数据模型
经纬度格点模型
缓存
Worker
Native Buffer
Texture Upload
Shader Uniform
数据生命周期管理

报告只描述现状。

16. 性能风险调查

不得运行大型性能优化工作。

仅根据真实架构识别潜在风险。

至少关注：

JS 高频循环
每帧 JS → Native 调用
大数组 Bridge 传输
JSON 序列化
ArrayBuffer 复制
Native → GPU 重复复制
Texture 高频重建
地图 Camera 变化导致的大规模重新计算
React re-render
MapView Overlay 与地图不同步
Android/iOS 实现分叉
GPU context 共享风险
地图销毁后的资源泄漏

风险需要标记等级：

高
中
低
尚无法判断

17. 当前架构图

最终调查报告必须至少包含以下几个简化架构图。

全部使用 Markdown 文本图即可。

17.1 当前 App / MapLibre 总体调用图

17.2 JS → Native → MapLibre 调用链

17.3 Android 地图渲染相关层级

17.4 iOS 地图渲染相关层级

17.5 当前能够确认的数据与渲染边界

不得为了图看起来完整而补画未经确认的组件。

未知位置使用：

[未确认]

18. 关键结论分类

调查报告结尾必须将全部关键结论整理成四类。

18.1 已确认事实

只能放已有源码或配置证据的事实。

18.2 当前限制

当前架构真实存在的限制。

18.3 候选扩展点

当前看来可能承载未来粒子系统的位置。

这里只列候选，不做最终选择。

18.4 未确认问题

列出不能通过本次仓库静态调查确认，但会影响后续架构设计的问题。

每个“未确认问题”注明：

为什么当前无法确认
是否会阻塞 20_架构设计
如果需要继续调查，建议采用什么最小方式确认

19. 是否需要追加调查任务的判断

本次调查结束时必须明确给出：

A. 可以直接进入 `20_架构设计`

或：

B. 必须追加一个新的 `10_架构调查` 子任务

只有关键技术事实无法确认并且会直接影响架构选择时才能选择 B。

如果选择 B，只提出真正需要的最少调查任务。

不得为了保险而把所有未知问题拆成新任务。

20. 禁止事项

本任务禁止：

修改生产源码
修改实验源码
新建粒子实现
修改 MapLibre 接入
升级 MapLibre
升级 React Native
安装任何新 npm 包
安装任何新 Pod
修改 Gradle 依赖
修改 Podfile
修改 Metro
修改 Babel
修改 TypeScript 配置
修改 Android 原生代码
修改 iOS 原生代码
创建 Shader 实现
创建 CustomLayer 实现
创建 Native Module
进行架构重构
顺手修复发现的问题

发现问题只记录。

21. 允许执行的验证

允许执行不会改变项目状态的只读命令，例如：

Git 状态查询
Git 分支查询
文件搜索
文本搜索
查看 package 配置
查看 Gradle 配置
查看 Pod 配置
查看源码
查看当前项目已有脚本定义

如果某个命令可能：

自动安装依赖
修改 lock 文件
修改构建产物
修改 Native 工程
写入项目配置

则不要执行。

本任务主要依赖静态调查。

22. 必做输出

22.1 架构调查成果

必须生成中文调查报告：

docs/20_调查/10_架构调查报告_v1.md

如果同名文件已经存在，不得覆盖，应递增版本号。

该报告是后续 20_架构设计 的主要输入。

22.2 Codex 完成报告

必须生成中文执行完成报告：

docs/报告/10_架构调查_Codex完成报告_v1.md

如果 docs/报告/ 不存在，则创建该目录。

如果同名报告已经存在，不得覆盖旧报告，应递增版本号。

23. 架构调查报告必须包含

docs/20_调查/10_架构调查报告_v1.md 至少包含：

调查环境
Git / 分支 / 工作区状态
总则 v1 读取情况
当前项目整体架构
核心依赖与版本
MapLibre 接入链
MapLibre 生命周期
自定义渲染能力
Android 渲染架构
iOS 渲染架构
JS / Native / Render / GPU 边界
Camera / Matrix / 坐标转换能力
帧驱动能力
当前数据与粒子相关实验代码
当前可复用基础设施
性能与线程风险
当前架构图
已确认事实
当前限制
候选扩展点
未确认问题
是否需要追加调查任务
是否已经具备进入 20_架构设计 的条件

24. Codex 完成报告必须包含

docs/报告/10_架构调查_Codex完成报告_v1.md 至少包含：

本次实际调查范围
必做项逐项状态：已完成 / 未完成 / 无法验证
未完成或无法验证的原因
实际生成或修改的文档清单
是否修改生产代码
是否安装或升级依赖
是否存在需要用户关注的阻塞项
下一步建议

25. 必做项完成检查

完成前逐项检查：

已读取总则 v1
已确认当前实际 Git 基线
已调查整体目录和工程形态
已确认核心依赖版本
已追踪 MapLibre 实际调用链
已调查地图生命周期
已调查自定义渲染扩展点
已分别调查 Android
已分别调查 iOS
已调查线程与执行边界
已调查 Camera / 坐标 / Matrix 能力
已调查帧驱动能力
已搜索现有粒子/场数据/Shader 实验代码
已调查当前可复用的数据基础设施
已整理性能风险
已绘制必要架构图
已区分事实、限制、候选和未知项
已判断是否需要追加调查
已判断能否进入 20_架构设计
未修改生产代码
未升级或安装依赖
已生成 docs/20_调查/ 下的正式调查报告
已生成 docs/报告/ 下的 Codex 完成报告

不得静默跳过任何必做项。

无法完成的项目必须明确写：

未完成

或：

无法验证

并说明原因。

26. 完成标准

本任务完成的标准不是“找到一个粒子方案”。

真正完成标准是：

已经能够基于 MapLibreParticleLab 当前真实代码，准确描述项目、React Native、Native、MapLibre 和 GPU 之间的现有边界，并明确下一阶段进行粒子系统架构设计时，哪些能力已经确认、哪些扩展位置值得考虑、哪些关键事实仍需要额外验证。

达到这个状态后，10_架构调查 才算完成。

除非存在真正阻塞架构选择的未知项，否则下一步直接进入：

20_架构设计

16 KiB Raw Blame History Unescape Escape