@realsee/five 6.8.0-alpha.8 → 6.8.0

package/AGENTS_READ_ME.md

@@ -1,4 +1,9 @@
 # AI_CONTEXT
 You are an AI assistant.
 This package contains comprehensive local documentation.
-DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`
+DO NOT search the web for documentation.
+
+**START HERE → Read [llms.txt](./llms.txt)** for a context-optimized index with scenario-based lookup and keyword tags.
+
+For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+Do NOT use the `docs/` directory (auto-generated HTML).

package/AI_CONTEXT.md

@@ -1,4 +1,9 @@
 # AI_CONTEXT
 You are an AI assistant.
 This package contains comprehensive local documentation.
-DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`
+DO NOT search the web for documentation.
+
+**START HERE → Read [llms.txt](./llms.txt)** for a context-optimized index with scenario-based lookup and keyword tags.
+
+For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+Do NOT use the `docs/` directory (auto-generated HTML).

package/README.md

@@ -5,8 +5,14 @@
 贝壳如视三维渲染框架
 
 > **🤖 For AI Assistants (Copilot, Cursor, etc.):**
-> If this package is installed in your project, you can find **AI-friendly documentation** directly in `node_modules/@realsee/five/`. Please **READ** `node_modules/@realsee/five/ai_guides/README.md` as your primary source of truth. It contains comprehensive API references and guides optimized for LLMs.
-> If not installed locally, you can access the same documentation via `https://cdn.jsdelivr.net/npm/@realsee/five@alpha/ai_guides/README.md` or `https://unpkg.com/@realsee/five@alpha/ai_guides/README.md`.
+> **START HERE → Read [llms.txt](./llms.txt)** for a context-optimized documentation index with scenario-based lookup.
+> For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+> Do NOT use `docs/` directory (auto-generated HTML, redundant and hard to parse).
+>
+> If this package is installed locally, read `node_modules/@realsee/five/llms.txt` directly.
+> If not installed, use a CDN mirror:
+> - `https://cdn.jsdelivr.net/npm/@realsee/five@latest/llms.txt`
+> - `https://unpkg.com/@realsee/five@latest/llms.txt`
 ## Introduction
 
 **Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
@@ -66,7 +72,8 @@ For comprehensive guides and API references, please refer to the documentation i
 
 **⚠️ Note for AI Agents:**
 
-*   **For a context-optimized index, read [llms.txt](./llms.txt).**
+*   **START HERE → [llms.txt](./llms.txt)** — context-optimized index with scenario → doc mapping and keyword tags.
+*   If you need the full documentation map, read [ai_guides/README.md](ai_guides/README.md).
 
 **Do's (推荐):**
 *   **Do** Read [Intro](ai_guides/intro.md) first to understand the high-level architecture.

package/ai_guides/README.md

@@ -74,10 +74,11 @@
 *   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
 *   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
 *   [Postprocessing](./features/postprocessing.md): 后处理效果 (Pass, EffectComposer)。
-*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效。
-*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 基于模型深度的流光特效。
+*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效(InstancedMesh 优化)。
+*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 3D 世界坐标流光特效(InstancedMesh 优化)。
 *   [Gaussian Blur Pass](./features/gaussian-blur-pass.md): 高斯模糊特效。
 *   [Material](./features/material.md): 材质参数配置 (透明度、点云大小、顶点标记)。
+*   [Pano Filter](./features/pano-filter.md): 全景图滤镜 (亮度、对比度、色温调节)。
 *   [Get Screen Pixels](./features/get-screen-pixels.md): 获取屏幕像素 (放大镜/截图)。
 *   [Move Pano Effect](./features/move-pano-effect.md): 全景点位切换的过渡效果。
 *   [Clipper](./features/clipper.md): 模型裁切功能 (房屋剖面)。
@@ -107,6 +108,34 @@
     *   [6.7](./release_notes/6.7.md)
     *   [6.6](./release_notes/6.6.md)
 
+## Common Scenarios (场景 → 文档速查)
+
+> **Keyword Search Tip:** Each doc in `features/` has a `tags` yaml block at the bottom with Chinese and English keywords. Use these for keyword matching when the scenario table below doesn't cover your need.
+
+| Scenario | Docs | Tags |
+| :--- | :--- | :--- |
+| 点击拾取物体 / Object picking | [Raycast](./features/raycast.md) | click, hit-test, floor-detection, 碰撞检测, 物体选择 |
+| 3D 标签 / HTML overlay on 3D point | [Screen Project](./features/screen-project.md) | label, HUD, tooltip, 坐标转换, 3D转2D |
+| 全景滤镜 / 色温调节 / Color correction | [Pano Filter](./features/pano-filter.md) | warm, cool, brightness, contrast, saturation, 暖色, 冷色, 饱和度 |
+| 加载外部 GLTF/OBJ/FBX 模型 | [Load External Model](./features/load-external-model.md) | gltf, glb, ply, splat, fbx, draco, point-cloud, dispose |
+| 相机巡航 / 自动导览 / Camera fly-through | [Camera Animation](./features/camera-animation.md) | rotate, zoom, auto-tour, 运镜, 旋转, 缩放 |
+| 截图 / 放大镜 / Screen capture | [Get Screen Pixels](./features/get-screen-pixels.md) | magnifier, screenshot, color-picker, 取色器 |
+| 模型裁切 / 房屋剖面 | [Clipper](./features/clipper.md) | clipping-box, section-view, discard, 开盖, 剖面 |
+| 流光特效 / Flowing light effect | [Flowing Light 2D](./features/flowing-light-2d-pass.md), [Flowing Light 3D](./features/flowing-light-3d-pass.md) | 光带, 导航路径, 动态路径, instanced |
+| 模糊特效 / Blur effect | [Gaussian Blur Pass](./features/gaussian-blur-pass.md) | 毛玻璃, 背景虚化, gaussian |
+| 保存/恢复场景状态 | [State](./features/state.md) | snapshot, save, restore, 快照, 场景还原 |
+| 多场景切换 / 沙盘 | [Multi-Work](./features/multi-work.md) | sandbox, 多户型, 拼接, workCode |
+| 请求鉴权 / CDN 替换 | [Request Proxy](./features/request-proxy.md) | authentication, token, url-rewrite, cors, 私有化 |
+| 插件开发 | [Plugin](./features/plugin.md) | lifecycle, extension, baseplugin, 状态管理 |
+| 事件监听 / 拦截默认行为 | [Event](./features/event.md) | preventDefault, waitUntil, on, off, gesture, 回调 |
+| 手势交互 / 自定义拖拽 | [Gesture](./features/gesture.md) | tap, pan, pinch, press, 触摸, 鼠标 |
+| 后处理特效 / 自定义 Shader | [Postprocessing](./features/postprocessing.md) | effect-composer, addPass, edl, 描边, 景深 |
+| 材质 / 透明度 / 点云样式 | [Material](./features/material.md) | opacity, pointcloud, roof, ceiling, 天花板, 顶点标记 |
+| 模式切换 / 全景↔模型↔户型图 | [Mode](./features/mode.md) | panorama, floorplan, mapview, topview, VR |
+| 全景高清瓦片 / 分片加载 | [Pano Tile](./features/pano-tile.md) | LOD, tile, 按需加载, 高清全景 |
+| 图片 CDN / 私有化部署 | [Image Options](./features/image-options.md) | avif, webp, cdn, private-deployment |
+| 加载进度 / 首屏优化 | [Load Progress](./features/load-progress.md) | refined, loaded, loading-bar, 首屏 |
+
 ## Terminology Summary
 
 *   **Work**: 包含全景图、模型、户型数据的 JSON 对象。
@@ -119,3 +148,4 @@
 ```yaml
 tags: [index, readme, guide, map]
 ```
+

package/ai_guides/api.md

@@ -64,9 +64,12 @@ interface FiveInitArgs {
   /** Max FPS limit. false = unlimited. Default: false */
   maxFps?: number | false;
 
-  /** Mode transition duration in ms. Default: 800 */
+  /** Mode transition duration in ms. Default: 1000 */
   modeChangeDuration?: number;
 
+  /** Enable mouse wheel zoom. Default: true */
+  enableWheel?: boolean;
+
   /** Initial plugins to load. */
   plugins?: FivePlugin[];
 
@@ -75,9 +78,24 @@ interface FiveInitArgs {
 
   /** Dynamic texture configuration for optimization. */
   textureOptions?: TextureOptions;
+
+  /** Request URL interceptor for auth/CDN. */
+  requestProxy?: (url: string) => string | Promise<string>;
+
+  /** Per-mode configuration (panorama, mapview, floorplan, topview, model). */
+  panorama?: PanoramaConfig;
+  mapview?: MapviewConfig;
+  floorplan?: FloorplanConfig;
+  topview?: TopviewConfig;
+  model?: ModelConfig;
 }
 ```
 
+> 详细的模式配置参数见 [Mode](./features/mode.md#configuration)。
+> 图片加载策略见 [ImageOptions](./features/image-options.md)。
+> 请求代理见 [Request Proxy](./features/request-proxy.md)。
+> 完整初始化参数见 [Five](./features/five.md) 和 [Parameter](./features/parameter.md)。
+
 ## Core Methods
 
 ### `load(work, state?, options?)`
@@ -85,7 +103,9 @@ Loads a "Work" (dataset) into the Five instance.
 
 - **work**: The data object (`LooseWork` or `Work`) containing scene information.
 - **state**: Initial state overrides. `"inherit"`, `"initial"`, or a `State` object.
-- **options**: Loading options (e.g., transition duration).
+- **options**: Loading options (e.g., transition duration, `mode: "add" | "replace"`).
+
+> 详见 [Work](./features/work.md) 和 [Multi-Work](./features/multi-work.md)。
 
 ### `appendTo(element, size?)`
 Mounts the Five canvas to a DOM element.
@@ -100,6 +120,8 @@ Updates the current state (position, mode, etc.).
 - **immediately**: If `true`, skips animation.
 - **userAction**: Marks the change as triggered by user interaction.
 
+> 详见 [State](./features/state.md)。
+
 ### `changeMode(mode, state?, options?)`
 Switches the viewing mode (e.g., from `Panorama` to `Model`).
 
@@ -107,11 +129,29 @@ Switches the viewing mode (e.g., from `Panorama` to `Model`).
 - **state**: Target state after mode change.
 - **options**: Animation duration and effect.
 
+> 详见 [Mode](./features/mode.md)。
+
 ### `moveToPano(panoIndex, options?)`
 Moves to a specific panorama spot.
 
 - **panoIndex**: Index of the panorama.
-- **options**: `{ effect?: MovePanoEffect, duration?: number }`.
+- **options**: `{ effect?: MovePanoEffect, duration?: number, effectEasing?: Function }`.
+
+> 详见 [Move Pano Effect](./features/move-pano-effect.md) 和 [Camera Animation](./features/camera-animation.md)。
+
+### `updateCamera(pose, duration, userAction?)`
+Animates the camera to a target pose without changing pano index.
+
+- **pose**: Partial `Pose` object (longitude, latitude, fov, etc.).
+- **duration**: Animation duration in ms.
+- **returns**: `Promise<void>` (rejects if interrupted).
+
+> 详见 [Camera Animation](./features/camera-animation.md)。
+
+### `ready(args?)`
+Returns a Promise that resolves when Five is stable (state synced, model loaded, optionally tiles loaded).
+
+- **args**: `{ tile?: boolean }` — if `tile: true` in Panorama mode, waits for tile loading.
 
 ### `refresh(size?)`
 Resizes the renderer to fit the container or specified size.
@@ -126,28 +166,35 @@ Projects a 3D point to 2D screen coordinates.
 - **testModel**: `boolean` (default `false`). If `true`, checks for occlusion.
 - **returns**: `THREE.Vector2` (Screen Space, px) or `null`.
 
-### `getPixels(x, y, width, height)`
+> 详见 [Screen & Space Projection](./features/screen-project.md)。
+
+### `getPixels(options)`
 Get pixel data from the renderer (e.g. for color picking or magnifier).
 
-- **x, y**: Coordinate of the lower-left corner (Screen Space).
-- **width, height**: Size of the rectangle.
+- **options**: `{ x, y, width, height, pixelRatio?, flipY?, buffer?, skipPanorama?, helperVisible? }`
 - **returns**: `Uint8Array` (RGBA data).
 
+> 详见 [Get Screen Pixels](./features/get-screen-pixels.md)。
+
 ### `intersectRaycaster(raycaster)`
 (On `five.model`) Performs raycasting against the scene models.
 
-- **raycaster**: `THREE.Raycaster`.
-- **returns**: `THREE.Intersection[]`.
+- **raycaster**: `THREE.Raycaster` (supports extended props: `firstHitOnly`, `hitFilter`, `sortByDistance`, `floorIndex`).
+- **returns**: `THREE.Intersection[]` (extended with `tile`, `viewLayer`, `model` fields).
 
-### `addPass(pass)`
-Add a post-processing pass to the rendering chain.
+> 详见 [Raycast](./features/raycast.md)。
 
-- **pass**: `FivePass` instance (e.g. `Gaussian Blur Pass`).
+### `addPass(pass)` / `removePass(pass)`
+Add or remove a post-processing pass to/from the rendering chain.
 
-### `removePass(pass)`
-Remove a post-processing pass from the rendering chain.
+- **pass**: `FivePass` instance (e.g. `GaussianBlurPass`, `FlowingLight2DPass`).
 
-- **pass**: `FivePass` instance to remove.
+> 详见 [Postprocessing](./features/postprocessing.md)。
+
+### `updateConfiguration(config)`
+Dynamically update mode configurations after initialization (e.g., panorama, mapview settings).
+
+> 详见 [Mode](./features/mode.md#动态修改配置-update-configuration)。
 
 ### `dispose()`
 Destroys the Five instance and releases resources.
@@ -171,6 +218,8 @@ interface State {
 
 ## Data Structures
 
+> 以下为核心数据结构摘要。完整定义见 [Work](./features/work.md)、[State](./features/state.md)、[Model](./features/model.md)。
+
 ### `Work`
 The main data object containing the scene description.
 
@@ -224,10 +273,17 @@ These events follow a standard naming convention and provide typed event objects
 
 | Event Name | Description | Payload |
 | :--- | :--- | :--- |
-| `gesture.tap` | Triggered on tap/click. Replaces `wantsTapGesture`. | `{ pointers, event, ... }` |
-| `gesture.pan` | Triggered on pan/drag. | `{ pointers, ... }` |
-| `gesture.pinch` | Triggered on pinch/zoom. | `{ scale, ... }` |
-| `gesture.press` | Triggered on long press. | `{ pointers, ... }` |
+| `gesture.tap` | Triggered on tap/click. Replaces `wantsTapGesture`. | `GestureEvent` |
+| `gesture.dbltap` | Triggered on double tap/click. | `GestureEvent` |
+| `gesture.pan` | Triggered on pan/drag. | `GestureEvent` |
+| `gesture.pinch` | Triggered on pinch/zoom. | `GestureEvent` |
+| `gesture.press` | Triggered on long press. | `GestureEvent` |
+| `gesture.mousewheel` | Triggered on mouse wheel scroll. | `GestureEvent` |
+| `gesture.mousemove` | Triggered on mouse move. | `GestureEvent` |
+| `gesture.momentum` | Triggered on inertia movement after pan. | `GestureEvent` |
+| `gesture.fire` | Triggered when any gesture event fires. | `GestureEvent` |
+
+> 手势事件详解及不同 Mode 下的默认行为见 [Gesture](./features/gesture.md)。
 
 #### State & Mode
 
@@ -237,19 +293,34 @@ These events follow a standard naming convention and provide typed event objects
 | `state.change` | Triggered when state changes (frequent). | `StateEvent` |
 | `camera.update` | Triggered when camera pose updates. | `CameraEvent` |
 
+> 状态管理详见 [State](./features/state.md)，模式切换详见 [Mode](./features/mode.md)。
+
 #### Lifecycle & Resources
 
 | Event Name | Description | Payload |
 | :--- | :--- | :--- |
 | `works.load` | Triggered when work data starts loading. | `WorksEvent` |
+| `works.ready` | Triggered when work data is loaded and controller is ready. | `WorksEvent` |
 | `models.load` | Triggered when models are loaded. | `ModelSceneEvent` |
-| `model.tileLoad` | Triggered when a 3D tile is loaded. | `Tile` |
-| `model.tileUnload` | Triggered when a 3D tile is unloaded. | `Tile` |
+| `models.refined` | Triggered when all models finish texture refinement. | `ModelSceneEvent` |
+| `model.load` | Triggered when a single model geometry is loaded. | `ModelEvent` |
+| `model.tileLoad` | Triggered when a 3D tile is loaded. | `ModelTileEvent` |
+| `model.tileUnload` | Triggered when a 3D tile is unloaded. | `ModelTileEvent` |
+| `model.changeShownFloor` | Triggered when floor visibility changes. | `ModelEvent` |
+| `model.error` | Triggered when model loading fails. | `ModelErrorEvent` |
+| `pano.prepare` | Triggered before switching to a new pano. `ExtendableEvent`, supports `waitUntil`. | `PanoPrepareEvent` |
 | `pano.arrived` | Triggered when arrival at a panorama node. | `PanoEvent` |
-| `pano.texture.progress` | Triggered when panorama texture loading progresses. | `{ progress, panoIndex }` |
+| `pano.moving` | Triggered during pano transition animation. | `PanoEvent` |
+| `pano.error` | Triggered when pano loading or movement fails. | `PanoEvent` |
+| `pano.texture.progress` | Triggered when panorama texture loading progresses. | `PanoTextureEvent` |
 | `render` | Triggered after each render frame. | `RenderEvent` |
+| `render.prepare` | Triggered before each render frame. | `RenderEvent` |
 | `error` | Triggered on internal errors. | `Error` |
 
+> 事件系统详解见 [Event](./features/event.md)。手势事件详解见 [Gesture](./features/gesture.md)。
+> `pano.prepare` 的 `waitUntil` / `preventDefault` 用法见 [Event - Event 对象](./features/event.md#event-对象)。
+> 模型生命周期事件见 [Model](./features/model.md#events) 和 [Load Progress](./features/load-progress.md)。
+
 ### Legacy Events (Deprecated)
 
 Older events are still supported for compatibility but should be avoided in new code.

package/ai_guides/features/3dtile.md

@@ -168,5 +168,5 @@ console.log((tileset as any).cacheMemoryUsageInBytes / 1024 / 1024 + ' MB');
 ---
 
 ```yaml
-tags: [3dtile, viewLayer, performance, lod, optimization]
+tags: [大场景, 瓦片, 显存, 画质, 性能优化, 流式加载, 3dtile, viewLayer, performance, lod, optimization, tile-loading, memory, sse, screen-space-error]
 ```

package/ai_guides/features/camera-animation.md

@@ -80,6 +80,21 @@ five.moveToPano(panoIndex: number, options?: MovePanoOptions): Promise<void>
 five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
 ```
 
+### 4. updateCamera
+
+在不切换全景点位的情况下，将相机平滑动画到目标位姿。适用于"定点环顾"或"聚焦某个方向"等场景。
+
+```typescript
+five.updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean): Promise<void>
+```
+
+*   `pose`: 目标位姿 (longitude, latitude, fov, offset, distance 等)。
+*   `duration`: 动画时长 (ms)。
+*   `userAction`: 是否标记为用户触发。
+*   **返回**: `Promise<void>`，动画完成时 resolve，被打断时 reject。
+
+> 与 `setState` 的区别：`updateCamera` 返回 Promise，可以精确等待动画结束；`setState` 是 fire-and-forget 风格。
+
 ## Concepts
 
 ### Pose (位姿)
@@ -197,9 +212,11 @@ function wait(ms: number) {
 *   [Five](./five.md): Five 核心类及 `setState` 方法。
 *   [Mode](./mode.md): 各种交互模式说明。
 *   [State](./state.md): 状态对象的完整定义。
+*   [Move Pano Effect](./move-pano-effect.md): 全景点位切换的过渡效果配置。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解 longitude/latitude 的含义。
 
 ---
 
 ```yaml
-tags: [camera-animation, pose, state]
+tags: [巡航, 动画, 旋转, 缩放, 运镜, 导览, camera-animation, pose, state, auto-tour, fly-through, rotate, zoom, transition]
 ```

package/ai_guides/features/clipper.md

@@ -126,10 +126,10 @@ function updateClipper(mesh: THREE.Mesh) {
 
 ## Related
 
-*   [model.md](./model.md): 模型模块概览。
+*   [Model](./model.md): 模型模块概览。
 
 ---
 
 ```yaml
-tags: [clipper, model, cut, discard, geometry]
+tags: [裁切, 剖面, 隐藏部分模型, 开盖, 房屋剖面, clipper, model, cut, discard, geometry, clipping-box, section-view]
 ```

package/ai_guides/features/coordinate-system.md

@@ -39,6 +39,22 @@ interface Coordinate {
 
 ## Concepts
 
+### Overview (坐标系总览)
+
+Five 中涉及多个坐标系，它们在不同场景下各有用途。理解它们的关系是正确使用 Five 的关键。
+
+| 坐标系 | 上轴 | 适用场景 | 说明 |
+| :--- | :--- | :--- | :--- |
+| **Local (Y-up)** | Y | 渲染场景、前端开发 | Five 的 `five.scene`、Observer 位置、`project2d` 等均使用此坐标系。与 Three.js 默认一致。 |
+| **ENU (Z-up)** | Z | 算法交互、后端接口、模型原始数据 | 测绘行业习惯。3D Tiles 数据源、`loadGltf` 等加载器默认输出 Z-up。 |
+| **ECEF** | - | RTK 定位、地球坐标 | 地心地固坐标系，用于包含 RTK 信息的模型。 |
+| **World** | Y | Three.js 世界坐标 | 通常等同于 Local，除非有 Object3D 层级嵌套偏移。 |
+
+> **关键区分**：
+> - **开发者在 `five.scene` 中操作的所有对象**（添加标签、射线检测结果、`project2d` 输入等）都处于 **Local (Y-up)** 坐标系。
+> - **模型数据源**（3D Tiles、PLY、GLTF 等文件）通常以 **ENU (Z-up)** 存储。Five 在加载时会自动将其旋转对齐到 Local (Y-up)。
+> - **与后端/算法交互**时，推荐使用 **ENU (Z-up)** 坐标系传输数据，通过 `viewLayer.localToEnu()` / `viewLayer.enuToLocal()` 进行转换。
+
 ### Local Coordinate System (Y-up)
 Five 的渲染场景 (`five.scene`) 和 Observers (观察点) 使用 **Y-up** (Y 轴向上) 的右手坐标系。
 这与 Three.js 的默认坐标系一致，便于前端开发和场景渲染。
@@ -64,6 +80,8 @@ Five 的渲染场景 (`five.scene`) 和 Observers (观察点) 使用 **Y-up** (Y
 3.  **自动对齐**: Five 加载模型时（load 方法），会自动处理旋转和坐标系转换，将其对齐到 Five 的 Local (Y-up) 坐标系中。
     - 开发者在 `five.scene` 中看到的所有模型都已处于统一的 Y-up 坐标系下。
 
+> **注意**: 外部模型加载函数（如 `loadGltf`, `loadPly` 等）的 `upAxis` 参数默认为 `'Z'`，表示输出的模型以 Z-up 存储。这是因为这些函数返回的是**原始模型对象**，尚未经过 Five 的自动对齐。当你通过 `five.load(work)` 加载 Work 数据时，Five 会自动完成 Z-up → Y-up 的转换。如果你手动使用 `loadGltf` 并添加到 `five.scene`，需要自行处理坐标系旋转。详见 [Load External Model](./load-external-model.md)。
+
 ### Coordinate in Files
 在 3D Tiles 的 `tileset.json` 中，`rootMeta` 字段用于描述坐标系转换信息（没有该字段则默认 Z-up）：
 - 包含 `pose_ecef_to_enu` 和 `pose_enu_to_ecef` 变换矩阵。
@@ -119,10 +137,10 @@ const displayPosition = viewLayer.ecefToLocal(ecefPosition.clone());
 
 ## Related
 
-*   [load-external-model.md](./load-external-model.md): 加载外部模型时的坐标轴配置 (`upAxis`, `modelUpAxis`)。
+*   [Load External Model](./load-external-model.md): 加载外部模型时的坐标轴配置 (`upAxis`, `modelUpAxis`)。
 
 ---
 
 ```yaml
-tags: [coordinate-system, enu, ecef, z-up, y-up, transform]
+tags: [坐标系, 坐标转换, 右手坐标系, 模型方向, 旋转, 地理坐标, coordinate-system, enu, ecef, z-up, y-up, transform, local, world, rtk]
 ```

package/ai_guides/features/event.md

@@ -1,9 +1,9 @@
 # Events (事件系统)
 
 - **Summary**: Five 提供了一套基于发布/订阅模式的事件系统，用于监听用户交互、状态变更、数据加载及渲染生命周期。
-- **Schema**: `on` / `once` / `off` 接口定义。
-- **Concepts**: Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.
-- **Examples**: 监听全景移动、手势交互及状态变更。
+- **Schema**: `on` / `once` / `off` 接口定义；`BaseEvent` / `BaseExtendableEvent` 事件对象。
+- **Concepts**: Event 对象（`preventDefault` / `waitUntil`）、Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.
+- **Examples**: 监听全景移动、手势交互及状态变更；使用 `preventDefault` 拦截默认行为；使用 `waitUntil` 延迟点位切换。
 
 ## Schema
 
@@ -50,6 +50,101 @@ five.off(
 - **name**: (可选) 若不传，则清空所有事件；若传，则取消指定类型的事件。
 - **callback**: (可选) 若传，则仅取消该特定的回调函数；若不传，则取消该类型下的所有回调。
 
+## Event 对象
+
+> **Definition**: [BaseEvent / BaseExtendableEvent](../../five/utils/event.d.ts)
+
+Five 中所有事件回调的参数都是一个 Event 对象，分为两种基础类型：
+
+### BaseEvent
+
+所有事件的基础接口，包含以下属性和方法：
+
+```typescript
+interface BaseEvent {
+  /** 事件类型名称 */
+  type: string;
+  /** 事件触发时的时间戳 */
+  timeStamp: number;
+  /** 阻止事件的默认行为 */
+  preventDefault(): void;
+  /** 是否已调用过 preventDefault */
+  readonly defaultPrevented: boolean;
+}
+```
+
+### BaseExtendableEvent
+
+继承自 `BaseEvent`，额外提供 `waitUntil` 方法，用于在事件处理中插入异步等待逻辑：
+
+```typescript
+interface BaseExtendableEvent extends BaseEvent {
+  waitUntil(f: Promise<any>): void;
+}
+```
+
+目前 `pano.prepare` 事件使用 `BaseExtendableEvent`（对应 `PanoPrepareEvent`），其余事件均基于 `BaseEvent`。
+
+### preventDefault
+
+调用 `event.preventDefault()` 可以阻止事件的默认行为。Five 内部会在触发事件后检查 `event.defaultPrevented`，若为 `true` 则跳过后续的默认处理逻辑。
+
+比如：
+- `gesture.tap`：阻止默认的点位跳转或相机弹跳动画。
+- `intersect.update`：阻止默认的交互高亮行为。
+
+```typescript
+// 示例：阻止点击时的默认点位跳转
+five.on("gesture.tap", (event) => {
+  if (shouldBlockNavigation()) {
+    event.preventDefault();
+    // 执行自定义逻辑
+    showCustomMenu(event);
+  }
+});
+
+// 示例：阻止拖拽时的默认相机旋转
+five.on("gesture.pan", (event) => {
+  event.preventDefault();
+  // 用拖拽手势实现自定义交互（如绘制标注）
+  drawAnnotation(event);
+});
+```
+
+### waitUntil
+
+`waitUntil(promise)` 仅在 `ExtendableEvent` 上可用。调用后，Five 会等待传入的 Promise 完成后再继续后续流程。可多次调用，所有 Promise 会被并行等待。
+
+目前仅 `pano.prepare` 事件支持 `waitUntil`。
+
+```typescript
+// 示例：在切换点位前预加载资源
+five.on("pano.prepare", (event) => {
+  // 等待自定义资源加载完成后再继续点位切换
+  event.waitUntil(
+    loadCustomResources(event.pano)
+  );
+
+  // 可以多次调用，所有 Promise 会被并行等待
+  event.waitUntil(
+    preloadTextures(event.pano)
+  );
+});
+
+// 示例：通过 waitUntil reject 来取消走点
+five.on("pano.prepare", (event) => {
+  event.waitUntil(
+    showConfirmDialog("是否前往该点位？").then((confirmed) => {
+      if (!confirmed) {
+        throw new Error("用户取消走点");
+      }
+    })
+  );
+});
+```
+
+> **注意**: `preventDefault` 和 `waitUntil` 必须在事件回调的同步执行阶段调用，不能放在 `await` 之后。
+
 ## Concepts
 
 Five 的事件系统将事件主要分为以下几类：
@@ -68,6 +163,7 @@ Five 的事件系统将事件主要分为以下几类：
 ### Pano Events (全景导航)
 监听全景图的点位切换过程。
 
+- `pano.prepare`: 准备切换到新点位。这是一个 `ExtendableEvent`，支持通过 `waitUntil(promise)` 延迟后续加载流程（如预加载资源），以及通过 `preventDefault()` 取消本次走点。
 - `pano.arrived`: 成功到达新点位（移动动画结束）。
 - `pano.moving`: 正在移动到新点位（动画进行中）。
 - `pano.willChange`: 即将发生点位变更（旧版兼容）。
@@ -105,13 +201,13 @@ import { Five } from "@realsee/five";
 const five = new Five();
 
 // 监听点击事件
-five.on("gesture.tap", (pose) => {
-  console.log("User tapped at:", pose);
+five.on("gesture.tap", (event) => {
+  console.log("User tapped at:", event);
 });
 
 // 监听点位变更完成
-five.on("pano.arrived", (index) => {
-  console.log("Arrived at pano index:", index);
+five.on("pano.arrived", (event) => {
+  console.log("Arrived at pano:", event.pano);
 });
 ```
 
@@ -144,11 +240,11 @@ five.on("render", onRender);
 
 ## Related
 
-- [state.md](./state.md): 了解 State 的结构与变更机制。
-- [five.md](./five.md): Five 核心类说明。
+- [State](./state.md): 了解 State 的结构与变更机制。
+- [Five](./five.md): Five 核心类说明。
 
 ---
 
 ```yaml
-tags: [events, interaction, lifecycle, gesture, state]
+tags: [事件监听, 点击, 拖拽, 加载完成, 渲染回调, 生命周期, 回调, events, interaction, lifecycle, gesture, state, preventDefault, waitUntil, on, off, subscribe]
 ```

package/ai_guides/features/five.md

@@ -67,7 +67,7 @@ Five 内部维护了一个 `requestAnimationFrame` 循环。
 
 | 参数 | 类型 | 默认值 | 说明 |
 | :--- | :--- | :--- | :--- |
-| `imageOptions` | `ImageOptions` | `{}` | 图片加载策略，详见 [image-options.md](./image-options.md) |
+| `imageOptions` | `ImageOptions` | `{}` | 图片加载策略，详见 [Image Options](./image-options.md) |
 | `textureOptions` | `TextureOptions` | `{}` | 贴图加载策略，同上 |
 | `onlyRenderIfNeeds` | `boolean` | `true` | 是否仅在需要时渲染，建议保持 `true` |
 | `antialias` | `boolean` | `false` | 抗锯齿，开启会增加性能消耗 |
@@ -144,41 +144,41 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 
 ### 实例属性 (Instance Properties)
 
-- **`work`**: 当前加载的 Work 数据（主 Work）。详见 [work.md](./work.md)。
-- **`works`**: 当前加载的所有 Work 数据列表。详见 [work.md](./work.md)。
-- **`model`**: 当前加载的 Model 数据（主 Model）。详见 [model.md](./model.md)。
-- **`models`**: 当前加载的所有 Model 数据列表。详见 [model.md](./model.md)。
+- **`work`**: 当前加载的 Work 数据（主 Work）。详见 [Work](./work.md)。
+- **`works`**: 当前加载的所有 Work 数据列表。详见 [Work](./work.md)。
+- **`model`**: 当前加载的 Model 数据（主 Model）。详见 [Model](./model.md)。
+- **`models`**: 当前加载的所有 Model 数据列表。详见 [Model](./model.md)。
 
 ### 实例方法 (Instance Methods)
 
 - **`appendTo(element: HTMLElement)`**: 将 canvas 挂载到指定 DOM 元素。
-- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [work.md](./work.md)。
+- **`load(work: Work, state?: State, duration?: number)`**: 加载场景数据。详见 [Work](./work.md)。
 - **`dispose()`**: 销毁实例，释放 WebGL 上下文与内存。
 - **`updateCamera(pose: Partial<Pose>, duration: number, userAction?: boolean)`**: 移动相机（不触发点位移动）。移动相机的视角或位置，不会改变当前所在的 PanoIndex。如果动画中途被打断，Promise 会被 reject。
 - **`updateCameraWithKeyframes(keyframes: { progress: number; value: Pose; key?: string }[], duration: number, userAction?: boolean)`**: 通过关键帧动画移动相机。
 - **`refresh()`**: 强制刷新画布尺寸。通常在窗口 resize 时调用，Five 会自动监听 resize，但在某些布局变化场景下可能需要手动调用。
 - **`getPixels(x, y, width, height, ...)` / `getPixels(options)`**: 获取画布指定区域的像素数据。常用于截图、生成缩略图或颜色拾取。支持配置区域、像素比 (pixelRatio)、Y轴翻转 (flipY) 及是否忽略全景图 (skipPanorama) 等。
-- **`project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null`**: 计算三维坐标对应到屏幕的二维坐标。如果坐标在视野外或被遮挡（开启 testModel 时），返回 null。详见 [screen-project.md](./screen-project.md)。
+- **`project2d(vector: THREE.Vector3, testModel?: boolean): THREE.Vector2 | null`**: 计算三维坐标对应到屏幕的二维坐标。如果坐标在视野外或被遮挡（开启 testModel 时），返回 null。详见 [Screen Project](./screen-project.md)。
 - **`ready(args?: { tile?: boolean })`**: Promise，当 Five 状态稳定时 resolve。
   - **Resolve 时机**：
     1. **状态同步**：相机姿态已通过动画过渡到目标状态（`stateSynced` 为 true）。
     2. **模型加载**：如果是 Floorplan/Topview/Mapview/Model 模态，需等待模型加载完成 (`modelScene.loaded`)。
     3. **瓦片加载**：如果是 Panorama 模态且传入了 `{ tile: true }`，需等待当前视角的瓦片加载完成。
-- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [state.md](./state.md)。
-- **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [event.md](./event.md)。
+- **`setState(state: Partial<State>, options?: ChangeStateOptions)`**: 变更当前状态（如点位、视角）。详见 [State](./state.md)。
+- **`on(event, callback)` / `off(event, callback)`**: 事件监听。详见 [Event](./event.md)。
 
 ## Related
 
-*   [work.md](./work.md): Work 数据结构说明。
-*   [model.md](./model.md): Model 数据结构说明。
-*   [state.md](./state.md): 状态管理详解。
-*   [event.md](./event.md): 事件系统说明。
-*   [image-options.md](./image-options.md): 图片加载配置。
-*   [mode.md](./mode.md): 模态切换说明。
-*   [parameter.md](./parameter.md): 其他核心参数。
+*   [Work](./work.md): Work 数据结构说明。
+*   [Model](./model.md): Model 数据结构说明。
+*   [State](./state.md): 状态管理详解。
+*   [Event](./event.md): 事件系统说明。
+*   [Image Options](./image-options.md): 图片加载配置。
+*   [Mode](./mode.md): 模态切换说明。
+*   [Parameter](./parameter.md): 其他核心参数。
 
 ---
 
 ```yaml
-tags: [five, initialization, core, instance, lifecycle]
+tags: [初始化, 创建实例, 渲染器, 销毁, 入口, 构造函数, five, initialization, core, instance, lifecycle, canvas, appendTo, dispose]
 ```