@quicktvui/ai 1.0.2 → 1.0.4

package/README.md

@@ -11,7 +11,7 @@ QuickTVUI 官方提供的 AI 辅助开发规范包。
 - `.clinerules` (供 Cline/Roo-Code 使用)
 - `.github/copilot-instructions.md` (供 GitHub Copilot 使用)
 - `GEMINI.md` / `CLAUDE.md` / `AGENTS.md` (供其他模型使用)
-- `.docs/` (本地轻量级 QuickTVUI 知识库)
+- `node_modules/@quicktvui/ai/rules/.docs/` (本地轻量级 QuickTVUI 知识库)
 
 这些规则会强制 AI：
 1. **停止捏造标签**（如禁止使用 `qt-web-view`，强制使用 `qt-web`）。
@@ -33,4 +33,4 @@ yarn add @quicktvui/ai --dev
 
 ## 验证
 
-安装完毕后，请检查你的项目根目录是否多出了 `.cursorrules` 等文件以及 `.docs` 目录。如果有，说明注入成功，尽情享受不踩坑的 AI 编程体验吧！
+安装完毕后，请检查你的项目根目录是否多出了 `.cursorrules` 等文件。如果有，说明注入成功，尽情享受不踩坑的 AI 编程体验吧！(注：`.docs` 文档库现在直接引用 `node_modules` 路径，不再复制到根目录)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "QuickTVUI AI 开发规范与脚手架注入工具",
   "main": "index.js",
   "scripts": {

package/postinstall.js

@@ -41,7 +41,7 @@ function copyDirectorySync(src, dest) {
 }
 
 try {
-  const rootItems = fs.readdirSync(rulesDir);
+  const rootItems = fs.readdirSync(rulesDir).filter((item) => item !== ".docs");
   let backupNeeded = false;
 
   // 1. 检查并备份现有配置
@@ -69,7 +69,15 @@ try {
   }
 
   // 2. 注入新规则
-  copyDirectorySync(rulesDir, projectRoot);
+  rootItems.forEach((item) => {
+    const srcPath = path.join(rulesDir, item);
+    const destPath = path.join(projectRoot, item);
+    if (fs.lstatSync(srcPath).isDirectory()) {
+      copyDirectorySync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  });
   console.log("🎉 [@quicktvui/ai] AI 规范注入成功！");
 
   // 3. 更新 .gitignore

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

@@ -12,7 +12,7 @@
 - 子元素跟随焦点状态：`:duplicateParentState="true"`
 - 文字用 `<span>` 或 `<qt-text>` 包裹
 - 所有元素显式指定 width/height（px）
-- 不用写 `display: flex`，默认就是 flex，默认 flex-direction: column
+- 必须声明 `display: flex;`，QuickTVUI 仅支持 flex 布局，默认 flex-direction: column
 - 不支持 %、auto、vh/vw、grid、动画、阴影、CSS 简写属性
 - 横向列表用 `<ul :horizontal="true">`
 - 设置 border 必须同时设置 border-color

package/rules/.clinerules

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -126,7 +126,7 @@ Other CSS rules:
 - **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.
-- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
 - Only use properties listed in "Supported Style Properties" section below
 - Do NOT use `<style scoped>` (unreliable in native rendering)
 - Only `px` units (no %, auto, vh, vw, rem, em). No CSS shorthand.
@@ -147,7 +147,7 @@ Other CSS rules:
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范 but 无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：
@@ -174,7 +174,7 @@ Other CSS rules:
 
 Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
 
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
 
 ### Layout & Size
 `width`, `height`, `left`, `top`, `overflow`, `direction`, `z-index`, `visibility`, `opacity`, `transform`

package/rules/.cursorrules

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -126,7 +126,7 @@ Other CSS rules:
 - **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.
-- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
 - Only use properties listed in "Supported Style Properties" section below
 - Do NOT use `<style scoped>` (unreliable in native rendering)
 - Only `px` units (no %, auto, vh, vw, rem, em). No CSS shorthand.
@@ -147,7 +147,7 @@ Other CSS rules:
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：
@@ -174,7 +174,7 @@ Other CSS rules:
 
 Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
 
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
 
 ### Layout & Size
 `width`, `height`, `left`, `top`, `overflow`, `direction`, `z-index`, `visibility`, `opacity`, `transform`

package/rules/.docs/zh-CN/css/layout/display.md

@@ -5,7 +5,8 @@ lang: zh-CN
 
 # display
 
-QuickTVUI 默认采用 Flex 布局。同时，因为仅支持 Flex 布局，所以不需要手写 `display: flex` 即可使用。
+QuickTVUI 默认采用 Flex 布局。同时， 因为仅支持 Flex 布局，所以必须手写 `display: flex` 才能生效。
+
 
 | Name               | Description      | Type                         | Default |
 |--------------------|------------------|------------------------------| ------- |

package/rules/.docs/zh-CN/guide/layout/layout.md

@@ -28,7 +28,7 @@ lang: zh-CN
 ## 布局（Flex）
 
 默认采用现在移动端最流行的 `Flex` 布局。
-因为仅支持 `Flex` 布局，所以不需要手写 `display: flex` 即可使用。
+因为仅支持 `Flex` 布局，所以必须手写 `display: flex` 才能生效。
 `Flex` 布局与 `Web` 的 `Flex` 类似，它们都旨在提供一个更加有效的方式制定、调整和分布一个容器里的项目布局，即使他们的大小是未知或者是动态的。
 `Flex` 规定了弹性元素如何伸长或缩短，以适应`flex容器`中的可用空间。
 

package/rules/.github/copilot-instructions.md

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -133,7 +133,7 @@ Other CSS rules:
 - **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.
-- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
 - Only use properties listed in "Supported Style Properties" section below
 - Do NOT use `<style scoped>` (unreliable in native rendering)
 - Only `px` units (no %, auto, vh, vw, rem, em). No CSS shorthand.
@@ -166,7 +166,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
 
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
 
 ### Layout & Size
 

package/rules/.windsurfrules

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -126,7 +126,7 @@ Other CSS rules:
 - **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.
-- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
 - Only use properties listed in "Supported Style Properties" section below
 - Do NOT use `<style scoped>` (unreliable in native rendering)
 - Only `px` units (no %, auto, vh, vw, rem, em). No CSS shorthand.
@@ -147,7 +147,7 @@ Other CSS rules:
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：
@@ -174,7 +174,7 @@ Other CSS rules:
 
 Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
 
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
 
 ### Layout & Size
 `width`, `height`, `left`, `top`, `overflow`, `direction`, `z-index`, `visibility`, `opacity`, `transform`

package/rules/AGENTS.md

@@ -6,14 +6,14 @@
 
 **AI MUST refer to the official documentation and source code below BEFORE generating any code. NEVER hallucinate component names, attribute names, or APIs. These are the ONLY authorities.**
 
-1.  **Local Documentation (PRIMARY)**: The `.docs/` folder in the project root. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `.docs/` directory before generating code.**
+1.  **Local Documentation (PRIMARY)**: The `node_modules/@quicktvui/ai/rules/.docs/` folder. Contains detailed MD documentation for all components, CSS, and native modules. **AI MUST use `grep_search` or `read_file` to retrieve relevant content from the `node_modules/@quicktvui/ai/rules/.docs/` directory before generating code.**
 2.  **Official Docs**: https://quicktvui.com (390+ docs)
 3.  **Core Library Samples**: https://github.com/quicktvui/quicktvui.git (Core library + samples)
 4.  **Cross-platform Framework Samples**: https://github.com/quicktvui/es-vue3.git (Cross-platform framework + samples)
 5.  **Best Practice App**: https://github.com/quicktvui/hellotv.git (Complete video app)
 
 **STRICT RULES:**
-- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
+- **VERIFY CAPABILITIES FIRST**: Before implementing features like "video playback," search the `node_modules/@quicktvui/ai/rules/.docs/` directory to verify component capabilities. DO NOT assume web behavior. **For example, `qt-web-view` does NOT support video playback; you MUST use the native `es-video-player` and `es-player-manager` components.**
 - **NOT A BROWSER & NO HTML**: **This framework does NOT support HTML. Standard HTML tags (like `p`, `img`, `a`, `ul`, `li`, `h1`) are STRICTLY PROHIBITED. It does NOT support `window`, `document` (DOM), or DOM APIs. You must exclusively use framework tags (like `qt-text`, `qt-image`) and Vue `ref`s.**
 - **NO HALLUCINATED TAGS**: e.g. `qt-web` is wrong, it is `qt-web-view`.
 - **NO HALLUCINATED APIs**: e.g. `onBack` is wrong, it must be `onBackPressed`.
@@ -133,7 +133,7 @@ CORRECT — `<template>` tag attributes use camelCase:
 
 Other CSS rules:
 
-- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
 - Only use properties listed in "Supported Style Properties" section below
 - Do NOT use `<style scoped>` (unreliable in native rendering)
 - Only `px` units (no %, auto, vh, vw, rem, em). No CSS shorthand.
@@ -158,7 +158,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：当用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议 (Execution Protocol)：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：
@@ -186,7 +186,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
 
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
 
 ### Layout & Size
 

package/rules/AI_HANDOFF.md

@@ -6,14 +6,14 @@
 
 **AI 在生成任何代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有开发工作的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.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`）。**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `node_modules/@quicktvui/ai/rules/.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`。
@@ -64,7 +64,7 @@ QuickTVUI 是基于 Vue 3 的 Android TV/大屏端 UI 框架，运行在 Hippy-b
 
 1. 自动理解 QuickTVUI 框架的核心概念和约束
 2. 生成符合框架规范的 Vue 代码（焦点系统、CSS 子集、TV 交互）
-3. 所有配置文件自包含、可移植，拷贝到任何 QuickTVUI 应用项目即可使用
+3. 所有配置文件引用 `@quicktvui/ai` 包内的文档库，安装包后即可使用。
 
 ## 三、已创建的文件清单
 
@@ -134,9 +134,9 @@ CSS 属性列表由框架作者直接提供，优先级高于文档推断。已
 
 ### 1. 自包含 vs 引用本地文档路径
 
-最初版本引用了 `docs/zh-CN/component/<name>.md` 等本地路径，但这些路径只存在于框架源码仓库中，不存在于用户的应用项目中。
+最初版本引用了 `docs/zh-CN/component/<name>.md` 等本地路径，但这些路径只存在于框架源码仓库中，不存 在于用户的应用项目中。
 
-**最终方案**：所有 AI 指令文件完全自包含，将核心知识直接嵌入文件内容，不依赖任何本地文件路径。用户只需将文件拷贝到自己的项目根目录即可使用。
+**最终方案**：AI 指令文件引用 `node_modules/@quicktvui/ai/rules/.docs/` 目录。用户通过安装 `@quicktvui/ai` 包即可获得这些文档。这样既保持了知识的实时性，又避免了在用户项目根目录下生成大量冗余文件。
 
 ### 2. 分层详略
 
@@ -354,7 +354,7 @@ onESCreate(params) → onESStart() → onESResume() → onESPause() → onESStop
 3. 根据"后续改进建议"选择优先级高的任务开始改进
 
 4. 改进时的关键原则：
-   - 保持所有文件自包含、可移植
+   - 保持配置文件引用的路径正确、可移植
    - 从 `docs/zh-CN/` 提取知识，不要编造
    - 使用用户提供的权威 CSS 属性列表
    - 参考 3 个外部代码仓库的实际代码风格

package/rules/CLAUDE.md

@@ -6,18 +6,18 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.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`）。**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `node_modules/@quicktvui/ai/rules/.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`。
-- **参考优先**：遇到不确定的组件用法，必须先在上述仓库中搜索同名组件的实际用法。
+- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或 `node_modules/@quicktvui/ai/rules/.docs/` 中搜索同名组件的实际用法。
 
 ## 快速创建项目 (Scaffolding)
 
@@ -151,9 +151,9 @@ https://quicktvui.com
 - **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.
-- **⚠️ 强制要求：默认布局为 `flex-direction: column`**。与 Web 浏览器不同，QuickTVUI 默认就是垂直布局。你几乎不需要写 `display: flex`。
+- **⚠️ 强制要求：必须声明 `display: flex;`**。QuickTVUI 仅支持 Flexbox 布局，所有样式化的元素必须显式包含 `display: flex;`。默认布局方向为 `flex-direction: column;`。
 - 只有本文档"二、样式属性"章节中列出的属性才能使用
-- `display: flex` 和 `flex-direction: column` 是支持的，但它们是默认值，通常不需要写
+- `display: flex` 和 `flex-direction: column` 是强制要求的。
 - 不要用 `<style scoped>`（在原生渲染中不可靠，直接用 `<style>`）
 - 不支持 `%`、`auto`、`vh`、`vw`、`rem`、`em` 单位，只支持 `px`
 - 不支持 CSS 简写如 `margin: 5px 10px`，必须拆写为 `margin-top: 5px; margin-right: 10px`
@@ -182,7 +182,7 @@ Android 默认裁切超出父容器边界的子元素。TV 端使用 `focusScale
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：
@@ -286,7 +286,7 @@ QuickTVUI 的样式是 Web CSS 的子集，默认 Flexbox 布局，默认 flex-d
 - 只支持 px 单位（不支持 %、auto、vh/vw/rem/em）
 - 不支持 CSS 简写属性（如 `margin: 5px 10px`，必须拆写）
 - 不支持 CSS 变量 `var(--xxx)`、`!important`
-- 不需要写 `display: flex`（默认就是）
+- **强制要求：必须声明 `display: flex;`**
 - 所有元素必须显式指定 width 和 height
 - 文字必须用 `<span>` 或 `<qt-text>` 包裹
 

package/rules/GEMINI.md

@@ -6,18 +6,18 @@
 
 **AI 在生成代码前，必须严格参考以下权威来源，严禁凭空想象任何组件名、属性名或 API。这是所有代码的唯一依据。**
 
-1.  **本地文档 (PRIMARY)**：项目根目录下的 `.docs/` 文件夹。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `.docs/` 目录中的相关内容。**
+1.  **本地文档 (PRIMARY)**：`node_modules/@quicktvui/ai/rules/.docs/` 目录。包含所有组件、CSS、原生模块的详细 MD 文档。**AI 必须在生成代码前使用 `grep_search` 或 `read_file` 检索 `node_modules/@quicktvui/ai/rules/.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`。**
+- **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `node_modules/@quicktvui/ai/rules/.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`） and Vue `ref`。**
 - **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
 - **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
-- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或本地 `.docs` 中搜索同名组件的实际用法。
+- **参考优先**：遇到不确定的组件用法，必须先在上述仓库或 `node_modules/@quicktvui/ai/rules/.docs/` 中搜索同名组件的实际用法。
 
 ## 快速创建项目 (Scaffolding)
 
@@ -136,9 +136,9 @@ CORRECT — `<template>` tag attributes use camelCase:
 
 Other CSS rules:
 
-- **CRITICAL: DEFAULT LAYOUT IS `flex-direction: column`**. Unlike web browsers, QuickTVUI defaults to vertical layout. You rarely need to specify `display: flex`.
+- **CRITICAL: MANDATORY `display: flex;`**. QuickTVUI exclusively supports Flexbox layout. Every styled element MUST explicitly include `display: flex;`. The default orientation is `flex-direction: column;`.
 - Only use properties listed in "Supported Style Properties" section below
-- `display: flex` and `flex-direction: column` are supported but are defaults, usually unnecessary
+- `display: flex` and `flex-direction: column` are supported and MANDATORY for all layouts.
 - Do NOT use `<style scoped>` (unreliable in native rendering, use `<style>` only)
 - Only `px` units (no %, auto, vh, vw, rem, em)
 - No CSS shorthand like `margin: 5px 10px` — must split: `margin-top: 5px; margin-right: 10px`
@@ -163,7 +163,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 当用户通过以下方式表达困惑时：
 - **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
-- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `node_modules/@quicktvui/ai/rules/.docs/` 规范但无法在用户端运行。
 
 **AI 执行协议：**
 1. **脱敏诊断 (Sanitized Diagnosis)**：
@@ -191,7 +191,7 @@ Android clips child views outside parent bounds by default. When using `focusSca
 
 Only properties listed below are supported. Default layout: flexbox, flex-direction: column.
 
-Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. No `display: flex` needed. All elements MUST have explicit width/height.
+Rules: px units only (no %, auto, vh/vw/rem/em). No CSS shorthand. No CSS variables. MANDATORY `display: flex;` for all elements. All elements MUST have explicit width/height.
 
 ### Layout & Size