@realsee/five 6.8.0-alpha.29 → 6.8.0-alpha.30

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

@@ -108,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 对象。

package/ai_guides/api.md

@@ -67,6 +67,9 @@ interface FiveInitArgs {
   /** 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).
+
+> 详见 [Raycast](./features/raycast.md)。
 
-### `addPass(pass)`
-Add a post-processing pass to the rendering chain.
+### `addPass(pass)` / `removePass(pass)`
+Add or remove a post-processing pass to/from the rendering chain.
 
-- **pass**: `FivePass` instance (e.g. `Gaussian Blur Pass`).
+- **pass**: `FivePass` instance (e.g. `GaussianBlurPass`, `FlowingLight2DPass`).
 
-### `removePass(pass)`
-Remove a post-processing pass from the rendering chain.
+> 详见 [Postprocessing](./features/postprocessing.md)。
 
-- **pass**: `FivePass` instance to remove.
+### `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.
 
@@ -234,6 +283,8 @@ These events follow a standard naming convention and provide typed event objects
 | `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
 
 | Event Name | Description | Payload |
@@ -242,6 +293,8 @@ 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 |
@@ -249,8 +302,12 @@ These events follow a standard naming convention and provide typed event objects
 | `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` |
+| `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.moving` | Triggered during pano transition animation. | `PanoEvent` |
@@ -260,6 +317,10 @@ These events follow a standard naming convention and provide typed event objects
 | `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

@@ -240,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, preventDefault, waitUntil]
+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]
 ```

package/ai_guides/features/flowing-light-2d-pass.md

@@ -439,4 +439,4 @@ setInterval(() => {
 ---
 
 
-tags: [postprocessing, effect, flowing, light, pass, rendering, screenspace, instanced, performance]
+tags: [流光, 光带, 导航路径, 指示线, 动态路径, 特效, postprocessing, effect, flowing, light, pass, rendering, screenspace, instanced, performance, 2d, screen-space]

package/ai_guides/features/flowing-light-3d-pass.md

@@ -422,4 +422,4 @@ setInterval(() => {
 ---
 
 
-tags: [postprocessing, effect, flowing, light, pass, rendering, worldspace, projection, instanced, performance]
+tags: [流光, 光带, 空间轨迹, 模型表面, 特效, postprocessing, effect, flowing, light, pass, rendering, worldspace, projection, instanced, performance, 3d, world-space]

package/ai_guides/features/gaussian-blur-pass.md

@@ -198,5 +198,5 @@ console.log('Resolution:', blurPass['material'].uniforms.resolution.value);
 ---
 
 ```yaml
-tags: [postprocessing, shader, effect, blur, pass, rendering]
+tags: [模糊, 高斯模糊, 毛玻璃, 背景虚化, postprocessing, shader, effect, blur, pass, rendering, gaussian, blur-effect]
 ```

package/ai_guides/features/gesture.md

@@ -177,5 +177,5 @@ five.on("gesture.pinch", (event) => {
 ---
 
 ```yaml
-tags: [gesture, event, interaction, tap, pan, pinch]
+tags: [手势, 点击, 拖拽, 缩放, 长按, 鼠标, 触摸, 交互控制, 自定义交互, gesture, event, interaction, tap, pan, pinch, preventDefault]
 ```

package/ai_guides/features/get-screen-pixels.md

@@ -173,10 +173,10 @@ function getCenterColor(five: Five) {
 
 ## Related
 
-*   [api.md](../api.md): Five 核心 API 说明。
+*   [API Reference](../api.md): Five 核心 API 说明。
 
 ---
 
 ```yaml
-tags: [getPixels, magnifier, screenshot, pixel, canvas]
+tags: [截图, 放大镜, 取色器, 颜色拾取, 像素数据, getPixels, magnifier, screenshot, pixel, canvas, screen-capture, color-picker]
 ```

package/ai_guides/features/image-options.md

@@ -155,10 +155,10 @@ console.log(cutUrl);
 
 ## Related
 
-*   [pano-tile.md](./pano-tile.md): 全景图瓦片加载策略与 WorkTile 数据结构说明。
+*   [Pano Tile](./pano-tile.md): 全景图瓦片加载策略与 WorkTile 数据结构说明。
 
 ---
 
 ```yaml
-tags: [imageOptions, configuration, optimization, cdn, private-deployment]
+tags: [图片配置, 图片格式, 域名映射, 多云部署, 私有化, 图片质量, 流量优化, imageOptions, configuration, optimization, cdn, private-deployment, avif, webp]
 ```

package/ai_guides/features/load-external-model.md

@@ -343,10 +343,12 @@ loadAt3d('https://example.com/model.at3d', {
 
 ## Related
 
-*   [model.md](./model.md): 关于 Five 内部模型加载机制的说明。
+*   [Model](./model.md): 关于 Five 内部模型加载机制的说明。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解 Y-up 与 Z-up 的转换。
+*   [Request Proxy](./request-proxy.md): 自定义请求拦截（鉴权、CDN），与 fetcher 配合使用。
 
 ---
 
 ```yaml
-tags: [loader, gltf, ply, splat, fbx, external-model]
+tags: [加载模型, 导入模型, 点云, 内存泄漏, loader, gltf, ply, splat, fbx, external-model, glb, obj, 3d-model, gaussian-splatting, point-cloud, draco, dispose]
 ```

package/ai_guides/features/load-progress.md

@@ -136,5 +136,5 @@ five.on("pano.texture.error", (event) => {
 ---
 
 ```yaml
-tags: [loading, progress, refined, loaded, event]
+tags: [加载进度, 加载完成, 首屏, 高清, 细化, 全景加载, 模型加载, loading, progress, refined, loaded, event, tile-load, loading-bar]
 ```

package/ai_guides/features/material.md

@@ -123,21 +123,27 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 ### 1. Adjusting Model Transparency and Style (调整模型透明度与样式)
 
 ```typescript
-five.model.set({
-  opacity: 0.5,           // Make model semi-transparent (半透明)
-  modelAlpha: 0.0,        // Show original UV texture only (仅显示原始UV贴图)
-  floorStyle: 'wireframe' // Wireframe mode (线框模式)
-});
+// 设置半透明
+five.modelScene.parameter.set('opacity', 0.5);
+
+// 仅显示原始 UV 贴图
+five.modelScene.parameter.set('modelAlpha', 0.0);
+
+// 设置楼层样式
+five.modelScene.parameter.set('floorStyle', 'wireframe');
 ```
 
 ### 2. Configuring Point Cloud Appearance (配置点云外观)
 
 ```typescript
-five.model.set({
-  pointSize: 'ATTENUATION', // 大小随距离衰减
-  pointScale: 0.05,         // 基础大小
-  pointMaxPixel: 20         // 最大像素限制
-});
+// 大小随距离衰减
+five.modelScene.parameter.set('pointSize', 'ATTENUATION');
+
+// 基础大小
+five.modelScene.parameter.set('pointScale', 0.05);
+
+// 最大像素限制
+five.modelScene.parameter.set('pointMaxPixel', 20);
 ```
 
 ## Related
@@ -149,5 +155,5 @@ five.model.set({
 ---
 
 ```yaml
-tags: [material, appearance, pointcloud, parameter, roof, ceiling, config]
+tags: [材质, 透明度, 点云, 楼层, 阴影, 亮度, 天花板, 开盖, 顶点标记, 渲染样式, material, appearance, pointcloud, parameter, roof, ceiling, config, opacity]
 ```

package/ai_guides/features/mode.md

@@ -265,5 +265,5 @@ document.querySelector('#btn-map').addEventListener('click', () => {
 ---
 
 ```yaml
-tags: [mode, state, interaction]
+tags: [模式, 全景, 户型图, 鸟瞰, 漫游, 切换模式, 视角, mode, state, interaction, VR, panorama, floorplan, mapview, topview, model]
 ```

package/ai_guides/features/model.md

@@ -182,5 +182,5 @@ model.viewLayers.forEach((layer) => {
 ---
 
 ```yaml
-tags: [model, viewlayer, object3d]
+tags: [模型, 三维模型, 点云, 高斯泼溅, 加载, 渲染, 图层, 楼层, 细化, model, viewlayer, object3d, mesh, refine]
 ```

package/ai_guides/features/move-pano-effect.md

@@ -141,5 +141,5 @@ five.moveToPano(aerialPanoIndex, {
 ---
 
 ```yaml
-tags: [move-pano-effect, camera-animation, pano-switch]
+tags: [全景切换, 走点效果, 淡入淡出, 飞行, 过渡动画, 缓动, move-pano-effect, camera-animation, pano-switch, fly, fade, easing]
 ```

package/ai_guides/features/multi-work.md

@@ -142,5 +142,5 @@ if (targetWork) {
 
 ---
 ```yaml
-tags: [multi-work, sandbox, works, load, transform]
+tags: [多场景, 沙盘, 多户型, 拼接, 追加, 切换场景, 多楼盘, multi-work, sandbox, works, load, transform, workCode]
 ```

package/ai_guides/features/pano-filter.md

@@ -140,9 +140,10 @@ function onContrastChange(value: number) {
 *   [Model](./model.md): 了解 ModelScene 及其参数系统。
 *   [Parameter](./parameter.md): 了解 Five 的全局初始化参数。
 *   [Postprocessing](./postprocessing.md): 了解屏幕空间的后处理效果。
+*   [Material](./material.md): 材质参数配置（透明度、点云等）。
 
 ---
 
 ```yaml
-tags: [filter, material, visual, color, brightness, contrast]
+tags: [滤镜, 色温, 暖色, 冷色, 饱和度, 亮度, 对比度, filter, material, visual, color, brightness, contrast, color-correction, warm, cool, tone]
 ```