@quicktvui/ai 1.1.16 → 1.1.19

package/rules/CLAUDE.md

@@ -1,6 +1,6 @@
 ---
 name: CLAUDE.md
-version: 1.1.16
+version: 1.1.19
 ---
 
 # QuickTVUI - AI 开发指南
@@ -139,6 +139,136 @@ 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`），或要求查看最近一次 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-*`
+3. 只有 MCP 和 CLI 都不可用时，才允许退回到手工 `adb` + `curl`
+
+推荐执行顺序：
+
+1. 先打开 Toolkit RESTful API
+   - CLI：`quicktvui-ai plugin-enable-api --device <serial>`
+   - 手工兜底：`adb -s <serial> shell am broadcast -a "eskit.sdk.core.ACTION_TOOLKIT_SETTING" --es "RESTFUL_API" "true"`
+2. 检查服务是否 ready
+   - MCP：`plugin_server_check`
+   - CLI：`quicktvui-ai plugin-check --device <serial>`
+3. 读取当前状态
+   - MCP：`plugin_server_status`
+   - CLI：`quicktvui-ai plugin-status --device <serial>`
+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
+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>`
+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` 为准。
+- 默认测试标识固定为：
+  - So 包名 / tag：`eskit.so.ffmpeg.command`
+  - 插件包名：`eskit.plugin.imagequality`
+- ABI 选择必须与当前插件服务对应设备的 `ro.product.cpu.abi` 一致，但只有上传 So 时才需要解析；若未显式传 `abi`，应优先让 CLI / MCP 在上传时按需补齐。
+- 未收到 MCP 或 CLI 的成功响应前，不得宣称上传成功。
+- 即使 `uploadPlugin` 返回 `registered: true`，`status.pluginList` 也可能仍为空；AI 必须如实说明，不得自行脑补安装状态。
+- `uploadPlugin` 成功或 `registered: true` 只代表插件包已经上传到插件服务，不代表 Vue 页面已经可直接使用；如果任务要求在页面里实际调用插件，AI 还必须补齐 Vue 侧安装逻辑。
+- 重新上传新的插件包后，当前宿主 / 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)
+
+当用户要求 AI 创建、更新、打包 Android 插件工程，或生成原生模块 / 原生组件时，AI 必须遵循以下优先级：
+
+1. 优先使用已连接的 `quicktvui-ai-mcp`：
+   - `plugin_project_create`
+   - `plugin_project_build`
+   - `plugin_module_create`
+   - `plugin_component_create`
+2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai`：
+   - `plugin-create-project`
+   - `plugin-build`
+   - `plugin-create-module`
+   - `plugin-create-component`
+3. 只有 MCP 和 CLI 都不可用时，才允许手工创建或修改脚手架。
+
+决策规则：
+
+1. 工程初始化 / 更新 / 打包：使用 `plugin_project_create` / `plugin_project_build`
+2. 无独立原生 UI 的能力：使用 `plugin_module_create`
+3. 有原生 View、属性、事件或函数派发的能力：使用 `plugin_component_create`
+
+硬约束：
+
+- 生成前应优先查阅以下包内文档：
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-project.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-module.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-component.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
+  - `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
+- 源码真值来自 `.source/sdk/base/...`，真实接口固定为：
+  - `com.quicktvui.sdk.base.module.IEsModule`
+  - `com.quicktvui.sdk.base.component.IEsComponent`
+  - `com.quicktvui.sdk.base.component.IEsComponentView`
+  - `com.quicktvui.sdk.base.component.EsComponentAttribute`
+- 脚手架结构默认仍以 `.source/sdk/base/...` 为准，但目标设备运行时日志永远优先于默认命名空间。
+- 如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或启动阶段提示缺失 `com.quicktvui.sdk.base.*` 相关类，AI 必须立刻把这视为运行时兼容性问题，而不是继续重复使用默认脚手架命名空间；应改为适配设备实际存在的运行时命名空间后重新构建、重传。
+- 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，AI 必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整注册代码后重新构建、重传。
+- AI 必须区分“本地 stub 可编译”和“设备运行时类真实存在”。如果插件能编译但在设备侧因 `EsProxy` 等类缺失而启动失败，这一版插件仍然判定为失败。
+- 插件工程打包完成或插件服务上传成功，并不代表 Vue 侧已经完成安装。
+- 如果页面需要实际使用插件，AI 必须在 Vue 侧使用 `@extscreen/es3-core` 的 `useESPlugin()` 补齐安装流程。
+- AI 必须在 `onESCreate` 中添加插件监听，在 `onESDestroy` 中移除监听。
+- 对于组件型插件，AI 应优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查组件是否已注册；若未注册，应先安装插件，再渲染或调用对应组件。
+- 不允许把“插件已上传”误当成“页面里已经可直接使用”，也不允许在未监听安装完成前直接假设同步可用。
+- 如果页面收到安装成功回调后，组件或模块注册仍然短暂不可见，AI 应允许一个简短的轮询复查窗口，再决定是否判定失败。
+- 如果是为修复运行时兼容性而重新上传的新插件版本，AI 在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+- 创建工程后必须写入 `.kyy-plugin-project.json`
+- 对于长期保留或准备发布的插件工程，默认应放在 `<project-root>/plugin/<plugin-name>` 这种项目根目录下的可见目录
+- 不允许把插件工程默认放到 `.ai-test/*` 等隐藏目录或其他点前缀目录
+- 若插件工程位于子目录且工作区根目录存在 `package.json`，必须注入 `build:android-plugin`
+- 打包优先级固定为：
+  1. `npm run build:android-plugin`
+  2. `npm run build:plugin`
+  3. `npm run build`
+  4. `./gradlew assembleGeneralDebug`
+- 如果插件构建报 Android SDK 缺失，AI 必须先按通用顺序探测 SDK：`ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> 当前平台默认 SDK 目录，然后再判断环境是否真的缺失。
+- 如果已经探测到 SDK，且目标插件工程缺少 `local.properties` / `sdk.dir`，AI 可以让 CLI / MCP 只为当前开发机补齐这个本地文件。
+- AI 不得把某个开发者本机的 Android SDK 路径写进共享规则、硬编码项目配置或提交到仓库。
+- 生成 module / component 前，必须先获得明确功能描述
+- Java 包名必须使用合法包段，不能把 `kebab-case` 直接写进包路径
+- component 必须生成或更新 `docs/component/<kebab-name>.md`
+- 组件标签必须使用 `kebab-case`
+- 在 Vue `h()` 中禁止传完整 Java 包名，必须使用组件类名或约定标签名
+- 如果能定位到 `Application`，应优先补 `EsProxy.get().registerModule(...)` / `EsProxy.get().registerComponent(...)`
+- 如果文档与源码或实际实现不一致，AI 必须更新文档
 
 ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
 

package/rules/GEMINI.md

@@ -1,6 +1,6 @@
 ---
 name: GEMINI.md
-version: 1.1.16
+version: 1.1.19
 ---
 
 # GEMINI.md - QuickTVUI AI 开发指南
@@ -130,6 +130,136 @@ 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`) 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-*`
+3. Only fall back to manual `adb` + `curl` when neither MCP nor CLI execution is available
+
+Required order:
+
+1. Enable Toolkit RESTful API first
+   - CLI: `quicktvui-ai plugin-enable-api --device <serial>`
+   - Manual fallback: `adb -s <serial> shell am broadcast -a "eskit.sdk.core.ACTION_TOOLKIT_SETTING" --es "RESTFUL_API" "true"`
+2. Probe readiness
+   - MCP: `plugin_server_check`
+   - CLI: `quicktvui-ai plugin-check --device <serial>`
+3. Read current state
+   - MCP: `plugin_server_status`
+   - CLI: `quicktvui-ai plugin-status --device <serial>`
+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
+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>`
+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:
+  - So package/tag: `eskit.so.ffmpeg.command`
+  - Plugin package: `eskit.plugin.imagequality`
+- ABI selection MUST match `ro.product.cpu.abi` on the service-corresponding device, but AI SHOULD only resolve ABI when uploading So and SHOULD let CLI / MCP fill it on demand if `abi` is not explicitly provided.
+- AI MUST NOT claim upload success unless MCP or CLI returned a success payload.
+- `status.pluginList` may still be empty even after `uploadPlugin` returns `registered: true`; AI MUST report that exact state.
+- `uploadPlugin` success or `registered: true` only means the package reached plugin service storage. If the task is to use the plugin from a Vue page, AI MUST still add Vue-side installation logic.
+- 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)
+
+当用户要求 AI 创建、更新、打包 Android 插件工程，或生成原生模块 / 原生组件时，AI 必须遵循以下优先级：
+
+1. 优先使用已连接的 `quicktvui-ai-mcp`：
+   - `plugin_project_create`
+   - `plugin_project_build`
+   - `plugin_module_create`
+   - `plugin_component_create`
+2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai`：
+   - `plugin-create-project`
+   - `plugin-build`
+   - `plugin-create-module`
+   - `plugin-create-component`
+3. 只有 MCP 和 CLI 都不可用时，才允许手工创建或修改脚手架。
+
+决策规则：
+
+1. 工程初始化 / 更新 / 打包：使用 `plugin_project_create` / `plugin_project_build`
+2. 无独立原生 UI 的能力：使用 `plugin_module_create`
+3. 有原生 View、属性、事件或函数派发的能力：使用 `plugin_component_create`
+
+硬约束：
+
+- 生成前应优先查阅以下包内文档：
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-project.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-module.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-component.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
+  - `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
+- 源码真值来自 `.source/sdk/base/...`，真实接口固定为：
+  - `com.quicktvui.sdk.base.module.IEsModule`
+  - `com.quicktvui.sdk.base.component.IEsComponent`
+  - `com.quicktvui.sdk.base.component.IEsComponentView`
+  - `com.quicktvui.sdk.base.component.EsComponentAttribute`
+- 脚手架结构默认仍以 `.source/sdk/base/...` 为准，但目标设备运行时日志永远优先于默认命名空间。
+- 如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或启动阶段提示缺失 `com.quicktvui.sdk.base.*` 相关类，AI 必须把这视为运行时兼容性问题，改为适配设备实际存在的运行时命名空间后再重新构建、重传。
+- 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，AI 必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应改为匹配设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径后重新构建、重传。
+- AI 必须区分“本地 stub 可编译”和“设备运行时类真实存在”。如果插件能编译但在设备侧因 `EsProxy` 等类缺失而启动失败，这一版插件仍然判定为失败。
+- 插件工程打包完成或插件服务上传成功，并不代表 Vue 侧已经完成安装。
+- 如果页面需要实际使用插件，AI 必须在 Vue 侧使用 `@extscreen/es3-core` 的 `useESPlugin()` 补齐安装流程。
+- AI 必须在 `onESCreate` 中添加插件监听，在 `onESDestroy` 中移除监听。
+- 对于组件型插件，AI 应优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查组件是否已注册；若未注册，应先安装插件，再渲染或调用对应组件。
+- 不允许把“插件已上传”误当成“页面里已经可直接使用”，也不允许在未监听安装完成前直接假设同步可用。
+- 如果页面收到安装成功回调后，组件或模块注册仍然短暂不可见，AI 应允许一个简短的轮询复查窗口，再决定是否判定失败。
+- 如果是为修复运行时兼容性而重新上传的新插件版本，AI 在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+- 创建工程后必须写入 `.kyy-plugin-project.json`
+- 对于长期保留或准备发布的插件工程，默认应放在 `<project-root>/plugin/<plugin-name>` 这种项目根目录下的可见目录
+- 不允许把插件工程默认放到 `.ai-test/*` 等隐藏目录或其他点前缀目录
+- 若插件工程位于子目录且工作区根目录存在 `package.json`，必须注入 `build:android-plugin`
+- 打包优先级固定为：
+  1. `npm run build:android-plugin`
+  2. `npm run build:plugin`
+  3. `npm run build`
+  4. `./gradlew assembleGeneralDebug`
+- 如果插件构建报 Android SDK 缺失，AI 必须先按通用顺序探测 SDK：`ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> 当前平台默认 SDK 目录，然后再判断环境是否真的缺失。
+- 如果已经探测到 SDK，且目标插件工程缺少 `local.properties` / `sdk.dir`，AI 可以让 CLI / MCP 只为当前开发机补齐这个本地文件。
+- AI 不得把某个开发者本机的 Android SDK 路径写进共享规则、硬编码项目配置或提交到仓库。
+- 生成 module / component 前，必须先获得明确功能描述
+- Java 包名必须使用合法包段，不能把 `kebab-case` 直接写进包路径
+- component 必须生成或更新 `docs/component/<kebab-name>.md`
+- 组件标签必须使用 `kebab-case`
+- 在 Vue `h()` 中禁止传完整 Java 包名，必须使用组件类名或约定标签名
+- 如果能定位到 `Application`，应优先补 `EsProxy.get().registerModule(...)` / `EsProxy.get().registerComponent(...)`
+- 如果文档与源码或实际实现不一致，AI 必须更新文档
 
 ---