u-space 0.0.26 → 0.0.28

package/docs/api-tools.md

@@ -221,7 +221,7 @@ annotationManager.add('label-01', {
 | `labelOffset`    | `{x, y, z}`              | `{0, 2, 0}` | 标签相对锚点的偏移。   |
 | `showLeaderLine` | `boolean`                | `true`      | 是否显示引线。         |
 | `lineColor`      | `ColorRepresentation`    | `0xffffff`  | 引线颜色。             |
-| `labelStyle`     | `Partial<CSSStyleDeclaration>` | —      | 自定义 CSS 样式。      |
+| `labelStyle`     | `AnnotationLabelStyle` | —      | 自定义 CSS 样式。      |
 
 ### `addText(text, position, options?)`
 

package/docs/changelog.md

@@ -2,6 +2,35 @@
 
 ## 未发布
 
+- **u-manager** — 新增 `UManagerLoader` 一体化入口，可同时加载 `SemanticLoader` 和 `SceneLoader`，返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`，并复用 semantic id 去重避免重复建筑/设备。
+- **u-manager breaking** — `SceneInstanceObject`、`FacilityInstanceObject` 和楼层多边形语义统一到 `SemanticInstanceObject` API：使用 `setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()`、`getSemanticBoundingBox()` 等方法，不再使用 scene/facility 专属实例方法。
+- **u-manager** — 新增共享 `SemanticModelInstancedLayer`，`SceneInstancedLayer` 和 `FacilityInstancedLayer` 共用同一套模型模板 instancing、material groups、多材质、dirty sync、raycast remap 和 fallback wrapper 逻辑。
+- **ObjectManager / MaterialEffects** — 对语义实例的显隐、透明度和高亮控制统一识别 `SemanticInstanceObject`，不再维护 SceneInstance/FacilityInstance 两套特殊分支。
+- **examples/docs/mcp** — 新增 `examples/test_umanager_loader.html`，演示 `UManagerLoader` 一次加载语义楼层、Facilities 和非语义场景树，并补充 Examples Guide 与 MCP 检索入口。
+
+## 0.0.27
+
+### 变更
+
+- **u-manager semantics** — `FacilityInstancedLayer` 的相机逐实例裁剪改为显式开启：默认不再按当前相机视锥或 `minScreenRadius` 压缩 active instances，避免相机距离影响设备显隐；需要性能压缩时可通过 `setInstanceCulling({ enabled: true })` 开启。
+- **u-manager semantics** — `FacilityInstancedLayer` 使用动态 `Group` 包裹 Facilities `InstancedMesh` batch，避免 Three.js WebGPU render bundle 缓存跳过子 mesh 的渲染前同步；`hideAllFacilities()` 后再 `showAllFacilities()` 不会复用过期 active instance 状态。
+- **u-manager semantics** — `FacilityInstancedLayer` 支持合法 `material[]` + `geometry.groups` 的设备模板进入 instancing；只有 groups 缺失或材质索引非法的多材质 Mesh 才回退为普通 `Model`。
+- **u-manager semantics** — Facilities instancing 会在相机矩阵、投影矩阵或 viewport 高度变化时重新压缩当前帧实例；设备显隐、颜色、透明度和 `planish('Facilities')` / `unplanish('Facilities')` 改变 transform 时刷新 instance data。
+- **u-manager semantics** — 全部设备隐藏或透明度为 0 时，`FacilityInstancedLayer` 会关闭空的内部 `InstancedMesh`；通过 `showAllFacilities()` 或单设备 API 恢复时会重新加入渲染同步。
+- **fire 插件** — 新增 `FireEffect`，封装 Three.js 官方 `webgpu_volume_fire` 体积火焰示例，支持 WebGPU 3D 流体模拟、烟雾散射、动态光照、体积阴影、output effect 叠加和 `cameraChange` 相机切换同步。
+- **u-manager loader** — `SceneLoader` 默认读取同路径 `db/semantic_model.json` 并按语义 `ID` 跳过重复场景树节点，支持与 `SemanticLoader` 同时加载。
+- **u-manager loader** — `SceneLoader` 默认按模型 `path` 合并重复静态 3D 节点，通过 `SceneInstancedLayer` 批量渲染，同时保留 `SceneInstanceObject` 逻辑对象用于单模型 ID 检索、显隐、颜色、透明度、包围盒和事件派发。
+- **docs/mcp** — 补充 `SceneInstanceObject` 和 `FacilityInstanceObject` 通过 `objectManager.getById()` + `getSemanticBoundingBox()` + `controls.flyToBox()` 飞向单个实例的示例与 MCP 检索说明。
+- **ObjectManager / MaterialEffects** — `setOpacity()`、`show()` / `hide()`、`isolate()`、`showAll()` 以及 `highlightColor()` / `removeHighlightColor()` 支持 `SceneInstanceObject` 的 per-instance 控制。
+- **u-manager loader** — `SceneLoader` 创建的根组、`GROUP` 和 `STUB` 节点改为 `BaseGroup`，隐藏后可通过对象自身 `raycast()` 返回值阻止子级继续参与递归射线检测。
+- **Viewer** — 默认使用 Three.js `reversedDepthBuffer` 替代 `logarithmicDepthBuffer`，减少 WebGPU 顶视角多层透明场景的 fragment 压力，同时保留远距离深度精度。
+
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.27`，Vercel 部署会继续按 `package.json` 注入当前版本。
+
+## 0.0.26
+
 ### 修复
 
 - **u-manager semantics** — `FloorMesh.planish()` 会在压平后的语义实例和 Facilities 上加入稳定的轻微 Y 偏移，减少门、墙等重叠薄片之间的共面闪烁。
@@ -13,21 +42,25 @@
 - **MaterialEffects** — 高亮、呼吸色、线框和淡入淡出效果支持材质数组，确保多材质 Mesh 和 `FloorMesh` 双材质通道都能正确应用并恢复材质状态。
 - **docs/mcp** — 补充 Facilities auto instancing 的动态材质透明度、包围盒视锥裁剪、`controls.flyToBox()` 飞向设备，以及多材质 fallback 对颜色/透明度 override 的支持说明。
 
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.26`，Vercel 部署会继续按 `package.json` 注入当前版本。
+
 ## 0.0.25
 
 ### 新增
 
-- **u-manager semantics** — 新增 `SemanticSceneGroup`，作为单次 `SemanticParser` 解析结果的顶层容器；`SemanticLoader.loadAsync()` / `SemanticParser.parseAsync()` 直接返回完整语义场景。
-- **u-manager semantics** — `SemanticSceneGroup` 新增 `getBuildingById(id)`，支持按语义数据里的 `Building.ID` 获取建筑。
-- **u-manager semantics** — `SemanticSceneGroup` 和 `BuildingGroup` 的建筑/设备 ID 查询改为内部 `Map` 索引，并通过楼层设备索引版本自动同步，避免每次查询扫描数组。
-- **u-manager semantics** — `FloorMesh.planish()` / `unplanish()`、`BuildingGroup.planishFloors()` / `unplanishFloors()` 和 `SemanticSceneGroup.planishFloors()` / `unplanishFloors()` 会把所有合并语义实例和 Facilities 都按包围盒贴到楼层平面，而不是围绕实例自身基点压缩。
-- **u-manager semantics** — 新增 scene-level Facilities auto instancing：同模型 URL 的静态设备会合并到 `SemanticSceneGroup.facilityLayer` 的 `InstancedMesh` batch，同时保留楼层下的设备引用用于检索、显隐、颜色和透明度控制；带动画、骨骼、morph target 或多材质 Mesh 的设备自动回退为普通 `Model`。
-- **u-manager semantics** — `SemanticSceneGroup`、`BuildingGroup` 和 `FloorMesh` 新增单个设备控制 API：`getFacilityById()`、`showFacility()`、`hideFacility()`、`setFacilityVisible()`、`setFacilityColor()`、`resetFacilityColor()` 和 `setFacilityOpacity()`，同时支持普通设备模型和 scene-level instanced 设备引用。
-- **docs/mcp** — 补充 Facilities auto instancing 的材质透明度行为、`resetFacilityColor()` 语义，以及多材质 fallback 对颜色/透明度 override 的限制说明。
+- **u-manager semantics** — 新增 `SemanticGroup`，作为单次 `SemanticParser` 解析结果的顶层容器；`SemanticLoader.loadAsync()` / `SemanticParser.parseAsync()` 直接返回完整语义场景。
+- **u-manager semantics** — `SemanticGroup` 新增 `getBuildingById(id)`，支持按语义数据里的 `Building.ID` 获取建筑。
+- **u-manager semantics** — `SemanticGroup` 和 `BuildingGroup` 的建筑/设备 ID 查询改为内部 `Map` 索引，并通过楼层设备索引版本自动同步，避免每次查询扫描数组。
+- **u-manager semantics** — `FloorMesh.planish()` / `unplanish()`、`BuildingGroup.planishFloors()` / `unplanishFloors()` 和 `SemanticGroup.planishFloors()` / `unplanishFloors()` 会把所有合并语义实例和 Facilities 都按包围盒贴到楼层平面，而不是围绕实例自身基点压缩。
+- **u-manager semantics** — 新增 scene-level Facilities auto instancing：同模型 URL 的静态设备会合并到 `SemanticGroup.facilityLayer` 的 `InstancedMesh` batch，同时保留楼层下的设备引用用于检索、显隐、颜色和透明度控制；带动画、骨骼、morph target 或多材质 Mesh 的设备自动回退为普通 `Model`。
+- **u-manager semantics** — `SemanticGroup`、`BuildingGroup` 和 `FloorMesh` 新增 `getFacilityById()` 设备检索，返回的 `FacilityInstanceObject` 可通过统一 `setSemanticVisible()`、`setSemanticColor()`、`resetSemanticColor()` 和 `setSemanticOpacity()` 控制普通设备模型或 scene-level instanced 设备引用。
+- **docs/mcp** — 补充 Facilities auto instancing 的材质透明度行为、`resetSemanticColor()` 语义，以及多材质 fallback 对颜色/透明度 override 的限制说明。
 
 ### 修复
 
-- **u-manager semantics** — 修复 scene-level instanced Facilities 的点击和指针事件派发：射线命中会映射回楼层下的 `FacilityInstanceObject`，并继续冒泡到所属 `FloorMesh`、`BuildingGroup` 和 `SemanticSceneGroup`。
+- **u-manager semantics** — 修复 scene-level instanced Facilities 的点击和指针事件派发：射线命中会映射回楼层下的 `FacilityInstanceObject`，并继续冒泡到所属 `FloorMesh`、`BuildingGroup` 和 `SemanticGroup`。
 - **u-manager semantics** — `FacilityInstancedLayer` 继承 `BaseGroup`，避免 `facilityLayer.visible = false` 后内部 `InstancedMesh` 仍参与射线检测并触发隐藏设备点击事件。
 - **u-manager semantics** — 移除语义设备解析里的 `sid` 检索和注册逻辑；Facilities 只按 `Facility.ID` 以及显式传入的别名进入楼层索引和 `viewer.objectManager`。
 

package/docs/examples-guide.md

@@ -4,7 +4,7 @@
 
 ## 运行方式与版本
 
-示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.25`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.25` 作为直接托管 `examples/` 时的 fallback。
+示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.27`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.27` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -54,7 +54,21 @@
 - 使用相机动画（`VisionsLoader` 和 `VisionsParser`）在场景中编排预定义的飞行路径。
 - 获取复杂的节点材质，并自定义 WebGPU 专属的 TSL（Three Shading Language）节点，如 `TSLEffects.fluid()`。
 
-## 5. `test_model_animation.html`：模型内置动画
+## 5. `test_umanager_loader.html`：UManagerLoader 一体化加载
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_umanager_loader.html)
+
+该示例演示通过 `UManagerLoader` 在同一个路径下同时加载语义楼层、Facilities 和非语义场景树内容。加载结果会返回一个 `UManagerSceneGroup`，其中 `semanticGroup` 指向 `SemanticGroup`，`sceneGroup` 指向非语义场景组。
+
+### 核心要点：
+
+- 使用 `UManagerLoader.setPath()` 配置场景根目录，并通过一次 `loadAsync()` 完成 `SemanticLoader` + `SceneLoader` 组合加载。
+- `SceneLoader` 会自动跳过语义文件中已存在的 `id`，避免建筑、楼层或设备重复加载。
+- 通过 `viewer.objectManager` 获取 `SceneInstanceObject` 和 `FacilityInstanceObject`，再使用统一 `getSemanticBoundingBox()` + `viewer.controls.flyToBox()` 飞向单个实例。
+- 使用 `setSemanticHighlight()`、`setSemanticVisible()`、`setSemanticOpacity()` 等统一 API 控制实例，不需要关心底层是合并几何、`InstancedMesh` 还是 fallback `Model`。
+- 示例把 `viewer`、`loader`、`root`、`semanticGroup`、`sceneGroup`、`sceneInstances` 和 `facilities` 暴露到 `window.uManagerExample`，方便在控制台调试。
+
+## 6. `test_model_animation.html`：模型内置动画
 
 [在线演示](https://u-space-phi.vercel.app/examples/test_model_animation.html)
 
@@ -68,7 +82,7 @@
 - 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
 - 使用 `model.stopAnimation()` 停止动画播放。
 
-## 6. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
+## 7. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
 
 该示例演示了如何在 3D 场景中叠加渲染 HTML 元素，展示三种 CSS 渲染模式的效果差异。
 
@@ -80,7 +94,7 @@
 - CSS2.5D 和 CSS3D 对象需要设置 `scale`（通常 `0.01`），因为 HTML 元素的像素尺寸远大于 3D 世界单位。
 - 渲染器采用懒加载，仅在首次创建对应类型对象时初始化。
 
-## 7. `test_postprocessing.html`：后处理效果
+## 8. `test_postprocessing.html`：后处理效果
 
 该示例演示了 `RenderPipeline` 的内置后处理功能，包括 Bloom、SSGI、TRAA 以及自定义后处理组合器。
 
@@ -94,7 +108,7 @@
 - 使用 `viewer.renderPipeline.setOutputComposer()` 自定义后处理链（示例中实现了灰度滤镜）。
 - 使用 `setOutputComposer(null)` 恢复默认渲染管线。
 
-## 8. `test_viewer_utils.html`：Viewer 工具方法
+## 9. `test_viewer_utils.html`：Viewer 工具方法
 
 该示例演示了 `Viewer` 新增的便捷方法：截图导出、背景切换、雾效控制和阴影开关。
 
@@ -106,7 +120,7 @@
 - 使用 `viewer.enableShadow()` / `viewer.disableShadow()` 控制阴影渲染。
 - 使用 `viewer.resize(width, height)` 手动触发尺寸更新。
 
-## 9. `test_camera_controls.html`：CameraControls 增强方法
+## 10. `test_camera_controls.html`：CameraControls 增强方法
 
 该示例演示了 `CameraControls` 的飞行定位、视角存取、锁定和二三维切换功能。
 
@@ -118,7 +132,7 @@
 - 使用 `viewer.controls.lock()` / `unlock()` 锁定或解锁相机控制。
 - 使用 `viewer.controls.setViewMode('2d')` / `setViewMode('3d')` 在二三维视图间切换。
 
-## 10. `test_object_manager.html`：ObjectManager 增强方法
+## 11. `test_object_manager.html`：ObjectManager 增强方法
 
 该示例演示了 `ObjectManager` 的显隐控制、孤立显示、透明度设置、包围盒查询和过滤功能。
 
@@ -130,7 +144,7 @@
 - 使用 `viewer.objectManager.getBoundingBox()` 查询所有对象的包围盒。
 - 使用 `viewer.objectManager.filter(predicate)` 按条件过滤对象。
 
-## 11. `test_material_effects.html`：MaterialEffects 增强效果
+## 12. `test_material_effects.html`：MaterialEffects 增强效果
 
 该示例演示了材质效果系统的线框、半透明、X 光和淡入淡出功能。
 
@@ -142,7 +156,7 @@
 - 使用 `MaterialEffects.fadeOut(object)` / `fadeIn(object)` 执行淡入淡出动画。
 - 使用 `MaterialEffects.removeHighlightColor(object)` 恢复原始材质状态。
 
-## 12. `test_selection.html`：Selection 选择系统
+## 13. `test_selection.html`：Selection 选择系统
 
 该示例演示了对象选择系统的单选和框选功能。
 
@@ -153,7 +167,7 @@
 - 使用 `selection.enableBoxSelection()` 开启鼠标框选模式。
 - 框选模式下可配合 `viewer.controls.lock()` 避免框选与相机旋转冲突。
 
-## 13. `test_measure.html`：MeasureTool 测量工具
+## 14. `test_measure.html`：MeasureTool 测量工具
 
 该示例演示了 3D 场景中的距离、面积和角度测量。
 
@@ -164,7 +178,7 @@
 - 使用 `measureTool.measureAngle(pointA, vertex, pointC)` 测量夹角。
 - 测量结果以可视化线条渲染到场景中，返回的 `MeasureResult` 包含数值和单位。
 
-## 14. `test_annotation.html`：AnnotationManager 标注管理
+## 15. `test_annotation.html`：AnnotationManager 标注管理
 
 该示例演示了 3D 标注的创建、更新和管理，配合 `CSSRenderer` 实现 HTML 浮动标签。
 
@@ -176,7 +190,7 @@
 - 使用 `updateContent()` 动态更新标注内容，`updatePosition()` 移动标注位置。
 - 使用 `hideAll()` / `showAll()` 批量控制标注显隐。
 
-## 15. `test_clipping.html`：ClippingTool 剖切工具
+## 16. `test_clipping.html`：ClippingTool 剖切工具
 
 该示例演示了剖切面的创建和实时调整。
 
@@ -187,7 +201,7 @@
 - 使用滑块通过 `clippingTool.setPlaneConstant()` 实时调整剖切位置。
 - 使用 `showHelper()` / `hideHelper()` 切换剖切面可视化辅助。
 
-## 16. `test_lights.html`：LightManager 灯光管理
+## 17. `test_lights.html`：LightManager 灯光管理
 
 该示例演示了灯光管理器的灯光预设和 Helper 可视化功能。
 
@@ -197,3 +211,15 @@
 - 支持 4 种预设：`indoor`（室内）、`outdoor`（室外）、`studio`（摄影棚）、`warehouse`（仓库）。
 - 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
 - 每种预设会自动清除旧灯光并创建新的灯光组合。
+
+## 18. `test_fire.html`：WebGPU 体积火焰
+
+该示例演示了 `u-space/plugins/fire` 的 `FireEffect` 插件，封装 Three.js 官方体积火焰示例，在独立 volumetric pass 中模拟火焰和烟雾后叠加到主场景。
+
+### 核心要点：
+
+- 使用 `FireEffect` 创建 WebGPU 体积火焰、烟雾、扰动、动态点光源和体积阴影。
+- 通过 `position` 和 `size` 设置体积盒底部中心和烟雾扩散约束范围。
+- 默认使用 `TeapotGeometry(0.8, 28)` 作为 emitter；也可以传入业务 `Object3D` 和自定义 `emitterGeometry`。
+- 通过 `fire.update()` 实时调整 `fireIntensity`、`smokeLifespan`、`emitterRadius` 等参数。
+- 插件使用 RenderPipeline output effect 接入，不占用业务侧的 `setOutputComposer()`。

package/docs/getting-started.md

@@ -125,7 +125,7 @@ box.addEventListener('pointerleave', (e) => {
 
 ```typescript
 import { version } from 'u-space';
-console.log(version); // e.g. '0.0.25'
+console.log(version); // e.g. '0.0.27'
 
 // 也可以通过全局变量访问
 console.log(window.__USPACE__.version);

package/docs/index.md

@@ -56,6 +56,7 @@ features:
 | [curve-movement](./api-plugin-curve-movement) | 沿样条曲线移动相机或对象 |
 | [tracking-controls](./api-plugin-tracking-controls) | 相机跟随移动目标 |
 | [atmosphere](./api-plugin-atmosphere) | 天空背景、天空环境、太阳/月亮光照与阴影 |
+| [fire](./api-plugin-fire) | WebGPU 体积火焰、烟雾、湍流、动态光照与阴影 |
 | [object-controls](./api-plugin-object-controls) | 交互式移动、旋转、缩放 3D 对象 |
 | [topology-drawer](./api-plugin-topology-drawer) | 在场景任意表面交互式绘制拓扑路径图 |
 

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # u-space MCP
 
-`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括 `u-manager` 的 `SemanticLoader`、`SemanticSceneGroup`、`BuildingGroup`、`FloorMesh` 语义楼层 API、楼层 `Facilities` 设备检索与 scene-level auto instancing、设备显隐/颜色/透明度控制、电梯井/通风井语义体块，以及 atmosphere 插件的 `skyBackground()`、`skyEnvironment()` 和 RenderPipeline output effect 配置。
+`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括 `u-manager` 的 `UManagerLoader` 一体化加载入口、`SceneLoader` 语义去重与 path-based model instancing、统一 `SemanticInstanceObject` API、`SemanticModelInstancedLayer` 共享模型合批层、`SceneInstanceObject` 场景模型引用、`SceneInstancedLayer` 批量渲染层、`SemanticLoader`、`SemanticGroup`、`BuildingGroup`、`FloorMesh` 语义楼层 API、`FacilityInstanceObject` 设备引用、`FacilityInstancedLayer` scene-level batch 渲染层、Facilities auto instancing、camera-based active instance culling、dirty-driven instance sync、楼层 `Facilities` 设备检索与控制、电梯井/通风井语义体块，atmosphere 插件的 `skyBackground()`、`skyEnvironment()` 和 RenderPipeline output effect 配置，以及 fire 插件的 `FireEffect` WebGPU 体积火焰、烟雾、emitter、体积盒、动态光照和 output effect 接入方式。
 
 ## 安装与启动
 
@@ -84,6 +84,39 @@ export const codingAgent = new Agent({
 | `find_examples` | 查找示例和用法相关文档 |
 | `get_changelog` | 读取更新日志 |
 
+## 示例检索
+
+MCP 文档索引包含 `examples/test_umanager_loader.html` 的说明。检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载语义楼层、Facilities 和非语义场景树的示例入口，以及 `window.uManagerExample` 控制台调试对象说明。
+
+## u-manager 检索范围
+
+MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 UManagerLoader、SemanticInstanceObject、SceneLoader、SceneInstanceObject、SceneInstancedLayer 和 Facilities 详细 API。客户端可以直接检索以下关键词：
+
+| 关键词 / API | 可检索内容 |
+| :----------- | :--------- |
+| `UManagerLoader` | 同时加载 `SemanticLoader` 和 `SceneLoader`、自动复用 semantic id 去重、返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`。 |
+| `SemanticInstanceObject` | 统一语义实例 API：`setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()`、`getSemanticBoundingBox()`、`setSemanticHighlight()`，覆盖楼层多边形、Facilities、SceneLoader path instances 和 fallback Model wrapper。 |
+| `SemanticModelInstancedLayer` | `SceneInstancedLayer` 与 `FacilityInstancedLayer` 的共享实现：模板 mesh 收集、合法 material groups、多材质 instancing、dirty-driven buffer sync、raycast hit remap 和可选相机实例裁剪。 |
+| `SceneLoader` | 场景树加载、语义 `ID` 去重、重复 3D 模型按 `path` 自动合并、unsupported template 回退普通 `Model`。 |
+| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、`userData.semanticKind = 'SceneInstances'`、`setSemanticVisible()`、`setSemanticColor()`、`resetSemanticColor()`、`setSemanticOpacity()`、`getSemanticColor()`、`getSemanticOpacity()`、`setSemanticHighlight()`、`clearSemanticHighlight()`、`getSemanticBoundingBox()` + `controls.flyToBox()` 飞向单模型、dirty 监听和事件目标。 |
+| `SceneInstancedLayer` | `SceneLoader` 内部批量渲染层、共享 `SemanticModelInstancedLayer`、dirty-driven instance buffer 同步、raycast hit remap。 |
+| `FacilityInstanceObject` | 楼层下的设备引用、`objectManager.getById()` 全局检索、`getSemanticBoundingBox()` + `controls.flyToBox()` 飞向单设备、统一 `setSemantic*` 控制、fallback `Model` wrapper 和事件目标。 |
+| `FacilityInstancedLayer` | `SemanticGroup.facilityLayer`、`addSemanticBatch()`、batch 创建条件、`setInstanceCulling()`、动态 Facilities batch、可选按相机视锥压缩 active instances、可选 `minScreenRadius` 屏幕尺寸裁剪、dirty-driven instance buffer 同步和 raycast hit remap。 |
+| `Facilities` | `SemanticLoader` 解析、`FloorMesh.getFacilityById()`、`FacilityInstanceObject.setSemanticOpacity()`、普通 `Model` fallback wrapper 与 scene-level instancing 的一致 API。 |
+
+## fire 检索范围
+
+MCP 文档索引会同步 `docs/api-plugin-fire.md` 中的 FireEffect API、参数和示例。客户端可以直接检索以下关键词：
+
+| 关键词 / API | 可检索内容 |
+| :----------- | :--------- |
+| `FireEffect` | 插件创建、`enable()`、`update()`、`setEmitter()`、`reset()`、`disable()` 和 `dispose()`。 |
+| `fire` / `volumetric fire` | WebGPU 体积火焰、烟雾散射、curl noise、buoyancy、Jacobi pressure projection 和 raymarch 输出。 |
+| `emitterGeometry` / `emitterRadius` | 默认 `TeapotGeometry(0.8, 28)`、自定义 emitter 几何、业务 `Object3D` matrix 驱动和移动扰动半径。 |
+| `size` / `gridSize` | 体积盒世界范围、烟雾扩散边界和 3D 模拟网格尺寸。 |
+| `addOutputEffect` | `FireEffect` 通过 RenderPipeline output effect 叠加体积 pass，不占用业务 `setOutputComposer()`。 |
+| `keyLight` / `pointLight` | 体积阴影 spot light、跟随火焰核心的动态点光源和可关闭的内置光源。 |
+
 ## 包结构
 
 源码位于 `packages/u-space-mcp`。根目录只保留一个 MCP 发布入口；执行时会先递增 `u-space-mcp` 的 patch 版本，再从 `docs/*.md` 生成内置文档索引，编译 MCP 包，然后发布到 npm：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -62,9 +62,9 @@
     "3d-tiles-renderer": ">=0.4.28",
     "@takram/three-geospatial": ">=0.9.1",
     "@takram/three-atmosphere": ">=0.19.1",
-    "@types/three": ">=0.184.1",
+    "@types/three": ">=0.185.0",
     "camera-controls": ">=3.1.2",
-    "postprocessing": ">=6.39.1",
-    "three": ">=0.184.0"
+    "postprocessing": ">=6.39.2",
+    "three": ">=0.185.0"
   }
 }

package/dist/plugins/u-manager/semantics/objects/SemanticSceneGroup.d.ts

@@ -1,31 +0,0 @@
-import { type ColorRepresentation, type Object3D } from 'three/webgpu';
-import { BaseGroup } from 'u-space';
-import type { BuildingFacilityReference, BuildingGroup } from './BuildingGroup';
-import type { FloorMesh, FloorSemanticKind } from './FloorMesh';
-export declare class SemanticSceneGroup extends BaseGroup {
-    #private;
-    isSemanticSceneGroup: boolean;
-    type: string;
-    buildings: BuildingGroup[];
-    facilityLayer: Object3D | null;
-    constructor();
-    addBuilding(group: BuildingGroup): this;
-    getBuildingAt(index: number): BuildingGroup;
-    getBuildingById(id: string): BuildingGroup | undefined;
-    getBuildings(): BuildingGroup[];
-    removeBuilding(group: BuildingGroup): this;
-    get floorMeshes(): FloorMesh[];
-    setFacilityLayer(layer: Object3D | null): this;
-    showAllFacilities(): this;
-    hideAllFacilities(): this;
-    getFacilityById(id: string): Object3D<import("three").Object3DEventMap> | undefined;
-    setFacilityVisible(facility: BuildingFacilityReference, visible: boolean): this;
-    showFacility(facility: BuildingFacilityReference): this;
-    hideFacility(facility: BuildingFacilityReference): this;
-    setFacilityColor(facility: BuildingFacilityReference, color: ColorRepresentation): this;
-    resetFacilityColor(facility: BuildingFacilityReference): this;
-    setFacilityOpacity(facility: BuildingFacilityReference, opacity: number): this;
-    showAllFloors(): this;
-    planishFloors(kind?: FloorSemanticKind): this;
-    unplanishFloors(kind?: FloorSemanticKind): this;
-}