@realsee/five 6.8.0-alpha.8 → 6.8.0

package/ai_guides/features/pano-filter.md

@@ -0,0 +1,149 @@
+# Pano Filter (全景图滤镜)
+
+- **Summary**: `PBMPanoFilter` 用于调整全景图的视觉效果，包括亮度、对比度、饱和度、色温、色调等。它作为参数传递给 `ModelScene`，可实时改变全景图的渲染表现。
+- **Schema**: `PBMPanoFilter`, `PBMUpdateable`
+- **Concepts**: Material Filter, Color Correction
+- **Configuration**: Temperature, Tint, Brightness, Contrast, Saturation
+- **Examples**: 滤镜开启与参数调整
+
+## Schema
+
+> **Definition**: [PBMPanoFilter](../../five/model/materials/pbmMaterial.d.ts)
+
+`PBMPanoFilter` 类定义了全景图的滤镜参数。所有属性均为对象引用，直接修改其内部属性即可生效。
+
+```typescript
+import { PBMUpdateable } from "@realsee/five";
+
+export class PBMPanoFilter extends PBMUpdateable {
+  /** 对比度控制 */
+  public readonly contrast: {
+    /** 对比度偏移 [-1, 1] (默认 0) */
+    contrastBias: number;
+  };
+
+  /** 饱和度控制 */
+  public readonly saturation: {
+    /** 饱和度偏移 [-1, 1] (默认 0) */
+    saturationBias: number;
+  };
+
+  /** 颜色控制 (色温与色调) */
+  public readonly color: {
+    /** 色温偏移 [-100, 100] (默认 0) */
+    temperatureBias: number;
+    /** 色调偏移 [-100, 100] (默认 0) */
+    tintBias: number
+  };
+
+  /** 高光与阴影控制 */
+  public readonly highlightShadow: {
+    /** 全局亮度偏移 [-255, 255] (默认 0) */
+    globalBias: number;
+    /** 高光偏移 [-255, 255] (默认 0) */
+    highlightBias: number;
+    /** 阴影偏移 [-255, 255] (默认 0) */
+    shadowBias: number;
+  };
+}
+```
+
+## Concepts
+
+### Material Filter (材质滤镜)
+与 [Postprocessing](./postprocessing.md) (后处理) 不同，`PBMPanoFilter` 是作用于全景图材质 (Material) 阶段的滤镜。这意味着它直接影响纹理的采样和着色计算，而不是对最终渲染图像进行二次处理。
+
+### Parameter Binding (参数绑定)
+滤镜实例需要通过 `five.modelScene.parameter.set('panoFilter', filter)` 绑定到场景中才能生效。
+
+## Configuration
+
+以下参数均通过修改 `PBMPanoFilter` 实例的属性进行配置。
+
+### Color & Tone (色彩与色调)
+
+| Property | Type | Range | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `color.temperatureBias` | `number` | `[-100, 100]` | `0` | **色温**。正值偏暖 (黄)，负值偏冷 (蓝)。 |
+| `color.tintBias` | `number` | `[-100, 100]` | `0` | **色调**。正值偏洋红，负值偏绿。 |
+| `saturation.saturationBias` | `number` | `[-1, 1]` | `0` | **饱和度**。`0` 为原色，`-1` 为黑白。 |
+| `contrast.contrastBias` | `number` | `[-1, 1]` | `0` | **对比度**。正值增强对比，负值降低对比。 |
+
+### Light & Shadow (光影)
+
+| Property | Type | Range | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `highlightShadow.globalBias` | `number` | `[-255, 255]` | `0` | **亮度 (Brightness)**。整体提升或降低画面亮度。 |
+| `highlightShadow.highlightBias` | `number` | `[-255, 255]` | `0` | **高光 (Highlight)**。仅调整画面亮部的亮度。 |
+| `highlightShadow.shadowBias` | `number` | `[-255, 255]` | `0` | **阴影 (Shadow)**。仅调整画面暗部的亮度。 |
+
+## Examples
+
+### Basic Usage (基础用法)
+
+创建一个滤镜实例并应用到 Five 场景中。
+
+```typescript
+import { Five, PBMPanoFilter } from "@realsee/five";
+
+const five = new Five();
+// ... 初始化 five ...
+
+// 1. 创建滤镜实例
+const panoFilter = new PBMPanoFilter();
+
+// 2. 配置参数 (例如：增加一点暖色调和亮度)
+panoFilter.color.temperatureBias = 10; // 暖色
+panoFilter.highlightShadow.globalBias = 20; // 提亮
+
+// 3. 启用滤镜
+five.modelScene.parameter.set('panoFilter', panoFilter);
+
+// 4. (可选) 停用滤镜
+// five.modelScene.parameter.reset('panoFilter');
+```
+
+### Interactive Adjustment (动态调整)
+
+滤镜参数支持实时修改，适合制作调节面板。
+
+```typescript
+import { Five, PBMPanoFilter } from "@realsee/five";
+
+// 假设已经有 five 实例
+const panoFilter = new PBMPanoFilter();
+five.modelScene.parameter.set('panoFilter', panoFilter);
+
+// 模拟 UI 绑定的数据对象
+const filterSettings = {
+  brightness: 0,
+  contrast: 0,
+};
+
+// 监听 UI 变化 (示例伪代码)
+function onBrightnessChange(value: number) {
+  // value range: [-255, 255]
+  panoFilter.highlightShadow.globalBias = value;
+  // 如果 five 没有开启自动渲染 (play: false)，需要手动触发重绘
+  five.needsRender = true;
+}
+
+function onContrastChange(value: number) {
+  // value range: [-1, 1]
+  panoFilter.contrast.contrastBias = value;
+  five.needsRender = true;
+}
+```
+
+## Related
+
+*   [Model](./model.md): 了解 ModelScene 及其参数系统。
+*   [Parameter](./parameter.md): 了解 Five 的全局初始化参数。
+*   [Postprocessing](./postprocessing.md): 了解屏幕空间的后处理效果。
+*   [Material](./material.md): 材质参数配置（透明度、点云等）。
+
+---
+
+```yaml
+tags: [滤镜, 色温, 暖色, 冷色, 饱和度, 亮度, 对比度, filter, material, visual, color, brightness, contrast, color-correction, warm, cool, tone]
+```

package/ai_guides/features/pano-tile.md

@@ -128,5 +128,5 @@ const five = new Five({
 ---
 
 ```yaml
-tags: [pano-tile, observer]
+tags: [全景瓦片, 高清全景, 分片加载, 瓦片, 全景图, 分辨率, 按需加载, pano-tile, observer, LOD, tile]
 ```

package/ai_guides/features/pano-uv.md

@@ -127,5 +127,5 @@ console.log(`正前方对应 Cubemap 的 ${face} 面，UV 为`, uv);
 ---
 
 ```yaml
-tags: [work, observer, uv, projection, math]
+tags: [全景UV, 方向转换, 全景坐标, 像素映射, 全景标注, work, observer, uv, projection, math, equirectangular, cubemap]
 ```

package/ai_guides/features/parameter.md

@@ -64,10 +64,34 @@ class Parameter {
   reset(...keys: string[]): void;
 
   /**
-   * 获取经过继承计算后的最终值
+   * 获取经过继承计算后的最终值（每次调用创建新对象）
    * @param upstream 上游 Parameter 对象列表（通常由引擎自动传入）
    */
   resolveValue(...upstream: Parameter[]): ResolvedParameterValue;
+
+  /**
+   * 获取经过继承计算后的最终值（复用 target 对象，避免重复创建）
+   * 适用于高频调用场景（如逐帧更新），可显著减少 GC 压力。
+   * @param target 用于写入结果的已有对象，其属性会被重置为默认值后重新赋值
+   * @param upstream 上游 Parameter 对象列表
+   */
+  static resolveValueTo(
+    target: Partial<ResolvedParameterValue>,
+    ...upstream: Partial<ParameterValue>[]
+  ): ResolvedParameterValue;
+}
+```
+
+> `resolveValue()` 内部已委托给 `resolveValueTo({}, ...)`，两者计算逻辑一致，区别仅在于是否复用对象。
+
+#### 3. Version (版本标识)
+
+`ResolvedParameterValue` 通过 `versionNumber: number` 标识当前配置的版本。引擎内部使用整数哈希（而非字符串拼接）计算版本号，用于高效的脏检查。
+
+```typescript
+interface ResolvedParameterValue extends ParameterValue {
+  /** 整数哈希，输入参数变化时值会改变，用于脏检查 */
+  versionNumber: number;
 }
 ```
 
@@ -149,5 +173,5 @@ const finalOpacity = five.modelScene.parameter.resolveValue().opacity;
 ---
 
 ```yaml
-tags: [parameter, config, hierarchy, api]
+tags: [配置, 参数, 继承, 覆盖, 全局配置, 局部配置, parameter, config, hierarchy, api, set, reset, modelScene]
 ```

package/ai_guides/features/plugin.md

@@ -206,5 +206,5 @@ export type { MyPluginType, Controller as MyPluginController }
 ---
 
 ```yaml
-tags: [plugin, baseplugin, development, guide]
+tags: [插件, 插件开发, 扩展, 自定义功能, 状态管理, plugin, baseplugin, development, guide, extension, lifecycle]
 ```

package/ai_guides/features/postprocessing.md

@@ -255,5 +255,5 @@ class FogPass extends FivePass {
 ---
 
 ```yaml
-tags: [postprocessing, shader, effect, adaptive-luminance, edl]
+tags: [后处理, 特效, 自定义shader, 滤镜, 描边, 景深, 色彩校正, 渲染管线, postprocessing, shader, effect, adaptive-luminance, edl, effect-composer, addPass]
 ```

package/ai_guides/features/raycast.md

@@ -166,10 +166,13 @@ const intersects = five.model.intersectRaycaster(raycaster);
 
 ## Related
 
-*   [parameter.md](./parameter.md): 了解模型参数配置。
+*   [Parameter](./parameter.md): 了解模型参数配置。
+*   [Screen Project](./screen-project.md): 屏幕坐标与空间坐标转换（标签、拾取的前置步骤）。
+*   [Event](./event.md): 手势事件系统，获取点击坐标的来源。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解 NDC 与世界坐标。
 
 ---
 
 ```yaml
-tags: [raycast, bvh, interaction, performance]
+tags: [点击, 拾取, 碰撞检测, 物体选择, raycast, bvh, interaction, performance, picking, hit-test, click, floor-detection]
 ```

package/ai_guides/features/request-proxy.md

@@ -108,5 +108,5 @@ const five = new Five({
 ---
 
 ```yaml
-tags: [configuration, network, proxy, authentication]
+tags: [请求代理, 鉴权, 域名替换, 私有化, 请求拦截, configuration, network, proxy, authentication, CDN, token, url-rewrite, cors]
 ```

package/ai_guides/features/screen-project.md

@@ -157,9 +157,10 @@ container.addEventListener("click", (event) => {
 *   [Raycast](./raycast.md): 详细的射线检测文档。
 *   [Five](./five.md): Five 核心类说明。
 *   [State](./state.md): 了解相机位姿 (Pose)。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义，理解世界坐标与屏幕坐标的关系。
 
 ---
 
 ```yaml
-tags: [coordinate, screen, project, label, ui]
+tags: [标签, 坐标转换, 信息面板, coordinate, screen, project, label, ui, tag, HUD, 3D转2D, overlay, tooltip]
 ```

package/ai_guides/features/state.md

@@ -79,8 +79,8 @@ const state = five.state;
 
 // 在当前状态基础上，向右旋转 90 度，并略微拉远距离
 five.setState({
-  longitude: tate.longitude + Math.PI / 2,
-  distance: tate.distance + 2.0
+  longitude: state.longitude + Math.PI / 2,
+  distance: state.distance + 2.0
 });
 ```
 
@@ -89,13 +89,33 @@ five.setState({
 1.  **单位混淆**: `longitude` 和 `latitude` 使用**弧度**，而 `fov` 使用**角度**（度）。
 2.  **Offset 类型**: `offset` 必须是 `THREE.Vector3` 实例。如果在 React 等框架中使用纯对象（Plain Object），Five 内部会自动转换，但在 TypeScript 中需注意类型匹配。
 3.  **异步更新**: `setState` 触发的相机运动是异步动画过程。如果需要立即无动画跳转，可传递第二个参数 `immediately: true`。
+4.  **JSON 序列化**: `State` 中的 `offset` 是 `THREE.Vector3` 实例，不能直接 `JSON.stringify`。保存时需手动提取 `{ x, y, z }`，恢复时需重新构造 `new THREE.Vector3(x, y, z)`。
+
+```typescript
+// 保存
+const snapshot = {
+  ...five.state,
+  offset: { x: five.state.offset.x, y: five.state.offset.y, z: five.state.offset.z }
+};
+localStorage.setItem('fiveState', JSON.stringify(snapshot));
+
+// 恢复
+const saved = JSON.parse(localStorage.getItem('fiveState')!);
+five.setState({
+  ...saved,
+  offset: new THREE.Vector3(saved.offset.x, saved.offset.y, saved.offset.z)
+}, true);
+```
 
 ## Related
 
 *   [Mode - 模式](./mode.md): 详细了解各种 Mode 的区别。
+*   [Camera Animation](./camera-animation.md): 基于 State 的相机动画控制。
+*   [Five](./five.md): Five 核心类，`setState` / `getCurrentState` 的宿主。
+*   [Coordinate System](./coordinate-system.md): 坐标系定义。
 
 ---
 
 ```yaml
-tags: [camera, state, pose, interaction]
+tags: [状态保存, 状态恢复, 场景还原, 快照, camera, state, pose, interaction, save, restore, snapshot]
 ```

package/ai_guides/features/view-layer.md

@@ -183,5 +183,5 @@ if (pointCloudLayer) {
 ---
 
 ```yaml
-tags: [viewlayer, model, 3dtile, parameter, layer]
+tags: [图层, 视图层, 可见性, 显隐控制, 图层切换, 分层渲染, viewlayer, model, 3dtile, parameter, layer, mesh, point-cloud, gaussian-splatting]
 ```

package/ai_guides/features/work.md

@@ -299,5 +299,5 @@ five.load(work3, "inherit", { mode: "replace" });
 ---
 
 ```yaml
-tags: [work, core, entity, observer]
+tags: [VR数据, 数据加载, 点位, 全景点, 数据结构, 多work, work, core, entity, observer, parseWork, workCode, JSON, load]
 ```

package/ai_guides/glossary.md

@@ -52,7 +52,7 @@ Five 定义的五种浏览状态：
 ### Pano Tile (全景瓦片)
 为了在移动端快速加载高分辨率全景图（如 8K/16K），将全景图切分为多个小块（瓦片）。Five 会根据当前视角按需加载可见区域的瓦片。
 
-### Quasi / Mesh
+### Mesh (三维网格)
 **三维模型**。通过激光扫描或视觉算法重建的空间几何结构。在 Five 中，全景图贴在几何模型上，从而实现“从全景中看出立体感”的效果。
 
 ### G-Buffer / Geometry Buffer
@@ -64,10 +64,10 @@ Five 定义的五种浏览状态：
 - 拥有独立的 `Parameter` 配置（覆盖上层配置）。
 - 支持可见性控制 (`visible`) 和优先级加载。
 
-### Gaussian Splatting (3DGS)
+### Gaussian Splatting
 一种基于点的 3D 渲染技术，通过各向异性高斯球（Splat）来表示场景。
 - 相比传统 Mesh，能更真实地还原复杂光照和细节。
-- Five 支持 `.spz` 和 `.splat` 格式的 3DGS 渲染。
+- Five 支持 `.spz` 和 `.splat` 格式的 Gaussian Splatting 渲染。
 
 ### 3D Tiles Refinement (细化)
 3D Tiles 加载过程中的状态概念：
@@ -89,5 +89,5 @@ Five 封装的手势事件：
 
 ---
 ```yaml
-tags: [glossary, terminology, definitions]
+tags: [术语, 概念, glossary, terminology, definitions, observer, pose, mode, work, panoindex, fov, viewlayer, gaussian-splatting, 3dtile]
 ```

package/ai_guides/release_notes/6.8.md

@@ -7,84 +7,216 @@ npm install @realsee/five@6.8
 
 ## Gaussian Splatting (3DGS) 支持
 > Five 现已支持 Gaussian Splatting (3DGS) 渲染管线。这是一种基于点的渲染技术，能够提供高质量的实时渲染效果。
+> 仅在 WebGL2 环境下可用。
+
+### 文件格式支持
+  1. `.splat` 文档及工具 [GitHub - antimatter15/splat: WebGL 3D Gaussian Splat Viewer](https://github.com/antimatter15/splat)
+  2. `.spz` 文档及工具 GitHub - [nianticlabs/spz: File format for 3D Gaussian splats. About 10x smaller than the PLY equival](https://github.com/nianticlabs/spz)
+  3. `.glb` `.gltf` 对应的 KHR_gaussian_splatting, KHR_gaussian_splatting_compression_spz, KHR_gaussian_splatting_compression_spz_2 扩展。
+
+### 支持 3d-tile
+> 通过 3d-tile 标准，使用 glb 作为模型格式。
+
+```json
+{
+  "asset": {
+    "version": "1.0",
+  },
+  "geometricError": 265.4529731527354,
+  "root": {
+    "boundingVolume": {
+       "box": [
+         0.9499778747558594,  3.5037269592285156,    17.48550033569336,
+         97.01779174804688,   0.0,                   0.0,
+         0.0,                 88.27268981933594,     0.0,
+         0.0,                 0.0,                   20.292869567871094
+       ]
+    },
+    "content": {
+      "uri": "splat.glb"
+    },
+    "geometricError": 66.36324328818385,
+    "refine": "ADD"
+  },
+  "transform": [
+     1.0,      0.0,      0.0,      0.0,
+     0.0,      1.0,      0.0,      0.0,
+     0.0,      0.0,      1.0,      0.0,
+     0.0,      0.0,      0.0,      1.0
+   ]
+}
+```
 
-*   **前提条件**: 仅在 WebGL2 环境下可用。
-*   **数据支持**:
-    *   支持 `3dtiles` 中包含 3DGS 数据。
-    *   支持加载 `.spz` (version 2) 或 `.splat` 格式的数据。
-    *   支持通过 glTF 扩展加载 content 为 `.spz` 的 glTF/glb 文件。
-*   **功能特性**:
-    *   支持透视相机与正交相机渲染。
-    *   支持 BVH 构建，支持射线检测 (Raycast)。
-    *   `pbmGSObject` 继承自 `THREE.Points`。
+### 通过 Work 加载
 
-### 配置球谐光照阶数 (SH Degree)
-可以通过 `five.parameter.gsSHDegree` 设置球谐光照阶数，支持 0, 1, 2 阶，默认为 0 阶。
+```json
+{
+  "work_code": "",
+  "model": {
+    "layers": {
+       "tileset_url": "tileset.json",
+       "name": "poincare_3dgs",
+       "type": "gaussian_splatting"
+    }
+  }
+}
+```
 
-```ts
+### 配置球谐光照阶数 (SH Degree)
+可以通过 `five.parameter.gaussianSplattingSHDegree` 设置球谐光照阶数，支持 0, 1, 2 阶，默认为 0 阶。
+```
 const five = new Five({
     parameters: {
-        gsSHDegree: 1 // 设置为 1 阶 SH
+        gaussianSplattingSHDegree: 1 // 设置为 1 阶 SH
     }
 });
 ```
 
-## ViewLayer 加载策略优化
-> 优化了 ViewLayer 的加载和显隐逻辑，以减少内存占用并提高性能。
+### 模型的射线检测
+gaussian_splatting 的模型同时也支持 rayscast 射线检测。同点云的处理保持一致。但是因为 gaussian_splatting 的射线交点对应的法线方向是一个估算值，精度并不高。请酌情使用。
 
-### 默认加载策略变更
-默认情况下，Five **不再加载所有图层**，而是根据优先级**仅加载一个**图层。
-优先级顺序：`mesh` > `point_cloud` > 其他类型。
+## glTF 模型支持增强
+> 新增了对更多 glTF 扩展的支持，提升了模型的表现力和动画能力。
 
-### 显隐与内存管理
-*   **显示**: 当 `viewLayer.visible = true` 时，开始加载资源。
-*   **隐藏**: 当 `viewLayer.visible = false` 时，**释放该图层占用的所有内存资源**。
+### 扩展新增及优化
 
-### 加载进度
-新增 `tile.content.loadProgress` 属性，用于查看每个瓦片的加载进度 (0-1)。
-新增 `tile.content.byteLength` 属性，可在加载过程中获取瓦片内容的字节长度。
-同时，`model.tileLoad` 和 `model.tileUnload` 事件被添加，用于监控瓦片的生命周期。
+#### KHR_animation_pointer
+> KHR_animation_pointer 允许动画通道指向 glTF 资产中任何对象的任何属性。
 
-### 下载进度回调
-外部模型加载函数（`loadGltf`, `loadPly` 等）现在支持 `onDownloadProgress` 回调，用于监控文件下载进度。
+默认的 animtion 只能修改 node 的 transform 实现节点的平移、旋转和缩放
 
-### 射线检测增强
-*   `Intersection` 对象新增了 `tile`, `model`, `viewLayer` 字段，便于在射线检测时获取更详细的上下文信息。
-*   `raycaster.hitFilter` 回调函数的参数类型定义已更新，包含 `model`, `viewLayer`, `tile` 等上下文信息。
+这个能力可以实现材质动画。比如：
+- 通过 uv transform 实现 texture 的移动，变化贴图位置。
+- 通过修改 material 上的材质属性，可以动态修改金属粗糙，透明度，自发光程度。
+- 通过修改 node 的 KHR_node_visibility 的扩展值，显隐某个节点。
+- 等等
 
-## glTF 模型支持增强
-> 新增了对更多 glTF 扩展的支持，提升了模型的表现力和动画能力。
+#### KHR_node_visibility
+> 允许设置节点的可见性属性。
+用于 配合 KHR_animation_pointer 实现显隐效果。
 
-### 新增扩展支持
-*   **KHR_animation_pointer**: 允许动画通道指向 glTF 资产中任何对象的任何属性，而不仅仅是节点的平移、旋转和缩放。
-*   **KHR_node_visibility**: 允许设置节点的可见性属性。
-*   **KHR_materials_clearcoat** 用于在材质上添加一层透明涂层，模拟车漆、碳纤维、清漆木材等真实世界中的表面效果。
-*   **KHR_materials_sheen** 绒面 / 绒毛类表面效果。
-*   **KHR_materials_transmission** 物理透光材质扩展，用于实现光线真正穿过物体的透明 / 半透明效果。
+#### KHR_materials_clearcoat
+> 用于在材质上添加一层透明涂层，模拟车漆、碳纤维、清漆木材等真实世界中的表面效果。
 
-## Work 核心能力增强
-> 为 WorkObserver 提供了更多实用的工具函数，便于进行坐标和 UV 转换。
+这个能力可以实现材质动画。比如
+- 漆面等光滑的表面
+- 塑料薄膜
+- 等等
 
-### UV 转换工具函数
-*   `vectorToEquirectangularUv`: 将方向向量转化为全景图 uv。
-*   `equirectangularUvToVector`: 将全景图 uv 转化为方向向量。
-*   `vectorToCubemapUv`: 将方向向量转化为立方体贴图 uv。
-*   `cubemapUvToVector`: 将立方体贴图 uv 转化为方向向量。
+#### KHR_materials_transmission
+> 物理透光材质扩展，用于实现光线真正穿过物体的透明 / 半透明效果。
 
-## 新增后处理效果 (Post-Processing Passes)
-> 新增了三个可选的内置后处理 Pass，用于增强视觉效果。
+这个能力可以实现材质动画。比如
+- 玻璃等即透光也反射的表面
+- 等等
+
+#### KHR_materials_emissive_strength
+> 调整自发光强度
 
-*   **[FlowingLight2DPass](../features/flowing-light-2d-pass.md)**: 2D 流光效果，通常用于在屏幕空间绘制流动的光线（如道路流光）。
-*   **[FlowingLight3DPass](../features/flowing-light-3d-pass.md)**: 3D 流光效果，基于深度缓冲区在三维模型表面绘制流光。
-*   **[GaussianBlurPass](../features/gaussian-blur-pass.md)**: 高斯模糊效果，可用于实现毛玻璃等视觉特效。
+#### KHR_materials_unlit
+> 不感光材质
+正确解析 KHR_materials_unlit。是否感光作用到对应的 material 上，而不是 gltf 中的所有元素。
 
-## AI 友好文档 (AI Guides)
-> 全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。
+### 动画优化
+- 处理额外动画骨骼未绑定导致的错误，出现的抖动。
+- 修复 glTF 骨骼 weight 为整型时，导致 boneTransform 计算出错进而引发射线检测错误的问题。gltf parser 在加载非 float 数据时，现已自动转换为 float 使用。
 
-*   文档目录迁移至 `ai_guides/`，并在 `package.json` 中新增 `ai` 字段指向该目录。
-*   文档内容包含源码链接 (`source` 字段)，直接指向对应的 `.ts` 定义文件。
-*   提供了更清晰的 API 定义和概念说明，例如新增了 [ViewLayer](../features/view-layer.md) 的详细文档。
+## 模型 ViewLayer 加载策略优化
+> 优化了 ViewLayer 的加载和显隐逻辑，以减少内存占用并提高性能。
+
+#### 默认加载策略变更
+默认情况下，Five 不再加载所有图层，而是根据优先级仅加载一个图层。
+优先级顺序：mesh > point_cloud > gaussian_splatting > 其他类型。
+
+#### 显隐与内存管理
+- 显示: 当 viewLayer.visible = true 时，开始加载资源。
+- 隐藏: 当 viewLayer.visible = false 时，释放该图层占用的所有内存资源。
+
+#### 加载进度
+- 新增 tile.content.loadProgress 属性，用于查看每个瓦片的加载进度 (0-1)。
+- 新增 tile.content.byteLength 属性，可在加载过程中获取瓦片内容的字节长度。
+- 同时，model.tileLoad 和 model.tileUnload 事件被添加，用于监控瓦片的生命周期。
+- 加载函数（loadGltf, loadPly 等）现在支持 onDownloadProgress 回调，用于监控文件下载进度。
+
+#### 射线检测增强
+- 射线交点 Intersection 对象新增了 tile, model, viewLayer 字段，便于在射线检测时获取更详细的上下文信息。
+- raycaster.hitFilter 回调函数的参数类型定义已更新，包含 model, viewLayer, tile 等上下文信息。
+
+## Work 结构改变
+### Observer 支持 uv 计算工具函数
+为 WorkObserver 提供了更多实用的工具函数，便于进行坐标和 UV 转换。
+UV 转换工具函数
+- observer.vectorToEquirectangularUv: 将方向向量转化为全景图 uv。
+- observer.equirectangularUvToVector: 将全景图 uv 转化为方向向量。
+- observer.vectorToCubemapUv: 将方向向量转化为立方体贴图 uv。
+- observer.cubemapUvToVector: 将立方体贴图 uv 转化为方向向量。
+
+### five.panoId
+新增 `five.panoId` 属性，使其与 `work.observer` 保持一致。
 
-## 其他优化
-*   **点云渲染**: 计算点位透明度时，现在会排除不活跃的点，提升渲染正确性。
-*   **TypeScript 支持**: 优化了 `.d.ts` 打包方式，声明文件现在与源码文件一一对应，提升了 IDE 的跳转体验。
+### derived_id 类型变更
+derived_id 的类型从 `number` 改为 `number | string`。
+
+## 全景图滤镜
+
+新增了全景图滤镜功能，支持实时调整全景图的亮度、对比度、饱和度、色温和色调等参数。
+
+通过 `five.modelScene.parameter.set('panoFilter', filter)` 绑定。
+支持的参数如下：
+- color: 颜色调整，包含色温 (Temperature) 和色调 (Tint)。
+- highlightShadow: 高光和阴影的独立调节。包括高光 (Highlight) 和阴影 (Shadow) 全局（Global）。
+- contrast: 对比度调整。
+- saturation: 饱和度调整。
+
+
+## 新增后处理效果 (Post-Processing Passes)
+新增了三个可选的内置后处理 Pass，用于增强视觉效果。
+
+- FlowingLight2DPass: 2D 流光效果，通常用于在屏幕空间绘制流动的光线（如道路流光）。
+- FlowingLight3DPass: 3D 流光效果，基于深度缓冲区在三维模型表面绘制流光。
+- GaussianBlurPass: 高斯模糊效果，可用于实现毛玻璃等视觉特效。
+
+## 工具优化
+### Work Viewer
+> https://vradmin.lianjia.com/project/
+- 支持 debug -> stateSync。可以打开两个页面，均开启 stateSync。两边同步相机状态。
+- 支持 work.json 拖拽加载加载。
+
+### Model Viewer
+> https://vradmin.lianjia.com/poincare/
+- 支持 debug -> stateSync。可以打开两个页面，均开启 stateSync。两边同步相机状态。
+- 支持 模型文件拖拽加载加载。
+
+### glTF Viewer
+> https://vradmin.lianjia.com/gltf/
+- 支持 debug -> stateSync。可以打开两个页面，均开启 stateSync。两边同步相机状态。
+- 支持 模型文件拖拽加载加载。
+- 支持 额外绑定动画文件（仅读取 gltf 的 animations 的部分，并绑定到当前的模型上）。
+- 支持 额外绑定动画的单独播放和暂停。
+
+## 友好文档
+全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。
+
+- 文档目录迁移至 ai_guides/，并在 package.json 中新增 ai 字段指向该目录。
+- 文档内容包含源码链接 (source 字段)，直接指向对应的 .ts 定义文件。
+- 提供了更清晰的 API 定义和概念说明，例如新增了 ViewLayer 的详细文档。
+- TypeScript 支持: 优化了 .d.ts 打包方式，声明文件现在与源码文件一一对应，提升了 IDE 的跳转体验。
+
+## 其他
+1. 优化 mapview 下滚动缩放。避免滚落所发有时会退回的问题。
+2. 优化 floorplan 从下向上看时的交互的屏幕上下滑动反人类下意识的问题。
+3. 优化 camera.autoNearFar 的计算结果。优化对于小物品的 near 过远以及 出现 z-fighting 的问题。
+4. 添加了 gesture.fire 事件，发生在任意事件被触发。
+5. gestureEvent.center gestureEvent.pointers 中加入了 buttons button shiftKey ctrlKey metaKey altKey 字段。
+6. 修复 gesture.momentum 前没有触发 gesture.create 的问题。
+7. 修复 gesture.pan 中 preventDefault 无法阻止触发 gesture.momentum 的问题。
+8. 修复 gesture.pan 中第一次并没有 event.isFirst = true 的问题。
+9. 添加自定义着色器 mainPanoColor 插入点，可以修改 pano0Color、pano1Color。
+10. 新增 `parameter.resolveValue('xxx')` 快速获取单个参数的最终值，无需创建完整的 `ResolvedParameterValue` 对象。
+11. 新增 `pano.prepare` 事件（ExtendableEvent），支持通过 `waitUntil(promise)` 在点位切换前插入异步操作。`PanoEvent` 和 `PanoPrepareEvent` 新增 `pano` 字段，包含目标点位信息。
+
+## 内部机制改动
+1. glTF 加载 mesh / points 都将直接使用 PBM 材质，而不是作为 PBM_Mesh 扩展形式去替换覆盖使用three内置材质的方式。
+2. 应用 animation pointer 以及 动画优化的原因。目前会重写 hack THREE.PropertyBinding.findNode。
+3. 打包不再合并 .d.ts 文件。便于文档可以更便于找到对应的类型声明。
+4. Parameter 性能优化：新增 `resolveValueTo` 支持对象复用以减少 GC，版本标识改用整数哈希（`versionNumber: number`）替代字符串拼接。

package/ai_guides/template.md

@@ -8,6 +8,12 @@
 
 ## Schema
 
+<!--
+  ⚠️ AI 注意：以下 Definition 链接使用了反引号包裹（代码块格式），这是模板的占位符写法，
+  目的是避免构建时因路径不存在而报错。
+  在编写正式文档时，必须将其还原为标准 Markdown 链接（去掉反引号），并确保路径指向真实存在的 .ts 文件。
+-->
+
 > **Definition**: `[InterfaceName](../../five/path/to/source.d.ts)` 或多个 `[Main](../../lib/...)`, `[Options](../../lib/...)`
 
 (这里放置 Interface 定义、TS 类型或参数表。务必包含 Definition 源码链接。)
@@ -61,6 +67,11 @@
 
 ## Related
 
+<!--
+  ⚠️ AI 注意：以下链接同样使用了反引号包裹（占位符写法）。
+  在编写正式文档时，必须还原为可点击的标准 Markdown 链接，并确保路径指向真实存在的文件。
+-->
+
 *   `[RelatedConcept](./related-concept.md)`: 简述关联关系。
 
 ---