u-space 0.0.21 → 0.0.23

package/dist/plugins/u-manager/semantics/SemanticLoader.d.ts

@@ -2,7 +2,13 @@ import { Loader } from 'three/webgpu';
 import type { Viewer } from 'u-space';
 import { BuildingGroup } from './objects/BuildingGroup';
 export declare class SemanticLoader extends Loader {
+    #private;
     viewer: Viewer;
+    key: string;
+    cachedIds: Set<string>;
     constructor(viewer: Viewer);
+    setKey(key: string): this;
     loadAsync(): Promise<BuildingGroup[]>;
+    clearCache(): void;
+    dispose(): void;
 }

package/dist/plugins/u-manager/semantics/SemanticParser.d.ts

@@ -1,5 +1,15 @@
+import { type LoadingManager, type Object3D } from 'three/webgpu';
 import { BuildingGroup } from './objects/BuildingGroup';
 import type { SemanticObject } from './semantic.types';
+import type { ITreeData } from '../types';
+export interface SemanticParserOptions {
+    treeData?: ITreeData[];
+    path?: string;
+    manager?: LoadingManager;
+    registerObject?: (id: string, object: Object3D) => void;
+}
 export declare class SemanticParser {
+    #private;
     parse(semanticData: SemanticObject): BuildingGroup[];
+    parseAsync(semanticData: SemanticObject, options?: SemanticParserOptions): Promise<BuildingGroup[]>;
 }

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

@@ -3,6 +3,7 @@ import type { ElevatorMesh } from './ElevatorMesh';
 import type { FloorMesh } from './FloorMesh';
 import type { SemanticKind } from '../types';
 import type { VentMesh } from './VentMesh';
+export type BuildingFloorReference = FloorMesh | number;
 export declare class BuildingGroup extends BaseGroup {
     isBuildingGroup: boolean;
     type: string;
@@ -19,8 +20,11 @@ export declare class BuildingGroup extends BaseGroup {
     addVent(mesh: VentMesh): this;
     getVentAt(index: number): VentMesh;
     removeVent(mesh: VentMesh): this;
-    isolateFloor(mesh: FloorMesh | number): this;
+    isolateFloor(floor: BuildingFloorReference | BuildingFloorReference[]): this;
+    isolateFloors(floors: BuildingFloorReference[]): this;
     showAllFloors(): this;
+    showAllFacilities(): this;
+    hideAllFacilities(): this;
     planishFloors(kind?: SemanticKind): this;
     unplanishFloors(kind?: SemanticKind): this;
 }

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

@@ -1,6 +1,26 @@
-import { Box3, BufferGeometry, Matrix4, MeshStandardNodeMaterial, Sphere, Vector3, Vector4, type Intersection, type Raycaster } from 'three/webgpu';
+import { Box3, BufferGeometry, Matrix4, MeshStandardNodeMaterial, Sphere, Vector3, Vector4, type Intersection, type Object3D, type Raycaster } from 'three/webgpu';
 import { BaseMesh, type InteractionEvent, type InteractionEventMap } from 'u-space';
 import type { SemanticColor, SemanticGeometryEntry, SemanticKind } from '../types';
+type FacilityReference = Object3D | string;
+type FacilitySemanticKind = 'Facilities';
+export type FloorSemanticKind = SemanticKind | FacilitySemanticKind;
+export interface FloorGeometrySemanticEntity {
+    type: 'geometry';
+    kind: SemanticKind;
+    id: string;
+    name?: string;
+    index: number;
+}
+export interface FloorFacilitySemanticEntity {
+    type: 'object';
+    kind: FacilitySemanticKind;
+    id: string;
+    name?: string;
+    index: number;
+    object: Object3D;
+    aliases: string[];
+}
+export type FloorSemanticEntity = FloorGeometrySemanticEntity | FloorFacilitySemanticEntity;
 type FloorMeshEventPayload<T> = T extends {
     event: InteractionEvent;
 } ? {
@@ -34,15 +54,28 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, MeshStandardNode
     windowsInstances: Map<string, number>;
     staircasesInstances: Map<string, number>;
     semanticInstances: Map<string, number>;
+    semanticEntities: Map<string, FloorSemanticEntity>;
+    facilityObjectsById: Map<string, Object3D>;
+    facilityObjects: Object3D[];
     constructor(entries: SemanticGeometryEntry[]);
     planish(kind?: SemanticKind): this;
     unplanish(kind?: SemanticKind): this;
     get semanticCount(): number;
     get instanceCount(): number;
     getSemanticIndexById(id: string): number | undefined;
+    getSemanticById(id: string): FloorSemanticEntity | undefined;
+    getSemantics(): FloorSemanticEntity[];
+    getSemanticsByKind(kind: FloorSemanticKind): FloorSemanticEntity[];
     getSemanticIdAt(index: number): string;
     getSemanticKindAt(index: number): SemanticKind;
     getSemanticNameAt(index: number): string | undefined;
+    showAllFacilities(): this;
+    hideAllFacilities(): this;
+    addFacility(object: Object3D, ids?: string | string[]): this;
+    getFacilityById(id: string): Object3D<import("three").Object3DEventMap> | undefined;
+    getFacilityAt(index: number): Object3D<import("three").Object3DEventMap>;
+    getFacilities(): Object3D<import("three").Object3DEventMap>[];
+    removeFacility(facility: FacilityReference): this;
     setColorAt(index: number, color: SemanticColor): this;
     getColorAt(index: number, target?: Vector4): Vector4;
     setOpacityAt(index: number, opacity: number): this;

package/dist/plugins/u-manager/semantics/semantic.types.d.ts

@@ -35,11 +35,17 @@ export interface Staircase {
     Polyline: number[];
     Spaces: number[];
 }
+export interface Facility {
+    ID: string;
+    Name: string;
+    Spaces: number[];
+    TwinsIdentifier: string;
+}
 export interface Story {
     Columns?: any[];
     Doors?: number[];
     Elevation?: number;
-    Facilities?: any[];
+    Facilities?: number[];
     FloorIndex?: any;
     Height?: number;
     ID?: string;
@@ -103,6 +109,7 @@ export interface Asset {
 export interface SemanticObject {
     Buildings?: Building[];
     Doors?: Door[];
+    Facilities?: Facility[];
     Spaces?: Space[];
     Staircases?: Staircase[];
     Stories?: Story[];

package/dist/src/viewers/Info.d.ts

@@ -1,5 +1,6 @@
 import { type WebGPURenderer } from 'three/webgpu';
 export declare class Info {
+    #private;
     el: HTMLElement;
     renderer: WebGPURenderer;
     container: HTMLElement;

package/docs/api-plugin-tiles.md

@@ -55,4 +55,4 @@ const { lon, lat, height } = arcgisTilesRenderer.positionToLonLatHeight(worldPos
 
 传给 `positionToLonLatHeight()` 的 `position` 必须是场景世界坐标。如果坐标来自某个对象的局部空间，先通过 `object.localToWorld(localPosition)` 或 `object.getWorldPosition()` 转成世界坐标。
 
-如果在瓦片 root tileset 加载前调用 `invalidate()`，重定位会等到 root tileset 加载后才真正应用。需要在业务逻辑中立即使用转换结果时，应确保 `invalidate()` 已经完成，或在瓦片加载完成后再调用转换方法。
+如果在瓦片 root tileset 加载前调用 `invalidate()`，会先基于当前 WGS84 椭球立即应用一次重定位，保证后续坐标转换可用；root tileset 加载完成后会按最终 ellipsoid 再应用一次。

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

@@ -1,12 +1,12 @@
 # u-manager
 
-`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性、相机视点、楼层和井道语义模型。
+`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性、相机视点、楼层、井道和设备语义模型。
 
 所有加载器均继承自 Three.js 的 `Loader`，并提供 `setPath(path)` 方法，在调用 `loadAsync()` 前配置基础数据目录。
 
 ## `SemanticLoader`
 
-加载 `db/semantic_model.json` 楼层语义数据，并按建筑返回 `BuildingGroup[]`。每个建筑包含多个 `FloorMesh`，每个楼层把墙、柱、空间等语义对象合并为一个 TSL 材质驱动的网格；建筑级电梯井和通风井会使用 `ExtrudeMesh` 独立渲染。
+加载 `db/semantic_model.json` 楼层语义数据，并按建筑返回 `BuildingGroup[]`。每个建筑包含多个 `FloorMesh`，每个楼层把墙、柱、空间、楼梯等语义对象合并为一个 TSL 材质驱动的网格；建筑级电梯井和通风井会使用 `ExtrudeMesh` 独立渲染。语义模型包含 `Facilities` 时，`SemanticLoader` 会额外读取 `SceneMetadata.json` 指向的 `tree_models`，按场景授权配置解密，再把对应设备模型挂载到所属楼层。
 
 ```typescript
 import { Vector3, Vector4 } from 'three';
@@ -14,6 +14,7 @@ import { SemanticLoader } from 'u-space/plugins/u-manager';
 
 const loader = new SemanticLoader(viewer);
 loader.setPath('./scenes/my-scene');
+loader.setKey('YOUR_LICENSE_KEY'); // 官方授权场景解析 tree_models 时必需
 
 const buildings = await loader.loadAsync(); // BuildingGroup[]
 viewer.scene.add(...buildings);
@@ -36,7 +37,7 @@ floor.addEventListener('click', ({ event }) => {
 
 ### `BuildingGroup`
 
-`BuildingGroup` 继承自 `BaseGroup`，用于组织一个建筑下的所有楼层、电梯井和通风井。
+`BuildingGroup` 继承自 `BaseGroup`，用于组织一个建筑下的所有楼层、电梯井和通风井。设备语义对象不会直接挂到 `BuildingGroup`，而是作为实际模型挂到对应的 `FloorMesh`。
 
 | 属性 / 方法 | 说明 |
 | :---------- | :--- |
@@ -50,8 +51,11 @@ floor.addEventListener('click', ({ event }) => {
 | `getElevatorAt(index)` | 按下标获取电梯井 `ExtrudeMesh`。 |
 | `addVent(vent)` / `removeVent(vent)` | 添加或移除通风井，并同步更新 group。 |
 | `getVentAt(index)` | 按下标获取通风井 `ExtrudeMesh`。 |
-| `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层。 |
+| `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层；也兼容传入楼层数组。 |
+| `isolateFloors(floors \| indexes)` | 只显示指定多个楼层，隐藏其他楼层。 |
 | `showAllFloors()` | 显示全部楼层。 |
+| `showAllFacilities()` | 显示整栋建筑内全部楼层设备。 |
+| `hideAllFacilities()` | 隐藏整栋建筑内全部楼层设备。 |
 | `planishFloors(kind?)` | 压扁所有楼层；传入 `kind` 时只压扁该语义类型。 |
 | `unplanishFloors(kind?)` | 恢复所有楼层；传入 `kind` 时只恢复该语义类型。 |
 
@@ -74,9 +78,30 @@ if (vent) {
 
 电梯井和通风井会在渲染阶段沿法线轻微内收，减少与墙体共面时的闪面。`Spaces` 实例也会使用稳定的 per-instance 渲染偏移抖动，缓解完全重叠空间之间的 z-fighting；这些偏移只影响渲染顶点，不改变语义 ID、实例矩阵和包围体查询的使用方式。
 
+### 设施设备
+
+`SemanticLoader` 会从 `Stories[].Facilities` 读取设备索引，再从顶层 `Facilities` 数组取得 `Facility` 数据，并使用 `Facility.ID` 在解密后的 `tree_models` 中查找同 ID 节点。只有带 `renderType: '3D'` 和模型 `path` 的节点会被加载。
+
+`tree_models.matrix` 是相对父节点的本地矩阵；`SemanticLoader` 会沿树父级累乘得到设备世界矩阵，再转换为对应 `FloorMesh` 的局部矩阵。因此楼层移动、隔离或显示隐藏时设备会跟随楼层一起工作。即使某个 story 只有 `Facilities`、没有墙柱空间等合并几何，也会创建一个空的 `FloorMesh` 作为设备容器。
+
+加载成功后，设备会写入 `userData.facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName`、`spaces`、`twinsIdentifier`、`storyId` 和 `floorIndex`，并按 `Facility.ID` 以及 `tree_models` 节点的 `sid` 注册到 `viewer.objectManager`。
+
+```typescript
+const floor = building.getFloorAt(0);
+
+const facility = floor.getFacilityById('FACILITY_001') ?? viewer.objectManager.getById('FACILITY_001');
+const facilityEntity = floor.getSemanticById('FACILITY_001');
+
+if (facility && facilityEntity?.type === 'object') {
+  await viewer.controls.flyToObject(facility);
+}
+
+const facilities = floor.getSemanticsByKind('Facilities');
+```
+
 ### `FloorMesh`
 
-`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。
+`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。设备模型作为普通 `Object3D` 子对象挂载在楼层下，通过设施检索 API 管理。
 
 这种结构的目标是让每个楼层通常只占一个主渲染 draw call，同时仍保留实例级控制能力。`xxxAt` 方法全部作用于单个语义实例；没有 `At` 后缀的方法作用于整个楼层 mesh。
 
@@ -84,11 +109,24 @@ if (vent) {
 | :---------- | :--- |
 | `semanticCount` / `instanceCount` | 当前楼层语义实例数量。 |
 | `semanticInstances` | `Map<string, number>`，从语义对象 ID 映射到实例下标。 |
-| `wallsInstances` / `columnsInstances` / `spacesInstances` / `doorsInstances` / `windowsInstances` | 按语义类型维护的 ID 到实例下标映射。 |
+| `wallsInstances` / `columnsInstances` / `spacesInstances` / `doorsInstances` / `windowsInstances` / `staircasesInstances` | 按语义类型维护的 ID 到实例下标映射。 |
+| `semanticEntities` | `Map<string, FloorSemanticEntity>`，统一索引楼层内合并几何语义和 `Facilities` 对象语义。 |
+| `facilityObjectsById` | `Map<string, Object3D>`，按 `Facility.ID`、`sid` 或显式别名查找设备模型。 |
+| `facilityObjects` | 当前楼层挂载的设备模型数组。 |
 | `getSemanticIndexById(id)` | 根据语义 ID 获取实例下标。 |
+| `getSemanticById(id)` | 根据语义 ID 或设备别名获取统一语义实体。 |
+| `getSemantics()` | 获取楼层内全部语义实体，包含合并几何和设备对象。 |
+| `getSemanticsByKind(kind)` | 按语义类型过滤实体；`kind` 可以是 `Walls`、`Columns`、`Spaces`、`Doors`、`Windows`、`Staircases` 或 `Facilities`。 |
 | `getSemanticIdAt(index)` | 获取实例语义 ID。 |
-| `getSemanticKindAt(index)` | 获取实例类型：`'Walls' \| 'Columns' \| 'Spaces' \| 'Doors' \| 'Windows'`。 |
+| `getSemanticKindAt(index)` | 获取合并几何实例类型：`'Walls' \| 'Columns' \| 'Spaces' \| 'Doors' \| 'Windows' \| 'Staircases'`。 |
 | `getSemanticNameAt(index)` | 获取实例名称；当前 `Spaces` 会从语义数据的 `Name` 写入，其他类型可能为 `undefined`。 |
+| `showAllFacilities()` | 显示当前楼层的全部设备对象。 |
+| `hideAllFacilities()` | 隐藏当前楼层的全部设备对象。 |
+| `addFacility(object, ids?)` | 把设备对象挂到楼层，并按显式 ID、`facilityId`、`semanticId`、`id`、`sid` 建立检索别名。 |
+| `getFacilityById(id)` | 根据 `Facility.ID`、`sid` 或别名获取设备对象。 |
+| `getFacilityAt(index)` | 按楼层设备数组下标获取设备对象。 |
+| `getFacilities()` | 获取当前楼层全部设备对象。 |
+| `removeFacility(facility)` | 按设备对象或 ID 从楼层移除设备，并同步清理检索索引。 |
 | `setColorAt(index, color)` / `getColorAt(index, target?)` | 修改或读取实例颜色，支持 `Color`、`Vector3`、`Vector4`。 |
 | `setOpacityAt(index, opacity)` / `getOpacityAt(index)` | 修改或读取实例透明度。 |
 | `setVisibleAt(index, visible)` / `getVisibleAt(index)` | 修改或读取实例显隐状态。 |

package/docs/changelog.md

@@ -4,6 +4,15 @@
 
 ### 新增
 
+- **u-manager semantics** — `BuildingGroup` 新增 `isolateFloors(floors)`，支持按多个 `FloorMesh` 或楼层下标同时隔离显示多个楼层；`isolateFloor()` 继续兼容单楼层调用，并可接收数组作为便捷写法。
+- **u-manager semantics** — `SemanticLoader` 新增 `Facilities` 解析：从 `Stories[].Facilities` 索引读取顶层设备语义，用 `Facility.ID` 匹配解密后的 `tree_models` 设备节点，沿父级累乘本地矩阵得到设备世界矩阵，加载 3D 设备模型并转换为楼层局部矩阵后挂载到对应 `FloorMesh`。
+- **u-manager semantics** — `FloorMesh` 新增楼层设备检索与统一语义实体 API：`getFacilityById()`、`getFacilityAt()`、`getFacilities()`、`removeFacility()`、`showAllFacilities()`、`hideAllFacilities()`、`getSemanticById()`、`getSemantics()` 和 `getSemanticsByKind('Facilities')`；`BuildingGroup.showAllFacilities()/hideAllFacilities()` 支持批量显示或隐藏整栋建筑内的楼层设备。
+- **u-space MCP** — 文档索引同步楼层 `Facilities` 解析和检索 API，MCP 客户端可检索设备按楼层挂载、`tree_models` 解密匹配、本地矩阵父级累乘和世界坐标转换规则。
+
+## 0.0.21
+
+### 新增
+
 - **u-manager semantics** — `SemanticLoader` 支持解析建筑级 `Elevators` 和 `Vents`，以 `Polygon.shape` 作为底面轮廓、`Elevation` 作为底面高度、`TotalHeight` 作为拉伸高度生成 `ExtrudeMesh`，并通过 `BuildingGroup.elevatorMeshes`、`BuildingGroup.ventMeshes` 及 add/get/remove 方法管理。
 
 ### 修复
@@ -11,6 +20,10 @@
 - **透明语义体块渲染** — 电梯井/通风井在渲染阶段沿法线轻微内收，`Spaces` 实例使用稳定 per-instance 渲染偏移抖动，缓解与墙体或完全重叠空间共面时的 z-fighting。
 - **atmosphere 插件** — 后处理链移除 aerial perspective 节点，保留 lens flare、tone mapping、temporal antialias 和 dithering；`scene.backgroundNode` 使用 `skyBackground()`，`scene.environmentNode` 使用 `skyEnvironment()`，并继续在关闭插件时恢复启用前的背景和环境节点。
 
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.21`，部署流程仍会优先按 `package.json` 注入当前版本。
+
 ## 0.0.18
 
 ### 变更
@@ -27,7 +40,7 @@
 ### 变更
 
 - **大气状态更新** — 大气插件在 `beforeRender` 中刷新相机 ECEF 位置、太阳/月亮方向和阴影 target，相机控制器驱动的移动也能逐帧更新大气状态。
-- **MCP 发布** — 根目录 MCP 发布入口合并为 `pnpm publish:mcp`，命令会先构建 `u-space-mcp` 文档索引，再发布 npm 包。
+- **MCP 发布** — 根目录 MCP 发布入口合并为 `pnpm publish:mcp`，命令会先递增 `u-space-mcp` 的 patch 版本，再构建文档索引并发布 npm 包。
 
 ## 0.0.16
 

package/docs/examples-guide.md

@@ -2,6 +2,12 @@
 
 `u-space` 的 `examples/` 目录中包含了大量演示引擎功能的示例。以下是几个关键示例及其所展示的系统特性。
 
+## 运行方式与版本
+
+示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.22`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.22` 作为直接托管 `examples/` 时的 fallback。
+
+插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
+
 ## 1. `demo01.html`：基础配置与交互
 
 该示例演示了通过 WebGPU 渲染 3D 场景所需的最少配置，与 [快速上手](./getting-started.md) 指南中的内容一致。

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

package/docs/index.md

@@ -52,7 +52,7 @@ features:
 | [keyboard-controls](./api-plugin-keyboard-controls) | WASD / 方向键控制相机移动与旋转 |
 | [minimap](./api-plugin-minimap) | 2D 小地图叠加层 |
 | [tiles](./api-plugin-tiles) | ArcGIS 3D 瓦片 / GIS 地球渲染 |
-| [u-manager](./api-plugin-u-manager) | 场景加载、语义楼层、语义井道、拓扑、动画、属性、视点管理 |
+| [u-manager](./api-plugin-u-manager) | 场景加载、语义楼层、语义井道、楼层设备、拓扑、动画、属性、视点管理 |
 | [curve-movement](./api-plugin-curve-movement) | 沿样条曲线移动相机或对象 |
 | [tracking-controls](./api-plugin-tracking-controls) | 相机跟随移动目标 |
 | [atmosphere](./api-plugin-atmosphere) | 天空背景、天空环境、太阳/月亮光照与阴影 |

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`、`BuildingGroup`、`FloorMesh` 语义楼层 API、电梯井/通风井语义体块，以及 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` 的 `SemanticLoader`、`BuildingGroup`、`FloorMesh` 语义楼层 API、楼层 `Facilities` 设备检索、电梯井/通风井语义体块，以及 atmosphere 插件的 `skyBackground()`、`skyEnvironment()` 和 RenderPipeline output effect 配置。
 
 ## 安装与启动
 
@@ -86,7 +86,7 @@ export const codingAgent = new Agent({
 
 ## 包结构
 
-源码位于 `packages/u-space-mcp`。根目录只保留一个 MCP 发布入口；执行时会先从 `docs/*.md` 生成内置文档索引，编译 MCP 包，然后发布到 npm：
+源码位于 `packages/u-space-mcp`。根目录只保留一个 MCP 发布入口；执行时会先递增 `u-space-mcp` 的 patch 版本，再从 `docs/*.md` 生成内置文档索引，编译 MCP 包，然后发布到 npm：
 
 ```bash
 pnpm publish:mcp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -29,7 +29,7 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:deploy": "pnpm docs:build && vercel --prod",
-    "publish:mcp": "pnpm --filter u-space-mcp build && npm publish ./packages/u-space-mcp --access public --ignore-scripts",
+    "publish:mcp": "npm --prefix ./packages/u-space-mcp version patch --no-git-tag-version && pnpm --filter u-space-mcp build && npm publish ./packages/u-space-mcp --access public --ignore-scripts",
     "release": "npm version patch && pnpm build && npm publish --access=public"
   },
   "files": [