npm package: @quicktvui/ai
Description: QuickTVUI AI 开发规范与脚手架注入工具
Author: QuickTVUI
Latest version: 1.1.22

# @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 项目根目录下运行：

```bash
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：

```bash
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`）

常用命令：

```bash
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.