@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 提交。

🌐 可选：全局 Skills 安装（Skill Runtime）

如果你使用支持 ~/.agents/skills/ 的 Agent（如部分本地 Agent 工具链），可以额外安装全局 skills：

npm install -g @quicktvui/ai-cli @quicktvui/ai-skills
quicktvui-ai init
quicktvui-ai doctor

默认会安装到：

• ~/.agents/skills/quicktvui

并自动维护 Gemini 全局桥接配置：

• ~/.gemini/GEMINI.md（加入 QuickTVUI skill @... 引入块）
• ~/.gemini/settings.json（补齐 context.fileName）

常用命令：

quicktvui-ai validate
quicktvui-ai update
quicktvui-ai prompt --lang zh

注意：全局 skills 不是对所有 AI 都自动生效。对仅读取项目文件的工具，仍需使用 npm install @quicktvui/ai --save-dev 注入项目内规则。

🧩 插件服务工作流

从当前版本开始，@quicktvui/ai 注入的规则也会约束 AI 如何联调电视插件服务：

1. 优先使用 quicktvui-ai-mcp 的插件工具：plugin_server_check、plugin_server_status、plugin_upload_so、plugin_upload_plugin
2. 没有 MCP 时，退回 quicktvui-ai plugin-*
3. 只有两者都不可用时，才允许 AI 手写 adb / curl

包内同时提供了可检索的插件服务文档：

• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md

规则会强制 AI 先打开 Toolkit RESTFUL_API，并要求：

• 接口返回优先于 Markdown 文档
• ABI 必须匹配 ro.product.cpu.abi
• uploadSo 调用时优先同时传 pkg 和 tag
• 默认测试标识使用 eskit.so.ffmpeg.command 与 eskit.plugin.imagequality

🏗️ 插件脚手架工作流

从当前版本开始，@quicktvui/ai 注入的规则还会约束 AI 如何创建 Android 插件工程、原生模块与原生组件：

1. 优先使用 quicktvui-ai-mcp：plugin_project_create、plugin_project_build、plugin_module_create、plugin_component_create
2. 没有 MCP 时，退回 quicktvui-ai plugin-create-project、plugin-build、plugin-create-module、plugin-create-component
3. 只有两者都不可用时，才允许 AI 手工修改脚手架

包内同步提供了可检索文档：

• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-project.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-module.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-component.md
• node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md

规则会进一步强制 AI：

• 先根据需求区分“无界面模块”还是“有界面组件”
• 以 .source/sdk/base/... 中的真实接口为准，而不是旧版 markdown 包名
• 创建工程后写入 .kyy-plugin-project.json
• 子目录工程自动补 build:android-plugin
• 组件必须补 docs/component/<kebab-name>.md
• Vue 标签必须使用 kebab-case

🤖 支持的 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 等）。
• 所有标签和组件都必须显式设置 width 和 height，不能依赖文本内容、父容器或自动撑开。
• 必须显式声明 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.