@quicktvui/ai 1.1.14 → 1.1.18

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

@@ -1,6 +1,6 @@
 ---
 name: copilot-instructions.md
-version: 1.1.14
+version: 1.1.18
 ---
 
 # copilot-instructions.md - QuickTVUI AI Development Guide
@@ -49,6 +49,146 @@ When asked to create a new QuickTVUI project, you MUST NOT generate a generic Vu
 4. **Install Deps**: `yarn install`
 5. **Setup Reminder**: Remind the user to run `npm install -g @quicktvui/cli@latest` and `qui setup` if they haven't configured the environment (see https://quicktvui.com/zh-CN/guide/basic/quick-start.html).
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+When the task is to inspect a running QuickTVUI app, AI MUST use this priority:
+
+1. MCP first, if `@quicktvui/ai-debug-mcp` is connected.
+2. Otherwise use `quicktvui-ai debug-*` commands against `ESDebugServer`.
+3. Only ask the user to paste logs manually if neither tool path is available.
+
+Required CLI sequence:
+
+- `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+- select `clientId`
+- `quicktvui-ai debug-context --client-id <clientId>`
+- `quicktvui-ai debug-events --client-id <clientId> --limit 100`
+- `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
+- `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
+
+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)
 

package/rules/.windsurfrules

@@ -1,6 +1,6 @@
 ---
 name: .windsurfrules
-version: 0.6.1
+version: 1.1.14
 ---
 
 # .windsurfrules - 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/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 name: AGENTS.md
-version: 1.1.14
+version: 1.1.18
 ---
 
 # AGENTS.md - QuickTVUI AI Development Guide
@@ -115,6 +115,153 @@ 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, recent errors, or current target state for a running QuickTVUI app, AI MUST use this priority:
+
+1. Prefer MCP resources/tools when `@quicktvui/ai-debug-mcp` is connected.
+2. If MCP is unavailable but shell/CLI execution is available, AI MUST use `quicktvui-ai debug-*` commands against the running `ESDebugServer`.
+3. Only if neither MCP nor CLI execution is available may AI ask the user to paste logs manually.
+
+Required non-MCP command order:
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. Choose `clientId`
+   - If only one target exists, AI MAY use it directly.
+   - If multiple targets exist, AI MUST ask user to confirm the right `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>`
+
+Hard requirements:
+
+- AI MUST NOT claim it has inspected Chrome logs, Android native logs, target context, or screenshots unless MCP or `quicktvui-ai debug-*` actually returned data.
+- 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.
+
+## 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:
+
+1. Prefer connected `quicktvui-ai-mcp` plugin tools:
+   - `plugin_server_check`
+   - `plugin_server_hello`
+   - `plugin_server_status`
+   - `plugin_upload_so`
+   - `plugin_upload_plugin`
+2. If MCP is unavailable but shell/CLI execution is available, AI MUST use `quicktvui-ai plugin-*`.
+3. Only if neither MCP nor CLI execution is available may AI fall back to manual `adb` + `curl`.
+
+Required workflow:
+
+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. 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:
+   - 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:
+   - 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`.
+- 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:
+  - 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 remain empty even after `uploadPlugin` returns `registered: true`; AI MUST report that as-is instead of fabricating a derived install state.
+- `uploadPlugin` success or `registered: true` only means the package reached the plugin service. If the user needs to use that plugin from a Vue page, AI MUST still add Vue-side plugin installation logic and MUST NOT treat upload as "already installed in page runtime".
+- 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/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. If MCP is unavailable but shell/CLI execution is available, AI MUST 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 template 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:
+
+- AI SHOULD consult 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`
+  - `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-of-truth interfaces come from `.source/sdk/base/...` and override markdown docs:
+  - `com.quicktvui.sdk.base.module.IEsModule`
+  - `com.quicktvui.sdk.base.component.IEsComponent`
+  - `com.quicktvui.sdk.base.component.IEsComponentView`
+  - `com.quicktvui.sdk.base.component.EsComponentAttribute`
+- The scaffold shape should follow `.source/sdk/base/...`, but target-device runtime logs are authoritative for runtime namespace compatibility.
+- If device logs show `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy` or other missing `com.quicktvui.sdk.base.*` classes during plugin startup, AI MUST treat that as a runtime-compatibility failure, switch runtime-facing registration/imports to the namespace actually present on the device, and rebuild/reupload instead of repeatedly forcing the scaffold default.
+- If device logs show `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`, AI MUST treat that as a bytecode-signature mismatch between the plugin's compiled registration entry and the actual device runtime, not as a page-logic bug. AI MUST realign runtime-facing `EsProxy.get()` usage / imports / registration path to the signature actually present on the device, then rebuild and reupload.
+- AI MUST distinguish compile-time stubs from real device runtime classes. A plugin that compiles against local stubs but crashes on device because `EsProxy` or related runtime classes are missing is NOT considered valid.
+- Plugin build/upload does NOT mean Vue can already use the plugin. If a Vue page needs the plugin at runtime, AI MUST add Vue-side installation with `useESPlugin()` from `@extscreen/es3-core`.
+- AI MUST register plugin listeners in `onESCreate` and remove them in `onESDestroy`.
+- For component plugins, AI SHOULD call `useES().isComponentRegistered("<fully-qualified-component-class>")` before rendering or dispatching to the plugin component, and install the plugin first when registration is still missing.
+- AI MUST gate plugin-dependent Vue rendering or calls on installation / registration readiness, instead of assuming upload or install starts synchronously and finishes instantly.
+- After page-side install success, if module/component registration is still missing, AI SHOULD perform a short retry/recheck window before declaring failure, because registration may lag slightly behind the install callback.
+- After reuploading a new plugin build for a runtime-compatibility fix, AI MUST restart the host/runtime process before retesting, because the already running host may still hold the old plugin bytes.
+- Project creation MUST write `.kyy-plugin-project.json`.
+- For long-lived or releasable plugin projects, AI SHOULD place the project under `<project-root>/plugin/<plugin-name>` by default.
+- AI MUST NOT default plugin projects to hidden directories such as `.ai-test/*` or other dot-prefixed paths.
+- If the plugin project is created under a workspace subdirectory and the workspace 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, AI MUST first resolve SDK generically via `ANDROID_SDK_ROOT`, then `ANDROID_HOME`, then platform-default SDK directories, before declaring the environment broken.
+- If SDK is found and the target plugin project lacks `local.properties` / `sdk.dir`, AI MAY let CLI / MCP create or update that local file for the current machine only.
+- AI MUST NOT 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 before generating files.
+- Java package segments MUST be valid identifiers. Do NOT put kebab-case directly into Java package names.
+- Component generation MUST create or update `docs/component/<kebab-name>.md`.
+- Component tags MUST be kebab-case.
+- In Vue `h()`, AI MUST NOT use the fully-qualified Java class name; use the component class name or agreed tag name instead.
+- When an `Application` class can be located, AI SHOULD register generated classes with `EsProxy.get().registerModule(...)` or `EsProxy.get().registerComponent(...)`.
+- If docs drift from source or actual implementation, AI MUST update the docs.
+
 ## 🔥 ARCHITECTURAL GOTCHAS (CRITICAL)
 
 AI assistants frequently fail by applying traditional Web paradigms to QuickTVUI. **You MUST memorize these constraints**:

package/rules/AI_HANDOFF.md

@@ -1,6 +1,6 @@
 ---
 name: AI_HANDOFF.md
-version: 1.1.14
+version: 1.1.18
 ---
 
 # QuickTVUI AI 集成 - 工作交接文档
@@ -61,6 +61,136 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 - 不得在未检查 CLI 能力前直接进入 `yarn dev` / 手写 `adb` 流程。
 - 若某一步骤在 `quicktvui-ai-cli` 中不存在对应命令，AI 必须先明确说明“CLI 暂不支持该步骤”，再走手工兜底流程。
 
+## Runtime Debug Data Workflow (CRITICAL)
+
+对于“读取运行中应用调试数据”的任务，后续 AI 必须统一遵循以下优先级：
+
+1. 优先使用 `@quicktvui/ai-debug-mcp`
+2. 没有 MCP 时，使用 `quicktvui-ai debug-*`
+3. 两者都不可用时，才要求用户手工提供日志或截图
+
+当前约定的非 MCP 命令链路：
+
+1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
+2. 选择或确认 `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>`
+
+接手注意事项：
+
+- 未通过 MCP 或 `quicktvui-ai debug-*` 真正读取到数据前，不得宣称“已检查运行时日志/截图”
+- `debug-targets` 返回空数组时，应先回到 run/dev 链路，确认 `ESDebugServer /ai/targets` 已建立
+- `debug-screenshot` 默认会把图片写到 `<project>/.quicktvui-ai/debug-screenshots/`，后续 AI 应优先使用命令返回的 `savedTo` 路径
+- `debug-native-logs` 与 `debug-screenshot` 的失败信息应直接向用户透明披露，不要二次包装成模糊描述
+
+## 插件服务工作流 (CRITICAL)
+
+当任务涉及电视插件服务接口（`/hello`、`/status`、`/uploadSo`、`/uploadPlugin`）时，后续 AI 必须统一遵循以下优先级：
+
+1. 优先使用 `quicktvui-ai-mcp` 中的插件工具
+2. 没有 MCP 时，使用 `quicktvui-ai plugin-*`
+3. 两者都不可用时，才退回手工 `adb` + `curl`
+
+当前约定的执行顺序：
+
+1. 先打开 Toolkit RESTful API
+   - `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. 健康检查
+   - MCP：`plugin_server_check`
+   - CLI：`quicktvui-ai plugin-check --device <serial>`
+3. 读取状态
+   - MCP：`plugin_server_status`
+   - CLI：`quicktvui-ai plugin-status --device <serial>`
+4. 解析插件服务地址
+   - 如果显式传了 `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
+   - 必须先根据当前插件服务对应设备的 `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
+   - CLI：`quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
+
+接手注意事项：
+
+- 文档与接口返回不一致时，统一以接口真实返回为准
+- `/hello`、`/status`、`/uploadSo`、`/uploadPlugin` 必须使用 `POST` 探测，不能用 `GET` 判断服务是否可用
+- 如果此时正在 `quicktvui-ai` 仓库中改规则或文档，必须同步把差异写回文档
+- `uploadSo` 目前存在 `pkg` / `tag` 漂移，调用时应尽量同时传这两个字段
+- 测试 Demo 固定标识：
+  - So：`eskit.so.ffmpeg.command`
+  - 插件：`eskit.plugin.imagequality`
+- `uploadPlugin` 返回 `registered: true` 后，`status.pluginList` 仍可能为空；后续 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/cli/plugin-server.md`
+
+## 插件脚手架工作流 (CRITICAL)
+
+当任务涉及 Android 插件工程创建 / 更新 / 打包，或原生模块 / 原生组件生成时，后续 AI 必须统一遵循以下优先级：
+
+1. 优先使用 `quicktvui-ai-mcp`
+2. 没有 MCP 时，使用 `quicktvui-ai plugin-*`
+3. 两者都不可用时，才退回手工脚手架
+
+当前约定工具：
+
+1. 工程创建 / 更新：`plugin_project_create` 或 `quicktvui-ai plugin-create-project`
+2. 工程打包：`plugin_project_build` 或 `quicktvui-ai plugin-build`
+3. 无界面原生能力：`plugin_module_create` 或 `quicktvui-ai plugin-create-module`
+4. 有界面原生能力：`plugin_component_create` 或 `quicktvui-ai plugin-create-component`
+
+接手注意事项：
+
+- 先查阅包内文档：
+  - `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.*`，接手方必须把它视为运行时兼容性问题，并改为适配设备实际存在的命名空间后重新构建、重传。
+- 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，接手方必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整后重新构建、重传。
+- 不要把“本地 stub 编译通过”误判成“设备运行时也没问题”；只要设备侧因为 `EsProxy` 或相关类缺失而崩溃，就必须回到兼容性修复。
+- 如果是为修复运行时兼容性而重新上传的新插件版本，接手方在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+- 插件工程打包完成或插件包上传完成，并不代表 Vue 页面已经可直接使用插件；如果需求里包含页面接入，接手方必须补齐 Vue 侧安装逻辑。
+- Vue 侧必须使用 `@extscreen/es3-core` 的 `useESPlugin()`，并在 `onESCreate` 中添加监听、在 `onESDestroy` 中移除监听。
+- 对于组件型插件，接手方应优先使用 `useES().isComponentRegistered("<组件完整类名>")` 判断是否已注册；若未注册，应先安装插件，再渲染或调用对应组件。
+- 不允许把“已上传插件”误判成“页面里已自动安装完成”，也不允许跳过安装完成监听。
+- 如果页面收到安装成功回调后，注册状态仍短暂不可见，接手方应允许一次简短轮询复查，而不是立刻判定失败。
+- 创建工程后必须写入 `.kyy-plugin-project.json`
+- 对于长期保留或准备发布的插件工程，默认应放在 `<project-root>/plugin/<plugin-name>` 这种项目根目录下的可见目录
+- 不允许把插件工程默认放到 `.ai-test/*` 等隐藏目录或其他点前缀目录
+- 若插件工程位于子目录且根目录有 `package.json`，必须注入 `build:android-plugin`
+- 如果插件构建报 Android SDK 缺失，接手方应先按通用顺序探测 SDK：`ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> 当前平台默认 SDK 目录。
+- 如果已探测到 SDK 且目标插件工程缺少 `local.properties` / `sdk.dir`，可以让 CLI / MCP 只为当前开发机补齐该本地文件。
+- 不要把某个开发者本机的 Android SDK 路径写进共享规则、硬编码项目配置或提交到仓库。
+- 打包顺序固定为：
+  1. `npm run build:android-plugin`
+  2. `npm run build:plugin`
+  3. `npm run build`
+  4. `./gradlew assembleGeneralDebug`
+- 生成 module / component 前必须先拿到明确功能描述
+- Java 包名不能使用带 `-` 的包段，不能把 `kebab-case` 直接写进 Java 包路径
+- component 必须同步生成或更新 `docs/component/<kebab-name>.md`
+- 组件标签必须使用 `kebab-case`
+- 在 Vue `h()` 中禁止使用完整 Java 包名，必须使用组件类名或约定标签名
+- 若能定位到 `Application`，应优先补 `EsProxy.get().registerModule(...)` / `EsProxy.get().registerComponent(...)`
+- 文档与源码或实际实现不一致时，必须回写文档
+
 ---
 
 ## 一、项目背景