u-space 0.0.27 → 0.0.29

package/docs/changelog.md

@@ -4,6 +4,36 @@
 
 ### 变更
 
+- **u-manager breaking** — `SemanticModelInstancedLayer` 移除旧的 `addSemanticBatch()` 公开入口，改为 `reserveSemanticBatch()`、`addSemanticInstance()` / `addSemanticInstances()`、`getSemanticInstanceById()`、`removeSemanticInstance()` / `removeSemanticInstances()`、`removeSemanticBatch()` 和 `clearSemanticBatches()`，支持运行时实例新增/删除、按 URL batch 的 capacity 预分配与扩容；`removeSemanticInstances()` 支持直接传单个字符串 `semanticId`，并且 layer 内部不再从 `instance.userData` 扫描 ID。
+- **u-manager breaking** — `SemanticInstanceObject` 新增独立身份字段 `semanticId`、`semanticKind`、`semanticName` 和 `setSemanticIdentity()`；Scene / Facility instancing 的查询、删除和 raycast remap 都使用这些字段，`userData` 只保留原始业务元数据。
+- **u-manager breaking** — `SemanticGroup`、`BuildingGroup` 和 `FloorMesh` 的 building/floor/facility 索引统一读取对象独立 `semanticId` 或显式传入的别名，不再把 `userData.id`、`userData.semanticId`、`userData.facilityId` 自动注册成查询 ID；`SemanticModelInstancedLayer` 会拒绝重复 `semanticId` 的新增实例，并在身份字段变化后按需刷新 id 索引。
+- **u-manager** — `SemanticInstanceObject` 新增对象级 `boundingBox`、`boundingSphere`、`computeBoundingBox()` 和 `computeBoundingSphere()`，`SceneInstanceObject`、`FacilityInstanceObject` 以及楼层语义代理可直接传给 `viewer.controls.flyToObject()`。
+- **u-manager** — `SemanticModelInstancedLayer` 的内部实例矩阵同步改为 WebGPU storage instanced buffer 路径，运行时新增或移动实例后会在下一帧立即同步 matrix；外部仍通过修改 `SemanticInstanceObject` transform 和 dirty sync 使用，不需要直接写内部 `InstancedMesh.instanceMatrix`。
+- **u-manager** — `SemanticGroup` 新增 `getDefaultFacilityLayer()`，`SceneLoader.loadAsync()` 返回的 `SceneGroup` 新增 `sceneLayer` / `getDefaultSceneLayer()`，外部可直接获取默认 Facilities 和场景模型合批层。
+- **docs/mcp** — 更新 u-manager 文档、Examples Guide、LLM 索引和 MCP 检索说明，推荐通过 `viewer.controls.flyToObject()` 飞向语义实例；`getSemanticBoundingBox(target, true)` 保留给手动合并或调整世界包围盒的场景。
+
+## 0.0.28
+
+### 新增
+
+- **u-manager** — 新增 `UManagerLoader` 一体化入口，可同时加载 `SemanticLoader` 和 `SceneLoader`，返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`，并复用 semantic id 去重避免重复建筑/设备。
+- **examples/docs/mcp** — 新增 `examples/test_umanager_loader.html`，演示 `UManagerLoader` 一次加载语义楼层、Facilities 和非语义场景树，并补充 Examples Guide 与 MCP 检索入口。
+
+### 变更
+
+- **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 两套特殊分支。
+- **u-manager loader** — `SceneLoader` 不再解析场景树里的 `AREA`、`FLOOR`、`ROOM` 语义面；楼层、区域和房间统一由 `SemanticLoader` / `SemanticGroup` 处理，避免同一语义对象在组合加载时重复出现。
+
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.28`，Vercel 部署会继续按 `package.json` 注入当前版本。
+
+## 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`。
@@ -12,11 +42,15 @@
 - **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` 通过 `objectManager.getById()` + `controls.flyToObject()` 飞向单个 path-instanced 场景模型、`FacilityInstanceObject` 通过 `getFacilityBoundingBox()` + `controls.flyToBox()` 飞向单个设备的示例与 MCP 检索说明。
+- **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
 
 ### 修复
@@ -38,17 +72,17 @@
 
 ### 新增
 
-- **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.26`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.26` 作为直接托管 `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.28`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.28` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -54,7 +54,37 @@
 - 使用相机动画（`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`，避免建筑、楼层或设备重复加载。
+- 通过 `root.semanticGroup.getDefaultFacilityLayer()` 和 `root.sceneGroup.getDefaultSceneLayer()` 直接获取默认设备合批层和场景模型合批层。
+- 通过 `viewer.objectManager` 获取 `SceneInstanceObject` 和 `FacilityInstanceObject`，再直接使用 `viewer.controls.flyToObject()` 飞向单个实例。
+- 使用 `setSemanticHighlight()`、`setSemanticVisible()`、`setSemanticOpacity()` 等统一 API 控制实例，不需要关心底层是合并几何、`InstancedMesh` 还是 fallback `Model`。
+- 示例把 `viewer`、`loader`、`root`、`semanticGroup`、`sceneGroup`、`facilityLayer`、`sceneLayer`、`sceneInstances` 和 `facilities` 暴露到 `window.uManagerExample`，方便在控制台调试。
+
+## 6. `test_umanager_dynamic_instances.html`：运行时动态实例
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_umanager_dynamic_instances.html)
+
+该示例把运行时实例新增、删除、恢复和按 ID 查询拆到独立场景中，避免和 `UManagerLoader` 的一体化加载流程混在一起。
+
+### 核心要点：
+
+- 创建 `SceneInstancedLayer` 并调用 `reserveSemanticBatch(url, template, capacity)` 预分配容量。
+- 通过 `SceneInstanceObject.setSemanticIdentity({ id, kind, name })` 设置实例独立身份字段，不依赖 `userData` 参与 layer 内部索引。
+- 同一个 layer 内 `semanticId` 必须唯一；重复 ID 的新增会返回 `false`，加入后修改身份字段会在下一次按 ID 查询时刷新索引。
+- 使用 `addSemanticInstances()` 批量新增实例，使用 `removeSemanticInstance(id)` / `removeSemanticInstances(id)` 按完整 `semanticId` 删除实例。
+- 使用 `getSemanticInstanceById(id)` 快速获取实例，返回对象可直接用于 `setSemanticHighlight()` 和 `viewer.controls.flyToObject()`。
+- 示例把 `viewer`、`layer`、`template`、`allInstances` 和 `removedInstances` 暴露到 `window.dynamicInstanceExample`。
+
+## 7. `test_model_animation.html`：模型内置动画
 
 [在线演示](https://u-space-phi.vercel.app/examples/test_model_animation.html)
 
@@ -68,7 +98,7 @@
 - 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
 - 使用 `model.stopAnimation()` 停止动画播放。
 
-## 6. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
+## 8. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
 
 该示例演示了如何在 3D 场景中叠加渲染 HTML 元素，展示三种 CSS 渲染模式的效果差异。
 
@@ -80,7 +110,7 @@
 - CSS2.5D 和 CSS3D 对象需要设置 `scale`（通常 `0.01`），因为 HTML 元素的像素尺寸远大于 3D 世界单位。
 - 渲染器采用懒加载，仅在首次创建对应类型对象时初始化。
 
-## 7. `test_postprocessing.html`：后处理效果
+## 9. `test_postprocessing.html`：后处理效果
 
 该示例演示了 `RenderPipeline` 的内置后处理功能，包括 Bloom、SSGI、TRAA 以及自定义后处理组合器。
 
@@ -94,7 +124,7 @@
 - 使用 `viewer.renderPipeline.setOutputComposer()` 自定义后处理链（示例中实现了灰度滤镜）。
 - 使用 `setOutputComposer(null)` 恢复默认渲染管线。
 
-## 8. `test_viewer_utils.html`：Viewer 工具方法
+## 10. `test_viewer_utils.html`：Viewer 工具方法
 
 该示例演示了 `Viewer` 新增的便捷方法：截图导出、背景切换、雾效控制和阴影开关。
 
@@ -106,7 +136,7 @@
 - 使用 `viewer.enableShadow()` / `viewer.disableShadow()` 控制阴影渲染。
 - 使用 `viewer.resize(width, height)` 手动触发尺寸更新。
 
-## 9. `test_camera_controls.html`：CameraControls 增强方法
+## 11. `test_camera_controls.html`：CameraControls 增强方法
 
 该示例演示了 `CameraControls` 的飞行定位、视角存取、锁定和二三维切换功能。
 
@@ -118,7 +148,7 @@
 - 使用 `viewer.controls.lock()` / `unlock()` 锁定或解锁相机控制。
 - 使用 `viewer.controls.setViewMode('2d')` / `setViewMode('3d')` 在二三维视图间切换。
 
-## 10. `test_object_manager.html`：ObjectManager 增强方法
+## 12. `test_object_manager.html`：ObjectManager 增强方法
 
 该示例演示了 `ObjectManager` 的显隐控制、孤立显示、透明度设置、包围盒查询和过滤功能。
 
@@ -130,7 +160,7 @@
 - 使用 `viewer.objectManager.getBoundingBox()` 查询所有对象的包围盒。
 - 使用 `viewer.objectManager.filter(predicate)` 按条件过滤对象。
 
-## 11. `test_material_effects.html`：MaterialEffects 增强效果
+## 13. `test_material_effects.html`：MaterialEffects 增强效果
 
 该示例演示了材质效果系统的线框、半透明、X 光和淡入淡出功能。
 
@@ -142,7 +172,7 @@
 - 使用 `MaterialEffects.fadeOut(object)` / `fadeIn(object)` 执行淡入淡出动画。
 - 使用 `MaterialEffects.removeHighlightColor(object)` 恢复原始材质状态。
 
-## 12. `test_selection.html`：Selection 选择系统
+## 14. `test_selection.html`：Selection 选择系统
 
 该示例演示了对象选择系统的单选和框选功能。
 
@@ -153,7 +183,7 @@
 - 使用 `selection.enableBoxSelection()` 开启鼠标框选模式。
 - 框选模式下可配合 `viewer.controls.lock()` 避免框选与相机旋转冲突。
 
-## 13. `test_measure.html`：MeasureTool 测量工具
+## 15. `test_measure.html`：MeasureTool 测量工具
 
 该示例演示了 3D 场景中的距离、面积和角度测量。
 
@@ -164,7 +194,7 @@
 - 使用 `measureTool.measureAngle(pointA, vertex, pointC)` 测量夹角。
 - 测量结果以可视化线条渲染到场景中，返回的 `MeasureResult` 包含数值和单位。
 
-## 14. `test_annotation.html`：AnnotationManager 标注管理
+## 16. `test_annotation.html`：AnnotationManager 标注管理
 
 该示例演示了 3D 标注的创建、更新和管理，配合 `CSSRenderer` 实现 HTML 浮动标签。
 
@@ -176,7 +206,7 @@
 - 使用 `updateContent()` 动态更新标注内容，`updatePosition()` 移动标注位置。
 - 使用 `hideAll()` / `showAll()` 批量控制标注显隐。
 
-## 15. `test_clipping.html`：ClippingTool 剖切工具
+## 17. `test_clipping.html`：ClippingTool 剖切工具
 
 该示例演示了剖切面的创建和实时调整。
 
@@ -187,7 +217,7 @@
 - 使用滑块通过 `clippingTool.setPlaneConstant()` 实时调整剖切位置。
 - 使用 `showHelper()` / `hideHelper()` 切换剖切面可视化辅助。
 
-## 16. `test_lights.html`：LightManager 灯光管理
+## 18. `test_lights.html`：LightManager 灯光管理
 
 该示例演示了灯光管理器的灯光预设和 Helper 可视化功能。
 
@@ -198,7 +228,7 @@
 - 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
 - 每种预设会自动清除旧灯光并创建新的灯光组合。
 
-## 17. `test_fire.html`：WebGPU 体积火焰
+## 19. `test_fire.html`：WebGPU 体积火焰
 
 该示例演示了 `u-space/plugins/fire` 的 `FireEffect` 插件，封装 Three.js 官方体积火焰示例，在独立 volumetric pass 中模拟火焰和烟雾后叠加到主场景。
 

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.26'
+console.log(version); // e.g. '0.0.28'
 
 // 也可以通过全局变量访问
 console.log(window.__USPACE__.version);

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` 的 `SceneLoader` 语义去重与 path-based model instancing、`SceneInstanceObject` 场景模型引用、`SceneInstancedLayer` 批量渲染层、`SemanticLoader`、`SemanticSceneGroup`、`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 接入方式。
+`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,18 +84,26 @@ export const codingAgent = new Agent({
 | `find_examples` | 查找示例和用法相关文档 |
 | `get_changelog` | 读取更新日志 |
 
+## 示例检索
+
+MCP 文档索引包含 `examples/test_umanager_loader.html` 和 `examples/test_umanager_dynamic_instances.html` 的说明。检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载语义楼层、Facilities 和非语义场景树的示例入口，以及 `window.uManagerExample` 控制台调试对象说明；检索 `dynamic instances`、`getSemanticInstanceById` 或 `test_umanager_dynamic_instances` 可以找到运行时新增、删除、恢复和按 ID 查询 instanced 语义实例的示例。
+
 ## u-manager 检索范围
 
-MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 SceneLoader、SceneInstanceObject、SceneInstancedLayer 和 Facilities 详细 API。客户端可以直接检索以下关键词：
+MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 UManagerLoader、SemanticInstanceObject、SceneLoader、SceneInstanceObject、SceneInstancedLayer 和 Facilities 详细 API。客户端可以直接检索以下关键词：
 
 | 关键词 / API | 可检索内容 |
 | :----------- | :--------- |
-| `SceneLoader` | 场景树加载、语义 `ID` 去重、重复 3D 模型按 `path` 自动合并、unsupported template 回退普通 `Model`。 |
-| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、显隐、颜色、透明度、包围盒、`objectManager.getById()` + `controls.flyToObject()` 飞向单模型，以及事件目标。 |
-| `SceneInstancedLayer` | `SceneLoader` 内部批量渲染层、`BundleGroup` batch、dirty-driven instance buffer 同步、raycast hit remap。 |
-| `FacilityInstanceObject` | 楼层下的 instanced 设备引用、`objectManager.getById()` 全局检索、`getFacilityBoundingBox()` + `controls.flyToBox()` 飞向单设备、单设备显隐、颜色、透明度和事件目标。 |
-| `FacilityInstancedLayer` | `SemanticSceneGroup.facilityLayer`、`addFacilityBatch()`、batch 创建条件、`setInstanceCulling()`、动态 Facilities batch、可选按相机视锥压缩 active instances、可选 `minScreenRadius` 屏幕尺寸裁剪、dirty-driven instance buffer 同步和 raycast hit remap。 |
-| `Facilities` | `SemanticLoader` 解析、`FloorMesh.getFacilityById()`、`SemanticSceneGroup.setFacilityOpacity()`、普通 `Model` fallback 与 scene-level instancing 的差异。 |
+| `UManagerLoader` | 同时加载 `SemanticLoader` 和 `SceneLoader`、自动复用 semantic id 去重、返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`；可通过 `semanticGroup.getDefaultFacilityLayer()` 和 `sceneGroup.getDefaultSceneLayer()` 直接访问默认合批层。 |
+| `SemanticInstanceObject` | 统一语义实例 API：独立字段 `semanticId` / `semanticKind` / `semanticName`、`setSemanticIdentity()`、`setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()`、`getSemanticBoundingBox()`、`setSemanticHighlight()`，以及对象级 `boundingBox` / `boundingSphere` / `computeBoundingBox()` / `computeBoundingSphere()`，覆盖楼层多边形、Facilities、SceneLoader path instances 和 fallback Model wrapper，可直接用于 `controls.flyToObject()`。 |
+| `SemanticModelInstancedLayer` | `SceneInstancedLayer` 与 `FacilityInstancedLayer` 的共享实现：模板 mesh 收集、合法 material groups、多材质 instancing、`getSemanticInstances()`、`getSemanticInstanceById()`、运行时实例新增/删除、capacity 预分配与扩容、重复 `semanticId` 拒绝加入、身份字段变化后按需刷新 id 索引、dirty-driven buffer sync、transform 变化后渲染前同步 instance matrix、raycast hit remap 和可选相机实例裁剪；内部索引使用实例独立字段，不依赖 `userData`。 |
+| `SceneLoader` | 场景树加载、语义 `ID` 去重、返回 `SceneGroup`、重复 3D 模型按 `path` 自动合并、unsupported template 回退普通 `Model`。 |
+| `SceneGroup` | `SceneLoader.loadAsync()` 返回根组，保留原始场景树层级，并通过 `sceneLayer` / `getDefaultSceneLayer()` 暴露默认 `SceneInstancedLayer`。 |
+| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、`semanticKind = 'SceneInstances'`、`setSemanticVisible()`、`setSemanticColor()`、`resetSemanticColor()`、`setSemanticOpacity()`、`getSemanticColor()`、`getSemanticOpacity()`、`setSemanticHighlight()`、`clearSemanticHighlight()`、对象级包围盒缓存 + `controls.flyToObject()` 飞向单模型、dirty 监听和事件目标。 |
+| `SceneInstancedLayer` | `SceneLoader` 内部批量渲染层、共享 `SemanticModelInstancedLayer`、dirty-driven instance buffer 同步、raycast hit remap。 |
+| `FacilityInstanceObject` | 楼层下的设备引用、`objectManager.getById()` 全局检索、对象级包围盒缓存 + `controls.flyToObject()` 飞向单设备、统一 `setSemantic*` 控制、fallback `Model` wrapper 和事件目标。 |
+| `FacilityInstancedLayer` | `SemanticGroup.facilityLayer` / `SemanticGroup.getDefaultFacilityLayer()`、`getSemanticInstances()`、`getSemanticInstanceById()`、`reserveSemanticBatch()`、`addSemanticInstance()` / `addSemanticInstances()`、`removeSemanticInstance()` / `removeSemanticInstances()`（支持单个 `semanticId` 字符串）、`removeSemanticBatch()`、`clearSemanticBatches()`、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；`SemanticGroup` / `BuildingGroup` / `FloorMesh` 查询使用对象 `semanticId` 或显式别名，不扫描 `userData` ID。 |
 
 ## fire 检索范围
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",

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;
-}