@quicktvui/ai 1.1.14 → 1.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/README.md +44 -0
  2. package/package.json +1 -1
  3. package/rules/.claude/commands/create-component.md +1 -1
  4. package/rules/.claude/commands/create-page.md +1 -1
  5. package/rules/.claude/commands/create-project.md +1 -1
  6. package/rules/.claude/commands/lookup-api.md +1 -1
  7. package/rules/.claude/commands/lookup-css.md +1 -1
  8. package/rules/.clinerules +141 -1
  9. package/rules/.cursorrules +141 -1
  10. package/rules/.docs/zh-CN/tool/api/overview.md +4 -0
  11. package/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md +46 -0
  12. package/rules/.docs/zh-CN/tool/api/plugin-server-api.md +198 -0
  13. package/rules/.docs/zh-CN/tool/cli/introduction.md +7 -0
  14. package/rules/.docs/zh-CN/tool/cli/plugin-create-component.md +101 -0
  15. package/rules/.docs/zh-CN/tool/cli/plugin-create-module.md +88 -0
  16. package/rules/.docs/zh-CN/tool/cli/plugin-create-project.md +106 -0
  17. package/rules/.docs/zh-CN/tool/cli/plugin-server.md +152 -0
  18. package/rules/.github/copilot-instructions.md +141 -1
  19. package/rules/.windsurfrules +141 -1
  20. package/rules/AGENTS.md +148 -1
  21. package/rules/AI_HANDOFF.md +131 -1
  22. package/rules/CLAUDE.md +148 -1
  23. package/rules/GEMINI.md +148 -1
package/rules/CLAUDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: CLAUDE.md
3
- version: 1.1.14
3
+ version: 1.1.18
4
4
  ---
5
5
 
6
6
  # QuickTVUI - AI 开发指南
@@ -115,6 +115,153 @@ Hard requirements:
115
115
  - If user asks to launch a specific ES app/version/source, run:
116
116
  `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
117
117
 
118
+ ## Runtime Debug Data Workflow (CRITICAL)
119
+
120
+ 当用户要求 AI 检查运行中应用的 console/network/exception、Android native logs、截图或当前 target 状态时，AI 必须使用以下优先级：
121
+
122
+ 1. 优先使用已连接的 `@quicktvui/ai-debug-mcp`
123
+ 2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai debug-*`
124
+ 3. 只有 MCP 和 CLI 都不可用时，才允许要求用户手工粘贴日志
125
+
126
+ 非 MCP 场景下，必须按以下顺序执行：
127
+
128
+ 1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
129
+ 2. 选择 `clientId`
130
+ - 仅有一个 target 时可直接使用
131
+ - 多个 target 时必须让用户确认正确的 `clientId`
132
+ 3. `quicktvui-ai debug-context --client-id <clientId>`
133
+ 4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
134
+ 5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
135
+ 6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
136
+
137
+ 硬约束：
138
+
139
+ - AI 未通过 MCP 或 `quicktvui-ai debug-*` 实际读取到数据前，不得声称自己已经检查过运行时日志、native logs 或截图
140
+ - `debug-targets` 为空时，必须明确说明当前 `ESDebugServer /ai/targets` 还没有可读 target
141
+ - `debug-native-logs` 或 `debug-screenshot` 失败时，必须原样报告命令和错误，不得编造兜底结论
142
+
143
+ ## Plugin Server Workflow (CRITICAL)
144
+
145
+ 当用户要求 AI 检查、上传或联调电视插件服务接口（`/hello`、`/status`、`/uploadSo`、`/uploadPlugin`）时，AI 必须遵循以下优先级：
146
+
147
+ 1. 优先使用已连接的 `quicktvui-ai-mcp` 插件工具：
148
+ - `plugin_server_check`
149
+ - `plugin_server_hello`
150
+ - `plugin_server_status`
151
+ - `plugin_upload_so`
152
+ - `plugin_upload_plugin`
153
+ 2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai plugin-*`
154
+ 3. 只有 MCP 和 CLI 都不可用时，才允许退回到手工 `adb` + `curl`
155
+
156
+ 推荐执行顺序：
157
+
158
+ 1. 先打开 Toolkit RESTful API
159
+ - CLI：`quicktvui-ai plugin-enable-api --device <serial>`
160
+ - 手工兜底：`adb -s <serial> shell am broadcast -a "eskit.sdk.core.ACTION_TOOLKIT_SETTING" --es "RESTFUL_API" "true"`
161
+ 2. 检查服务是否 ready
162
+ - MCP：`plugin_server_check`
163
+ - CLI：`quicktvui-ai plugin-check --device <serial>`
164
+ 3. 读取当前状态
165
+ - MCP：`plugin_server_status`
166
+ - CLI：`quicktvui-ai plugin-status --device <serial>`
167
+ 4. 解析插件服务地址
168
+ - 如果显式传了 `baseUrl` / `--plugin-base-url`，优先使用该地址
169
+ - 否则，如果 adb 已连接设备，先尝试使用该设备的插件服务地址
170
+ - 如果无法从目标设备推断 host，则改用 adb 端口转发和 `http://127.0.0.1:36366`
171
+ - 如果同时连接了多台 adb 设备，AI 必须要求用户选择 `serial` 或提供服务 IP / `baseUrl`
172
+ - 如果没有任何 adb 已连接设备，AI 必须向用户索要服务 IP / `baseUrl`，不得脑补或写死某个开发者自己的电视 IP
173
+ 5. 上传 So
174
+ - 必须根据当前插件服务对应设备的 `ro.product.cpu.abi` 选择匹配的 zip
175
+ - CLI：`quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
176
+ 6. 上传插件 APK
177
+ - CLI：`quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
178
+
179
+ 硬约束：
180
+
181
+ - 运行中接口返回永远优先于 markdown 文档。
182
+ - `/hello`、`/status`、`/uploadSo`、`/uploadPlugin` 必须使用 `POST` 探测，不能用 `GET` 判断服务是否可用。
183
+ - 如果 AI 正在 `quicktvui-ai` 仓库内工作，且文档与实机接口不一致，必须回写文档。
184
+ - `uploadSo` 目前存在 `pkg` / `tag` 字段漂移，AI 应同时传 `pkg` 和 `tag`，成功后以返回的 `data.tag` 为准。
185
+ - 默认测试标识固定为：
186
+ - So 包名 / tag：`eskit.so.ffmpeg.command`
187
+ - 插件包名：`eskit.plugin.imagequality`
188
+ - ABI 选择必须与当前插件服务对应设备的 `ro.product.cpu.abi` 一致，但只有上传 So 时才需要解析；若未显式传 `abi`，应优先让 CLI / MCP 在上传时按需补齐。
189
+ - 未收到 MCP 或 CLI 的成功响应前，不得宣称上传成功。
190
+ - 即使 `uploadPlugin` 返回 `registered: true`，`status.pluginList` 也可能仍为空；AI 必须如实说明，不得自行脑补安装状态。
191
+ - `uploadPlugin` 成功或 `registered: true` 只代表插件包已经上传到插件服务，不代表 Vue 页面已经可直接使用；如果任务要求在页面里实际调用插件，AI 还必须补齐 Vue 侧安装逻辑。
192
+ - 重新上传新的插件包后，当前宿主 / runtime 进程不会自动热更新到新字节码；在重新验证启动、注册或页面接入之前，AI 必须先重启宿主 / runtime 进程。
193
+ - 生成命令或说明前，应优先查阅以下包内文档：
194
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
195
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
196
+
197
+ ## Plugin Scaffold Workflow (CRITICAL)
198
+
199
+ 当用户要求 AI 创建、更新、打包 Android 插件工程，或生成原生模块 / 原生组件时，AI 必须遵循以下优先级：
200
+
201
+ 1. 优先使用已连接的 `quicktvui-ai-mcp`：
202
+ - `plugin_project_create`
203
+ - `plugin_project_build`
204
+ - `plugin_module_create`
205
+ - `plugin_component_create`
206
+ 2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai`：
207
+ - `plugin-create-project`
208
+ - `plugin-build`
209
+ - `plugin-create-module`
210
+ - `plugin-create-component`
211
+ 3. 只有 MCP 和 CLI 都不可用时，才允许手工创建或修改脚手架。
212
+
213
+ 决策规则：
214
+
215
+ 1. 工程初始化 / 更新 / 打包：使用 `plugin_project_create` / `plugin_project_build`
216
+ 2. 无独立原生 UI 的能力：使用 `plugin_module_create`
217
+ 3. 有原生 View、属性、事件或函数派发的能力：使用 `plugin_component_create`
218
+
219
+ 硬约束：
220
+
221
+ - 生成前应优先查阅以下包内文档：
222
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-project.md`
223
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-module.md`
224
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-component.md`
225
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md`
226
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
227
+ - `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
228
+ - `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
229
+ - 源码真值来自 `.source/sdk/base/...`，真实接口固定为：
230
+ - `com.quicktvui.sdk.base.module.IEsModule`
231
+ - `com.quicktvui.sdk.base.component.IEsComponent`
232
+ - `com.quicktvui.sdk.base.component.IEsComponentView`
233
+ - `com.quicktvui.sdk.base.component.EsComponentAttribute`
234
+ - 脚手架结构默认仍以 `.source/sdk/base/...` 为准，但目标设备运行时日志永远优先于默认命名空间。
235
+ - 如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或启动阶段提示缺失 `com.quicktvui.sdk.base.*` 相关类，AI 必须立刻把这视为运行时兼容性问题，而不是继续重复使用默认脚手架命名空间；应改为适配设备实际存在的运行时命名空间后重新构建、重传。
236
+ - 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，AI 必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应按设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径调整注册代码后重新构建、重传。
237
+ - AI 必须区分“本地 stub 可编译”和“设备运行时类真实存在”。如果插件能编译但在设备侧因 `EsProxy` 等类缺失而启动失败，这一版插件仍然判定为失败。
238
+ - 插件工程打包完成或插件服务上传成功，并不代表 Vue 侧已经完成安装。
239
+ - 如果页面需要实际使用插件，AI 必须在 Vue 侧使用 `@extscreen/es3-core` 的 `useESPlugin()` 补齐安装流程。
240
+ - AI 必须在 `onESCreate` 中添加插件监听，在 `onESDestroy` 中移除监听。
241
+ - 对于组件型插件，AI 应优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查组件是否已注册；若未注册，应先安装插件，再渲染或调用对应组件。
242
+ - 不允许把“插件已上传”误当成“页面里已经可直接使用”，也不允许在未监听安装完成前直接假设同步可用。
243
+ - 如果页面收到安装成功回调后，组件或模块注册仍然短暂不可见，AI 应允许一个简短的轮询复查窗口，再决定是否判定失败。
244
+ - 如果是为修复运行时兼容性而重新上传的新插件版本，AI 在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
245
+ - 创建工程后必须写入 `.kyy-plugin-project.json`
246
+ - 对于长期保留或准备发布的插件工程，默认应放在 `<project-root>/plugin/<plugin-name>` 这种项目根目录下的可见目录
247
+ - 不允许把插件工程默认放到 `.ai-test/*` 等隐藏目录或其他点前缀目录
248
+ - 若插件工程位于子目录且工作区根目录存在 `package.json`，必须注入 `build:android-plugin`
249
+ - 打包优先级固定为：
250
+ 1. `npm run build:android-plugin`
251
+ 2. `npm run build:plugin`
252
+ 3. `npm run build`
253
+ 4. `./gradlew assembleGeneralDebug`
254
+ - 如果插件构建报 Android SDK 缺失，AI 必须先按通用顺序探测 SDK：`ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> 当前平台默认 SDK 目录，然后再判断环境是否真的缺失。
255
+ - 如果已经探测到 SDK，且目标插件工程缺少 `local.properties` / `sdk.dir`，AI 可以让 CLI / MCP 只为当前开发机补齐这个本地文件。
256
+ - AI 不得把某个开发者本机的 Android SDK 路径写进共享规则、硬编码项目配置或提交到仓库。
257
+ - 生成 module / component 前，必须先获得明确功能描述
258
+ - Java 包名必须使用合法包段，不能把 `kebab-case` 直接写进包路径
259
+ - component 必须生成或更新 `docs/component/<kebab-name>.md`
260
+ - 组件标签必须使用 `kebab-case`
261
+ - 在 Vue `h()` 中禁止传完整 Java 包名，必须使用组件类名或约定标签名
262
+ - 如果能定位到 `Application`，应优先补 `EsProxy.get().registerModule(...)` / `EsProxy.get().registerComponent(...)`
263
+ - 如果文档与源码或实际实现不一致，AI 必须更新文档
264
+
118
265
  ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)
119
266
 
120
267
  AI 在编写业务逻辑时，极易带入传统 Web 开发习惯导致严重报错，**必须牢记以下框架特性**：
package/rules/GEMINI.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: GEMINI.md
3
- version: 1.1.14
3
+ version: 1.1.18
4
4
  ---
5
5
 
6
6
  # GEMINI.md - QuickTVUI AI 开发指南
@@ -106,6 +106,153 @@ Hard requirements:
106
106
  - If user asks to launch a specific ES app/version/source, run:
107
107
  `quicktvui-ai run-esapp --project <project-path> --pkg <es-package> [options]`
108
108
 
109
+ ## Runtime Debug Data Workflow (CRITICAL)
110
+
111
+ When the user asks AI to inspect runtime console logs, network/exception events, Android native logs, screenshots, or current target state, AI MUST use this priority:
112
+
113
+ 1. Prefer connected `@quicktvui/ai-debug-mcp`
114
+ 2. If MCP is unavailable but shell/CLI is available, use `quicktvui-ai debug-*`
115
+ 3. Only ask the user to paste logs manually when both MCP and CLI paths are unavailable
116
+
117
+ Required non-MCP order:
118
+
119
+ 1. `quicktvui-ai debug-targets --base-url http://127.0.0.1:38989`
120
+ 2. Resolve `clientId`
121
+ - use directly when only one target exists
122
+ - ask the user to confirm when multiple targets exist
123
+ 3. `quicktvui-ai debug-context --client-id <clientId>`
124
+ 4. `quicktvui-ai debug-events --client-id <clientId> --limit 100`
125
+ 5. `quicktvui-ai debug-native-logs --client-id <clientId> --limit 100`
126
+ 6. `quicktvui-ai debug-screenshot --client-id <clientId> --project <project-path>`
127
+
128
+ Hard requirements:
129
+
130
+ - AI MUST NOT claim it inspected runtime data unless MCP or `quicktvui-ai debug-*` actually returned that data
131
+ - If `debug-targets` is empty, AI MUST say that `ESDebugServer /ai/targets` is still empty
132
+ - If `debug-native-logs` or `debug-screenshot` fails, AI MUST report the real command/error instead of inventing fallback observations
133
+
134
+ ## Plugin Server Workflow (CRITICAL)
135
+
136
+ When the user asks AI to inspect, upload, or debug TV plugin server endpoints (`/hello`, `/status`, `/uploadSo`, `/uploadPlugin`):
137
+
138
+ 1. Prefer connected `quicktvui-ai-mcp` plugin tools:
139
+ - `plugin_server_check`
140
+ - `plugin_server_hello`
141
+ - `plugin_server_status`
142
+ - `plugin_upload_so`
143
+ - `plugin_upload_plugin`
144
+ 2. Otherwise use `quicktvui-ai plugin-*`
145
+ 3. Only fall back to manual `adb` + `curl` when neither MCP nor CLI execution is available
146
+
147
+ Required order:
148
+
149
+ 1. Enable Toolkit RESTful API first
150
+ - CLI: `quicktvui-ai plugin-enable-api --device <serial>`
151
+ - Manual fallback: `adb -s <serial> shell am broadcast -a "eskit.sdk.core.ACTION_TOOLKIT_SETTING" --es "RESTFUL_API" "true"`
152
+ 2. Probe readiness
153
+ - MCP: `plugin_server_check`
154
+ - CLI: `quicktvui-ai plugin-check --device <serial>`
155
+ 3. Read current state
156
+ - MCP: `plugin_server_status`
157
+ - CLI: `quicktvui-ai plugin-status --device <serial>`
158
+ 4. Resolve plugin server address
159
+ - If `baseUrl` / `--plugin-base-url` is explicitly provided, use it
160
+ - Otherwise, if adb already has a connected target, use that target's plugin service address first
161
+ - If the target host cannot be inferred, use adb port forward and `http://127.0.0.1:36366`
162
+ - If multiple adb devices are connected, AI MUST ask the user to choose `serial` or provide service IP / `baseUrl`
163
+ - If no adb-connected device exists, AI MUST ask the user for service IP / `baseUrl`, and MUST NOT invent a developer-specific TV IP
164
+ 5. Upload So zip
165
+ - choose the archive that matches `ro.product.cpu.abi` on the device behind the current plugin service
166
+ - CLI: `quicktvui-ai plugin-upload-so --device <serial> --tag eskit.so.ffmpeg.command --pkg eskit.so.ffmpeg.command --file <zip-path>`
167
+ 6. Upload plugin APK
168
+ - CLI: `quicktvui-ai plugin-upload-plugin --device <serial> --pkg eskit.plugin.imagequality --file <apk-path>`
169
+
170
+ Hard requirements:
171
+
172
+ - Runtime endpoint behavior overrides markdown docs.
173
+ - Probe `/hello`, `/status`, `/uploadSo`, `/uploadPlugin` with `POST`, not `GET`.
174
+ - When AI is editing the `quicktvui-ai` repo itself and finds doc/runtime drift, AI MUST update docs.
175
+ - `uploadSo` currently shows `pkg` / `tag` drift. AI SHOULD send both `pkg` and `tag`, and trust `data.tag` in successful responses.
176
+ - Default demo identifiers:
177
+ - So package/tag: `eskit.so.ffmpeg.command`
178
+ - Plugin package: `eskit.plugin.imagequality`
179
+ - 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.
180
+ - AI MUST NOT claim upload success unless MCP or CLI returned a success payload.
181
+ - `status.pluginList` may still be empty even after `uploadPlugin` returns `registered: true`; AI MUST report that exact state.
182
+ - `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.
183
+ - 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.
184
+ - AI SHOULD consult:
185
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-server-api.md`
186
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-server.md`
187
+
188
+ ## Plugin Scaffold Workflow (CRITICAL)
189
+
190
+ 当用户要求 AI 创建、更新、打包 Android 插件工程，或生成原生模块 / 原生组件时，AI 必须遵循以下优先级：
191
+
192
+ 1. 优先使用已连接的 `quicktvui-ai-mcp`：
193
+ - `plugin_project_create`
194
+ - `plugin_project_build`
195
+ - `plugin_module_create`
196
+ - `plugin_component_create`
197
+ 2. 如果没有 MCP，但具备 shell/CLI 能力，则必须使用 `quicktvui-ai`：
198
+ - `plugin-create-project`
199
+ - `plugin-build`
200
+ - `plugin-create-module`
201
+ - `plugin-create-component`
202
+ 3. 只有 MCP 和 CLI 都不可用时，才允许手工创建或修改脚手架。
203
+
204
+ 决策规则：
205
+
206
+ 1. 工程初始化 / 更新 / 打包：使用 `plugin_project_create` / `plugin_project_build`
207
+ 2. 无独立原生 UI 的能力：使用 `plugin_module_create`
208
+ 3. 有原生 View、属性、事件或函数派发的能力：使用 `plugin_component_create`
209
+
210
+ 硬约束：
211
+
212
+ - 生成前应优先查阅以下包内文档：
213
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-project.md`
214
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-module.md`
215
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/cli/plugin-create-component.md`
216
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/tool/api/plugin-scaffold-mcp.md`
217
+ - `node_modules/@quicktvui/ai/rules/.docs/zh-CN/module/plugin.md`
218
+ - `node_modules/@quicktvui/ai/rules/.docs/examples/module/plugin/es-basic.vue`
219
+ - `node_modules/@quicktvui/ai/rules/.source/quicktvui/src/long-image/index.vue`
220
+ - 源码真值来自 `.source/sdk/base/...`，真实接口固定为：
221
+ - `com.quicktvui.sdk.base.module.IEsModule`
222
+ - `com.quicktvui.sdk.base.component.IEsComponent`
223
+ - `com.quicktvui.sdk.base.component.IEsComponentView`
224
+ - `com.quicktvui.sdk.base.component.EsComponentAttribute`
225
+ - 脚手架结构默认仍以 `.source/sdk/base/...` 为准，但目标设备运行时日志永远优先于默认命名空间。
226
+ - 如果设备日志出现 `ClassNotFoundException: com.quicktvui.sdk.base.core.EsProxy`，或启动阶段提示缺失 `com.quicktvui.sdk.base.*` 相关类，AI 必须把这视为运行时兼容性问题，改为适配设备实际存在的运行时命名空间后再重新构建、重传。
227
+ - 如果设备日志出现 `java.lang.NoSuchMethodError: No static method get()Leskit/sdk/support/core/EsProxy;`，AI 必须把它视为插件注册入口的字节码签名不兼容，而不是页面逻辑问题；应改为匹配设备真实 runtime 的 `EsProxy.get()` 签名 / 调用路径后重新构建、重传。
228
+ - AI 必须区分“本地 stub 可编译”和“设备运行时类真实存在”。如果插件能编译但在设备侧因 `EsProxy` 等类缺失而启动失败，这一版插件仍然判定为失败。
229
+ - 插件工程打包完成或插件服务上传成功，并不代表 Vue 侧已经完成安装。
230
+ - 如果页面需要实际使用插件，AI 必须在 Vue 侧使用 `@extscreen/es3-core` 的 `useESPlugin()` 补齐安装流程。
231
+ - AI 必须在 `onESCreate` 中添加插件监听，在 `onESDestroy` 中移除监听。
232
+ - 对于组件型插件，AI 应优先使用 `useES().isComponentRegistered("<组件完整类名>")` 检查组件是否已注册；若未注册，应先安装插件，再渲染或调用对应组件。
233
+ - 不允许把“插件已上传”误当成“页面里已经可直接使用”，也不允许在未监听安装完成前直接假设同步可用。
234
+ - 如果页面收到安装成功回调后，组件或模块注册仍然短暂不可见，AI 应允许一个简短的轮询复查窗口，再决定是否判定失败。
235
+ - 如果是为修复运行时兼容性而重新上传的新插件版本，AI 在复测前必须先重启宿主 / runtime 进程，否则当前进程仍可能持有旧插件字节码。
236
+ - 创建工程后必须写入 `.kyy-plugin-project.json`
237
+ - 对于长期保留或准备发布的插件工程，默认应放在 `<project-root>/plugin/<plugin-name>` 这种项目根目录下的可见目录
238
+ - 不允许把插件工程默认放到 `.ai-test/*` 等隐藏目录或其他点前缀目录
239
+ - 若插件工程位于子目录且工作区根目录存在 `package.json`，必须注入 `build:android-plugin`
240
+ - 打包优先级固定为：
241
+ 1. `npm run build:android-plugin`
242
+ 2. `npm run build:plugin`
243
+ 3. `npm run build`
244
+ 4. `./gradlew assembleGeneralDebug`
245
+ - 如果插件构建报 Android SDK 缺失，AI 必须先按通用顺序探测 SDK：`ANDROID_SDK_ROOT` -> `ANDROID_HOME` -> 当前平台默认 SDK 目录，然后再判断环境是否真的缺失。
246
+ - 如果已经探测到 SDK，且目标插件工程缺少 `local.properties` / `sdk.dir`，AI 可以让 CLI / MCP 只为当前开发机补齐这个本地文件。
247
+ - AI 不得把某个开发者本机的 Android SDK 路径写进共享规则、硬编码项目配置或提交到仓库。
248
+ - 生成 module / component 前，必须先获得明确功能描述
249
+ - Java 包名必须使用合法包段，不能把 `kebab-case` 直接写进包路径
250
+ - component 必须生成或更新 `docs/component/<kebab-name>.md`
251
+ - 组件标签必须使用 `kebab-case`
252
+ - 在 Vue `h()` 中禁止传完整 Java 包名，必须使用组件类名或约定标签名
253
+ - 如果能定位到 `Application`，应优先补 `EsProxy.get().registerModule(...)` / `EsProxy.get().registerComponent(...)`
254
+ - 如果文档与源码或实际实现不一致，AI 必须更新文档
255
+
109
256
  ---
110
257
 
111
258
  ## 🔥 核心架构避坑指南 (ARCHITECTURAL GOTCHAS)