@quicktvui/ai 1.1.16 → 1.1.18

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

@@ -0,0 +1,101 @@
+---
+title: Plugin Create Component
+lang: zh-CN
+---
+
+# 插件组件创建
+
+## 一、适用范围
+
+组件用于有原生 UI 的能力，例如二维码、卡片、轮播、支付入口、图片容器等。
+
+如果只是无界面能力，请改用 `plugin-create-module`。
+
+## 二、源码真值
+
+生成组件前，必须优先对照：
+
+1. `node_modules/@quicktvui/ai/rules/.source/sdk/base/sdk-base/src/main/java/com/quicktvui/sdk/base/component/IEsComponent.java`
+2. `node_modules/@quicktvui/ai/rules/.source/sdk/base/sdk-base/src/main/java/com/quicktvui/sdk/base/component/IEsComponentView.java`
+3. `node_modules/@quicktvui/ai/rules/.source/sdk/base/sdk-base/src/main/java/com/quicktvui/sdk/base/component/EsComponentAttribute.java`
+
+真实接口：
+
+```java
+com.quicktvui.sdk.base.component.IEsComponent
+com.quicktvui.sdk.base.component.IEsComponentView
+com.quicktvui.sdk.base.component.EsComponentAttribute
+```
+
+## 三、CLI 命令
+
+```bash
+quicktvui-ai plugin-create-component \
+  --project plugin/demo-plugin \
+  --description "展示二维码" \
+  --props '[{"name":"content","type":"String","description":"二维码内容"}]' \
+  --events onRendered \
+  --functions refresh
+```
+
+## 四、MCP 工具
+
+```text
+plugin_component_create
+```
+
+## 五、生成规则
+
+1. `--description` 必填
+2. 组件类名追加 `Component`
+3. View 类名追加 `View`
+4. Java 包名必须合法，不能把 `kebab-case` 直接写入包路径
+5. Vue 标签必须使用 `kebab-case`
+6. `--project` 默认应指向项目根目录下可见的 `plugin/<plugin-name>`，不要默认指向隐藏目录
+7. 默认生成 `docs/component/<name>.md`
+8. 默认不强依赖 `@ESKitAutoRegister`
+9. 默认尝试在 `Application#onCreate` 中注册 `EsProxy.get().registerComponent("com.xxx.Component")`
+10. 编译期接口由插件工程内的 `quicktvui-plugin-stubs` 模块提供；运行时依赖仍以模板工程里的 `com.extscreen.runtime:eskit:2.6.0` 为准
+
+## 六、Vue 侧安装约束
+
+组件插件生成完成、打包完成或上传成功，并不代表 Vue 页面已经可以直接渲染该组件。
+
+如果页面里要真正使用组件型插件，还必须：
+
+1. 使用 `@extscreen/es3-core` 的 `useESPlugin()`
+2. 在 `onESCreate` 中 `addListener(pluginInfo, listener)`
+3. 在 `onESDestroy` 中 `removeListener(listener)`
+4. 在组件未注册时调用 `installPlugin({ pkg })`
+5. 优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查注册状态，再决定是否渲染组件
+
+推荐参考：
+
+1. `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
+2. `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
+3. `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
+
+## 七、运行时兼容约束
+
+1. 组件骨架默认仍以 `com.quicktvui.sdk.base.component.*` 和 `EsProxy` 的源码结构为准。
+2. 但如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或提示缺失 `com.quicktvui.sdk.base.*`，必须把设备日志视为运行时命名空间兼容性的最高优先级信号。
+3. 这说明本地 stub 虽然可编译，但目标 TV 运行时并没有这套类；此时应切换运行时侧注册/导入到设备实际存在的命名空间后重新构建、重传。
+4. 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整注册实现后重新构建、重传。
+5. 页面侧安装成功回调后，如果组件注册仍短暂不可见，允许一个简短轮询复查窗口，再决定是否判定失败。
+6. 如果是为修复运行时兼容性而重新上传的新插件版本，复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+
+## 八、关键参数
+
+| 参数 | 说明 |
+| ---- | ---- |
+| `--description <text>` | 功能描述，必填 |
+| `--class-name <name>` | 显式组件类名 |
+| `--view-class-name <name>` | 显式 View 类名 |
+| `--view-base-class <name>` | View 基类 |
+| `--package-name <pkg>` | 显式包名 |
+| `--props <json|csv>` | 属性列表 |
+| `--events <json|csv>` | 事件列表 |
+| `--functions <json|csv>` | dispatchFunction 列表 |
+| `--docs-dir <path>` | 组件文档目录 |
+| `--native-tag-name <name>` | 原生标签名 |
+| `--wrapper-tag-name <name>` | 包装组件标签名 |

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

@@ -0,0 +1,88 @@
+---
+title: Plugin Create Module
+lang: zh-CN
+---
+
+# 插件模块创建
+
+## 一、适用范围
+
+模块用于无独立原生 UI 的能力封装，例如设备信息、网络能力、Toast、下载、埋点等。
+
+如果需要原生 View、属性、UI 事件，应改用 `plugin-create-component`。
+
+## 二、源码真值
+
+生成模块前，必须优先对照：
+
+1. `node_modules/@quicktvui/ai/rules/.source/sdk/base/sdk-base/src/main/java/com/quicktvui/sdk/base/module/IEsModule.java`
+2. `node_modules/@quicktvui/ai/rules/.source/sdk/base/sdk-base/src/main/java/com/quicktvui/sdk/base/core/EsProxy.java`
+
+真实接口：
+
+```java
+com.quicktvui.sdk.base.module.IEsModule
+```
+
+## 三、CLI 命令
+
+```bash
+quicktvui-ai plugin-create-module \
+  --project plugin/demo-plugin \
+  --description "展示设备信息" \
+  --methods "showInfo,getInfo"
+```
+
+## 四、MCP 工具
+
+```text
+plugin_module_create
+```
+
+## 五、生成规则
+
+1. `--description` 必填
+2. 类名使用 PascalCase，并追加 `Module`
+3. Java 包名必须合法，不能把 `kebab-case` 直接写入包路径
+4. `--project` 默认应指向项目根目录下可见的 `plugin/<plugin-name>`，不要默认指向隐藏目录
+5. 默认实现 `IEsModule`
+6. 默认不强依赖 `@ESKitAutoRegister`
+7. 默认尝试在 `Application#onCreate` 中注册 `EsProxy.get().registerModule("com.xxx.Module")`
+8. 编译期接口由插件工程内的 `quicktvui-plugin-stubs` 模块提供；运行时依赖仍以模板工程里的 `com.extscreen.runtime:eskit:2.6.0` 为准
+
+## 六、Vue 侧安装约束
+
+模块插件生成完成、打包完成或上传成功，并不代表 Vue 页面已经可以直接调用该模块。
+
+如果页面里要真正使用插件模块，还必须：
+
+1. 使用 `@extscreen/es3-core` 的 `useESPlugin()`
+2. 在 `onESCreate` 中 `addListener(pluginInfo, listener)`
+3. 在 `onESDestroy` 中 `removeListener(listener)`
+4. 在插件尚未可用时调用 `installPlugin({ pkg })`
+
+推荐参考：
+
+1. `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
+2. `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
+
+## 七、运行时兼容约束
+
+1. 模块骨架默认仍以 `com.quicktvui.sdk.base.module.IEsModule` 和 `EsProxy` 的源码结构为准。
+2. 但如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或提示缺失 `com.quicktvui.sdk.base.*`，必须把设备日志视为运行时命名空间兼容性的最高优先级信号。
+3. 这说明本地 stub 虽然可编译，但目标 TV 运行时并没有这套类；此时应切换运行时侧注册/导入到设备实际存在的命名空间后重新构建、重传。
+4. 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整注册实现后重新构建、重传。
+5. 页面侧安装成功回调后，如果模块注册仍短暂不可见，允许一个简短轮询复查窗口，再决定是否判定失败。
+6. 如果是为修复运行时兼容性而重新上传的新插件版本，复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+
+## 八、关键参数
+
+| 参数 | 说明 |
+| ---- | ---- |
+| `--description <text>` | 功能描述，必填 |
+| `--class-name <name>` | 显式类名 |
+| `--package-name <pkg>` | 显式包名 |
+| `--methods <json|csv>` | 对外暴露方法 |
+| `--register <true|false>` | 是否自动注册 |
+| `--app-file <path>` | 指定 Application 文件 |
+| `--src-root <path>` | 指定源码根目录 |

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

@@ -0,0 +1,106 @@
+---
+title: Plugin Create Project
+lang: zh-CN
+---
+
+# 插件工程创建与打包
+
+## 一、推荐入口
+
+1. 优先使用 MCP：`plugin_project_create`、`plugin_project_build`
+2. 没有 MCP 时，使用 CLI：`quicktvui-ai plugin-create-project`、`quicktvui-ai plugin-build`
+3. 只有两者都不可用时，才手工执行 `git clone` / `gradlew`
+
+## 二、创建命令
+
+```bash
+quicktvui-ai plugin-create-project plugin/demo-plugin \
+  --workspace-root . \
+  --package-name com.qtapp.plugin.demo
+```
+
+关键行为：
+
+1. 默认模板仓库：`https://gitlab01.huan.tv/weipeng/eskit-plugin-template.git`
+2. 创建成功后写入 `.kyy-plugin-project.json`
+3. 如指定 `--package-name`，会同步改清单、源码包声明和包目录
+4. 会补充本地编译支撑模块 `quicktvui-plugin-stubs`
+5. 会在 `settings.gradle` 中追加 `include ':quicktvui-plugin-stubs'`
+6. 会在 `app/build.gradle` 中追加 `compileOnly project(':quicktvui-plugin-stubs')`
+7. 若创建到子目录且工作区根有 `package.json`，会注入 `build:android-plugin`
+8. 长期保留或准备发布的插件工程，默认放到项目根目录下可见的 `plugin/` 目录，例如 `plugin/demo-plugin`
+9. 不要把插件工程默认放到 `.ai-test/*` 等隐藏目录
+
+## 三、更新模式
+
+```bash
+quicktvui-ai plugin-create-project plugin/demo-plugin --mode update
+```
+
+说明：
+
+1. `update` 仅允许用于已带 `.kyy-plugin-project.json` 的工程
+2. 非插件工程目录拒绝更新，避免误改
+
+## 四、打包命令
+
+```bash
+quicktvui-ai plugin-build plugin/demo-plugin
+```
+
+固定优先级：
+
+1. `npm run build:android-plugin`
+2. `npm run build:plugin`
+3. `npm run build`
+4. `./gradlew assembleGeneralDebug`
+
+说明：
+
+1. 模板运行时依赖仍以 `com.extscreen.runtime:eskit:2.6.0` 为准
+2. `quicktvui-plugin-stubs` 只用于补齐脚手架生成代码的编译期接口
+3. 构建前会优先从 `ANDROID_SDK_ROOT`、`ANDROID_HOME` 和当前平台默认 Android SDK 目录中自动探测 SDK
+4. 如探测到 SDK 且目标工程缺少 `local.properties` / `sdk.dir`，CLI 会在目标插件工程内自动补齐本地 `local.properties`
+5. `local.properties` 属于开发机本地文件，不应提交到共享仓库
+
+## 五、Vue 侧安装约束
+
+插件工程创建、打包或插件服务上传成功，并不代表 Vue 页面已经可以直接使用插件。
+
+如果业务页面需要真正接入插件，必须额外补齐：
+
+1. 使用 `@extscreen/es3-core` 的 `useESPlugin()`
+2. 在 `onESCreate` 中 `addListener(pluginInfo, listener)`
+3. 在 `onESDestroy` 中 `removeListener(listener)`
+4. 在插件尚未可用时调用 `installPlugin({ pkg })`
+5. 如果是组件型插件，优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查是否已注册，再决定是否安装或渲染
+
+推荐参考：
+
+1. `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
+2. `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
+3. `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
+
+## 六、运行时兼容约束
+
+1. 脚手架结构默认仍以 `.source/sdk/base/...` 为准。
+2. 但如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或启动阶段提示缺失 `com.quicktvui.sdk.base.*`，必须把设备日志视为运行时命名空间兼容性的最高优先级信号。
+3. 这通常意味着“本地 stub 能编译”但“目标 TV 运行时并没有这套类”；此时必须改为适配设备实际存在的运行时命名空间后重新构建、重传。
+4. 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整注册实现后重新构建、重传。
+5. 页面侧安装成功回调后，如果组件或模块注册仍短暂不可见，允许一个简短轮询复查窗口，再决定是否判定失败。
+6. 如果是为修复运行时兼容性而重新上传的新插件版本，复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+
+## 七、关键参数
+
+| 参数 | 说明 |
+| ---- | ---- |
+| `--mode <create|update>` | 创建或更新 |
+| `--template-repo <url>` | 自定义模板仓库 |
+| `--package-name <pkg>` | 目标 Java 包名 |
+| `--workspace-root <path>` | 工作区根目录 |
+
+## 八、注意事项
+
+1. 文档与实现不一致时，以 `quicktvui-ai-cli/lib/plugin-scaffold.js` 为准。
+2. 创建到子目录时，建议始终传 `--workspace-root`，让根脚本注入更稳定。
+3. 如果插件工程后续需要继续开发、交接或发布，优先使用项目根目录下的 `plugin/<plugin-name>` 路径。

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

@@ -0,0 +1,152 @@
+---
+title: Plugin Server
+lang: zh-CN
+---
+
+# 插件服务 CLI 工作流
+
+## 一、推荐优先级
+
+当 AI 需要联调电视插件服务时，推荐优先级如下：
+
+1. 优先使用 `quicktvui-ai-mcp`
+2. 没有 MCP 时，使用 `quicktvui-ai plugin-*`
+3. CLI 也不可用时，再退回手工 `adb` + `curl`
+
+## 二、标准命令链路
+
+### 2.1 打开 RESTful API
+
+```bash
+quicktvui-ai plugin-enable-api --device <serial>
+```
+
+说明：
+
+1. 该命令内部会发送 `eskit.sdk.core.ACTION_TOOLKIT_SETTING`
+2. 默认等价于 `RESTFUL_API=true`
+3. 如需关闭，可显式传 `--enabled false`
+
+### 2.2 检查服务可用性
+
+```bash
+quicktvui-ai plugin-check --device <serial>
+```
+
+说明：
+
+1. 会以 `POST` 探测 `/hello`、`/status`、`/uploadSo`、`/uploadPlugin`
+2. 同路径 `GET` 在实测设备上可能返回 `404`，不能据此判断服务未启动
+3. `uploadSo` / `uploadPlugin` 返回缺参 `400` 视为“接口活着”，不是失败
+
+### 2.3 查看当前状态
+
+```bash
+quicktvui-ai plugin-status --device <serial>
+```
+
+### 2.4 上传 So
+
+```bash
+quicktvui-ai plugin-upload-so \
+  --device <serial> \
+  --tag eskit.so.ffmpeg.command \
+  --pkg eskit.so.ffmpeg.command \
+  --file docs/plugin/armeabi-v7a.zip
+```
+
+说明：
+
+1. `--abi` 省略时，CLI 只会在执行 `uploadSo` 的这一刻，从当前插件服务对应设备读取 `ro.product.cpu.abi`
+2. 建议总是同时传 `--tag` 和 `--pkg`
+3. So zip 必须和设备 ABI 一致
+
+### 2.5 上传插件 APK
+
+```bash
+quicktvui-ai plugin-upload-plugin \
+  --device <serial> \
+  --pkg eskit.plugin.imagequality \
+  --file docs/plugin/plugin-general-debug.apk
+```
+
+说明：
+
+1. 上传成功只代表插件包已经进入插件服务缓存，不代表当前宿主进程已经切到新插件字节码
+2. 如果上传的是新构建或覆盖上传的插件包，复测前必须先重启宿主 / runtime 进程
+3. 宿主重启后，再继续做 Vue 页面安装、注册校验或启动验证
+
+### 2.6 Vue 侧安装插件
+
+`plugin-upload-plugin` 成功，只代表插件包已经进入插件服务缓存；如果页面里需要真正使用插件，还必须在 Vue 侧补齐安装流程。
+
+标准约束：
+
+1. 使用 `@extscreen/es3-core` 的 `useESPlugin()`
+2. 在 `onESCreate` 中 `addListener(pluginInfo, listener)`
+3. 在 `onESDestroy` 中 `removeListener(listener)`
+4. 在插件尚未可用时调用 `installPlugin({ pkg })`
+5. 如果是组件型插件，优先用 `useES().isComponentRegistered("<组件完整类名>")` 检查是否已注册，再决定是否安装或渲染
+
+推荐参考：
+
+1. `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
+2. `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
+3. `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
+
+如果上传成功但插件启动失败，应继续看设备日志；若日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy` 或缺失 `com.quicktvui.sdk.base.*`，说明问题在运行时命名空间兼容性，而不是上传链路本身。若日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，则说明插件注册入口的字节码签名与设备 runtime 不兼容，必须改成匹配设备真实 `EsProxy.get()` 签名 / 调用路径的实现，重新构建、重传，并在复测前重启宿主进程。
+
+## 三、关键参数
+
+| 参数 | 说明 |
+| ---- | ---- |
+| `--device <serial>` | 目标 adb 设备序列号 |
+| `--device-ip <ip[:port]>` | 先 `adb connect` 再执行命令 |
+| `--plugin-base-url <url>` | 显式覆盖插件服务地址；不传时 CLI 会优先自动探测 |
+| `--timeout-ms <n>` | 请求超时 |
+| `--enabled <true|false>` | `plugin-enable-api` 的值 |
+| `--tag` | So 标识 |
+| `--pkg` | So 或插件包名 |
+| `--abi` | 可选；仅在 `plugin-upload-so` 时使用，不传则按当前服务目标设备按需读取 |
+| `--file` | 本地 zip/apk 文件 |
+| `--file-name` | 覆盖上传文件名 |
+
+## 四、地址自动解析与转发行为
+
+不传 `--plugin-base-url` 时，CLI 会按下面顺序解析插件服务地址：
+
+1. 如果 adb 已连接目标设备：
+   - 优先尝试该设备的插件服务地址
+   - 若无法从目标设备推断 host，则自动使用 adb 端口转发并回落到 `http://127.0.0.1:36366`
+2. 如果同时连接了多台 adb 设备：
+   - 必须显式传 `--device <serial>`，或直接传 `--plugin-base-url`
+3. 如果没有 adb 已连接设备：
+   - 交互模式下会提示输入服务 IP / URL
+   - 非交互模式下会直接报错，要求显式传 `--plugin-base-url`
+
+如果目标是设备本地服务而本机回环地址无法直连，CLI 会自动尝试：
+
+```bash
+adb -s <serial> forward tcp:36366 tcp:36366
+```
+
+如果你已经知道电视局域网地址，也可以显式指定：
+
+```bash
+quicktvui-ai plugin-check --plugin-base-url http://<tv-ip>:36366
+```
+
+## 五、推荐测试标识
+
+| 类型 | 标识 |
+| ---- | ---- |
+| So 包名 / tag | `eskit.so.ffmpeg.command` |
+| 插件包名 | `eskit.plugin.imagequality` |
+
+推荐测试文件：
+
+| 文件 | 用途 |
+| ---- | ---- |
+| `docs/plugin/arm64-v8a.zip` | arm64-v8a So 包 |
+| `docs/plugin/armeabi-v7a.zip` | armeabi-v7a So 包 |
+| `docs/plugin/plugin-general-debug.apk` | 插件 APK |

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

@@ -1,6 +1,6 @@
 ---
 name: copilot-instructions.md
-version: 1.1.16
+version: 1.1.18
 ---
 
 # copilot-instructions.md - QuickTVUI AI Development Guide
@@ -68,6 +68,127 @@ Required CLI sequence:
 
 AI MUST NOT say it has checked logs/screenshots unless one of those MCP/CLI reads actually succeeded.
 
+## 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:
+
+1. Prefer connected `quicktvui-ai-mcp` plugin tools:
+   - `plugin_server_check`
+   - `plugin_server_hello`
+   - `plugin_server_status`
+   - `plugin_upload_so`
+   - `plugin_upload_plugin`
+2. Otherwise use `quicktvui-ai plugin-*`
+3. Only fall back to manual `adb` + `curl` when neither tool path is available
+
+Required order:
+
+- Enable Toolkit RESTful API first:
+  - `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"`
+- Probe readiness:
+  - `plugin_server_check`
+  - or `quicktvui-ai plugin-check --device <serial>`
+- Read current state:
+  - `plugin_server_status`
+  - or `quicktvui-ai plugin-status --device <serial>`
+- Resolve plugin server address:
+  - explicit `baseUrl` / `--plugin-base-url`
+  - adb-connected device service address
+  - adb forward + `http://127.0.0.1:36366` when target host cannot be inferred
+  - if multiple adb devices are connected, ask for `serial` or `baseUrl`
+  - if no adb-connected device exists, ask the user for service IP / `baseUrl` and never invent a developer-specific TV IP
+- Upload So zip:
+  - choose the archive matching `ro.product.cpu.abi`
+  - `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
+- Upload plugin APK:
+  - `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`.
+- 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:
+  - So package/tag: `eskit.so.ffmpeg.command`
+  - Plugin package: `eskit.plugin.imagequality`
+- ABI 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 after `uploadPlugin` returns `registered: true`; 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.
+- 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/cli/plugin-server.md`
+
+
+## Plugin Scaffold Workflow (CRITICAL)
+
+When the user asks AI to create/update/build Android plugin projects, native modules, or native UI components, AI MUST use this priority:
+
+1. Prefer connected `quicktvui-ai-mcp` tools:
+   - `plugin_project_create`
+   - `plugin_project_build`
+   - `plugin_module_create`
+   - `plugin_component_create`
+2. Otherwise use `quicktvui-ai`:
+   - `plugin-create-project`
+   - `plugin-build`
+   - `plugin-create-module`
+   - `plugin-create-component`
+3. Only if neither MCP nor CLI execution is available may AI scaffold manually
+
+Decision rules:
+
+- project init / update / packaging -> `plugin_project_create` / `plugin_project_build`
+- non-UI native capability -> `plugin_module_create`
+- native View + props/events/functions -> `plugin_component_create`
+
+Hard requirements:
+
+- Read these packaged docs first:
+  - `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`
+- Source-of-truth interfaces come from `.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`
+- Project creation MUST write `.kyy-plugin-project.json`
+- By default, long-lived or releasable plugin projects SHOULD live under `<project-root>/plugin/<plugin-name>`
+- Plugin projects MUST NOT default to hidden directories such as `.ai-test/*` or other dot-prefixed paths
+- If plugin project is under a workspace subdirectory and root has `package.json`, AI MUST inject `build:android-plugin`
+- Build order MUST be:
+  1. `npm run build:android-plugin`
+  2. `npm run build:plugin`
+  3. `npm run build`
+  4. `./gradlew assembleGeneralDebug`
+- Module/component generation MUST require a concrete feature description first
+- Java package segments MUST be valid identifiers; do NOT place kebab-case directly into Java package names
+- Component generation MUST create/update `docs/component/<kebab-name>.md`
+- Component tags MUST be kebab-case
+- In Vue `h()`, do NOT use the fully-qualified Java class name
+- If plugin build reports missing Android SDK, resolve SDK generically in this order: `ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> platform default SDK directories.
+- If SDK is found and the target plugin project lacks `local.properties` / `sdk.dir`, allow CLI / MCP to create or update that local file for the current machine only.
+- Never turn one developer's local Android SDK path into a shared rule, hardcoded project setting, or committed repository file.
+- Read plugin runtime installation references when the page must really use the plugin:
+  - `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`
+- Build/upload success does NOT mean the Vue page can already use the plugin.
+- If a Vue page depends on the plugin, use `useESPlugin()` from `@extscreen/es3-core`, add listeners in `onESCreate`, and remove them in `onESDestroy`.
+- For component plugins, call `useES().isComponentRegistered("<fully-qualified-component-class>")` before using the component, and install the plugin first when registration is still missing.
+- Gate plugin-dependent rendering and calls on installation / registration readiness instead of assuming upload or install finishes synchronously.
+- Scaffold structure should follow `.source/sdk/base/...`, but live device logs override the default runtime namespace when startup fails.
+- If logs show `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy` or missing `com.quicktvui.sdk.base.*`, treat that as runtime compatibility drift and adapt runtime-facing imports/registration to the namespace actually present on the device before rebuilding/reuploading.
+- If logs show `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`, treat that as a bytecode-signature mismatch in the plugin registration entry, realign `EsProxy.get()` usage / registration to the actual device runtime signature, then rebuild/reupload.
+- Do not confuse local stub compilation with device runtime availability.
+- After install success, allow a short retry/recheck window if registration is still briefly missing.
+- After reuploading a compatibility-fixed plugin build, restart the host/runtime process before retesting.
+- If docs drift from source or implementation, AI MUST update docs
 
 ## Game Loop & Timer Constraints (CRITICAL)