@qomicex/cli 0.1.1 → 0.1.3

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/commands/pack.js

@@ -48,21 +48,26 @@ export async function packCommand(opts = {}) {
     if (!id)
         fail('manifest.json 缺少 id');
     let entries = buildPackageEntries(root, manifest);
-    // 可选签名（仅 signature.json；需要证书链请用 publish）
+    // 可选签名（signature.json + signature.cert.json；无商店证书时生成自签证书）
     if (opts.key) {
         const keyContent = await readKeyInput(opts.key);
         const priv = parsePrivateKey(keyContent);
-        const { derivePublicKey } = await import("../lib/signature.js");
+        const { derivePublicKey, makeSelfSignedCert } = await import("../lib/signature.js");
         const pub = await derivePublicKey(priv);
         const keyId = `ed25519:${pub.slice(0, 8)}`;
         const localCert = join(root, 'signature.cert.json');
         let certJson;
-        if (existsSync(localCert))
+        if (existsSync(localCert)) {
             certJson = readFileSync(localCert, 'utf8');
+        }
+        else {
+            const name = String(manifest.name ?? '');
+            certJson = await makeSelfSignedCert(priv, keyId, name);
+            writeFileSync(localCert, certJson);
+            warn('未找到本地签名证书，已生成自签证书并写入 signature.cert.json；上传商店需先在开发者中心注册对应公钥');
+        }
         const sig = await signPackage(entries, priv, keyId, certJson);
         entries = { ...entries, ...sig };
-        if (!certJson)
-            warn('缺少本地 signature.cert.json，商店上传仍需证书；建议改用 qomicex publish 走完整签名');
     }
     const outDir = resolve(root, opts.outDir ?? 'release');
     mkdirSync(outDir, { recursive: true });

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 = {};
@@ -49,6 +52,8 @@ qomicex v${VERSION} — Qomicex 插件生态 CLI
                                 构建并打 .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           显示帮助
@@ -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/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) {
@@ -98,10 +98,34 @@ async function signBytes(privDer, msg) {
     const sig = await crypto.subtle.sign({ name: ALG }, key, msg);
     return bytesToBase64(new Uint8Array(sig));
 }
+/** 自签开发者证书（开发者私钥签证书体）：未注册商店密钥时的离线打包/本地验证用，商店上传需对应公钥已注册。 */
+export async function makeSelfSignedCert(privDer, keyId, developerName = '') {
+    const { derivePublicKey } = await import("./signature.js");
+    const publicKey = await derivePublicKey(privDer);
+    const body = {
+        alg: ALG,
+        keyId,
+        developerId: '',
+        developerName,
+        publicKey,
+        issuedAt: new Date().toISOString(),
+        signature: '',
+    };
+    const certBody = canonicalJson({
+        alg: body.alg,
+        keyId: body.keyId,
+        developerId: body.developerId,
+        developerName: body.developerName,
+        publicKey: body.publicKey,
+        issuedAt: body.issuedAt,
+    });
+    body.signature = await signBytes(privDer, new TextEncoder().encode(certBody));
+    return JSON.stringify(body);
+}
 /**
  * 对包内全部条目生成签名文件。
  * @param certJson 商店根钥签发的开发者证书 JSON（POST /developer/keys 返回值），
- *                 无 cert 时仅生成 signature.json（pack 场景，publish 会走完整证书链）。
+ *                 省略时仅生成 signature.json（publish 场景由调用方传证书）。
  */
 export async function signPackage(entries, privDer, keyId, certJson) {
     const payload = await signedPayloadBytes(entries);

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.1",
+  "version": "0.1.3",
   "publishConfig": {
     "access": "public"
   },

package/skills/qomicex-plugin/SKILL.md

@@ -1,65 +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 签名一律以技能包内文档为准，不臆造。
+# 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

@@ -1,55 +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 需优雅降级（模板已处理）。
-- 只读操作可放心跑；避免在调试页触发写数据 / 启动实例类操作。
+# 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 需优雅降级（模板已处理）。
+- 只读操作可放心跑；避免在调试页触发写数据 / 启动实例类操作。