@qomicex/cli 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @qomicex/cli — qomicex 插件 CLI
+
+Qomicex 插件生态脚手架：`create` / `dev` / `pack` / `verify` / `publish`。零运行时依赖（Node ≥ 20，仅用内置 `node:fs`/`node:zlib`/WebCrypto）。
+
+## 安装
+
+```bash
+# 仓库内（pnpm workspace 成员，`packages/qomicex-cli`）
+pnpm install
+pnpm --filter @qomicex/cli build
+# 本地链接到 PATH
+pnpm --filter @qomicex/cli link
+```
+
+## 命令
+
+### create
+```bash
+qomicex create com.example.demo
+```
+从内置模板生成合法插件项目（Vite + React 19 + TS + Tailwind + `@qomicex/plugin-ui`），自动替换 `manifest.json` / `package.json` 中的 id。模板 `layers:["l2"]`（iframe 沙箱），权限最小集 `config:read / ui:toast / network:cors_proxy`。生成后提示 `pnpm install`。
+
+### dev
+```bash
+qomicex dev            # 默认 5173
+qomicex dev --port 3000
+```
+起本地插件调试环境：
+- **仓库内（harness 模式）**：插件位于仓库 `plugins-dev/{id}` 时，自动检测并 spawn `scripts/harness/run.mjs`，进入完整调试环境——Playwright 起 Vite(:1420) + 注入 Tauri mock + stub mock server(:5100) + 源码变更热重载（重建后整页 reload）。此模式 `--port` 不生效（harness 固定端口），`Ctrl+C` 退出时一并清理 stub/Vite。
+- **仓库外（裸 Vite）**：未检测到 harness 时回退为起 Vite dev server + 在项目根写 `.qomicex-dev.json`（dev 源插件配置：插件 id → localhost URL 映射），供手动注册 dev 源使用。
+
+### pack
+```bash
+qomicex pack                          # tsc && vite build → release/<id>-<version>.qplugin
+qomicex pack --version 0.2.0          # 覆盖 manifest 版本号
+qomicex pack --key ./dev-key.pem      # 附签名（仅 signature.json；完整证书链请用 publish）
+qomicex pack --skip-build             # 跳过构建（复用现有 dist）
+```
+`.qplugin` = zip，`manifest.json` 在根 + `dist/**`。`entry.theme` / `contributes.overlay.file` 若引用 `dist/` 下文件但源码在根目录，会自动拷入。
+
+### verify
+```bash
+qomicex verify                        # 目录模式：manifest + 权限 + 长循环
+qomicex verify --package ./release/x.qplugin   # 包模式：manifest + 签名验签
+```
+- **manifest 合法性**：id（反向域名/安全字符）、name、version(semver)、minLauncherVersion、layers、permissions、entry、contributes。
+- **权限最小化**：对比 `manifest.permissions` 与源码实际调用的桥方法（`METHOD_PERMISSIONS` 表）。声明未用 / 用了未声明都会报错。
+- **长循环告警**：`while(true)`、`for(;;)`、`setInterval` 无界轮询（提示放 Worker/WASM/后端）。
+- **签名检查**：包模式用内置商店根公钥验签（ADR-050）；无签名提示"未签名"不拒绝。
+
+### publish
+```bash
+export QOMICEX_SIGN_KEY=<私钥 base64/PEM>   # 或 --key ./key.pem
+qomicex publish                            # 设备流登录 → 签名 → 上传
+qomicex publish --changelog "修复 X" --yes
+qomicex publish --api http://127.0.0.1:8787/api/v1   # 本地商店（wrangler dev）调试
+```
+流程（对齐商店契约，见 `docs/junsi-dev-docs/2-架构设计/插件生态技术提案.md` §3.1/§4.1 与 ADR-050）：
+1. `POST /api/v1/auth/device/code` → 打印授权码与验证 URL → 轮询 `device/token` 拿访问令牌（RFC 8628）。
+2. `POST /api/v1/developer/keys` 上传 Ed25519 公钥 → 商店根钥签发开发者证书（`keyId` + `signature.cert.json`）。
+3. 用私钥对包体签名（规范化 JSON 载荷 → Ed25519 → `signature.json`），与证书一起打进 `.qplugin`。
+4. 查找/创建插件记录（`/plugins/mine` → 无则 `POST /plugins`），确认后 `POST /plugins/:id/versions` multipart 上传。
+5. 成功后将签名包存为 `release/<id>-<version>.signed.qplugin` 供复验。
+
+## 签名密钥
+
+生成 Ed25519 密钥对（PKCS#8 PEM 或 raw 32 字节 seed base64）：
+
+```bash
+openssl genpkey -algorithm Ed25519 -out dev-key.pem
+# raw seed 提取（publish 也接受 PEM，通常不必）
+openssl pkey -in dev-key.pem -outform DER | tail -c 32 | base64
+```
+
+## 开发
+
+```bash
+pnpm --filter @qomicex/cli build      # tsc → dist/（rewriteRelativeImportExtensions 输出可运行 ESM）
+pnpm --filter @qomicex/cli typecheck
+```
+
+## 设计说明
+
+- **零依赖**：zip 读写（`node:zlib` + 手写 CRC32/目录结构）、Ed25519（WebCrypto）、参数解析（手写）均不引入第三方包。
+- **签名规范化** 与 store `src/lib/signature.ts`、launcher `plugin_signature.rs` 字节级一致（键序/无空白 canonicalJson，`signedHash` = 载荷 SHA-256）。
+- **不改商店上传接口**：只读参考契约实现客户端。

package/dist/commands/create.js

@@ -0,0 +1,74 @@
+// qomicex create <id> — 从内置模板生成合法插件项目。
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { checkId } from "../lib/manifest.js";
+import { fail, info } from "../lib/io.js";
+export function templateDir() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '../../templates/plugin');
+}
+function humanizeName(id) {
+    const last = id.split('.').pop() ?? id;
+    const words = last.split('-').filter(Boolean);
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+export async function createCommand(id) {
+    if (!id || id.length === 0)
+        fail('用法: qomicex create <id>（如 qomicex create com.example.demo）');
+    const errors = checkId(id).filter((e) => !e.startsWith('id 建议'));
+    if (errors.length > 0)
+        fail(`非法插件 id：${errors.join('；')}`);
+    const dest = resolve(process.cwd(), id);
+    if (existsSync(dest) && readdirSync(dest).length > 0) {
+        fail(`目标目录已存在且非空: ${dest}`);
+    }
+    const src = templateDir();
+    if (!existsSync(src))
+        fail(`模板目录不存在: ${src}（CLI 安装不完整）`);
+    mkdirSync(dest, { recursive: true });
+    const name = humanizeName(id);
+    copyReplace(src, dest, { __QOMICEX_PLUGIN_ID__: id, __QOMICEX_PLUGIN_NAME__: name });
+    info(`✔ 已生成插件项目 ${dest}`);
+    info(`  id   : ${id}`);
+    info(`  name : ${name}`);
+    info('');
+    info('下一步：');
+    info(`  cd ${id}`);
+    info('  pnpm install          # 安装依赖');
+    info('  pnpm run dev          # 本地热重载预览');
+    info('  qomicex verify        # manifest / 权限 / 长循环 校验');
+    info('  qomicex pack          # 构建并打包 .qplugin');
+    info('  qomicex publish       # 设备流登录后签名上传到商店');
+    info('');
+    info('提示：模板依赖已发布的 @qomicex/plugin-ui，可在任意目录独立构建；');
+    info('若项目创建在仓库 plugins-dev/ 内（pnpm workspace 覆盖区），请用 npm install 安装依赖。');
+}
+function copyReplace(src, dest, subs) {
+    for (const entry of readdirSync(src)) {
+        const s = join(src, entry);
+        const d = join(dest, entry);
+        if (statSync(s).isDirectory()) {
+            mkdirSync(d, { recursive: true });
+            copyReplace(s, d, subs);
+        }
+        else {
+            cpSync(s, d);
+            // 只在需要插值的文件里替换（避免误伤 src/ 里运行时全局 window.__PLUGIN_ID__）
+            if (/\.(json|html|md)$/.test(entry)) {
+                applySubs(d, subs);
+            }
+        }
+    }
+}
+function applySubs(file, subs) {
+    let content = readFileSync(file, 'utf8');
+    let changed = false;
+    for (const [k, v] of Object.entries(subs)) {
+        if (content.includes(k)) {
+            content = content.split(k).join(v);
+            changed = true;
+        }
+    }
+    if (changed)
+        writeFileSync(file, content, 'utf8');
+}

package/dist/commands/dev.js

@@ -0,0 +1,59 @@
+// qomicex dev — 起本地插件调试环境。
+// 在仓库内（plugins-dev/ 等）检测到 scripts/harness/run.mjs 时，spawn harness
+// 走完整调试环境（Tauri mock + stub + 热重载）；否则回退裸 Vite + 输出 dev 源配置。
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fail, info, runShell } from "../lib/io.js";
+/** 从 cwd 逐级向上查找仓库根下的 scripts/harness/run.mjs；找不到返回 null */
+function findHarnessStart() {
+    let dir = resolve(process.cwd());
+    while (true) {
+        const candidate = join(dir, 'scripts', 'harness', 'run.mjs');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export async function devCommand(opts = {}) {
+    const root = process.cwd();
+    if (!existsSync(join(root, 'manifest.json')))
+        fail('当前目录不是插件项目（缺少 manifest.json）');
+    const manifest = JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'));
+    const pluginId = manifest.id ?? 'unknown';
+    // 仓库内检测到 harness → 走完整调试环境（Tauri mock + stub + 热重载）。
+    // 注意：harness 固定使用仓库根 Vite(:1420) + stub(:5100)，CLI 的 --port 在此模式不生效。
+    const harness = findHarnessStart();
+    if (harness) {
+        info(`✔ 检测到调试 harness（${harness}），进入完整调试环境（Tauri mock + stub + 热重载）`);
+        info('  插件须位于仓库 plugins-dev/{id} 供 harness 定位；--port 参数在此模式不生效（固定 1420）');
+        info('  停止：Ctrl+C（会一并清理 stub / Vite）');
+        const code = await runShell(`node ${JSON.stringify(harness)} --plugin ${JSON.stringify(pluginId)}`, root);
+        if (code !== 0)
+            fail(`harness 退出（code ${code}）`);
+        return;
+    }
+    const port = opts.port ?? 5173;
+    const devUrl = `http://localhost:${port}`;
+    const devConfig = {
+        kind: 'dev-source-plugin',
+        pluginId,
+        vite: { url: devUrl, port },
+        entry: 'index.html',
+        launcherHint: '将本插件的 dev 源（registryUrl / 本地插件映射）指向上述地址，或在调试 harness 中打开该 URL。',
+        note: 'v1：仅输出配置产物与使用说明，不自动挂载到启动器。',
+    };
+    const outFile = join(root, '.qomicex-dev.json');
+    writeFileSync(outFile, JSON.stringify(devConfig, null, 2));
+    info(`✔ 已生成 dev 源插件配置 ${outFile}`);
+    info('');
+    info(`正在启动 Vite dev server: ${devUrl}`);
+    info('  插件入口（与 manifest.entry.frontend 对应）：本机预览打开 index.html 即可');
+    info('  热重载：保存源码自动刷新；沙箱 API 桥在浏览器直开时降级为 null');
+    info('  停止：Ctrl+C');
+    const code = await runShell(`pnpm exec vite --port ${port} --strictPort`, root);
+    if (code !== 0)
+        fail(`Vite dev server 退出（code ${code}）`);
+}

package/dist/commands/pack.js

@@ -0,0 +1,85 @@
+// qomicex pack — 构建（tsc && vite build）并打 .qplugin（manifest.json 在 zip 根）。
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { readManifestFile, collectDir } from "../lib/project.js";
+import { zipWrite } from "../lib/zip.js";
+import { fail, info, runShell, warn } from "../lib/io.js";
+import { parsePrivateKey, signPackage } from "../lib/signature.js";
+/** 组装包内条目：manifest.json + dist/**，并把入口引用的根文件（theme.css/overlay.html）拷进 dist。 */
+export function buildPackageEntries(root, manifest) {
+    const entries = {};
+    entries['manifest.json'] = new TextEncoder().encode(JSON.stringify(manifest));
+    const distDir = join(root, 'dist');
+    if (!existsSync(distDir))
+        fail('缺少 dist/ 目录，请先构建（pnpm run build 或使用 qomicex pack）');
+    for (const f of collectDir(distDir, 'dist/'))
+        entries[f.name] = f.data;
+    // entry.theme / contributes.overlay.file 引用 dist/ 下文件但源码在根目录时，自动拷入
+    const entry = manifest.entry;
+    const overlay = manifest.contributes?.overlay;
+    for (const ref of [entry?.theme, overlay?.file]) {
+        if (typeof ref !== 'string' || !ref.startsWith('dist/'))
+            continue;
+        const target = join(root, ref);
+        if (existsSync(target))
+            continue;
+        const rootSrc = join(root, ref.slice('dist/'.length));
+        if (existsSync(rootSrc)) {
+            writeFileSync(target, readFileSync(rootSrc));
+            entries[ref] = readFileSync(target);
+        }
+    }
+    return entries;
+}
+export async function packCommand(opts = {}) {
+    const root = process.cwd();
+    const manifestFile = join(root, 'manifest.json');
+    if (!existsSync(manifestFile))
+        fail('当前目录不是插件项目（缺少 manifest.json）');
+    if (!opts.skipBuild) {
+        info('==> 构建前端（tsc + vite build）');
+        const code = await runShell('pnpm run build', root);
+        if (code !== 0)
+            fail('构建失败，请先修复编译错误');
+    }
+    const manifest = readManifestFile(manifestFile);
+    const id = String(manifest.id ?? '');
+    const version = opts.version ?? String(manifest.version ?? '');
+    if (!id)
+        fail('manifest.json 缺少 id');
+    let entries = buildPackageEntries(root, manifest);
+    // 可选签名（仅 signature.json；需要证书链请用 publish）
+    if (opts.key) {
+        const keyContent = await readKeyInput(opts.key);
+        const priv = parsePrivateKey(keyContent);
+        const { derivePublicKey } = 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))
+            certJson = readFileSync(localCert, 'utf8');
+        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 });
+    const outPath = join(outDir, `${id}-${version}.qplugin`);
+    writeFileSync(outPath, zipWrite(Object.entries(entries).map(([name, data]) => ({ name, data }))));
+    info(`✔ 已生成 ${outPath} (${entriesCount(entries)} 个文件)`);
+    return { outPath, entries };
+}
+async function readKeyInput(key) {
+    if (key.trim().startsWith('-----BEGIN') || /^[A-Za-z0-9+/=]{20,}$/.test(key.trim())) {
+        // 内联 PEM / base64
+        return key.trim();
+    }
+    const { readFileSync } = await import('node:fs');
+    const p = resolve(process.cwd(), key);
+    return readFileSync(p, 'utf8').trim();
+}
+function entriesCount(entries) {
+    return Object.keys(entries).length;
+}

package/dist/commands/publish.js

@@ -0,0 +1,126 @@
+// qomicex publish — 设备流登录（RFC 8628）→ 注册签名公钥 → 签名打包 → 上传到商店。
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { buildPackageEntries, packCommand } from "./pack.js";
+import { readManifestFile } from "../lib/project.js";
+import { zipRead, zipWrite } from "../lib/zip.js";
+import { DEFAULT_API_BASE, StoreApiError, requestDeviceCode, pollDeviceLogin, fetchMinePlugins, createPlugin, registerDevKey, uploadVersion, } from "../lib/store.js";
+import { parsePrivateKey, derivePublicKey, signPackage } from "../lib/signature.js";
+import { confirm, fail, info, warn } from "../lib/io.js";
+export async function publishCommand(opts = {}) {
+    const root = process.cwd();
+    const manifestFile = join(root, 'manifest.json');
+    if (!existsSync(manifestFile))
+        fail('当前目录不是插件项目（缺少 manifest.json）');
+    const manifest = readManifestFile(manifestFile);
+    const slug = opts.slug ?? String(manifest.id ?? '');
+    const version = opts.version ?? String(manifest.version ?? '');
+    if (!slug)
+        fail('manifest.json 缺少 id，无法发布');
+    // 1) 私钥（必须，商店要求签名包）
+    const keyContent = process.env.QOMICEX_SIGN_KEY || (opts.key ? await readKeyFile(opts.key) : '');
+    if (!keyContent) {
+        fail('缺少签名私钥：请通过环境变量 QOMICEX_SIGN_KEY 或 --key <私钥文件> 提供（PKCS#8 PEM / raw base64 seed）');
+    }
+    const priv = parsePrivateKey(keyContent);
+    const publicKey = await derivePublicKey(priv);
+    // 2) 打包（复用 pack 管线；已有 --package 则直接读取）
+    let entries;
+    if (opts.package) {
+        const p = resolve(root, opts.package);
+        if (!existsSync(p))
+            fail(`找不到包文件: ${p}`);
+        entries = zipRead(readFileSync(p));
+    }
+    else {
+        const packOpts = { ...opts };
+        await packCommand({ ...packOpts, key: undefined });
+        entries = buildPackageEntries(root, manifest);
+    }
+    // 清掉旧签名文件，避免脏残留
+    for (const k of ['signature.json', 'signature.cert.json'])
+        delete entries[k];
+    // 3) 设备流登录
+    const api = opts.api ?? process.env.QOMICEX_STORE_API ?? DEFAULT_API_BASE;
+    info('==> 设备流登录');
+    const code = await requestDeviceCode(api);
+    info(`  请在浏览器打开（或扫码）并登录确认：`);
+    info(`  ${code.verificationUriComplete}`);
+    info(`  授权码: ${code.userCode}`);
+    const login = await pollDeviceLogin(api, code);
+    info(`✔ 登录成功：${login.user.username}`);
+    // 4) 注册/刷新签名公钥，获取商店根钥签发的证书
+    info('==> 注册签名公钥');
+    const keyRes = await registerDevKey(api, login.accessToken, publicKey);
+    const certJson = JSON.stringify(keyRes.cert);
+    info(`✔ 签名证书就绪（keyId: ${keyRes.keyId}）`);
+    // 5) 签名
+    const sig = await signPackage(entries, priv, keyRes.keyId, certJson);
+    entries = { ...entries, ...sig };
+    const signedBytes = zipWrite(Object.entries(entries).map(([name, data]) => ({ name, data })));
+    // 6) 查找/创建插件记录
+    info('==> 确认插件记录');
+    let pluginId = '';
+    const mine = await fetchMinePlugins(api, login.accessToken);
+    const existing = mine.find((p) => p.slug === slug);
+    if (existing) {
+        pluginId = existing.id;
+        info(`✔ 找到已有插件 ${slug}（id: ${pluginId}）`);
+    }
+    else {
+        try {
+            const created = await createPlugin(api, login.accessToken, {
+                slug,
+                name: String(manifest.name ?? slug),
+                description: String(manifest.description ?? ''),
+                orgId: opts.orgId,
+            });
+            pluginId = created.id;
+            info(`✔ 已创建插件记录 ${slug}（id: ${pluginId}，等待商店审核）`);
+        }
+        catch (e) {
+            if (e instanceof StoreApiError && e.status === 409) {
+                const again = await fetchMinePlugins(api, login.accessToken);
+                const found = again.find((p) => p.slug === slug);
+                if (!found)
+                    throw e;
+                pluginId = found.id;
+                info(`✔ slug 已存在，复用插件 ${slug}（id: ${pluginId}）`);
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    // 7) 确认后上传
+    info('');
+    info(`发布预览：`);
+    info(`  插件: ${slug}  v${version}`);
+    info(`  keyId: ${keyRes.keyId}`);
+    info(`  包体: ${signedBytes.length} 字节（已签名）`);
+    const ok = await confirm('确认发布到商店？', opts.yes ?? false);
+    if (!ok) {
+        warn('已取消发布');
+        return;
+    }
+    info('==> 上传版本');
+    const result = await uploadVersion(api, login.accessToken, pluginId, signedBytes, opts.changelog);
+    info(`✔ 上传完成：${slug} v${version}`);
+    info(`  商店地址: ${api.replace('/api/v1', '')}`);
+    if (typeof result === 'object' && result && 'status' in result) {
+        info(`  状态: ${String(result.status)}`);
+    }
+    // 保存签名包到 release/，方便复验
+    const outDir = resolve(root, 'release');
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(outDir, { recursive: true });
+    const outPath = join(outDir, `${slug}-${version}.signed.qplugin`);
+    writeFileSync(outPath, signedBytes);
+    info(`✔ 已保存签名包 ${outPath}（可 qomicex verify --package 复验）`);
+}
+async function readKeyFile(key) {
+    const p = resolve(process.cwd(), key);
+    if (existsSync(p))
+        return readFileSync(p, 'utf8').trim();
+    return key.trim();
+}

package/dist/commands/verify.js

@@ -0,0 +1,80 @@
+// qomicex verify — manifest 合法性 + 权限最小化 + 长循环告警 + 签名检查。
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { validateManifest } from "../lib/manifest.js";
+import { checkPermissions, checkLongLoops } from "../lib/scan.js";
+import { zipRead } from "../lib/zip.js";
+import { verifyPackageSignature } from "../lib/signature.js";
+import { fail, info, warn } from "../lib/io.js";
+export async function verifyCommand(opts = {}) {
+    if (opts.package) {
+        await verifyPackage(opts.package);
+        return;
+    }
+    const root = process.cwd();
+    const manifestFile = join(root, 'manifest.json');
+    if (!existsSync(manifestFile))
+        fail('当前目录不是插件项目（缺少 manifest.json）');
+    const manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
+    const findings = [];
+    let errors = 0;
+    const mCheck = validateManifest(manifest);
+    findings.push(...mCheck.issues);
+    errors += mCheck.issues.filter((i) => i.severity === 'error').length;
+    const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : [];
+    const permCheck = checkPermissions(root, permissions);
+    findings.push(...permCheck.findings);
+    errors += permCheck.findings.filter((f) => f.severity === 'error').length;
+    const loops = checkLongLoops(root);
+    findings.push(...loops);
+    for (const f of findings) {
+        const tag = f.severity === 'error' ? '✗' : '⚠';
+        const loc = 'file' in f && f.file ? ` (${f.file})` : '';
+        if (f.severity === 'error')
+            console.error(`${tag} ${f.message}${loc}`);
+        else
+            console.warn(`${tag} ${f.message}${loc}`);
+    }
+    info(`\n校验完成：${mCheck.issues.length} manifest 项，权限 ${permissions.length} 项（未用 ${permCheck.unused.length}，缺声明 ${permCheck.missing.length}），长循环告警 ${loops.length}`);
+    if (errors > 0) {
+        console.error(`发现 ${errors} 个错误，请修复后重试`);
+        process.exit(1);
+    }
+    info('✔ verify 通过');
+}
+async function verifyPackage(pkg) {
+    const file = resolve(process.cwd(), pkg);
+    if (!existsSync(file))
+        fail(`找不到文件: ${file}`);
+    let entries;
+    try {
+        entries = zipRead(readFileSync(file));
+    }
+    catch (e) {
+        fail(`不是有效的 .qplugin（zip）: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!entries['manifest.json'])
+        fail('包内缺少根级 manifest.json');
+    const manifest = JSON.parse(new TextDecoder().decode(entries['manifest.json']));
+    const mCheck = validateManifest(manifest);
+    for (const i of mCheck.issues) {
+        if (i.severity === 'error')
+            console.error(`✗ [manifest.${i.path}] ${i.message}`);
+        else
+            warn(`[manifest.${i.path}] ${i.message}`);
+    }
+    const sig = await verifyPackageSignature(entries);
+    if (sig.ok) {
+        info(`✔ 签名有效（开发者: ${sig.cert.developerName}, keyId: ${sig.cert.keyId}）`);
+    }
+    else if (sig.code === 'signature_required') {
+        warn(sig.reason);
+    }
+    else {
+        console.error(`✗ 签名无效: ${sig.reason}`);
+    }
+    if (!mCheck.ok || (sig.ok === false && sig.code === 'signature_invalid')) {
+        process.exit(1);
+    }
+    info('✔ verify 通过');
+}

package/dist/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// qomicex CLI 入口：create / dev / pack / verify / 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 { fail } from "./lib/io.js";
+const VERSION = '0.1.0';
+function parseArgs(argv) {
+    const positional = [];
+    const options = {};
+    const command = argv[0] ?? 'help';
+    for (let i = 1; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            if (eq !== -1) {
+                options[a.slice(2, eq)] = a.slice(eq + 1);
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    options[a.slice(2)] = next;
+                    i++;
+                }
+                else {
+                    options[a.slice(2)] = true;
+                }
+            }
+        }
+        else if (a.startsWith('-') && a.length === 2) {
+            options[a.slice(1)] = true;
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    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）
+`;
+}
+async function main() {
+    const { command, positional, options } = parseArgs(process.argv.slice(2));
+    if (command === 'help' || command === '--help' || command === '-h' || options['help']) {
+        console.log(helpText());
+        return;
+    }
+    if (command === '--version' || command === '-v' || command === 'version') {
+        console.log(VERSION);
+        return;
+    }
+    const num = (v, d) => (typeof v === 'string' && /^\d+$/.test(v) ? Number(v) : d);
+    try {
+        switch (command) {
+            case 'create':
+                await createCommand(positional[0] ?? '');
+                break;
+            case 'dev':
+                await devCommand({ port: num(options['port'], 5173) });
+                break;
+            case 'pack':
+                await packCommand({
+                    outDir: typeof options['out-dir'] === 'string' ? options['out-dir'] : undefined,
+                    version: typeof options['version'] === 'string' ? options['version'] : undefined,
+                    key: typeof options['key'] === 'string' ? options['key'] : undefined,
+                    skipBuild: options['skip-build'] === true,
+                });
+                break;
+            case 'verify':
+                await verifyCommand({ package: typeof options['package'] === 'string' ? options['package'] : undefined });
+                break;
+            case 'publish':
+                await publishCommand({
+                    key: typeof options['key'] === 'string' ? options['key'] : undefined,
+                    slug: typeof options['slug'] === 'string' ? options['slug'] : undefined,
+                    changelog: typeof options['changelog'] === 'string' ? options['changelog'] : undefined,
+                    api: typeof options['api'] === 'string' ? options['api'] : undefined,
+                    orgId: typeof options['org-id'] === 'string' ? options['org-id'] : undefined,
+                    package: typeof options['package'] === 'string' ? options['package'] : undefined,
+                    yes: options['yes'] === true,
+                });
+                break;
+            default:
+                fail(`未知命令: ${command}\n${helpText()}`);
+        }
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+}
+void main();

package/dist/lib/io.js

@@ -0,0 +1,35 @@
+// CLI 通用 IO：输出 / 退出 / 子进程。
+import { spawn } from 'node:child_process';
+export function info(msg) {
+    console.log(msg);
+}
+export function warn(msg) {
+    console.warn(`⚠  ${msg}`);
+}
+export function fail(msg) {
+    console.error(`✗ ${msg}`);
+    process.exit(1);
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** 以 shell 方式运行命令（继承 stdio），返回退出码。Windows/Linux/macOS 通用。 */
+export function runShell(cmdLine, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn(cmdLine, { cwd, stdio: 'inherit', shell: true });
+        child.on('close', (code) => resolve(code ?? 1));
+        child.on('error', () => resolve(1));
+    });
+}
+/** 非交互确认：默认 N，回答 y/yes 才放行。 */
+export async function confirm(question, yesFlag) {
+    if (yesFlag)
+        return true;
+    process.stdout.write(`${question} [y/N] `);
+    return await new Promise((resolve) => {
+        process.stdin.once('data', (d) => {
+            const a = d.toString().trim().toLowerCase();
+            resolve(a === 'y' || a === 'yes');
+        });
+    });
+}