@quicktvui/ai 1.0.1 → 1.0.3

package/package.json

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

package/postinstall.js

@@ -11,7 +11,10 @@ if (!projectRoot || !fs.existsSync(projectRoot)) {
 }
 
 // 避免在包自身的开发环境中循环复制
-if (projectRoot === __dirname || projectRoot === path.join(__dirname, '..', '..')) {
+if (
+  projectRoot === __dirname ||
+  projectRoot === path.join(__dirname, "..", "..")
+) {
   process.exit(0);
 }
 
@@ -20,7 +23,7 @@ console.log(`📂 目标目录: ${projectRoot}`);
 
 const rulesDir = path.join(__dirname, "rules");
 const backupBaseDir = path.join(projectRoot, ".quicktvui-ai-backup");
-const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
 const currentBackupDir = path.join(backupBaseDir, `backup_${timestamp}`);
 
 function copyDirectorySync(src, dest) {
@@ -46,7 +49,8 @@ try {
     const targetPath = path.join(projectRoot, item);
     if (fs.existsSync(targetPath)) {
       if (!backupNeeded) {
-        if (!fs.existsSync(currentBackupDir)) fs.mkdirSync(currentBackupDir, { recursive: true });
+        if (!fs.existsSync(currentBackupDir))
+          fs.mkdirSync(currentBackupDir, { recursive: true });
         backupNeeded = true;
       }
       const backupPath = path.join(currentBackupDir, item);
@@ -59,7 +63,9 @@ try {
   });
 
   if (backupNeeded) {
-    console.log(`📦 已检测到现有 AI 配置文件，已备份至: .quicktvui-ai-backup/backup_${timestamp}`);
+    console.log(
+      `📦 已检测到现有 AI 配置文件，已备份至: .quicktvui-ai-backup/backup_${timestamp}`,
+    );
   }
 
   // 2. 注入新规则
@@ -75,7 +81,9 @@ try {
 
   const itemsToIgnore = [
     ".quicktvui-ai-backup",
-    ...rootItems.map(item => item === ".github" ? ".github/copilot-instructions.md" : item)
+    ...rootItems.map((item) =>
+      item === ".github" ? ".github/copilot-instructions.md" : item,
+    ),
   ];
 
   let updatedGitignore = gitignoreContent;
@@ -83,7 +91,10 @@ try {
 
   const sectionHeader = "# QuickTVUI AI Rules";
   if (!updatedGitignore.includes(sectionHeader)) {
-    updatedGitignore += (updatedGitignore.length > 0 && !updatedGitignore.endsWith("\n") ? "\n" : "") + `\n${sectionHeader}\n`;
+    updatedGitignore +=
+      (updatedGitignore.length > 0 && !updatedGitignore.endsWith("\n")
+        ? "\n"
+        : "") + `\n${sectionHeader}\n`;
     hasChanges = true;
   }
 
@@ -97,11 +108,10 @@ try {
   });
 
   if (hasChanges) {
-  fs.writeFileSync(gitignorePath, updatedGitignore);
-  console.log("✅ 已更新 .gitignore，排除 AI 配置文件。");
+    fs.writeFileSync(gitignorePath, updatedGitignore);
+    console.log("✅ 已更新 .gitignore，排除 AI 配置文件。");
   }
-  } catch (err) {
-
+} catch (err) {
   console.error(`❌ 注入失败: ${err.message}`);
 }
 

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

@@ -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.
@@ -143,6 +143,26 @@ Other CSS rules:
 <qt-list-view :clipChildren="false" :clipPadding="false" />
 ```
 
+## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
+
+当用户通过以下方式表达困惑时：
+- **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+
+**AI 执行协议：**
+1. **脱敏诊断 (Sanitized Diagnosis)**：
+   - 提取报错日志（去除绝对路径和私密 Token）。
+   - 整理环境信息（Node 版本、package.json 中的框架版本）。
+   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
+2. **寻求授权 (Request Consent)**：
+   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
+3. **提交方式 (Submission)**：
+   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
+     - macOS: `open "URL"`
+     - Linux: `xdg-open "URL"`
+     - Windows: `start "URL"`
+   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
+
 ### Import Sources
 - `defineComponent` from `vue` — NOT from `@vue/runtime-core`
 - Router: `useESRouter` from `@extscreen/es3-router`
@@ -154,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

@@ -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.
@@ -143,6 +143,26 @@ Other CSS rules:
 <qt-list-view :clipChildren="false" :clipPadding="false" />
 ```
 
+## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
+
+当用户通过以下方式表达困惑时：
+- **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+
+**AI 执行协议：**
+1. **脱敏诊断 (Sanitized Diagnosis)**：
+   - 提取报错日志（去除绝对路径和私密 Token）。
+   - 整理环境信息（Node 版本、package.json 中的框架版本）。
+   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
+2. **寻求授权 (Request Consent)**：
+   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
+3. **提交方式 (Submission)**：
+   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
+     - macOS: `open "URL"`
+     - Linux: `xdg-open "URL"`
+     - Windows: `start "URL"`
+   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
+
 ### Import Sources
 - `defineComponent` from `vue` — NOT from `@vue/runtime-core`
 - Router: `useESRouter` from `@extscreen/es3-router`
@@ -154,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

@@ -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

@@ -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.
@@ -143,6 +143,26 @@ Other CSS rules:
 <qt-list-view :clipChildren="false" :clipPadding="false" />
 ```
 
+## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
+
+当用户通过以下方式表达困惑时：
+- **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+
+**AI 执行协议：**
+1. **脱敏诊断 (Sanitized Diagnosis)**：
+   - 提取报错日志（去除绝对路径和私密 Token）。
+   - 整理环境信息（Node 版本、package.json 中的框架版本）。
+   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
+2. **寻求授权 (Request Consent)**：
+   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
+3. **提交方式 (Submission)**：
+   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
+     - macOS: `open "URL"`
+     - Linux: `xdg-open "URL"`
+     - Windows: `start "URL"`
+   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
+
 ### Import Sources
 - `defineComponent` from `vue` — NOT from `@vue/runtime-core`
 - Router: `useESRouter` from `@extscreen/es3-router`
@@ -154,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

@@ -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.
@@ -154,6 +154,26 @@ Android clips child views outside parent bounds by default. When using `focusSca
 <qt-list-view :clipChildren="false" :clipPadding="false" />
 ```
 
+## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
+
+当用户通过以下方式表达困惑时：
+- **关键词触发**：当用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+
+**AI 执行协议 (Execution Protocol)：**
+1. **脱敏诊断 (Sanitized Diagnosis)**：
+   - 提取报错日志（必须去除绝对路径和私密 Token/API Keys）。
+   - 整理环境信息（Node 版本、package.json 中的框架版本）。
+   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
+2. **寻求授权 (Request Consent)**：
+   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
+3. **提交方式 (Submission)**：
+   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
+     - macOS: `open "URL"`
+     - Linux: `xdg-open "URL"`
+     - Windows: `start "URL"`
+   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
+
 ### Import Sources
 
 - `defineComponent` from `vue` — NOT from `@vue/runtime-core`
@@ -166,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/CLAUDE.md

@@ -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`
@@ -178,6 +178,26 @@ Android 默认裁切超出父容器边界的子元素。TV 端使用 `focusScale
 <qt-waterfall :clipChildren="false" :clipPadding="false" />
 ```
 
+## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
+
+当用户通过以下方式表达困惑时：
+- **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+
+**AI 执行协议：**
+1. **脱敏诊断 (Sanitized Diagnosis)**：
+   - 提取报错日志（去除绝对路径和私密 Token）。
+   - 整理环境信息（Node 版本、package.json 中的框架版本）。
+   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
+2. **寻求授权 (Request Consent)**：
+   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
+3. **提交方式 (Submission)**：
+   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
+     - macOS: `open "URL"`
+     - Linux: `xdg-open "URL"`
+     - Windows: `start "URL"`
+   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
+
 ### import 来源
 
 - `defineComponent` 从 `vue` 导入（对），不要从 `@vue/runtime-core` 导入
@@ -266,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

@@ -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`
@@ -159,6 +159,26 @@ Android clips child views outside parent bounds by default. When using `focusSca
 <qt-list-view :clipChildren="false" :clipPadding="false" />
 ```
 
+## 🛡️ AI Sentinel: 框架问题上报机制 (Bug Reporting)
+
+当用户通过以下方式表达困惑时：
+- **关键词触发**：用户提到“问题上报”、“碰到问题”、“反馈”、“Bug 反馈”、“还是没改好”、“运行报错”、“API 报错”等。
+- **自动检测触发**：同一段代码逻辑在 3 次修复后仍然报错，或 AI 确认生成的代码符合 `.docs` 规范但无法在用户端运行。
+
+**AI 执行协议：**
+1. **脱敏诊断 (Sanitized Diagnosis)**：
+   - 提取报错日志（去除绝对路径和私密 Token）。
+   - 整理环境信息（Node 版本、package.json 中的框架版本）。
+   - 编写最小可复现 Demo 代码（Minimum Reproducible Example）。
+2. **寻求授权 (Request Consent)**：
+   - AI 必须询问：“检测到该问题可能属于 QuickTVUI 框架缺陷，我已为您准备好一份脱敏后的诊断报告，是否允许我协助您将其上报到 GitHub 官方仓库以寻求官方支持？”
+3. **提交方式 (Submission)**：
+   - 授权后，**自动打开浏览器**：AI 应尝试根据操作系统执行系统命令以自动打开 Issue 链接：
+     - macOS: `open "URL"`
+     - Linux: `xdg-open "URL"`
+     - Windows: `start "URL"`
+   - 如果自动打开失败，则展示 Issue 预填充链接引导用户点击。
+
 ### Import Sources
 
 - `defineComponent` from `vue` (correct) — NOT from `@vue/runtime-core`
@@ -171,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