@realsee/five 6.8.0-alpha.2 → 6.8.0-alpha.20

package/AGENTS_READ_ME.md

@@ -0,0 +1,4 @@
+# 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`

package/AI_CONTEXT.md

@@ -0,0 +1,4 @@
+# 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`

package/README.md

@@ -4,6 +4,9 @@
 
 贝壳如视三维渲染框架
 
+> **🤖 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`.
 ## Introduction
 
 **Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
@@ -58,20 +61,20 @@ window.addEventListener('resize', () => five.refresh());
 ## Documentation
 
 For comprehensive guides and API references, please refer to the documentation included in this package:
-- [Feature Guides](guides/README.md)
-- [API Reference](guides/api.md)
+- [Feature Guides](ai_guides/README.md)
+- [API Reference](ai_guides/api.md)
 
 **⚠️ Note for AI Agents:**
 
 *   **For a context-optimized index, read [llms.txt](./llms.txt).**
 
 **Do's (推荐):**
-*   **Do** Read [Intro](guides/intro.md) first to understand the high-level architecture.
-*   **Do** Use [API Reference](guides/api.md) for checking method signatures and property types.
-*   **Do** Refer to `guides/*.md` files for feature-specific implementation details.
+*   **Do** Read [Intro](ai_guides/intro.md) first to understand the high-level architecture.
+*   **Do** Use [API Reference](ai_guides/api.md) for checking method signatures and property types.
+*   **Do** Refer to `ai_guides/*.md` files for feature-specific implementation details.
 *   **Do** Prefer Markdown documentation over HTML files or raw code when understanding concepts.
 
 **Don'ts (禁止):**
 *   **Don't** Index or read files in the `docs/` directory (auto-generated HTML). They are redundant and hard to parse.
 *   **Don't** Hallucinate API methods. Always verify against `api.md` or `.d.ts` files.
-*   **Don't** Assume legacy behavior. Check `guides/release_notes/` if you encounter version discrepancies.
+*   **Don't** Assume legacy behavior. Check `ai_guides/release_notes/` if you encounter version discrepancies.

package/{guides → ai_guides}/README.md

@@ -54,14 +54,16 @@
 
 *   [Five](./features/five.md): 核心类 `Five`，管理渲染循环与全局状态。
 *   [Work](./features/work.md): 数据载体，描述三维空间的数据结构 (VR 看房数据)。
+*   [Panorama UV](./features/pano-uv.md): 全景图 UV 与空间方向转换工具。
 *   [Mode](./features/mode.md): 五种核心浏览模式 (Panorama, Floorplan, Topview, Model, Map)。
 *   [State](./features/state.md): 状态管理 (Pose, Mode, PanoIndex)，用于复原场景。
-*   [Coordinate System](./features/coordnate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。
+*   [Coordinate System](./features/coordinate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。
 
 ### 3. Data & Resource (数据与资源)
 数据加载与资源管理配置。
 
 *   [Load External Model](./features/load-external-model.md): 加载外部 3D 模型 (GLTF, OBJ 等)。
+*   [Load Progress](./features/load-progress.md): 监控模型与全景图的加载进度 (Loaded/Refined)。
 *   [Multi-Work (Sandbox)](./features/multi-work.md): 多 Work 加载与沙盘场景管理。
 *   [Request Proxy](./features/request-proxy.md): 请求拦截与代理 (CDN 替换、鉴权)。
 *   [Image Options](./features/image-options.md): 图片资源配置 (CDN, 格式, 尺寸)。
@@ -72,6 +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): 屏幕空间流光特效(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): 模型裁切功能 (房屋剖面)。
@@ -89,13 +96,15 @@
 ### 6. Advanced & Extensions (进阶与扩展)
 复杂配置与功能扩展。
 
-*   [Plugin](./plugin.md): 插件开发指南。
+*   [Plugin](./features/plugin.md): 插件开发指南。
+*   [ViewLayer](./features/view-layer.md): 视图层。
 *   [Parameter](./features/parameter.md): Five 初始化详细参数配置。
 
 ### 7. Meta & Support (其他)
 *   [Support](./support.md): 浏览器兼容性。
 *   [AI Documentation Guidelines](./ai-doc-guidelines.md): AI 文档编写与维护规范 (必读)。
 *   Release Notes: 版本更新记录。
+    *   [6.8](./release_notes/6.8.md)
     *   [6.7](./release_notes/6.7.md)
     *   [6.6](./release_notes/6.6.md)
 
@@ -111,3 +120,4 @@
 ```yaml
 tags: [index, readme, guide, map]
 ```
+

package/ai_guides/ai-doc-guidelines.md

@@ -0,0 +1,102 @@
+<!-- AI-friendly guide template for `ai_guides/` -->
+# AI 文档与维护指南 (AI Documentation & Maintenance Guide)
+
+## Summary
+本文档包含两部分内容：
+1.  **Writing Guide**: 供 AI 和人类编写新文档时的标准模板与风格规范。
+2.  **Maintenance Guide**: 供 AI 维护者进行文档更新、同步与体检的操作指南。
+
+---
+
+# Part 1: Writing Guide (编写指南)
+
+## 目的
+提供统一、结构化的 Markdown 模板，便于 AI 自动解析、索引与生成功能性示例。
+
+## 建议风格
+- 使用中文为主，代码示例使用 TypeScript。
+- **受众意识**: 文档面向 SDK 的**外部使用者**。避免暴露无用的内部实现细节（如私有属性、临时状态），除非对调试有帮助。
+- **结构规范**: 严格使用二级标题 (`##`) 作为主要段落分割（如 `## Schema`, `## Concepts`），避免使用中文标题（如 `## 格式说明`）。
+- **代码缩进**: 强制使用 **两个空格** 缩进。
+- **相对路径**: 内部文档链接必须使用 **相对路径**（如 `./state.md`）。
+- **Schema**: 必须提供 TypeScript Interface 定义，并保留关键字段的注释（JSDoc）。
+    - **精简原则**: 仅展示核心与常用字段，避免列出所有内部或废弃字段。
+- **Configuration**: 对于参数较多的配置项，建议按 **“常用 (Common)”**、**“进阶 (Advanced)”**、**“内部 (Internal)”** 进行分类表格展示，并在内部参数处添加“不建议修改”的警告。
+- **Source Link**: 引用源码文件时，请在 `## Schema` 章节中使用 `> **Definition**: [InterfaceName](../../path/to/source.ts)` 的格式。**支持多个链接**（如 `[Five](...), [EventTypes](...)`），以便完整覆盖相关类型。**必须** 指向 `lib/` 目录下的 `.ts` 文件。构建脚本会自动将其转换为发布包中的 `.d.ts` 链接。
+- **Related**: 文档末尾建议包含 `## Related` 章节，提供相关文档的**相对路径链接**。
+    - **语义化**: 链接文字应准确反映目标文档的主题（如 `[Coordinate System](./coordinate.md)`）。
+- **Metadata**: 结尾必须包含 YAML 格式的 `tags`。
+- **文档拆分与审查**: 单个文档应保持精简。若内容过多需拆分为新专题，**必须**在创建新文件前向用户确认并获得批准，严禁擅自创建新文件。
+
+## 最佳实践 (Best Practices)
+
+### 1. 变量命名语义化 (Semantic Variable Naming)
+在示例代码中，变量名应准确反映其通用性或特定上下文。
+- **Good**: `parentParameter` (暗示可用于 Model, ViewLayer 等多种父级)
+- **Bad**: `modelParam` (若该逻辑同样适用于 ViewLayer，则会误导用户)
+
+### 2. 区分属性与方法 (Property vs Method)
+明确区分“直接访问属性”与“调用方法计算”。
+- 若 API 设计为 Getter (如 `parameter.opacity`)，文档应引导用户直接访问属性，避免混淆使用 `get()` 方法。
+- 对于涉及计算或继承的逻辑 (如 `resolveValue()`)，应显式说明其与直接访问的区别。
+
+### 3. 显式说明默认行为 (Explicit Default Behavior)
+对于有默认值或继承逻辑的方法，务必说明“不传参”时的行为。
+- 例如：`resolveValue()` 不传参时仅计算默认值；传入 `upstream` 时会包含继承逻辑。
+
+## 标准模板结构 (Standard Template Structure)
+
+无论是**新建文档**还是**维护现有文档**，都请参考独立模板文件：[template.md](./template.md)。
+
+- **新建文档**: 直接复制模板内容开始编写。
+- **维护文档**: 在修改现有文档时，请检查其结构是否符合模板要求（如 Schema 的 Definition 引用、Configuration 的分类等）。如果发现结构过时，请顺手将其标准化。
+- **特殊说明 (Special Notes)**:
+    - **模板链接格式 (Template Link Format)**:
+        - 模板(`template.md`)中所有的占位符链接（如 `Definition` 处的 `[InterfaceName](...)` 或 `Related` 处的 `[RelatedConcept](...)`）均使用了**代码块**包裹，以避免构建时因路径不存在而报错。
+        - **AI 操作**: 在编写正式文档时，**必须将其还原为可点击的标准 Markdown 链接**（即去掉反引号），并确保路径指向真实存在的文件。
+
+请严格遵循该模板的结构，以保证文档风格一致性。
+
+---
+
+# Part 2: Maintenance Guide (维护指南)
+
+## 核心原则 (Core Principles)
+为了防止文档与代码脱节，我们遵循 **“代码变更驱动文档更新”** 的原则。
+
+## 1. 语义化检索 (Semantic Retrieval)
+不再维护硬编码的“源码-文档”映射表。AI 维护者在修改代码后，应利用自身的语义搜索能力（如 `SearchCodebase` 或 `Grep`）来定位需要更新的文档。
+
+**推荐策略**:
+- 搜索**类名/方法名**: 如修改了 `five.load`，搜索 `five.load` 或 `load`。
+- 搜索**概念关键词**: 如修改了射线检测逻辑，搜索 `Raycast` 或 `project2d`。
+
+## 2. 单一事实来源 (Single Source of Truth)
+- **API 签名**: 以 `package/five/index.d.ts` 和代码中的 TSDoc 为准。
+- **ai_guides/api.md**: 仅作为 **索引 (Index)** 和 **摘要 (Summary)**。不要试图复制所有参数细节，除非是核心参数。
+- **ai_guides/features/*.md**: 重点解释 **“为什么”** 和 **“怎么用”**，避免机械复制类型定义。
+
+## 3. 维护工作流 (Maintenance Workflow)
+
+### 场景 A：代码功能迭代后 (Post-Coding)
+当修改了 SDK 源码后，请执行以下检查：
+1.  **反向查找**: 利用工具搜索关键词（API 名称、Feature 名称），找到 `ai_guides/` 下相关的文档。
+2.  **更新文档**:
+    *   如果修改了 API 签名 -> 更新对应的 `Schema` 和 `Examples`。
+    *   如果废弃了功能 -> 在文档中添加 `> [!WARNING] Deprecated` 提示。
+3.  **更新索引**: 如果是新功能，确保将其添加到 `ai_guides/README.md` 的合适章节中。
+4.  **同步 llms.txt**: 若新增了文档或修改了文档路径，**必须**同步更新项目根目录下的 `llms.txt`，确保外部索引与 `ai_guides/` 保持一致。
+
+### 场景 B：API 文档同步 (Sync API Doc)
+定期检查 `ai_guides/api.md` 的完整性：
+1.  读取 `package/five/index.d.ts` 获取最新公开 API。
+2.  对比 `ai_guides/api.md`，找出缺失的高频 API 或已删除的 API。
+3.  **注意**: 只收录高频/核心 API，低频 API 应引导用户查看源码或专门的 Feature 文档。
+
+## 目录结构说明
+- `ai_guides/`: 文档根目录。
+- `ai_guides/features/`: 功能性文档 (Features)。
+- `ai_guides/release_notes/`: 版本更新记录。
+- `ai_guides/api.md`: 核心 API 索引。
+- `ai_guides/README.md`: 文档总索引。
+- `package/five/index.d.ts`: **API 签名的真理来源**。

package/{guides → ai_guides}/api.md

@@ -83,7 +83,7 @@ interface FiveInitArgs {
 ### `load(work, state?, options?)`
 Loads a "Work" (dataset) into the Five instance.
 
-- **work**: The data object containing scene information (panorama, model, etc.).
+- **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).
 
@@ -139,6 +139,16 @@ Get pixel data from the renderer (e.g. for color picking or magnifier).
 - **raycaster**: `THREE.Raycaster`.
 - **returns**: `THREE.Intersection[]`.
 
+### `addPass(pass)`
+Add a post-processing pass to the rendering chain.
+
+- **pass**: `FivePass` instance (e.g. `Gaussian Blur Pass`).
+
+### `removePass(pass)`
+Remove a post-processing pass from the rendering chain.
+
+- **pass**: `FivePass` instance to remove.
+
 ### `dispose()`
 Destroys the Five instance and releases resources.
 
@@ -187,6 +197,16 @@ interface WorkObserver {
   accessibleNodes: number[]; // Indices of reachable points
   images: WorkImage;         // Panorama image URLs
   active: boolean;           // Whether the point is enabled
+
+  // Coordinate Methods
+  getWorldPosition(): THREE.Vector3;
+  getWorldStandingPosition(): THREE.Vector3;
+
+  // UV Conversion Methods
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [CubeFace, THREE.Vector2];
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
 }
 ```
 
@@ -223,7 +243,10 @@ These events follow a standard naming convention and provide typed event objects
 | :--- | :--- | :--- |
 | `works.load` | Triggered when work data starts loading. | `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` |
 | `pano.arrived` | Triggered when arrival at a panorama node. | `PanoEvent` |
+| `pano.texture.progress` | Triggered when panorama texture loading progresses. | `{ progress, panoIndex }` |
 | `render` | Triggered after each render frame. | `RenderEvent` |
 | `error` | Triggered on internal errors. | `Error` |
 

package/ai_guides/features/3dtile.md

@@ -0,0 +1,172 @@
+# 3DTile (3D 瓦片)
+
+- **Summary**: Five 用于加载和渲染大规模三维场景的核心模块，支持动态 LOD 调度与流式加载。
+- **Schema**: 对应 `ParameterTilesetValue` 接口，通过 Parameter 配置 LOD、显存与并发控制。
+- **Concepts**: LOD (细节层级), SSE (屏幕空间误差), Cache Management (显存管理), ViewLayer (视图层)。
+- **Configuration**: 包含画质精度、显存配额、几何误差、并发请求等详细参数。
+- **Examples**: 画质平衡与多图层优化。
+
+## Schema
+
+> **Definition**: [ParameterTilesetValue](../../five/model/parameter.d.ts)
+
+以下是 `ParameterTilesetValue` 的 TypeScript 定义摘要：
+
+```typescript
+export interface ParameterTilesetValue {
+  /** 屏幕空间误差阈值 (像素) */
+  maxScreenSpaceError: number;
+  /** 最大显存占用 (MB) */
+  maxMemoryUsage: number;
+  /** 最小几何误差 (精度上限锁) */
+  minGeometricError: number;
+  // ... 更多字段见下方配置表
+}
+```
+
+## Concepts
+
+### 1. LOD & Screen Space Error (SSE)
+
+LOD (Level of Detail) 是 3DTile 的核心机制。引擎不会一次性加载整个从宏观到微观的所有模型数据，而是根据相机位置动态计算每个瓦片的 **屏幕空间误差 (SSE)**。
+
+*   **Geometric Error (几何误差)**: 3D Tiles 数据源中定义的指标（单位：米），表示当前瓦片与真实物体之间的最大形状差异。
+    *   **根节点**: 误差巨大（如 100米），仅有模糊轮廓。
+    *   **叶子节点**: 误差极小（如 0.01米），细节丰富。
+*   **SSE 计算逻辑**: `SSE = (GeometricError / DistanceToCamera) * ScreenHeight`。
+*   **判定标准**: 如果 `SSE > maxScreenSpaceError`，说明当前瓦片在屏幕上看起来太粗糙（误差像素太大），需要分裂并加载下一级子瓦片；反之则停止细分。
+*   **调整影响**: 调低 `maxScreenSpaceError` 会迫使引擎加载更深层级的瓦片，从而获得更清晰的细节，但也会急剧增加渲染三角形数量和显存占用。
+
+### 2. 显存管理 (Cache Management)
+
+为了在浏览器有限的资源下渲染海量数据（如城市级倾斜摄影），3DTile 实现了基于 LRU (Least Recently Used) 的缓存淘汰机制和动态画质调整策略。
+
+*   **LRU 淘汰**: 当 `maxMemoryUsage` 超限时，引擎会优先保留当前视锥体内的瓦片。视锥体外的、或者距离相机较远的瓦片会被优先释放。
+*   **动态画质调整 (Dynamic Scaling)**: 如果开启了 `memoryAdjustedScreenSpaceError`，引擎会以 `maxMemoryUsage` 为目标，实时调整 SSE。
+    *   **目标**: 尽量跑满 `maxMemoryUsage` 设定的显存额度，不浪费资源。
+    *   **范围**: 实际 SSE 会在 `1.0` (极高画质) 到 `maxScreenSpaceError` (设定底线) 之间波动。
+    *   **场景**: 适合显存充足但希望自动平衡画质的场景。
+
+### 3. ViewLayer 与 3DTile
+
+目前所有的 `ViewLayer` 在底层都是一个 `Tile3D` 实例。它们各自拥有独立的：
+*   **配置**: `maxScreenSpaceError`, `maxMemoryUsage` 等参数互不干扰。
+*   **缓存**: 显存配额各自独立计算。
+
+> **注意**: 即使是通过 `file_url` 加载的单体模型（如 `.obj`, `.at3d`），在 Five 内部也会被封装为 `Tile3D` 实例进行统一管理。
+
+## Configuration
+
+以下表格列出了控制 3DTile 加载与性能调度的所有可用参数。
+
+### Core Quality & Performance (核心画质与性能)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxScreenSpaceError` | `number` | `16` | **核心参数**。屏幕空间误差阈值 (像素)。<br>值越小画质越高，性能开销越大。建议范围 8-32。 |
+| `maxMemoryUsage` | `number` | `512` | 最大显存占用 (MB)。超限后自动触发 LRU 淘汰机制。 |
+| `memoryAdjustedScreenSpaceError` | `boolean` | `false` | 是否开启基于内存的动态 SSE 调整。<br>开启后引擎会自动调整 SSE 以尽量占满显存配额。 |
+| `cameraCulling` | `boolean` | `true` | 是否开启视锥体剔除 (不加载视野外的瓦片)。**建议始终开启**。 |
+
+### Geometric Error Control (几何误差控制)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `minGeometricError` | `number` | `0` | 最小几何误差 (精度上限锁)。<br>当瓦片误差小于此值时停止细分。可用于限制过高精度的加载。 |
+| `maxGeometricError` | `number` | `10000` | 最大几何误差 (最低精度保证)。<br>强制细分直到误差小于此值。可用于避免模型过于模糊。 |
+
+### Network & Loading (网络与加载)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxRequests` | `number` | `4` | 最大并发请求数。建议保持默认，避免网络拥堵。 |
+| `requestOrder` | `string` | `'SCREEN_SPACE_ERROR'` | 请求优先级策略。<br>`'SCREEN_SPACE_ERROR'`: 优先加载 SSE 大的瓦片；<br>`'SCREEN_LEVEL_VERTICAL'`: 优先加载垂直层级高的。 |
+| `loadSiblings` | `boolean` | `true` | 是否预加载兄弟节点。 |
+| `skipLevelOfDetail` | `boolean` | `false` | 是否允许跳级加载 (跳过中间层级直接加载高精瓦片)。 |
+
+### Legacy LOD Control (不推荐)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `minLevelOfDetail` | `number` | `0` | 最小 LOD 层级 (Tree Depth)。建议使用 `maxGeometricError` 替代。 |
+| `maxLevelOfDetail` | `number` | `20` | 最大 LOD 层级 (Tree Depth)。建议使用 `minGeometricError` 替代。 |
+
+## Examples
+
+### 1. Adjusting Quality & Memory (调整画质与内存平衡)
+
+在移动端或性能受限设备上，建议适当降低画质以保证流畅度。
+
+```typescript
+const parameter = five.modelScene.parameter;
+
+// 1. 性能优先模式 (适用于低端设备)
+// 增大 SSE 阈值，降低画质
+parameter.set('maxScreenSpaceError', 16);
+// 限制显存，防止 Crash
+parameter.set('maxMemoryUsage', 256);
+
+// 2. 画质优先模式 (适用于桌面端/截图)
+// 减小 SSE 阈值，提升细节
+parameter.set('maxScreenSpaceError', 4);
+// 允许更多显存占用
+parameter.set('maxMemoryUsage', 1024);
+
+// 3. 重置为默认
+parameter.reset('maxScreenSpaceError', 'maxMemoryUsage');
+```
+
+### 2. Multi-ViewLayer Optimization (多 ViewLayer 优化)
+
+在对比查看或多楼层场景中，通常存在多个 `ViewLayer`。为了避免资源竞争，建议对非焦点的 ViewLayer 进行降级处理。
+
+```typescript
+// 假设 viewLayerA 是当前主要查看的模型，viewLayerB 是背景参考
+
+// 聚焦 ViewLayerA: 正常画质
+viewLayerA.parameter.reset('maxScreenSpaceError');
+
+// 降级 ViewLayerB: 仅显示轮廓，节省资源
+viewLayerB.parameter.set('maxScreenSpaceError', 48); // 极低画质
+viewLayerB.parameter.set('maxMemoryUsage', 128);     // 极低显存配额
+```
+
+## Debugging
+
+在开发过程中，可以通过访问 `ViewLayer` 内部的 `tileset` 对象来实时监控渲染状态。
+
+```typescript
+// 假设已获取 viewLayer 实例
+const tileset = viewLayer.tileset;
+
+// 1. 查看当前加载的瓦片数量
+console.log(tileset.loadedTiles.size);
+
+// 2. 查看当前实际生效的 SSE (如果开启了动态调整，此值会波动)
+console.log(tileset.currentMaxScreenSpaceError);
+
+// 3. 查看显存占用 (近似值，单位字节)
+// 注意: 这是内部私有属性，仅供调试参考
+console.log((tileset as any).cacheMemoryUsageInBytes / 1024 / 1024 + ' MB');
+```
+
+## Common Pitfalls
+
+1.  **误解 GeometricError 作用域**: `minGeometricError` 和 `maxGeometricError` 是**全局硬约束**，不随相机距离变化。
+    *   错误设置（例如将 `maxGeometricError` 设得极小）会强制全场景所有瓦片（哪怕是远处的背景）都加载到极高精度。
+    *   这会导致三角形数量和显存占用**指数级爆炸**，瞬间卡死浏览器。
+2.  **过度降低 `maxScreenSpaceError`**: 设置过小（如 < 4）可能导致每帧需要加载和渲染的三角形数量指数级上升，瞬间撑爆显存或导致掉帧。
+3.  **忽略 `cameraCulling`**: 默认应该开启。如果手动关闭视锥体剔除，引擎将尝试加载全场景数据，极易导致崩溃。
+4.  **频繁切换配置**: `maxMemoryUsage` 等参数的修改会触发缓存整理，高频修改可能导致卡顿。
+
+## Related
+
+*   [Parameter](./parameter.md): 了解参数的继承关系及材质、点云相关配置。
+*   [Model](./model.md): 了解 Model 和 ViewLayer 的关系。
+*   [Work](./work.md): 了解 Work 数据结构。
+
+---
+
+```yaml
+tags: [3dtile, viewLayer, performance, lod, optimization]
+```

package/{guides → ai_guides}/features/camera-animation.md

@@ -10,6 +10,8 @@
 
 ### MovePanoOptions
 
+> **Definition**: [MovePanoOptions](../../five/types/movePanoOptions.d.ts)
+
 点位移动参数配置。
 
 ```typescript
@@ -18,8 +20,12 @@ interface MovePanoOptions extends Partial<Omit<State, "offset" | 'distance' | 'm
   effect?: MovePanoEffect;
   /** 走点图片过度策略 */
   effectEasing?: (progress: number) => number;
-  /** 运动耗时 (ms) */
-  duration?: number;
+  /**
+   * 运动耗时 (ms)
+   * - number: 固定时长
+   * - function: (distance, speed) => number 根据距离动态计算
+   */
+  duration?: number | ((distance: number, speed: number) => number) | string | null;
   /** 运动开始回调 */
   moveStartCallback?: (toState: State) => void;
   /** 运动结束回调 */
@@ -92,9 +98,24 @@ five.changeMode(mode: Mode, options?, animationOptions?): Promise<void>
 
 ## Configuration
 
+### Global Configuration (全局配置)
+
 在 `new Five(config)` 初始化时可以设置全局动画参数：
 
-*   `modeChangeDuration`: 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。默认为 1000ms。
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `modeChangeDuration` | `number` | `1000` | 模态切换 (如 Panorama -> Mapview) 的默认时长 (ms)。 |
+
+### MovePanoOptions Configuration (移动参数)
+
+调用 `five.moveToPano(index, options)` 时使用的配置参数：
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `effect` | `MovePanoEffect` | `'fly'` | 动画效果。<br>`'fly'`: 空间移动（模拟行走）；<br>`'fade'`: 淡入淡出（保持位置不变）；<br>`'instant'`: 瞬间跳转。 |
+| `duration` | `number` \| `Function` | - | 动画时长 (ms)。若不传，则根据距离和速度自动计算。 |
+| `effectEasing` | `Function` | - | 自定义过渡效果的缓动函数。 |
+| `moveEndCallback` | `Function` | - | 动画结束后的回调函数。 |
 
 ## Examples
 

package/{guides → ai_guides}/features/clipper.md

@@ -8,6 +8,8 @@
 
 ## Schema
 
+> **Definition**: [PBMClipperParameter](../../five/model/materials/pbmMaterial.d.ts)
+
 ```typescript
 /** 模型裁切参数 */
 interface PBMClipperParameter {

package/{guides/features/coordnate-system.md → ai_guides/features/coordinate-system.md}

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [TilesetHeader](../../five/model/tile3d/header.d.ts)
+
 ### RootMeta
 
 3D Tiles `rootMeta` 字段中定义的坐标系元数据。

package/{guides → ai_guides}/features/event.md

@@ -7,6 +7,8 @@
 
 ## Schema
 
+> **Definition**: [Five](../../five/application/five.d.ts), [EventTypes](../../five/application/events.d.ts)
+
 Five 实例提供了以下方法来管理事件监听：
 
 ### on

package/{guides → ai_guides}/features/five.md

@@ -9,6 +9,9 @@
 ## Schema
 
 ### FiveInitArgs
+
+> **Definition**: [FiveInitArgs](../../five/application/fiveInitArgs.d.ts)
+
 `new Five(args)` 的初始化参数对象。
 
 ```typescript
@@ -155,6 +158,7 @@ five.updateCameraWithKeyframes(keyframes, 2000).then(() => {
 - **`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)。
 - **`ready(args?: { tile?: boolean })`**: Promise，当 Five 状态稳定时 resolve。
   - **Resolve 时机**：
     1. **状态同步**：相机姿态已通过动画过渡到目标状态（`stateSynced` 为 true）。