@quicktvui/ai 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "QuickTVUI AI 开发规范与脚手架注入工具",
   "main": "index.js",
   "scripts": {

package/rules/.clinerules

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
@@ -50,6 +53,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -389,3 +397,9 @@ export default defineComponent({
 .detail-back-btn { width: 240px; height: 70px; background-color: #333; focus-background-color: #0066FF; border-radius: 35px; }
 .detail-back-text { width: 240px; height: 70px; font-size: 26px; color: #ffffff; }
 </style>
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.

package/rules/.cursorrules

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
@@ -51,6 +54,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -390,3 +398,9 @@ export default defineComponent({
 .detail-back-btn { width: 240px; height: 70px; background-color: #333; focus-background-color: #0066FF; border-radius: 35px; }
 .detail-back-text { width: 240px; height: 70px; font-size: 26px; color: #ffffff; }
 </style>
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.

package/rules/.github/copilot-instructions.md

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
@@ -50,6 +53,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -458,3 +466,9 @@ export default defineComponent({
 }
 </style>
 ```
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.

package/rules/.windsurfrules

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
@@ -50,6 +53,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -389,3 +397,9 @@ export default defineComponent({
 .detail-back-btn { width: 240px; height: 70px; background-color: #333; focus-background-color: #0066FF; border-radius: 35px; }
 .detail-back-text { width: 240px; height: 70px; font-size: 26px; color: #ffffff; }
 </style>
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.

package/rules/AGENTS.md

@@ -6,7 +6,10 @@
 
 **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 `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.**
+1.  **Local Docs & Examples (PRIMARY)**: `node_modules/@quicktvui/ai/rules/.docs/` directory.
+    *   **Component Docs**: Detailed definitions of components, APIs, and CSS.
+    *   **Example Code**: Vue files under `node_modules/@quicktvui/ai/rules/.docs/examples/` are verified best practices. **AI MUST refer to these examples before generating any logic.**
+
 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)
@@ -50,6 +53,11 @@ AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI
     *   CSS shorthand is **BANNED** (e.g., `margin: 10px` will crash. Use `margin-top: 10px; margin-left: 10px;`).
     *   `auto` and `%` sizing are **BANNED**. Every element must have explicit `px` width/height.
 
+### 4. Pagination & Load More Rules (CRITICAL)
+*   **`qt-tabs` (Tabs Waterfall)**: MUST use **`@onTabPageLoadData="onTabPageLoadData"`**. For page 1 use `setPageData`, for subsequent pages use `addPageData` or push to the array.
+*   **`qt-waterfall` (Single Waterfall)**: NO native `loadMore` event. Triggered via **`@onItemBind`** on the last section or by listening to **`@onScrollToBottom`** (if supported).
+*   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `(pageNo: number) => void`.
+
 ## Overview
 
 QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
@@ -478,3 +486,9 @@ export default defineComponent({
 }
 </style>
 ```
+
+
+5.  **Pagination & Load More Rules (CRITICAL)**:
+    *   **`qt-tabs` (Tabs Waterfall)**: **MUST** use **`@onTabPageLoadData="onTabPageLoadData"`**. Append data via `addPageData`.
+    *   **`qt-waterfall` (Single Waterfall)**: **NO native `loadMore` event**. Usually triggered via **`@onItemBind`** on the last section (e.g., a Loading Section) or by listening to **`@onScrollToBottom`** (if supported by parent).
+    *   **`qt-list-view` / `qt-grid-view`**: Support native `@loadMore="loadMoreFn"` with `pageNo` parameter.

package/rules/CLAUDE.md

@@ -6,7 +6,10 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.docs/` 目录中的相关内容。**
+1.  **本地文档与示例 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。
+    *   **组件文档**：提供组件、API 及 CSS 的详细定义。
+    *   **示例代码**：`node_modules/@quicktvui/ai/rules/.docs/examples/` 下的 Vue 文件是经过验证的最佳实践，**AI 在生成逻辑前必须优先参考这些示例。**
+
 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)
@@ -50,6 +53,11 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
     *   不支持任何 CSS 简写（例如 `margin: 10px` 必崩，必须写 `margin-top: 10px; margin-left: 10px;`）。
     *   不支持 `auto`，不支持 `%`。所有组件**必须显式定义宽高**（`width` / `height` 赋明确的 px 值）。
 
+### 4. 分页加载硬约束 (Pagination Rules)
+*   **`qt-tabs` (Tabs Waterfall)**：必须使用 **`@onTabPageLoadData="onTabPageLoadData"`** 回调。加载数据后，第一页使用 `setPageData`，后续页使用 `addPageData` 追加（或直接 push 到绑定数组）。
+*   **`qt-waterfall` (单瀑布流)**：原生没有 `loadMore` 事件。通常在最后一个板块的 **`@onItemBind`** 中触发下一页请求，或监听 **`@onScrollToBottom`** (若外层容器支持)。
+*   **`qt-list-view` / `qt-grid-view`**：原生支持 `@loadMore="loadMoreFn"`，方法签名：`(pageNo: number) => void`。
+
 ## 框架概述
 
 QuickTVUI 是基于 Vue 3 的 Android TV/大屏端 UI 框架。运行在快应用运行环境（Hippy-based）上，Vue 语法开发，渲染为 Android 原生视图。

package/rules/GEMINI.md

@@ -1,4 +1,4 @@
-# GEMINI.md - QuickTVUI AI Development Guide
+# GEMINI.md - QuickTVUI AI 开发指南
 
 > 放入任何 QuickTVUI 项目根目录，Gemini CLI / Gemini Code Assist 自动加载。
 
@@ -6,482 +6,65 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-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)
-
-**要求：**
-- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `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`。
-- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或 `node_modules/@quicktvui/ai/rules/.docs/` 中搜索同名组件的实际用法。
+1.  **本地文档与示例 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。
+    *   **组件文档**：提供组件、API 及 CSS 的详细定义。
+    *   **示例代码**：`node_modules/@quicktvui/ai/rules/.docs/examples/` 下的 Vue 文件是经过验证的最佳实践，**AI 在生成逻辑前必须优先参考这些示例。**
 
-## 快速创建项目 (Scaffolding)
+2.  **官方文档**：https://quicktvui.com (官网 390+ 篇详细文档)
+3.  **核心库示例**：https://github.com/quicktvui/quicktvui.git
+4.  **最佳实践应用**：https://github.com/quicktvui/hellotv.git
 
-当用户要求创建全新的 QuickTVUI 快应用项目时，AI **必须**严格遵循以下流程（切勿凭空生成目录和文件）：
-1. **获取模板**：`git clone https://github.com/quicktvui/quicktvui-template.git <项目名>`
-2. **清理 Git**：`cd <项目名> && rm -rf .git`
-3. **更新配置**：读取 `package.json`，修改 `name` 为目标项目名称，重置 `version` 为 `1.0.0`。
-4. **安装依赖**：`yarn install`（推荐）。
-5. **初始化提示**：提醒用户启动服务前，需确认是否已安装全局 CLI `npm install -g @quicktvui/cli@latest` 并执行了 `qui setup` 配置环境（详见 https://quicktvui.com/zh-CN/guide/basic/quick-start.html）。
+---
 
 ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
 
-AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报错，**必须牢记以下框架特性**：
-
-1.  **视频/音频播放架构**：
-    *   **绝对禁止**使用 HTML5 `<video>`、`<audio>` 或 `qt-web-view` 播放媒体。
-    *   **最佳实践**：必须优先使用 **`es-player-manager`**（播放管理器）配合 `es-video-player` 或 `es-audio-player`。`es-player-manager` 负责处理窗口切换（全屏/小窗）、播放列表、焦点逻辑和生命周期，单用底层 player 会导致大量底层逻辑缺失。
-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-` 开头的专属标签。
-    *   **禁用 API**：没有 `window`, `document`, `e.preventDefault()`, `alert()`。本地存储必须用 `useESLocalStorage()`，提示必须用 `useESToast()`。
-4.  **CSS 严格子集**：
-    *   不支持任何 CSS 简写（例如 `margin: 10px` 必崩，必须写 `margin-top: 10px; margin-left: 10px;`）。
-    *   不支持 `auto`，不支持 `%`。所有组件**必须显式定义宽高**（`width` / `height` 赋明确的 px 值）。
-
-## Overview
-
-QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on Hippy-based quick app runtime, rendering Vue components as native Android views. Design resolution: 1920x1080 (auto-scaled).
-
-## Example Repositories
-
-- https://github.com/quicktvui/quicktvui.git — Core library + samples
-- https://github.com/quicktvui/es-vue3.git — Cross-platform framework + samples
-- https://github.com/quicktvui/hellotv.git — Complete video app (best practice)
-- Online docs: https://quicktvui.com
-
-## CRITICAL RULES (Read First — Violations Will Cause Runtime Failures)
-
-### Function Naming (Framework matches by exact name — wrong name = never called)
-
-- Back key handler MUST be named `onBackPressed` — NOT `onBack`, `goBack`, `handleBack`
-- Key events MUST be named `onKeyDown` / `onKeyUp` — NOT `handleKeyDown`, `onKeyPress`
-- Lifecycle MUST be named `onESCreate` / `onESResume` / `onESDestroy` etc. — exact names only
-- ALL these functions MUST be defined in `setup()` AND returned in `return { }`
-
-### Every Page MUST Include (Checklist)
-
-- `onESCreate(params)` — page lifecycle entry, MUST define and return
-- `onBackPressed()` — back key handler, MUST define and return (usually calls `router.back()`)
-- At least one element with `:autofocus="true"` — otherwise no focus on page open, remote control won't work
-- Root element size: `width: 1920px; height: 1080px`
-
-### Component Names (Must be exact — no HTML tag substitutes)
-
-- Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
-- Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
-- Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
-- Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
-
-### STRICT COMPONENT NAMING (CRITICAL)
-
-**Do NOT hallucinate or use standard web tags. The following mapping is MANDATORY:**
-
-| Mandatory Tag | Forbidden (Do NOT use)             |
-| ------------- | ---------------------------------- |
-| `<qt-image>`  | `<qt-img>`, `<img>`                |
-| `<qt-text>`   | `<p>`, `<h1>`~`<h6>`, `<label>`    |
-| `<qt-button>` | `<button>`                         |
-| `<div>`       | `<section>`, `<main>`, `<article>` |
-| `<span>`      | `<p>`, `<label>`                   |
-
-### CSS Rules (This is NOT standard Web CSS)
+AI 在编写业务逻辑时，必须牢记以下框架特性，防止套用 Web 开发习惯：
 
-- **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
-- **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
-- **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
-- **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.
-- **CRITICAL: Static styles MUST be in `<style>` (kebab-case), Dynamic styles MUST be in `:style` attributes.**
-- **CRITICAL: NO `-webkit-font-smoothing: antialiased;`**. This is not supported.
-- **CRITICAL: ONLY use `div` and `span` for standard tags.** Do NOT use `p`, `h1-h6`, `section`, etc.
-- **`<style>` = kebab-case, `<template>` tag attributes = camelCase.** Do NOT mix them up.
+### 1. 视频/音频播放架构
+*   **绝对禁止**使用 HTML5 `<video>`、`<audio>` 或 `qt-web-view` 播放媒体。
+*   **必须使用 `es-player-manager`**。它负责处理窗口切换（全屏/小窗）、播放列表、焦点逻辑和生命周期，单用底层 player 会导致大量逻辑缺失。
 
-WRONG — DO NOT write camelCase in `<style>`:
+### 2. 长列表组件 (`qt-list-view`, `qt-grid-view`, `qt-waterfall`)
+*   必须设置 `listenBoundEvent="true"` 并监听 `@item-bind`。
+*   列表加载更多模版 `type` 必须是 `1002`，底线提示 `type` 必须是 `1003`。
 
-```css
-/* WRONG! camelCase in <style> will NOT work */
-.item {
-  backgroundcolor: #333;
-  fontsize: 28px;
-  focusbackgroundcolor: #0066ff;
-  borderradius: 10px;
-}
-```
+### 3. Waterfall 瀑布流硬约束 (CRITICAL)
+*   **布局属性**：自定义 Item 根节点 **必须** 包含 `layout="${layout}"` 和 `flexStyle="${style}"`，否则条目会堆叠重合。
+*   **本地图片**：瀑布流数据中的本地图片路径 **必须** 补充 `file://` 协议头（如 ``file://${icon}``）。
+*   **结构细节**：详细布局逻辑参考 `node_modules/@quicktvui/ai/rules/.docs/zh-CN/component/waterfall_structure.md`。
 
-CORRECT — `<style>` must use kebab-case for ALL properties:
+### 4. 分页加载硬约束 (Pagination Rules)
+*   **`qt-tabs` (Tabs Waterfall)**：必须使用 **`@onTabPageLoadData="onTabPageLoadData"`** 回调。加载数据后，第一页使用 `setPageData`，后续页使用 `addPageData` 追加（或直接 push 到绑定数组）。
+*   **`qt-waterfall` (单瀑布流)**：原生没有 `loadMore` 事件。可通过监听 **`@onScrollToBottom`** (若外层容器支持) 或在最后一个板块的 **`@onItemBind`** 中触发下一页请求。
+*   **`qt-list-view` / `qt-grid-view`**：原生支持 `@loadMore="loadMoreFn"`，方法签名：`(pageNo: number) => void`。
 
-```css
-/* CORRECT — kebab-case in <style>, including framework extensions */
-.item {
-  background-color: #333;
-  font-size: 28px;
-  focus-background-color: #0066ff;
-  border-radius: 10px;
-}
-```
+### 5. 零 HTML 与 零 DOM 环境
+*   **禁用标签**：`<p>`, `<img>`, `<ul>`, `<li>`, `<a>`, `<h1>`, `<button>` 全部禁用。只允许使用 `div`, `span` 或 `qt-` 开头的专属标签。
+*   **禁用 API**：没有 `window`, `document`, `e.preventDefault()`, `alert()`。本地存储用 `useESLocalStorage()`，提示用 `useESToast()`。
 
-CORRECT — `<template>` tag attributes use camelCase:
+### 6. CSS 严格子集
+*   **强制 Flex**：每个有样式的元素必须显式写 `display: flex;`。默认方向为 `flex-direction: column;`。
+*   **禁止简写**：不支持 `margin: 10px`，必须写 `margin-top: 10px;` 等。
+*   **禁止相对单位**：只允许 `px`，不支持 `%`, `auto`, `vh/vw`, `rem`。
 
-```vue
-<!-- CORRECT — camelCase on tag attributes -->
-<div :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
-```
-
-Other CSS rules:
-
-- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
-- Only use properties listed in "Supported Style Properties" section below
-- `display: flex` and `flex-direction: column` are supported and MANDATORY for all layouts.
-- Do NOT use `<style scoped>` (unreliable in native rendering, use `<style>` only)
-- Only `px` units (no %, auto, vh, vw, rem, em)
-- No CSS shorthand like `margin: 5px 10px` — must split: `margin-top: 5px; margin-right: 10px`
-
-### clipChildren / clipPadding (MANDATORY for TV — without these, focusScale gets clipped)
-
-Android clips child views outside parent bounds by default. When using `focusScale`, the enlarged item gets cut off.
-
-**Rules:**
-- Any container with `focusScale` children MUST set `:clipChildren="false"`
-- List components (`qt-list-view`, `qt-waterfall`, `qt-grid-view`) MUST set both `:clipChildren="false"` and `:clipPadding="false"`
-- Written as camelCase attributes in `<template>`
-
-```vue
-<div :clipChildren="false">
-  <div :focusable="true" :focusScale="1.1">...</div>
-</div>
-<qt-list-view :clipChildren="false" :clipPadding="false" />
-```
+---
 
 ## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
 
-当用户通过以下方式表达困惑时：
-- **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
-
-**AI 执行协议：**
-1. **脱敏诊断 (Sanitized Diagnosis)**：
-   - 提取报错日志（去除绝对路径和私密 Token）。
-   - 整理环境信息（Node 版本、package.json 中的框架版本）。
-   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
-2. **寻求授权 (Request Consent)**：
-   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
-3. **提交方式 (Submission)**：
-   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
-     - macOS: `open "URL"`
-     - Linux: `xdg-open "URL"`
-     - Windows: `start "URL"`
-   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
-
-### Import Sources
-
-- `defineComponent` from `vue` (correct) — NOT from `@vue/runtime-core`
-- Router: `useESRouter` from `@extscreen/es3-router`
-- Native modules from `@extscreen/es3-core`
+当 AI 修复同一问题超过 3 次未果，或确认代码符合规范但仍报错时，必须启动：
+1. **脱敏诊断**：提取报错日志（去除私密信息），编写最小可复现 Demo。
+2. **寻求授权**：询问用户是否允许将诊断报告上报到 GitHub 官方仓库。
+3. **自动化上报**：获得授权后，尝试使用系统命令（如 macOS `open`）自动打开 GitHub Issue 预填充页面。
 
 ---
 
-## Supported Style Properties (Complete List)
-
-Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
-
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
-
-### Layout & Size
-
-`width`, `height`, `left`, `top`, `overflow`, `direction`, `z-index`, `visibility`, `opacity`, `transform`
-
-### Background
-
-`background-color`, `background-image`, `background-position-x`, `background-position-y`, `background-size`, `linear-gradient`
-
-### Border
-
-`border-color`, `border-style`, `border-width`, `border-radius`, `border-top-color/style/width`, `border-bottom-color/style/width`, `border-left-color/style/width`, `border-right-color/style/width`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-left-radius`, `border-bottom-right-radius`
-
-### Shadow
-
-`shadow-color`, `shadow-offset`, `shadow-offset-x`, `shadow-offset-y`, `shadow-opacity`, `shadow-radius`
+## 🚀 快速创建项目 (Scaffolding)
+AI 在创建新项目时，必须遵循：`git clone` 官方模板 -> 清理 `.git` -> 修改 `package.json` -> `yarn install`。
 
-### Text
-
-`color`, `text`, `text-align`, `text-align-vertical`, `font-size`, `font-family`, `font-style`, `font-weight`, `fake-bold`, `letter-spacing`, `line-height`, `line-spacing-extra`, `line-spacing-multiplier`, `number-of-lines`, `ellipsize-mode`, `enable-scale`, `break-strategy`, `text-decoration-color/line/style`, `text-shadow-color/offset/radius`, `vertical-align`
-
-### Image
-
-`src`, `resize-mode`, `tint-color`, `tint-color-blend-mode`, `cap-insets`, `default-source`
-
-### Focus State
-
-`focus-background-color`, `focus-color`, `select-color`, `select-background-color`, `enable-focus-border`, `focus-border`, `focus-border-width`, `focus-border-color`, `focus-border-color-string`, `focus-border-style`, `focus-border-radius`, `focus-border-top-left-radius`, `focus-border-top-right-radius`, `focus-border-bottom-right-radius`, `focus-border-bottom-left-radius`, `focus-border-type`, `enable-black-border`
-
-### Input & Other
-
-`caret-color`, `placeholderTextColor`, `blur`
-
-## Focus System (Core)
-
-TV has no mouse/touch. Users navigate with remote control directional keys.
-
-```vue
-<div :focusable="true" :focusScale="1.1" :enableFocusBorder="true">
-  <qt-text text="Button" :duplicateParentState="true" />
-</div>
-<div :autofocus="true" :focusable="true"></div>
-<qt-list-view :autofocusPosition="5"></qt-list-view>
-```
-
-Focus CSS extensions:
-
-```css
-.item {
-  focus-background-color: black;
-  focus-color: white;
-  focus-border-radius: 5px;
-  focus-border-width: 3px;
-  focus-border-color: red;
-  enable-focus-border: true;
-  enable-black-border: true;
-  select-background-color: blue;
-  select-color: yellow;
-}
-```
-
-Focus direction: `:nextFocusName="{down:'listC', right:'listB'}"`, `:blockFocusDirections="['left','right']"`, `:descendantFocusability="2"` (disable subtree focus)
-
-## Router & Lifecycle
-
-```typescript
-// routes.ts
-const routes = [
-  { path: "/index", name: "index", component: index },
-  { path: "/detail", name: "detail", component: detail },
-];
-
-// main.ts
-import { createESRouter } from "@extscreen/es3-router";
-const router = createESRouter({
-  main: "index",
-  error: "error",
-  limit: 10,
-  routes,
-});
-
-// Navigation
-const router = useESRouter();
-router.push({ name: "detail", params: { id: "123" } });
-router.back();
-```
-
-Page lifecycle (only route-declared components, NO async):
-
-```
-onESCreate(params) → onESStart() → onESResume() → onESPause() → onESStop() → onESDestroy()
-```
-
-## Key Events
-
-```typescript
-// In setup(), must return these functions
-function onKeyDown(keyEvent) {
-  /* keyEvent.keyCode, keyEvent.action */
-}
-function onBackPressed() {
-  router.back();
-}
-return { onKeyDown, onBackPressed };
-```
-
-Key codes: DPAD_UP(19), DPAD_DOWN(20), DPAD_LEFT(21), DPAD_RIGHT(22), DPAD_CENTER(23), ENTER(66), BACK(4), MENU(82)
-
-## Common Components
-
-| Component      | Purpose          | Key Props                                                                   |
-| -------------- | ---------------- | --------------------------------------------------------------------------- |
-| qt-button      | Button           | text, size, focusable, focusScale, disabled, round                          |
-| qt-text        | Text             | text, fontSize, textColor, focusColor, gravity, lines, duplicateParentState |
-| qt-image       | Image            | src, focusable, enableFade, resizeMode                                      |
-| qt-input       | Input            | hintText, textColor, textSize, strokeWidth, strokeColor                     |
-| qt-waterfall   | Waterfall list   | enablePlaceholder, blockFocusDirections, autofocusPosition                  |
-| qt-list-view   | List             | autofocusPosition, blockFocusDirections                                     |
-| qt-grid-view   | Grid             | autofocusPosition                                                           |
-| qt-tabs        | Tabs             | defaultIndex, itemList                                                      |
-| qt-card        | Card             | load(), reload(), requestCardFocus()                                        |
-| qt-seek-bar    | Seek bar         | progress, range, seekBarMode                                                |
-| qt-dialog      | Dialog           | Global or route-based                                                       |
-| qt-row         | Horizontal flex  | flex-direction: row                                                         |
-| qt-column      | Vertical flex    | flex-direction: column                                                      |
-| qt-scroll-view | Scroll container | -                                                                           |
-| qt-animation   | Animation        | alpha/rotation/scale/translation                                            |
-
-## Native Modules
-
-All from `@extscreen/es3-core`:
-
-```typescript
-// Storage
-const storage = useESLocalStorage();
-await storage.putString("key", "value");
-await storage.getString("key", "default");
-
-// Toast
-const toast = useESToast();
-toast.showToast("message");
-
-// Device
-const device = useESDevice();
-device.getScreenWidth() / device.getScreenHeight();
-
-// Network
-const network = useESNetwork();
-network.isNetworkConnected();
-
-// Audio
-const audio = useESAudio();
-audio.getStreamMusicVolume();
-
-// Event Bus
-const bus = useESEventBus();
-bus.on("event", callback);
-bus.emit("event", data);
-```
-
-## Minimal Page Template
-
-```vue
-<template>
-  <div class="page">
-    <div
-      class="item"
-      :focusable="true"
-      :focusScale="1.1"
-      :enableFocusBorder="true"
-      :autofocus="true"
-      @click="onClick"
-    >
-      <qt-text text="Hello TV" :duplicateParentState="true" class="text" />
-    </div>
-  </div>
-</template>
-
-<script lang="ts">
-import { defineComponent } from "vue";
-import { useESRouter } from "@extscreen/es3-router";
-export default defineComponent({
-  setup() {
-    const router = useESRouter();
-    function onESCreate(params) {}
-    function onClick() {}
-    function onBackPressed() {
-      router.back();
-    }
-    return { onESCreate, onClick, onBackPressed };
-  },
-});
-</script>
-
-<style>
-.page {
-  width: 1920px;
-  height: 1080px;
-  background-color: #000000;
-}
-.item {
-  width: 300px;
-  height: 100px;
-  background-color: #333;
-  focus-background-color: #0066ff;
-}
-.text {
-  width: 300px;
-  height: 100px;
-  font-size: 28px;
-  color: #fff;
-}
-</style>
-```
-
-## Detail Page Template (with params + back key)
-
-```vue
-<template>
-  <div class="detail-page">
-    <qt-text class="detail-title" :text="title" gravity="center" />
-    <div
-      class="detail-back-btn"
-      :focusable="true"
-      :focusScale="1.1"
-      :enableFocusBorder="true"
-      :autofocus="true"
-      @click="onBackPressed"
-    >
-      <qt-text
-        text="Back"
-        :duplicateParentState="true"
-        class="detail-back-text"
-        gravity="center"
-      />
-    </div>
-  </div>
-</template>
-
-<script lang="ts">
-import { defineComponent, ref } from "vue";
-import { useESRouter } from "@extscreen/es3-router";
-export default defineComponent({
-  setup() {
-    const router = useESRouter();
-    const title = ref("Detail");
-    function onESCreate(params) {
-      if (params && params.title) title.value = params.title;
-    }
-    function onBackPressed() {
-      router.back();
-    }
-    return { title, onESCreate, onBackPressed };
-  },
-});
-</script>
+---
 
-<style>
-.detail-page {
-  width: 1920px;
-  height: 1080px;
-  background-color: #1a1a1a;
-  align-items: center;
-  justify-content: center;
-}
-.detail-title {
-  width: 600px;
-  height: 80px;
-  font-size: 48px;
-  color: #ffffff;
-  margin-bottom: 40px;
-}
-.detail-back-btn {
-  width: 240px;
-  height: 70px;
-  background-color: #333;
-  focus-background-color: #0066ff;
-  border-radius: 35px;
-  align-items: center;
-  justify-content: center;
-}
-.detail-back-text {
-  width: 240px;
-  height: 70px;
-  font-size: 26px;
-  color: #ffffff;
-}
-</style>
-```
+## 📚 常用组件与 API (速查)
+* **Back 键**：必须命名为 `onBackPressed`。
+* **生命周期**：必须命名为 `onESCreate`, `onESResume`, `onESDestroy` 等。
+* **焦点**：页面必须有元素设置 `:autofocus="true"`，且容器需设置 `:clipChildren="false"`。
+* **路由**：使用 `useESRouter()`。