@quicktvui/ai 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# @quicktvui/ai
+
+QuickTVUI 官方提供的 AI 辅助开发规范包。
+安装后，会自动将 QuickTVUI 的严格开发规范、架构避坑指南（不支持 HTML、组件用法等）、以及本地文档库注入到你的项目中。
+
+## 它可以做什么？
+
+安装本包后，它会自动在你的项目根目录下生成并配置：
+- `.cursorrules` (供 Cursor 使用)
+- `.windsurfrules` (供 Windsurf 使用)
+- `.clinerules` (供 Cline/Roo-Code 使用)
+- `.github/copilot-instructions.md` (供 GitHub Copilot 使用)
+- `GEMINI.md` / `CLAUDE.md` / `AGENTS.md` (供其他模型使用)
+- `.docs/` (本地轻量级 QuickTVUI 知识库)
+
+这些规则会强制 AI：
+1. **停止捏造标签**（如禁止使用 `qt-web-view`，强制使用 `qt-web`）。
+2. **遵守非浏览器环境**（禁止使用 `window`, `document` 和任何标准 HTML 标签，如 `p`, `div` 以外的标签）。
+3. **正确的播放器架构**（强制使用 `es-player-manager`）。
+4. **严格的 CSS 子集**（禁止简写，禁止 auto 等）。
+
+## 安装方式
+
+在你的 QuickTVUI 项目根目录下运行：
+
+```bash
+npm install @quicktvui/ai --save-dev
+# 或者
+yarn add @quicktvui/ai --dev
+```
+
+> 安装完成后，脚本会自动将相关规范和文档拷贝到你的项目根目录。如果你的项目使用 Git，它还会自动执行 `git add`。
+
+## 验证
+
+安装完毕后，请检查你的项目根目录是否多出了 `.cursorrules` 等文件以及 `.docs` 目录。如果有，说明注入成功，尽情享受不踩坑的 AI 编程体验吧！

package/index.js

@@ -0,0 +1,2 @@
+// QuickTVUI AI Rules Package
+module.exports = {};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@quicktvui/ai",
+  "version": "1.0.0",
+  "description": "QuickTVUI AI 开发规范与脚手架注入工具",
+  "main": "index.js",
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "keywords": [
+    "quicktvui",
+    "ai",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "claude"
+  ],
+  "author": "QuickTVUI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quicktvui/quicktvui-template.git"
+  }
+}

package/postinstall.js

@@ -0,0 +1,61 @@
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+// 确定用户的项目根目录（执行 npm install 的地方）
+const projectRoot = process.env.INIT_CWD || path.resolve("../../..");
+
+if (!projectRoot || !fs.existsSync(projectRoot)) {
+  console.log("⚠️ [@quicktvui/ai] 无法确定项目根目录，跳过自动注入。");
+  process.exit(0);
+}
+
+// 避免在包自身的开发环境中循环复制
+if (projectRoot === __dirname) {
+  process.exit(0);
+}
+
+console.log("\n🚀 [@quicktvui/ai] 开始为您注入 QuickTVUI 专属 AI 规范...");
+console.log(`📂 目标目录: ${projectRoot}`);
+
+const rulesDir = path.join(__dirname, "rules");
+
+function copyDirectorySync(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectorySync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+try {
+  // 1. 拷贝规则
+  copyDirectorySync(rulesDir, projectRoot);
+  console.log("🎉 [@quicktvui/ai] AI 规范注入成功！");
+
+  // 2. 尝试 Git Add
+  const gitDir = path.join(projectRoot, ".git");
+  if (fs.existsSync(gitDir)) {
+    console.log("📦 正在将配置文件添加到 Git 暂存区...");
+    const rootItems = fs.readdirSync(rulesDir);
+    rootItems.forEach((item) => {
+      try {
+        execSync(`git add "${item}"`, { cwd: projectRoot, stdio: "ignore" });
+      } catch (e) {}
+    });
+    console.log("✅ 自动 git add 完成。");
+  } else {
+    console.log("ℹ️ 未检测到 Git 仓库，跳过自动 git add。");
+  }
+} catch (err) {
+  console.error(`❌ 注入失败: ${err.message}`);
+}
+console.log(
+  "\n🤖 您的项目现已全面兼容 Cursor, Windsurf, Cline 等 AI 助手！开发愉快！\n",
+);

package/rules/.claude/commands/create-component.md

@@ -0,0 +1,39 @@
+# 创建 QuickTVUI 组件
+
+按照框架规范创建一个新的 QuickTVUI 组件。
+
+## 文件结构
+
+```
+packages/components/<name>/
+├── index.ts              # 导出入口，withInstall 包装
+├── src/
+│   ├── <name>.vue        # Vue 组件（defineComponent + Composition API）
+│   ├── <name>-props.ts   # Props 定义（buildProps）
+│   ├── <name>-instance.ts # 实例类型导出
+│   ├── <name>-types.ts   # 类型定义
+│   ├── <name>-api.ts     # API 工厂函数（复杂组件可选）
+│   └── <name>-element.ts # 原生组件注册（可选）
+└── style/
+    ├── index.ts           # SCSS 引入
+    └── css.ts             # 编译后 CSS 引入
+```
+
+## 注册流程
+
+1. `packages/components/index.ts` — 导出组件
+2. `packages/quicktvui/component.ts` — 注册为插件
+3. `packages/quicktvui/element.ts` — 注册原生组件（如有）
+4. `typings/component.ts` — 导出类型
+5. `global.d.ts` — 全局类型声明
+
+## 样式规范
+
+- SCSS + BEM 命名（block\_\_element--modifier）
+- 文件：`packages/theme-chalk/src/<name>.scss`
+- 注册：`packages/theme-chalk/src/index.scss` 中 `@use './<name>'`
+
+## 参考
+
+- https://quicktvui.com — 在线文档
+- 项目根目录 CONTRIBUTING_COMPONENT.md — 完整流程

package/rules/.claude/commands/create-page.md

@@ -0,0 +1,44 @@
+# 创建 TV 页面
+
+根据用户需求，创建一个 QuickTVUI TV 页面。
+
+## 代码规范
+
+- Vue 3 Composition API + TypeScript
+- 设计分辨率 1920x1080
+- 所有可交互元素必须设置 `:focusable="true"`
+- 必须有一个元素设置 `:autofocus="true"` 或 `:requestFocus="true"`
+- 焦点态样式用 `focusScale`、`enableFocusBorder` 或 CSS focus-\* 属性
+- 子元素跟随焦点状态：`:duplicateParentState="true"`
+- 文字用 `<span>` 或 `<qt-text>` 包裹
+- 所有元素显式指定 width/height（px）
+- 不用写 `display: flex`，默认就是 flex，默认 flex-direction: column
+- 不支持 %、auto、vh/vw、grid、动画、阴影、CSS 简写属性
+- 横向列表用 `<ul :horizontal="true">`
+- 设置 border 必须同时设置 border-color
+
+## 页面结构
+
+```typescript
+import { defineComponent } from "vue";
+import { useESRouter } from "@extscreen/es3-router";
+
+export default defineComponent({
+  setup() {
+    const router = useESRouter();
+    function onESCreate(params) {
+      /* 初始化 */
+    }
+    function onBackPressed() {
+      router.back();
+    }
+    return { onESCreate, onBackPressed };
+  },
+});
+```
+
+## 参考代码
+
+- https://github.com/quicktvui/hellotv.git — 完整项目参考
+- https://github.com/quicktvui/quicktvui.git — 组件示例
+- https://quicktvui.com — 在线文档

package/rules/.claude/commands/create-project.md

@@ -0,0 +1,25 @@
+# 创建 QuickTVUI 项目
+
+根据用户提供的项目名称，创建一个全新的 QuickTVUI 快应用项目。
+
+## 创建步骤 (AI 必须严格执行以下步骤)
+
+1. **拉取官方模板**：使用 `run_shell_command` 或相关终端工具执行 Git Clone。
+   ```bash
+   git clone https://github.com/quicktvui/quicktvui-template.git <项目名称>
+   ```
+2. **清理 Git 记录**：进入新建的项目目录，删除 `.git` 文件夹。
+   ```bash
+   cd <项目名称> && rm -rf .git
+   ```
+3. **修改项目信息**：读取并修改项目根目录的 `package.json`，将 `name` 字段修改为用户指定的 <项目名称>，重置 `version` 为 `"1.0.0"`。
+4. **安装依赖**：推荐使用 `yarn` 进行安装。
+   ```bash
+   cd <项目名称> && yarn install
+   ```
+5. **初始化环境提示**：告知用户若首次开发，需运行 `npm install -g @quicktvui/cli@latest` 和 `qui setup` 配置环境（参考 https://quicktvui.com/zh-CN/guide/basic/quick-start.html），然后使用 `npm run dev` 启动服务。
+
+## 规范与约束
+
+- 绝对不能凭空生成项目文件结构！必须从 `https://github.com/quicktvui/quicktvui-template.git` 拉取代码。
+- 确保 `package.json` 修改后的 JSON 格式有效。

package/rules/.claude/commands/lookup-api.md

@@ -0,0 +1,28 @@
+# 查询 QuickTVUI 组件 API
+
+根据用户提到的组件名称，查找并展示其 API。
+
+## 组件名称映射
+
+组件前缀 `Qt` 或 `qt-` 对应去掉前缀的名称：
+
+- QtButton / qt-button → button
+- QtText / qt-text → text
+- QtImage / qt-image → image
+
+## 查询方式
+
+1. 先查看 CLAUDE.md 中的组件速查表
+2. 如不够详细，访问 https://quicktvui.com 在线文档
+3. 参考示例仓库中的实际用法：
+   - https://github.com/quicktvui/quicktvui.git
+   - https://github.com/quicktvui/hellotv.git
+
+## 回答格式
+
+展示组件的：
+
+- Props（属性名、类型、默认值、说明）
+- Events（事件名、参数、说明）
+- Slots（插槽名、说明）
+- Exposes（暴露方法，如有）

package/rules/.claude/commands/lookup-css.md

@@ -0,0 +1,53 @@
+# 查询 QuickTVUI CSS 属性
+
+根据用户的 CSS/布局需求，提供 QuickTVUI 兼容的写法。
+
+## 核心限制
+
+- 只支持 px 单位（不支持 %, auto, vh, vw, rem, em）
+- 不支持简写属性（margin: 5px 10px → 拆成 margin-top/right/bottom/left）
+- 不支持 CSS 变量、!important
+- 默认 flexbox 布局，默认 flex-direction: column
+- 所有元素必须显式指定 width 和 height
+
+## 全部支持的属性
+
+### 布局
+
+`width`, `height`, `left`, `top`, `overflow`, `direction`, `zIndex`, `visibility`, `opacity`, `transform`
+
+### 背景
+
+`backgroundColor`, `backgroundImage`, `backgroundPositionX`, `backgroundPositionY`, `backgroundSize`, `linearGradient`
+
+### 边框
+
+`borderColor/Style/Width/Radius`, `borderTop/Bottom/Left/Right` + Color/Style/Width, 四角圆角
+
+### 阴影
+
+`shadowColor`, `shadowOffset`, `shadowOffsetX/Y`, `shadowOpacity`, `shadowRadius`
+
+### 文字
+
+`color`, `text`, `textAlign`, `textAlignVertical`, `fontSize`, `fontFamily/Style/Weight`, `fakeBold`, `letterSpacing`, `lineHeight`, `lineSpacingExtra/Multiplier`, `numberOfLines`, `ellipsizeMode`, `textDecoration*`, `textShadow*`, `verticalAlign`
+
+### 图片
+
+`src`, `resizeMode`, `tintColor`, `tintColorBlendMode`, `capInsets`, `defaultSource`
+
+### 焦点态
+
+`focusBackgroundColor`, `focusColor`, `selectColor`, `selectBackgroundColor`
+`enableFocusBorder`, `focusBorder`, `focusBorderWidth/Color/Style/Radius`
+`focusBorderTopLeftRadius`, `focusBorderTopRightRadius`
+`focusBorderBottomRightRadius`, `focusBorderBottomLeftRadius`
+`focusBorderType`, `focusBorderColorString`, `enableBlackBorder`
+
+### 输入与其他
+
+`caret-color`, `placeholderTextColor`, `blur`
+
+## 在线文档
+
+https://quicktvui.com

package/rules/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "Bash(git checkout -- src/views/detail.vue)",
+      "Bash(node -e \"const s = require\\('fs'\\).readFileSync\\('/Users/liulipeng/workspace/quicktv/quicktvui-ai/node_modules/@quicktvui/quicktvui3/dist/index.js','utf8'\\); const matches = s.match\\(/name\\\\s*:\\\\s*['\\\\\"]qt-[^'\\\\\"]*['\\\\\"/]/g\\); console.log\\(matches ? matches.join\\('\\\\n'\\) : 'no matches'\\)\")",
+      "Bash(node -e \"const s = require\\('fs'\\).readFileSync\\('/Users/liulipeng/workspace/quicktv/quicktvui-ai/node_modules/@quicktvui/quicktvui3/dist/index.js','utf8'\\); const matches = s.match\\(/clip[A-Za-z]*/gi\\); if\\(matches\\) console.log\\([...new Set\\(matches\\)].join\\('\\\\n'\\)\\); else console.log\\('no matches'\\)\")",
+      "Bash(node -e \"const s = require\\('fs'\\).readFileSync\\('/Users/liulipeng/workspace/quicktv/quicktvui-ai/node_modules/@extscreen/es3-vue/dist/index.js','utf8'\\); const matches = s.match\\(/clip[A-Za-z]*/gi\\); if\\(matches\\) console.log\\([...new Set\\(matches\\)].join\\('\\\\n'\\)\\); else console.log\\('no matches'\\)\" 2>/dev/null || echo \"file not found, trying other paths\")"
+    ]
+  }
+}