@quicktvui/ai 1.1.14 → 1.1.18

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

@@ -0,0 +1,198 @@
+---
+title: Plugin Server API
+lang: zh-CN
+---
+
+# 插件服务接口
+
+## 一、概述
+
+电视侧插件服务默认监听 `36366` 端口，接口根路径为：
+
+```text
+http://<tv-ip>:36366/api/v1
+```
+
+在调用 `/hello`、`/status`、`/uploadSo`、`/uploadPlugin` 之前，必须先通过 Toolkit 广播打开 `RESTFUL_API`。
+
+重要约束：
+
+1. 文档与接口返回不一致时，统一以接口真实返回为准。
+2. 这些接口要求使用 `POST`；同路径 `GET` 在实测设备上可能返回 `404`。
+3. `uploadSo` 已观察到 `pkg` / `tag` 字段漂移；调用时建议同时传这两个字段。
+4. `status.pluginList` 可能在 `uploadPlugin` 返回 `registered: true` 后仍为空，这属于真实接口行为，不能自行推导为失败或成功安装完成。
+5. QuickTVUI AI 工具在未显式传 `baseUrl` 时，会优先尝试 adb 已连接设备的插件服务地址；如果没有 adb 设备，AI 应先向用户索要服务 IP / `baseUrl`。
+6. `abi` 只在上传 So 时才需要。CLI / MCP 如果在 `uploadSo` 时未显式传 `abi`，会尝试读取当前插件服务对应设备的 `ro.product.cpu.abi` 并按需补齐；`check` / `hello` / `status` / `uploadPlugin` 不会主动查询 ABI。
+7. `uploadPlugin` 返回成功，只代表插件包已上传到插件服务缓存；如果 Vue 页面需要实际使用该插件，还必须在页面侧通过 `useESPlugin()` 监听并调用 `installPlugin({ pkg })`，不能把“上传成功”误当成“页面已安装完成”。
+8. 上传新的插件包到服务后，当前宿主 / runtime 进程不会自动热更新到新字节码；复测启动、注册或页面接入前，必须先重启宿主进程。
+
+## 二、开启服务
+
+### 2.1 adb 广播
+
+```bash
+adb -s <serial> shell am broadcast -a "eskit.sdk.core.ACTION_TOOLKIT_SETTING" --es "RESTFUL_API" "true"
+```
+
+### 2.2 QuickTVUI AI CLI
+
+```bash
+quicktvui-ai plugin-enable-api --device <serial>
+```
+
+## 三、接口列表
+
+### 3.1 `POST /hello`
+
+用途：确认服务已启动。
+
+典型响应：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {}
+}
+```
+
+### 3.2 `POST /status`
+
+用途：读取当前插件服务缓存状态。
+
+典型响应：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "soList": [
+      "eskit.so.player.v1"
+    ],
+    "pluginList": []
+  }
+}
+```
+
+说明：
+
+1. `soList` / `pluginList` 反映的是当前服务返回的数据，不应脑补额外状态。
+2. 即使上传插件成功，`pluginList` 也可能仍为空。
+
+### 3.3 `POST /uploadSo`
+
+用途：上传 So zip。
+
+推荐请求方式：`multipart/form-data`
+
+建议字段：
+
+| 字段 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `tag` | 是 | So 标识，建议与包名保持一致 |
+| `pkg` | 是 | 兼容字段，当前建议与 `tag` 同时传 |
+| `abi` | 是 | 目标设备 ABI，例如 `armeabi-v7a` / `arm64-v8a`；CLI / MCP 在 `uploadSo` 且未显式传值时，会尝试按当前服务目标设备自动补齐 |
+| `osCpuAbi` | 否 | 建议与 `abi` 保持一致 |
+| `file` | 是 | zip 文件 |
+| `fileName` / `name` | 否 | 上传文件名 |
+
+空请求实测返回：
+
+```json
+{
+  "code": 400,
+  "message": "tag is required",
+  "data": null
+}
+```
+
+成功响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "tag": "eskit.so.ffmpeg.command",
+    "abi": "armeabi-v7a",
+    "fileName": "armeabi-v7a.zip",
+    "filePath": "/data/user/0/tv.eskit.debugger/cache/rpk/local_install_so/eskit.so.ffmpeg.command/armeabi-v7a/armeabi-v7a.zip",
+    "size": 4623751,
+    "registered": true
+  }
+}
+```
+
+说明：
+
+1. 返回字段以 `data.tag` 为准。
+2. `filePath` 实测会带 `rpk/local_install_so/` 路径层级。
+3. 上传前必须根据当前插件服务对应设备的 `ro.product.cpu.abi` 选择正确的 zip。
+
+### 3.4 `POST /uploadPlugin`
+
+用途：上传插件 APK。
+
+推荐请求方式：`multipart/form-data`
+
+建议字段：
+
+| 字段 | 必填 | 说明 |
+| ---- | ---- | ---- |
+| `pkg` | 是 | 插件包名 |
+| `packageName` | 否 | 兼容字段，建议与 `pkg` 同时传 |
+| `file` | 是 | APK 文件 |
+| `fileName` / `name` | 否 | 上传文件名 |
+
+空请求实测返回：
+
+```json
+{
+  "code": 400,
+  "message": "pkg is required",
+  "data": null
+}
+```
+
+成功响应示例：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "pkg": "eskit.plugin.imagequality",
+    "fileName": "plugin-general-debug.apk",
+    "filePath": "/data/user/0/tv.eskit.debugger/cache/rpk/local_upload_plugin/eskit.plugin.imagequality/plugin-general-debug.apk",
+    "size": 89578,
+    "registered": true
+  }
+}
+```
+
+说明：
+
+1. `filePath` 实测会带 `rpk/local_upload_plugin/` 路径层级。
+2. `registered: true` 只代表接口返回注册成功，不代表 `status.pluginList` 一定马上可见。
+3. 如果业务页面要真正使用该插件，还必须在 Vue 侧调用插件安装流程，推荐参考 `module/plugin` 文档、`module/plugin/es-basic.vue` 示例，以及 `quicktvui/src/long-image/index.vue` 的注册检查实现。
+4. 如果上传成功但设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy` 或缺失 `com.quicktvui.sdk.base.*`，应视为运行时命名空间兼容性问题，而不是插件服务上传失败。
+5. 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，应视为插件注册入口的字节码签名与设备 runtime 不兼容；需要改成匹配设备真实 `EsProxy.get()` 签名 / 调用路径的实现后重新构建、重传。
+6. 上传新的插件版本后，必须先重启宿主 / runtime 进程，再验证插件启动、注册和页面侧安装，否则当前进程仍可能持有旧插件字节码。
+
+## 四、测试 Demo 标识
+
+推荐默认测试标识：
+
+| 类型 | 标识 |
+| ---- | ---- |
+| So 包名 / tag | `eskit.so.ffmpeg.command` |
+| 插件包名 | `eskit.plugin.imagequality` |
+
+本地测试文件映射：
+
+| 文件 | 用途 | 对应标识 |
+| ---- | ---- | -------- |
+| `docs/plugin/arm64-v8a.zip` | arm64-v8a So 包 | `eskit.so.ffmpeg.command` |
+| `docs/plugin/armeabi-v7a.zip` | armeabi-v7a So 包 | `eskit.so.ffmpeg.command` |
+| `docs/plugin/plugin-general-debug.apk` | 插件 APK | `eskit.plugin.imagequality` |

package/rules/.docs/zh-CN/tool/cli/introduction.md

@@ -23,4 +23,11 @@ lang: zh-CN
 * 日志 [`qui logcat`](/zh-CN/tool/cli/logcat)
 * 测试 [`qui test`](/zh-CN/tool/cli/test)
 
+## QuickTVUI AI 插件工作流
+
+* 插件服务联调 [`plugin-server`](/zh-CN/tool/cli/plugin-server)
+* 插件工程创建与打包 [`plugin-create-project`](/zh-CN/tool/cli/plugin-create-project)
+* 插件模块创建 [`plugin-create-module`](/zh-CN/tool/cli/plugin-create-module)
+* 插件组件创建 [`plugin-create-component`](/zh-CN/tool/cli/plugin-create-component)
+
 <img src="/tool/cli/cli.png" />

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 |