u-space 0.0.28 → 0.0.29

package/dist/plugins/u-manager/instances/SemanticInstanceObject.d.ts

@@ -1,4 +1,4 @@
-import { Box3, Color, Object3D, type ColorRepresentation } from 'three/webgpu';
+import { Box3, BufferGeometry, Color, Object3D, Sphere, type ColorRepresentation } from 'three/webgpu';
 import { BaseGroup } from 'u-space';
 export interface SemanticInstanceStyle {
     color: Color | null;
@@ -8,6 +8,11 @@ export interface SemanticInstanceStyle {
 export interface SemanticInstanceObjectOptions {
     boundsName?: string;
 }
+export interface SemanticInstanceIdentity {
+    id?: string | null;
+    kind?: string | null;
+    name?: string | null;
+}
 export declare const SEMANTIC_COLOR_MODE_NONE = 0;
 export declare const SEMANTIC_COLOR_MODE_OVERRIDE = 1;
 export declare const SEMANTIC_COLOR_MODE_TINT = 2;
@@ -15,10 +20,19 @@ export declare class SemanticInstanceObject extends BaseGroup {
     #private;
     isSemanticInstanceObject: boolean;
     type: string;
+    semanticId: string;
+    semanticKind: string;
+    semanticName: string;
+    geometry: BufferGeometry<import("three").NormalBufferAttributes, import("three").BufferGeometryEventMap>;
+    boundingBox: Box3 | null;
+    boundingSphere: Sphere | null;
     constructor(options?: SemanticInstanceObjectOptions);
+    setSemanticIdentity(identity: SemanticInstanceIdentity): this;
     setSemanticBounds(bounds: Box3): this;
     setSemanticRenderObject(object: Object3D | null): this;
     getSemanticRenderObject(): Object3D<import("three").Object3DEventMap> | null;
+    computeBoundingBox(): void;
+    computeBoundingSphere(): void;
     getSemanticBoundingBox(target?: Box3, world?: boolean): Box3;
     setSemanticVisible(visible: boolean): this;
     setSemanticColor(color: ColorRepresentation): this;

package/dist/plugins/u-manager/instances/SemanticModelInstancedLayer.d.ts

@@ -8,7 +8,7 @@ export interface SemanticInstanceCullingOptions {
 }
 export interface SemanticModelInstancedLayerOptions<T extends SemanticInstanceObject> {
     name?: string;
-    getBatchUserData?: (url: string, instances: T[]) => Record<string, unknown>;
+    semanticKind?: string;
     getHitUserData?: (instance: T, renderIndex: number) => Record<string, unknown>;
 }
 export declare class SemanticModelInstancedLayer<T extends SemanticInstanceObject = SemanticInstanceObject> extends BaseGroup {
@@ -16,7 +16,10 @@ export declare class SemanticModelInstancedLayer<T extends SemanticInstanceObjec
     isSemanticModelInstancedLayer: boolean;
     type: string;
     constructor(options?: SemanticModelInstancedLayerOptions<T>);
+    get semanticKind(): string;
     getSemanticInstances(): T[];
+    getSemanticInstanceById(id: string): T | undefined;
+    hasSemanticInstance(id: string): boolean;
     getInstanceCulling(): {
         enabled: boolean;
         frustum: boolean;
@@ -29,5 +32,11 @@ export declare class SemanticModelInstancedLayer<T extends SemanticInstanceObjec
     setSemanticOpacity(opacity: number): this;
     setSemanticHighlight(color: Parameters<SemanticInstanceObject['setSemanticHighlight']>[0], opacity: number, overwrite?: boolean): this;
     clearSemanticHighlight(): this;
-    addSemanticBatch(url: string, template: Object3D, instances: T[]): boolean;
+    reserveSemanticBatch(url: string, template: Object3D, capacity: number): boolean;
+    addSemanticInstance(url: string, template: Object3D, instance: T): boolean;
+    addSemanticInstances(url: string, template: Object3D, instances: T[]): boolean;
+    removeSemanticInstance(instanceOrId: T | string): boolean;
+    removeSemanticInstances(instancesOrIds: Iterable<T | string> | T | string): number;
+    removeSemanticBatch(url: string): boolean;
+    clearSemanticBatches(): this;
 }

package/dist/plugins/u-manager/loaders/SceneLoader.d.ts

@@ -1,6 +1,15 @@
-import { Group, Loader } from 'three/webgpu';
-import { Model, type Viewer } from 'u-space';
+import { Loader } from 'three/webgpu';
+import { Model, type Viewer, BaseGroup } from 'u-space';
+import { SceneInstancedLayer } from './SceneInstancedLayer';
 import type { ITreeData } from '../types';
+export declare class SceneGroup extends BaseGroup {
+    isSceneGroup: boolean;
+    type: string;
+    sceneLayer: SceneInstancedLayer | null;
+    constructor();
+    setSceneLayer(layer: SceneInstancedLayer | null): this;
+    getDefaultSceneLayer(): SceneInstancedLayer | null;
+}
 export declare class SceneLoader extends Loader {
     #private;
     viewer: Viewer;
@@ -18,7 +27,7 @@ export declare class SceneLoader extends Loader {
      * @param options
      * @returns
      */
-    loadAsync(): Promise<Group>;
+    loadAsync(): Promise<SceneGroup>;
     clearCache(): void;
     dispose(): void;
 }

package/dist/plugins/u-manager/loaders/UManagerLoader.d.ts

@@ -1,14 +1,14 @@
-import { Loader, type Group } from 'three/webgpu';
+import { Loader } from 'three/webgpu';
 import { BaseGroup, type Viewer } from 'u-space';
-import { SceneLoader } from './SceneLoader';
+import { SceneLoader, type SceneGroup } from './SceneLoader';
 import { SemanticLoader } from '../semantics/SemanticLoader';
 import type { SemanticGroup } from '../semantics';
 export declare class UManagerSceneGroup extends BaseGroup {
     isUManagerSceneGroup: boolean;
     type: string;
     semanticGroup: SemanticGroup;
-    sceneGroup: Group;
-    constructor(semanticGroup: SemanticGroup, sceneGroup: Group);
+    sceneGroup: SceneGroup;
+    constructor(semanticGroup: SemanticGroup, sceneGroup: SceneGroup);
 }
 export declare class UManagerLoader extends Loader {
     #private;

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

@@ -9,10 +9,18 @@ export declare class BuildingGroup extends BaseGroup {
     #private;
     isBuildingGroup: boolean;
     type: string;
+    semanticId: string;
+    semanticKind: string;
+    semanticName: string;
     floorMeshes: FloorMesh[];
     elevatorMeshes: ElevatorMesh[];
     ventMeshes: VentMesh[];
     constructor();
+    setSemanticIdentity(identity: {
+        id?: string | null;
+        kind?: string | null;
+        name?: string | null;
+    }): this;
     addFloor(mesh: FloorMesh): this;
     hasFloor(mesh: FloorMesh): boolean;
     getFloorAt(index: number): FloorMesh;

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

@@ -67,6 +67,9 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, FloorMeshMateria
     #private;
     isFloorMergedSemanticMesh: boolean;
     type: string;
+    semanticId: string;
+    semanticKind: string;
+    semanticName: string;
     pivot: Vector3;
     boundingBox: Box3 | null;
     boundingSphere: Sphere | null;
@@ -82,6 +85,11 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, FloorMeshMateria
     facilityObjects: SemanticInstanceObject[];
     facilityIndexVersion: number;
     constructor(entries: SemanticGeometryEntry[]);
+    setSemanticIdentity(identity: {
+        id?: string | null;
+        kind?: string | null;
+        name?: string | null;
+    }): this;
     planish(kind?: FloorSemanticKind): this;
     unplanish(kind?: FloorSemanticKind): this;
     get semanticCount(): number;

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

@@ -1,6 +1,6 @@
-import { type Object3D } from 'three/webgpu';
 import { BaseGroup } from 'u-space';
 import type { BuildingGroup } from './BuildingGroup';
+import type { FacilityInstancedLayer } from './FacilityInstancedLayer';
 import type { FloorMesh, FloorSemanticKind } from './FloorMesh';
 import type { SemanticInstanceObject } from '../../instances';
 export declare class SemanticGroup extends BaseGroup {
@@ -8,7 +8,7 @@ export declare class SemanticGroup extends BaseGroup {
     isSemanticGroup: boolean;
     type: string;
     buildings: BuildingGroup[];
-    facilityLayer: Object3D | null;
+    facilityLayer: FacilityInstancedLayer | null;
     constructor();
     addBuilding(group: BuildingGroup): this;
     getBuildingAt(index: number): BuildingGroup;
@@ -16,7 +16,8 @@ export declare class SemanticGroup extends BaseGroup {
     getBuildings(): BuildingGroup[];
     removeBuilding(group: BuildingGroup): this;
     get floorMeshes(): FloorMesh[];
-    setFacilityLayer(layer: Object3D | null): this;
+    setFacilityLayer(layer: FacilityInstancedLayer | null): this;
+    getDefaultFacilityLayer(): FacilityInstancedLayer | null;
     showAllFacilities(): this;
     hideAllFacilities(): this;
     getFacilityById(id: string): SemanticInstanceObject | undefined;

package/docs/api-plugin-u-manager.md

@@ -20,9 +20,11 @@ viewer.scene.add(group);
 
 const semanticGroup = group.semanticGroup;
 const sceneGroup = group.sceneGroup;
+const facilityLayer = semanticGroup.getDefaultFacilityLayer();
+const sceneLayer = sceneGroup.getDefaultSceneLayer();
 ```
 
-完整可运行示例见 [`examples/test_umanager_loader.html`](https://u-space-phi.vercel.app/examples/test_umanager_loader.html)。该示例展示了如何从返回根组中直接读取 `semanticGroup` / `sceneGroup`，并通过 `viewer.objectManager` 获取 `SceneInstanceObject` / `FacilityInstanceObject` 后调用统一 `getSemanticBoundingBox()`、`setSemanticHighlight()`、`setSemanticVisible()` 和 `setSemanticOpacity()`。
+完整可运行示例见 [`examples/test_umanager_loader.html`](https://u-space-phi.vercel.app/examples/test_umanager_loader.html)。该示例展示了如何从返回根组中直接读取 `semanticGroup` / `sceneGroup`，通过 `getDefaultFacilityLayer()` / `getDefaultSceneLayer()` 获取默认合批层，并通过 `viewer.objectManager` 获取 `SceneInstanceObject` / `FacilityInstanceObject` 后调用统一 `viewer.controls.flyToObject()`、`setSemanticHighlight()`、`setSemanticVisible()` 和 `setSemanticOpacity()`。运行时动态新增/删除 batch 实例的示例见 [`examples/test_umanager_dynamic_instances.html`](https://u-space-phi.vercel.app/examples/test_umanager_dynamic_instances.html)。
 
 ## `SemanticLoader`
 
@@ -57,7 +59,9 @@ floor.addEventListener('click', ({ event }) => {
 });
 ```
 
-所有可按 ID 操作的实例都会尽量暴露统一的 `SemanticInstanceObject` API。楼层多边形语义使用轻量 `FloorSemanticInstanceObject` 代理合并几何中的一个实例；Facilities 和 SceneLoader path instancing 使用同一套模型实例化底层。业务代码优先使用 `setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()` 和 `getSemanticBoundingBox()`，而不是关心底层是合并几何、`InstancedMesh` 还是 fallback `Model`。
+所有可按 ID 操作的实例都会尽量暴露统一的 `SemanticInstanceObject` API。楼层多边形语义使用轻量 `FloorSemanticInstanceObject` 代理合并几何中的一个实例；Facilities 和 SceneLoader path instancing 使用同一套模型实例化底层。业务代码优先使用 `setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()` 和 `viewer.controls.flyToObject(instance)`，而不是关心底层是合并几何、`InstancedMesh` 还是 fallback `Model`。
+
+`SemanticInstanceObject` 也按 Three.js 对象级包围盒约定提供 `boundingBox`、`boundingSphere`、`computeBoundingBox()` 和 `computeBoundingSphere()`。它们缓存的是实例本地坐标包围体，`Box3.setFromObject()` 会自动调用 `computeBoundingBox()` 并应用 `matrixWorld`，因此 `viewer.controls.flyToObject()` 可以直接飞向 `SceneInstanceObject`、`FacilityInstanceObject` 和楼层语义实例。需要手动处理世界包围盒时，仍可使用 `getSemanticBoundingBox(target, true)`。
 
 ### `SemanticGroup`
 
@@ -73,6 +77,7 @@ floor.addEventListener('click', ({ event }) => {
 | `getBuildingAt(index)` / `getBuildingById(id)` / `getBuildings()` | 按下标、`Building.ID` 或整体列表获取建筑。 |
 | `floorMeshes` | 聚合返回所有建筑内的 `FloorMesh[]`。 |
 | `setFacilityLayer(layer)` | 设置跨楼层设备渲染层；传入 `null` 会移除已有 layer。 |
+| `getDefaultFacilityLayer()` | 返回当前默认 `FacilityInstancedLayer`；没有可实例化 Facilities 时返回 `null`。 |
 | `getFacilityById(id)` | 在整次语义解析结果中按 `Facility.ID` 或显式别名查找设备。 |
 | `showAllFacilities()` / `hideAllFacilities()` | 显示或隐藏整次语义解析结果中的全部设备。 |
 | `showAllFloors()` | 显示所有建筑的所有楼层。 |
@@ -102,7 +107,7 @@ floor.addEventListener('click', ({ event }) => {
 | `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层；也兼容传入楼层数组。 |
 | `isolateFloors(floors \| indexes)` | 只显示指定多个楼层，隐藏其他楼层。 |
 | `showAllFloors()` | 显示全部楼层。 |
-| `getFacilityById(id)` | 在当前建筑的楼层中按 `Facility.ID` 或显式别名查找设备。 |
+| `getFacilityById(id)` | 在当前建筑的楼层中按 `Facility.ID` 或 `FloorMesh.addFacility()` 显式传入的别名查找设备。 |
 | `showAllFacilities()` | 显示整栋建筑内全部楼层设备。 |
 | `hideAllFacilities()` | 隐藏整栋建筑内全部楼层设备。 |
 | `planishFloors(kind?)` | 压扁所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面附近，同时添加稳定的轻微 Y 偏移以减少共面闪烁；传入 `kind` 时只压扁该语义类型，`kind` 可包含 `Facilities`。 |
@@ -141,21 +146,16 @@ Facilities 会在单次 `SemanticParser` 解析范围内按模型 URL 自动分
 
 Instanced 设备通过 per-instance opacity attribute 控制单个设备透明度。batch 材质默认沿用源材质的透明状态；只有源材质本身透明，或当前参与渲染的设备存在 `opacity < 1` 时，材质才会切到 `transparent: true`，`setSemanticOpacity(1)` 可在没有其他半透明实例时回到不透明渲染队列。`resetSemanticColor()` 只清除颜色 override，不影响透明度 override。`FacilityInstancedLayer` 会在设备显隐、颜色、透明度、floor planish/unplanish 改变设备 transform，或相机矩阵、投影矩阵、viewport 高度变化时，在下一次渲染前同步实例矩阵、颜色、透明度和当前 active instance count。普通 fallback `Model` 的颜色和透明度控制由 wrapper 委托到 `MaterialEffects`，单材质和多材质 Mesh 都会应用 override。
 
-加载成功后，设备引用会写入 `userData.facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName`、`spaces`、`twinsIdentifier`、`storyId` 和 `floorIndex`，并按 `Facility.ID` 注册到 `viewer.objectManager`。自动 instancing 的引用还会带有 `userData.instanced: true` 和 `userData.modelUrl`。
+加载成功后，`BuildingGroup`、`FloorMesh` 和设备引用都会在对象字段上写入独立语义身份，例如 `semanticId`、`semanticKind` 和 `semanticName`。`SemanticGroup.getBuildingById()`、`BuildingGroup.getFloorById()`、`BuildingGroup.getFacilityById()`、`FloorMesh.getFacilityById()` 以及 `SemanticModelInstancedLayer` 的查询、删除和 raycast remap 都使用这些对象字段或显式传入的别名，不再从 `userData.id`、`userData.semanticId`、`userData.facilityId` 里扫描 ID。`userData` 只保留原始业务元数据，例如 `facilityId`、`spaces`、`twinsIdentifier`、`storyId`、`floorIndex`、`instanced` 和 `modelUrl`。
 
 ```typescript
-import { Box3 } from 'three';
-
 const floor = building.getFloorAt(0);
-const box = new Box3();
 
 const facility = floor.getFacilityById('FACILITY_001') ?? viewer.objectManager.getById('FACILITY_001');
 const facilityEntity = floor.getSemanticById('FACILITY_001');
 
 if (facility && facilityEntity?.type === 'object') {
-  const facilityBox = facility.getSemanticBoundingBox(box, true);
-
-  await viewer.controls.flyToBox(facilityBox, {
+  await viewer.controls.flyToObject(facility, {
     viewpoint: 'rightFrontTop',
     padding: 0.2,
   });
@@ -170,26 +170,23 @@ facility
   .setSemanticVisible(true);
 ```
 
-对 Facilities 推荐使用 `controls.flyToBox()` 飞向设备包围盒。无论设备实际渲染来自 `InstancedMesh` 还是 fallback `Model`，都可以通过 `getSemanticBoundingBox(box, true)` 取得完整世界包围盒。
+对 Facilities 推荐直接使用 `controls.flyToObject()` 飞向设备。无论设备实际渲染来自 `InstancedMesh` 还是 fallback `Model`，`FacilityInstanceObject` 都会暴露本地 `boundingBox` / `boundingSphere`，让 Three.js 的 `Box3.setFromObject()` 能计算完整世界包围盒。
 
 ### `FacilityInstanceObject`
 
 `FacilityInstanceObject` 继承自统一的 `SemanticInstanceObject`，表示一个设备语义实例。它会挂在所属 `FloorMesh` 下，用于 ID 检索、事件派发、显隐、颜色、透明度和包围盒查询；如果设备可以 instancing，真正几何由 `SemanticGroup.facilityLayer` 里的 `InstancedMesh` 统一渲染；如果不能 instancing，fallback `Model` 会作为它的子对象挂载。
 
-通常不需要手动创建 `FacilityInstanceObject`。`SemanticParser` 在解析 `Facilities` 时会自动创建它，并写入 `userData.facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName`、`spaces`、`twinsIdentifier`、`storyId`、`floorIndex`、`instanced` 和 `modelUrl`。`userData.instanced` 表示当前设备是否由 `InstancedMesh` 渲染；fallback 时仍然保留同一套语义实例 API。
+通常不需要手动创建 `FacilityInstanceObject`。`SemanticParser` 在解析 `Facilities` 时会自动创建它，并通过 `setSemanticIdentity()` 写入 `semanticId`、`semanticKind` 和 `semanticName`。`userData.instanced` 表示当前设备是否由 `InstancedMesh` 渲染；fallback 时仍然保留同一套语义实例 API。
 
-加载完成后，设备可以按 `Facility.ID` 从全局 `objectManager` 取回。推荐使用 `getSemanticBoundingBox(box, true)` 取得完整世界包围盒，再调用 `viewer.controls.flyToBox()`。
+加载完成后，设备可以按 `Facility.ID` 从全局 `objectManager` 取回，并直接传给 `viewer.controls.flyToObject()`。如果需要自己合并多个对象或调整包围盒，也可以继续调用 `getSemanticBoundingBox(box, true)`。
 
 ```typescript
-import { Box3 } from 'three';
 import { FacilityInstanceObject } from 'u-space/plugins/u-manager';
 
 const facility = viewer.objectManager.getById<FacilityInstanceObject>('FACILITY_001');
 
 if (facility?.isFacilityInstanceObject) {
-  const box = facility.getSemanticBoundingBox(new Box3(), true);
-
-  await viewer.controls.flyToBox(box, {
+  await viewer.controls.flyToObject(facility, {
     viewpoint: 'rightFrontTop',
     padding: 0.2,
     enableTransition: true,
@@ -201,8 +198,15 @@ if (facility?.isFacilityInstanceObject) {
 | :---------- | :--- |
 | `isFacilityInstanceObject` | 类型标记，值为 `true`。 |
 | `type` | Three.js 对象类型名，值为 `'FacilityInstanceObject'`。 |
-| `setSemanticBounds(bounds)` | 设置模板在引用本地空间内的包围盒，并返回自身；主要由 `SemanticModelInstancedLayer.addSemanticBatch()` 在建 batch 时写入。 |
-| `getSemanticBoundingBox(target?, world?)` | 获取完整包围盒。`world = true` 时会应用 `matrixWorld`，适合传给 `viewer.controls.flyToBox()`；没有 bounds 时返回 empty `Box3`。 |
+| `semanticId` | 实例独立 ID，设备默认等于 `Facility.ID`；layer 的按 ID 查询、删除和 raycast remap 都使用该字段。 |
+| `semanticKind` | 实例语义类型，设备为 `'Facilities'`。 |
+| `semanticName` | 实例显示名称，设备默认使用 `Facility.Name`。 |
+| `setSemanticIdentity({ id, kind, name })` | 设置实例独立身份字段，并返回自身；`semanticId` 在同一个 `SemanticModelInstancedLayer` 内必须唯一，加入 layer 后修改 id 时，下一次按 id 查询会刷新索引。 |
+| `boundingBox` | 实例本地包围盒缓存，初始为 `null`；`Box3.setFromObject()` 或手动调用 `computeBoundingBox()` 时会计算。 |
+| `boundingSphere` | 实例本地包围球缓存，初始为 `null`；手动调用 `computeBoundingSphere()` 时会由当前本地包围盒派生。 |
+| `setSemanticBounds(bounds)` | 设置模板在引用本地空间内的包围盒，并返回自身；主要由 `SemanticModelInstancedLayer.addSemanticInstances()` / `reserveSemanticBatch()` 在建 batch 时写入。 |
+| `computeBoundingBox()` / `computeBoundingSphere()` | 按 Three.js 对象级包围盒约定更新 `boundingBox` / `boundingSphere`，使 `viewer.controls.flyToObject()` 能直接飞向实例。 |
+| `getSemanticBoundingBox(target?, world?)` | 获取完整包围盒。`world = true` 时会应用 `matrixWorld`，适合需要手动传给 `viewer.controls.flyToBox()` 的场景；没有 bounds 时返回 empty `Box3`。 |
 | `setSemanticVisible(visible)` | 设置单个语义实例的 `visible`，并返回自身；渲染和射线检测都会跳过不可见引用。 |
 | `setSemanticColor(color)` | 设置单个语义实例的颜色 override，并返回自身。`color` 支持 Three.js `ColorRepresentation`。 |
 | `resetSemanticColor()` | 清除颜色 override，恢复使用源材质颜色，并返回自身；不会清除透明度 override。 |
@@ -212,10 +216,8 @@ if (facility?.isFacilityInstanceObject) {
 | `getSemanticOpacity()` | 读取当前透明度 override。 |
 
 ```typescript
-import { Box3 } from 'three';
 import { FacilityInstanceObject } from 'u-space/plugins/u-manager';
 
-const box = new Box3();
 const facility = floor.getFacilityById('FACILITY_001');
 
 if (facility instanceof FacilityInstanceObject) {
@@ -224,7 +226,7 @@ if (facility instanceof FacilityInstanceObject) {
     .setSemanticOpacity(0.6)
     .setSemanticVisible(true);
 
-  await viewer.controls.flyToBox(facility.getSemanticBoundingBox(box, true), {
+  await viewer.controls.flyToObject(facility, {
     viewpoint: 'rightFrontTop',
     padding: 0.2,
   });
@@ -235,7 +237,7 @@ if (facility instanceof FacilityInstanceObject) {
 
 `FacilityInstancedLayer` 继承自 `SemanticModelInstancedLayer`，是 scene-level Facilities 的批量渲染层。`SemanticGroup.facilityLayer` 默认就是该类型；它会按模型 URL 把同一模板的静态设备合并为一个或多个 `InstancedMesh`，并用普通 `Group` 包裹每个模型 URL batch，保证设备显隐、颜色、透明度和相机实例裁剪能在每帧渲染前同步，同时保留每个楼层下的 `FacilityInstanceObject` 引用用于业务 API 和事件冒泡。
 
-使用 `SemanticLoader` 时通常不需要直接调用 `addSemanticBatch()`；只有自定义语义解析或自建设备 batch 时才需要手动创建 layer，然后通过 `semanticGroup.setFacilityLayer(layer)` 挂回语义场景。
+使用 `SemanticLoader` 时通常不需要直接调用 `addSemanticInstances()`；只有自定义语义解析、运行时新增设备或自建设备 batch 时才需要手动创建 layer，然后通过 `semanticGroup.setFacilityLayer(layer)` 挂回语义场景。
 
 | 属性 / 方法 | 说明 |
 | :---------- | :--- |
@@ -244,11 +246,41 @@ if (facility instanceof FacilityInstanceObject) {
 | `name` | 构造函数默认设为 `'Facilities'`。 |
 | `getInstanceCulling()` | 返回当前实例裁剪配置：`enabled`、`frustum`、`minScreenRadius`。 |
 | `setInstanceCulling(options)` | 设置实例裁剪配置，并返回自身。默认 `enabled: false`、`frustum: true`、`minScreenRadius: 0`；默认不按相机裁剪设备，避免相机距离影响设备显隐。需要性能压缩时可设置 `enabled: true` 开启视锥裁剪，或再把 `minScreenRadius` 设为大于 0 的值开启屏幕尺寸裁剪。 |
-| `addSemanticBatch(url, template, instances)` | 尝试把同一模型 URL 的语义实例引用合并为 instanced batch。成功返回 `true`，失败返回 `false`，失败时调用方应回退为普通模型渲染。 |
+| `getSemanticInstances()` | 返回当前 layer 内全部语义实例对象数组。 |
+| `getSemanticInstanceById(id)` | 根据实例对象的 `semanticId` 快速获取语义实例；找不到时返回 `undefined`。 |
+| `hasSemanticInstance(id)` | 判断当前 layer 是否包含对应 `semanticId` 的实例。 |
+| `reserveSemanticBatch(url, template, capacity)` | 为某个模型 URL 预分配 batch 容量。适合接下来会多次运行时新增实例的场景，成功返回 `true`，模板不支持 instancing 时返回 `false`。 |
+| `addSemanticInstance(url, template, instance)` | 向某个模型 URL 的 batch 新增一个语义实例。成功返回 `true`，失败时调用方应回退为普通模型渲染。 |
+| `addSemanticInstances(url, template, instances)` | 向某个模型 URL 的 batch 批量新增语义实例。推荐运行时新增多个实例时优先使用，避免连续单个新增造成重复扩容检查。 |
+| `removeSemanticInstance(instanceOrId)` | 删除一个语义实例，可传实例对象或完整 `semanticId`。删除成功返回 `true`。 |
+| `removeSemanticInstances(instancesOrIds)` | 删除一个或多个语义实例。可传单个实例对象、单个字符串 `semanticId`，或混合实例对象和 ID 的 iterable；返回实际删除数量。 |
+| `removeSemanticBatch(url)` | 删除某个模型 URL 的完整 batch，释放对应内部 `InstancedMesh` 和 cloned materials。 |
+| `clearSemanticBatches()` | 清空当前 layer 的所有模型 batch，并返回自身。 |
+
+`addSemanticInstances(url, template, instances)` 会按模型 URL 复用或创建 batch，从 `template` 收集可 instancing 的可见 `Mesh`，克隆源材质，并为每个 batch 建立 instance matrix、颜色和透明度 attribute。没有动画、没有骨骼、没有 morph target，且每个多材质 `Mesh` 都有合法 `geometry.groups` 的模板会进入 instancing；不满足条件、模板没有可用 Mesh、`instances` 为空，或待加入实例的 `semanticId` 与当前 layer 内已有实例重复时会返回 `false`。
+
+动态新增时，layer 会维护每个 URL batch 的 `capacity`。容量足够时，新增实例只会写入逻辑数组、注册 dirty callback 并标记下一帧同步；容量不足时才按 2 倍增长策略重建该 URL 下的内部 `InstancedMesh` 和 attribute buffer。运行时需要连续新增大量实例时，推荐先调用 `reserveSemanticBatch(url, template, expectedCount)`，再调用 `addSemanticInstances()`。删除实例不会立即收缩 GPU buffer；只有 batch 为空、调用 `removeSemanticBatch()` 或 `clearSemanticBatches()` 时才释放内部渲染资源。
+
+外部代码不需要直接写内部 `InstancedMesh.instanceMatrix`。要移动、旋转或缩放实例时，直接修改对应 `SemanticInstanceObject` 的 transform，然后让它更新世界矩阵或等待下一帧渲染即可；`SemanticInstanceObject.updateMatrixWorld()` 会标记 batch dirty，layer 会在渲染前把世界矩阵同步到内部 instance matrix 并设置 `instanceMatrix.needsUpdate = true`。因此即使底层使用 WebGPU storage instanced buffer，公开更新方式仍然是面向语义实例对象：
+
+```typescript
+const instance = layer.getSemanticInstanceById('FACILITY_001');
+
+if (instance) {
+  instance.position.set(10, 0, 5);
+  instance.updateMatrixWorld(true);
+  viewer.render();
+}
+```
 
-`addSemanticBatch(url, template, instances)` 会从 `template` 收集可 instancing 的可见 `Mesh`，克隆源材质，并为每个 batch 建立 instance matrix、颜色和透明度 attribute。没有动画、没有骨骼、没有 morph target，且每个多材质 `Mesh` 都有合法 `geometry.groups` 的模板会进入 instancing；不满足条件、模板没有可用 Mesh 或 `instances` 为空时会返回 `false`。
+删除 API 支持单个字符串 ID，不需要为了删除一个实例额外包一层数组。下面两个调用等价，都会按完整 ID 删除实例：
 
-渲染前，layer 会同步每个 `FacilityInstanceObject` 的世界矩阵、颜色和透明度，并只在数据变化时上传对应 buffer。默认情况下，相机移动不会改变设备 active instance 集合；显式调用 `setInstanceCulling({ enabled: true })` 后，layer 才会按当前渲染相机逐实例压缩 `InstancedMesh.count`，视锥外设备不会进入本帧实例 buffer；只有同时设置 `minScreenRadius > 0` 时，屏幕半径小于该阈值的设备才会被跳过。相机矩阵、投影矩阵或 viewport 高度未变化时不会重复压缩；设备显隐、透明度为 0、颜色/透明度变化或 `planish('Facilities')` / `unplanish('Facilities')` 改变 transform 时会标记 batch dirty。全部设备不可渲染时，内部 `InstancedMesh.visible` 会被关闭；只有被当前相机裁掉时，mesh 会保留可见并把 `count` 设为 0，以便相机移动后自动恢复。射线检测命中 batch 内实例时，`hit.object` 会被改写为对应的 `FacilityInstanceObject`，并附加 `semanticObject`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName` 和 `semanticIndex`，事件随后会按楼层引用对象继续冒泡。
+```typescript
+layer.removeSemanticInstance('FACILITY_001');
+layer.removeSemanticInstances('FACILITY_001');
+```
+
+渲染前，layer 会同步每个 `FacilityInstanceObject` 的世界矩阵、颜色和透明度，并只在数据变化时上传对应 buffer。默认情况下，相机移动不会改变设备 active instance 集合；显式调用 `setInstanceCulling({ enabled: true })` 后，layer 才会按当前渲染相机逐实例压缩 `InstancedMesh.count`，视锥外设备不会进入本帧实例 buffer；只有同时设置 `minScreenRadius > 0` 时，屏幕半径小于该阈值的设备才会被跳过。相机矩阵、投影矩阵或 viewport 高度未变化时不会重复压缩；设备显隐、透明度为 0、颜色/透明度变化或 `planish('Facilities')` / `unplanish('Facilities')` 改变 transform 时会标记 batch dirty。全部设备不可渲染时，内部 `InstancedMesh.visible` 会被关闭；只有被当前相机裁掉时，mesh 会保留可见并把 `count` 设为 0，以便相机移动后自动恢复。射线检测命中 batch 内实例时，`hit.object` 会被改写为对应的 `FacilityInstanceObject`，并从实例对象字段附加 `semanticObject`、`semanticId`、`semanticKind`、`semanticName` 和 `semanticIndex`，事件随后会按楼层引用对象继续冒泡。
 
 ```typescript
 import { FacilityInstancedLayer, FacilityInstanceObject } from 'u-space/plugins/u-manager';
@@ -256,16 +288,21 @@ import { FacilityInstancedLayer, FacilityInstanceObject } from 'u-space/plugins/
 const layer = new FacilityInstancedLayer();
 const refs = facilityItems.map(() => new FacilityInstanceObject());
 
-if (layer.addSemanticBatch('/models/camera.glb', templateObject, refs)) {
+layer.reserveSemanticBatch('/models/camera.glb', templateObject, refs.length + 100);
+
+if (layer.addSemanticInstances('/models/camera.glb', templateObject, refs)) {
   semanticGroup.setFacilityLayer(layer);
 }
+
+// 运行时按完整字符串 ID 删除一个实例；返回实际删除数量。
+layer.removeSemanticInstances('FACILITY_001');
 ```
 
 如果只想整体隐藏或禁用 scene-level batch，可以设置 `semanticGroup.facilityLayer.visible = false`；如果只想控制单个设备，推荐从 `floor.getFacilityById(id)` 或 `viewer.objectManager.getById(id)` 取回 `FacilityInstanceObject` 后调用 `setSemanticVisible()` / `setSemanticOpacity()`。
 
 ### `SemanticModelInstancedLayer`
 
-`SemanticModelInstancedLayer` 是 `SceneInstancedLayer` 和 `FacilityInstancedLayer` 的共享实现。它负责模板 mesh 收集、材质克隆、`InstancedMesh` 创建、instance matrix/color/opacity buffer 同步、raycast hit remap、fallback 判定和可选相机实例裁剪。通常业务代码不需要直接使用它，除非要为新的语义实例类型复用同一套模型 instancing 能力。
+`SemanticModelInstancedLayer` 是 `SceneInstancedLayer` 和 `FacilityInstancedLayer` 的共享实现。它负责模板 mesh 收集、材质克隆、`InstancedMesh` 创建、运行时实例新增/删除、capacity 扩容、instance matrix/color/opacity buffer 同步、raycast hit remap、fallback 判定和可选相机实例裁剪。layer 内部只依赖 `SemanticInstanceObject` 的 `semanticId`、`semanticKind`、`semanticName` 独立字段，不再扫描 `instance.userData` 的 `facilityId`、`id` 或 `sid`。`getSemanticInstanceById()` / `removeSemanticInstances(id)` 会按需刷新 id 索引；新增实例时如果发现重复 `semanticId` 会拒绝加入，避免同一个 layer 内出现不确定查询结果。通常业务代码不需要直接使用它，除非要为新的语义实例类型复用同一套模型 instancing 能力。
 
 ### `FloorMesh`
 
@@ -291,7 +328,7 @@ if (layer.addSemanticBatch('/models/camera.glb', templateObject, refs)) {
 | `getSemanticObjectAt(index)` | 获取合并几何实例对应的 `FloorSemanticInstanceObject` 轻量对象。 |
 | `showAllFacilities()` | 显示当前楼层的全部设备对象。 |
 | `hideAllFacilities()` | 隐藏当前楼层的全部设备对象。 |
-| `addFacility(object, ids?)` | 把设备对象挂到楼层，并按显式 ID、`facilityId`、`semanticId`、`id` 建立检索别名。 |
+| `addFacility(object, ids?)` | 把设备对象挂到楼层，并按对象 `semanticId` 和显式 `ids` 建立检索别名。不会从 `object.userData` 自动扫描 ID。 |
 | `getFacilityById(id)` | 根据 `Facility.ID` 或别名获取设备对象。 |
 | `getFacilityAt(index)` | 按楼层设备数组下标获取设备对象。 |
 | `getFacilities()` | 获取当前楼层全部设备对象。 |
@@ -323,17 +360,23 @@ floor.addEventListener('click', async ({ event }) => {
 
   if (intersect.semanticKind === 'Facilities') {
     const facility = intersect.semanticObject ?? event.target;
-    const facilityBox = facility.getSemanticBoundingBox(box, true);
 
-    await viewer.controls.flyToBox(facilityBox, {
+    await viewer.controls.flyToObject(facility, {
+      viewpoint: 'rightFrontTop',
+      padding: 0.2,
+    });
+    return;
+  }
+
+  if (intersect.semanticObject) {
+    await viewer.controls.flyToObject(intersect.semanticObject, {
       viewpoint: 'rightFrontTop',
       padding: 0.2,
     });
     return;
   }
 
-  const semanticBox = intersect.semanticObject?.getSemanticBoundingBox(box, true)
-    ?? currentTarget.getBoundingBoxAt(intersect.semanticIndex, box, true);
+  const semanticBox = currentTarget.getBoundingBoxAt(intersect.semanticIndex, box, true);
 
   if (semanticBox) {
     await viewer.controls.flyToBox(semanticBox, {
@@ -375,8 +418,10 @@ import { SceneLoader } from 'u-space/plugins/u-manager';
 const sceneLoader = new SceneLoader(viewer);
 sceneLoader.setPath('./scenes/my-scene');
 sceneLoader.setKey('YOUR_LICENSE_KEY'); // 官方授权场景必需
-const group = await sceneLoader.loadAsync();
+const group = await sceneLoader.loadAsync(); // SceneGroup
 viewer.scene.add(group);
+
+const sceneLayer = group.getDefaultSceneLayer();
 ```
 
 **方法：**
@@ -384,15 +429,26 @@ viewer.scene.add(group);
 | 方法                | 说明                                                                 |
 | :------------------ | :------------------------------------------------------------------- |
 | `setKey(key)`       | 设置授权场景的 RSA 解密密钥。                                        |
-| `loadAsync()`       | 加载并解析场景，返回去除语义重复节点后的 `Group`。                   |
+| `loadAsync()`       | 加载并解析场景，返回去除语义重复节点后的 `SceneGroup`。              |
 | `clearCache()`      | 从 `objectManager` 中移除此加载器注册的所有 ID。                     |
 | `dispose()`         | 清除缓存并释放水印叠加层。                                           |
 
+### `SceneGroup`
+
+`SceneGroup` 继承自 `BaseGroup`，是 `SceneLoader.loadAsync()` 的返回根组。它保留 `tree_models.json` 解析后的原始父子层级，并把重复静态模型的默认合批渲染层挂在 `sceneLayer`，方便外部直接访问，而不需要遍历 `children`。
+
+| 属性 / 方法 | 说明 |
+| :---------- | :--- |
+| `isSceneGroup` | 固定为 `true`，用于判断对象是否为 `SceneLoader` 根组。 |
+| `sceneLayer` | 当前默认 `SceneInstancedLayer`；没有可合批的重复 3D 模型时为 `null`。 |
+| `setSceneLayer(layer)` | 设置默认 `SceneInstancedLayer`；传入 `null` 会移除已有 layer。 |
+| `getDefaultSceneLayer()` | 返回当前默认 `SceneInstancedLayer`；没有可合批模型时返回 `null`。 |
+
 ### `SceneInstanceObject`
 
 `SceneInstanceObject` 继承自统一的 `SemanticInstanceObject`，表示一个由 `SceneInstancedLayer` 批量渲染或 fallback 普通渲染的场景模型引用。它会保留在原场景树层级中，并注册到 `viewer.objectManager`，因此 `getById()`、`show()` / `hide()`、`isolate()`、`showAll()`、`setOpacity()` 和 `getBoundingBox()` 可以继续按单个模型 ID 使用。
 
-`SceneInstanceObject` 本身只增加场景模型语义：`isSceneInstanceObject = true`、`type = 'SceneInstanceObject'`，并把 `userData.semanticKind` 设为 `SceneInstances`。加载器会把场景树节点的 `id` 和 `sid` 都注册到 `viewer.objectManager`，因此同一个对象可以通过任一 ID 取回。对重复模型的 instanced 路径，`userData.instanced = true`，并带有 `modelPath`、`modelUrl`、`semanticId` 和 `semanticName`；如果模板不支持 instancing，会退回普通 `Model`，但仍挂在同一个 `SceneInstanceObject` 下，对外 API 不变。
+`SceneInstanceObject` 本身只增加场景模型语义：`isSceneInstanceObject = true`、`type = 'SceneInstanceObject'`、`semanticKind = 'SceneInstances'`。加载器会把场景树节点的 `id` 和 `sid` 都注册到 `viewer.objectManager`，因此同一个对象可以通过任一 ID 取回。对重复模型的 instanced 路径，`semanticId` 默认等于场景树节点 `id`，`semanticName` 默认等于节点名称；`userData.instanced = true`，并保留 `modelPath` 和 `modelUrl` 等原始加载元数据。如果模板不支持 instancing，会退回普通 `Model`，但仍挂在同一个 `SceneInstanceObject` 下，对外 API 不变。
 
 **识别字段：**
 
@@ -401,10 +457,13 @@ viewer.scene.add(group);
 | `isSceneInstanceObject` | 固定为 `true`，用于判断对象是否来自 `SceneLoader` 的场景实例。 |
 | `isSemanticInstanceObject` | 固定为 `true`，表示它支持统一语义实例 API。 |
 | `type` | 固定为 `SceneInstanceObject`。 |
+| `semanticId` | 实例独立 ID，默认等于场景树节点 `id`；layer 的按 ID 查询、删除和 raycast remap 都使用该字段。 |
+| `semanticKind` | 实例语义类型，场景实例为 `'SceneInstances'`。 |
+| `semanticName` | 实例显示名称，默认等于场景树节点名称。 |
+| `setSemanticIdentity({ id, kind, name })` | 设置实例独立身份字段，并返回自身；运行时手动创建实例时建议先设置再加入 layer，加入后修改 id 会在下一次按 id 查询时刷新索引。 |
+| `boundingBox` | 实例本地包围盒缓存，初始为 `null`；`Box3.setFromObject()` 或手动调用 `computeBoundingBox()` 时会计算。 |
+| `boundingSphere` | 实例本地包围球缓存，初始为 `null`；手动调用 `computeBoundingSphere()` 时会由当前本地包围盒派生。 |
 | `userData.id` / `userData.sid` | 原始场景树节点 ID；两个 ID 都会注册到 `viewer.objectManager`。 |
-| `userData.semanticId` | 语义事件和 raycast remap 使用的实例 ID，默认等于场景树节点 `id`。 |
-| `userData.semanticKind` | 固定为 `SceneInstances`。 |
-| `userData.semanticName` | 原始场景树节点名称。 |
 | `userData.instanced` | `true` 表示实际渲染来自 `SceneInstancedLayer`；`false` 表示 fallback `Model` 挂在当前对象下。 |
 | `userData.modelPath` / `userData.modelUrl` | instanced 场景实例对应的模型相对路径和完整 URL。 |
 
@@ -415,6 +474,7 @@ viewer.scene.add(group);
 | `setSemanticBounds(bounds)` | 设置本地包围盒。`SceneLoader` 会在创建 instanced batch 时根据模板模型自动设置；业务一般不需要手动调用。 |
 | `setSemanticRenderObject(object)` | 设置 fallback 渲染对象并作为子对象挂载。模板无法 instancing 时由 `SceneLoader` 自动调用；自定义语义实例渲染时可手动使用。 |
 | `getSemanticRenderObject()` | 返回 fallback 渲染对象；instanced 渲染路径通常返回 `null`，因为真实 Mesh 在 `SceneInstancedLayer` 中。 |
+| `computeBoundingBox()` / `computeBoundingSphere()` | 按 Three.js 对象级包围盒约定更新 `boundingBox` / `boundingSphere`，使 `viewer.controls.flyToObject()` 能直接飞向实例。 |
 | `getSemanticBoundingBox(target?, world?)` | 返回实例包围盒。`world = true` 时会应用 `matrixWorld`，适合直接传给 `viewer.controls.flyToBox()`；无 bounds 和 render object 时返回 empty `Box3`。 |
 | `setSemanticVisible(visible)` | 设置单个实例显隐并标记 batch dirty；隐藏后该实例不会继续渲染，也不会被 instanced raycast 命中。 |
 | `setSemanticColor(color)` | 设置单个实例颜色 override。instanced 路径写入 per-instance color；fallback `Model` 路径会委托到材质高亮逻辑。 |
@@ -431,17 +491,15 @@ viewer.scene.add(group);
 
 `MaterialEffects.highlightColor()` / `removeHighlightColor()` 会识别 `SceneInstanceObject` 并调用 `setSemanticHighlight()` / `clearSemanticHighlight()`，不会直接修改共享 batch 材质。`ObjectManager.setOpacity()`、`ObjectManager.hide()`、`ObjectManager.show()` 也会通过统一 API 作用到单个实例。
 
-加载完成后可以按场景树节点 `id` 从 `objectManager` 取回 `SceneInstanceObject`，再用 `getSemanticBoundingBox(box, true)` 取得世界包围盒并传给 `viewer.controls.flyToBox()`。`SceneInstanceObject` 内部带有不可见的本地 bounds，因此不需要加载真实 Mesh 副本也能计算飞行包围盒。
+加载完成后可以按场景树节点 `id` 从 `objectManager` 取回 `SceneInstanceObject`，再直接传给 `viewer.controls.flyToObject()`。`SceneInstanceObject` 内部带有本地 `boundingBox` 缓存能力，因此不需要加载真实 Mesh 副本也能计算飞行包围盒。
 
 ```typescript
-import { Box3 } from 'three/webgpu';
 import { SceneInstanceObject } from 'u-space/plugins/u-manager';
 
 const object = viewer.objectManager.getById<SceneInstanceObject>('SCENE_NODE_ID');
 
 if (object?.isSceneInstanceObject) {
-  const box = object.getSemanticBoundingBox(new Box3(), true);
-  await viewer.controls.flyToBox(box, {
+  await viewer.controls.flyToObject(object, {
     viewpoint: 'current',
     padding: 0.2,
     enableTransition: true,

package/docs/changelog.md

@@ -2,11 +2,33 @@
 
 ## 未发布
 
+### 变更
+
+- **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 两套特殊分支。
-- **examples/docs/mcp** — 新增 `examples/test_umanager_loader.html`，演示 `UManagerLoader` 一次加载语义楼层、Facilities 和非语义场景树，并补充 Examples Guide 与 MCP 检索入口。
+- **u-manager loader** — `SceneLoader` 不再解析场景树里的 `AREA`、`FLOOR`、`ROOM` 语义面；楼层、区域和房间统一由 `SemanticLoader` / `SemanticGroup` 处理，避免同一语义对象在组合加载时重复出现。
+
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.28`，Vercel 部署会继续按 `package.json` 注入当前版本。
 
 ## 0.0.27