cesium-multi-target-framework 0.1.0

package/doc//345/257/271/345/244/226/346/216/245/345/217/243/350/257/264/346/230/216.md

@@ -0,0 +1,519 @@
+# 对外接口说明
+
+本文档按 `src/index.ts` 的包根入口整理当前对外能力，适用于从 `cesium-multi-target-framework` 接入的业务方。
+
+## 一、包根导出
+
+```ts
+import {
+  Viewer,
+  MultiTargetFramework,
+  createMultiTargetFramework,
+  SiteLayer,
+  TrackManager,
+  createQuadClusterer,
+  clusterProgressive,
+  lonLatToLocalPlane,
+  createClusterWorkerClient,
+  bindFrameworkEventBus,
+  bindSiteLayerEventBus,
+  getFrameworkEventBus,
+} from "cesium-multi-target-framework";
+```
+
+包根导出分为七类：
+
+| 类别 | 导出 |
+| --- | --- |
+| Cesium | `export * from "cesium"`，可直接导入 `Viewer`、`Cartesian3` 等 Cesium API |
+| 高层目标框架 | `MultiTargetFramework`、`createMultiTargetFramework` |
+| 底层目标场景 | `MultiTargetScene` |
+| 轨迹和站点 | `TrackManager`、`SiteLayer` |
+| Web Event Bus | `bindFrameworkEventBus`、`bindSiteLayerEventBus`、`getFrameworkEventBus`、`tryGetFrameworkEventBus`、`createFrameworkEventBus` |
+| 聚类工具 | `createQuadClusterer`、`clusterProgressive`、`lonLatToLocalPlane`、`createClusterWorkerClient` |
+| 常量 | `VERSION`、`DEFAULT_LOD`、`DEFAULT_POOL`、`DEFAULT_ANIMATED_POOL`、`DEFAULT_SCENE`、`TARGET_DOMAINS` |
+
+常用类型包括：`TargetData`、`StandardTargetData`、`TrackPoint`、`IncrementalPayload`、`PackedTargetData`、`SceneConfig`、`MultiTargetFrameworkOptions`、`MultiTargetTypeConfig`、`TargetSnapshot`、`ContextMenuContext`、`SiteData`、`SiteLayerOptions`、`TrackRecord`、`ClusterWorkerClient`、`FrameworkEventBus`、`FrameworkBusActionMap`、`FrameworkBusEventMap` 等。
+
+## 二、高层入口 `MultiTargetFramework`
+
+推荐业务优先使用该入口。它不改写原始 `Viewer`，而是在内部持有 `scene`、`viewer`、`tracks`。
+
+### 创建
+
+```ts
+const framework = new MultiTargetFramework(viewer, {
+  targetTypes: [
+    {
+      type: "ship",
+      name: "船舶",
+      iconPath: "/icons/target-ship-mask.png",
+      defaultColor: "#25e65c",
+      smoothMove: true,
+    },
+  ],
+  scene: {
+    data: { commitIntervalMs: 2000, leading: true, worker: true },
+    merge: { enabled: true, maxVisible: 30000 },
+  },
+});
+
+// 等价工厂（异步：等引擎就绪后 resolve）
+const framework2 = await createMultiTargetFramework(viewer, options);
+```
+
+`MultiTargetFramework` 内部会启动一个 Web Worker，构造函数同步返回时引擎尚未就绪。需要「初始化完成后再加载依赖底座的其它组件」时，有两种等价写法：
+
+```ts
+// 写法一：同步 new，可立即挂事件/调方法，需要就绪时再 await
+const framework = new MultiTargetFramework(viewer, options);
+framework.scene.on("perf", console.log);
+await framework.ready;        // 引擎（Worker 握手）就绪
+loadOtherComponents(framework);
+
+// 写法二：异步工厂，拿到的实例已就绪
+const framework3 = await MultiTargetFramework.create(viewer, options);
+loadOtherComponents(framework3);
+```
+
+> `ready` 只等引擎就绪（Worker init 握手完成）；glTF 模型按需懒加载，不纳入就绪范围。
+
+`MultiTargetFrameworkOptions`：
+
+| 字段 | 说明 |
+| --- | --- |
+| `targetTypes` | 必填，目标类型数组 |
+| `scene` | 可选，除 `nodeTypes` 之外的 `SceneConfig` |
+
+`MultiTargetTypeConfig` 重点字段：`type`、`name`、`targetDomain`、`iconPath`、`defaultColor`、`highModel`、`lowModel`、`highModelUrl`、`lowModelUrl`、`scale`、`modelHeadingOffset`、`modelPitchOffset`、`modelRollOffset`、`smoothMove`、`smoothMoveMinCameraHeight`、`smoothMoveDurationMs`、`predict`、`predictMove`、`predictMinCameraHeight`、`predictSeconds`、`predictFitSeconds`。
+
+### 数据方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `setData(targets)` | `setTargetData` 的别名，全量替换目标数据 |
+| `upsert(targets)` | `upsertTargetData` 的别名，增量新增或更新 |
+| `remove(ids)` | `removeTargetData` 的别名，按 id 删除 |
+| `addTarget(target)` | 校验并实时 upsert 单目标，返回校验后的目标 |
+| `updateTarget(target)` | 校验并实时 upsert 单目标，返回校验后的目标 |
+| `setTargetData(targets)` | 全量替换目标数据 |
+| `upsertTargetData(targets)` | 增量新增或更新目标数据 |
+| `removeTargetData(ids)` | 实时删除目标 |
+| `applyTargetIncremental(payload)` | 应用 `{ upserts, removes }` 增量包 |
+
+`MultiTargetFramework` 会校验目标字段，只允许 `id`、`type`、`lon`、`lat`、`height`、`speedH`、`speedV`、`heading`、`renderColor`、`openAnimate`、`animateType`、`animateColor`、`nationality`、`customInfo`、`track`、`secrecy`、`extra`。
+
+### 样式和显示
+
+| 方法 | 说明 |
+| --- | --- |
+| `setTargetColor(id, color, options?)` | 设置单个或多个目标颜色，颜色格式 `#RRGGBB` 或 `#RRGGBBAA` |
+| `setTargetGlow(id, enabled, color?, options?)` | 开关发光动画 |
+| `hideTarget(id, options?)` | 隐藏目标 |
+| `showTarget(id, options?)` | 显示目标 |
+| `disappearTarget(id, options?)` | `hideTarget` 别名 |
+| `appearTarget(id, options?)` | `showTarget` 别名 |
+| `setNameplateConfig(config)` | 动态更新名称牌/标签配置 |
+
+`id` 可传字符串或字符串数组。`TargetStyleOptions.clearBefore` 默认 `true`，表示本次样式补丁会先清理旧同类样式；`clearBefor` 为兼容旧拼写。
+
+### 选择、框选和定位
+
+| 方法 | 说明 |
+| --- | --- |
+| `selectTarget(id, options?)` | 选中目标，返回 `TargetSnapshot | null` |
+| `selectTargets(ids, options?)` | 批量选中目标，返回存在的快照数组 |
+| `unselectTarget(id)` | 取消单目标选中 |
+| `clearSelection()` | 清空选中和框选状态 |
+| `boxTarget(id, enabled?, options?)` | 设置黄色框选覆盖层，`enabled` 默认 `true` |
+| `unboxTarget(id, options?)` | 取消框选 |
+| `locateTarget(id, options?)` | 飞行定位目标，返回目标快照 |
+
+`LocateTargetOptions`：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `range` | `18000` | 相机离目标距离，单位米 |
+| `height` | - | 兼容旧字段，低优先级 |
+| `duration` | `0.8` | 飞行时间，秒 |
+| `pitch` | `-65` | 俯仰角，度 |
+| `heading` | `0` | 航向角，度 |
+
+### 右键菜单
+
+| 方法 | 说明 |
+| --- | --- |
+| `registerContextMenuItem(item)` | 注册菜单项，返回注销函数 |
+| `showContextMenu(ctx)` | 使用统一菜单 DOM 展示上下文 |
+| `closeContextMenu()` | 关闭菜单 |
+
+```ts
+const dispose = framework.registerContextMenuItem({
+  key: "locate",
+  label: "定位",
+  targetKinds: ["target", "site"],
+  order: 10,
+  visible: (ctx) => ctx.target.kind !== "ground",
+  onClick: async (ctx) => {
+    if (ctx.target.kind === "target") await ctx.framework.locateTarget(ctx.target.id);
+  },
+});
+```
+
+`ContextMenuContext.target.kind` 支持：
+
+| kind | 数据 |
+| --- | --- |
+| `"target"` | `id`、`type`、`data: TargetSnapshot` |
+| `"ground"` | `lon`、`lat`、`height` |
+| `"site"` | `id`、`siteType`、`data?` |
+
+### 生命周期
+
+| 方法 | 说明 |
+| --- | --- |
+| `destroy()` | 销毁菜单 DOM、事件监听、底层场景和 worker |
+| `MultiTargetFramework.create(viewer, options)` | 静态异步工厂，构造后等 `ready` 就绪再 resolve，返回 `Promise<MultiTargetFramework>` |
+
+## 三、底层入口 `MultiTargetScene`
+
+`MultiTargetScene` 更接近渲染引擎本体，适合需要 packed 数据、底层事件或自定义封装的场景。高层 `MultiTargetFramework.scene` 即为此实例。
+
+### 属性
+
+| 属性 | 说明 |
+| --- | --- |
+| `config` | 解析后的 `ResolvedConfig` |
+| `render` | 点云/图标渲染器 |
+| `models` | 低模/高模模型池渲染器 |
+| `symbols` | 可选，地表实例化有向符号渲染器 |
+| `selection` | 选中覆盖层渲染器 |
+| `tracks` | `TrackManager` |
+| `nodes` | `SceneNodeStats` 渲染统计 |
+| `quality` | 当前质量档，当前固定为 `{ tier: "high" }` |
+| `targetCount` | 当前 worker 内目标总数 |
+
+### 数据和渲染方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `setData(targets)` | 全量目标数据 |
+| `applyIncremental(payload)` | 增量目标数据 |
+| `applyRealtimeUpsert(targets)` | 实时 upsert，不走周期提交等待 |
+| `applyRealtimeRemove(ids)` | 实时删除 |
+| `applyPacked(payload)` | 提交 typed array packed 数据，适合大批量高频输入 |
+| `applyTargetStyle(patches)` | 底层样式补丁 |
+| `setBoxedTargetIds(ids)` | 设置框选 id 集合 |
+| `setLabelConfig(config)` | 更新标签配置 |
+| `flushNow()` | 立即提交当前 staged 数据 |
+| `pause()` | 暂停提交和视口刷新 |
+| `resume()` | 恢复并刷新视口 |
+| `destroy()` | 销毁 worker、渲染器、事件和选择状态 |
+
+### 查询和交互方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `selectTarget(id, clearBefore?)` | 选中目标，返回 `PickedNodeLike | null` |
+| `selectTargets(ids, clearBefore?)` | 批量选中，返回命中的目标数组 |
+| `unselectTarget(id)` | 取消选中 |
+| `clearSelection(emit?)` | 清空选择，`emit` 默认 `true` |
+| `getTargetSnapshot(id)` | 从 worker 查询目标逻辑快照 |
+| `getRenderedTargetFrame(id, result?)` | 查询当前实际渲染帧位置和航向 |
+| `getRenderedTargetPosition(id, result?)` | 查询当前 render packet 中的渲染坐标 |
+
+### 事件
+
+`MultiTargetScene` 继承 `EventEmitter`，使用 `scene.on(event, handler)` 监听，返回取消监听函数。
+
+| 事件 | 载荷 |
+| --- | --- |
+| `perf` | 输入、worker、渲染慢帧等性能事件 |
+| `dirty` | `{ added, updated, removed }` 普通 diff |
+| `packedDirty` | packed diff |
+| `pick` | `PickedNodeLike | null` |
+| `hover` | `PickedNodeLike | null` |
+| `selection` | `PickedNodeLike[]` |
+| `contextmenu` | 目标或空地右键上下文 |
+
+## 四、目标数据类型
+
+`TargetData` / `StandardTargetData`：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `id` | 是 | 唯一 id |
+| `type` | 是 | 目标类型，必须命中配置 |
+| `lon` / `lat` / `height` | 是 | WGS84 经纬度和高度 |
+| `speedH` / `speedV` | 是 | 水平/垂直速度，m/s |
+| `heading` | 是 | 航向角，度，正北 0 顺时针 |
+| `renderColor` | 否 | `#RRGGBB` 或 `#RRGGBBAA` |
+| `openAnimate` | 否 | 是否开启动画 |
+| `animateType` | 否 | 当前内置支持 `glow` / `发光` |
+| `animateColor` | 否 | 动画颜色 |
+| `nationality` | 否 | 国籍/归属字符串 |
+| `customInfo` | 否 | 自定义信息对象，可用于名称牌字段 |
+| `track` | 否 | `TrackPoint[]` |
+| `secrecy` | 否 | 密级（预留字段，当前仅透传，未参与聚合/合并逻辑） |
+| `extra` | 否 | 额外内部/业务状态 |
+
+`PackedTargetData` 用 typed array 表示大批量数据：`lon`、`lat` 必填；`ids`、`types`、`height`、`speedH`、`speedV`、`heading`、`secrecy`、`renderColor`、`animate`、`animateColor`、`removes` 可选。
+
+## 五、配置速查
+
+| 配置 | 当前默认 | 说明 |
+| --- | --- | --- |
+| `lod.pointAbove` | `150000` | 高于此高度走点模式 |
+| `lod.animatedBelow` | `10000` | 低于此高度允许高模动画 |
+| `pool.size` | `30000` | 通用目标池容量 |
+| `animatedPool.size` | `64` | 高模动画容量 |
+| `updateFps` | `30` | 渲染/刷新频率 |
+| `predictSeconds` | `10` | 预测窗口秒数 |
+| `predictFitSeconds` | `2` | 新权威数据到达后的拟合秒数 |
+| `fadeMs` | `350` | 显隐淡入淡出时间 |
+| `masterHideHeight` | `150000` | 高于此高度隐藏模型内容 |
+| `merge.mode` | `"global"` | 聚合模式 |
+| `merge.maxVisible` | `pool.size` | 最大渲染目标数 |
+| `merge.globalRootLimit` | `500` | global 顶层根聚合数量上限 |
+| `merge.globalMaxLevels` | `64` | global 最大层级 |
+| `merge.globalRebuildIntervalMs` | `300000` | global 缓存重建间隔 |
+| `merge.globalViewportHeight` | `450000` | 高于此高度按全球视口处理 |
+| `merge.cameraMergeBaseHeight` | `100000` | 低于/等于该高度不随相机增加合并半径 |
+| `merge.cameraMergeStepHeight` | `10000` | 相机高度每增一档的高度 |
+| `merge.cameraMergeStepRadius` | `100` | 每档半径增量 |
+| `pick.enabled` | `true` | 是否启用点击拾取 |
+| `pick.pixelThreshold` | `20` | 拾取像素阈值 |
+| `pick.hover` | `true` | 是否启用 hover |
+| `cull.viewportBufferRatio` | `0.15` | 视口缓冲比例 |
+| `label.enabled` | `true` | 是否显示名称牌 |
+| `label.maxCount` | `200` | 名称牌最多显示数量 |
+| `label.maxCameraHeight` | `5000` | 名称牌最大相机高度 |
+| `frame.maxLowModelRenderItems` | `3000` | 低模后端数量上限 |
+| `frame.maxModelRenderItems` | `2000` | 旧兼容项 |
+| `data.commitIntervalMs` | `2000` | 数据提交周期 |
+| `data.leading` | `true` | 首批数据是否立即提交 |
+| `data.worker` | `true` | 数据处理是否使用 worker |
+| `groundSymbols` | `false` | 点档单目标是否用地表实例化有向符号 |
+| `groundSymbolPixelSize` | `30` | 地表符号像素大小 |
+
+## 六、轨迹 `TrackManager`
+
+可通过 `framework.tracks` 或 `scene.tracks` 使用。
+
+| 方法 | 说明 |
+| --- | --- |
+| `on("hover", handler)` | 监听轨迹点 hover，载荷为 `TrackHoverInfo | null` |
+| `setTracks(tracks)` | 新增或更新轨迹 |
+| `getTracks(targetIds?)` | 查询轨迹，返回拷贝 |
+| `showTracks(targetIds)` | 显示轨迹 |
+| `hideTracks(targetIds)` | 隐藏轨迹 |
+| `removeTracks(targetIds)` | 删除指定轨迹 |
+| `clearTracks()` | 清空轨迹 |
+
+`TrackRecord` 支持 `pointList` 或 `trackLine`。`trackLine` 格式为 `LINESTRING (...)` 或 `LINESTRING Z (...)`。
+
+## 七、站点层 `SiteLayer`
+
+站点层独立于目标系统，用于光电、雷达、AIS 等固定站点图标/低模展示。
+
+```ts
+const siteLayer = new SiteLayer(viewer, {
+  modelSwitchHeight: 8000,
+  siteTypes: [
+    {
+      type: "radar",
+      category: "radar",
+      iconPath: "/icons/radar.png",
+      lowModel: { url: "/model/radar.glb" },
+    },
+  ],
+});
+
+siteLayer.setData([{ id: "radar-1", type: "radar", lon: 121, lat: 31, height: 0 }]);
+```
+
+### 属性和方法
+
+| 方法/属性 | 说明 |
+| --- | --- |
+| `options` | 解析后的站点配置 |
+| `stats` | `{ total, inView, iconCount, lowModelCount, lowModelEligibleCount, mode }` |
+| `setData(sites)` | 全量设置站点 |
+| `pickAt(position, thresholdPx?)` | 按屏幕坐标拾取最近站点 |
+| `clear()` | 清空站点 |
+| `destroy()` | 销毁图标、低模和事件 |
+
+事件：
+
+| 事件 | 载荷 |
+| --- | --- |
+| `contextmenu` | `{ site, screenX, screenY, cartesian? }` |
+| `pick` | `SiteData | null` |
+
+`SiteLayer` 右键站点后可调用 `framework.showContextMenu(...)` 接入统一菜单。
+
+## 八、聚类工具
+
+### 同步聚类
+
+| 方法 | 说明 |
+| --- | --- |
+| `lonLatToLocalPlane(lons, lats, count, lon0?, lat0?)` | 经纬度投影到本地平面米坐标 |
+| `clusterProgressive(xs, ys, count, options?)` | 一次性递进聚类，返回独立数组，适合低频 |
+| `createQuadClusterer(initialCapacity?)` | 创建复用缓冲的高频聚类器 |
+
+`ProgressiveClusterOptions`：`baseCellMeters` 默认 `200`、`maxClusters` 默认 `30000`、`maxLevels` 默认 `20`。
+
+### Worker 聚类
+
+```ts
+const client = createClusterWorkerClient();
+const result = await client.run(lons, lats, count, { baseCellMeters: 200, maxClusters: 30000 });
+client.terminate();
+```
+
+`ClusterWorkerClient`：
+
+| 方法 | 说明 |
+| --- | --- |
+| `run(lons, lats, count, options?)` | 拷贝输入并在 worker 中聚类；忙时 last-wins，旧排队任务返回 `null` |
+| `inputBuffers(count)` | 借出内部输入缓冲 |
+| `runReusing(count, options?)` | 零拷贝提交内部输入缓冲 |
+| `terminate()` | 结束 worker |
+
+## 九、Web Event Bus 自动对外暴露能力
+
+本包集成 `web-event-bus`，用于把框架实例的对外方法和事件自动暴露到全局 bus。创建 `MultiTargetFramework` 后会自动注册 framework/tracks 相关 action 并桥接 scene/tracks 事件；创建 `SiteLayer` 后会自动注册 site 相关 action 并桥接站点事件。该能力不会修改 `scene.on(...)`、`siteLayer.on(...)`、`tracks.on(...)` 的原行为，实例 `destroy()` 时会自动解绑本实例注册的 action 和事件桥接。
+
+默认使用固定 action 名；如果页面上同时存在多个 `MultiTargetFramework` 或多个 `SiteLayer`，最后创建的同类实例会接管对应 action。旧实例销毁时不会注销已被新实例接管的 action。
+
+### 使用方式
+
+```ts
+import {
+  getFrameworkEventBus,
+} from "cesium-multi-target-framework";
+
+const framework = new MultiTargetFramework(viewer, options);
+const siteLayer = new SiteLayer(viewer, siteOptions);
+const bus = getFrameworkEventBus();
+
+bus.on("mtf.scene.hover", (payload) => {
+  console.log("scene hover", payload);
+});
+
+await bus.invoke("mtf.framework.locateTarget", {
+  id: "ship-001",
+});
+```
+
+| 工具 | 说明 |
+| --- | --- |
+| `getFrameworkEventBus()` | 获取 `web-event-bus` 的浏览器全局 bus；非浏览器环境会抛错 |
+| `tryGetFrameworkEventBus()` | 获取全局 bus；不可用时返回 `null` |
+| `createFrameworkEventBus()` | 创建独立 bus 实例，不挂到全局 |
+| `bindFrameworkEventBus(framework, options?)` | 高级用法：手动把指定 `MultiTargetFramework` 绑定到自定义 bus 或自定义 owner |
+| `bindSiteLayerEventBus(siteLayer, options?)` | 高级用法：手动把指定 `SiteLayer` 绑定到自定义 bus 或自定义 owner |
+
+自动绑定内部也使用 `FrameworkBusBinding` 管理生命周期。手动调用 `bindFrameworkEventBus` / `bindSiteLayerEventBus` 时会返回该对象：
+
+| 字段/方法 | 说明 |
+| --- | --- |
+| `active` | 是否成功绑定；非浏览器环境且未传入自定义 bus 时为 `false` |
+| `owner` | 注册到 bus 的 owner 名 |
+| `dispose()` | 注销本次注册的 action，并取消事件桥接监听 |
+
+绑定选项：
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `bus` | 全局 bus | 指定使用的 `FrameworkEventBus` |
+| `owner` | `"cesium-multi-target-framework"` | 注册 action 时写入的 owner |
+| `registerActions` | `true` | 是否注册方法 action |
+| `bridgeEvents` | `true` | 是否桥接框架事件到 bus |
+| `replaceExisting` | `false` | action 已存在时是否先 unregister 再注册 |
+
+### 自动暴露的事件
+
+事件会在对应实例创建后自动桥接到 bus。bus listener 抛错由 `web-event-bus` 隔离，不影响原本 `.on()` 监听。
+
+| event 字符串 | 载荷 |
+| --- | --- |
+| `mtf.scene.perf` | `SceneEvents["perf"]` |
+| `mtf.scene.dirty` | `SceneEvents["dirty"]` |
+| `mtf.scene.packedDirty` | `SceneEvents["packedDirty"]` |
+| `mtf.scene.pick` | `PickedNodeLike \| null` |
+| `mtf.scene.hover` | `PickedNodeLike \| null` |
+| `mtf.scene.selection` | `PickedNodeLike[]` |
+| `mtf.scene.contextmenu` | `SceneContextMenuPayload \| null` |
+| `mtf.track.hover` | `TrackHoverInfo \| null` |
+| `mtf.site.contextmenu` | `SiteContextMenuPayload` |
+| `mtf.site.pick` | `SiteData \| null` |
+| `mtf.site.hover` | `SiteData \| null` |
+
+### 自动暴露的方法 action
+
+创建 `MultiTargetFramework` 后自动注册 `framework` 和 `framework.tracks` 的对外方法：
+
+| action 字符串 | params | result |
+| --- | --- | --- |
+| `mtf.framework.addTarget` | `{ target }` | `StandardTargetData` |
+| `mtf.framework.updateTarget` | `{ target }` | `StandardTargetData` |
+| `mtf.framework.setTargetData` | `{ targets }` | `void` |
+| `mtf.framework.upsertTargetData` | `{ targets }` | `void` |
+| `mtf.framework.removeTargetData` | `{ ids }` | `void` |
+| `mtf.framework.applyTargetIncremental` | `{ payload }` | `void` |
+| `mtf.framework.setTargetColor` | `{ id, color, options? }` | `void` |
+| `mtf.framework.setTargetGlow` | `{ id, enabled, color?, options? }` | `void` |
+| `mtf.framework.hideTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.showTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.disappearTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.appearTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.setNameplateConfig` | `{ config }` | `void` |
+| `mtf.framework.selectTarget` | `{ id, options? }` | `TargetSnapshot \| null` |
+| `mtf.framework.selectTargets` | `{ ids, options? }` | `TargetSnapshot[]` |
+| `mtf.framework.unselectTarget` | `{ id }` | `void` |
+| `mtf.framework.clearSelection` | `undefined` | `void` |
+| `mtf.framework.boxTarget` | `{ id, enabled?, options? }` | `void` |
+| `mtf.framework.unboxTarget` | `{ id, options? }` | `void` |
+| `mtf.framework.locateTarget` | `{ id, options? }` | `TargetSnapshot \| null` |
+| `mtf.framework.registerContextMenuItem` | `{ item }` | `() => void` |
+| `mtf.framework.showContextMenu` | `{ context }` | `void` |
+| `mtf.framework.closeContextMenu` | `undefined` | `void` |
+| `mtf.framework.destroy` | `undefined` | `void` |
+| `mtf.tracks.setTracks` | `{ tracks }` | `void` |
+| `mtf.tracks.getTracks` | `{ targetIds? } \| undefined` | `TrackRecord[]` |
+| `mtf.tracks.showTracks` | `{ targetIds }` | `void` |
+| `mtf.tracks.hideTracks` | `{ targetIds }` | `void` |
+| `mtf.tracks.removeTracks` | `{ targetIds }` | `void` |
+| `mtf.tracks.clearTracks` | `undefined` | `void` |
+
+创建 `SiteLayer` 后自动注册站点层方法：
+
+| action 字符串 | params | result |
+| --- | --- | --- |
+| `mtf.site.setData` | `{ sites }` | `void` |
+| `mtf.site.clear` | `undefined` | `void` |
+| `mtf.site.pickAt` | `{ position, thresholdPx? }` | `SiteData \| null` |
+| `mtf.site.destroy` | `undefined` | `void` |
+
+### TypeScript 类型
+
+| 类型 | 说明 |
+| --- | --- |
+| `FrameworkEventBus` | 带框架事件/action 类型提示的 bus |
+| `FrameworkBusEventMap` | event name 到 payload 的映射 |
+| `FrameworkBusActionMap` | action name 到 params/result 的映射 |
+| `FrameworkEventName` / `FrameworkEventPayload` | 事件名和载荷辅助类型 |
+| `FrameworkBusActionName` / `FrameworkBusActionParams` / `FrameworkBusActionResult` | action 名、参数、结果辅助类型 |
+
+## 十、事件工具 `EventEmitter`
+
+`EventEmitter<EventMap>` 是一个轻量事件类，`MultiTargetScene`、`TrackManager`、`SiteLayer` 都继承它。
+
+| 方法 | 说明 |
+| --- | --- |
+| `on(event, handler)` | 注册监听，返回取消函数 |
+| `off(event, handler)` | 取消监听 |
+| `emit(event, payload)` | 触发事件，通常内部使用 |
+| `clear()` | 清空所有监听 |

package/doc//345/267/245/344/275/234/350/256/241/345/210/222.md

@@ -0,0 +1,59 @@
+# Cesium 多目标渲染框架 — 工作计划
+
+> 逐项实施，完成一项勾一项。`- [ ]` 未完成，`- [x]` 已完成。
+
+## 阶段 0：项目骨架
+- [x] 初始化 `package.json`（TS 库 + Vite，产出 ESM/UMD + .d.ts）
+- [x] `tsconfig.json` / `vite.config.ts`（demo）/ `vite.lib.config.ts`（库构建）
+- [x] `.gitignore`、目录结构、demo 入口 HTML
+- [x] 安装依赖（cesium 1.107.2、vite、vite-plugin-cesium、vite-plugin-dts、typescript）
+
+## 阶段 1：数据标准与 DataManager
+- [x] 定义 `TargetData` / 轨迹点 `TrackPoint` 数据标准（统一口径）
+- [x] `DataManager.setData` 全量、`applyIncremental` 增量差分
+- [x] 坐标预处理 + `onPointsDirty` 脏事件派发
+
+## 阶段 2：核心包装实例与版本适配
+- [x] `CesiumAdapter` 封装 1.107.2~1.128.0 版本敏感 API
+- [x] `WrappedScene` 用 Proxy 代理原 Cesium 全部方法并叠加框架能力
+- [x] `index.ts` 导出 `createMultiTargetScene`
+
+## 阶段 3：节点管理与八叉树
+- [x] `Node` 单节点逻辑态（逻辑位/渲染位/运动状态/交互态）
+- [x] `Octree` 空间索引（插入/更新/删除/范围与射线查询）
+- [x] `NodeManager` 维护节点集合、消费 dirty 事件、投影 RenderItem
+
+## 阶段 4：对象池与分帧调度
+- [x] 通用 `ObjectPool`（容量 ~5000，借/还/复用）
+- [x] `FrameScheduler` 分帧计算（大批量计算切片到多帧）
+- [x] `MotionLoop` 帧循环驱动（固定 FPS）
+
+## 阶段 5：三级 LOD 渲染
+- [x] `InstanceManager` RenderItem 归一与分桶
+- [x] `PointRenderer`（PointPrimitiveCollection 点模式 + 动态图集）
+- [x] `InstancedModelRenderer`（低模实例化合批）
+- [x] `AnimatedModelRenderer`（高模动画对象池承载）
+- [x] `RenderManager` 按 LOD/renderKind 分发
+
+## 阶段 6：预测与平滑渲染
+- [x] `Predictor` 3 秒预测窗口（低/高速分类外推、垂直速率 clamp）
+- [x] 渲染位趋同 blend（按剩余时间比例拉拢，航向 slerp）
+- [x] 无新包时按运动学继续外推
+
+## 阶段 7：射线拾取与交互
+- [x] `Picker` 八叉树 + 射线拾取
+- [x] 禁用 Cesium 原生左键查找
+- [x] 选中/悬停优先抢占动画池
+
+## 阶段 8：相机分级与合并显示
+- [x] 相机高度分级（逻辑缩放乘子 + 高空总开关隐藏模型）
+- [x] 基于八叉树聚类的密级船舶合并显示
+
+## 阶段 9：Demo 与联调验证
+- [x] demo 页面 + 模拟数据源（无人机 2500 + 船舶 800，每秒推权威增量）
+- [x] 验证：tsc 类型检查通过 / dev server 200 / 入口转译正常 / 库构建产物完整
+- [ ] 浏览器可视化复核（合批不卡 / 预测平滑 / LOD 切换 / 拾取选中）— 待本地 `npm run dev` 人工确认
+
+## 阶段 10：文档与发布
+- [x] 补全 `README.md` 使用说明与 API 文档
+- [x] 提交并推送 Gitee