@quicktvui/ai 1.1.16 → 1.1.18

package/rules/GEMINI.md

@@ -1,6 +1,6 @@
 ---
 name: GEMINI.md
-version: 1.1.16
+version: 1.1.18
 ---
 
 # GEMINI.md - QuickTVUI AI 开发指南
@@ -131,6 +131,128 @@ Hard requirements:
 - If `debug-targets` is empty, AI MUST say that `ESDebugServer /ai/targets` is still empty
 - If `debug-native-logs` or `debug-screenshot` fails, AI MUST report the real command/error instead of inventing fallback observations
 
+## 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 MCP nor CLI execution is available
+
+Required order:
+
+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 a developer-specific TV IP
+5. Upload So zip
+   - choose the archive that matches `ro.product.cpu.abi` on the device behind the current plugin service
+   - 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:
+
+- Runtime endpoint behavior overrides markdown docs.
+- Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
+- When AI is editing the `quicktvui-ai` repo itself and finds doc/runtime drift, AI MUST update docs.
+- `uploadSo` currently shows `pkg` / `tag` drift. AI SHOULD send both `pkg` and `tag`, and trust `data.tag` in successful responses.
+- Default demo identifiers:
+  - 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 still be empty even after `uploadPlugin` returns `registered: true`; AI MUST 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.
+- Uploading a newly rebuilt or replaced plugin package does NOT hot-swap the already running host/runtime process. Before validating startup, registration, or page-side usage after a new upload, AI MUST restart the host/runtime process.
+- AI SHOULD 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)
+
+当用户要求 AI 创建、更新、打包 Android 插件工程，或生成原生模块 / 原生组件时，AI 必须遵循以下优先级：
+
+1. 优先使用已连接的 `quicktvui-ai-mcp`：
+   - `plugin_project_create`
+   - `plugin_project_build`
+   - `plugin_module_create`
+   - `plugin_component_create`
+2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai`：
+   - `plugin-create-project`
+   - `plugin-build`
+   - `plugin-create-module`
+   - `plugin-create-component`
+3. 只有 MCP 和 CLI 都不可用时，才允许手工创建或修改脚手架。
+
+决策规则：
+
+1. 工程初始化 / 更新 / 打包：使用 `plugin_project_create` / `plugin_project_build`
+2. 无独立原生 UI 的能力：使用 `plugin_module_create`
+3. 有原生 View、属性、事件或函数派发的能力：使用 `plugin_component_create`
+
+硬约束：
+
+- 生成前应优先查阅以下包内文档：
+  - `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.*` 相关类，AI 必须把这视为运行时兼容性问题，改为适配设备实际存在的运行时命名空间后再重新构建、重传。
+- 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，AI 必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应改为匹配设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径后重新构建、重传。
+- AI 必须区分“本地 stub 可编译”和“设备运行时类真实存在”。如果插件能编译但在设备侧因 `EsProxy` 等类缺失而启动失败，这一版插件仍然判定为失败。
+- 插件工程打包完成或插件服务上传成功，并不代表 Vue 侧已经完成安装。
+- 如果页面需要实际使用插件，AI 必须在 Vue 侧使用 `@extscreen/es3-core` 的 `useESPlugin()` 补齐安装流程。
+- AI 必须在 `onESCreate` 中添加插件监听，在 `onESDestroy` 中移除监听。
+- 对于组件型插件，AI 应优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查组件是否已注册；若未注册，应先安装插件，再渲染或调用对应组件。
+- 不允许把“插件已上传”误当成“页面里已经可直接使用”，也不允许在未监听安装完成前直接假设同步可用。
+- 如果页面收到安装成功回调后，组件或模块注册仍然短暂不可见，AI 应允许一个简短的轮询复查窗口，再决定是否判定失败。
+- 如果是为修复运行时兼容性而重新上传的新插件版本，AI 在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
+- 创建工程后必须写入 `.kyy-plugin-project.json`
+- 对于长期保留或准备发布的插件工程，默认应放在 `<project-root>/plugin/<plugin-name>` 这种项目根目录下的可见目录
+- 不允许把插件工程默认放到 `.ai-test/*` 等隐藏目录或其他点前缀目录
+- 若插件工程位于子目录且工作区根目录存在 `package.json`，必须注入 `build:android-plugin`
+- 打包优先级固定为：
+  1. `npm run build:android-plugin`
+  2. `npm run build:plugin`
+  3. `npm run build`
+  4. `./gradlew assembleGeneralDebug`
+- 如果插件构建报 Android SDK 缺失，AI 必须先按通用顺序探测 SDK：`ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> 当前平台默认 SDK 目录，然后再判断环境是否真的缺失。
+- 如果已经探测到 SDK，且目标插件工程缺少 `local.properties` / `sdk.dir`，AI 可以让 CLI / MCP 只为当前开发机补齐这个本地文件。
+- AI 不得把某个开发者本机的 Android SDK 路径写进共享规则、硬编码项目配置或提交到仓库。
+- 生成 module / component 前，必须先获得明确功能描述
+- Java 包名必须使用合法包段，不能把 `kebab-case` 直接写进包路径
+- component 必须生成或更新 `docs/component/<kebab-name>.md`
+- 组件标签必须使用 `kebab-case`
+- 在 Vue `h()` 中禁止传完整 Java 包名，必须使用组件类名或约定标签名
+- 如果能定位到 `Application`，应优先补 `EsProxy.get().registerModule(...)` / `EsProxy.get().registerComponent(...)`
+- 如果文档与源码或实际实现不一致，AI 必须更新文档
+
 ---
 
 ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)