@quicktvui/ai 1.1.13 → 1.1.16

package/README.md

@@ -107,6 +107,7 @@ quicktvui-ai prompt --lang zh
 ### 2. 严格的 CSS 子集
 - 必须使用 `px` 单位，严禁使用 `%`, `auto`, `rem`, `vh` 等。
 - 严禁 CSS 属性简写（如 `margin` 必须拆分为 `margin-top` 等）。
+- 所有标签和组件都必须显式设置 `width` 和 `height`，不能依赖文本内容、父容器或自动撑开。
 - 必须显式声明 `display: flex` 且默认方向为 `column`。
 
 ### 3. TV 特有的焦点系统

package/USAGE.md

@@ -61,6 +61,7 @@ quicktvui-ai doctor
 当 AI 为你生成代码后，请务必核对以下关键点：
 
 - [ ] **标签检查**：是否误用了 `p`, `img`, `h1`？（必须是 `qt-text`, `qt-image`）
+- [ ] **尺寸检查**：所有标签和组件是否都显式设置了 `width` 和 `height`？（尤其 `div`、`span`、`qt-text`、`qt-image`、`qt-view`）
 - [ ] **生命周期**：入口函数是否叫 `onESCreate(params)`？
 - [ ] **返回键**：处理函数是否叫 `onBackPressed()` 且已 `return`？
 - [ ] **焦点系统**：页面是否至少有一个元素设置了 `:autofocus="true"`？

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: create-component.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # 创建 QuickTVUI 组件

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

@@ -1,6 +1,6 @@
 ---
 name: create-page.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # 创建 TV 页面

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

@@ -1,6 +1,6 @@
 ---
 name: create-project.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # 创建 QuickTVUI 项目

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

@@ -1,6 +1,6 @@
 ---
 name: lookup-api.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # 查询 QuickTVUI 组件 API

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

@@ -1,6 +1,6 @@
 ---
 name: lookup-css.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # 查询 QuickTVUI CSS 属性

package/rules/.clinerules

@@ -1,6 +1,6 @@
 ---
 name: .clinerules
-version: 0.6.1
+version: 1.1.14
 ---
 
 # .clinerules - QuickTVUI AI Development Guide
@@ -35,6 +35,7 @@ version: 0.6.1
 **STRICT RULES:**
 - **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.**
+- **EXPLICIT SIZE IS MANDATORY FOR ALL TAGS AND COMPONENTS**: Every tag and component, including `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all `qt-*` components, MUST declare explicit `width` and `height` in px. Do NOT rely on content, parent layout, or auto sizing.
 - **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`.
 - **REFERENCE FIRST**: Search for component usages in the linked repositories if unsure.
@@ -82,6 +83,25 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the user asks AI to inspect runtime logs, native logs, screenshots, or target state:
+
+1. Prefer connected `@quicktvui/ai-debug-mcp`
+2. Otherwise use `quicktvui-ai debug-*`
+3. Only ask the user to paste logs manually when neither path is available
+
+Required CLI order:
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. resolve `clientId`
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*` actually returned it.
+
 
 ## Game Loop & Timer Constraints (CRITICAL)
 
@@ -146,6 +166,7 @@ QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on
 ### Component Names (Must be exact — no HTML tag substitutes)
 - Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
 - Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
+- All tags and components, including `<div>`, `<span>`, `<qt-text>`, `<qt-image>`, `<qt-view>`, and all `qt-*` tags, MUST declare explicit `width` and `height` (px).
 - Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
 - Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
 
@@ -192,6 +213,7 @@ CORRECT — `<template>` tag attributes use camelCase:
 Other CSS rules:
 
 - **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: Every tag and component MUST set explicit `width` and `height` in px.** This includes `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all other `qt-*` components.
 - **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
 - **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
 - **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.

package/rules/.cursorrules

@@ -1,6 +1,6 @@
 ---
 name: .cursorrules
-version: 0.6.1
+version: 1.1.14
 ---
 
 # .cursorrules - QuickTVUI AI Development Guide
@@ -35,6 +35,7 @@ version: 0.6.1
 **STRICT RULES:**
 - **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.**
+- **EXPLICIT SIZE IS MANDATORY FOR ALL TAGS AND COMPONENTS**: Every tag and component, including `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all `qt-*` components, MUST declare explicit `width` and `height` in px. Do NOT rely on content, parent layout, or auto sizing.
 - **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`.
 - **REFERENCE FIRST**: Search for component usages in the linked repositories if unsure.
@@ -82,6 +83,25 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the user asks AI to inspect runtime logs, native logs, screenshots, or target state:
+
+1. Prefer connected `@quicktvui/ai-debug-mcp`
+2. Otherwise use `quicktvui-ai debug-*`
+3. Only ask the user to paste logs manually when neither path is available
+
+Required CLI order:
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. resolve `clientId`
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*` actually returned it.
+
 
 ## Game Loop & Timer Constraints (CRITICAL)
 
@@ -147,6 +167,7 @@ QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on
 ### Component Names (Must be exact — no HTML tag substitutes)
 - Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
 - Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
+- All tags and components, including `<div>`, `<span>`, `<qt-text>`, `<qt-image>`, `<qt-view>`, and all `qt-*` tags, MUST declare explicit `width` and `height` (px).
 - Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
 - Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
 
@@ -193,6 +214,7 @@ CORRECT — `<template>` tag attributes use camelCase:
 Other CSS rules:
 
 - **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: Every tag and component MUST set explicit `width` and `height` in px.** This includes `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all other `qt-*` components.
 - **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
 - **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
 - **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.

package/rules/.docs/zh-CN/guide/ai/ai-assistant.md

@@ -56,6 +56,7 @@ quicktvui-ai doctor
 当 AI 为你生成代码后，请务必核对以下关键点：
 
 - **标签检查**：是否误用了 `p`, `img`, `h1`？（必须是 `qt-text`, `qt-image`）
+- **尺寸检查**：所有标签和组件是否都显式设置了 `width` 和 `height`？（尤其 `div`、`span`、`qt-text`、`qt-image`、`qt-view`）
 - **生命周期**：入口函数是否叫 `onESCreate(params)`？
 - **返回键**：处理函数是否叫 `onBackPressed()` 且已 `return`？
 - **焦点系统**：页面是否至少有一个元素设置了 `:autofocus="true"`？

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

@@ -5,9 +5,9 @@ lang: zh-CN
 
 # 布局样式相关问题
 
-## 一、所有的组件都需要指定宽高尺寸
+## 一、所有的标签和组件都需要指定宽高尺寸
 
-`div`、`qt-text`、`qt-image`、`qt-view`等组件都需要指定宽高尺寸
+`div`、`span`、`qt-text`、`qt-image`、`qt-view` 等标签和组件都需要指定宽高尺寸
 
 ## 二、仅支持部分 css 样式
 

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

@@ -1,6 +1,6 @@
 ---
 name: copilot-instructions.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # copilot-instructions.md - QuickTVUI AI Development Guide
@@ -35,6 +35,7 @@ version: 1.1.13
 **STRICT RULES:**
 - **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.**
+- **EXPLICIT SIZE IS MANDATORY FOR ALL TAGS AND COMPONENTS**: Every tag and component, including `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all `qt-*` components, MUST declare explicit `width` and `height` in px. Do NOT rely on content, parent layout, or auto sizing.
 - **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`.
 - **REFERENCE FIRST**: Search for component usages in the linked repositories if unsure.
@@ -48,6 +49,25 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
 4. **Install Deps**: `yarn install`
 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the task is to inspect a running QuickTVUI app, AI MUST use this priority:
+
+1. MCP first, if `@quicktvui/ai-debug-mcp` is connected.
+2. Otherwise use `quicktvui-ai debug-*` commands against `ESDebugServer`.
+3. Only ask the user to paste logs manually if neither tool path is available.
+
+Required CLI sequence:
+
+- `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+- select `clientId`
+- `quicktvui-ai debug-context --client-id <clientId>`
+- `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+- `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+- `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+AI MUST NOT say it has checked logs/screenshots unless one of those MCP/CLI reads actually succeeded.
+
 
 ## Game Loop & Timer Constraints (CRITICAL)
 
@@ -115,6 +135,7 @@ QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on
 
 - Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
 - Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
+- All tags and components, including `<div>`, `<span>`, `<qt-text>`, `<qt-image>`, `<qt-view>`, and all `qt-*` tags, MUST declare explicit `width` and `height` (px).
 - Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
 - Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
 
@@ -165,6 +186,7 @@ CORRECT — `<template>` tag attributes use camelCase:
 Other CSS rules:
 
 - **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: Every tag and component MUST set explicit `width` and `height` in px.** This includes `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all other `qt-*` components.
 - **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
 - **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
 - **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.
@@ -511,4 +533,4 @@ AI MUST understand the mapping between Vue components and Java Native controller
 | **(Deprecated)** | `Text` | `com.tencent.mtt.hippy.views.text.HippyTextViewController` | **DEPRECATED** |
 | **(Deprecated)** | `ListView` | `com.tencent.mtt.hippy.views.list.HippyListViewController` | **DEPRECATED** |
 
-**Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.
+**Rule**: Always prefer source code in `.source/hippy/extend_views/`. Use `.source/hippy/hippy_views/` only as a secondary fallback.

package/rules/.windsurfrules

@@ -1,6 +1,6 @@
 ---
 name: .windsurfrules
-version: 0.6.1
+version: 1.1.14
 ---
 
 # .windsurfrules - QuickTVUI AI Development Guide
@@ -35,6 +35,7 @@ version: 0.6.1
 **STRICT RULES:**
 - **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.**
+- **EXPLICIT SIZE IS MANDATORY FOR ALL TAGS AND COMPONENTS**: Every tag and component, including `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all `qt-*` components, MUST declare explicit `width` and `height` in px. Do NOT rely on content, parent layout, or auto sizing.
 - **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`.
 - **REFERENCE FIRST**: Search for component usages in the linked repositories if unsure.
@@ -82,6 +83,25 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the user asks AI to inspect runtime logs, native logs, screenshots, or target state:
+
+1. Prefer connected `@quicktvui/ai-debug-mcp`
+2. Otherwise use `quicktvui-ai debug-*`
+3. Only ask the user to paste logs manually when neither path is available
+
+Required CLI order:
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. resolve `clientId`
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*` actually returned it.
+
 
 ## Game Loop & Timer Constraints (CRITICAL)
 
@@ -146,6 +166,7 @@ QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on
 ### Component Names (Must be exact — no HTML tag substitutes)
 - Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
 - Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
+- All tags and components, including `<div>`, `<span>`, `<qt-text>`, `<qt-image>`, `<qt-view>`, and all `qt-*` tags, MUST declare explicit `width` and `height` (px).
 - Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
 - Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
 
@@ -192,6 +213,7 @@ CORRECT — `<template>` tag attributes use camelCase:
 Other CSS rules:
 
 - **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: Every tag and component MUST set explicit `width` and `height` in px.** This includes `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all other `qt-*` components.
 - **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
 - **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
 - **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.

package/rules/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 name: AGENTS.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # AGENTS.md - QuickTVUI AI Development Guide
@@ -35,6 +35,7 @@ version: 1.1.13
 **STRICT RULES:**
 - **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.**
+- **EXPLICIT SIZE IS MANDATORY FOR ALL TAGS AND COMPONENTS**: Every tag and component, including `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all `qt-*` components, MUST declare explicit `width` and `height` in px. Do NOT rely on content, parent layout, or auto sizing.
 - **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`.
 - **REFERENCE FIRST**: Search for component usages in the linked repositories if unsure.
@@ -114,6 +115,32 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the user asks AI to inspect runtime logs, native logs, screenshots, recent errors, or current target state for a running QuickTVUI app, AI MUST use this priority:
+
+1. Prefer MCP resources/tools when `@quicktvui/ai-debug-mcp` is connected.
+2. If MCP is unavailable but shell/CLI execution is available, AI MUST use `quicktvui-ai debug-*` commands against the running `ESDebugServer`.
+3. Only if neither MCP nor CLI execution is available may AI ask the user to paste logs manually.
+
+Required non-MCP command order:
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. Choose `clientId`
+   - If only one target exists, AI MAY use it directly.
+   - If multiple targets exist, AI MUST ask user to confirm the right `clientId`.
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+Hard requirements:
+
+- AI MUST NOT claim it has inspected Chrome logs, Android native logs, target context, or screenshots unless MCP or `quicktvui-ai debug-*` actually returned data.
+- If `debug-targets` returns an empty list, AI MUST clearly state that no active `ESDebugServer /ai/targets` are available yet.
+- If `debug-native-logs` or `debug-screenshot` fails, AI MUST report the concrete command/error instead of fabricating fallback observations.
+- When user asks for a screenshot and CLI mode is used, AI SHOULD prefer the file path returned by `quicktvui-ai debug-screenshot` rather than asking the user to locate the image manually.
+
 ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
 
 AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:
@@ -172,6 +199,7 @@ QuickTVUI is a Vue 3 UI framework for Android TV / large-screen devices. Runs on
 
 - Image component is `qt-image` — NOT `qt-img`, NOT `<img>`
 - Text MUST use `<qt-text>` or `<span>` — NOT `<p>`, `<h1>`~`<h6>`, `<label>`
+- All tags and components, including `<div>`, `<span>`, `<qt-text>`, `<qt-image>`, `<qt-view>`, and all `qt-*` tags, MUST declare explicit `width` and `height` (px).
 - Containers: `<div>`, `<qt-view>`, `<qt-row>`, `<qt-column>` — NOT `<section>`, `<main>`, `<article>`
 - Buttons: `<qt-button>` or focusable `<div>` — NOT `<button>`
 
@@ -228,6 +256,7 @@ CORRECT — `<template>` tag attributes use camelCase:
 
 Other CSS rules:
 
+- **CRITICAL: Every tag and component MUST set explicit `width` and `height` in px.** This includes `div`, `span`, `qt-text`, `qt-image`, `qt-view`, and all other `qt-*` components.
 - **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)

package/rules/AI_HANDOFF.md

@@ -1,6 +1,6 @@
 ---
 name: AI_HANDOFF.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # QuickTVUI AI 集成 - 工作交接文档
@@ -20,6 +20,7 @@ version: 1.1.13
 **要求：**
 - **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `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`。**
+- **标签与组件尺寸强约束**：所有标签和组件都必须显式设置 `width` 和 `height`（px），包括 `div`、`span`、`qt-text`、`qt-image`、`qt-view` 以及所有 `qt-*` 组件。不能依赖内容、父容器或自动撑开。
 - **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
 - **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
 - **参考优先**：遇到不确定的组件用法，必须先在上述仓库中搜索同名组件的实际用法。
@@ -41,6 +42,7 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 4.  **CSS 严格子集**：
     *   不支持任何 CSS 简写（例如 `margin: 10px` 必崩，必须写 `margin-top: 10px; margin-left: 10px;`）。
     *   不支持 `auto`，不支持 `%`。所有组件**必须显式定义宽高**（`width` / `height` 赋明确的 px 值）。
+    *   所有标签和组件都要遵守这个硬约束：生成代码时必须显式声明 `width` 和 `height`，不能依赖文案长度、父容器或 `autoWidth` / `autoHeight` 自动撑开。
 
 ## 快速创建项目 (Scaffolding)
 
@@ -59,6 +61,30 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 - 不得在未检查 CLI 能力前直接进入 `yarn dev` / 手写 `adb` 流程。
 - 若某一步骤在 `quicktvui-ai-cli` 中不存在对应命令，AI 必须先明确说明“CLI 暂不支持该步骤”，再走手工兜底流程。
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+对于“读取运行中应用调试数据”的任务，后续 AI 必须统一遵循以下优先级：
+
+1. 优先使用 `@quicktvui/ai-debug-mcp`
+2. 没有 MCP 时，使用 `quicktvui-ai debug-*`
+3. 两者都不可用时，才要求用户手工提供日志或截图
+
+当前约定的非 MCP 命令链路：
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. 选择或确认 `clientId`
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+接手注意事项：
+
+- 未通过 MCP 或 `quicktvui-ai debug-*` 真正读取到数据前，不得宣称“已检查运行时日志/截图”
+- `debug-targets` 返回空数组时，应先回到 run/dev 链路，确认 `ESDebugServer /ai/targets` 已建立
+- `debug-screenshot` 默认会把图片写到 `<project>/.quicktvui-ai/debug-screenshots/`，后续 AI 应优先使用命令返回的 `savedTo` 路径
+- `debug-native-logs` 与 `debug-screenshot` 的失败信息应直接向用户透明披露，不要二次包装成模糊描述
+
 ---
 
 ## 一、项目背景

package/rules/CLAUDE.md

@@ -1,6 +1,6 @@
 ---
 name: CLAUDE.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # QuickTVUI - AI 开发指南
@@ -35,6 +35,7 @@ version: 1.1.13
 **要求：**
 - **检索与能力验证优先**：在实现任何功能（如“视频播放”）前，必须先在 `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`。**
+- **标签与组件尺寸强约束**：所有标签和组件都必须显式设置 `width` 和 `height`（px），包括 `div`、`span`、`qt-text`、`qt-image`、`qt-view` 以及所有 `qt-*` 组件。不能依赖内容、父容器或自动撑开。
 - **严禁自造标签**：如 `qt-web` 是错的，官方示例中是 `qt-web-view`。
 - **严禁自造 API**：如 `onBack` 是错的，必须是 `onBackPressed`。
 - **参考优先**：遇到不确定的组件用法，必须先在上述仓库或 `node_modules/@quicktvui/ai/rules/.docs/` 中搜索同名组件的实际用法。
@@ -114,6 +115,31 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+当用户要求 AI 检查运行中应用的 console/network/exception、Android native logs、截图或当前 target 状态时，AI 必须使用以下优先级：
+
+1. 优先使用已连接的 `@quicktvui/ai-debug-mcp`
+2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai debug-*`
+3. 只有 MCP 和 CLI 都不可用时，才允许要求用户手工粘贴日志
+
+非 MCP 场景下，必须按以下顺序执行：
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. 选择 `clientId`
+   - 仅有一个 target 时可直接使用
+   - 多个 target 时必须让用户确认正确的 `clientId`
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+硬约束：
+
+- AI 未通过 MCP 或 `quicktvui-ai debug-*` 实际读取到数据前，不得声称自己已经检查过运行时日志、native logs 或截图
+- `debug-targets` 为空时，必须明确说明当前 `ESDebugServer /ai/targets` 还没有可读 target
+- `debug-native-logs` 或 `debug-screenshot` 失败时，必须原样报告命令和错误，不得编造兜底结论
+
 ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
 
 AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报错，**必须牢记以下框架特性**：
@@ -187,6 +213,7 @@ https://quicktvui.com
 
 - 图片组件是 `qt-image`，不是 `qt-img`、`<img>`
 - 文字必须用 `<qt-text>` 或 `<span>`，不能用 `<p>`、`<h1>`~`<h6>`、`<label>` 等 HTML 标签
+- 所有标签和组件都必须显式声明 `width` 和 `height`（px），包括 `<div>`、`<span>`、`<qt-text>`、`<qt-image>`、`<qt-view>` 以及所有 `qt-*` 标签
 - 容器用 `<div>`、`<qt-view>`、`<qt-row>`、`<qt-column>`，不能用 `<section>`、`<main>`、`<article>` 等语义标签
 - 按钮用 `<qt-button>` 或可获焦的 `<div>`，不能用 `<button>`
 
@@ -240,6 +267,7 @@ https://quicktvui.com
 其他 CSS 规则：
 
 - **CRITICAL: NO `auto` sizing**. All elements MUST have explicit `px` values.
+- **CRITICAL: 所有标签和组件都必须显式设置 `width` 和 `height`（px）**。包括 `div`、`span`、`qt-text`、`qt-image`、`qt-view` 以及所有其他 `qt-*` 组件，不能依赖内容自适应或父容器撑开。
 - **CRITICAL: NO `alert()`**. Use `useESToast().showToast()` instead.
 - **CRITICAL: NO `e.preventDefault()`** or `e.stopPropagation()`. These do not exist in the native event system.
 - **CRITICAL: NO `window` or `document` (DOM) objects**. The runtime is not a browser.
@@ -581,6 +609,8 @@ Events: `focus(isFocused: boolean)`, `click()`
 
 ### qt-text
 
+**强制规则**：生成代码时，所有标签和组件都必须显式声明 `width` 和 `height`，`qt-text` 只是最常见的易错项，不要依赖 `autoWidth` / `autoHeight`、文案内容或父容器自动撑开。
+
 ```vue
 <qt-text
   text="标题"

package/rules/GEMINI.md

@@ -1,6 +1,6 @@
 ---
 name: GEMINI.md
-version: 1.1.13
+version: 1.1.16
 ---
 
 # GEMINI.md - QuickTVUI AI 开发指南
@@ -106,6 +106,31 @@ Hard requirements:
 - If user asks to launch a specific ES app/version/source, run:
   `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the user asks AI to inspect runtime console logs, network/exception events, Android native logs, screenshots, or current target state, AI MUST use this priority:
+
+1. Prefer connected `@quicktvui/ai-debug-mcp`
+2. If MCP is unavailable but shell/CLI is available, use `quicktvui-ai debug-*`
+3. Only ask the user to paste logs manually when both MCP and CLI paths are unavailable
+
+Required non-MCP order:
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. Resolve `clientId`
+   - use directly when only one target exists
+   - ask the user to confirm when multiple targets exist
+3. `quicktvui-ai debug-context --client-id <clientId>`
+4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+Hard requirements:
+
+- AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*` actually returned that data
+- If `debug-targets` is empty, AI MUST say that `ESDebugServer /ai/targets` is still empty
+- If `debug-native-logs` or `debug-screenshot` fails, AI MUST report the real command/error instead of inventing fallback observations
+
 ---
 
 ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
@@ -138,6 +163,7 @@ AI 在编写业务逻辑时，必须牢记以下框架特性，防止套用 Web
 *   **强制 Flex**：每个有样式的元素必须显式写 `display: flex;`。默认方向为 `flex-direction: column;`。
 *   **禁止简写**：不支持 `margin: 10px`，必须写 `margin-top: 10px;` 等。
 *   **禁止相对单位**：只允许 `px`，不支持 `%`, `auto`, `vh/vw`, `rem`。
+*   **所有标签和组件强制宽高**：所有标签和组件都必须显式声明 `width` 和 `height`（px），包括 `div`、`span`、`qt-text`、`qt-image`、`qt-view` 以及所有 `qt-*` 组件，不能依赖文字内容、父容器或自动撑开。
 
 ---
 
@@ -168,4 +194,5 @@ AI 必须了解 Vue 组件与 Java Native 层的对应关系，避免查阅已
 * **Back 键**：必须命名为 `onBackPressed`。
 * **生命周期**：必须命名为 `onESCreate`, `onESResume`, `onESDestroy` 等。
 * **焦点**：页面必须有元素设置 `:autofocus="true"`，且容器需设置 `:clipChildren="false"`。
+* **尺寸**：所有标签和组件都必须显式设置 `width` 和 `height`，`qt-text` 只是高频易错例子。
 * **路由**：使用 `useESRouter()`。