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

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

@@ -173,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

@@ -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
@@ -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/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)`: 简述关联关系。
 
 ---

package/docs/00_FOR_AI_AGENTS.md

@@ -7,5 +7,6 @@
 >
 > Instead, refer to the **ai_guides** directory in the package root. It contains high-quality, structured Markdown documentation specifically optimized for comprehension and retrieval.
 >
-> *   **Go to Guides**: [../ai_guides/README.md](../ai_guides/README.md)
-> *   **Go to API Index**: [../ai_guides/api.md](../ai_guides/api.md)
+> *   **Go to llms.txt**: [llms.txt](../llms.txt)
+> *   **Go to Guides**: [ai_guides/README.md](../ai_guides/README.md)
+> *   **Go to API Index**: [ai_guides/api.md](../ai_guides/api.md)

package/docs/README.md

@@ -7,5 +7,6 @@
 >
 > Instead, refer to the **ai_guides** directory in the package root. It contains high-quality, structured Markdown documentation specifically optimized for comprehension and retrieval.
 >
-> *   **Go to Guides**: [../ai_guides/README.md](../ai_guides/README.md)
-> *   **Go to API Index**: [../ai_guides/api.md](../ai_guides/api.md)
+> *   **Go to llms.txt**: [llms.txt](../llms.txt)
+> *   **Go to Guides**: [ai_guides/README.md](../ai_guides/README.md)
+> *   **Go to API Index**: [ai_guides/api.md](../ai_guides/api.md)

package/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "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"
+window.hierarchyData = "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"