@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.31

package/ai_guides/features/pano-uv.md

@@ -0,0 +1,131 @@
+# 全景图 UV 与方向转换 (Panorama UV Conversion)
+
+- **Summary**: 提供了一组工具方法，用于在**全景图 UV 坐标** (Equirectangular UV / Cubemap UV) 与**三维空间方向向量** (Vector3) 之间进行转换。
+- **Schema**: 依赖 `WorkObserver` 实例，提供四个核心转换方法。
+- **Concepts**: Equirectangular Projection, Cubemap Projection, UV Origin, Coordinate Systems.
+- **Configuration**: `uvOrigin` (UV 原点设置).
+- **Examples**: 向量转全景 UV、UV 转向量、Cubemap 转换。
+
+## Schema
+
+> **Definition**: [WorkObserver](../../five/work/work.d.ts)
+
+这些方法挂载在 `WorkObserver` 实例上，依赖当前观察点 (Observer) 的位姿信息 (Position & Quaternion) 以及 `work.transform` 进行计算。
+
+```typescript
+interface WorkObserver {
+  /**
+   * 将方向向量转化为全景图 uv
+   * @param vector - 全局方向向量 (World Space)
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+
+  /**
+   * 将全景图 uv 转化为方向向量
+   * @param uv - 全景图 UV 坐标 [0, 1]
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+
+  /**
+   * 将方向向量转化为六视图 uv
+   * @param vector - 全局方向向量 (World Space)
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [cubeFace: CubeFace, cubemapUv: THREE.Vector2];
+
+  /**
+   * 将六视图 uv 转化为方向向量
+   * @param cubeFace - 立方体面 ('up' | 'down' | 'left' | 'right' | 'front' | 'back')
+   * @param uv - 该面上的 UV 坐标 [0, 1]
+   * @param uvOrigin - UV 原点位置，默认为 'top-left'
+   */
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+}
+
+type CubeFace = 'up' | 'down' | 'left' | 'right' | 'front' | 'back';
+```
+
+## Concepts
+
+### 1. 坐标系转换 (Coordinate Transformation)
+转换过程会自动处理以下坐标空间的变换：
+1.  **World Space (世界坐标系)**: `vector` 参数所处的坐标系。
+2.  **Work Space (Work 坐标系)**: 考虑 `work.transform` 带来的整体旋转。
+3.  **Observer Space (观察者坐标系)**: 考虑 `observer.quaternion` 带来的观察点旋转。
+4.  **Panorama Space (全景图空间)**: 最终映射到 2D 图片上的 UV 坐标。
+
+### 2. 投影方式 (Projection Types)
+*   **Equirectangular (等距柱状投影)**: 将球体展开为 2:1 的矩形图片。常用于全景图预览。
+*   **Cubemap (立方体贴图)**: 将球体投影到立方体的六个面上。常用于高清全景浏览。
+
+### 3. UV 原点 (UV Origin)
+*   **top-left (默认)**: 原点 `(0, 0)` 在图片**左上角**。U 轴向右，V 轴向下。符合大多数 Web 图片处理习惯 (Canvas, DOM)。
+*   **bottom-left**: 原点 `(0, 0)` 在图片**左下角**。U 轴向右，V 轴向上。符合 WebGL / OpenGL 纹理坐标习惯。
+
+## Configuration
+
+所有方法均包含可选参数 `uvOrigin`。
+
+### Common Configuration
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `uvOrigin` | `'top-left' \| 'bottom-left'` | `'top-left'` | 指定 UV 坐标系的原点位置。 |
+
+## Examples
+
+### 1. 点击全景图获取空间方向 (Click to Vector)
+假设你有一个全景图的点击事件，获取到了点击位置的 UV：
+
+```typescript
+const observer = five.work.observers[0];
+// 假设这是用户点击全景图后归一化得到的 UV (0~1)
+const clickUv = new THREE.Vector2(0.5, 0.5);
+
+// 转换为世界空间的方向向量
+const direction = observer.equirectangularUvToVector(clickUv);
+
+console.log('点击方向:', direction);
+```
+
+### 2. 将空间点映射到全景图上 (World Point to UV)
+假设场景中有一个 3D 物体，你想知道它在当前全景图上的位置（例如打标签）：
+
+```typescript
+const observer = five.work.observers[0];
+const objectPosition = new THREE.Vector3(10, 2, 5);
+
+// 计算物体相对于观察点的方向向量
+const direction = objectPosition.clone().sub(observer.position).normalize();
+
+// 获取全景图 UV
+const uv = observer.vectorToEquirectangularUv(direction);
+
+console.log(`物体在全景图上的位置: u=${uv.x}, v=${uv.y}`);
+```
+
+### 3. 处理 Cubemap 坐标 (Cubemap Conversion)
+如果你使用的是六面体全景图资源：
+
+```typescript
+const observer = five.work.observers[0];
+const direction = new THREE.Vector3(0, 0, -1); // 正前方
+
+// 获取对应的面和 UV
+const [face, uv] = observer.vectorToCubemapUv(direction);
+
+console.log(`正前方对应 Cubemap 的 ${face} 面，UV 为`, uv);
+```
+
+## Related
+
+*   [Work](./work.md): 了解 WorkObserver 的数据结构。
+*   [Coordinate System](./coordinate-system.md): 了解 Five 的坐标系定义。
+
+---
+
+```yaml
+tags: [全景UV, 方向转换, 全景坐标, 像素映射, 全景标注, work, observer, uv, projection, math, equirectangular, cubemap]
+```

package/ai_guides/features/parameter.md

@@ -1,102 +1,109 @@
-# Parameter (配置)
+# Parameter (配置系统)
 
 - **Summary**: Five 用于控制三维模型渲染表现的核心配置系统，采用树形继承设计。
-- **Schema**: 包含材质、楼层、阴影、LOD 等配置项。
-- **Concepts**: Hierarchy (树形继承), Material, LOD, Point Cloud。
-- **Examples**: 全局设置与局部差异化配置。
+- **Schema**: 是所有配置项的容器，通过继承机制管理 Material 和 3DTile 等子配置。
+- **Concepts**: Hierarchy (树形继承), Override (覆盖), Resolution (解析)。
+- **Examples**: 全局配置、局部覆盖、参数重置。
 
 ## Schema
 
-### Parameter Class
+> **Definition**: [Parameter](../../five/model/parameter.d.ts)
 
-`Parameter` 是一个配置容器，提供了读写配置项的方法。
+`Parameter` 类是配置的入口。它并不直接包含所有配置字段的定义，而是将它们组织在不同的接口中。
+
+### Parameter Categories (参数分类)
+
+为了便于理解，我们将参数分为两大类：
+
+| Category | Description | Link |
+| :--- | :--- | :--- |
+| **Material & Appearance** | 控制“长什么样”。包括材质、颜色、楼层显示、阴影、点云样式等。 | [Material Params](./material.md) |
+| **3DTile & Performance** | 控制“怎么加载”。包括 LOD (细节层级)、显存配额、网络并发、SSE 阈值等。 | [3DTile Params](./3dtile.md) |
+
+### Parameter Class API
+
+#### 1. Getting Values (获取值)
+
+获取参数值**不使用** `get()` 方法，而是直接访问属性。
+
+*   **Direct Access (直接访问)**: 获取当前 `Parameter` 实例上设置的值。如果未设置，返回 `undefined`。
+*   **Resolve Value (计算最终值)**: 获取经过树形继承计算后的最终生效值。
+    *   如果不传参，则基于默认值计算 (Default -> Current)。
+    *   如果传入上游 Parameter，则基于默认值 + 上游 Parameter 计算 (Default -> Upstream -> Current)。
 
 ```typescript
-// 简化定义
-class Parameter implements Readonly<Partial<ParameterValue>> {
-  // 可以直接通过属性访问配置项，例如 parameter.opacity
-  readonly [key in keyof ParameterValue]?: ParameterValue[key];
+// 方式 A: 直接访问 (获取当前层级配置)
+const currentVal = parameter.maxMemoryUsage;
+
+// 方式 B: 计算最终值 (包含继承逻辑)
+
+// 1. 基础用法：仅继承默认值
+const finalVal = parameter.resolveValue().maxMemoryUsage;
 
-  /** 设置配置项 */
-  set<K extends keyof ParameterValue>(key: K, value: ParameterValue[K]): void;
-  set(values: Partial<ParameterValue>): void;
+// 2. 进阶用法：指定继承源 (例如 ViewLayer 继承自 Model)
+const inheritedVal = viewLayerParam.resolveValue(parentParameter).maxMemoryUsage;
+```
+
+#### 2. Methods (方法)
+
+`Parameter` 实例提供了以下核心方法来管理配置：
 
-  /** 重置当前层级的配置项 (恢复继承) */
-  reset(...keys: (keyof ParameterValue)[]): void;
+```typescript
+class Parameter {
+  /**
+   * 设置配置项
+   * @param key 参数名 (如 'opacity', 'maxMemoryUsage')
+   * @param value 参数值
+   */
+  set(key: string, value: any): void;
+
+  /**
+   * 重置配置项（移除当前层级的设置，恢复继承上游的值）
+   * @param keys 要重置的参数名列表
+   */
+  reset(...keys: string[]): void;
 
   /**
-   * 获取最终计算值 (包含继承逻辑)
-   * @param upstream - 上游 Parameter 对象列表
+   * 获取经过继承计算后的最终值（每次调用创建新对象）
+   * @param upstream 上游 Parameter 对象列表（通常由引擎自动传入）
    */
   resolveValue(...upstream: Parameter[]): ResolvedParameterValue;
+
+  /**
+   * 获取经过继承计算后的最终值（复用 target 对象，避免重复创建）
+   * 适用于高频调用场景（如逐帧更新），可显著减少 GC 压力。
+   * @param target 用于写入结果的已有对象，其属性会被重置为默认值后重新赋值
+   * @param upstream 上游 Parameter 对象列表
+   */
+  static resolveValueTo(
+    target: Partial<ResolvedParameterValue>,
+    ...upstream: Partial<ParameterValue>[]
+  ): ResolvedParameterValue;
 }
 ```
 
-### ParameterValue Interface
+> `resolveValue()` 内部已委托给 `resolveValueTo({}, ...)`，两者计算逻辑一致，区别仅在于是否复用对象。
 
-所有的配置项定义在 `ParameterValue` 接口中。
+#### 3. Version (版本标识)
+
+`ResolvedParameterValue` 通过 `versionNumber: number` 标识当前配置的版本。引擎内部使用整数哈希（而非字符串拼接）计算版本号，用于高效的脏检查。
 
 ```typescript
-import * as THREE from 'three';
-
-export interface ParameterValue {
-  // --- 基础材质表现 ---
-  /** 模型透明度 [0-1] */
-  opacity: number;
-  /** 模型整体亮度 */
-  brightness: number;
-  /** 颜色饱和度调整 */
-  colorSaturation: number;
-  /** 颜色亮度调整 */
-  colorBrightness: number;
-
-  // --- 全景混动与过渡 ---
-  /** 模型贴图和全景图的混合程度 [0-1] (0:纯模型纹理, 1:纯全景纹理) */
-  modelAlpha: number;
-
-  // --- 楼层控制 ---
-  /** 当前显示的楼层索引 (null 为显示所有) */
-  shownFloorIndex: number | null;
-  /** 楼层隐藏样式 ('OPACITY': 透明, 'VISIBILITY': 隐藏) */
-  floorStyle: 'OPACITY' | 'VISIBILITY';
-
-  // --- 阴影 ---
-  /** 是否产生阴影 */
-  castShadow: boolean;
-  /** 是否接受阴影 */
-  receiveShadow: boolean;
-
-  // --- 点云特有 ---
-  /** 点云大小 */
-  pointSize: number;
-  /** 点云基础缩放 */
-  pointScale: number;
-
-  // --- 3DTile / LOD 控制 ---
-  /** 最小细节层级 */
-  minLevelOfDetail: number;
-  /** 最大细节层级 */
-  maxLevelOfDetail: number;
-  /** 几何误差阈值 (越小越精细) */
-  minGeometricError: number;
-  /** 最大网络并发请求数 */
-  maxRequests: number;
-  /** 最大内存使用量 (MB) */
-  maxMemoryUsage: number;
-
-  // ... 更多高级参数请参考 five/index.d.ts
+interface ResolvedParameterValue extends ParameterValue {
+  /** 整数哈希，输入参数变化时值会改变，用于脏检查 */
+  versionNumber: number;
 }
 ```
 
 ## Concepts
 
-### 1. 树形继承关系 (Hierarchy)
+### 树形继承关系 (Hierarchy)
 
-Parameter 遵循 **“就近原则” (Override)** 的继承逻辑。当渲染引擎需要获取某个属性值时，会按照以下顺序查找：
+Parameter 遵循 **“就近原则” (Override)** 的继承逻辑。
 
-1.  **ViewLayer Parameter**: 最具体，优先级最高。
-2.  **Model Parameter**: 覆盖该 Model 下的所有 ViewLayer。
-3.  **ModelScene Parameter**: 全局默认值，优先级最低。
+1.  **ViewLayer Parameter**: 最具体，优先级最高。通常对应一个具体的 `.gltf` 文件或数据块。
+2.  **Model Parameter**: 覆盖该 Model 下的所有 ViewLayer。一个 Model 可能包含多个 ViewLayer (如 Mesh 层和 PointCloud 层)。
+3.  **ModelScene Parameter**: 全局默认值，优先级最低。影响整个场景。
 
 ```mermaid
 graph TD
@@ -105,74 +112,66 @@ graph TD
   Model -->|Inherit| Layer2[ViewLayer.parameter]
 ```
 
-**示例逻辑**:
-*   如果 `ModelScene` 设置 `opacity = 0.5`，所有模型都会变半透明。
-*   如果此时 `Model A` 设置 `opacity = 1.0`，那么 `Model A` 及其下的 ViewLayer 会变为不透明，而其他 Model 保持半透明。
-
-### 2. 参数分类
+> **Global Configuration (全局设置)**:
+> 若需修改所有模型的默认表现（如统一调暗亮度、统一设置显存上限），**请直接配置 `five.modelScene.parameter`**。它是继承链的根节点，其设置会向下传递给所有 Model 和 ViewLayer。
+>
+> **Why modelScene? (生命周期优势)**:
+> `Model` 实例是跟随 Work 加载生命周期的（需 `five.load(work)` 后才能访问，且切换 Work 会销毁重建）。
+> 相比之下，`ModelScene` 是常驻对象。因此，**使用 `modelScene` 进行配置更安全且持久**，既无需等待 Work 加载完成，也无需担心切换 Work 导致配置丢失。
 
-#### 材质与外观 (Material & Appearance)
-控制模型“长什么样”。比如：
-*   **`modelAlpha`**: 核心参数。Five 的模型纹理通常来自全景图投影。该值控制是显示原始模型 UV 贴图，还是显示全景投影贴图。
-*   **`shownFloorIndex`**: 实现“分层拆解”效果。
-*   **`floorStyle`**: 控制楼层隐藏的表现形式。
+## Examples
 
-#### 3DTile & 性能 (LOD)
-控制模型“怎么加载”。比如：
-*   **`maxMemoryUsage`**: 显存控制。当加载的模型块超过此限制时，会自动卸载不可见的块。
-*   **`maxScreenSpaceError`**: 画质控制。值越小，加载的模型精度越高（允许的屏幕空间误差越小），但网络和渲染开销越大。
-*   **`minGeometricError`**: 几何误差阈值。值越小，加载的模型精度越高（允许的几何误差越小），但网络和渲染开销越大。
-*   **`maxRequests`**: 最大并发请求数。控制同时加载的模型块数量，避免对服务器压力过大。
+### 1. 基础配置 (Basic Usage)
 
-#### 点云 (Point Cloud)
-专用于 `type: point_cloud` 的 ViewLayer。比如：
-*   **`pointSize`**: 控制点的像素大小。
-*   **`pointScale`**: 点云整体缩放。
+```typescript
+// 1. 设置全局最大显存 (影响所有模型)
+five.modelScene.parameter.set('maxMemoryUsage', 512);
 
-## Examples
+// 2. 设置全局半透明
+five.modelScene.parameter.set('opacity', 0.5);
+```
 
-### 基础用法：设置全局透明度
+### 2. 局部覆盖 (Override)
 
 ```typescript
-// 将整个场景的模型设为半透明
-five.modelScene.parameter.set('opacity', 0.5);
+// 场景中大部分模型不产生阴影
+five.modelScene.parameter.set('castShadow', false);
 
-// 恢复默认
-five.modelScene.parameter.remove('opacity');
+// 但让特定的“主角”模型产生阴影
+const heroModel = five.models[0];
+heroModel.parameter.set('castShadow', true);
 ```
 
-### 进阶用法：差异化配置
+### 3. 重置配置 (Reset)
 
 ```typescript
-// 1. 全局开启阴影
-five.modelScene.parameter.set('castShadow', true);
+// 假设之前设置了 opacity
+five.modelScene.parameter.set('opacity', 0.5);
 
-// 2. 但让第一个模型不产生阴影
-const mainModel = five.models[0];
-if (mainModel) {
-  mainModel.parameter.set('castShadow', false);
-}
+// ... 一段时间后 ...
 
-// 3. 让特定的点云图层点变大
-const pointCloudLayer = mainModel.viewLayers.find(l => l.type === 'point_cloud');
-if (pointCloudLayer) {
-  pointCloudLayer.parameter.set('pointSize', 2.0);
-}
+// 移除该设置，恢复默认值 (或继承值)
+five.modelScene.parameter.reset('opacity');
 ```
 
-## Common Pitfalls
+### 4. 获取配置 (Get Value)
+
+```typescript
+// 获取当前对象上的配置（如果未设置，则为 undefined）
+const ownOpacity = five.modelScene.parameter.opacity;
 
-1.  **拼写错误**: `parameter.set()` 的 key 是字符串，拼写错误不会报错（除非使用 TypeScript），但配置不会生效。
-2.  **层级混淆**: 在 `ModelScene` 上设置了 `shownFloorIndex`，却期望只影响某个 Model。请务必确认操作的 `parameter` 对象所属的层级。
-3.  **类型错误**: 某些数值参数（如 `opacity`）需要 `number` 类型，传入字符串可能导致渲染计算 NaN 错误。
+// 获取最终生效的配置（计算继承链后的值）
+const finalOpacity = five.modelScene.parameter.resolveValue().opacity;
+```
 
 ## Related
 
-*   [Model](./model.md): Parameter 的宿主之一。
-*   [3DTile](./3dtile.md): 受 Parameter 控制的底层技术。
+*   [Material Parameters](./material.md): 材质与外观参数详情。
+*   [3DTile Parameters](./3dtile.md): 性能与加载参数详情。
+*   [Model](./model.md): Parameter 的宿主。
 
 ---
 
 ```yaml
-tags: [parameter, config, appearance, 3dtile]
+tags: [配置, 参数, 继承, 覆盖, 全局配置, 局部配置, parameter, config, hierarchy, api, set, reset, modelScene]
 ```

package/ai_guides/features/plugin.md

@@ -0,0 +1,210 @@
+# 插件系统 (Plugin System)
+
+- **Summary**: Five 插件系统基于 `BasePlugin` 命名空间构建，提供了一套标准化的状态管理、生命周期控制和事件通信机制。
+- **Schema**: 核心类型定义位于 `BasePlugin` 命名空间。
+- **Concepts**: BasePlugin, State, Lifecycle, Controller.
+- **Configuration**: 插件特定的参数配置。
+- **Examples**: 标准插件开发示例。
+
+## Schema
+
+> **Definition**: [BasePlugin](../../plugins/BasePlugin/index.d.ts)
+
+`BasePlugin` 是一个命名空间，包含 `Controller` (抽象基类), `State` (状态接口), `EventMap` (事件映射) 等核心定义。
+
+```typescript
+export namespace BasePlugin {
+  export interface State {
+    enabled: boolean
+    visible?: boolean
+    config?: unknown
+  }
+  export abstract class Controller<PluginState, PluginEventMap, PluginServerData, PluginData> {
+    public five: Five
+    public abstract state: PluginState
+    public hooks: Subscribe<PluginEventMap>
+    // ...
+  }
+}
+```
+
+## Concepts
+
+### Directory Structure (目录结构)
+
+一个标准的插件通常包含以下文件：
+
+```text
+PluginName/
+  ├── index.ts        # 插件入口，导出工厂函数和类型
+  ├── Controller.ts   # 插件控制器，核心逻辑实现
+  └── typing.ts       # 类型定义
+```
+
+### BasePlugin
+
+所有插件推荐继承 `BasePlugin.Controller`。它定义了规范的泛型接口：
+
+- `PluginState`: 插件状态类型，继承自 `BasePlugin.State`。
+- `PluginEventMap`: 插件事件类型，继承自 `BasePlugin.EventMap`。
+- `PluginServerData`: 服务端原始数据类型。
+- `PluginData`: 解析后的插件数据类型。
+
+### State (状态)
+
+插件的状态驱动其行为。`BasePlugin.State` 定义了最基本的状态：
+
+- `enabled`: 是否启用。
+- `visible`: UI 是否可见。
+- `config`: 配置项。
+
+### Lifecycle (生命周期)
+
+插件的主要生命周期方法：
+
+- **constructor**: 初始化配置和初始状态。
+- **load**: 加载和解析数据。
+- **enable**: 启用插件，注册事件监听，添加副作用。
+- **disable**: 禁用插件，移除事件监听，清理副作用。
+- **dispose**: 销毁插件，彻底清理资源。
+
+## Configuration
+
+### BasePlugin Configuration
+
+`BasePlugin` 控制器构造函数接受可选的配置对象：
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `staticPrefix` | `string` | `'//vr-image-4.realsee-cdn.cn'` | 静态资源前缀。 |
+| `i18n` | `(key: string) => string` | `undefined` | 国际化转换函数。 |
+
+## Examples
+
+### Plugin Development Walkthrough (插件开发指南)
+
+以创建一个 `MyPlugin` 为例。
+
+#### 1. 定义类型 (typing.ts)
+
+定义插件所需的参数、状态、数据和事件类型。
+
+```typescript
+import { BasePlugin } from '../BasePlugin'
+
+// 1. 定义参数
+export interface Params extends BasePlugin.Config {
+  initialState?: Partial<State>
+  config?: Config
+}
+
+// 2. 定义配置
+export interface Config {
+  color?: string
+}
+
+// 3. 定义状态 (继承 BasePlugin.State)
+export interface State extends BasePlugin.State {
+  activeId?: string
+}
+
+// 4. 定义数据类型
+export interface ServerData { /* 服务端数据结构 */ }
+export interface PluginData { /* 解析后的数据结构 */ }
+
+// 5. 定义事件 (继承 BasePlugin.EventMap)
+export interface EventMap extends BasePlugin.EventMap<State, PluginData> {
+  click: (id: string) => void
+}
+```
+
+#### 2. 实现控制器 (Controller.ts)
+
+继承 `BasePlugin.Controller` 并实现核心逻辑。
+
+```typescript
+import { Five } from '@realsee/five'
+import { BasePlugin } from '../BasePlugin'
+import * as MyPluginType from './typing'
+
+export class Controller extends BasePlugin.Controller<
+  MyPluginType.State,
+  MyPluginType.EventMap,
+  MyPluginType.ServerData,
+  MyPluginType.PluginData
+> {
+  public state: MyPluginType.State
+
+  constructor(five: Five, params?: MyPluginType.Params) {
+    super(five)
+    this.state = {
+      enabled: true,
+      visible: true,
+      ...params?.initialState
+    }
+    if (this.state.enabled) {
+      this._enable()
+    }
+  }
+
+  public async load(serverData: MyPluginType.ServerData) {
+    // 解析数据
+  }
+
+  public enable() {
+    if (this.state.enabled) return
+    this.state.enabled = true
+    this._enable()
+    this.hooks.emit('stateChange', { state: this.state, userAction: true })
+  }
+
+  public disable() {
+    if (!this.state.enabled) return
+    this.state.enabled = false
+    this._disable()
+    this.hooks.emit('stateChange', { state: this.state, userAction: true })
+  }
+
+  public dispose = () => {
+    this.disable()
+    this.hooks.emit('dispose')
+  }
+
+  private _enable() {
+    // five.scene.add(...)
+    // five.on('tap', this.onTap)
+  }
+
+  private _disable() {
+    // five.scene.remove(...)
+    // five.off('tap', this.onTap)
+  }
+}
+```
+
+#### 3. 导出插件 (index.ts)
+
+提供一个工厂函数。
+
+```typescript
+import { Five } from '@realsee/five'
+import { Controller } from './Controller'
+import * as MyPluginType from './typing'
+
+export const MyPlugin = (five: Five, params?: MyPluginType.Params) =>
+  new Controller(five, params)
+
+export type { MyPluginType, Controller as MyPluginController }
+```
+
+## Common Pitfalls (最佳实践)
+
+1. **状态驱动**: 始终通过修改 `state` 来驱动插件行为，而不是直接操作 DOM 或 3D 对象。
+2. **清理资源**: 在 `disable` 和 `dispose` 中务必清理所有事件监听和副作用，防止内存泄漏。
+3. **类型安全**: 充分利用 TypeScript 泛型，确保事件和状态的类型安全。
+
+---
+
+```yaml
+tags: [插件, 插件开发, 扩展, 自定义功能, 状态管理, plugin, baseplugin, development, guide, extension, lifecycle]
+```