@quicktvui/ai 1.1.14 → 1.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicktvui/ai",
-  "version": "1.1.14",
+  "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.14
+version: 1.1.16
 ---
 
 # 创建 QuickTVUI 组件

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: lookup-css.md
-version: 1.1.14
+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
@@ -83,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)
 

package/rules/.cursorrules

@@ -1,6 +1,6 @@
 ---
 name: .cursorrules
-version: 0.6.1
+version: 1.1.14
 ---
 
 # .cursorrules - QuickTVUI AI Development Guide
@@ -83,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)
 

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

@@ -1,6 +1,6 @@
 ---
 name: copilot-instructions.md
-version: 1.1.14
+version: 1.1.16
 ---
 
 # copilot-instructions.md - QuickTVUI AI Development Guide
@@ -49,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)
 

package/rules/.windsurfrules

@@ -1,6 +1,6 @@
 ---
 name: .windsurfrules
-version: 0.6.1
+version: 1.1.14
 ---
 
 # .windsurfrules - QuickTVUI AI Development Guide
@@ -83,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)
 

package/rules/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 name: AGENTS.md
-version: 1.1.14
+version: 1.1.16
 ---
 
 # AGENTS.md - QuickTVUI AI Development Guide
@@ -115,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**:

package/rules/AI_HANDOFF.md

@@ -1,6 +1,6 @@
 ---
 name: AI_HANDOFF.md
-version: 1.1.14
+version: 1.1.16
 ---
 
 # QuickTVUI AI 集成 - 工作交接文档
@@ -61,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.14
+version: 1.1.16
 ---
 
 # QuickTVUI - AI 开发指南
@@ -115,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 开发习惯导致严重报错，**必须牢记以下框架特性**：

package/rules/GEMINI.md

@@ -1,6 +1,6 @@
 ---
 name: GEMINI.md
-version: 1.1.14
+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)