release: bump version to 0.44.2

VERSION

@@ -1 +1 @@
-0.44.1
+0.44.2

docs/CHANGELOG.md

@@ -8,6 +8,15 @@ This project follows the repository versioning rule:
 - `improvement` -> `+0.0.1`（bugfix + 小功能混合）
 - `bugfix` -> `+0.0.1`
 
+## [0.44.2] — 2026-04-29
+
+### 📝 Documentation
+- 补充 Earth 船只图层技术文档，记录分桶 `THREE.Points` 批量渲染、同尺寸交互 overlay 和屏幕空间 picking 的设计约束。
+- 同步 Earth 渲染图层顺序和样式参考，明确 AIS 船只 renderOrder、depthTest、图标尺寸、航向分桶与 hover 命中半径。
+- 更新船只渲染性能计划状态，标注 `0.44.1` 已落地的实现与后续全球 AIS / LOD 演进方向。
+
+---
+
 ## [0.44.1] — 2026-04-29
 
 ### 🐛 Fixes

docs/plans/earth-vessel-rendering-performance-plan.md

@@ -1,5 +1,17 @@
 # Earth Vessel Rendering Performance Plan
 
+## 当前状态
+
+该计划的前端核心部分已经在 `0.44.1` 落地，但最终实现不是原文设想的 `InstancedBufferGeometry` quad，而是更稳的分桶 `THREE.Points` 方案：
+
+- 普通船只按 moving / anchored 和 `VESSEL_COURSE_BINS` 航向分桶，使用 `PointsMaterial` 批量绘制。
+- 航行船只仍是带方向的三角形，停泊或低速船只仍是圆点。
+- hover / locked 不再放大成世界尺寸 Sprite，而是在原点位叠加同尺寸单点 glow overlay。
+- picking 改为屏幕空间命中，拖动和惯性期间跳过 hover picking。
+- 普通态关闭 glow，交互态才显示 glow，降低 overdraw 并让默认地图更干净。
+
+后续如果需要全球 AIS 或更高船只密度，再评估是否从分桶 `Points` 升级到真正 instanced quad 或视口 bbox / LOD。
+
 ## 背景
 
 Earth 船只图层已经形成了一套较好的视觉语言：
@@ -8,10 +20,10 @@ Earth 船只图层已经形成了一套较好的视觉语言：
 - 标记按航向旋转
 - 停泊或低速船只使用圆点
 - 不同船型使用不同颜色
-- hover / locked 状态有放大、透明度和聚焦反馈
+- hover / locked 状态有 glow、透明度和聚焦反馈
 - 标记带有轻微 glow / soft edge，和 Earth HUD 的观感一致
 
-当前性能问题不应通过降级成普通 `Points` 来解决。目标是在保留现有观赏性的前提下，把底层从“每艘船一个 Sprite 对象”优化为批量绘制和轻量交互。
+当前性能问题不应通过降级成无方向、无船型语义的普通小点来解决。目标是在保留现有观赏性的前提下，把底层从“每艘船一个 Sprite 对象”优化为批量绘制和轻量交互。
 
 ## 当前问题判断
 
@@ -106,11 +118,18 @@ Earth 船只图层已经形成了一套较好的视觉语言：
 
 目标是减少屏幕空间重叠面积，而不是改变符号设计。
 
-## Phase 3：保留视觉的批量渲染
+## Phase 3：保留视觉的批量渲染（已落地为分桶 Points）
 
-正式方案是把每艘船的视觉从 `THREE.Sprite` 迁移为 instanced sprite batch。
+原设想是把每艘船的视觉从 `THREE.Sprite` 迁移为 instanced sprite batch。实际落地时选择了更稳的分桶 `THREE.Points`：
 
-### 1. 使用 instanced quad
+- 不依赖自定义 shader。
+- 不依赖 `Points` 自带 raycaster。
+- 用 canvas 纹理保留三角、圆点、船型颜色和航向。
+- 用 hover / locked 单点 overlay 保留交互 glow。
+
+如果未来全球 AIS 导致分桶 `Points` 仍不够，再升级到 instanced quad。
+
+### 1. 原候选方案：instanced quad
 
 每艘船仍然显示为带贴图/软边的 billboard，但底层使用：
 
@@ -130,7 +149,7 @@ Earth 船只图层已经形成了一套较好的视觉语言：
 
 这样 draw call 从“每艘船一个”变为“每类船只一个”。
 
-### 2. per-instance attributes
+### 2. 原候选方案：per-instance attributes
 
 每个 instance 存：
 
@@ -142,9 +161,21 @@ Earth 船只图层已经形成了一套较好的视觉语言：
 - state
 - mmsi / data index
 
-hover、locked、dimmed 通过更新少量 instance attribute 实现，不再逐个修改 material。
+hover、locked、dimmed 可通过更新少量 instance attribute 实现，不再逐个修改 material。
 
-### 3. 复刻当前视觉
+### 3. 当前落地方案：分桶 `THREE.Points`
+
+当前实现按以下方式复刻视觉：
+
+- moving 船只按 `VESSEL_COURSE_BINS` 做航向分桶。
+- anchored / slow 船只使用圆点分桶。
+- 每个分桶生成一组 `THREE.Points`，共享 `PointsMaterial` 和 canvas 点纹理。
+- `VESSEL_CONFIG.colors` 仍通过 vertex colors 表示船型颜色。
+- hover / locked 在原位置叠加同尺寸单点 overlay，普通态不带 glow，交互态才带 glow。
+
+这样 draw call 从“每艘船一个”变为“每个形状 / 航向分桶一组”，同时避免自定义 shader 的兼容风险。
+
+### 4. 复刻当前视觉
 
 视觉上继续使用当前 canvas texture 或等效 shader：
 
@@ -213,5 +244,6 @@ hover、locked、dimmed 通过更新少量 instance attribute 实现，不再逐
 
 1. 先做 Phase 1，快速恢复地球拖动手感。
 2. 再做 Phase 2，减少每帧 JS 写操作。
-3. 最后做 Phase 3 和 Phase 4，把船只迁移到 instanced sprite batch。
+3. Phase 3 和 Phase 4 已按分桶 `THREE.Points` + 屏幕空间 picking 落地。
 4. Phase 5 等全球船只数据或数量压力出现后再推进。
+5. 如果分桶 `THREE.Points` 达到瓶颈，再评估 instanced quad。

docs/technical/zh/earth-frontend-context.md

@@ -253,11 +253,34 @@ AIS 船只图层入口：
 船只图层当前负责：
 
 - 请求 `/api/v1/visualization/geo/vessels`
-- 将 BarentsWatch AIS GeoJSON 转为 Three.js sprite
+- 将 BarentsWatch AIS GeoJSON 转为地球局部坐标 marker 数据
+- 用按航向分桶的 `THREE.Points` 批量渲染普通船只 marker
 - 按船型映射颜色
 - 根据航行/停泊状态绘制三角形或圆点纹理
+- 用单点 `THREE.Points` overlay 承载 hover / locked glow
 - 支持 hover、lock、轨迹加载和视觉聚焦
 
+船只图层不再是“每艘船一个 `THREE.Sprite`”。原始 Sprite 方案在拖动地球时会把透明对象排序、draw call 和对象级 raycast 成本全部放到主交互路径上；即使 BarentsWatch 免费 AIS 当前只覆盖挪威周边，也会让地球拖动明显不跟手。
+
+当前设计把普通船只拆成少量批次：
+
+- moving / anchored 分开。
+- moving 船只按 `VESSEL_COURSE_BINS` 做航向分桶。
+- 每个批次是一组 `THREE.PointsMaterial`，位置和颜色写入 `BufferGeometry` attribute。
+- 普通态不带 glow；hover / locked 时才在相同点位叠加带 glow 的单点 overlay。
+
+方向标准以 AIS `course / cog` 为准：从正北开始顺时针。普通态和交互态都通过同一套 canvas 旋转规则生成纹理，避免 hover 后箭头方向和原 marker 不一致。
+
+船只 hover / click 也不再对渲染对象做 `raycaster.intersectObjects()`。`main.js` 会：
+
+1. 拖动地球或惯性旋转时跳过 hover picking。
+2. 对 hover picking 做轻量节流。
+3. 只保留正面船只作为候选。
+4. 将候选船只投影到屏幕坐标。
+5. 用 `VESSEL_POINTER_RADIUS_PX` 做像素距离命中，并取最近船只。
+
+这样 picking 位置和用户看到的屏幕 marker 对齐，也避免 `Points` 自带 raycaster 在固定屏幕尺寸图标上的命中半径错位。
+
 图例系统已经注册 `vessels` 模式：
 
 - [legend.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/legend.js)

docs/technical/zh/earth-layer-style-reference.md

@@ -186,6 +186,27 @@
 | footprint renderOrder | local `GROUND_FOOTPRINT_RENDER_ORDER` | `3` | footprint fill |
 | footprint group renderOrder | inline | `0` | 避免 Group 排序盖过卫星点 |
 
+## AIS 船只
+
+| 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |
+| --- | --- | --- | --- |
+| 船只半径偏移 | `VESSEL_CONFIG.altitudeOffset` | `0.56` | 普通 marker 位置 |
+| 船只轨迹半径偏移 | `VESSEL_CONFIG.track.altitudeOffset` | `0.7` | 选中船只轨迹线 |
+| 船只 renderOrder | local `VESSEL_RENDER_ORDER` | `4.4` | 普通 marker 和交互 overlay |
+| 船只轨迹 renderOrder | `VESSEL_RENDER_ORDER - 0.1` | `4.3` | 低于船只 marker |
+| 船只点像素尺寸 | local `VESSEL_POINT_SIZE` | `34` | 普通 marker 与 hover / locked overlay 共享尺寸 |
+| 船只纹理画布尺寸 | local `VESSEL_ATLAS_CELL_SIZE` | `128` | canvas 点纹理 |
+| 航向分桶数 | local `VESSEL_COURSE_BINS` | `32` | moving 船只按 COG 分桶，降低 draw call 同时保留方向 |
+| 船只 hover 拾取节流 | local `VESSEL_HOVER_PICK_INTERVAL_MS` | `100` | `main.js` hover picking |
+| 船只屏幕命中半径 | local `VESSEL_POINTER_RADIUS_PX` | `22` | `main.js` 屏幕空间 picking |
+| 普通船只透明度 | `VESSEL_CONFIG.marker.baseOpacity` | `0.88` | 普通 `PointsMaterial.opacity` |
+| dimmed 船只透明度 | `VESSEL_CONFIG.marker.dimmedOpacity` | `0.26` | 锁定某艘船后其他批次透明度 |
+| hover 船只透明度 | inline | `0.98` | hover overlay |
+| locked 船只透明度 | inline | `1` | locked overlay |
+| 船型颜色 | `VESSEL_CONFIG.colors.*` | cargo / tanker / passenger / fishing / military / other | `PointsMaterial.vertexColors` 和 overlay texture |
+
+AIS 船只普通态使用批量 `THREE.Points`，不是逐船 `THREE.Sprite`。航行船只保持三角形，停泊或低速船只保持圆点；普通态不带 glow，hover / locked 时在同一屏幕尺寸上叠加带 glow 的单点 overlay。AIS 航向按 `course / cog` 从正北顺时针解释，普通态和交互态必须使用同一套 canvas 旋转规则。
+
 ## 算力中心
 
 | 正式名称 | 变量名 | 当前值 | 使用位置 / 说明 |

docs/technical/zh/earth-render-layer-order.md

@@ -30,7 +30,7 @@
 | 3 | 卫星 footprint 填充 | `satellites.js` | `GROUND_FOOTPRINT_RENDER_ORDER` | depth-tested，Group renderOrder 保持 0 | Footprint 在国界线之上，但在算力中心和卫星之下。 |
 | 3-5 | BGP 标记和覆盖层 | `bgp.js` | 各 marker 自身 renderOrder | BGP 拾取路径 | 保持现有 BGP 视觉层级。 |
 | 4.3 | AIS 船只轨迹线 | `vessels.js` | `VESSEL_RENDER_ORDER - 0.1`；`CONFIG.earthRadius + VESSEL_CONFIG.track.altitudeOffset` | 跟随船只显隐，不单独参与拾取 | 选中船只后显示最近轨迹，低于船只 marker。 |
-| 4.4 | AIS 船只 marker | `vessels.js` | `VESSEL_RENDER_ORDER`；`CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset` | 船只拾取路径；只取正面 marker | 航行船只用三角 sprite，停泊/低速用圆点；低于算力中心 `4.5`。 |
+| 4.4 | AIS 船只 marker | `vessels.js` | `VESSEL_RENDER_ORDER`；`CONFIG.earthRadius + VESSEL_CONFIG.altitudeOffset`；普通 marker 为分桶 `THREE.Points`，hover / locked 为单点 `THREE.Points` overlay | `depthTest: true`；`main.js` 使用屏幕空间 picking，只取正面 marker | 航行船只用三角点纹理，停泊/低速用圆点；普通态无 glow，交互态叠加同尺寸 glow；低于算力中心 `4.5`。 |
 | 4.5 | 算力中心 | `compute-centers.js` | `COMPUTE_CENTER_RENDER_ORDER` | 算力中心拾取路径 | 地表设施，保持在卫星下方。 |
 | 5 | 卫星背景点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 位于卫星点下方。 |
 | 6 | 卫星点 | `satellites.js` | 固定 renderOrder | 屏幕空间卫星拾取 | 卫星点压过 footprint 和算力中心。 |
@@ -57,4 +57,4 @@
 | 中国 / 台湾 hover | `CHN` 和 `TWN` 被归到同一个 hover 高亮组；tooltip 仍显示鼠标实际命中的 feature。 |
 | 地形 | 只作为视觉层参与，`terrain.raycast` 已禁用。 |
 | 卫星 | 使用屏幕空间卫星拾取，避免 footprint 或地表层挡住卫星点击。 |
-| 船只 | 使用 sprite marker 拾取，并在 `main.js` 中先过滤正面船只；点击后可加载轨迹线。 |
+| 船只 | 不使用对象级 sprite raycast。`main.js` 会在拖动 / 惯性期间跳过 hover picking，平时将正面船只投影到屏幕坐标，用像素半径命中最近船只；点击后可加载轨迹线。 |

docs/version-history.md

@@ -16,12 +16,13 @@
 ## Current Version
 
 - `main` 当前主线历史推导到：`0.16.5`
-- `dev` 当前开发分支历史推导到：`0.44.1`
+- `dev` 当前开发分支历史推导到：`0.44.2`
 
 ## Timeline
 
 | Version | Type | Branch | Commit | Summary |
 | --- | --- | --- | --- | --- |
+| `0.44.2` | bugfix | `dev` | `pending` | 补充 Earth 船只批量渲染、屏幕拾取、图层顺序、样式参考和性能计划状态文档 |
 | `0.44.1` | bugfix | `dev` | `pending` | 优化 Earth 船只批量渲染性能，修复拖动卡顿、拾取错位、交互态方向/尺寸和地表压盖问题 |
 | `0.44.0` | feature | `dev` | `pending` | 重构数据源目录与采集器设置，新增 BarentsWatch AIS 连接教程、Earth 船只/缩放体验优化和仪表盘前端重启 |
 | `0.43.1` | bugfix | `dev` | `pending` | 修正全量 restart 后 AI Provider 启动提示语义，避免把预期未就绪描述成异常 |

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planet-frontend",
-  "version": "0.44.1",
+  "version": "0.44.2",
   "private": true,
   "packageManager": "bun@1",
   "dependencies": {

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "planet"
-version = "0.44.1"
+version = "0.44.2"
 description = "智能星球计划 - 态势感知系统"
 requires-python = ">=3.14"
 dependencies = [

uv.lock

@@ -475,7 +475,7 @@ wheels = [
 
 [[package]]
 name = "planet"
-version = "0.44.1"
+version = "0.44.2"
 source = { virtual = "." }
 dependencies = [
     { name = "aiofiles" },