@quicktvui/ai 1.0.0

package/rules/AI_HANDOFF.md

@@ -0,0 +1,376 @@
+# QuickTVUI AI 集成 - 工作交接文档
+
+> 本文档记录了为 QuickTVUI 框架搭建 AI 辅助开发体系的完整过程，供后续 AI 接手改进。
+
+## 🔴 核心准则：权威来源与严禁幻觉 (CRITICAL)
+
+**AI 在生成任何代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有开发工作的唯一依据。**
+
+1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.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`。**
+- **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
+- **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
+- **参考优先**：遇到不确定的组件用法，必须先在上述仓库中搜索同名组件的实际用法。
+
+## 🔥 核心架构避坑指南 (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`。
+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 值）。
+
+## 快速创建项目 (Scaffolding)
+
+当用户要求创建全新的 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）。
+
+---
+
+## 一、项目背景
+
+QuickTVUI 是基于 Vue 3 的 Android TV/大屏端 UI 框架，运行在 Hippy-based 快应用运行环境上。
+
+**重要说明**：
+
+- 文档仓库：https://github.com/quicktvui/quicktvui-next.git（本仓库）
+- 文档位置：`docs/` 目录下，约 390 个 md 文档文件
+- **只使用 MD 文档作为知识来源，不使用本仓库的代码**（packages/ 目录下的源码不参考）
+
+## 二、目标
+
+让 AI 工具（Claude Code、Codex、Gemini、Cursor、Copilot、Windsurf、Cline）能够：
+
+1. 自动理解 QuickTVUI 框架的核心概念和约束
+2. 生成符合框架规范的 Vue 代码（焦点系统、CSS 子集、TV 交互）
+3. 所有配置文件自包含、可移植，拷贝到任何 QuickTVUI 应用项目即可使用
+
+## 三、已创建的文件清单
+
+### AI 指令文件（各工具自动加载）
+
+| 文件                              | 适用工具                              | 说明                                 |
+| --------------------------------- | ------------------------------------- | ------------------------------------ |
+| `CLAUDE.md`                       | Claude Code                           | 最详细版本，含完整组件 API、代码模板 |
+| `AGENTS.md`                       | OpenAI Codex / Gemini(Android Studio) | 英文精简版                           |
+| `GEMINI.md`                       | Gemini CLI / Gemini Code Assist       | 基于 AGENTS.md                       |
+| `.cursorrules`                    | Cursor IDE                            | 精简版规则                           |
+| `.github/copilot-instructions.md` | GitHub Copilot                        | 基于 AGENTS.md                       |
+| `.windsurfrules`                  | Windsurf (Codeium)                    | 基于 AGENTS.md                       |
+| `.clinerules`                     | Cline                                 | 基于 AGENTS.md                       |
+
+### Claude Code Skills（快捷指令）
+
+| 文件                                   | 触发命令            | 功能                   |
+| -------------------------------------- | ------------------- | ---------------------- |
+| `.claude/commands/create-page.md`      | `/create-page`      | 创建符合规范的 TV 页面 |
+| `.claude/commands/create-component.md` | `/create-component` | 按框架规范创建新组件   |
+| `.claude/commands/lookup-api.md`       | `/lookup-api`       | 查询组件 API           |
+| `.claude/commands/lookup-css.md`       | `/lookup-css`       | 查询 CSS 属性及限制    |
+
+## 四、知识来源
+
+所有 AI 指令文件的内容提炼自以下来源：
+
+### 本仓库 MD 文档（约 390 个文件）
+
+**文档仓库**：https://github.com/quicktvui/quicktvui-next.git
+
+**重要**：只使用此仓库 `docs/` 目录下的 MD 文档，不使用 `packages/` 目录下的源码。
+
+```
+docs/zh-CN/
+├── component/     # ~155 个组件文档（button.md, waterfall.md 等）
+├── guide/         # ~100 个开发指南
+│   ├── focus/     # 焦点系统（basic, auto-focus, request-focus, focus-method, list-auto-focus）
+│   ├── layout/    # 布局（layout, style, adapter）
+│   ├── page/      # 页面生命周期
+│   ├── key/       # 按键事件
+│   ├── router/    # 路由
+│   └── ...
+├── css/           # ~40 个 CSS 属性文档
+│   ├── layout/    # 布局属性
+│   ├── style/     # 样式属性
+│   └── color/     # 颜色格式
+├── module/        # ~30 个原生模块文档
+├── tool/          # CLI 工具文档
+└── sdk/           # SDK 集成文档
+```
+
+### 外部代码仓库（供 AI 参考实际代码风格）
+
+**重要**：这 3 个仓库用于参考实际的 Vue 代码风格和最佳实践，不是文档来源。
+
+- https://github.com/quicktvui/quicktvui.git — 核心库 + sample 示例
+- https://github.com/quicktvui/es-vue3.git — 跨平台框架 + sample 示例
+- https://github.com/quicktvui/hellotv.git — 完整视频应用（最佳实践）
+
+### 用户提供的权威 CSS 属性列表
+
+CSS 属性列表由框架作者直接提供，优先级高于文档推断。已嵌入所有 AI 指令文件中。
+
+## 五、设计决策与原因
+
+### 1. 自包含 vs 引用本地文档路径
+
+最初版本引用了 `docs/zh-CN/component/<name>.md` 等本地路径，但这些路径只存在于框架源码仓库中，不存在于用户的应用项目中。
+
+**最终方案**：所有 AI 指令文件完全自包含，将核心知识直接嵌入文件内容，不依赖任何本地文件路径。用户只需将文件拷贝到自己的项目根目录即可使用。
+
+### 2. 分层详略
+
+- `CLAUDE.md`：最详细（~400 行），包含完整组件 API 表格、代码模板、所有原生模块
+- `AGENTS.md`：英文精简版（~190 行），覆盖核心概念，作为其他工具配置的基础模板
+- `.cursorrules`：最精简（~80 行），只保留关键规则和属性列表
+
+原因：不同 AI 工具对指令文件的 token 预算不同，Claude Code 支持较长上下文，Cursor 则需要更紧凑。
+
+### 3. 英文 vs 中文
+
+- `CLAUDE.md`：中文（框架用户主要是中文开发者，Claude 中文理解能力强）
+- `AGENTS.md` 及衍生文件：英文（Codex/Gemini 等工具对英文指令效果更稳定）
+
+### 4. CSS 属性使用 camelCase
+
+框架的 CSS 属性名使用 camelCase（如 `focusBackgroundColor`），不是标准 Web 的 kebab-case（如 `focus-background-color`）。所有文件和代码模板中统一使用 camelCase。
+
+## 六、从文档中提取的核心知识点
+
+### 焦点系统（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/guide/focus/` 提取）
+
+- 基础属性：`focusable`, `focusScale`, `enableFocusBorder`, `autofocus`, `requestFocus`
+- CSS 扩展：`focusBackgroundColor`, `focusColor`, `selectColor`, `enableBlackBorder` 等
+- 方向控制：`nextFocusName`, `blockFocusDirections`, `descendantFocusability`
+- 列表焦点：`autofocusPosition`, `focusMemory`
+- 状态继承：`duplicateParentState`, `showOnState`
+
+### CSS 约束（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/css/` + 用户提供列表）
+
+- **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.
+- 只支持 px 单位（不支持 %、auto、vh/vw/rem/em）
+- 不支持 CSS 简写（如 `margin: 5px 10px` 必须拆写）
+- 不支持 CSS 变量、`!important`
+- 默认 flexbox 布局，默认 `flex-direction: column`
+- 所有元素必须显式指定 width 和 height
+- 支持的属性：布局、背景、边框、阴影、文字、图片、焦点态、输入（共 80+ 个属性）
+
+### 页面生命周期（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/guide/page/` 提取）
+
+```
+onESCreate(params) → onESStart() → onESResume() → onESPause() → onESStop() → onESDestroy()
+```
+
+- 只有在 routes.ts 中声明的组件才是 Page，子组件不能监听生命周期
+- 生命周期方法不能用 `async`
+
+### 路由系统（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/guide/router/` 提取）
+
+- `createESRouter({ main, error, limit, routes })`
+- `useESRouter()` → `router.push()`, `router.back()`
+- 路由参数通过 `onESCreate(params)` 接收
+
+### 按键事件（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/guide/key/` 提取）
+
+- 在 `setup()` 中定义 `onKeyDown`, `onKeyUp`, `onBackPressed`，必须在 `return` 中导出
+- 常用键值：DPAD_UP(19), DOWN(20), LEFT(21), RIGHT(22), CENTER(23), ENTER(66), BACK(4)
+
+### 组件 API（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/component/` 提取）
+
+已提取详细 API 的组件：
+
+- `qt-button`：text, size, focusable, focusScale, disabled, round, icon, gradientBackground
+- `qt-text`：text, fontSize, textColor, focusColor, gravity, lines, duplicateParentState
+- `qt-image`：src, focusable, enableFade, fadeDuration, resizeMode
+- `qt-input`：hintText, textColor, textSize, strokeWidth, strokeColor
+- `qt-waterfall`：enablePlaceholder, blockFocusDirections, autofocusPosition, 事件（onScroll, onItemClick, onItemFocused）
+
+其他组件（已列出但未详细展开）：qt-card, qt-tabs, qt-seek-bar, qt-dialog, qt-list-view, qt-grid-view, qt-scroll-view, qt-row, qt-column, qt-animation 等
+
+### 原生模块（从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/module/` 提取）
+
+- `useESLocalStorage()`：putString/getString, putInt/getInt, putBoolean/getBoolean
+- `useESToast()`：showToast, showLongToast, showShortToast
+- `useESDevice()`：getScreenWidth, getScreenHeight, getIPAddress
+- `useESNetwork()`：isNetworkConnected, getActiveNetworkInfo, addListener
+- `useESAudio()`：getStreamMusicVolume, setStreamVolume, setStreamMute
+- `useESEventBus()`：on, once, emit, off
+- `useESBrightness()`：getScreenBrightness, changeScreenBrightness
+
+## 七、已知缺陷与限制
+
+### 1. 组件 API 覆盖不完整
+
+当前 `CLAUDE.md` 只详细展开了 5 个组件的 API（qt-button, qt-text, qt-image, qt-input, qt-waterfall），但框架实际有 100+ 个组件。其他组件只在表格中列出了名称和用途，没有详细的属性、事件、方法说明。
+
+**影响**：AI 在使用 qt-card, qt-tabs, qt-seek-bar 等组件时可能生成不准确的代码。
+
+**改进方向**：逐步补充更多组件的详细 API（从 `docs/zh-CN/component/` 中提取）。
+
+### 2. CSS 属性列表未与文档交叉验证
+
+当前使用的 CSS 属性列表是用户直接提供的，未与 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/css/` 中的所有文档文件逐一对照验证。可能存在：
+
+- 文档中有说明但列表中遗漏的属性
+- 列表中有但文档未详细说明的属性
+- 属性的取值范围、默认值等细节信息缺失
+
+**改进方向**：编写脚本自动提取所有 CSS 文档中的属性定义，与用户列表合并校验。
+
+### 3. 代码模板较少
+
+当前只有 1 个完整的页面模板（最小 TV 页面），缺少：
+
+- 列表页模板（qt-waterfall / qt-list-view）
+- 详情页模板（带返回键处理）
+- 弹窗模板（qt-dialog）
+- 表单页模板（qt-input + 焦点管理）
+- 视频播放页模板
+
+**改进方向**：从 https://github.com/quicktvui/hellotv.git 仓库中提取典型页面作为模板。
+
+### 4. Skills 功能有限
+
+当前 4 个 Skills 都是查询型或脚手架型，缺少：
+
+- 调试辅助（如 `/debug-focus` 生成焦点可视化代码）
+- 代码检查（如 `/check-css` 检查是否使用了不支持的属性）
+- 迁移辅助（如 `/migrate-from-web` 将标准 Vue 代码转换为 QuickTVUI 代码）
+
+### 5. 无动态文档查询能力
+
+所有知识都静态嵌入在 AI 指令文件中，当框架文档更新时，需要手动重新提取和更新。
+
+**改进方向**：构建 MCP Server，让 AI 能动态查询最新文档内容。
+
+## 八、后续改进建议
+
+### 短期改进（1-2 周）
+
+1. **补充高频组件 API**
+   - 优先补充：qt-card, qt-tabs, qt-list-view, qt-grid-view, qt-seek-bar, qt-dialog
+   - 从 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/component/` 中提取完整的属性表、事件列表、方法说明
+   - 更新到 `CLAUDE.md` 和 `AGENTS.md`
+
+2. **添加更多代码模板**
+   - 列表页模板（包含 qt-waterfall 的完整用法）
+   - 详情页模板（包含参数接收、返回键处理）
+   - 弹窗模板（全局弹窗 vs 路由弹窗）
+   - 嵌入到 Skills 或 CLAUDE.md 的"代码模板"章节
+
+3. **创建实用 Skills**
+   - `/debug-focus`：生成焦点调试代码（显示当前焦点元素、焦点路径）
+   - `/check-css`：检查代码中是否使用了不支持的 CSS 属性
+   - `/fix-focus`：自动为页面添加基础焦点配置
+
+### 中期改进（1-2 个月）
+
+4. **CSS 属性完整性验证**
+   - 编写脚本遍历 https://github.com/quicktvui/quicktvui-next.git `docs/zh-CN/css/` 所有文档
+   - 提取每个属性的：支持的值、默认值、示例、注意事项
+   - 与用户提供的列表交叉验证，生成完整的 CSS 属性字典
+   - 考虑将详细的 CSS 字典作为独立文件（如 `CSS_REFERENCE.md`）
+
+5. **构建 MCP Server**
+   - 实现 `search_component(name)` 工具：动态查询组件文档
+   - 实现 `search_css(property)` 工具：动态查询 CSS 属性
+   - 实现 `search_guide(topic)` 工具：动态查询开发指南
+   - 让 AI 能实时获取最新文档，而不依赖静态嵌入的知识
+
+6. **自动化同步机制**
+   - 监听 `docs/zh-CN/` 目录变化
+   - 文档更新时自动重新提取知识，更新 AI 指令文件
+   - 生成变更日志，通知用户哪些知识点发生了变化
+
+### 长期改进（3+ 个月）
+
+7. **多语言支持**
+   - 当前只有中文（CLAUDE.md）和英文（AGENTS.md）
+   - 考虑添加日文、韩文版本（如果框架有国际化需求）
+
+8. **AI 代码审查 Skill**
+   - `/review-code`：检查代码是否符合框架最佳实践
+   - 检查项：焦点配置完整性、CSS 属性合规性、生命周期使用正确性、按键事件处理
+
+9. **交互式学习模式**
+   - `/learn-focus`：交互式教程，逐步引导用户理解焦点系统
+   - `/learn-css`：交互式 CSS 属性查询和示例生成
+
+10. **与 hellotv 项目深度集成**
+    - 从 https://github.com/quicktvui/hellotv.git 提取真实业务场景的代码片段
+    - 作为"最佳实践"嵌入 AI 指令文件
+    - 让 AI 能参考真实项目的代码风格和架构模式
+
+## 九、使用方法
+
+### 对于框架用户（应用开发者）
+
+1. 将以下文件拷贝到你的 QuickTVUI 应用项目根目录：
+   - `CLAUDE.md`（如果使用 Claude Code）
+   - `AGENTS.md`（如果使用 OpenAI Codex）
+   - `GEMINI.md`（如果使用 Gemini）
+   - `.cursorrules`（如果使用 Cursor）
+   - `.github/copilot-instructions.md`（如果使用 GitHub Copilot）
+   - `.windsurfrules`（如果使用 Windsurf）
+   - `.clinerules`（如果使用 Cline）
+   - `.claude/commands/`（如果使用 Claude Code，拷贝整个目录）
+
+2. AI 工具会自动加载这些文件，理解 QuickTVUI 框架规范
+
+3. 开始编码时，AI 会生成符合框架约束的代码（焦点系统、CSS 子集、TV 交互）
+
+### 对于后续 AI 接手者
+
+1. 阅读本文档（`AI_HANDOFF.md`）了解整体架构和设计决策
+
+2. 查看"已知缺陷与限制"章节，了解当前的不足
+
+3. 根据"后续改进建议"选择优先级高的任务开始改进
+
+4. 改进时的关键原则：
+   - 保持所有文件自包含、可移植
+   - 从 `docs/zh-CN/` 提取知识，不要编造
+   - 使用用户提供的权威 CSS 属性列表
+   - 参考 3 个外部代码仓库的实际代码风格
+   - 测试生成的代码模板是否能直接运行
+
+## 十、参考资源
+
+- 在线文档：https://quicktvui.com
+- **文档仓库**：https://github.com/quicktvui/quicktvui-next.git（`docs/` 目录，约 390 个 md 文件）
+- **代码参考仓库**：
+  - 核心库：https://github.com/quicktvui/quicktvui.git
+  - 跨平台框架：https://github.com/quicktvui/es-vue3.git
+  - 完整应用示例：https://github.com/quicktvui/hellotv.git
+
+---
+
+**文档版本**：v1.0
+**创建日期**：2026-02-27
+**最后更新**：2026-02-27