@quicktvui/ai 1.1.18 → 1.1.19

package/package.json

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

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

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

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

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

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

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

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

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

package/rules/.clinerules

@@ -104,12 +104,13 @@ AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*`
 
 ## Plugin Server Workflow (CRITICAL)
 
-When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`:
 
 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. Otherwise use `quicktvui-ai plugin-*`
@@ -126,7 +127,10 @@ Required order:
 3. Read current state:
    - `plugin_server_status`
    - or `quicktvui-ai plugin-status --device <serial>`
-4. Upload So zip:
+4. If the task is to inspect recent runtime load state or latest error info after quick-app/plugin load:
+   - `quicktvui_runtime_status`
+   - or `quicktvui-ai runtime-status --device <serial>`
+5. Upload So zip:
    - choose the archive matching `ro.product.cpu.abi` on the service-corresponding device
    - `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
 5. Upload plugin APK:
@@ -136,6 +140,7 @@ Hard requirements:
 
 - Runtime endpoint behavior overrides markdown docs.
 - Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side install, or a startup failure, query `quicktvui_runtime_status` / `runtime-status` and report the package key plus `__debug__`.
 - Resolve plugin server address in this order:
   - explicit `baseUrl` / `--plugin-base-url`
   - adb-connected device service address
@@ -154,7 +159,9 @@ Hard requirements:
 - After uploading a newly rebuilt or replaced plugin package, restart the host/runtime process before validating page-side usage or startup; the running host does not hot-swap new plugin bytes automatically.
 - Consult:
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 
 ## Plugin Scaffold Workflow (CRITICAL)

package/rules/.cursorrules

@@ -104,12 +104,13 @@ AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*`
 
 ## Plugin Server Workflow (CRITICAL)
 
-When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`:
 
 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. Otherwise use `quicktvui-ai plugin-*`
@@ -126,7 +127,10 @@ Required order:
 3. Read current state:
    - `plugin_server_status`
    - or `quicktvui-ai plugin-status --device <serial>`
-4. Upload So zip:
+4. If the task is to inspect recent runtime load state or latest error info after quick-app/plugin load:
+   - `quicktvui_runtime_status`
+   - or `quicktvui-ai runtime-status --device <serial>`
+5. Upload So zip:
    - choose the archive matching `ro.product.cpu.abi` on the service-corresponding device
    - `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
 5. Upload plugin APK:
@@ -136,6 +140,7 @@ Hard requirements:
 
 - Runtime endpoint behavior overrides markdown docs.
 - Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side install, or a startup failure, query `quicktvui_runtime_status` / `runtime-status` and report the package key plus `__debug__`.
 - Resolve plugin server address in this order:
   - explicit `baseUrl` / `--plugin-base-url`
   - adb-connected device service address
@@ -154,7 +159,9 @@ Hard requirements:
 - After uploading a newly rebuilt or replaced plugin package, restart the host/runtime process before validating page-side usage or startup; the running host does not hot-swap new plugin bytes automatically.
 - Consult:
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 
 ## Plugin Scaffold Workflow (CRITICAL)

package/rules/.docs/zh-CN/tool/api/plugin-server-api.md

@@ -25,6 +25,7 @@ http://<tv-ip>:36366/api/v1
 6. `abi` 只在上传 So 时才需要。CLI / MCP 如果在 `uploadSo` 时未显式传 `abi`，会尝试读取当前插件服务对应设备的 `ro.product.cpu.abi` 并按需补齐；`check` / `hello` / `status` / `uploadPlugin` 不会主动查询 ABI。
 7. `uploadPlugin` 返回成功，只代表插件包已上传到插件服务缓存；如果 Vue 页面需要实际使用该插件，还必须在页面侧通过 `useESPlugin()` 监听并调用 `installPlugin({ pkg })`，不能把“上传成功”误当成“页面已安装完成”。
 8. 上传新的插件包到服务后，当前宿主 / runtime 进程不会自动热更新到新字节码；复测启动、注册或页面接入前，必须先重启宿主进程。
+9. 当快应用、插件或页面刚刚发起加载后，若需要继续查看最近一次加载状态与错误信息，应优先查询 `/status` 中的 `data.loadStatus`，推荐参考同目录 `runtime-status.md`。
 
 ## 二、开启服务
 
@@ -70,15 +71,30 @@ quicktvui-ai plugin-enable-api --device <serial>
     "soList": [
       "eskit.so.player.v1"
     ],
-    "pluginList": []
+    "pluginList": [],
+    "loadStatus": {
+      "es.extscreen.runtime.error": {
+        "status": "SUCCESS",
+        "message": ""
+      },
+      "__debug__": {
+        "status": "ERROR",
+        "message": "网络不可用，请检查网络后重试"
+      }
+    }
   }
 }
 ```
 
 说明：
 
-1. `soList` / `pluginList` 反映的是当前服务返回的数据，不应脑补额外状态。
+1. `soList` / `pluginList` / `loadStatus` 都以当前服务实际返回为准，不应脑补额外状态。
 2. 即使上传插件成功，`pluginList` 也可能仍为空。
+3. `loadStatus` 用于表达最近一次加载状态映射，key 一般是包名或 `__debug__`。
+4. 当快应用加载失败、页面没起来、或插件安装后仍不可用时，AI 应优先继续分析 `loadStatus` 中对应项的 `status` / `message`。
+5. QuickTVUI AI 推荐命令：
+   - CLI：`quicktvui-ai runtime-status --device <serial>`
+   - MCP：`quicktvui_runtime_status`
 
 ### 3.3 `POST /uploadSo`
 

package/rules/.docs/zh-CN/tool/api/runtime-status.md

@@ -0,0 +1,95 @@
+---
+title: Runtime Status API
+lang: zh-CN
+---
+
+# 运行状态接口
+
+## 一、用途
+
+当快应用已经发起加载、插件已经上传或安装、页面启动失败，且 AI 需要继续查看最近一次加载状态与错误信息时，应读取插件服务的 `/status` 返回中的 `data.loadStatus`。
+
+典型场景：
+
+1. `run-dev` / `run-esapp` 后页面没有正常起来
+2. 插件安装成功回调后，模块 / 组件仍未可用
+3. 需要确认最近一次加载到底是 `SUCCESS` 还是 `ERROR`
+4. 需要拿到最近一次失败消息继续诊断
+
+## 二、接口信息
+
+```http
+POST /api/v1/status
+```
+
+说明：
+
+1. 该接口是 `POST`，不要用 `GET`
+2. 根路径默认是 `http://<tv-ip>:36366/api/v1`
+3. 在调用前，应先通过 Toolkit 广播打开 `RESTFUL_API`
+
+## 三、关键字段
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `soList` | array | 当前已加载的 So 键列表 |
+| `pluginList` | array | 当前已加载的插件包名列表 |
+| `loadStatus` | object | 最近一次加载状态映射，key 一般是包名或 `__debug__` |
+
+`loadStatus` 子字段：
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| `status` | string | `SUCCESS` 或 `ERROR` |
+| `message` | string | 最近一次错误信息；成功时通常为空字符串 |
+
+## 四、建议读取方式
+
+优先使用 QuickTVUI AI 工具，而不是直接手写 curl。
+
+### 4.1 CLI
+
+```bash
+quicktvui-ai runtime-status --device <serial>
+```
+
+### 4.2 MCP
+
+- `quicktvui_runtime_status`
+
+## 五、判断规则
+
+1. `plugin-status` / `plugin_server_status` 更适合读原始 `/status`
+2. `runtime-status` / `quicktvui_runtime_status` 更适合聚焦 `loadStatus`
+3. 分析时应同时看：
+   - 业务包名对应项
+   - `__debug__`
+4. 如果 `message` 非空，应优先把它当成最近一次加载失败的直接线索
+5. `status.pluginList` 为空，不代表 `loadStatus` 也没有信息
+
+## 六、示例
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "soList": [
+      "demo_arm64-v8a"
+    ],
+    "pluginList": [
+      "eskit.plugin.test"
+    ],
+    "loadStatus": {
+      "es.extscreen.runtime.error": {
+        "status": "SUCCESS",
+        "message": ""
+      },
+      "__debug__": {
+        "status": "ERROR",
+        "message": "网络不可用，请检查网络后重试"
+      }
+    }
+  }
+}
+```

package/rules/.docs/zh-CN/tool/cli/plugin-server.md

@@ -45,7 +45,24 @@ quicktvui-ai plugin-check --device <serial>
 quicktvui-ai plugin-status --device <serial>
 ```
 
-### 2.4 上传 So
+说明：
+
+1. 该命令适合读取原始 `/status`
+2. 重点关注 `soList`、`pluginList` 与原始 `data` 结构
+
+### 2.4 查看最近加载状态与错误信息
+
+```bash
+quicktvui-ai runtime-status --device <serial>
+```
+
+说明：
+
+1. 该命令同样读取 `/status`，但会把 `data.loadStatus` 作为重点输出字段
+2. 当快应用刚加载、插件刚安装、页面没起来、或需要继续看最近一次错误信息时，应优先使用这个命令
+3. 重点关注具体包名对应项，以及 `__debug__` 下的 `status` / `message`
+
+### 2.5 上传 So
 
 ```bash
 quicktvui-ai plugin-upload-so \
@@ -61,7 +78,7 @@ quicktvui-ai plugin-upload-so \
 2. 建议总是同时传 `--tag` 和 `--pkg`
 3. So zip 必须和设备 ABI 一致
 
-### 2.5 上传插件 APK
+### 2.6 上传插件 APK
 
 ```bash
 quicktvui-ai plugin-upload-plugin \
@@ -76,7 +93,7 @@ quicktvui-ai plugin-upload-plugin \
 2. 如果上传的是新构建或覆盖上传的插件包，复测前必须先重启宿主 / runtime 进程
 3. 宿主重启后，再继续做 Vue 页面安装、注册校验或启动验证
 
-### 2.6 Vue 侧安装插件
+### 2.7 Vue 侧安装插件
 
 `plugin-upload-plugin` 成功，只代表插件包已经进入插件服务缓存；如果页面里需要真正使用插件，还必须在 Vue 侧补齐安装流程。
 

package/rules/.docs/zh-CN/tool/cli/runtime-status.md

@@ -0,0 +1,49 @@
+---
+title: Runtime Status
+lang: zh-CN
+---
+
+# 运行状态 CLI
+
+## 一、用途
+
+当快应用加载后页面未正常起来、插件安装后组件/模块仍未注册、或用户明确要求查看最近一次加载状态与错误信息时，优先使用：
+
+```bash
+quicktvui-ai runtime-status --device <serial>
+```
+
+这个命令底层仍调用 `/api/v1/status`，但会把 `data.loadStatus` 作为重点输出字段，方便 AI 继续判断最近一次加载是成功还是失败。
+
+## 二、推荐时机
+
+1. `quicktvui-ai run-dev` / `run-esapp` 之后
+2. `plugin-upload-plugin` 或页面侧 `installPlugin({ pkg })` 之后
+3. 页面空白、组件未注册、模块调用失败之后
+4. 设备日志以外，还需要再看服务侧最近一次加载状态时
+
+## 三、命令示例
+
+```bash
+quicktvui-ai runtime-status --device <serial>
+```
+
+也可以显式指定服务地址：
+
+```bash
+quicktvui-ai runtime-status --plugin-base-url http://<tv-ip>:36366
+```
+
+## 四、重点字段
+
+1. `loadStatus.<pkg>.status`
+2. `loadStatus.<pkg>.message`
+3. `loadStatus.__debug__.status`
+4. `loadStatus.__debug__.message`
+
+## 五、判断规则
+
+1. 这个命令适合查最近一次加载状态与错误信息
+2. `plugin-status` 更适合读取原始 `/status` 缓存状态
+3. 如果 `pluginList` 为空，也不能跳过 `loadStatus`
+4. 如果刚重传了新插件版本，复测前应先重启宿主 / runtime 进程，再重新查询运行状态

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

@@ -1,6 +1,6 @@
 ---
 name: copilot-instructions.md
-version: 1.1.18
+version: 1.1.19
 ---
 
 # copilot-instructions.md - QuickTVUI AI Development Guide
@@ -70,12 +70,13 @@ AI MUST NOT say it has checked logs/screenshots unless one of those MCP/CLI read
 
 ## Plugin Server Workflow (CRITICAL)
 
-When the task is to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`), AI MUST use this priority:
+When the task is to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`, AI MUST use this priority:
 
 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. Otherwise use `quicktvui-ai plugin-*`
@@ -92,6 +93,9 @@ Required order:
 - Read current state:
   - `plugin_server_status`
   - or `quicktvui-ai plugin-status --device <serial>`
+- If the task is to inspect recent runtime load state or latest error info after quick-app/plugin load:
+  - `quicktvui_runtime_status`
+  - or `quicktvui-ai runtime-status --device <serial>`
 - Resolve plugin server address:
   - explicit `baseUrl` / `--plugin-base-url`
   - adb-connected device service address
@@ -108,6 +112,7 @@ Hard requirements:
 
 - Runtime endpoint behavior overrides markdown docs.
 - Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side install, or a startup failure, query `quicktvui_runtime_status` / `runtime-status` and report the package key plus `__debug__`.
 - If AI is working inside the `quicktvui-ai` repo and finds doc/runtime drift, AI MUST update the docs.
 - `uploadSo` currently has `pkg` / `tag` drift. AI SHOULD send both fields and trust successful `data.tag`.
 - Default demo identifiers:
@@ -120,7 +125,9 @@ Hard requirements:
 - After uploading a newly rebuilt or replaced plugin package, restart the host/runtime process before validating page-side usage or startup; the running host does not hot-swap new plugin bytes automatically.
 - Consult:
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 
 ## Plugin Scaffold Workflow (CRITICAL)

package/rules/.windsurfrules

@@ -104,12 +104,13 @@ AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*`
 
 ## Plugin Server Workflow (CRITICAL)
 
-When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`:
 
 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. Otherwise use `quicktvui-ai plugin-*`
@@ -126,7 +127,10 @@ Required order:
 3. Read current state:
    - `plugin_server_status`
    - or `quicktvui-ai plugin-status --device <serial>`
-4. Upload So zip:
+4. If the task is to inspect recent runtime load state or latest error info after quick-app/plugin load:
+   - `quicktvui_runtime_status`
+   - or `quicktvui-ai runtime-status --device <serial>`
+5. Upload So zip:
    - choose the archive matching `ro.product.cpu.abi` on the service-corresponding device
    - `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
 5. Upload plugin APK:
@@ -136,6 +140,7 @@ Hard requirements:
 
 - Runtime endpoint behavior overrides markdown docs.
 - Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side install, or a startup failure, query `quicktvui_runtime_status` / `runtime-status` and report the package key plus `__debug__`.
 - Resolve plugin server address in this order:
   - explicit `baseUrl` / `--plugin-base-url`
   - adb-connected device service address
@@ -154,7 +159,9 @@ Hard requirements:
 - After uploading a newly rebuilt or replaced plugin package, restart the host/runtime process before validating page-side usage or startup; the running host does not hot-swap new plugin bytes automatically.
 - Consult:
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 
 ## Plugin Scaffold Workflow (CRITICAL)

package/rules/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 name: AGENTS.md
-version: 1.1.18
+version: 1.1.19
 ---
 
 # AGENTS.md - QuickTVUI AI Development Guide
@@ -140,15 +140,17 @@ Hard requirements:
 - 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.
+- When the user is asking about recent quick-app load state, startup failure, or the latest runtime-side error message after load, AI SHOULD also query `quicktvui_runtime_status` / `quicktvui-ai runtime-status` and report the relevant package key plus `__debug__` from `data.loadStatus`.
 
 ## Plugin Server Workflow (CRITICAL)
 
-When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`), AI MUST use this priority:
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`, AI MUST use this priority:
 
 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. If MCP is unavailable but shell/CLI execution is available, AI MUST use `quicktvui-ai plugin-*`.
@@ -165,22 +167,26 @@ Required workflow:
 3. Read current state:
    - MCP: `plugin_server_status`
    - CLI: `quicktvui-ai plugin-status --device <serial>`
-4. Resolve plugin server address:
+4. If the user needs recent runtime load state or latest error info after quick-app/plugin load:
+   - MCP: `quicktvui_runtime_status`
+   - CLI: `quicktvui-ai runtime-status --device <serial>`
+5. Resolve plugin server address:
    - If `baseUrl` / `--plugin-base-url` is explicitly provided, use it
    - Otherwise, if adb already has a connected target, use that target's plugin service address first
    - If the target host cannot be inferred, use adb port forward and `http://127.0.0.1:36366`
    - If multiple adb devices are connected, AI MUST ask the user to choose `serial` or provide service IP / `baseUrl`
    - If no adb-connected device exists, AI MUST ask the user for service IP / `baseUrl`, and MUST NOT invent or hardcode a developer-specific TV IP
-5. Upload So zip:
+6. Upload So zip:
    - choose the zip whose ABI matches `ro.product.cpu.abi` on the device that serves the current plugin endpoint
    - CLI: `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
-6. Upload plugin APK:
+7. Upload plugin APK:
    - CLI: `quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
 
 Hard requirements:
 
 - AI MUST treat live endpoint behavior as the source of truth over markdown docs.
 - AI MUST probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side plugin install, or a startup failure, AI SHOULD query `quicktvui_runtime_status` / `runtime-status` and report the relevant package key plus `__debug__`.
 - If AI is working inside the `quicktvui-ai` repository and docs disagree with the live interface, AI MUST update the docs to match the runtime behavior.
 - `uploadSo` currently has observed `pkg` / `tag` drift. AI SHOULD send both `pkg` and `tag`, and treat successful response field `data.tag` as authoritative.
 - The default demo identifiers are:
@@ -193,7 +199,9 @@ Hard requirements:
 - Uploading a newly rebuilt or replaced plugin package to the plugin service does NOT hot-swap the already running host/runtime process. Before validating startup, registration, or page-side usage after a new plugin upload, AI MUST restart the host/runtime process so the new plugin bytes can take effect.
 - AI SHOULD consult these packaged docs before generating commands or guidance:
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 ## Plugin Scaffold Workflow (CRITICAL)
 

package/rules/AI_HANDOFF.md

@@ -1,6 +1,6 @@
 ---
 name: AI_HANDOFF.md
-version: 1.1.18
+version: 1.1.19
 ---
 
 # QuickTVUI AI 集成 - 工作交接文档
@@ -104,22 +104,26 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 3. 读取状态
    - MCP：`plugin_server_status`
    - CLI：`quicktvui-ai plugin-status --device <serial>`
-4. 解析插件服务地址
+4. 如果任务需要最近一次 runtime 加载状态与错误信息
+   - MCP：`quicktvui_runtime_status`
+   - CLI：`quicktvui-ai runtime-status --device <serial>`
+5. 解析插件服务地址
    - 如果显式传了 `baseUrl` / `--plugin-base-url`，优先使用该地址
    - 否则，如果 adb 已连接设备，先尝试使用该设备的插件服务地址
    - 如果无法从目标设备推断 host，则改用 adb 端口转发和 `http://127.0.0.1:36366`
    - 如果同时连接了多台 adb 设备，后续 AI 必须要求用户选择 `serial` 或提供服务 IP / `baseUrl`
    - 如果没有任何 adb 已连接设备，后续 AI 必须向用户索要服务 IP / `baseUrl`，不得脑补或写死某个开发者自己的电视 IP
-5. 上传 So
+6. 上传 So
    - 必须先根据当前插件服务对应设备的 `ro.product.cpu.abi` 选择 zip
    - CLI：`quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
-6. 上传插件 APK
+7. 上传插件 APK
    - CLI：`quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
 
 接手注意事项：
 
 - 文档与接口返回不一致时，统一以接口真实返回为准
 - `/hello`、`/status`、`/uploadSo`、`/uploadPlugin` 必须使用 `POST` 探测，不能用 `GET` 判断服务是否可用
+- `/status` 中的 `data.loadStatus` 是最近一次 runtime 加载状态与错误信息的权威来源；接手后若要继续排查加载失败，应优先调用 `quicktvui_runtime_status` / `quicktvui-ai runtime-status`，并同时报告相关包名项与 `__debug__`
 - 如果此时正在 `quicktvui-ai` 仓库中改规则或文档，必须同步把差异写回文档
 - `uploadSo` 目前存在 `pkg` / `tag` 漂移，调用时应尽量同时传这两个字段
 - 测试 Demo 固定标识：
@@ -129,7 +133,9 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 - 重新上传新的插件包后，接手方在复测前必须先重启宿主 / runtime 进程；当前进程不会自动热更新到新插件字节码
 - 优先参考包内文档：
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 ## 插件脚手架工作流 (CRITICAL)
 

package/rules/CLAUDE.md

@@ -1,6 +1,6 @@
 ---
 name: CLAUDE.md
-version: 1.1.18
+version: 1.1.19
 ---
 
 # QuickTVUI - AI 开发指南
@@ -139,15 +139,17 @@ Hard requirements:
 - AI 未通过 MCP 或 `quicktvui-ai debug-*` 实际读取到数据前，不得声称自己已经检查过运行时日志、native logs 或截图
 - `debug-targets` 为空时，必须明确说明当前 `ESDebugServer /ai/targets` 还没有可读 target
 - `debug-native-logs` 或 `debug-screenshot` 失败时，必须原样报告命令和错误，不得编造兜底结论
+- 如果用户要查最近一次快应用加载状态、启动失败，或最近一次 runtime 侧错误信息，AI 还应优先补查 `quicktvui_runtime_status` / `quicktvui-ai runtime-status`，并同时报告相关包名项与 `__debug__`
 
 ## Plugin Server Workflow (CRITICAL)
 
-当用户要求 AI 检查、上传或联调电视插件服务接口（`/hello`、`/status`、`/uploadSo`、`/uploadPlugin`）时，AI 必须遵循以下优先级：
+当用户要求 AI 检查、上传或联调电视插件服务接口（`/hello`、`/status`、`/uploadSo`、`/uploadPlugin`），或要求查看最近一次 runtime 加载状态与错误信息时，AI 必须遵循以下优先级：
 
 1. 优先使用已连接的 `quicktvui-ai-mcp` 插件工具：
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai plugin-*`
@@ -164,22 +166,26 @@ Hard requirements:
 3. 读取当前状态
    - MCP：`plugin_server_status`
    - CLI：`quicktvui-ai plugin-status --device <serial>`
-4. 解析插件服务地址
+4. 如果任务需要最近一次 runtime 加载状态或错误信息
+   - MCP：`quicktvui_runtime_status`
+   - CLI：`quicktvui-ai runtime-status --device <serial>`
+5. 解析插件服务地址
    - 如果显式传了 `baseUrl` / `--plugin-base-url`，优先使用该地址
    - 否则，如果 adb 已连接设备，先尝试使用该设备的插件服务地址
    - 如果无法从目标设备推断 host，则改用 adb 端口转发和 `http://127.0.0.1:36366`
    - 如果同时连接了多台 adb 设备，AI 必须要求用户选择 `serial` 或提供服务 IP / `baseUrl`
    - 如果没有任何 adb 已连接设备，AI 必须向用户索要服务 IP / `baseUrl`，不得脑补或写死某个开发者自己的电视 IP
-5. 上传 So
+6. 上传 So
    - 必须根据当前插件服务对应设备的 `ro.product.cpu.abi` 选择匹配的 zip
    - CLI：`quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
-6. 上传插件 APK
+7. 上传插件 APK
    - CLI：`quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
 
 硬约束：
 
 - 运行中接口返回永远优先于 markdown 文档。
 - `/hello`、`/status`、`/uploadSo`、`/uploadPlugin` 必须使用 `POST` 探测，不能用 `GET` 判断服务是否可用。
+- `/status` 中的 `data.loadStatus` 是最近一次 runtime 加载状态与错误信息的权威来源。执行 `run-dev`、`run-esapp`、页面侧安装插件、或启动失败后，AI 应优先查询 `quicktvui_runtime_status` / `runtime-status`，并同时报告相关包名项与 `__debug__`。
 - 如果 AI 正在 `quicktvui-ai` 仓库内工作，且文档与实机接口不一致，必须回写文档。
 - `uploadSo` 目前存在 `pkg` / `tag` 字段漂移，AI 应同时传 `pkg` 和 `tag`，成功后以返回的 `data.tag` 为准。
 - 默认测试标识固定为：
@@ -192,7 +198,9 @@ Hard requirements:
 - 重新上传新的插件包后，当前宿主 / runtime 进程不会自动热更新到新字节码；在重新验证启动、注册或页面接入之前，AI 必须先重启宿主 / runtime 进程。
 - 生成命令或说明前，应优先查阅以下包内文档：
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 ## Plugin Scaffold Workflow (CRITICAL)
 

package/rules/GEMINI.md

@@ -1,6 +1,6 @@
 ---
 name: GEMINI.md
-version: 1.1.18
+version: 1.1.19
 ---
 
 # GEMINI.md - QuickTVUI AI 开发指南
@@ -130,15 +130,17 @@ 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
+- When the task is to inspect recent quick-app load state, startup failure, or the latest runtime-side error message after load, AI SHOULD also query `quicktvui_runtime_status` / `quicktvui-ai runtime-status` and report the relevant package key plus `__debug__` from `data.loadStatus`
 
 ## Plugin Server Workflow (CRITICAL)
 
-When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`:
 
 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
    - `plugin_server_check`
    - `plugin_server_hello`
    - `plugin_server_status`
+   - `quicktvui_runtime_status`
    - `plugin_upload_so`
    - `plugin_upload_plugin`
 2. Otherwise use `quicktvui-ai plugin-*`
@@ -155,22 +157,26 @@ Required order:
 3. Read current state
    - MCP: `plugin_server_status`
    - CLI: `quicktvui-ai plugin-status --device <serial>`
-4. Resolve plugin server address
+4. If the user needs recent runtime load state or latest error info after quick-app/plugin load
+   - MCP: `quicktvui_runtime_status`
+   - CLI: `quicktvui-ai runtime-status --device <serial>`
+5. Resolve plugin server address
    - If `baseUrl` / `--plugin-base-url` is explicitly provided, use it
    - Otherwise, if adb already has a connected target, use that target's plugin service address first
    - If the target host cannot be inferred, use adb port forward and `http://127.0.0.1:36366`
    - If multiple adb devices are connected, AI MUST ask the user to choose `serial` or provide service IP / `baseUrl`
    - If no adb-connected device exists, AI MUST ask the user for service IP / `baseUrl`, and MUST NOT invent a developer-specific TV IP
-5. Upload So zip
+6. Upload So zip
    - choose the archive that matches `ro.product.cpu.abi` on the device behind the current plugin service
    - CLI: `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
-6. Upload plugin APK
+7. Upload plugin APK
    - CLI: `quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
 
 Hard requirements:
 
 - Runtime endpoint behavior overrides markdown docs.
 - Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side plugin install, or a startup failure, AI SHOULD query `quicktvui_runtime_status` / `runtime-status` and report the relevant package key plus `__debug__`.
 - When AI is editing the `quicktvui-ai` repo itself and finds doc/runtime drift, AI MUST update docs.
 - `uploadSo` currently shows `pkg` / `tag` drift. AI SHOULD send both `pkg` and `tag`, and trust `data.tag` in successful responses.
 - Default demo identifiers:
@@ -183,7 +189,9 @@ Hard requirements:
 - Uploading a newly rebuilt or replaced plugin package does NOT hot-swap the already running host/runtime process. Before validating startup, registration, or page-side usage after a new upload, AI MUST restart the host/runtime process.
 - AI SHOULD consult:
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/runtime-status.md`
   - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
 
 ## Plugin Scaffold Workflow (CRITICAL)