@quicktvui/ai

让 AI 助你丝滑开发 QuickTVUI，彻底告别“Web 习惯”导致的运行报错。

@quicktvui/ai 是 QuickTVUI 官方提供的 AI 辅助开发规范包。它通过向你的项目中注入经过深度调优的 AI 指令（Rules）和本地知识库，让 Cursor、Windsurf、Copilot、Cline 等 AI 助手瞬间化身为“QuickTVUI 资深专家”。

🚀 为什么需要它？

QuickTVUI 运行在 TV 端原生环境（Hippy-based），虽然使用 Vue 语法，但它不是浏览器。开发者在使用 AI 辅助编程时，AI 极其容易带入传统的 Web 开发习惯，导致生成无法运行的代码：

• ❌ 误用 HTML 标签：生成了 <p>, <img>, <a> 等标签（QuickTVUI 必须使用 qt-text, qt-image）。
• ❌ 误用 DOM API：使用了 window, document, alert()（原生环境不存在这些对象）。
• ❌ 无效的 CSS：使用了简写（margin: 10px）或 auto 尺寸（QuickTVUI 严格要求拆写且必须是 px）。
• ❌ 错误的播放器架构：直接使用 <video> 标签（必须使用 es-player-manager）。

安装 @quicktvui/ai 后，这些问题将不复存在。AI 将严格遵守框架规范，生成 100% 可运行的 TV 端代码。

📦 安装方式

在你的 QuickTVUI 项目根目录下运行：

npm install @quicktvui/ai --save-dev
# 或者
yarn add @quicktvui/ai --dev

安装完成后，脚本会自动执行以下操作：

1. 注入配置文件：在根目录生成 .cursorrules, .clinerules, GEMINI.md, CLAUDE.md 等。
2. 配置 Copilot：在 .github/ 下注入 Copilot 专用指令。
3. 关联知识库：让 AI 能够检索 node_modules 中内置的组件详细文档。
4. 自动忽略：自动更新 .gitignore，确保这些辅助配置文件不会污染你的 Git 提交。

🤖 支持的 AI 工具与配置

本包一次性适配了市面上主流的 AI 编程助手，安装后会自动在项目根目录生成对应的配置文件：

| AI 工具 | 核心配置文件 | 配置方式 | | :--- | :--- | :--- | | Cursor | .cursorrules | 自动加载，无需额外设置 | | Windsurf | .windsurfrules | 自动加载，级联项目上下文 | | Cline (Roo-Code) | .clinerules | 自动加载，作为 Agent 的全局指令 | | GitHub Copilot | .github/copilot-instructions.md | 自动生效 (需较新版本的 Copilot 插件) | | Gemini CLI | GEMINI.md | 自动被 Gemini 及其相关工具链引用 | | Claude Code | CLAUDE.md / .claude/ | 深度适配，提供 /create-page 等快捷指令 |

🌟 强力推荐：最佳模型选择

为了获得最精准的 QuickTVUI 代码生成效果，我们强烈建议开发者配合以下最新一代 AI 模型使用：

1. Claude 3.5 Sonnet (推荐)：目前对 QuickTVUI 复杂焦点逻辑和样式约束理解最深刻的模型，逻辑严密，极少幻觉。
2. GitHub Copilot (基于 Codex/GPT-4o)：响应速度快，适合日常组件编写和代码补全。
3. Gemini 1.5 Pro / Flash：拥有超长上下文窗口，能够一次性理解项目中的多个页面关系，适合进行大型功能重构。

提示：在使用这些 AI 时，请确保已启用“读取项目文件”或“代码库索引”功能，以便 AI 能够自动发现并遵循本项目注入的 .docs 文档。

✨ 它强制 AI 遵守的核心规范

安装后，AI 将掌握以下“生存法则”：

1. 零 HTML 与 零 DOM

• 绝对禁止使用 p, img, ul, li, h1, button 等标签。
• 绝对禁止使用 window, document, e.preventDefault()。
• 必须使用 qt-text, qt-image, qt-view 等原生对应组件。

2. 严格的 CSS 子集

• 必须使用 px 单位，严禁使用 %, auto, rem, vh 等。
• 严禁 CSS 属性简写（如 margin 必须拆分为 margin-top 等）。
• 必须显式声明 display: flex 且默认方向为 column。

3. TV 特有的焦点系统

• 自动为交互元素添加 :focusable="true"。
• 自动处理 focusScale 带来的 clipChildren="false" 适配问题。

4. 正确的命名协议

• 返回键处理函数必须叫 onBackPressed。
• 生命周期必须叫 onESCreate, onESResume 等。

5. AI 哨兵：自动化问题上报

当 AI 发现代码符合规范但仍运行报错，或者同一问题修复 3 次未果时，它会启动问题上报机制：

• 脱敏诊断：自动整理报错日志、环境信息并编写最小可复现 Demo。
• 一键上报：在获得你授权后，AI 会自动尝试打开浏览器或生成 GitHub Issue 链接，助你快速反馈给官方。

🔍 验证注入是否成功

安装完成后，检查项目根目录，如果出现以下文件，说明注入成功：

• .cursorrules
• .clinerules
• .windsurfrules
• GEMINI.md
• CLAUDE.md
• .quicktvui-ai-backup/ (如有旧配置，会自动备份在此)

🛠️ 进阶使用：本地知识库

本包在 node_modules/@quicktvui/ai/rules/.docs/ 下内置了约 400 篇 QuickTVUI 核心组件及 API 文档。你的 AI 助手现在具备了“离线查阅文档”的能力，生成代码前它会先检索本地文档，确保参数和用法 100% 准确。

📄 开源协议

MIT License.