@quicktvui/ai 1.1.16 → 1.1.19

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

@@ -1,6 +1,6 @@
 ---
 name: copilot-instructions.md
-version: 1.1.16
+version: 1.1.19
 ---
 
 # copilot-instructions.md - QuickTVUI AI Development Guide
@@ -68,6 +68,134 @@ 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`) or recent runtime load status from `/status`, AI MUST use this priority:
+
+1. Prefer connected `quicktvui-ai-mcp` plugin tools:
+   - `plugin_server_check`
+   - `plugin_server_hello`
+   - `plugin_server_status`
+   - `quicktvui_runtime_status`
+   - `plugin_upload_so`
+   - `plugin_upload_plugin`
+2. Otherwise use `quicktvui-ai plugin-*`
+3. Only fall back to manual `adb` + `curl` when neither 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>`
+- If the task is to inspect recent runtime load state or latest error info after quick-app/plugin load:
+  - `quicktvui_runtime_status`
+  - or `quicktvui-ai runtime-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`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side install, or a startup failure, query `quicktvui_runtime_status` / `runtime-status` and report the package key plus `__debug__`.
+- 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/api/runtime-status.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
+
+
+## Plugin Scaffold Workflow (CRITICAL)
+
+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

@@ -102,6 +102,134 @@ Required CLI order:
 
 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`) or recent runtime load status from `/status`:
+
+1. Prefer connected `quicktvui-ai-mcp` plugin tools:
+   - `plugin_server_check`
+   - `plugin_server_hello`
+   - `plugin_server_status`
+   - `quicktvui_runtime_status`
+   - `plugin_upload_so`
+   - `plugin_upload_plugin`
+2. Otherwise use `quicktvui-ai plugin-*`
+3. Only fall back to manual `adb` + `curl` when neither 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. If the task is to inspect recent runtime load state or latest error info after quick-app/plugin load:
+   - `quicktvui_runtime_status`
+   - or `quicktvui-ai runtime-status --device <serial>`
+5. 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`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side install, or a startup failure, query `quicktvui_runtime_status` / `runtime-status` and report the package key plus `__debug__`.
+- 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/api/runtime-status.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
+
+
+## Plugin Scaffold Workflow (CRITICAL)
+
+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.16
+version: 1.1.19
 ---
 
 # AGENTS.md - QuickTVUI AI Development Guide
@@ -140,6 +140,135 @@ Hard requirements:
 - 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.
+- When the user is asking about recent quick-app load state, startup failure, or the latest runtime-side error message after load, AI SHOULD also query `quicktvui_runtime_status` / `quicktvui-ai runtime-status` and report the relevant package key plus `__debug__` from `data.loadStatus`.
+
+## Plugin Server Workflow (CRITICAL)
+
+When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`) or recent runtime load status from `/status`, AI MUST use this priority:
+
+1. Prefer connected `quicktvui-ai-mcp` plugin tools:
+   - `plugin_server_check`
+   - `plugin_server_hello`
+   - `plugin_server_status`
+   - `quicktvui_runtime_status`
+   - `plugin_upload_so`
+   - `plugin_upload_plugin`
+2. 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. If the user needs recent runtime load state or latest error info after quick-app/plugin load:
+   - MCP: `quicktvui_runtime_status`
+   - CLI: `quicktvui-ai runtime-status --device <serial>`
+5. Resolve plugin server address:
+   - If `baseUrl` / `--plugin-base-url` is explicitly provided, use it
+   - Otherwise, if adb already has a connected target, use that target's plugin service address first
+   - If the target host cannot be inferred, use adb port forward and `http://127.0.0.1:36366`
+   - If multiple adb devices are connected, AI MUST ask the user to choose `serial` or provide service IP / `baseUrl`
+   - If no adb-connected device exists, AI MUST ask the user for service IP / `baseUrl`, and MUST NOT invent or hardcode a developer-specific TV IP
+6. 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>`
+7. 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`.
+- `/status` may include `data.loadStatus`, which is the authoritative recent runtime load-state/error map for quick-app/plugin startup. After `run-dev`, `run-esapp`, page-side plugin install, or a startup failure, AI SHOULD query `quicktvui_runtime_status` / `runtime-status` and report the relevant package key plus `__debug__`.
+- 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/api/runtime-status.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
+
+## Plugin Scaffold Workflow (CRITICAL)
+
+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)
 

package/rules/AI_HANDOFF.md

@@ -1,6 +1,6 @@
 ---
 name: AI_HANDOFF.md
-version: 1.1.16
+version: 1.1.19
 ---
 
 # QuickTVUI AI 集成 - 工作交接文档
@@ -85,6 +85,118 @@ AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报
 - `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. 如果任务需要最近一次 runtime 加载状态与错误信息
+   - MCP：`quicktvui_runtime_status`
+   - CLI：`quicktvui-ai runtime-status --device <serial>`
+5. 解析插件服务地址
+   - 如果显式传了 `baseUrl` / `--plugin-base-url`，优先使用该地址
+   - 否则，如果 adb 已连接设备，先尝试使用该设备的插件服务地址
+   - 如果无法从目标设备推断 host，则改用 adb 端口转发和 `http://127.0.0.1:36366`
+   - 如果同时连接了多台 adb 设备，后续 AI 必须要求用户选择 `serial` 或提供服务 IP / `baseUrl`
+   - 如果没有任何 adb 已连接设备，后续 AI 必须向用户索要服务 IP / `baseUrl`，不得脑补或写死某个开发者自己的电视 IP
+6. 上传 So
+   - 必须先根据当前插件服务对应设备的 `ro.product.cpu.abi` 选择 zip
+   - CLI：`quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
+7. 上传插件 APK
+   - CLI：`quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
+
+接手注意事项：
+
+- 文档与接口返回不一致时，统一以接口真实返回为准
+- `/hello`、`/status`、`/uploadSo`、`/uploadPlugin` 必须使用 `POST` 探测，不能用 `GET` 判断服务是否可用
+- `/status` 中的 `data.loadStatus` 是最近一次 runtime 加载状态与错误信息的权威来源；接手后若要继续排查加载失败，应优先调用 `quicktvui_runtime_status` / `quicktvui-ai runtime-status`，并同时报告相关包名项与 `__debug__`
+- 如果此时正在 `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/api/runtime-status.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
+  - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/runtime-status.md`
+
+## 插件脚手架工作流 (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(...)`
+- 文档与源码或实际实现不一致时，必须回写文档
+
 ---
 
 ## 一、项目背景