@realsee/five-webgpu 1.0.0-alpha.1

package/AGENTS_READ_ME.md

@@ -0,0 +1,9 @@
+# AI_CONTEXT
+You are an AI assistant.
+This package contains comprehensive local documentation.
+DO NOT search the web for documentation.
+
+**START HERE → Read [llms.txt](./llms.txt)** for a context-optimized index with scenario-based lookup and keyword tags.
+
+For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+Do NOT use the `docs/` directory (auto-generated HTML).

package/AI_CONTEXT.md

@@ -0,0 +1,9 @@
+# AI_CONTEXT
+You are an AI assistant.
+This package contains comprehensive local documentation.
+DO NOT search the web for documentation.
+
+**START HERE → Read [llms.txt](./llms.txt)** for a context-optimized index with scenario-based lookup and keyword tags.
+
+For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+Do NOT use the `docs/` directory (auto-generated HTML).

package/README.md

@@ -0,0 +1,80 @@
+# Five.js
+
+[![npm version](https://img.shields.io/npm/v/@realsee/five.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five)](https://www.npmjs.com/package/@realsee/five)
+
+贝壳如视三维渲染框架
+
+> **🤖 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 看房与空间交互应用。
+
+核心能力包括：
+*   **全景浏览**: 高分辨率全景图的高效加载与平滑浏览。
+*   **空间漫游**: 在三维模型中自由行走、跳转。
+*   **模型渲染**: 内置高效的模型加载策略 (3DTile)。
+*   **交互事件**: 完善的手势与射线检测系统。
+
+## Installation
+
+通过 npm 或 yarn 安装：
+
+```bash
+npm install three@^0.117.1 @realsee/five
+# or
+yarn add three@^0.117.1 @realsee/five
+```
+
+> **注意**: Five 依赖 `three`，目前推荐版本为 `0.117.1`。
+
+## Quick Start
+
+```typescript
+import { Five, parseWork } from "@realsee/five";
+
+// 1. 初始化
+const five = new Five();
+five.appendTo(document.getElementById('app'));
+
+// 2. 加载数据
+const workURL = 'https://raw.githubusercontent.com/realsee-developer/dnalogel/main/open-works/real/80o024DE2xyva3j5BE/work.json';
+fetch(workURL).then(res => res.json()).then(json => {
+  five.load(parseWork(json));
+});
+
+// 3. 适配窗口
+window.addEventListener('resize', () => five.refresh());
+```
+
+## Browser Support
+
+| Browser | Version | Note |
+| :--- | :--- | :--- |
+| **Chrome** | >= 69 | |
+| **Safari** | >= 9 | iOS Safari >= 9 |
+| **Firefox** | >= 45 | |
+| **Edge** | >= 13 | |
+| **Android** | >= 93 | Chrome内核 |
+
+## Documentation
+
+For comprehensive guides and API references, please refer to the documentation included in this package:
+- [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](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 `ai_guides/release_notes/` if you encounter version discrepancies.

package/TERMS.txt

@@ -0,0 +1,54 @@
+Realsee SDK License Agreement
+Update: July 28, 2021
+THIS LICENSE AGREEMENT BETWEEN YOU AND 【BEIKE REALSEE TECHNOLOGY (HK) LIMITED】(“Realsee”) FORMS A LEGALLY BINDING CONTRACT BETWEEN YOU AND REALSEE IN RELATION TO YOUR USE OF THE SDK. This License Agreement accompanies the Realsee Software Development Kit(s) for the software and related explanatory materials (the "SDK") and includes any upgrades, modified versions, updates, additions, and copies of the SDK licensed to You by Realsee.
+BY DOWNLOADING, INSTALLING, OR OTHERWISE ACCESSING OR USING THE SDK, YOU AGREE THAT YOU HAVE READ, UNDERSTOOD, AND AGREE TO BE BOUND BY THIS AGREEMENT. YOU ARE AGREEING ON YOUR OWN BEHALF AND/OR ON BEHALF OF YOUR COMPANY OR ORGANIZATION TO THE TERMS AND CONDITIONS STATED BELOW.
+This Agreement applies to Your use of the SDK in the country in which You legally install it (“Territory”) and is subject to the laws of such Territory and further subject to Section 12 below. Different terms, conditions, and limitations may apply to the use of the SDK in any additional countries.
+1. DEFINITIONS.
+“Agreement” means this Realsee SDK License Agreement.
+“Developer”, “You” and “Your” means the person(s) or entity acquiring or using the SDK or otherwise exercising rights under the terms of this Agreement.
+“Documentation” means the technical or other specifications or documentation that Realsee may provide to You for use in connection with the SDK.
+“Integrated Product” means any software, website, or on-line service developed by You based on or using the SDK (collectively, the “Integrated Product”).
+“Intellectual Property” means any patents, patent rights, trademarks, service marks, registered and unregistered designs, applications for any of the foregoing, copyright, and any other similar protected rights in any country and to the extent recognised by any relevant jurisdiction as intellectual property, trade secrets, know-how and confidential information. Realsee reserves all rights not expressly granted to You.
+“Realsee” means [Beike Realsee Technology (HK) Limited, a company incorporated and validly existing under the laws of Hong Kong].
+“SDK” means the Realsee-proprietary Software Development Kits (SDK) provided hereunder, includes all development tools (including any compiler and debugger), application programming interfaces (“APIs”), libraries, binary utilities, header files, Documentation, content, data, code samples, and other materials provided to You in connection with this Agreement, whether delivered through a download, or any other media or form, and is licensed, not sold, to You by Realsee for use only under the terms of this Agreement. The terms of this Agreement will govern any updates provided by Realsee that replace and/or supplement the original SDK delivered to You, unless such update is accompanied by a separate license, in which case the terms of such license will govern.
+2. LICENSED USES AND RESTRICTIONS.
+2.1 Subject to the restrictions contained in this Section 2, Realsee grants to You during the term, a limited, non-exclusive, revocable, non-sublicensable, non-transferable license to install and use the SDK within the Territory only for the purpose of internal development.
+2.2 Restrictions. You acknowledge and agree that, You shall not, and shall ensure that Your affiliates, employees, agents, representatives, officers, representatives, and subcontractors do not (directly or indirectly):
+2.2.1 decompile, reverse engineer, disassemble or attempt to derive the source code of, those components of the SDK provided in object code form, or any part thereof;
+2.2.2 remove, alter, or obscure any copyright notice or other proprietary rights notice on any part of the SDK;
+2.2.3 sell, assign, pledge, rent, lease, lend, upload to or host on any website or server for use by any third party except You, redistribute, or sublicense the SDK (or any part thereof), or operate the SDK (or any part thereof) in the capacity of a service bureau or other hosted services provider, in whole or in part, nor may You enable others to do so;
+2.2.4 or alter, modify, customize or improve the SDK, or any part thereof;
+2.2.5 use the SDK (or any part thereof) for any illegal purpose, in any manner that is inconsistent with the terms of this Agreement, or to engage in any illegal activity;
+2.2.6 use the SDK (or any part thereof) in any manner that may damage the operation of Realsee’s products or services; or
+2.2.7 use the SDK or any information contained therein or otherwise provided by Realsee for the purpose of developing, or having developed, any product competitive with any Realsee product or service, as determined by Realsee in its sole discretion;
+2.2.8 include any portion of the SDK in Your Developer products.
+2.3 Realsee has the right to impose reasonable conditions such as a reasonable fee for use of the SDK in Integrated Product in the future.
+2.4 You may make a limited number of copies of the SDK to be used by Your employees or consultants as provided herein, and not for general business purposes, and such employees or consultants shall be subject to the obligations and restrictions in this Agreement.
+2.5 All licenses not expressly granted in this Agreement are reserved and no other licenses, immunity, or rights, express or implied, are granted by Realsee, by implication, estoppel, or otherwise.
+3. CONFIDENTIALITY.
+The SDK and all source code, Documentation, specifications, engineering details, and related information pertaining to the SDK, whether in oral, written, graphic, or electronic form, are and shall remain the confidential and proprietary information of Realsee or its licensors (collectively, the “Confidential Information”). You shall (i) disclose Confidential Information to only those directors and employees (collectively, “Affiliates”) whose duties justify their need to know such information and who have been clearly informed of their obligation to maintain the confidential, proprietary, and/or trade secret status of such Confidential Information; and (ii) use Confidential Information solely in accordance with the license granted hereunder. In any event, You and Your Affiliates shall treat Confidential Information as strictly confidential and shall use the same care to prevent disclosure of such information as You use with respect to Your own similar confidential and/or proprietary information, which shall not be less than the care a reasonable person would use under similar circumstances. All Confidential Information, and any copies thereof, shall be returned promptly to Realsee upon request. You shall ensure that Your Affiliates comply with the provisions of this Section 3, and You shall be liable for any breach of this Section 3 resulting from the act or omission of any of Your Affiliates. You shall not disclose Confidential Information to any third party, including, without limitation, any of Your subcontractors.
+4. PROPRIETARY RIGHTS.
+4.1 As between You and Realsee, Realsee and/or its licensors retain ownership of all right, title, and interest in, to, and under the SDK, including, without limitation, all patents, copyrights, trade secrets, trademarks and other intellectual property and other proprietary rights therein, and reserve all rights not expressly granted to You.
+4.2 The items contained in the SDK are the intellectual property of Realsee and its licensors and are protected by PRC copyright and patent law, international treaty provisions and applicable laws of the country in which it is being used. You agree to protect all copyright and other ownership interests of Realsee and/or its licensors in all items in the SDK supplied under this License Agreement. You agree that all copies of the items in the SDK, reproduced for any reason by You, contain the same copyright notices, and other proprietary notices as appropriate, as appear on or in the original items delivered by Realsee in the SDK. Realsee and/or its licensors retain title and ownership of the items in the SDK, the media on which it is loaded, and all subsequent copies, regardless of the form or media in or on which the original and other copies may exist. Except as stated above, this Agreement does not grant You any rights to patents, copyrights, trade secrets, trademarks or any other rights in respect to the items in the SDK.
+5. TERM AND TERMINATION.
+5.1 This Agreement is effective until terminated. Realsee has the right to terminate this Agreement immediately, without judicial intervention, if You fail to comply with any term herein. Upon any such termination You must remove all full and partial copies of the items in the SDK from Your computer and discontinue the use of the items in the SDK.
+5.2 Realsee may at any time, terminate the Agreement with You if: (A) You have breached any provision of the Agreement; or (B) Realsee is required to do so by law; or (C) Realsee decides to no longer provide the SDK or certain parts of the SDK to users in the country in which You are resident or from which You use the service, or the provision of the SDK or certain SDK services to You by Realsee is, in Realsee's sole discretion, no longer legally or commercially viable.
+5.3 When the Agreement comes to an end, all of the legal rights, obligations and liabilities that You and Realsee have benefited from, been subject to (or which have accrued over time whilst the Agreement has been in force) or which are expressed to continue indefinitely, shall be unaffected by this cessation, and the provisions of Section 3, 4, 6, 7 and 8 shall continue to apply to such rights, obligations and liabilities indefinitely.
+6. DISCLAIMER OF WARRANTY.
+YOU EXPRESSLY ACKNOWLEDGE AND AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, USE OF THE SDK (OR ANY PART THEREOF) IS AT YOUR SOLE RISK AND THAT THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH YOU. REALSEE LICENSES THE SDK TO YOU ONLY ON AN "AS-IS" BASIS. REALSEE MAKES NO REPRESENTATION WITH RESPECT TO THE ADEQUACY OF ANY ITEMS IN THE SDK, WHETHER OR NOT USED BY YOU IN THE DEVELOPMENT OF INTEGRATED PRODUCT, FOR ANY PARTICULAR PURPOSE OR WITH RESPECT TO THEIR ADEQUACY TO PRODUCE ANY PARTICULAR RESULT. REALSEE AND ITS LICENSORS SHALL NOT BE LIABLE FOR LOSS OR DAMAGE ARISING OUT OF THIS AGREEMENT OR FROM THE DISTRIBUTION OR USE OF INTEGRATED PRODUCT CONTAINING PORTIONS OF THE SDK. REALSEE AND ITS LICENSORS DISCLAIM ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED CONDITIONS OR WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT OF ANY THIRD PARTY RIGHT IN RESPECT OF THE ITEMS IN THE SDK OR ANY SERVICES RELATED TO THE SDK.
+REALSEE IS UNDER NO OBLIGATION TO PROVIDE ANY SUPPORT UNDER THIS LICENSE AGREEMENT, INCLUDING UPGRADES OR FUTURE VERSIONS OF THE SDK OR ANY PORTIONS THEREOF, TO YOU, END USER OR TO ANY OTHER PARTY.
+7. LIMITATION OF LIABILITY.
+TO THE EXTENT NOT PROHIBITED BY APPLICABLE LAW, IN NO EVENT WILL REALSEE OR ITS LICENSORS BE LIABLE FOR ANY DIRECT, INCIDENTAL, SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, LOSS OF BUSINESS, REVENUE, OR PROFITS, LOSS OF OPPORTUNITY (WHETHER DIRECT OR INDIRECT), CORRUPTION OR LOSS OF DATA, LOSS OF REPUTATION OR SAVINGS, DOWNTIME, OR DAMAGE TO, LOSS OF OR REPLACEMENT OF DATA OR TRANSACTIONS, COST OF PROCUREMENT OF SUBSTITUTE SERVICES, BUSINESS INTERRUPTION, OR ANY OTHER COMMERCIAL DAMAGES OR LOSSES, ARISING OUT OF OR RELATED TO YOUR USE OR INABILITY TO USE THE SDK (OR ANY PART THEREOF), ANY INTEGRATED PRODUCT, OR ANY THIRD PARTY SOFTWARE, APPLICATIONS, OR SERVICES IN CONJUNCTION WITH THE SDK (OR ANY PART THEREOF), HOWEVER CAUSED, REGARDLESS OF THE THEORY OF LIABILITY (CONTRACT, TORT, OR OTHERWISE) AND EVEN IF REALSEE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO EVENT WILL REALSEE’S TOTAL LIABILITY TO YOU FOR ALL DAMAGES EXCEED ONE HUNDRED DOLLARS ($100.00). THE FOREGOING LIMITATIONS WILL APPLY EVEN IF THE ABOVE STATED REMEDY FAILS OF ITS ESSENTIAL PURPOSE. THE LIMITATIONS CONTAINED IN SECTIONS 6 AND THIS SECTION 7 ARE A FUNDAMENTAL PART OF THE BASIS OF REALSEE’S BARGAIN HEREUNDER, AND REALSEE WOULD NOT ENTER INTO THIS AGREEMENT OR PROVIDE YOU WITH ACCESS TO THE SDK ABSENT SUCH LIMITATIONS.
+8. INDEMNIFICATION.
+To the extent permitted by applicable law, You agree to indemnify, defend and hold harmless Realsee, its affiliates and each of their directors, officers, employees, independent contractors, and agents (each a “Realsee Indemnified Party”) from any and all claims, losses, liabilities, damages, expenses, and costs (including without limitation attorneys’ fees and court costs) incurred by a Realsee Indemnified Party as a result of: (i) Your non-compliance with any terms of this Agreement; (ii) Your use of the SDK (or any part thereof); or (iii) Your use of any Integrated Product, including any claim that Integrated Product infringes the copyright, trademark, trade secret or other intellectual property right of a third party.
+9. ACKNOWLEDGEMENTS.
+Portions of the SDK may utilize or include third party software and other copyrighted material. Acknowledgments, licensing terms, and disclaimers for such material are contained in Documentation for the SDK or may otherwise accompany such material, and Your use of such materials governed by their respective terms. In the event of conflict between the terms of this Agreement and an applicable open source or third party agreement, the open source or third party agreement will control solely with respect to the open source software or third party software. Moreover, You shall not subject any items (including not limited to source code, object code, and any software)  included in the SDK to any open source license.
+10. NON-BLOCKING OF REALSEE DEVELOPMENT.
+You acknowledge that Realsee is currently developing or may develop technologies and products in the future that have or may have design and/or functionality similar to Integrated Product that You may develop based on Your license herein. Nothing in this Agreement shall impair, limit or curtail Realsee's right to continue with its development, maintenance and/or distribution of Realsee's technology or products.
+11. GENERAL.
+11.1 Export Control. You may not use or otherwise export or re-export the SDK (or any part thereof) except as authorized by United States law and the laws of the jurisdiction(s) in which the SDK (or any part thereof) was obtained. In particular, but without limitation, the SDK may not be exported or re-exported (i) into any U.S. embargoed countries or (ii) to anyone on the U.S. Treasury Department's list of Specially Designated Nationals or the U.S. Department of Commerce Denied Person's List or Entity List. By using the SDK (or any part thereof), You represent and warrant that You are not located in any such country or on any such list.
+11.2 Governing Law. This Agreement and the rights of the parties hereunder shall be governed by and construed in accordance with the laws of People’s Republic of China (for purpose of this Agreement, excluding Hong Kong, Taiwan, and Macau), without reference to its conflict of laws principles. Any dispute, controversy or claim arising from or in connection with this Agreement, or the breach, termination or invalidity thereof, shall be submitted to China International Economic and Trade Arbitration Commission (“CIETAC”) for arbitration in Beijing which shall be conducted in accordance with the CIETAC's arbitration rules in effect at the time of applying for arbitration. The arbitral award is final and binding upon both parties.
+11.3 Severability. If any provision of this Agreement is held by a court of competent jurisdiction to be unenforceable for any reason, the remaining provisions hereof will be unaffected and remain in full force and effect.
+11.4. Modifications. Realsee reserves the right, from time to time, with or without notice to You, to make revisions to this Agreement in our sole and absolute discretion.  The most current version of this Agreement will supersede all previous versions and shall be made available on the website where the SDK is made available, or by such other means as Realsee may determine in its discretion. Any modified versions of this Agreement hereto shall take effect from the time that it is made available. You shall be responsible for regularly checking for notice of any such modifications. You agree that Your continued use of the SDK constitutes Your agreement to the modified Agreement.
+11.5 Relationship of the Parties. This Agreement will not be construed as creating an agency, partnership, joint venture, fiduciary duty, or any other form of legal association between You and Realsee, and You will not represent to the contrary, whether expressly, by implication, appearance, or otherwise.
+11.6 Entire Agreement; Governing Language. This Agreement constitutes the entire agreement between You and Realsee with respect to the use of the SDK licensed hereunder and supersedes all prior understandings regarding such subject matter. No amendment to or modification of this Agreement will be binding unless in writing and signed by Realsee. You and Realsee hereto confirm that this Agreement and all related documents shall be drafted in English.

package/ai_guides/README.md

@@ -0,0 +1,118 @@
+# Five SDK Documentation
+
+[![npm version](https://img.shields.io/npm/v/@realsee/five.svg?style=flat-square&logo=npm&label=npm%20install%20@realsee/five)](https://www.npmjs.com/package/@realsee/five)
+
+- **Summary**: Five SDK 的文档索引与阅读指南，旨在帮助开发者与 AI 助手快速定位所需信息。
+- **Audience**: 开发者、AI 辅助编程工具。
+
+## Context for AI Agents
+
+**Five** 是贝壳如视 (Realsee) 提供的三维空间渲染 SDK。
+
+### 1. Documentation Maintenance (文档维护)
+> [!IMPORTANT]
+> Before writing or updating any documentation, YOU MUST READ [AI Documentation Guidelines](./ai-doc-guidelines.md).
+> 在书写文档时，务必遵循 [AI Documentation Guidelines](./ai-doc-guidelines.md) 中的规范。
+
+### 2. Application Development Strategy (应用开发建议)
+当协助用户编写代码或构建 Five 应用时，请遵循以下阅读与检索策略：
+
+*   **Initialization (初始化)**:
+    *   阅读 [Quick Start](./quick-start.md) 掌握最小化启动流程。
+    *   查阅 [Parameter](./features/parameter.md) 获取 `new Five(config)` 的完整配置项（如 canvas 尺寸、资源路径、纹理压缩设置）。
+*   **Data Handling (数据加载)**:
+    *   核心 VR 数据：深入理解 [Work](./features/work.md) 结构，它是 Five 渲染的基础。
+    *   外部模型：参考 [Load External Model](./features/load-external-model.md) 加载 GLTF/OBJ 等格式。
+    *   多场景/沙盘：参考 [Multi-Work (Sandbox)](./features/multi-work.md) 处理复杂场景切换。
+*   **Interaction & Logic (交互逻辑)**:
+    *   事件监听：查阅 [Event](./features/event.md) 处理用户点击 (Tap)、手势 (Gesture) 及状态变更 (StateChange)。
+    *   空间操作：使用 [Raycast](./features/raycast.md) 实现物体拾取，使用 [Screen & Space Projection](./features/screen-project.md) 实现 3D 标签挂载。
+    *   动画控制：参考 [Camera Animation](./features/camera-animation.md) 和 [Move Pano Effect](./features/move-pano-effect.md) 实现平滑运镜。
+*   **State Management (状态管理)**:
+    *   保存/恢复场景：**必须** 深刻理解 [State](./features/state.md)。它是 Five 的核心快照机制，包含 Pose、Mode 和 PanoIndex。不要尝试手动管理零散的相机参数，应统一使用 State。
+*   **Coding Standards (代码规范)**:
+    *   优先使用 TypeScript 类型提示。
+    *   确保从 `@realsee/five` 导入核心类与类型 (e.g., `import { Five, Mode, Work, State } from "@realsee/five"`).
+
+### 3. General Retrieval (通用检索)
+*   **API Signatures**: [API Reference](./api.md) 是最权威的接口定义来源，包含方法的参数与返回值。
+*   **Terminology**: 遇到不确定的术语 (e.g., Pose vs State, Observer) 时，务必查阅 [Glossary](./glossary.md)。
+*   **Core Relationships**: 理解 [Five](./features/five.md) (渲染器) 与 [Work](./features/work.md) (数据) 的分离设计。
+
+## Documentation Map
+
+### 1. Essential Reference (必读/速查)
+最常用的入口文档。
+
+*   [Intro](./intro.md): Five SDK 简介与能力概览。
+*   [Quick Start](./quick-start.md): 快速集成指南。
+*   [API Reference](./api.md): **核心 API 索引** (Five 类, State, Events, Methods)。
+*   [Glossary](./glossary.md): **术语表** (Work, Observer, Pose, etc.)。
+
+### 2. Core Concepts (核心概念)
+基础架构与生命周期管理。
+
+*   [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/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, 格式, 尺寸)。
+
+### 4. Rendering & Visuals (渲染与视觉)
+画面表现与渲染管线配置。
+
+*   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
+*   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
+*   [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): 模型裁切功能 (房屋剖面)。
+*   [3D Tile](./features/3dtile.md): 大场景 3D Tile 渲染策略。
+
+### 5. Interaction & Control (交互与控制)
+用户输入与相机控制。
+
+*   [Event](./features/event.md): 事件系统 (Tap, Gesture, StateChange)。
+*   [Gesture](./features/gesture.md): 手势交互详解。
+*   [Screen & Space Projection](./features/screen-project.md): 屏幕坐标与空间坐标转换 (标签/射线)。
+*   [Raycast](./features/raycast.md): 射线检测 (点击拾取物体)。
+*   [Camera Animation](./features/camera-animation.md): 相机动画控制 API。
+
+### 6. Advanced & Extensions (进阶与扩展)
+复杂配置与功能扩展。
+
+*   [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)
+
+## Terminology Summary
+
+*   **Work**: 包含全景图、模型、户型数据的 JSON 对象。
+*   **Observer**: 观察点，通常对应一个全景拍摄点位。
+*   **PanoIndex**: 全景点位的索引下标。
+*   **Pose**: 相机位姿 (Longitude, Latitude, Fov)。
+*   **Mode**: 浏览模式 (Panorama, Model, etc.)。
+
+---
+```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 签名的真理来源**。