@realsee/five 6.8.0-alpha.9 → 6.8.0

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

@@ -130,7 +130,7 @@ pass.setLines([pathLine]);
 ### `setLine(params: { id: string } & Partial<Omit<Line, 'id'>>)`
 通过 `id` 修改单条线的参数。支持部分更新,只更新传入的字段。
 
-**性能优化**: 
+**性能优化**:
 - 如果 `points` 数量不变,只更新 GPU 的 instance attributes,性能极高
 - 如果 `points` 数量改变,会重建整个 mesh,性能开销较大
 
@@ -187,7 +187,7 @@ pass.setLine({
 
 ### 快速上手 (Quick Example)
 
-
+```typescript
 import { Five } from '@realsee/five';
 import { FlowingLight2DPass } from '../../lib/five/renderer/postprocessing';
 import * as THREE from 'three';
@@ -221,11 +221,12 @@ function animate() {
   five.render();
 }
 animate();
+```
 
 
 ### 多条路径 & 动态更新
 
-
+```typescript
 const pass = new FlowingLight2DPass(five.camera);
 
 // 初始路径集合
@@ -262,7 +263,7 @@ document.addEventListener('click', (e) => {
   const rect = five.canvas.getBoundingClientRect();
   const x = (e.clientX - rect.left) / rect.width;
   const y = (e.clientY - rect.top) / rect.height; // 左上角为原点,无需翻转
-  
+
   const newPath = {
     points: [
       new THREE.Vector2(0.5, 0.5),
@@ -275,11 +276,12 @@ document.addEventListener('click', (e) => {
   };
   pass.setLines([...paths, newPath]);
 });
+```
 
 
 ### 计算路径总长度
 
-
+```typescript
 function calculatePathLength(points: THREE.Vector2[]): number {
   let length = 0;
   for (let i = 1; i < points.length; i++) {
@@ -303,6 +305,7 @@ const pathLine = {
   duration: 2000,
   lineWidth: 0.01,
 };
+```
 
 
 ### 矩形路径示例
@@ -332,7 +335,7 @@ pass.setLines([rectPath]);
 
 ### 高 DPR 场景优化
 
-
+```typescript
 // InstancedMesh 实现自动优化高 DPR 性能
 // 在 DPR=2 的 Retina 屏幕上,性能显著优于全屏着色器方案
 
@@ -352,6 +355,7 @@ const paths = Array.from({ length: 10 }, (_, i) => ({
 }));
 
 pass.setLines(paths);
+```
 
 
 ## Debugging
@@ -435,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

@@ -122,7 +122,7 @@ pass.setLines([pathLine]);
 ### `setLine(params: { id: string } & Partial<Omit<Line, 'id'>>)`
 通过 `id` 修改单条线的参数。支持部分更新,只更新传入的字段。
 
-**性能优化**: 
+**性能优化**:
 - 如果 `points` 数量不变,只更新 GPU 的 instance attributes,性能极高
 - 如果 `points` 数量改变,会重建整个 mesh,性能开销较大
 
@@ -180,7 +180,7 @@ pass.setLine({
 
 ### 快速上手 (Quick Example)
 
-
+```typescript
 import { Five } from '@realsee/five';
 import { FlowingLight3DPass } from '../../lib/five/renderer/postprocessing';
 import * as THREE from 'three';
@@ -215,11 +215,12 @@ function animate() {
   five.render();
 }
 animate();
+```
 
 
 ### 多条 3D 路径
 
-
+```typescript
 const pass = new FlowingLight3DPass(camera);
 
 const paths = [
@@ -258,11 +259,12 @@ const paths = [
 ];
 
 pass.setLines(paths);
+```
 
 
 ### 计算 3D 路径长度
 
-
+```typescript
 function calculatePath3DLength(points: THREE.Vector3[]): number {
   let length = 0;
   for (let i = 1; i < points.length; i++) {
@@ -284,11 +286,12 @@ const pathLine = {
   duration: 3000,
   lineWidth: 3.0,
 };
+```
 
 
 ### 结合相机动画
 
-
+```typescript
 // 光带路径随相机移动自动投影
 const pass = new FlowingLight3DPass(camera);
 
@@ -309,11 +312,12 @@ five.setState({
   mode: Five.Mode.Model,
   // ... 其他参数
 });
+```
 
 
 ### 高 DPR 场景优化
 
-
+```typescript
 // InstancedMesh 实现自动优化高 DPR 性能
 // 在 DPR=2 的 Retina 屏幕上,性能显著优于全屏着色器方案
 
@@ -333,6 +337,7 @@ const paths = Array.from({ length: 10 }, (_, i) => ({
 }));
 
 pass.setLines(paths);
+```
 
 
 ## Debugging
@@ -417,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

@@ -44,6 +44,7 @@ interface GestureEvent {
 
 Five 的手势系统基于 Hammer.js 封装，主要包含以下几种手势：
 
+*   **gesture.fire**: 任意事件被触发。
 *   **gesture.pan**: 拖拽/平移。
 *   **gesture.pinch**: 双指缩放。
 *   **gesture.tap**: 点击。
@@ -176,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

@@ -78,7 +78,9 @@ Five 使用 **Z-up** (Z 轴向上) 的右手坐标系。
 *   `EXT_texture_webp`
 *   `CESIUM_RTC`
 *   `REALSEE_materials_lightmap`
+*   `KHR_gaussian_splatting`
 *   `KHR_gaussian_splatting_compression_spz`
+*   `KHR_gaussian_splatting_compression_spz_2`
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
@@ -341,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

@@ -82,6 +82,7 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 | `receiveShadow` | `boolean` | `false` | 模型是否接收阴影。 |
 | `useAddBlend` | `boolean` | `false` | 是否使用半透明叠加渲染。 |
 | `customShaders` | `PBMCustomShader[]` | `[]` | 自定义 Shader 配置。 |
+| `panoFilter` | `PBMPanoFilter` | `null` | 全景图滤镜 (亮度、对比度、色温等)。详情见 [Pano Filter](./pano-filter.md)。 |
 | `clippers` | `PBMClipperParameter[]` | `[]` | 模型裁切参数。 |
 | `boundingBox` | `THREE.Box3` | `Infinity` | 模型包围盒。 |
 
@@ -97,7 +98,7 @@ Five 支持高性能的点云渲染（PBM），并提供灵活的样式配置：
 | `constantColor` | `THREE.Vector3` | `(0.6, 0.6, 0.6)` | 模型纯色模式下的颜色值。 |
 | `outlineGain` | `number` | `0.0` | 轮廓线增益。 |
 | `distanceGain` | `number` | `0.0` | 距离增益。 |
-| `gsSHDegree` | `number` | `0` | 3D Gaussian Splatting 的球谐阶数。 |
+| `gaussianSplattingSHDegree` | `number` | `0` | 3D Gaussian Splatting 的球谐阶数。 |
 
 ### Internal & Low-Level (内部与底层配置)
 
@@ -122,30 +123,37 @@ 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
 
 *   [Parameter](./parameter.md): 配置系统入口与继承逻辑。
+*   [Pano Filter](./pano-filter.md): 了解全景图滤镜的详细用法。
 *   [3DTile Params](./3dtile.md): 性能与加载相关参数。
 
 ---
 
 ```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

@@ -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]
 ```