@quicktvui/ai 1.0.3 → 1.0.5

package/rules/AGENTS.md

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com (390+ docs)
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git (Core library + samples)
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git (Complete video app)
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -38,6 +38,10 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
 2.  **List Components (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**:
     *   You MUST set `listenBoundEvent="true"` and listen to `@item-bind`.
     *   The "Loading More" template `type` **MUST** be `1002`. The "End of List" template `type` **MUST** be `1003`.
+    *   **Waterfall Critical Rules (qt-waterfall)**:
+        *   Custom item root nodes **MUST** include `layout="${layout}"` and `flexStyle="${style}"` to avoid stacking/overlapping.
+        *   Local image paths in waterfall data **MUST** use the `file://` protocol (e.g., `file://${icon}`).
+        *   Refer to `node_modules/@quicktvui/ai/rules/.docs/zh-CN/component/waterfall_structure.md` for full layout logic.
 3.  **Zero HTML & Zero DOM**:
     *   **This is NOT a browser.** It compiles to Hippy Native Android Views.
     *   **Banned Tags**: Standard HTML tags (`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>`) will **CRASH** the app. Use only `div`, `span`, or `qt-*` tags.
@@ -158,7 +162,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：当用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议 (Execution Protocol)：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：

package/rules/AI_HANDOFF.md

@@ -6,14 +6,14 @@
 
 **AI 在生成任何代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有开发工作的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.docs/` 目录中的相关内容。**
 2.  **官方文档**：https://quicktvui.com (包含约 390 个详细文档)
 3.  **核心库示例**：https://github.com/quicktvui/quicktvui.git (Core library + samples)
 4.  **跨平台框架示例**：https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
 5.  **最佳实践应用**：https://github.com/quicktvui/hellotv.git (Complete video app)
 
 **要求：**
-- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `node_modules/@quicktvui/ai/rules/.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
 - **非浏览器与无 HTML 环境**：**本框架绝对不支持标准 HTML 标签（如 `p`, `img`, `a`, `ul`, `li`, `h1` 等），严禁在模板中使用！绝对不支持 `window`、`document` (DOM) 对象或任何 DOM 操作 API。必须使用框架专属标签（如 `qt-text`, `qt-image`）和 Vue `ref`。**
 - **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
 - **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
@@ -64,7 +64,7 @@ QuickTVUI 是基于 Vue 3 的 Android TV/大屏端 UI 框架，运行在 Hippy-b
 
 1. 自动理解 QuickTVUI 框架的核心概念和约束
 2. 生成符合框架规范的 Vue 代码（焦点系统、CSS 子集、TV 交互）
-3. 所有配置文件自包含、可移植，拷贝到任何 QuickTVUI 应用项目即可使用
+3. 所有配置文件引用 `@quicktvui/ai` 包内的文档库，安装包后即可使用。
 
 ## 三、已创建的文件清单
 
@@ -134,9 +134,9 @@ CSS 属性列表由框架作者直接提供，优先级高于文档推断。已
 
 ### 1. 自包含 vs 引用本地文档路径
 
-最初版本引用了 `docs/zh-CN/component/<name>.md` 等本地路径，但这些路径只存在于框架源码仓库中，不存在于用户的应用项目中。
+最初版本引用了 `docs/zh-CN/component/<name>.md` 等本地路径，但这些路径只存在于框架源码仓库中，不存 在于用户的应用项目中。
 
-**最终方案**：所有 AI 指令文件完全自包含，将核心知识直接嵌入文件内容，不依赖任何本地文件路径。用户只需将文件拷贝到自己的项目根目录即可使用。
+**最终方案**：AI 指令文件引用 `node_modules/@quicktvui/ai/rules/.docs/` 目录。用户通过安装 `@quicktvui/ai` 包即可获得这些文档。这样既保持了知识的实时性，又避免了在用户项目根目录下生成大量冗余文件。
 
 ### 2. 分层详略
 
@@ -354,7 +354,7 @@ onESCreate(params) → onESStart() → onESResume() → onESPause() → onESStop
 3. 根据"后续改进建议"选择优先级高的任务开始改进
 
 4. 改进时的关键原则：
-   - 保持所有文件自包含、可移植
+   - 保持配置文件引用的路径正确、可移植
    - 从 `docs/zh-CN/` 提取知识，不要编造
    - 使用用户提供的权威 CSS 属性列表
    - 参考 3 个外部代码仓库的实际代码风格

package/rules/CLAUDE.md

@@ -6,18 +6,18 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.docs/` 目录中的相关内容。**
 2.  **官方文档**：https://quicktvui.com (官网 390+ 篇详细文档)
 3.  **核心库示例**：https://github.com/quicktvui/quicktvui.git (Core library + samples)
 4.  **跨平台框架示例**：https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
 5.  **最佳实践应用**：https://github.com/quicktvui/hellotv.git (Complete video app)
 
 **要求：**
-- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `node_modules/@quicktvui/ai/rules/.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
 - **非浏览器与无 HTML 环境**：**本框架绝对不支持标准 HTML 标签（如 `p`, `img`, `a`, `ul`, `li`, `h1` 等），严禁在模板中使用！绝对不支持 `window`、`document` (DOM) 对象或任何 DOM 操作 API。必须使用框架专属标签（如 `qt-text`, `qt-image`）和 Vue `ref`。**
 - **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
 - **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
-- **参考优先**：遇到不确定的组件用法，必须先在上述仓库中搜索同名组件的实际用法。
+- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或 `node_modules/@quicktvui/ai/rules/.docs/` 中搜索同名组件的实际用法。
 
 ## 快速创建项目 (Scaffolding)
 
@@ -38,6 +38,10 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 2.  **长列表组件 (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**：
     *   必须设置 `listenBoundEvent="true"` 并监听 `@item-bind`。
     *   列表的加载更多模版 `type` **必须**是 `1002`，底线提示 `type` **必须**是 `1003`。
+    *   **Waterfall 瀑布流硬约束**：
+        *   自定义 Item 根节点 **必须** 包含 `layout="${layout}"` 和 `flexStyle="${style}"`，否则条目会堆叠重合。
+        *   瀑布流数据中的本地图片路径 **必须** 补充 `file://` 协议头（如 ``file://${icon}``）。
+        *   详细布局逻辑参考：`node_modules/@quicktvui/ai/rules/.docs/zh-CN/component/waterfall_structure.md`。
 3.  **零 HTML 与 零 DOM 环境**：
     *   **这不是浏览器！** 底层是 Hippy 渲染的 Android Native View。
     *   **禁用标签**：`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>` 等标准 HTML 标签**全部禁用**。只允许使用 `div`, `span` 或 `qt-` 开头的专属标签。
@@ -182,7 +186,7 @@ Android 默认裁切超出父容器边界的子元素。TV 端使用 `focusScale
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：

package/rules/GEMINI.md

@@ -6,18 +6,18 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.docs/` 目录中的相关内容。**
 2.  **官方文档**：https://quicktvui.com (官网 390+ 篇详细文档)
 3.  **核心库示例**：https://github.com/quicktvui/quicktvui.git (Core library + samples)
 4.  **跨平台框架示例**：https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
 5.  **最佳实践应用**：https://github.com/quicktvui/hellotv.git (Complete video app)
 
 **要求：**
-- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
-- **非浏览器与无 HTML 环境**：**本框架绝对不支持标准 HTML 标签（如 `p`, `img`, `a`, `ul`, `li`, `h1` 等），严禁在模板中使用！绝对不支持 `window`、`document` (DOM) 对象或任何 DOM 操作 API。必须使用框架专属标签（如 `qt-text`, `qt-image`）和 Vue `ref`。**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `node_modules/@quicktvui/ai/rules/.docs/` 目录中检索相关文档，验证组件是否支持该功能。切勿想当然！**例如：`qt-web-view` 绝对不支持视频播放，视频播放必须使用框架提供的专用视频组件和管理器（如 `es-video-player` 和 `es-player-manager`）。**
+- **非浏览器与无 HTML 环境**：**本框架绝对不支持标准 HTML 标签（如 `p`, `img`, `a`, `ul`, `li`, `h1` 等），严禁在模板中使用！绝对不支持 `window`、`document` (DOM) 对象或任何 DOM 操作 API。必须使用框架专属标签（如 `qt-text`, `qt-image`） and Vue `ref`。**
 - **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
 - **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
-- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或本地 `.docs` 中搜索同名组件的实际用法。
+- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或 `node_modules/@quicktvui/ai/rules/.docs/` 中搜索同名组件的实际用法。
 
 ## 快速创建项目 (Scaffolding)
 
@@ -38,6 +38,10 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 2.  **长列表组件 (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)**：
     *   必须设置 `listenBoundEvent="true"` 并监听 `@item-bind`。
     *   列表的加载更多模版 `type` **必须**是 `1002`，底线提示 `type` **必须**是 `1003`。
+    *   **Waterfall 瀑布流硬约束**：
+        *   自定义 Item 根节点 **必须** 包含 `layout="${layout}"` 和 `flexStyle="${style}"`，否则条目会堆叠重合。
+        *   瀑布流数据中的本地图片路径 **必须** 补充 `file://` 协议头（如 ``file://${icon}``）。
+        *   详细布局逻辑参考：`node_modules/@quicktvui/ai/rules/.docs/zh-CN/component/waterfall_structure.md`。
 3.  **零 HTML 与 零 DOM 环境**：
     *   **这不是浏览器！** 底层是 Hippy 渲染的 Android Native View。
     *   **禁用标签**：`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>` 等标准 HTML 标签**全部禁用**。只允许使用 `div`, `span` 或 `qt-` 开头的专属标签。
@@ -163,7 +167,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：