@quicktvui/ai 1.1.14 → 1.1.18

package/README.md

@@ -66,6 +66,50 @@ quicktvui-ai prompt --lang zh
 
 > 注意：全局 skills 不是对所有 AI 都自动生效。对仅读取项目文件的工具，仍需使用 `npm install @quicktvui/ai --save-dev` 注入项目内规则。
 
+## 🧩 插件服务工作流
+
+从当前版本开始，`@quicktvui/ai` 注入的规则也会约束 AI 如何联调电视插件服务：
+
+1. 优先使用 `quicktvui-ai-mcp` 的插件工具：`plugin_server_check`、`plugin_server_status`、`plugin_upload_so`、`plugin_upload_plugin`
+2. 没有 MCP 时，退回 `quicktvui-ai plugin-*`
+3. 只有两者都不可用时，才允许 AI 手写 `adb` / `curl`
+
+包内同时提供了可检索的插件服务文档：
+
+- `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`
+
+规则会强制 AI 先打开 Toolkit `RESTFUL_API`，并要求：
+
+- 接口返回优先于 Markdown 文档
+- ABI 必须匹配 `ro.product.cpu.abi`
+- `uploadSo` 调用时优先同时传 `pkg` 和 `tag`
+- 默认测试标识使用 `eskit.so.ffmpeg.command` 与 `eskit.plugin.imagequality`
+
+## 🏗️ 插件脚手架工作流
+
+从当前版本开始，`@quicktvui/ai` 注入的规则还会约束 AI 如何创建 Android 插件工程、原生模块与原生组件：
+
+1. 优先使用 `quicktvui-ai-mcp`：`plugin_project_create`、`plugin_project_build`、`plugin_module_create`、`plugin_component_create`
+2. 没有 MCP 时，退回 `quicktvui-ai plugin-create-project`、`plugin-build`、`plugin-create-module`、`plugin-create-component`
+3. 只有两者都不可用时，才允许 AI 手工修改脚手架
+
+包内同步提供了可检索文档：
+
+- `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`
+
+规则会进一步强制 AI：
+
+- 先根据需求区分“无界面模块”还是“有界面组件”
+- 以 `.source/sdk/base/...` 中的真实接口为准，而不是旧版 markdown 包名
+- 创建工程后写入 `.kyy-plugin-project.json`
+- 子目录工程自动补 `build:android-plugin`
+- 组件必须补 `docs/component/<kebab-name>.md`
+- Vue 标签必须使用 `kebab-case`
+
 ---
 
 ## 🤖 支持的 AI 工具与配置

package/package.json

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

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

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: lookup-css.md
-version: 1.1.14
+version: 1.1.18
 ---
 
 # 查询 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,146 @@ 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.
+
+## Plugin Server Workflow (CRITICAL)
+
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
+
+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 path is available
+
+Required order:
+
+1. 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"`
+2. Probe readiness:
+   - `plugin_server_check`
+   - or `quicktvui-ai plugin-check --device <serial>`
+3. Read current state:
+   - `plugin_server_status`
+   - or `quicktvui-ai plugin-status --device <serial>`
+4. 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:
+   - `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`.
+- Resolve plugin server address in this order:
+  - 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 the user to choose `serial` or provide service IP / `baseUrl`.
+- If no adb-connected device exists, ask the user for service IP / `baseUrl` and never invent a developer-specific TV IP.
+- 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`
+- 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.
+- 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
+- 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)
 

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,146 @@ 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.
+
+## Plugin Server Workflow (CRITICAL)
+
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
+
+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 path is available
+
+Required order:
+
+1. 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"`
+2. Probe readiness:
+   - `plugin_server_check`
+   - or `quicktvui-ai plugin-check --device <serial>`
+3. Read current state:
+   - `plugin_server_status`
+   - or `quicktvui-ai plugin-status --device <serial>`
+4. 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:
+   - `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`.
+- Resolve plugin server address in this order:
+  - 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 the user to choose `serial` or provide service IP / `baseUrl`.
+- If no adb-connected device exists, ask the user for service IP / `baseUrl` and never invent a developer-specific TV IP.
+- 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`
+- 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.
+- 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
+- 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)
 

package/rules/.docs/zh-CN/tool/api/overview.md

@@ -94,6 +94,10 @@ qt.view.requestFocus(viewRef)
 | `qt.brightness`           |   ESBrightness              | [点击查看详细API](/zh-CN/module/brightness#exposes)                 |
 | `qt.service`              |   ESService                 | [点击查看详细API](/zh-CN/module/service#exposes)                 |
 
+## QuickTVUI AI 插件接口工作流
+
+* 插件服务接口 [`plugin-server-api`](/zh-CN/tool/api/plugin-server-api)
+* 插件脚手架 MCP [`plugin-scaffold-mcp`](/zh-CN/tool/api/plugin-scaffold-mcp)
 
 
 

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

@@ -0,0 +1,46 @@
+---
+title: Plugin Scaffold MCP
+lang: zh-CN
+---
+
+# 插件创建 MCP 工具
+
+## 一、工具列表
+
+| 工具 | 用途 |
+| ---- | ---- |
+| `plugin_project_create` | 创建或更新插件工程 |
+| `plugin_project_build` | 打包插件工程 |
+| `plugin_module_create` | 创建无界面原生模块 |
+| `plugin_component_create` | 创建有界面原生组件 |
+
+## 二、使用优先级
+
+当 AI 在支持 MCP 的客户端中工作时，插件创建类任务应优先调用上述工具，而不是直接手写文件。
+
+## 三、决策规则
+
+1. 创建工程或打包工程：使用 `plugin_project_create` / `plugin_project_build`
+2. 无独立原生 UI 的原生能力：使用 `plugin_module_create`
+3. 有原生 View、属性、事件、方法的能力：使用 `plugin_component_create`
+
+## 四、硬约束
+
+1. 真实源码优先于 markdown 文档
+2. `plugin_module_create` 必须按 `com.quicktvui.sdk.base.module.IEsModule` 生成
+3. `plugin_component_create` 必须按 `com.quicktvui.sdk.base.component.IEsComponent`、`IEsComponentView`、`EsComponentAttribute` 生成
+4. 组件必须补 `docs/component/<name>.md`
+5. 组件标签必须使用 `kebab-case`
+6. `plugin_project_build` 构建前应优先复用 CLI 的通用 Android SDK 探测逻辑：先看 `ANDROID_SDK_ROOT` / `ANDROID_HOME`，再看平台默认 SDK 目录
+7. 如探测到 SDK 且目标工程缺少 `local.properties` / `sdk.dir`，允许工具在目标插件工程内自动补齐本地 `local.properties`
+8. `local.properties` 只属于开发机本地配置，不应作为共享工程规则提交
+9. 长期保留或准备发布的插件工程，默认应创建到项目根目录下可见的 `plugin/<plugin-name>`
+10. 不要把插件工程默认创建到 `.ai-test/*` 等隐藏目录
+11. 插件工程打包成功或插件包上传成功，并不代表 Vue 页面已经可直接使用插件
+12. 如果页面里要实际使用插件，AI 还必须补齐 Vue 侧安装逻辑：`useESPlugin()`、`addListener` / `removeListener`、`installPlugin({ pkg })`
+13. 对于组件型插件，优先参考 `module/plugin` 文档与 `quicktvui/src/long-image/index.vue`，先用 `useES().isComponentRegistered("<组件完整类名>")` 检查注册状态，再决定是否安装或渲染
+14. 脚手架结构默认按 `.source/sdk/base/...` 生成，但一旦设备日志显示 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy` 或缺失 `com.quicktvui.sdk.base.*`，应立即把运行时日志视为更高优先级的兼容性信号
+15. 这类报错通常表示本地 stub 可编译，但目标 TV 运行时只暴露旧命名空间；AI 应切换运行时侧注册/导入到设备真实存在的命名空间后重新构建、重传
+16. 页面侧收到安装成功回调后，如注册状态仍短暂不可见，允许一个简短轮询复查窗口，再决定是否判定失败
+17. 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，应视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；AI 应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整注册实现后重新构建、重传
+18. 如果是为修复运行时兼容性而重新上传的新插件版本，AI 在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码