@realsee/five 6.8.0-alpha.1 → 6.8.0-alpha.11

package/ai_guides/release_notes/6.7.md

@@ -0,0 +1,401 @@
+# Release Note 6.7.x
+> 6.7.x 版本发布日志
+
+```shell
+npm install @realsee/five@6.7
+```
+
+## five.laod 的多 Work 的非阻塞性加载
+> `five.load` 时，现在可选择追加或者替换。
+> 并且在切换过程中，可以不再发生切换/锁定视角等妨碍用户持续操作的行为。
+> 这方面的改动只要适用于多项目下，项目追加，分批次加载的情况。
+
+### 使用 `FiveLoadOptions.mode` 在控制 替换 / 追加项目
+
+```ts
+// 替换项目
+// mode: 'replace' 默认
+five.load([parseWork(json1), parseWork(json2)], 'inherit', { mode: 'replace' });
+
+// 追加项目
+// mode: 'add'
+five.load(parseWork(json2), 'inherit', { mode: 'add' });
+```
+
+注意事项：
+- Work 的唯一标识依旧是 `workCode`。 同一场景下，不允许出现两个相同的 `workCode` 的 Work。如果出现会报错处理。
+- 如果通过 `replace` 替换的 Work 的 `workCode` 和当前场景中有一样的（相当于替换一个一样的 Work），则会保留之前的 Work 的模型，直接挂在到新 Work 上，而不是重新加载。
+
+### 重新定义 `state=inherit` 的行为
+
+```ts
+five.load(parseWork(json), 'inherit', { mode: 'add' });
+```
+当 `state=inherit` 时，在切换过程中，可以不再发生切换/锁定视角等妨碍用户持续操作的行为。
+
+- 在模型态：保持当前视角状态
+- 在全景态：如果当前 work 存在则不改变。不存在切换到一个可用的全景点。
+
+## work 更加精简和灵活
+> 针对大项目，对 work 的 json。做精简优化，减少网络传输时间。并且增加灵活性。
+
+### panorama.pattern 模版
+> 通过模版的模式匹配减少重复内容。
+> panoram 中的 hash，index 等参数的重复度很高，对一样的内容可以通过这种方式减少文件长度。
+
+Before:
+```json
+"panorama": {
+  "count": 465,
+  "list": [
+    {
+      "index": 0,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117678",
+      "up": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_u.jpg",
+      "down": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_d.jpg",
+      "left": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_l.jpg",
+      "right": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_r.jpg",
+      "front": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_f.jpg",
+      "back": "images/cube_2048/0/0fd265355dbb94cb22fb930e52dd3c19/0_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+
+    },
+    {
+      "index": 1,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117799",
+      "up": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_u.jpg",
+      "down": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_d.jpg",
+      "left": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_l.jpg",
+      "right": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_r.jpg",
+      "front": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_f.jpg",
+      "back": "images/cube_2048/1/a6ca1991fc6bdb2dbd1a1003d9f62394/1_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+    },
+    {
+      "index": 2,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117912",
+      "up": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_u.jpg",
+      "down": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_d.jpg",
+      "left": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_l.jpg",
+      "right": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_r.jpg",
+      "front": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_f.jpg",
+      "back": "images/cube_2048/2/567f94406885bf06f5586d7972da2b5e/2_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+    },
+    {
+      "index": 3,
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735118067",
+      "up": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_u.jpg",
+      "down": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_d.jpg",
+      "left": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_l.jpg",
+      "right": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_r.jpg",
+      "front": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_f.jpg",
+      "back": "images/cube_2048/3/fa70f0f26594d3023a3824c9a92033da/3_b.jpg",
+      "size_list": [ 2048, 4096 ],
+      "tiles": [ 1, 2, 3 ],
+    },
+    ...
+  ]
+}
+```
+
+After:
+```json
+"panorama": {
+  "count": 465,
+  "pattern": {
+    "up": "images/cube_2048/{index}/{hash}/{index}_u.jpg",
+    "down": "images/cube_2048/{index}/{hash}/{index}_d.jpg",
+    "left": "images/cube_2048/{index}/{hash}/{index}_l.jpg",
+    "right": "images/cube_2048/{index}/{hash}/{index}_r.jpg",
+    "front": "images/cube_2048/{index}/{hash}/{index}_f.jpg",
+    "back": "images/cube_2048/{index}/{hash}/{index}_b.jpg",
+    "size_list": [ 2048, 4096 ],
+    "tiles": [ 1, 2, 3]
+  },
+  "list": [
+    {
+      "hash": "0fd265355dbb94cb22fb930e52dd3c19",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117678",
+      "index": 0
+    },
+    {
+      "hash": "a6ca1991fc6bdb2dbd1a1003d9f62394",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117799",
+      "index": 1
+    },
+    {
+      "hash": "567f94406885bf06f5586d7972da2b5e",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735117912",
+      "index": 2
+    },
+    {
+      "hash": "fa70f0f26594d3023a3824c9a92033da",
+      "derived_id": 0,
+      "derived_id_str": "auto3d-light-vEY8Zp4lPlkZ7R9K_1735118067",
+      "index": 3
+    },
+    ...
+  ]
+}
+```
+
+### 相对路径
+> 在序列话 Work Json 时。资源的地址，均尝试存储为 `base_url` 的相对地址，减少存储的开销。
+
+- 可以通过 `work.getURL` 获取到完整地址。
+  ```ts
+  // 获取图片地址
+  work.getURL(work.observers[0].image.left);
+  ```
+
+- 可以通过修改 `work.baseURL=` 修改前缀。
+
+### 一些字段的新增、废弃与兼容
+- 现在 accessable_nodes 与 visible_nodes 不再有行为差异。visible_nodes 将废弃。
+- observers[].derived_id 的缺损值不再是 undefiend. 而是 0。
+- observers[].derived_id_str 的缺损值不再是 undefiend. 而是 空字符串。
+- 优化 at3d / pbm 的 material_textures 的参数的各种兼容问题 以及 错误的警告信息。
+
+### model 支持 coordinate 以及 up_axis
+- model.coordinate 同 `tileeset.rootMeta.coordinate`。声明 `file_url` 的世界坐标。
+- model.up_axis 设置 `file_url` 模型的上方向, 仅针对 obj / ply 等自身没有上方向定义的模型格式。
+
+### toJSON 方法
+- 通过 `work.toJSON()` 可以获取到当前序列化后的标准 Work Json。类型为 `WorkJson`
+- 该方法并不是返回当时 `parseWork` 时的 Json。 而是从 work 数据中序列化后的结果。
+- 并不包含 `_signature` `certificate` 等字段。
+
+### work-downloader 的速度优化
+
+- 优化 对于 avif 格式的 cube 图的处理的效率。
+- 优化 全景图片瓦片的切割参数，该有尽有。
+- 优化 图片的清晰度参数，目前均使用 95 最为图片质量。
+
+## 模型优化材质展示, 3d-tile，以及碰撞计算
+
+### glTF 模型材质 与 动画
+> 优化 Gltf PBR 材质渲染。
+> 对技术美术输出的模型，更准确的还原。
+
+- 解决混合底色是白色的问题 从修改 CustomBlending 改为在着色器中处理，所以只有使用 PBM 的材质支持。three 默认材质不处理这个改动。
+- 优化 gltf 骨骼绑定，对于骨骼关联大于 4 的情况，使用前 4 个权重大的骨骼，并归一化。并且考虑通过整形数组 normalize 的情况。
+- 修改 gltf 中对 uv2 copy 的逻辑，添加当检测到有 occlusionTexture 材质时，如果没有 uv2 自动拷贝 uv -> uv2。
+
+### glTF 预览工具
+
+地址： [https://vradmin.lianjia.com/gltf/](https://vradmin.lianjia.com/gltf/)
+
+- 支持加载 线上 / 本地文件。gltf / glb。
+- 支持链接 单独的 gltf / glb 动画文件。
+- 内置了 gltf 官方测试集。[https://github.com/KhronosGroup/glTF-Sample-Assets/](https://github.com/KhronosGroup/glTF-Sample-Assets/)
+- 内置多个环境光照，以及上传自定义环境光照 (.exr)。
+
+### 优化模型碰撞
+
+扩展 threejs 的 Raycaster。 支持多个自定义参数。
+
+```ts
+declare module 'three' {
+
+  export interface Raycaster {
+    /**
+     * 只捕获第一个交点
+     */
+    firstHitOnly?: boolean;
+
+    /**
+     * 对交点进行筛选
+     */
+    hitFilter?: (intersect: THREE.Intersection) => boolean;
+
+    /**
+     * 作用楼层
+     */
+    floorIndex?: number;
+  }
+
+}
+```
+
+- firstHitOnly - 只捕获第一个交点。比获取全部取第一个更快获取到结果。
+- hitFilter - 过滤函数，可以根据逻辑否绝一些交点。配合 firstHitOnly 可以更加匹配业务需求。
+- floorIndex - 过滤楼层。默认为当前显示楼层，-1 为所有楼层。其他数字则定向对应的楼层。
+
+同时一些内部逻辑变化
+
+- 内置事件生成的 Raycaster。均设置 firstHitOnly = true。
+- 交点获取，内置过滤掉了 模型裁剪 clippers 中的内容。
+
+### 3d-tile 支持通过内存上限动态调整 maxScreenSpaceError。
+> 目的是通过有限的内存，获取到最清晰的模型效果。
+
+```ts
+// 设置内存最高缓存到 512 MB
+five.modelScene.parameter.set('maxMemoryUsage', 512);
+
+// 设置 maxScreenSpaceError 到 32
+five.modelScene.parameter.set('maxScreenSpaceError', 32);
+
+// 设置通过内存上限动态调整 maxScreenSpaceError
+five.modelScene.parameter.set('memoryAdjustedScreenSpaceError', true);
+```
+
+当设置的 `maxScreenSpaceError` 已经全部加载完毕后，发现内存空间仍有剩余。则会尝试降低 `maxScreenSpaceError` 知道内存大体到达 `maxMemoryUsage` 设置的水平。
+
+- 如果设置的 `maxScreenSpaceError` 已经全部加载完毕后，内存已经大于 `maxMemoryUsage` 设置的水平则不会变化。
+- 因为是动态尝试， 所以悲观情况下会出现在 `maxMemoryUsage` 附近摆动的情况。导致模型反复加载/销毁。
+- 只针对 layer 生效。多个 layer 是单独计算，并不是综合计算。
+
+## 全景浏览
+
+### moveToPano 新增 effect=model 模型过渡效果
+
+通过过渡到模型实现点位游走效果
+
+```ts
+five.moveToPano(0, {
+  effect: 'model',
+});
+```
+
+目前支持:
+
+- fly - 通过相机移动方式变化
+- instant - 直接变化
+- fade - 通过渐变方式变化
+- montage - 通过渐变穿插到黑屏方式变化
+- spread - 通过扩散方式变化
+- zoomin - 通过放大变化
+- zoomout - 通过缩小变化
+- model - 通过过度到模型
+
+### moveToPano 新增参数 effectEasing 控制前后全景图的切换进度
+
+```ts
+function easeInQuad(x: number): number {
+  return x * x;
+};
+
+five.moveToPano({
+  workCode: "axv2ZQMaKZcMl5Bc6x",
+  panoIndex: 51,
+}, {
+  latitude: 0.5314685806864204,
+  longitude: 4.324187623631265,
+  fov: 90,
+  effectEasing: easeInQuad
+})
+```
+
+- effectEasing 生命一个函数，接受一个 0 到 1 的数字， 返回一个 0 到 1 的数字。
+- 当值为 0 时显示前一个全景图。 为 1 时显示后一个全景图。 中间数值为两个全景图的混合， 数值表示混合比例。
+- 用于 地面-天空 等切换切换占比差异较大的情况下单独设置。
+
+### 全景图支持航拍点的差异显示
+
+默认逻辑为:
+```ts
+const five = new Five({
+  panorama: {
+    aerialObserverMinHeight: 5,
+    panoCircleMeshCreator: (observer, options) => {
+      const distance = observer.position.distanceTo(observer.standingPosition);
+      if (distance > options.aerialObserverMinHeight) {
+        return new PanoCircleMeshSolid();
+      } else {
+        return new PanoCircleMesh();
+      }
+    },
+  }
+}
+```
+- 如果距地大于 5 米的点位为航拍点。
+- 如果是航拍点，则使用 PanoCircleMeshSolid， 否则使用 PanoCircleMesh。
+- 内部逻辑。航拍点会面向相机展示。
+
+业务可以修改或介入这个逻辑。
+
+## 渲染以及后处理
+
+重写了渲染相关的逻辑。将 scene-renderer 和 postprocessing 分开
+
+- scene-renderer 场景的渲染相关，需要多次渲染场景采样比如抗锯齿（aa），或者对场景内容改变，必须点云的点融合等。
+- postprocessing 后处理，将 scene-renderer 的结果通过多次处理，比如轮廓增强，调整亮度等，将最终处理后的结果显示到画布上。
+
+### 提供的 scene-renderer
+
+- scene-renderer - 直接渲染
+- point-cloud-high-quality-scene-renderer - 点云融合渲染
+- ssaa-scene-renderer - SSAA算法的抗锯齿渲染
+
+```ts
+// 通过 renderMode 切换
+
+// 直接渲染
+five.renderMode = 'default';
+
+// 点云融合渲染
+five.renderMode = 'point-cloud-high-quality';
+
+// SSAA算法的抗锯齿渲染
+five.renderMode = 'ssaa';
+```
+
+### 内置后处理
+- adaptive-luminance-pass - 屏幕空间动态亮度
+- eye-dome-lighting-pass - 轮廓增强
+
+```ts
+// 开启 eye-dome-lighting-pass
+five.enableEDL = true;
+
+// 开启 adaptive-luminance-pass
+five.enableAdaptiveLuminance = true;
+```
+
+### 自定义后处理
+
+后处理支持 THREE 对于 后处理 Pass 的定义。可以自定义追加。
+
+注意：目前不支持 mask 模版剔除部分的逻辑。
+
+```ts
+
+interface Pass {
+  enabled: boolean;
+  needsSwap: boolean;
+  clear: boolean;
+  renderToScreen: boolean;
+  setSize(width: number, height: number): void;
+  render(
+    renderer: THREE.WebGLRenderer,
+    writeBuffer: THREE.WebGLRenderTarget,
+    readBuffer: THREE.WebGLRenderTarget,
+    deltaTime?: number,
+    maskActive?: boolean
+  ): void;
+}
+
+const myPass: Pass = ...;
+
+this.fiveRenderer.composer.addPass(myPass)
+```
+
+## 其他
+
+- 不再使用分层渲染。enableLayeringRendering 参数废弃。
+- 修复 涉嫌计算 intersectRaycaster, 如果 origin 离得太近会出现取不到的问题，优化 bvhbox 的距离判断逻辑。
+- 优化近处点云碰撞时，规避掉角度大 distanceToRay / distance > 0.07 的点云。
+- 修复多个 five 实例间，共用同一个 work 时 proxy 指向错误 five 实例的问题。
+- 修复 mesh 模型 material.vertexMarks 没有同步 parameterValue.vertexMarks 的问题

package/ai_guides/release_notes/6.8.md

@@ -0,0 +1,90 @@
+# Release Note 6.8.x
+> 6.8.x 版本发布日志
+
+```shell
+npm install @realsee/five@6.8
+```
+
+## Gaussian Splatting (3DGS) 支持
+> Five 现已支持 Gaussian Splatting (3DGS) 渲染管线。这是一种基于点的渲染技术，能够提供高质量的实时渲染效果。
+
+*   **前提条件**: 仅在 WebGL2 环境下可用。
+*   **数据支持**:
+    *   支持 `3dtiles` 中包含 3DGS 数据。
+    *   支持加载 `.spz` (version 2) 或 `.splat` 格式的数据。
+    *   支持通过 glTF 扩展加载 content 为 `.spz` 的 glTF/glb 文件。
+*   **功能特性**:
+    *   支持透视相机与正交相机渲染。
+    *   支持 BVH 构建，支持射线检测 (Raycast)。
+    *   `pbmGSObject` 继承自 `THREE.Points`。
+
+### 配置球谐光照阶数 (SH Degree)
+可以通过 `five.parameter.gsSHDegree` 设置球谐光照阶数，支持 0, 1, 2 阶，默认为 0 阶。
+
+```ts
+const five = new Five({
+    parameters: {
+        gsSHDegree: 1 // 设置为 1 阶 SH
+    }
+});
+```
+
+## ViewLayer 加载策略优化
+> 优化了 ViewLayer 的加载和显隐逻辑，以减少内存占用并提高性能。
+
+### 默认加载策略变更
+默认情况下，Five **不再加载所有图层**，而是根据优先级**仅加载一个**图层。
+优先级顺序：`mesh` > `point_cloud` > 其他类型。
+
+### 显隐与内存管理
+*   **显示**: 当 `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` 等上下文信息。
+
+## glTF 模型支持增强
+> 新增了对更多 glTF 扩展的支持，提升了模型的表现力和动画能力。
+
+### 新增扩展支持
+*   **KHR_animation_pointer**: 允许动画通道指向 glTF 资产中任何对象的任何属性，而不仅仅是节点的平移、旋转和缩放。
+*   **KHR_node_visibility**: 允许设置节点的可见性属性。
+*   **KHR_materials_clearcoat** 用于在材质上添加一层透明涂层，模拟车漆、碳纤维、清漆木材等真实世界中的表面效果。
+*   **KHR_materials_sheen** 绒面 / 绒毛类表面效果。
+*   **KHR_materials_transmission** 物理透光材质扩展，用于实现光线真正穿过物体的透明 / 半透明效果。
+
+## Work 核心能力增强
+> 为 WorkObserver 提供了更多实用的工具函数，便于进行坐标和 UV 转换。
+
+### UV 转换工具函数
+*   `vectorToEquirectangularUv`: 将方向向量转化为全景图 uv。
+*   `equirectangularUvToVector`: 将全景图 uv 转化为方向向量。
+*   `vectorToCubemapUv`: 将方向向量转化为立方体贴图 uv。
+*   `cubemapUvToVector`: 将立方体贴图 uv 转化为方向向量。
+
+## 新增后处理效果 (Post-Processing Passes)
+> 新增了三个可选的内置后处理 Pass，用于增强视觉效果。
+
+*   **[FlowingLight2DPass](../features/flowing-light-2d-pass.md)**: 2D 流光效果，通常用于在屏幕空间绘制流动的光线（如道路流光）。
+*   **[FlowingLight3DPass](../features/flowing-light-3d-pass.md)**: 3D 流光效果，基于深度缓冲区在三维模型表面绘制流光。
+*   **[GaussianBlurPass](../features/gaussian-blur-pass.md)**: 高斯模糊效果，可用于实现毛玻璃等视觉特效。
+
+## AI 友好文档 (AI Guides)
+> 全面重构了文档结构，使其更适合 AI 辅助编程工具 (如 Cursor, Copilot) 阅读和索引。
+
+*   文档目录迁移至 `ai_guides/`，并在 `package.json` 中新增 `ai` 字段指向该目录。
+*   文档内容包含源码链接 (`source` 字段)，直接指向对应的 `.ts` 定义文件。
+*   提供了更清晰的 API 定义和概念说明，例如新增了 [ViewLayer](../features/view-layer.md) 的详细文档。
+
+## 其他优化
+*   **点云渲染**: 计算点位透明度时，现在会排除不活跃的点，提升渲染正确性。
+*   **TypeScript 支持**: 优化了 `.d.ts` 打包方式，声明文件现在与源码文件一一对应，提升了 IDE 的跳转体验。

package/ai_guides/support.md

@@ -0,0 +1,23 @@
+# Browser Support (浏览器支持)
+
+- **Summary**: Five 依赖 WebGL 渲染，支持所有现代浏览器。
+
+## Compatibility
+
+Five 需要浏览器支持 **WebGL 1.0** (推荐 WebGL 2.0 以获得更好性能)。
+
+| Browser | Version Requirement | Note |
+| :--- | :--- | :--- |
+| **Chrome** | >= 69 | 推荐使用最新版 |
+| **Safari** | >= 9 | iOS Safari >= 9 |
+| **Firefox** | >= 45 | |
+| **Edge** | >= 13 | |
+| **Android Webview** | >= 93 (Chrome内核) | |
+
+## WebXR Support
+
+如果需要使用 VR 模式 (XRPanorama)，需要浏览器支持 [WebXR Device API](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API)。
+
+## Related
+
+*   [Quick Start](./quick-start.md)

package/ai_guides/template.md

@@ -0,0 +1,70 @@
+# 功能名称 (中文名称)
+
+- **Summary**: 一段一句话的概要（中文）。
+- **Schema**: 简述涉及的数据结构或类型。
+- **Concepts**: 涉及的核心概念关键词。
+- **Configuration**: 关键配置项说明。
+- **Examples**: 简述提供的示例类型。
+
+## Schema
+
+> **Definition**: `[InterfaceName](../../five/path/to/source.d.ts)` 或多个 `[Main](../../lib/...)`, `[Options](../../lib/...)`
+
+(这里放置 Interface 定义、TS 类型或参数表。务必包含 Definition 源码链接。)
+
+## Concepts
+
+(这里解释核心概念、术语定义及业务逻辑)
+
+## Configuration
+
+(可选：初始化参数、配置项说明。若参数较多，请按以下分类展示)
+
+### Common Configuration (常用配置)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `key` | `type` | `default` | Description. |
+
+### Advanced Configuration (进阶配置)
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `key` | `type` | `default` | Description. |
+
+## Instance Properties
+
+(可选：类文档专用，列出关键属性及类型)
+
+## Instance Methods
+
+(可选：类文档专用，列出关键方法签名及说明)
+
+## Examples
+
+### 快速上手 (Quick Example)
+
+(最小可运行代码)
+
+### 进阶用法 (Advanced Usage)
+
+(更复杂的场景或配置)
+
+## Debugging
+
+(可选：调试技巧、监控方法)
+
+## Common Pitfalls
+
+1. **坑点1**: 说明及规避方法。
+2. **坑点2**: ...
+
+## Related
+
+*   `[RelatedConcept](./related-concept.md)`: 简述关联关系。
+
+---
+
+```yaml
+tags: [keywords, tags]
+```

package/docs/00_FOR_AI_AGENTS.md

@@ -0,0 +1,11 @@
+# FOR_AI_AGENTS 
+> **⚠️ Note for AI Agents:**
+>
+> This directory contains auto-generated HTML documentation which is dense and difficult to parse effectively.
+>
+> **PLEASE IGNORE THE CONTENTS OF THIS DIRECTORY.**
+>
+> 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)

package/docs/README.md

@@ -0,0 +1,11 @@
+# Documentation Directory 
+> **⚠️ Note for AI Agents:**
+>
+> This directory contains auto-generated HTML documentation which is dense and difficult to parse effectively.
+>
+> **PLEASE IGNORE THE CONTENTS OF THIS DIRECTORY.**
+>
+> 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)

package/docs/assets/hierarchy.js

@@ -1 +1 @@
-window.hierarchyData = "eJytWltP3DgU/i95dtn4nvBGKe0iQUGAupUqtDIzZiYlcdhcKKjiv1dOYMbOZCbHsC9TqZwv33cuPr7+jqqybOpo/wcmOEU4xhhxgTBPKcISYyRxHCNBBMIiiRElcYI4TmLECZaIC8ERZQQjSqk14QzhFAkmkMSMIpGmBDEiMOIk4YhTKq5RVOnbXM+arDR1tP87won9NarQ0X70UdX6PG8XmYlQdJeZebTPUNRWebQfFeW8zXX9133393pvbbu3bIo8QtEsV3Ud7UdNPf9gwR/sV+t7NdPRM4pw6hBdNqrRKw7CxStLZhpd3arZOFEH20q3wkYoak32X6u/qkKfq0qbPsbJNYpmyyyfV9pE+z94SiQScYKRoFwgwVKJhBDp9TOKuHDUHpamqco819VKMibJq+ROx7jeNXCr6P4/Bro4RgLHFAlq00+lRIJThoQkxIrDxI3ll5Orzyelmu9Wt8ib2w95Z7a3RkzIekYRY9Th+qqbX2V1d9ne1LMqu9G7GG+zB703BEwT8sR17uCnejy776t1d7l0dI45oEyeUSSI2HQvgNBHgErTzXTSFZtgrgh4cKFR9TgZ63pLiiSXHbvtOm4PKFszz8ziW5m3xdQY7WT4iNAY4FimCGPCEcaS9YJk6gl6fIumx2BZlhoT7lBf6EVWmnD2MRxUgGRuLdwvdaXDBYzhgAKI16htMzt60KYBBf3VOLgGCE8RJjJBmCQSYZIyhGlsfwhFmFL7w2L7kyBMuUSYSvvX5KUfeln7ouumreCyXXtokLgbpGP7t1rPGjClj4CSCneuPi3n+nCpzALu6AACpZVD2jyIMQ8iS+SQ7HKmTZiPDgRKm7LNaeBC12VbzeDcYzigABq7As5ufoZUk2MOpfNa/rkyJZhsZQylInRAdaUfg8bnEAMlptRr5WauKzCnYw6lY/FwgQtmW1uHd047cRJh2yLG170Qd7z+U1Z3NVjI2hrqNXfH6/eL0N7rI6Ck3hz5/eJS13VWmgBSFwElTYhHul7bB/AOQEBq5m/SXmb1U10vJ5eIrvH02hszOuwLh1k1yzWIyzeHsEm5le2yzLN5IGWHAfByQrbyHrZ1UxaBxD0Iwizp2LrBCy9k2bAzwH7x8NSjLNRCB+xvXPvg3iRi0XUkEbv7m5dWHiDCRwD9FtxtEudlDVo4W7twP0XfeYXAwykA3P2hXiXx1tI9duSBJtURaLDvjGJkBxSyo7mLgvTWFl7JBikcRwYL5JK+yHKX7J+zh+n9tTWaHtQU440167rP963h2GTNQbUAVfvOD8DKhGLKB2VSqUK9R9XUN4DCSJyMCDvJ7vT/IW7Xd0ILx6YV2UDa6rEHrK7uj6ewGbG3CzmesZN9x8gIHjCqRleZykEBWZsH+80YR5SL3m/G+KbfG0om/J+Ush5LXAz4zsvMNId52c5DWDdRgJNO4rXvqyzX9NMkWW8WdgAnugzbfx2+b5n+daKenFPcHfldGcOGHY+l3w8qVehGV99U3gJnCxcRfMyJSTc12H+9LVld5g96Hi5nHAmMBR5MoS+feC2U8Jh4yODYxLIbafZGZ0yWra9aN+GqXODbRSV8sJc8bG90tyiEbidXgGARJKWIU057Jd4y1n44SAVUgaXye71Fn93UunqADU3XPthlLrvWYL0eSLDphNJbW6CvXA4PC17H1obP2zrgGAhwzSMYHqzHzvtWOb0ms4ZBF2oiwYhL3FeS8KcYl3TnuNrBuS2dguGeMnF9PZir+yZ70CdtkRllZjDHR1GAOEvsltLRk/5UFvokWyybzCxAzCMY0DWe22aPG12cqvquvxi9erpfF/PWG+ZNDOym2d7rvvGueYTyfXfONgxdCaQcj4Rj5GYZJhBws+zfc8bSPfM4qzJtGmX30yEZGYXBkmLv2d+YlHHW9+XFxqO7esUx3RWX4ATt+AIwUzR2B85HNbtbVPYU742Ctn8Aqse7nX7JgC7uc9VoWNlsYoA1Q71nGCE1M0L5zoKhrDvMsq8x3F1CpezdS1k9BSdmDApMCUuGB6cHJit0yFAeAQGTwtK3dtcxzndmhSXdzsI+jxmLSHBSRpDAnAjvZOPTk1FFNjtXzfIkM0GZ2QoF5keIt7602s78ziyJuFvW2vdLUzEKztjEV4DZS1NX2dXfF0dH4e+qBrCgYx/SvcWRsddsrUNfdFnopnraJSLPjN5zjafXZ/Zl4YDpUi8Km7EgxiEoxGnrbec1pvEw+v/aj5NJCY4txGfvMdsa++pECN8KE+Qxpt1y0L69Gux+js3P/lmmHXBTW5JKq1mztwmDVPvz8x+laxjX"
+window.hierarchyData = "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"