@qomicex/cli 0.1.1 → 0.1.2

package/skills/qomicex-plugin/permissions.md

@@ -1,98 +1,98 @@
-# 权限目录与最小权限原则
-
-权限目录源：`src/plugins/types.ts` 的 `PERMISSION_CATALOG`（启动器）与 `packages/qomicex-cli/src/lib/permissions.ts`（CLI verify，两者一致）。方法→权限映射源：CLI `src/lib/permissions.ts` 的 `METHOD_PERMISSIONS` 表（与 `src/plugins/sandbox.ts` 一致）。
-
-## 风险分级
-
-| 级别 | 含义 | 安装详情弹窗视觉 |
-|------|------|------|
-| `normal` | 只读 / 低影响 | 蓝 |
-| `warning` | 写操作 / 网络 / 进程类 | 黄 |
-| `danger` | 系统命令 / 文件写 / 装插件 | 红 |
-
-**最小权限原则**：只声明真正用到的权限。`qomicex verify` 会扫描源码实际调用的桥方法（按 `METHOD_PERMISSIONS` 表），**声明了未用到的 → 报错；用了没声明的 → 报错**。因此 AI 生成插件时务必按"最终调用了哪些 API"反推权限集合，宁可少而准。
-
-## 完整权限目录（39 项）
-
-| 权限 ID | 风险 | 用途 |
-|---------|------|------|
-| `instance:read` | normal | 读取实例列表 |
-| `instance:write` | warning | 创建/修改/删除实例（含安装整合包） |
-| `account:read` | normal | 读取账号列表 |
-| `license:read` | normal | 读取许可证信息 |
-| `config:read` | normal | 读取启动器配置 / 插件配置 |
-| `config:write` | warning | 修改启动器配置 / 插件配置 |
-| `cache:access` | normal | 读写插件缓存 |
-| `endpoint:discover` | normal | 获取后端 API 端点 |
-| `page:list` | normal | 获取页面列表 |
-| `network:fetch` | warning | 调用后端 API（callBackend）/ 插件互调 |
-| `network:cors_proxy` | warning | CORS 代理请求（proxyFetch / proxyFetchStream） |
-| `network:websocket` | warning | WebSocket 连接 |
-| `network:proxy` | warning | 修改代理设置 |
-| `ui:inject_sidebar` | normal | 注入侧边栏菜单 |
-| `ui:inject_settings` | normal | 注入设置页 |
-| `ui:picture_in_picture` | warning | 画中画窗口 |
-| `ui:sub_window` | warning | 独立子窗口 / 悬浮窗 |
-| `ui:context_menu` | normal | 注入右键菜单 |
-| `ui:toast` | normal | 应用内 toast 通知 |
-| `ui:navigate` | normal | 跳转页面 |
-| `system:info` | normal | 读取系统和启动器信息 |
-| `system:notification` | normal | 发送系统通知 / 打开外链 |
-| `clipboard:read` | warning | 读取剪贴板 |
-| `clipboard:write` | warning | 写入剪贴板 |
-| `wasm:execute` | warning | 执行 WASM 模块（callWasm） |
-| `plugin:install` | danger | 安装/卸载/更新插件 |
-| `plugin:list` | normal | 读取已安装插件列表 |
-| `resource:read` | normal | 读取游戏资源文件 |
-| `resource:write` | warning | 写入游戏资源文件 |
-| `java:manage` | warning | 管理 Java 运行时 |
-| `download:manage` | warning | 管理下载中心任务 |
-| `game:process` | warning | 启停游戏进程 |
-| `game:log` | normal | 检测游戏日志 |
-| `connector:host` | warning | 启停联机 |
-| `connector:scan` | normal | 扫描局域网联机 |
-| `shell:execute` | danger | 执行系统命令 |
-| `filesystem:read` | warning | 读取文件系统 |
-| `filesystem:write` | danger | 写入/删除文件系统 |
-| （例外）`addMenuItem` | — | 动态注册侧边栏菜单，**无需声明权限** |
-
-## 方法 → 权限映射（生成权限列表时照此反推）
-
-| API 方法 | 所需权限 |
-|----------|----------|
-| `getSettings` | `config:read` |
-| `setSettings`、`registerMethod` | `config:write` |
-| `getCache` / `setCache` | `cache:access` |
-| `callBackend`、`callPlugin` | `network:fetch` |
-| `proxyFetch` / `proxyFetchStream` | `network:cors_proxy` |
-| `uploadPlugin` | `plugin:install` |
-| `callWasm` / `listWasmPlugins` | `wasm:execute` |
-| `readText` / `readBytes` | `filesystem:read` |
-| `writeText` / `writeBytes` / `deleteFile` | `filesystem:write` |
-| `execCommand` | `shell:execute` |
-| `navigate` | `config:read` |
-| `showToast` | `ui:toast` |
-| `getSystemInfo` | `system:info` |
-| `openUrl` | `system:notification` |
-| `listPlugins` | `plugin:list` |
-| `overlay.*`（create/show/hide/destroy/setHtml/setPosition） | `ui:sub_window` |
-| `download.addTask` / `.progress` / `.cancel` / `.list` | `download:manage` |
-| `download.registerInstall` | `instance:write` |
-| `modpack.install` | `instance:write` |
-| `addMenuItem` | 无需权限 |
-
-## 常见权限组合
-
-- **纯 UI 插件**（模板默认）：`config:read` + `ui:toast` + `network:cors_proxy`。
-- 需要联网的插件：`network:cors_proxy`（外网请求）或 `network:fetch`（调启动器后端）。
-- 需要持久化自己的配置：加 `config:write`（配合 `getSettings`/`setSettings`）。
-- 需要文件读写：`filesystem:read`（读）或 `filesystem:write`（写/删，danger）。文件访问是**授权制**——首次访问用户弹窗确认，按路径前缀持久化。
-
-## 模板默认 manifest
-
-```json
-{
-  "layers": ["l2"],
-  "permissions": ["config:read", "ui:toast", "network:cors_proxy"]
-}
-```
+# 权限目录与最小权限原则
+
+权限目录源：`src/plugins/types.ts` 的 `PERMISSION_CATALOG`（启动器）与 `packages/qomicex-cli/src/lib/permissions.ts`（CLI verify，两者一致）。方法→权限映射源：CLI `src/lib/permissions.ts` 的 `METHOD_PERMISSIONS` 表（与 `src/plugins/sandbox.ts` 一致）。
+
+## 风险分级
+
+| 级别 | 含义 | 安装详情弹窗视觉 |
+|------|------|------|
+| `normal` | 只读 / 低影响 | 蓝 |
+| `warning` | 写操作 / 网络 / 进程类 | 黄 |
+| `danger` | 系统命令 / 文件写 / 装插件 | 红 |
+
+**最小权限原则**：只声明真正用到的权限。`qomicex verify` 会扫描源码实际调用的桥方法（按 `METHOD_PERMISSIONS` 表），**声明了未用到的 → 报错；用了没声明的 → 报错**。因此 AI 生成插件时务必按"最终调用了哪些 API"反推权限集合，宁可少而准。
+
+## 完整权限目录（39 项）
+
+| 权限 ID | 风险 | 用途 |
+|---------|------|------|
+| `instance:read` | normal | 读取实例列表 |
+| `instance:write` | warning | 创建/修改/删除实例（含安装整合包） |
+| `account:read` | normal | 读取账号列表 |
+| `license:read` | normal | 读取许可证信息 |
+| `config:read` | normal | 读取启动器配置 / 插件配置 |
+| `config:write` | warning | 修改启动器配置 / 插件配置 |
+| `cache:access` | normal | 读写插件缓存 |
+| `endpoint:discover` | normal | 获取后端 API 端点 |
+| `page:list` | normal | 获取页面列表 |
+| `network:fetch` | warning | 调用后端 API（callBackend）/ 插件互调 |
+| `network:cors_proxy` | warning | CORS 代理请求（proxyFetch / proxyFetchStream） |
+| `network:websocket` | warning | WebSocket 连接 |
+| `network:proxy` | warning | 修改代理设置 |
+| `ui:inject_sidebar` | normal | 注入侧边栏菜单 |
+| `ui:inject_settings` | normal | 注入设置页 |
+| `ui:picture_in_picture` | warning | 画中画窗口 |
+| `ui:sub_window` | warning | 独立子窗口 / 悬浮窗 |
+| `ui:context_menu` | normal | 注入右键菜单 |
+| `ui:toast` | normal | 应用内 toast 通知 |
+| `ui:navigate` | normal | 跳转页面 |
+| `system:info` | normal | 读取系统和启动器信息 |
+| `system:notification` | normal | 发送系统通知 / 打开外链 |
+| `clipboard:read` | warning | 读取剪贴板 |
+| `clipboard:write` | warning | 写入剪贴板 |
+| `wasm:execute` | warning | 执行 WASM 模块（callWasm） |
+| `plugin:install` | danger | 安装/卸载/更新插件 |
+| `plugin:list` | normal | 读取已安装插件列表 |
+| `resource:read` | normal | 读取游戏资源文件 |
+| `resource:write` | warning | 写入游戏资源文件 |
+| `java:manage` | warning | 管理 Java 运行时 |
+| `download:manage` | warning | 管理下载中心任务 |
+| `game:process` | warning | 启停游戏进程 |
+| `game:log` | normal | 检测游戏日志 |
+| `connector:host` | warning | 启停联机 |
+| `connector:scan` | normal | 扫描局域网联机 |
+| `shell:execute` | danger | 执行系统命令 |
+| `filesystem:read` | warning | 读取文件系统 |
+| `filesystem:write` | danger | 写入/删除文件系统 |
+| （例外）`addMenuItem` | — | 动态注册侧边栏菜单，**无需声明权限** |
+
+## 方法 → 权限映射（生成权限列表时照此反推）
+
+| API 方法 | 所需权限 |
+|----------|----------|
+| `getSettings` | `config:read` |
+| `setSettings`、`registerMethod` | `config:write` |
+| `getCache` / `setCache` | `cache:access` |
+| `callBackend`、`callPlugin` | `network:fetch` |
+| `proxyFetch` / `proxyFetchStream` | `network:cors_proxy` |
+| `uploadPlugin` | `plugin:install` |
+| `callWasm` / `listWasmPlugins` | `wasm:execute` |
+| `readText` / `readBytes` | `filesystem:read` |
+| `writeText` / `writeBytes` / `deleteFile` | `filesystem:write` |
+| `execCommand` | `shell:execute` |
+| `navigate` | `config:read` |
+| `showToast` | `ui:toast` |
+| `getSystemInfo` | `system:info` |
+| `openUrl` | `system:notification` |
+| `listPlugins` | `plugin:list` |
+| `overlay.*`（create/show/hide/destroy/setHtml/setPosition） | `ui:sub_window` |
+| `download.addTask` / `.progress` / `.cancel` / `.list` | `download:manage` |
+| `download.registerInstall` | `instance:write` |
+| `modpack.install` | `instance:write` |
+| `addMenuItem` | 无需权限 |
+
+## 常见权限组合
+
+- **纯 UI 插件**（模板默认）：`config:read` + `ui:toast` + `network:cors_proxy`。
+- 需要联网的插件：`network:cors_proxy`（外网请求）或 `network:fetch`（调启动器后端）。
+- 需要持久化自己的配置：加 `config:write`（配合 `getSettings`/`setSettings`）。
+- 需要文件读写：`filesystem:read`（读）或 `filesystem:write`（写/删，danger）。文件访问是**授权制**——首次访问用户弹窗确认，按路径前缀持久化。
+
+## 模板默认 manifest
+
+```json
+{
+  "layers": ["l2"],
+  "permissions": ["config:read", "ui:toast", "network:cors_proxy"]
+}
+```

package/skills/qomicex-plugin/plugin-api.md

@@ -1,113 +1,113 @@
-# 桥 API 签名速查
-
-插件脚本通过全局 `window.__PLUGIN_API__` 与启动器交互。L2 iframe 沙箱 / 内联渲染均可用；独立 `pnpm dev`（浏览器直开）时优雅降级为 `null`。
-
-完整文档见 `D:\docs\docs\plugins\plugin-api.md`（启动器公开文档，内容更全含完整示例与错误码）。
-
-## 全局变量
-
-| 变量 | 说明 |
-|------|------|
-| `window.__PLUGIN_API__` | 桥 API 对象（`null` = 浏览器直开，优雅降级） |
-| `window.__PLUGIN_API_BASE__` | L2 沙箱内自动注入，值为 `http://localhost:5000/api/plugins/{id}/files`，用于拼包内资源地址 |
-| `window.__PLUGIN_ID__` | 当前插件 id |
-
-## 调用方式
-
-```ts
-const api = window.__PLUGIN_API__
-
-// ① 通用 call（绝大多数方法）
-const data = await api.call('getSettings')
-
-// ② 3 个专用快捷方式
-api.registerMethod('name', fn)                          // 注册方法
-await api.callPlugin('id', 'method', ...args)            // 调用其他插件方法
-await api.proxyFetchStream(req, { onChunk, onError })   // 流式请求
-```
-
-## 方法签名速查
-
-| 方法 | 签名 | 所需权限 |
-|------|------|----------|
-| **getSettings** | `call('getSettings') → Record<string, unknown>` | `config:read` |
-| **setSettings** | `call('setSettings', key, value)` | `config:write` |
-| **setCache** | `call('setCache', key, value, ttlSeconds?)` | `cache:access` |
-| **getCache** | `call('getCache', key) → any \| null` | `cache:access` |
-| **callBackend** | `call('callBackend', endpoint, data?) → any` | `network:fetch` |
-| | 有 data → POST；无 data → GET。data 可传 `_method` 覆盖 HTTP 方法 | |
-| **proxyFetch** | `call('proxyFetch', { url, method?, headers?, body?, timeoutMs? }) → { status, headers, body?, bodyBase64? }` | `network:cors_proxy` |
-| | SSRF 防护：仅 http/https，禁止内网地址 | |
-| **proxyFetchStream** | `proxyFetchStream(req, { onChunk, onError })` | `network:cors_proxy` |
-| | 消费 SSE 流，逐块回调。`req.signal` 可传 AbortSignal 中断 | |
-| **registerMethod** | `registerMethod(name, fn)` | `config:write` |
-| | 注册方法到全局注册表，供其他插件 `callPlugin` 调用。插件停用时自动注销 | |
-| **callPlugin** | `callPlugin(pluginId, method, ...args) → any` | `network:fetch` |
-| | 目标未安装/未激活/未注册方法 → reject | |
-| **callWasm** | `call('callWasm', pluginId, exportName?) → { ok, result }` | `wasm:execute` |
-| | 调用 L3 WASM 插件导出函数，缺省 `on_load` | |
-| **listWasmPlugins** | `call('listWasmPlugins') → string[]` | `wasm:execute` |
-| **readText** | `call('readText', path, options?) → { path, content }` | `filesystem:read` |
-| | `options: { start?, length? }`。授权制（首次访问用户弹窗确认） | |
-| **readBytes** | `call('readBytes', path, options?) → { path, contentBase64 }` | `filesystem:read` |
-| | 同 readText 授权制 | |
-| **writeText** | `call('writeText', path, content) → { path }` | `filesystem:write` |
-| | 授权制，自动创建父目录 | |
-| **writeBytes** | `call('writeBytes', path, bytes: Uint8Array) → { path }` | `filesystem:write` |
-| | 授权制，自动创建父目录 | |
-| **deleteFile** | `call('deleteFile', path) → { path }` | `filesystem:write` |
-| | 仅文件不支持目录；授权制 | |
-| **execCommand** | `call('execCommand', command, timeoutMs?) → { exitCode, stdout, stderr }` | `shell:execute` |
-| | Windows → powershell，Unix → /bin/sh。默认超时 15s，范围 1-120s | |
-| **getSystemInfo** | `call('getSystemInfo') → { Os, Architecture, LauncherVersion, ... }` | `system:info` |
-| **openUrl** | `call('openUrl', url)` | `system:notification` |
-| | 仅 http/https，沙箱内 window.open 被拦时应使用 | |
-| **listPlugins** | `call('listPlugins') → [{ id, name, version, status }]` | `plugin:list` |
-| **uploadPlugin** | `call('uploadPlugin', fileData: number[], fileName)` | `plugin:install` |
-| | 安装 .qplugin 包 | |
-| **navigate** | `call('navigate', path)` | `config:read` |
-| | 跳转启动器内部路由，勿用外部 URL | |
-| **showToast** | `call('showToast', message, type?)` | `ui:toast` |
-| | `type: 'info' \| 'error' \| 'success'`，默认 info | |
-| **overlay.create** | `call('overlay.create', { title?, html, x?, y?, width?, height?, minimizable?, resizable? }) → overlayId` | `ui:sub_window` |
-| **overlay.show/hide/destroy** | `call('overlay.show/hide/destroy', overlayId)` | `ui:sub_window` |
-| **overlay.setHtml** | `call('overlay.setHtml', overlayId, html)` | `ui:sub_window` |
-| **overlay.setPosition** | `call('overlay.setPosition', overlayId, x, y)` | `ui:sub_window` |
-| **download.addTask** | `call('download.addTask', { url, targetPath \| (instanceId, category, fileName), ... }) → { taskId }` | `download:manage` |
-| | 支持实例+类别自动解析隔离目录。`extract: true` 下载后自动解压 zip | |
-| **download.progress** | `call('download.progress', taskId) → snapshot \| null` | `download:manage` |
-| **download.cancel** | `call('download.cancel', taskId)` | `download:manage` |
-| **download.list** | `call('download.list') → snapshot[]` | `download:manage` |
-| **download.registerInstall** | `call('download.registerInstall', { instanceId, name, gameVersion, loader, loaderVersion })` | `instance:write` |
-| | 仅登记安装任务到下载中心，不创建真实下载 | |
-| **modpack.install** | `call('modpack.install', { id, gameDir, path | (type, projectId, fileId), ... }) → { instanceId }` | `instance:write` |
-| | 一键安装整合包（本地 zip / mrpack 或在线 Modrinth/CurseForge/FTB） | |
-| **addMenuItem** | `addMenuItem(item: PluginMenuItem)` | 无需权限 |
-| | 运行时动态注册侧边栏菜单项，停用时自动移除 | |
-
-## error 处理
-
-```ts
-try {
-  await api.call('getSettings')
-} catch (e) {
-  console.error(e.message)
-  // 常见错误:
-  // "Permission denied: requires xxx" —— manifest 权限未包含
-  // "Backend error: 404" —— callBackend 端点不存在
-  // "Proxy failed: 400" —— proxyFetch 参数错误（含 SSRF 拦截）
-  // "插件 xxx 未提供方法 yyy" —— callPlugin 目标不可用
-}
-```
-
-## 文件拖放事件
-
-主窗口广播 `file-drop` 事件（`DragDrop::Drop` 触发），payload = 文件绝对路径数组。沙箱插件需经主界面中转：主界面监听后 `callPlugin(pluginId, method, paths)` 转发。
-
-## 模板 api.ts
-
-模板项目 `src/api.ts` 提供了 `getApi()` 和 `getPluginId()` 辅助函数（使用 `window.__PLUGIN_API__` / `window.__PLUGIN_ID__`）：
-```ts
-import { getApi, getPluginId } from './api.ts'
-const api = getApi()  // null if browser direct
+# 桥 API 签名速查
+
+插件脚本通过全局 `window.__PLUGIN_API__` 与启动器交互。L2 iframe 沙箱 / 内联渲染均可用；独立 `pnpm dev`（浏览器直开）时优雅降级为 `null`。
+
+完整文档见 `D:\docs\docs\plugins\plugin-api.md`（启动器公开文档，内容更全含完整示例与错误码）。
+
+## 全局变量
+
+| 变量 | 说明 |
+|------|------|
+| `window.__PLUGIN_API__` | 桥 API 对象（`null` = 浏览器直开，优雅降级） |
+| `window.__PLUGIN_API_BASE__` | L2 沙箱内自动注入，值为 `http://localhost:5000/api/plugins/{id}/files`，用于拼包内资源地址 |
+| `window.__PLUGIN_ID__` | 当前插件 id |
+
+## 调用方式
+
+```ts
+const api = window.__PLUGIN_API__
+
+// ① 通用 call（绝大多数方法）
+const data = await api.call('getSettings')
+
+// ② 3 个专用快捷方式
+api.registerMethod('name', fn)                          // 注册方法
+await api.callPlugin('id', 'method', ...args)            // 调用其他插件方法
+await api.proxyFetchStream(req, { onChunk, onError })   // 流式请求
+```
+
+## 方法签名速查
+
+| 方法 | 签名 | 所需权限 |
+|------|------|----------|
+| **getSettings** | `call('getSettings') → Record<string, unknown>` | `config:read` |
+| **setSettings** | `call('setSettings', key, value)` | `config:write` |
+| **setCache** | `call('setCache', key, value, ttlSeconds?)` | `cache:access` |
+| **getCache** | `call('getCache', key) → any \| null` | `cache:access` |
+| **callBackend** | `call('callBackend', endpoint, data?) → any` | `network:fetch` |
+| | 有 data → POST；无 data → GET。data 可传 `_method` 覆盖 HTTP 方法 | |
+| **proxyFetch** | `call('proxyFetch', { url, method?, headers?, body?, timeoutMs? }) → { status, headers, body?, bodyBase64? }` | `network:cors_proxy` |
+| | SSRF 防护：仅 http/https，禁止内网地址 | |
+| **proxyFetchStream** | `proxyFetchStream(req, { onChunk, onError })` | `network:cors_proxy` |
+| | 消费 SSE 流，逐块回调。`req.signal` 可传 AbortSignal 中断 | |
+| **registerMethod** | `registerMethod(name, fn)` | `config:write` |
+| | 注册方法到全局注册表，供其他插件 `callPlugin` 调用。插件停用时自动注销 | |
+| **callPlugin** | `callPlugin(pluginId, method, ...args) → any` | `network:fetch` |
+| | 目标未安装/未激活/未注册方法 → reject | |
+| **callWasm** | `call('callWasm', pluginId, exportName?) → { ok, result }` | `wasm:execute` |
+| | 调用 L3 WASM 插件导出函数，缺省 `on_load` | |
+| **listWasmPlugins** | `call('listWasmPlugins') → string[]` | `wasm:execute` |
+| **readText** | `call('readText', path, options?) → { path, content }` | `filesystem:read` |
+| | `options: { start?, length? }`。授权制（首次访问用户弹窗确认） | |
+| **readBytes** | `call('readBytes', path, options?) → { path, contentBase64 }` | `filesystem:read` |
+| | 同 readText 授权制 | |
+| **writeText** | `call('writeText', path, content) → { path }` | `filesystem:write` |
+| | 授权制，自动创建父目录 | |
+| **writeBytes** | `call('writeBytes', path, bytes: Uint8Array) → { path }` | `filesystem:write` |
+| | 授权制，自动创建父目录 | |
+| **deleteFile** | `call('deleteFile', path) → { path }` | `filesystem:write` |
+| | 仅文件不支持目录；授权制 | |
+| **execCommand** | `call('execCommand', command, timeoutMs?) → { exitCode, stdout, stderr }` | `shell:execute` |
+| | Windows → powershell，Unix → /bin/sh。默认超时 15s，范围 1-120s | |
+| **getSystemInfo** | `call('getSystemInfo') → { Os, Architecture, LauncherVersion, ... }` | `system:info` |
+| **openUrl** | `call('openUrl', url)` | `system:notification` |
+| | 仅 http/https，沙箱内 window.open 被拦时应使用 | |
+| **listPlugins** | `call('listPlugins') → [{ id, name, version, status }]` | `plugin:list` |
+| **uploadPlugin** | `call('uploadPlugin', fileData: number[], fileName)` | `plugin:install` |
+| | 安装 .qplugin 包 | |
+| **navigate** | `call('navigate', path)` | `config:read` |
+| | 跳转启动器内部路由，勿用外部 URL | |
+| **showToast** | `call('showToast', message, type?)` | `ui:toast` |
+| | `type: 'info' \| 'error' \| 'success'`，默认 info | |
+| **overlay.create** | `call('overlay.create', { title?, html, x?, y?, width?, height?, minimizable?, resizable? }) → overlayId` | `ui:sub_window` |
+| **overlay.show/hide/destroy** | `call('overlay.show/hide/destroy', overlayId)` | `ui:sub_window` |
+| **overlay.setHtml** | `call('overlay.setHtml', overlayId, html)` | `ui:sub_window` |
+| **overlay.setPosition** | `call('overlay.setPosition', overlayId, x, y)` | `ui:sub_window` |
+| **download.addTask** | `call('download.addTask', { url, targetPath \| (instanceId, category, fileName), ... }) → { taskId }` | `download:manage` |
+| | 支持实例+类别自动解析隔离目录。`extract: true` 下载后自动解压 zip | |
+| **download.progress** | `call('download.progress', taskId) → snapshot \| null` | `download:manage` |
+| **download.cancel** | `call('download.cancel', taskId)` | `download:manage` |
+| **download.list** | `call('download.list') → snapshot[]` | `download:manage` |
+| **download.registerInstall** | `call('download.registerInstall', { instanceId, name, gameVersion, loader, loaderVersion })` | `instance:write` |
+| | 仅登记安装任务到下载中心，不创建真实下载 | |
+| **modpack.install** | `call('modpack.install', { id, gameDir, path | (type, projectId, fileId), ... }) → { instanceId }` | `instance:write` |
+| | 一键安装整合包（本地 zip / mrpack 或在线 Modrinth/CurseForge/FTB） | |
+| **addMenuItem** | `addMenuItem(item: PluginMenuItem)` | 无需权限 |
+| | 运行时动态注册侧边栏菜单项，停用时自动移除 | |
+
+## error 处理
+
+```ts
+try {
+  await api.call('getSettings')
+} catch (e) {
+  console.error(e.message)
+  // 常见错误:
+  // "Permission denied: requires xxx" —— manifest 权限未包含
+  // "Backend error: 404" —— callBackend 端点不存在
+  // "Proxy failed: 400" —— proxyFetch 参数错误（含 SSRF 拦截）
+  // "插件 xxx 未提供方法 yyy" —— callPlugin 目标不可用
+}
+```
+
+## 文件拖放事件
+
+主窗口广播 `file-drop` 事件（`DragDrop::Drop` 触发），payload = 文件绝对路径数组。沙箱插件需经主界面中转：主界面监听后 `callPlugin(pluginId, method, paths)` 转发。
+
+## 模板 api.ts
+
+模板项目 `src/api.ts` 提供了 `getApi()` 和 `getPluginId()` 辅助函数（使用 `window.__PLUGIN_API__` / `window.__PLUGIN_ID__`）：
+```ts
+import { getApi, getPluginId } from './api.ts'
+const api = getApi()  // null if browser direct
 ```

package/skills/qomicex-plugin/rules.md

@@ -1,46 +1,46 @@
-# AI 生成插件硬性规则
-
-AI agent 生成/修改插件时必须逐条遵守。违反任何一条都可能导致 `qomicex verify` 不通过或运行时错误。
-
-## manifest 校验
-
-1. **id 格式**：`^[a-z0-9]+([.-][a-z0-9]+)*$`，3-128 字符，**必须含至少一个点**（反向域名，如 `com.example.demo`）。大写字母、空格、连续双点 → error。
-2. **version**：严格 semver `数字.数字.数字`（可带 `-预发布` / `+构建号`），如 `0.1.0`、`1.2.0-beta.1`。
-3. **minLauncherVersion**：必填字符串。
-4. **layers**：至少一项，值 ∈ `l0`/`l1`/`l2`/`l3`。声明了 `entry.frontend` 但 layers 无 `l2`/`l3` → UI 无法渲染。
-5. **permissions**：值是权限目录 id。未知权限 → warning。
-6. **entry**：`frontend`/`backend`/`theme` 至少一个。`frontend` 应指向 `.html`（如 `dist/index.html`）。
-7. **render**：默认 `iframe`（沙箱），仅显式 `"inline"` 走内联渲染。对 UI 插件建议不做修改，保持 iframe 默认。
-
-## 权限
-
-8. **最小权限原则**：只声明真正用到的权限。`qomicex verify` 会扫描源码，声明未用 / 用了未声明**都会报错**。按"最终调用了哪些 API 方法"反推权限集合，从 `permissions.md` 的 `METHOD_PERMISSIONS` 表查对应的权限 id。
-9. **danger 权限**：`shell:execute`、`filesystem:write`、`plugin:install` 安装时红色提示，非必要不声明。
-10. **addMenuItem 无需权限**：`addMenuItem` 不要求 manifest 声明任何权限。
-
-## 代码
-
-11. **TS import 带扩展名**：Vite 强制要求，`import { foo } from './bar.ts'`，不得省略 `.ts`/`.tsx`。例外：目录 barrel（`index.ts`）可省略。
-12. **vite.config.ts 必须设 `base: './'`**：否则产物 `/assets/...` 被解析为站点根路径，插件白屏。
-13. **不使用 `<a>` 做内部导航**：内部路由用 `<Link>`（React Router），`<a>` 触发整页刷新丢失持久状态。外部链接用 `openUrl` / `callBackend('/system/open-url', { url })`。
-14. **沙箱内不用 `window.open`**：L2 iframe 的 `sandbox` 属性不含 `allow-popups`，`window.open` 被拦截。用 `openUrl` 方法或 `callBackend('/system/open-url', { url })`。
-15. **不用 `fetch` 请求外部 URL**：用 `proxyFetch`（非流式）或 `proxyFetchStream`（流式，SSE），两者自带 SSRF 防护（禁止内网）和 CORS 代理。
-16. **不虚构 API**：权限目录里有但桥 API 没有对应方法的能力（如 `clipboard:read`/`clipboard:write`、`network:websocket` 等当前无对应 `__PLUGIN_API__` 方法）不要臆造调用方式。以 `plugin-api.md` 列出的方法为准，不确定就标注「以代码为准」。
-
-## 主题
-
-17. **CSS 全用 `var(--*)`**：禁止 `#hex` / `rgb()` / `hsl()` 字面量。插件主题文件（`theme.css`）也只覆盖 `var()` token。
-18. **Tailwind 用语义类名**：`bg-primary`、`text-foreground`、`text-muted-foreground`、`bg-muted`、`border-border` 等（`@qomicex/plugin-ui/tailwind-preset` 已映射）。
-
-## 安全
-
-19. **禁止硬编码密钥**：插件源码 / manifest / package.json 不得包含 API key、token、密码。用户配置经 `setSettings`/`getSettings` 存取。
-20. **不滥用 `shell:execute`**：系统命令调用有 15s 超时（范围 1-120s），仅用于纯本地工具链，不传用户输入到 shell。
-21. **文件读写经授权制**：`filesystem:read`/`write` 首次访问未授权路径时用户弹窗确认，按路径前缀持久化。插件不能假设用户一定会授权。
-
-## 开发流程
-
-22. **生成项目用 `qomicex create`**：不要手写 `manifest.json` 和项目结构，从模板起步。
-23. **打包前必须 `qomicex verify`**：0 error 才算通过。warning 可接受但建议消除。
-24. **不触碰启动器核心代码**：插件只修改自己目录内的文件，不动 `src/`、`src-tauri/`、`src-backend/` 等。
+# AI 生成插件硬性规则
+
+AI agent 生成/修改插件时必须逐条遵守。违反任何一条都可能导致 `qomicex verify` 不通过或运行时错误。
+
+## manifest 校验
+
+1. **id 格式**：`^[a-z0-9]+([.-][a-z0-9]+)*$`，3-128 字符，**必须含至少一个点**（反向域名，如 `com.example.demo`）。大写字母、空格、连续双点 → error。
+2. **version**：严格 semver `数字.数字.数字`（可带 `-预发布` / `+构建号`），如 `0.1.0`、`1.2.0-beta.1`。
+3. **minLauncherVersion**：必填字符串。
+4. **layers**：至少一项，值 ∈ `l0`/`l1`/`l2`/`l3`。声明了 `entry.frontend` 但 layers 无 `l2`/`l3` → UI 无法渲染。
+5. **permissions**：值是权限目录 id。未知权限 → warning。
+6. **entry**：`frontend`/`backend`/`theme` 至少一个。`frontend` 应指向 `.html`（如 `dist/index.html`）。
+7. **render**：默认 `iframe`（沙箱），仅显式 `"inline"` 走内联渲染。对 UI 插件建议不做修改，保持 iframe 默认。
+
+## 权限
+
+8. **最小权限原则**：只声明真正用到的权限。`qomicex verify` 会扫描源码，声明未用 / 用了未声明**都会报错**。按"最终调用了哪些 API 方法"反推权限集合，从 `permissions.md` 的 `METHOD_PERMISSIONS` 表查对应的权限 id。
+9. **danger 权限**：`shell:execute`、`filesystem:write`、`plugin:install` 安装时红色提示，非必要不声明。
+10. **addMenuItem 无需权限**：`addMenuItem` 不要求 manifest 声明任何权限。
+
+## 代码
+
+11. **TS import 带扩展名**：Vite 强制要求，`import { foo } from './bar.ts'`，不得省略 `.ts`/`.tsx`。例外：目录 barrel（`index.ts`）可省略。
+12. **vite.config.ts 必须设 `base: './'`**：否则产物 `/assets/...` 被解析为站点根路径，插件白屏。
+13. **不使用 `<a>` 做内部导航**：内部路由用 `<Link>`（React Router），`<a>` 触发整页刷新丢失持久状态。外部链接用 `openUrl` / `callBackend('/system/open-url', { url })`。
+14. **沙箱内不用 `window.open`**：L2 iframe 的 `sandbox` 属性不含 `allow-popups`，`window.open` 被拦截。用 `openUrl` 方法或 `callBackend('/system/open-url', { url })`。
+15. **不用 `fetch` 请求外部 URL**：用 `proxyFetch`（非流式）或 `proxyFetchStream`（流式，SSE），两者自带 SSRF 防护（禁止内网）和 CORS 代理。
+16. **不虚构 API**：权限目录里有但桥 API 没有对应方法的能力（如 `clipboard:read`/`clipboard:write`、`network:websocket` 等当前无对应 `__PLUGIN_API__` 方法）不要臆造调用方式。以 `plugin-api.md` 列出的方法为准，不确定就标注「以代码为准」。
+
+## 主题
+
+17. **CSS 全用 `var(--*)`**：禁止 `#hex` / `rgb()` / `hsl()` 字面量。插件主题文件（`theme.css`）也只覆盖 `var()` token。
+18. **Tailwind 用语义类名**：`bg-primary`、`text-foreground`、`text-muted-foreground`、`bg-muted`、`border-border` 等（`@qomicex/plugin-ui/tailwind-preset` 已映射）。
+
+## 安全
+
+19. **禁止硬编码密钥**：插件源码 / manifest / package.json 不得包含 API key、token、密码。用户配置经 `setSettings`/`getSettings` 存取。
+20. **不滥用 `shell:execute`**：系统命令调用有 15s 超时（范围 1-120s），仅用于纯本地工具链，不传用户输入到 shell。
+21. **文件读写经授权制**：`filesystem:read`/`write` 首次访问未授权路径时用户弹窗确认，按路径前缀持久化。插件不能假设用户一定会授权。
+
+## 开发流程
+
+22. **生成项目用 `qomicex create`**：不要手写 `manifest.json` 和项目结构，从模板起步。
+23. **打包前必须 `qomicex verify`**：0 error 才算通过。warning 可接受但建议消除。
+24. **不触碰启动器核心代码**：插件只修改自己目录内的文件，不动 `src/`、`src-tauri/`、`src-backend/` 等。
 25. **不 git commit**：插件开发阶段不提交改动到仓库。