@qomicex/cli 0.1.0 → 0.1.2

package/README.md

@@ -62,6 +62,37 @@ qomicex publish --api http://127.0.0.1:8787/api/v1   # 本地商店（wrangler d
 4. 查找/创建插件记录（`/plugins/mine` → 无则 `POST /plugins`），确认后 `POST /plugins/:id/versions` multipart 上传。
 5. 成功后将签名包存为 `release/<id>-<version>.signed.qplugin` 供复验。
 
+## AI 辅助开发
+
+CLI 随包分发 **AI skill 包**（`skills/qomicex-plugin/`），供 AI agent（Claude / opencode / Cursor 等）在写插件时加载，获得准确且不过时的 manifest 字段、权限目录、桥 API 签名、主题 token、签名与调试流程——避免 AI 臆造字段。安装 CLI 后本地路径为 `node_modules/@qomicex/cli/skills/qomicex-plugin/`（npm 包内，随 `files` 分发）。
+
+`qomicex create` 默认**不自动复制** skill 包到项目目录（保持项目最小化）；需要时手动复制即可。
+
+在 AI 会话中这样用：
+
+```text
+你是 Qomicex 插件开发工程师。请先阅读 <CLI 安装路径>/skills/qomicex-plugin/SKILL.md
+（及其余分册，尤其 rules.md），然后帮我做一个「XXX」插件：
+1. qomicex create com.example.xxx 生成项目
+2. 实现功能（manifest / 权限 / API 签名以技能包文档为准，不臆造）
+3. qomicex verify 过 0 error
+4. qomicex pack 出包
+```
+
+skill 包结构：
+
+```text
+skills/qomicex-plugin/
+  SKILL.md            # 主文档：何时用、快速开始、常见错误
+  manifest-schema.md  # manifest.json 全字段 + layers + render + dependencies + contributes
+  permissions.md      # 权限目录（39 项，normal/warning/danger）+ 方法→权限映射
+  plugin-api.md       # 桥 API 签名速查（完整文档见 D:\docs\docs\plugins\plugin-api.md）
+  theme.md            # 三级语义 token + var() 消费约定
+  signing.md          # Ed25519 签名流程（生成密钥 → pack --key → publish）
+  debugging.md        # harness 热重载调试
+  rules.md            # AI 生成插件的硬性规则
+```
+
 ## 签名密钥
 
 生成 Ed25519 密钥对（PKCS#8 PEM 或 raw 32 字节 seed base64）：

package/dist/commands/bump.js

@@ -0,0 +1,30 @@
+// qomicex bump — 递增 manifest.json 版本号（major/minor/patch）。
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readManifestFile } from "../lib/project.js";
+import { fail, info } from "../lib/io.js";
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(-.+)?$/;
+export async function bumpCommand(opts) {
+    const manifestFile = join(process.cwd(), 'manifest.json');
+    if (!existsSync(manifestFile))
+        fail('当前目录不是插件项目（缺少 manifest.json）');
+    const manifest = readManifestFile(manifestFile);
+    const current = String(manifest.version ?? '');
+    const next = opts.version ?? (() => {
+        const m = SEMVER_RE.exec(current);
+        if (!m)
+            fail(`当前版本不是合法 semver: ${current}`);
+        const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+        if (opts.part === 'major')
+            return `${major + 1}.0.0`;
+        if (opts.part === 'patch')
+            return `${major}.${minor}.${patch + 1}`;
+        return `${major}.${minor + 1}.0`;
+    })();
+    if (!SEMVER_RE.test(next))
+        fail(`目标版本不是合法 semver: ${next}`);
+    manifest.version = next;
+    writeFileSync(manifestFile, JSON.stringify(manifest, null, 2) + '\n');
+    info(`✔ manifest.json version: ${current} → ${next}`);
+    return next;
+}

package/dist/index.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
-// qomicex CLI 入口：create / dev / pack / verify / publish
+// qomicex CLI 入口：create / dev / pack / verify / bump / publish
 import { createCommand } from "./commands/create.js";
 import { devCommand } from "./commands/dev.js";
 import { packCommand } from "./commands/pack.js";
 import { verifyCommand } from "./commands/verify.js";
 import { publishCommand } from "./commands/publish.js";
+import { bumpCommand } from "./commands/bump.js";
 import { fail } from "./lib/io.js";
-const VERSION = '0.1.0';
+import { createRequire } from 'node:module';
+// 版本号单一来源：package.json（bump 只改一处）
+const VERSION = createRequire(import.meta.url)('../package.json').version;
 function parseArgs(argv) {
     const positional = [];
     const options = {};
@@ -39,24 +42,26 @@ function parseArgs(argv) {
     return { command, positional, options };
 }
 function helpText() {
-    return `
-qomicex v${VERSION} — Qomicex 插件生态 CLI
-
-用法:
-  qomicex create <id>           从内置模板生成合法插件项目（Vite+React+TS+plugin-ui+tailwind）
-  qomicex dev [--port <n>]      起本地 Vite dev server + 生成 dev 源插件配置（默认 5173）
-  qomicex pack [--out-dir <d>] [--version <v>] [--key <k>] [--skip-build]
-                                构建并打 .qplugin（manifest.json 在 zip 根）
-  qomicex verify [--package <f>]
-                                manifest 合法性 + 权限最小化 + 长循环告警 + 签名检查
-  qomicex publish [--key <k>] [--slug <s>] [--changelog <c>] [--api <url>] [--org-id <id>] [--package <f>] [--yes]
-                                设备流登录 → 注册签名公钥 → 签名 → 上传到商店
-  qomicex --help | -h           显示帮助
-  qomicex --version | -v        显示版本
-
-环境变量:
-  QOMICEX_SIGN_KEY   签名私钥（PKCS#8 PEM 或 raw base64 seed），publish 必填
-  QOMICEX_STORE_API  商店 API base（默认 https://plugins.qomicex.top/api/v1）
+    return `
+qomicex v${VERSION} — Qomicex 插件生态 CLI
+
+用法:
+  qomicex create <id>           从内置模板生成合法插件项目（Vite+React+TS+plugin-ui+tailwind）
+  qomicex dev [--port <n>]      起本地 Vite dev server + 生成 dev 源插件配置（默认 5173）
+  qomicex pack [--out-dir <d>] [--version <v>] [--key <k>] [--skip-build]
+                                构建并打 .qplugin（manifest.json 在 zip 根）
+  qomicex verify [--package <f>]
+                                manifest 合法性 + 权限最小化 + 长循环告警 + 签名检查
+  qomicex bump <major|minor|patch> [--version <v>]
+                                递增 manifest.json 版本号（或 --version 直接指定）
+  qomicex publish [--key <k>] [--slug <s>] [--changelog <c>] [--api <url>] [--org-id <id>] [--package <f>] [--yes]
+                                设备流登录 → 注册签名公钥 → 签名 → 上传到商店
+  qomicex --help | -h           显示帮助
+  qomicex --version | -v        显示版本
+
+环境变量:
+  QOMICEX_SIGN_KEY   签名私钥（PKCS#8 PEM 或 raw base64 seed），publish 必填
+  QOMICEX_STORE_API  商店 API base（默认 https://plugins.qomicex.top/api/v1）
 `;
 }
 async function main() {
@@ -89,6 +94,12 @@ async function main() {
             case 'verify':
                 await verifyCommand({ package: typeof options['package'] === 'string' ? options['package'] : undefined });
                 break;
+            case 'bump':
+                await bumpCommand({
+                    part: positional[0] ?? 'minor',
+                    version: typeof options['version'] === 'string' ? options['version'] : undefined,
+                });
+                break;
             case 'publish':
                 await publishCommand({
                     key: typeof options['key'] === 'string' ? options['key'] : undefined,

package/dist/lib/manifest.js

@@ -3,7 +3,7 @@
 import { PERMISSION_CATALOG } from "./permissions.js";
 export const ID_RE = /^(?!.*\.\.)[a-z0-9]+([.-][a-z0-9]+)*$/;
 export const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
-export const LAYERS = ['l0', 'l1', 'l2', 'l3'];
+export const LAYERS = ['l0', 'l1', 'l2', 'l3', 'l4'];
 export function checkId(id) {
     const errs = [];
     if (typeof id !== 'string')
@@ -44,11 +44,11 @@ export function validateManifest(raw) {
                 add('error', 'layers', `未知 layer: ${String(l)}（可用 ${LAYERS.join('/')}）`);
         }
         const hasFrontend = !!m.entry?.frontend;
-        if (!m.layers.includes('l2') && !m.layers.includes('l3') && hasFrontend) {
-            add('warning', 'layers', '声明了 frontend 入口但 layers 无 l2/l3，将无法渲染 UI');
+        if (!m.layers.includes('l2') && !m.layers.includes('l3') && !m.layers.includes('l4') && hasFrontend) {
+            add('warning', 'layers', '声明了 frontend 入口但 layers 无 l2/l3/l4，将无法渲染 UI');
         }
-        if (!m.layers.includes('l2') && hasFrontend) {
-            add('warning', 'layers', 'UI 插件建议声明 l2（iframe 沙箱）');
+        if (!m.layers.includes('l2') && !m.layers.includes('l4') && hasFrontend) {
+            add('warning', 'layers', 'UI 插件建议声明 l2（iframe 沙箱）或 l4（独立 WebView 窗口）');
         }
     }
     if (!Array.isArray(m.permissions)) {
@@ -76,8 +76,8 @@ export function validateManifest(raw) {
     }
     if (m.dependencies !== undefined && !Array.isArray(m.dependencies))
         add('error', 'dependencies', 'dependencies 必须是数组');
-    if (m.render !== undefined && m.render !== 'inline' && m.render !== 'iframe') {
-        add('warning', 'render', "render 仅支持 'inline' / 'iframe'");
+    if (m.render !== undefined && m.render !== 'inline' && m.render !== 'iframe' && m.render !== 'webview') {
+        add('warning', 'render', "render 仅支持 'inline' / 'iframe' / 'webview'");
     }
     if (m.contributes !== undefined) {
         const c = m.contributes;

package/dist/lib/permissions.js

@@ -44,6 +44,7 @@ export const METHOD_PERMISSIONS = {
     registerMethod: 'config:write', callPlugin: 'network:fetch', callWasm: 'wasm:execute', listWasmPlugins: 'wasm:execute',
     readText: 'filesystem:read', readBytes: 'filesystem:read', writeText: 'filesystem:write', writeBytes: 'filesystem:write', deleteFile: 'filesystem:write', execCommand: 'shell:execute',
     navigate: 'config:read', showToast: 'ui:toast', getSystemInfo: 'system:info', openUrl: 'system:notification', listPlugins: 'plugin:list',
+    getThemeColor: 'config:read', applyThemeOverride: 'config:write', clearThemeOverride: 'config:write',
     'overlay.create': 'ui:sub_window', 'overlay.show': 'ui:sub_window', 'overlay.hide': 'ui:sub_window',
     'overlay.destroy': 'ui:sub_window', 'overlay.setHtml': 'ui:sub_window', 'overlay.setPosition': 'ui:sub_window',
     'download.addTask': 'download:manage', 'download.progress': 'download:manage', 'download.cancel': 'download:manage', 'download.list': 'download:manage', 'download.registerInstall': 'instance:write',

package/dist/lib/signature.js

@@ -8,7 +8,7 @@ export const SIGNATURE_FILE = 'signature.json';
 export const CERT_FILE = 'signature.cert.json';
 export const ALG = 'Ed25519';
 /** 商店签名根公钥（raw base64），与 launcher plugin_signature.rs ROOT_PUBLIC_KEY_B64 一致 */
-export const STORE_ROOT_PUBLIC_KEY_B64 = 'hNoXOazEkdTRoxBra8ABlCWXhy16S7rM5ZmEDa+GmnE=';
+export const STORE_ROOT_PUBLIC_KEY_B64 = 'sPKcrc6QR5gcOnQMdq21Jo3yqxN7Mbm61OYxZnKuHE0=';
 /** Ed25519 PKCS#8 DER 固定前缀（前 16 字节），后接 32 字节 seed */
 const ED25519_PKCS8_PREFIX = Uint8Array.from([0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20]);
 export function bytesToBase64(bytes) {

package/dist/lib/store.js

@@ -65,7 +65,7 @@ export async function fetchMinePlugins(base, token) {
 }
 /** 新建插件（store 返回 201 {plugin:{id}}），slug 占用抛 409。 */
 export async function createPlugin(base, token, input) {
-    const r = await request(base, '/plugins/', {
+    const r = await request(base, '/plugins', {
         method: 'POST',
         body: JSON.stringify({
             slug: input.slug,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qomicex/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",

package/skills/qomicex-plugin/SKILL.md

@@ -0,0 +1,65 @@
+# Qomicex 插件开发技能包（qomicex-plugin）
+
+面向 AI agent（Claude / opencode / Cursor 等）的 Qomicex 启动器插件（`.qplugin`）开发技能包，随 `@qomicex/cli` 分发。本技能把"生成合规插件"所需的全部事实（manifest 校验、权限目录、桥 API、主题 token、签名、调试）收敛到一个目录，避免 AI 臆造字段。
+
+## 何时使用
+
+用户要求**开发 / 修改 / 审查 / 打包 / 发布** Qomicex 启动器插件时加载本技能。判断依据：涉及 `manifest.json`、`__PLUGIN_API__`、`entry.frontend`、`contributes`、权限声明、`.qplugin` 打包等关键词。
+
+## 文件导航（建议全读，勿跳）
+
+| 文件 | 内容 |
+|------|------|
+| `manifest-schema.md` | manifest.json 全字段 + layers 语义 + render 默认 iframe + dependencies + contributes |
+| `permissions.md` | 权限目录（normal/warning/danger）+ 每个权限对应的桥 API 方法 |
+| `plugin-api.md` | 桥 API（`__PLUGIN_API__`）签名速查 |
+| `theme.md` | 主题语义 token 三级体系 + `var()` 消费约定 + 主题贡献 |
+| `signing.md` | Ed25519 签名流程（生成密钥 → pack --key → publish） |
+| `debugging.md` | harness 热重载调试 |
+| `rules.md` | AI 生成插件的硬性规则（必须逐条遵守） |
+
+## 完整流程（create → dev → verify → pack → publish）
+
+```bash
+# 1. 生成项目（id 需反向域名格式，如 com.example.demo）
+qomicex create com.example.demo
+
+# 2. 本地调试（仓库内自动进 harness，固定端口 1420；仓库外裸 Vite 默认 5173）
+cd com.example.demo && pnpm install && qomicex dev
+
+# 3. 校验（提交/打包前必跑，0 error 才算通过）
+qomicex verify
+
+# 4. 打包（tsc && vite build → release/<id>-<version>.qplugin）
+qomicex pack --version 0.2.0
+qomicex pack --key ./dev-key.pem   # 附签名（仅 signature.json；完整证书链走 publish）
+
+# 5. 发布（设备流登录 → 商店签发证书 → 签名 → 上传）
+export QOMICEX_SIGN_KEY=<私钥 base64/PEM>
+qomicex publish
+```
+
+## 常见错误与规避
+
+| 错误 | 规避 |
+|------|------|
+| `id` 不含点 / 大写 / 连续双点 | id 用 `^[a-z0-9]+([.-][a-z0-9]+)*$`，3-128 字符，含至少一个点 |
+| `version` 非 semver | 严格 `数字.数字.数字`（可带 `-预发布` / `+构建号`） |
+| `entry.frontend` 指向非 `.html` | `verify` 警告：frontend 应指向 `.html`（如 `dist/index.html`） |
+| 声明了 frontend 但 `layers` 无 `l2`/`l3` | 无法渲染 UI；UI 插件务必声明 `l2`（iframe 沙箱，默认推荐） |
+| 权限声明与源码调用不一致 | `verify` 会做权限最小化扫描，声明未用 / 用了未声明**都会报错** |
+| 相对 import 不带扩展名 | Vite 强制：`import { x } from './api.ts'`，漏 `.ts/.tsx` 直接构建失败 |
+| 插件里 `fetch()` 外部 URL 被 CORS / SSRF 拦 | 用 `proxyFetch` / `proxyFetchStream`（带 SSRF 防护） |
+| 沙箱内 `window.open` 被拦 | 用 `callBackend('/system/open-url', { url })` 或 `openUrl` |
+| `vite.config.ts` 没设 `base: './'` | 产物 `/assets/...` 会被解析成站点根，插件白屏 |
+| 长循环 / 无界 `setInterval` | `verify` 会告警；放 Worker / WASM / 后端 |
+| 硬编码 API key 进插件源码 | 无密钥存储；让用户经 `setSettings` 配置，运行时 `getSettings` 读取 |
+
+## 事实一致红线
+
+- 本技能内容与代码事实对齐（`src/plugins/types.ts`、CLI `src/lib/*`、公开文档 `docs/plugins/plugin-api.md`）。字段含义有疑问时**以代码为准**，不确定就标注，不要虚构 API 或字段。
+- `packages/plugin-ui`（`@qomicex/plugin-ui`）的组件库使用参见 `tailwind.config.js` 的 `@qomicex/plugin-ui/tailwind-preset`，主题类名（`bg-primary`、`text-muted-foreground` 等）直接消费语义 token。
+
+## 起步提示词（给 AI 用）
+
+> 你是 Qomicex 插件开发工程师。先读 `skills/qomicex-plugin/` 下的 SKILL.md 与各分册（尤其 rules.md），再按流程工作：`qomicex create <id>` 生成项目 → 实现功能 → `qomicex verify` 过 0 error → `qomicex pack` 出包。manifest 字段、权限、API 签名一律以技能包内文档为准，不臆造。

package/skills/qomicex-plugin/debugging.md

@@ -0,0 +1,55 @@
+# Harness 热重载调试
+
+调试实现源：`packages/qomicex-cli/src/commands/dev.ts` + `scripts/harness/run.mjs`。
+
+## qomicex dev 的两条路径
+
+```bash
+qomicex dev            # 默认
+qomicex dev --port 3000
+```
+
+`dev` 命令从当前目录向上查找 `scripts/harness/run.mjs`：
+
+| 场景 | 行为 |
+|------|------|
+| **仓库内（harness 模式）** | 检测到 harness → spawn `scripts/harness/run.mjs`，进入完整调试环境。**插件必须位于 `plugins-dev/{id}`**（harness 从该目录定位）。`--port` 在此模式不生效（固定 1420） |
+| **仓库外（裸 Vite）** | 回退为 Vite dev server（默认 5173）+ 在项目根写 `.qomicex-dev.json`（dev 源插件配置，供手动注册 dev 源） |
+
+## harness 模式做什么
+
+不启动 Tauri、不启动 Rust 后端，纯浏览器调试：
+
+1. 起 stub mock server（`scripts/harness/stub.mjs`，固定 `:5100`）。
+2. 复用已有 Vite dev（`:1420`）；未运行则自动 spawn `pnpm run dev`。
+3. `addInitScript` 注入 **Tauri API mock**（`window.__TAURI_INTERNALS__` 等，跨导航保留）——否则前端在纯浏览器里无法挂载。
+4. 打开插件页 `http://127.0.0.1:1420/plugins/p/{pluginId}`。
+5. `fs.watch` 监听插件 `src/`（含 `index.html`/`theme.css`/`overlay.html`/`vite.config.ts`）→ 变更后重建（`pnpm run build`）→ 整页 reload（iframe 重新挂载）。
+
+**前置要求**：Playwright + Chromium：
+
+```bash
+pnpm add -D playwright
+pnpm exec playwright install chromium
+```
+
+## 手动运行 harness
+
+```bash
+node scripts/harness/run.mjs <pluginId> [--headed] [--mock file.json] [--build-cmd "pnpm run build"]
+# 或仓库根：pnpm run harness -- hello-plugin
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--headed` | 有头模式（默认 headless，看不到窗口；调试用 --headed） |
+| `--mock file.json` | 自定义 stub 返回（mock 数据） |
+| `--build-cmd "..."` | 覆盖重建命令（默认 `pnpm run build`） |
+
+## 注意事项
+
+- **网络请求转发**：前端直连 `:5000` 的 `/api/**` 请求被 route 到 stub `:5100`。stub 返回什么，插件就拿到什么——需要真实后端数据时请先跑 Rust 后端或改 mock。
+- **热重载陷阱**：浏览器(Chromium) ≠ WebView2，复合/backdrop-filter 等行为可能有差异，结论需在真实 Tauri 复核。
+- **停止**：`Ctrl+C`，会一并清理 stub / Vite。
+- **浏览器直开降级**：独立 `pnpm dev`（不经 harness）时 `window.__PLUGIN_API__` 为 `null`，`getApi()` 返回 null，UI 需优雅降级（模板已处理）。
+- 只读操作可放心跑；避免在调试页触发写数据 / 启动实例类操作。

package/skills/qomicex-plugin/manifest-schema.md

@@ -0,0 +1,130 @@
+# manifest.json 字段全解
+
+`manifest.json` 位于 `.qplugin` 包**根目录**，是插件唯一身份文件。本册字段以 `src/plugins/types.ts` 的 `PluginManifest` 与 CLI 校验器（`packages/qomicex-cli/src/lib/manifest.ts`）为准，与启动器 store 上传校验一致。
+
+## 完整示例
+
+```json
+{
+  "id": "com.example.demo",
+  "name": "示例插件",
+  "version": "0.1.0",
+  "minLauncherVersion": "0.1.0",
+  "layers": ["l2"],
+  "permissions": ["config:read", "ui:toast", "network:cors_proxy"],
+  "dependencies": [
+    { "id": "top.qomicex.markdown", "version": ">=1.0.0", "optional": false }
+  ],
+  "entry": {
+    "frontend": "dist/index.html",
+    "theme": "dist/theme.css"
+  },
+  "render": "iframe",
+  "contributes": {
+    "menuItems": [
+      { "path": "/plugins/p/com.example.demo", "label": "示例插件", "icon": "🧩", "action": "page" }
+    ],
+    "overlay": {
+      "file": "dist/overlay.html",
+      "title": "示例悬浮窗",
+      "width": 380,
+      "height": 500,
+      "minimizable": true,
+      "resizable": true
+    }
+  },
+  "icon": "fa-solid fa-puzzle-piece"
+}
+```
+
+## 字段总表
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | ✅ | 插件唯一 ID。格式 `^[a-z0-9]+([.-][a-z0-9]+)*$`，3-128 字符，**必须含至少一个点**（反向域名，如 `com.example.demo`）。含点但非法字符 → error；不含点 → warning。一经发布不要更改（用作安装目录 `plugins/{id}/`） |
+| `name` | string | ✅ | 显示名，非空 |
+| `version` | string | ✅ | 严格 semver：`^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$`，如 `1.2.0`、`0.1.0-beta.1` |
+| `minLauncherVersion` | string | ✅（CLI 校验） | 最低启动器版本。CLI 校验必填；运行时行为以启动器为准 |
+| `layers` | string[] | ✅ | 图层声明，至少一项，值 ∈ `l0`/`l1`/`l2`/`l3`。声明 frontend 但无 `l2`/`l3` → 无法渲染 UI（warning） |
+| `permissions` | string[] | ✅ | 权限声明，值必须是权限目录中的 id（见 `permissions.md`）。未知权限 → warning |
+| `dependencies` | PluginDependency[] | 可选 | 前置插件依赖，见下 |
+| `entry` | object | ✅ | 入口声明，`frontend`/`backend`/`theme` **至少一个** |
+| `render` | 'inline' \| 'iframe' | 可选 | **默认 `iframe`**（沙箱）。仅显式 `"inline"` 走内联渲染（与主界面同 window） |
+| `contributes` | object | 可选 | 扩展点 |
+| `icon` | string | 可选 | 顶层图标（插件管理/列表显示；库插件建议用顶层 icon 而非 menuItems） |
+
+## entry 对象
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `frontend` | string | 插件页面入口，`.qplugin` 内相对路径，应指向 `.html`（如 `dist/index.html`）。声明了 frontend 的插件才会被激活并渲染到 `/plugins/p/:id` |
+| `theme` | string | 主题 CSS 路径（如 `dist/theme.css`），激活时注入。引用 `dist/` 下文件但源码在根目录时，`qomicex pack` 会自动拷入 dist |
+| `backend` | string | 保留字段，当前未使用（以代码为准） |
+
+## layers 图层语义
+
+| 层级 | 技术 | 说明 |
+|------|------|------|
+| `l0` | 静态声明 | 主题 / 声明式内容，纯声明无执行能力 |
+| `l1` | 声明式 | 新增下载源 / 镜像 / 端点等声明（当前为预留层级） |
+| `l2` | JS 前端沙箱 | **UI 插件默认层级**。iframe 沙箱（`sandbox="allow-scripts"`，opaque origin，与主界面 DOM/CSS 隔离），经 postMessage 桥做权限检查，`__PLUGIN_API__` 全量可用，`registerMethod`/`callPlugin` 跨窗口中转 |
+| `l3` | WASM（wasmtime） | 后端沙箱执行 `plugin.wasm`，Host API 权限门控。包内含 `plugin.wasm` + 声明 `l3` 即被加载 |
+
+- **render 默认 iframe**：带 `entry.frontend` 的插件默认走 iframe 沙箱。内联渲染（`"render":"inline"`）与主界面同 window，仅适合需要访问主界面 DOM 的轻量插件。
+- `layers` 可声明多个（如 `["l2","l3"]`）。
+- 纯 `["l3"]` 且无 `entry.frontend` 的插件不会自动激活渲染 UI。
+
+## dependencies 依赖语法
+
+```json
+"dependencies": [
+  { "id": "top.qomicex.markdown", "version": ">=1.0.0", "optional": false }
+]
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | string | 被依赖插件 id |
+| `version` | string | 可选，版本约束 |
+| `optional` | boolean | 可选，是否非必装（缺省 false） |
+
+- 安装时检查必装前置，缺失拒绝安装（`PLUGIN_MISSING_DEPENDENCY`）。
+- 激活时检查前置已启用，缺失则本插件禁用。
+- 激活顺序由依赖拓扑排序保证。
+- `version` 约束写法（以代码 / 公开文档为准）：`>=1.0.0`、`<=2.0.0`、`>1.0`、`<2.0`、`=1.2.0`、裸版本 `1.2.0`、空格分隔多约束 `">=1.0 <2.0"`。不支持 `^`/`~`/`*`/`||`。
+
+## contributes 扩展点
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `downloadSources` | string[] | 保留（当前未使用，以代码为准） |
+| `commands` | string[] | 保留（当前未使用，以代码为准） |
+| `settingsPages` | string[] | 保留（当前未使用，以代码为准） |
+| `menuItems` | PluginMenuItem[] | 侧边栏入口列表 |
+| `overlay` | object | 悬浮窗配置 |
+
+### menuItems 数组元素
+
+```ts
+{ path: string; label: string; icon?: string; action?: 'page' | 'overlay' }
+```
+
+- `path`：入口目标路由（如 `/plugins/p/:id`）。
+- `icon`：emoji / 文本 / 绝对 URL / 包内相对路径（`dist/icon.svg`，启动器自动解析为 `http://localhost:5000/api/plugins/{id}/files/dist/icon.svg`）。
+- `action`：`"page"`（跳转页面，默认）或 `"overlay"`（打开悬浮窗，需配合 `contributes.overlay`）。
+
+### overlay 对象
+
+```ts
+{ file: string; title?: string; width?: number; height?: number; minimizable?: boolean; resizable?: boolean }
+```
+
+- `file`：悬浮窗 HTML 文件路径（必填，指向 `.html`，如 `dist/overlay.html`）。
+- `title` / `width` / `height` / `minimizable` / `resizable`：可选，视觉/行为参数（具体默认值以启动器代码为准）。
+
+## CLI 校验行为（`qomicex verify` 目录模式）
+
+- manifest 合法性：id / name / version(semver) / minLauncherVersion / layers / permissions / entry / contributes。
+- 权限最小化：对比 `permissions` 与源码实际调用的桥方法（`METHOD_PERMISSIONS` 表），**声明未用 / 用了未声明都会报错**。
+- 长循环告警：`while(true)`、`for(;;)`、无界 `setInterval`。
+- 校验通过标准：**0 error**（warning 可接受但建议消除）。

package/skills/qomicex-plugin/permissions.md

@@ -0,0 +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"]
+}
+```

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

@@ -0,0 +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
+```

package/skills/qomicex-plugin/rules.md

@@ -0,0 +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/` 等。
+25. **不 git commit**：插件开发阶段不提交改动到仓库。

package/skills/qomicex-plugin/signing.md

@@ -0,0 +1,80 @@
+# Ed25519 签名流程
+
+签名实现源：`packages/qomicex-cli/src/lib/signature.ts`。规范：**ADR-050 三级信任链**（商店根钥 → 开发者证书 → 包体签名）。与 store `src/lib/signature.ts`、launcher `plugin_signature.rs` 字节级一致。
+
+## 签名载荷（规范化）
+
+```
+payload = canonicalJson({
+  manifest: sha256Hex(manifest.json 原始字节),
+  files: [{ path, sha256 }...]     // 按 path 升序
+})
+signedHash = SHA-256(payload)      // 文本 UTF-8
+signature  = Ed25519(私钥, payload 的 UTF-8 字节)
+```
+
+- `canonicalJson`：递归按键排序、无空白 JSON（键序对哈希无影响，保证确定性）。
+- 包内 `signature.json` 与 `signature.cert.json` 本身不参与签名。
+
+## 产物文件
+
+| 文件 | 内容 |
+|------|------|
+| `signature.json` | `{ alg: "Ed25519", signedHash, signerKeyId, signature }` |
+| `signature.cert.json` | 商店根钥签发的开发者证书：`{ alg, keyId, developerId, developerName, publicKey, issuedAt, signature }` |
+
+验包要求：**两个文件都必须存在**，缺任一 → 未签名（`verify` 警告不拒绝）；根钥验证书失败 / 包体验签失败 / 哈希不符 → 拒绝。
+
+## 1. 生成密钥对
+
+```bash
+openssl genpkey -algorithm Ed25519 -out dev-key.pem
+# 可选：提取 raw 32 字节 seed base64（publish 也接受 PEM，通常不必）
+openssl pkey -in dev-key.pem -outform DER | tail -c 32 | base64
+```
+
+私钥支持三种格式：PKCS#8 PEM、PKCS#8 DER base64、raw 32 字节 seed base64。
+
+> ⚠️ 私钥 = 开发者身份。**禁止**写入插件源码 / manifest / git 仓库 / 提交任何公开位置。使用环境变量 `QOMICEX_SIGN_KEY` 传入。
+
+## 2. pack --key（本地签名，仅 signature.json）
+
+```bash
+qomicex pack --key ./dev-key.pem
+```
+
+- `keyId = ed25519:{公钥 base64 前 8 字符}`。
+- 若项目根存在 `signature.cert.json` 会自动带上（发布过一次后即有）。
+- 无证书时 CLI 会警告：商店上传仍需完整证书，建议走 publish。
+
+## 3. publish（完整证书链）
+
+```bash
+export QOMICEX_SIGN_KEY=<私钥 base64/PEM>   # 或 --key ./dev-key.pem
+qomicex publish
+qomicex publish --changelog "修复 X" --yes
+qomicex publish --api http://127.0.0.1:8787/api/v1   # 本地商店（wrangler dev）调试
+```
+
+流程（RFC 8628 设备流）：
+1. `POST /api/v1/auth/device/code` → 打印授权码 + 验证 URL → 轮询 `device/token` 拿访问令牌。
+2. `POST /api/v1/developer/keys` 上传 Ed25519 公钥 → 商店根钥签发开发者证书（返回 `keyId` + 证书内容）。
+3. 用私钥对包体签名，写入 `signature.json`，与证书一起打进 `.qplugin`。
+4. 查找/创建插件记录（`/plugins/mine` → 无则 `POST /plugins`），确认后 `POST /plugins/:id/versions` multipart 上传。
+5. 成功后将签名包存为 `release/<id>-<version>.signed.qplugin` 供复验。
+
+## 4. 验包
+
+```bash
+qomicex verify --package ./release/x.qplugin
+```
+
+- 用内置商店根公钥验签：`STORE_ROOT_PUBLIC_KEY_B64`（与 launcher `plugin_signature.rs` 的 `ROOT_PUBLIC_KEY_B64` 一致）。
+- 未签名 → 提示"未签名"（警告，不拒绝）；签名无效 → error 退出。
+
+## 商店根公钥
+
+```
+sPKcrc6QR5gcOnQMdq21Jo3yqxN7Mbm61OYxZnKuHE0=
+```
+（raw base64 Ed25519 公钥；开发 / 自建商店需替换为对应根钥）

package/skills/qomicex-plugin/theme.md

@@ -0,0 +1,58 @@
+# 主题语义 Token
+
+规范源：`docs/junsi-dev-docs/2-架构设计/主题语义Token规范v1.md`（实现：`src/theme/`）。插件 UI 主题的**唯一正确做法**：全量经 `var(--*)` 消费语义 token，禁止内联色值。
+
+## 三级语义模型
+
+```
+primitives（原始色板）→ semantic（语义角色）→ component（CSS 变量，唯一被 var() 读取）
+```
+
+v1 落点：`.qtheme` 主题直接表达 semantic/component 层（即 `--*` 平铺变量）。插件不写主题，只**消费**这些变量。token 点分命名，`.` 归一化为 `-`（`background.emphasis` → `--background-emphasis`）。
+
+## 色板 token（plugin-ui 消费全集）
+
+| token（theme.json 键） | CSS 变量 | 默认值(dark) | 语义 |
+|---|---|---|---|
+| background | `--background` | `230 20% 6%` | 页面底色 |
+| foreground | `--foreground` | `220 20% 93%` | 主文字 |
+| card / card-foreground | `--card` / `--card-foreground` | `228 18% 10%` / `220 20% 93%` | 卡片 |
+| popover / popover-foreground | `--popover` / `--popover-foreground` | `228 18% 10%` / `220 20% 93%` | 浮层 |
+| primary / primary-foreground | `--primary` / `--primary-foreground` | `142 71% 48%` / `230 20% 6%` | 主强调 |
+| secondary / secondary-foreground | `--secondary` / `--secondary-foreground` | `228 18% 14%` / `220 20% 93%` | 次级 |
+| muted / muted-foreground | `--muted` / `--muted-foreground` | `228 10% 18%` / `228 8% 55%` | 弱化 |
+| accent / accent-foreground | `--accent` / `--accent-foreground` | `228 18% 14%` / `220 20% 93%` | 强调底 |
+| destructive / destructive-foreground | `--destructive` / `--destructive-foreground` | `0 84% 60%` / `220 20% 93%` | 危险 |
+| border | `--border` | `228 14% 21%` | 边框 |
+| input | `--input` | `228 14% 21%` | 输入框 |
+| ring | `--ring` | `142 71% 48%` | 焦点环 |
+
+扩展语义（可选，emit 为 `--foreground-accent` 等）：`foreground.accent`、`foreground.muted`、`foreground.destructive`、`background.elevated`、`background.emphasis`、`background.sunken`、`border.strong`、`border.accent`、`accent.hover`、`accent.active`、`status.success`、`status.warning`、`status.error`。
+
+## 非色 token
+
+| token | CSS 变量 | 默认值 | 说明 |
+|---|---|---|---|
+| radius | `--radius` | `0.625rem` | 圆角 |
+| glass-blur | `--glass-blur` | `18px` | 毛玻璃模糊 |
+
+## var() 消费约定
+
+- **全部用 `var(--*)`，禁止内联色值**（`#hex` / `rgb()` / `hsl()` 字面量）。plugin-ui 组件已全量 var() 消费，换主题即时生效，无需重建 dist。
+- 颜色值多为 HSL 三元组（如 `142 71% 48%`），组件库经 `hsl(var(--primary))` 解析。插件自定义 CSS 需要时同样写 `hsl(var(--primary) / <alpha>)` 形式。
+- Tailwind 侧直接用语义类名：`bg-primary`、`text-foreground`、`bg-muted`、`text-muted-foreground`、`border-border` 等（`@qomicex/plugin-ui/tailwind-preset` 已映射）。
+
+## 主题贡献（entry.theme）
+
+- manifest `entry.theme` 指向 `dist/theme.css`，激活时注入 `<style data-plugin-theme>`。
+- 主题 CSS 只能**覆盖/补充** token，仍须全部 `var()` 引用，禁止内联色值：
+
+```css
+:root[data-theme] {
+  /* 可选：覆盖默认 HSL token */
+  --primary: 142 71% 48%;
+}
+```
+
+- `qomicex pack` 会自动把根目录的 `theme.css` 拷入 `dist/theme.css`（若 manifest 引用 `dist/theme.css`）。
+- **不要在插件里定义与启动器冲突的平铺变量**；需要私有样式时走组件 class（Tailwind）或局部作用域。