@qmuse/qmuse-cli 1.0.9-dev.4 → 1.0.10-dev.1

package/dist/version-gate.js

@@ -0,0 +1,202 @@
+/**
+ * 版本闸门（version gate）：三档判定 + 失败降级。
+ *
+ * 档位（与业界 CLI 一致）：
+ *  - ok       低于 warnBelow 之外的正常状态
+ *  - notice   有更新：仅退出时提示一行
+ *  - warning  低于 warnBelow：每条命令告警，但继续执行
+ *  - blocked  低于 minRequired：拒绝执行（exit 1），只放行 upgrade 等放行清单命令
+ *
+ * 策略来源（provider 可替换，默认读 npm 包元数据，后端零改动）：
+ *  - npm/tnpm 的 `<pkg>/latest` 响应里携带 `qmuseVersionPolicy: { minRequired, warnBelow, message, upgradeCommand }`
+ *  - 读不到（离线/旧包/字段缺失）→ 一律降级为 ok，绝不因为闸门把 CLI 锁死
+ */
+import semver from 'semver';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { QMUSE_CLI_DISTRIBUTION, QMUSE_CLI_NAME, QMUSE_CLI_VERSION } from './version.js';
+/** 不需要闸门放行的命令（否则用户无法自救升级）。 */
+export const GATE_BYPASS_COMMANDS = new Set([
+    'upgrade',
+    'help',
+    'version',
+    'agent-skill',
+]);
+export function defaultUpgradeCommand(distribution) {
+    return distribution === 'PUBLIC'
+        ? 'npm install -g @qmuse/qmuse-cli@latest'
+        : 'tnpm install -g @alipay/qmuse-cli@latest';
+}
+function validOrUndefined(value) {
+    return typeof value === 'string' && semver.valid(value) ? value : undefined;
+}
+/** 从 registry 的 `/latest` 元数据里解析策略；字段缺失或非法一律忽略（失败降级）。 */
+export function parsePolicy(metadata) {
+    const record = (metadata ?? {});
+    // 既支持 registry 元数据的嵌套形态（qmuseVersionPolicy），也支持策略对象自身的扁平形态（环境变量/未来接口）。
+    const nested = (record['qmuseVersionPolicy'] ?? record['versionPolicy']);
+    const raw = nested && typeof nested === 'object' ? nested : record;
+    const policy = {};
+    if (raw && typeof raw === 'object') {
+        const minRequired = validOrUndefined(raw['minRequired']);
+        const warnBelow = validOrUndefined(raw['warnBelow']);
+        if (minRequired)
+            policy.minRequired = minRequired;
+        if (warnBelow)
+            policy.warnBelow = warnBelow;
+        if (typeof raw['message'] === 'string' && raw['message'].trim())
+            policy.message = raw['message'].trim().slice(0, 500);
+        if (typeof raw['upgradeCommand'] === 'string' && raw['upgradeCommand'].trim()) {
+            policy.upgradeCommand = raw['upgradeCommand'].trim().slice(0, 300);
+        }
+    }
+    return {
+        latest: validOrUndefined(record['version']),
+        ...(Object.keys(policy).length > 0 ? { policy } : {}),
+        checkedAt: Date.now(),
+    };
+}
+/** 三档判定：纯函数，便于测试；任何无法比较的输入都降级为 ok。 */
+export function gateLevel(current, snapshot) {
+    if (!snapshot || !semver.valid(current))
+        return 'ok';
+    const { policy } = snapshot;
+    const minRequired = policy?.minRequired;
+    const warnBelow = policy?.warnBelow;
+    try {
+        // 预发布版本（1.0.9-dev.3）代表领先于同名正式版，因此「有无更新」不提示；
+        // 但它仍然可能落后于 minRequired（例如要求 1.5.0 时 1.0.9 必须阻断），故阻断判据不豁免。
+        const isPrerelease = !!semver.prerelease(current);
+        if (minRequired && semver.valid(minRequired) && semver.compare(current, minRequired) < 0)
+            return 'blocked';
+        if (warnBelow && semver.valid(warnBelow) && semver.compare(current, warnBelow) < 0)
+            return 'warning';
+        if (isPrerelease)
+            return 'ok';
+        if (snapshot.latest && semver.valid(snapshot.latest) && semver.lt(current, snapshot.latest))
+            return 'notice';
+        return 'ok';
+    }
+    catch {
+        return 'ok';
+    }
+}
+/** 是否需要升级：预发布版本不判「落后」；缺少最新版本信息时返回 false（降级）。 */
+export function shouldUpgrade(current, latest) {
+    if (!latest || !semver.valid(latest) || !semver.valid(current))
+        return false;
+    if (semver.prerelease(current))
+        return false;
+    try {
+        return semver.lt(current, latest);
+    }
+    catch {
+        return false;
+    }
+}
+/** 生成给用户看的决定（含 upgrade 命令），供 CLI 输出。 */
+export function decide(current, snapshot, distribution = QMUSE_CLI_DISTRIBUTION) {
+    const level = gateLevel(current, snapshot);
+    const upgradeCommand = snapshot?.policy?.upgradeCommand ?? defaultUpgradeCommand(distribution);
+    return {
+        level,
+        current,
+        ...(snapshot?.latest ? { latest: snapshot.latest } : {}),
+        ...(snapshot?.policy?.minRequired ? { minRequired: snapshot.policy.minRequired } : {}),
+        ...(snapshot?.policy?.message ? { message: snapshot.policy.message } : {}),
+        upgradeCommand,
+    };
+}
+/** 元数据地址（与 update-notice 一致，按发行版切换公共/内部 registry）。 */
+export function policyRegistryUrl(distribution = QMUSE_CLI_DISTRIBUTION) {
+    return distribution === 'PUBLIC'
+        ? 'https://registry.npmjs.org/@qmuse%2fqmuse-cli/latest'
+        : 'https://registry.antgroup-inc.cn/@alipay%2fqmuse-cli/latest';
+}
+/**
+ * 环境变量 provider（QMUSE_VERSION_POLICY='{"minRequired":"1.2.0"}'）：
+ * 便于自测与企业内网固定策略；与服务端接口就绪前的过渡手段。
+ */
+export function envPolicyProvider(json = process.env.QMUSE_VERSION_POLICY) {
+    return async () => {
+        if (!json)
+            return undefined;
+        try {
+            return parsePolicy(JSON.parse(json));
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+const POLICY_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+/** 缓存目录：QMUSE_CLI_CACHE_DIR 可覆盖（测试与多环境隔离）。 */
+function policyCacheDir() {
+    return process.env.QMUSE_CLI_CACHE_DIR ?? join(homedir(), '.cache', 'qmuse-cli');
+}
+function policyCachePath(distribution) {
+    return join(policyCacheDir(), `version-policy-${distribution.toLowerCase()}.json`);
+}
+function readPolicyCache(distribution) {
+    try {
+        const raw = JSON.parse(readFileSync(policyCachePath(distribution), 'utf8'));
+        if (!raw || typeof raw.checkedAt !== 'number')
+            return undefined;
+        if (Date.now() - raw.checkedAt > POLICY_CACHE_TTL_MS)
+            return undefined;
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writePolicyCache(distribution, snapshot) {
+    try {
+        const file = policyCachePath(distribution);
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        writeFileSync(file, JSON.stringify(snapshot), { mode: 0o600 });
+    }
+    catch { /* 缓存失败不影响闸门判定 */ }
+}
+/** 默认 provider：读 `<pkg>/latest`，任何异常都返回 undefined（失败降级放行）。 */
+export function registryPolicyProvider(options = {}) {
+    const distribution = options.distribution ?? QMUSE_CLI_DISTRIBUTION;
+    const url = options.url ?? policyRegistryUrl(distribution);
+    const timeoutMs = options.timeoutMs ?? 2500;
+    return async () => {
+        // 缓存优先：6 小时内不重复打 registry（每条命令一次请求代价过高）。
+        const cached = readPolicyCache(distribution);
+        if (cached)
+            return cached;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        timer.unref?.();
+        try {
+            const response = await (options.fetcher ?? fetch)(url, {
+                signal: controller.signal,
+                redirect: 'error',
+                headers: { Accept: 'application/json', 'x-qmuse-client': QMUSE_CLI_NAME },
+            });
+            if (!response.ok)
+                return undefined;
+            const snapshot = parsePolicy(await response.json());
+            writePolicyCache(distribution, snapshot);
+            return snapshot;
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+/** 执行闸门检查：失败降级为 ok；放行清单内命令永不阻断。 */
+export async function checkVersionGate(input) {
+    const current = input.current ?? QMUSE_CLI_VERSION;
+    const snapshot = await (input.provider ?? registryPolicyProvider({ distribution: input.distribution }))();
+    const decision = decide(current, snapshot, input.distribution ?? QMUSE_CLI_DISTRIBUTION);
+    const bypass = input.command !== undefined && GATE_BYPASS_COMMANDS.has(input.command);
+    return { decision, blocked: decision.level === 'blocked' && !bypass };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qmuse/qmuse-cli",
-  "version": "1.0.9-dev.4",
-  "description": "将本地 React 项目安全导入 QMuse 的命令行客户端",
+  "version": "1.0.10-dev.1",
+  "description": "QMuse 命令行客户端：在本地创建/导入 React 项目、与 QMuse 对话、拉取发布与云端调试",
   "type": "module",
   "bin": {
     "qmuse": "dist/cli.js",
@@ -29,6 +29,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "engines": {
@@ -44,6 +45,7 @@
     "vite": "7.3.6"
   },
   "license": "MIT",
+  "repository": "git@code.alipay.com:q-muse/qmuse-cli.git",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/skills/qmuse-cli/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: qmuse-cli
+description: QMuse CLI 官方研发指南：本地工程初始化、导入、应用绑定、远端对话、本地开发、源码同步、云数据与发布。当用户要求使用 QMuse CLI 创建/开发/导入/发布应用到 QMuse，或排查 qmuse 命令问题时使用。
+---
+
+# QMuse CLI 官方指南
+
+总原则：先 `qmuse info --json` 判定上下文（登录态、环境、绑定、云架构），再选择下方分流入口；
+每个命令都可以 `qmuse help` 查看参数，`--json` 拿结构化输出。执行失败时：
+先读取命令输出中的诊断字段（`message`、`errorCode`、`diagnostics`、`.qmuse/last-import-error.json`），
+不要凭猜测重复执行可能创建新资源的操作（重复创建请求只恢复身份，不重跑首轮生成）。
+
+## 工程与任务分流（先读这里）
+
+| 用户意图 | 入口 | 关键约束 |
+| --- | --- | --- |
+| 初始化一个新的本地工程 | `qmuse create <dir>` | 只负责本地模板与说明；远端应用用 `qmuse import` 或 `qmuse app create` |
+| 已有 React 工程导入 QMuse | `qmuse import <dir>` | 安全预检 → 打包上传 → 应用/版本生成；预发/正式环境用 `--env` 区分 |
+| 修改已导入的同一应用 | `qmuse import .`（项目目录内） | 自动走 UPDATE 语义；远端基线变化时要求 pull 或 `--force` |
+| 自然语言创建应用并首轮生成 | `qmuse app create <web\|h5> --file <路径\|->` | POST /api/chat mode=create 一次完成；同 requestId 重发只恢复身份（REUSED） |
+| 已有应用继续对话/生成 | `qmuse chat send / resume --app-id … --chat-id …` | 需要应用绑定或显式 appId；中断恢复传 `--interrupt-id` 与 `--file` |
+| 本地开发（云资源连接） | `qmuse dev [dir]` | 云绑定应用；`qmuse dev status/stop` 管理会话 |
+| 拉取最新已保存源码 | `qmuse pull [dir]` / `qmuse code export` | 本地有改动会先备份再停止；不静默覆盖 |
+| 发布与发布结果 | `qmuse deploy --version <id>`、`qmuse release status <releaseId>` | 受理后可 `--no-wait` 退出；结果含发布地址与安全检查 |
+
+## 与官方 Skill 的关系
+
+- 本指南随 CLI 包内分发（离线可用）。升级 CLI 后执行 `qmuse agent-skill install --agent codex` 重新安装对应版本。
+- `qmuse agent-skill status` 查看安装目标、版本与文件状态。
+- 云服务规则不复制到本指南：以 `qmuse info --json` / `qmuse cloud status` 返回的实际架构与平台权威文档为准（见 references/cloud.md）。

package/skills/qmuse-cli/references/cloud.md

@@ -0,0 +1,32 @@
+# 云服务指南（S01.11：匹配现有云服务）
+
+CLI 不复制云规则，只做两件事：识别当前应用的实际架构，然后把操作路由到现有权威入口。
+
+## 1. 识别当前架构
+
+```bash
+qmuse info --json          # bindings + cloud 汇总（entitlement / environment）
+qmuse cloud status --app-id <appId> --json   # effectiveMode、activationStatus、publishAllowed、canRetryInitialization
+```
+
+- `SINGLE_ENV` / Legacy：应用没有开通多环境；云初始化与首版同步由导入或对话侧完成。
+- `MULTI_ENV`（Hono）：`qmuse cloud enable` 之后再查询状态；已初始化失败用 `qmuse cloud environment retry --wait`。
+
+## 2. 路由到现有入口
+
+| 判断 | 动作 |
+| --- | --- |
+| 权益预检（不伪装已开通） | `qmuse cloud init -d "<功能描述>"` |
+| 实际开通 | `qmuse cloud enable --app-id <appId>` |
+| 状态/失败原因 | `qmuse cloud status --app-id <appId>` |
+| 初始化失败重试 | `qmuse cloud environment retry --app-id <appId> --wait` |
+| 公开连接与运行配置 | `qmuse cloud pull-env --app-id <appId> --output .qmuse/local-dev.json` |
+| 数据库/表结构与用量 | `qmuse data-source list|info`、`qmuse db tables`、`qmuse db records …` |
+| 云函数 | `qmuse fn list|info|retry|deployment-*|execution-*` |
+| 秘密（安全输入） | `qmuse cloud set-secret K1,K2 --stdin`；查询 `qmuse secret list` / `secret sync status|retry` |
+
+## 3. 约束
+
+- 管理凭证只保留在 CLI 会话或服务端；`pull-env` 输出仅含公开配置。
+- 预检通过不等于初始化完成：以 `cloud status` 的 `activationStatus` 为准。
+- 套餐与订阅购买流程在 PC 端；CLI 只读 `qmuse account` 汇总并在缺少契约时返回 `unavailable` 原因。

package/skills/qmuse-cli/references/core-flows.md

@@ -0,0 +1,93 @@
+# 核心流程参考（S01.12）
+
+仅覆盖当前交付入口：身份与应用、初始化与导入、本地开发、对话恢复、源码同步、云数据、发布及错误恢复。
+
+## 0. 通用建议
+
+- 结构化输出加 `--json`；日志与进度走 stderr。
+- 凭证保存在系统凭证存储（1.0.9+）；`--env prod|pre|local` 隔离身份，凭证不跨 Origin 发送。
+- 空间选择全局保存：`qmuse space list` → `qmuse space use <spaceId>`（保存前校验可访问）。
+
+## 1. 身份与应用
+
+```bash
+qmuse login [--status]           # 浏览器确认登录
+qmuse whoami                     # 验证真实登录身份
+qmuse app create web --file 构思.md   # 统一创建（身份头 → 首轮 SSE 终态）
+qmuse app list / info / use <appId> / current / unlink / update / delete --yes
+```
+
+创建恢复：同 `--request-id` 重发 → `REUSED`，返回已有身份 JSON，不重跑首轮生成。
+断流恢复顺序：`chat state` → `chat history` → 显式 `chat cancel`（如需停止）。
+
+## 2. 初始化与导入
+
+```bash
+qmuse create my-app              # 仅本地模板与说明
+qmuse import /path/to/react-app   # 预检→上传→应用/版本生成
+qmuse import .                    # 已绑定目录的持续更新（UPDATE 语义）
+qmuse import status <jobId> --wait
+qmuse import configure <jobId> --cloud-mode EXTERNAL --public-config '@public.json'
+```
+
+- 云模式：`AUTO`（默认）/`EXTERNAL`（外部云，`--public-config`）/`QMUSE`（需 `--confirm-cloud-service`）。
+- 外部数据不自动迁移：`--acknowledge-empty-cloud-data` 显式确认，不伪装已迁移。
+- 失败诊断：`.qmuse/last-import-error.json`（含 stage/diagnostic/retry 建议）。
+
+## 3. 本地开发
+
+```bash
+qmuse dev [dir] --port 5173      # 连接开发云资源 + 启动本地 Vite
+qmuse dev status                 # 当前会话 pid/appId/localUrl
+qmuse dev stop                   # SIGTERM→8s→SIGKILL，清理会话文件
+qmuse pull [dir]                 # 拉取最新已保存源码（本地有改动先备份并停止）
+```
+
+CLI 凭证不进入浏览器：开发连接由 CLI 代理，浏览器只访问本地服务。
+
+## 4. 对话恢复
+
+```bash
+qmuse chat send --app-id <id> --chat-id <id> --file - \
+  [--model <model>] [--ndjson]
+qmuse chat resume <chatId> --interrupt-id <id> --file 回答.json --app-id <id>
+qmuse chat history --app-id <id> --sprint-id <id>
+qmuse chat state <chatId>            # 先查询再恢复
+qmuse models                         # 模型可用性来自平台
+qmuse chat attachment upload <path> --app-id <id>
+```
+
+中断恢复要点：同一会话与 checkpoint；`--interrupt-id` 来自 chat state/事件；
+重复创建请求只恢复身份（REUSED），不重跑首轮生成。
+
+## 5. 源码同步
+
+```bash
+qmuse version list|info --app-id <id>
+qmuse code export --app-id <id> --output ./exported
+qmuse pull .                       # 最新已保存源码；覆盖前自动备份
+```
+
+上传走 `import`；下载用 `pull`（最新已保存版）或 `code export`（只提供最新已保存版源码）。
+
+## 6. 云数据
+
+```bash
+qmuse data-source list|info --app-id <id>
+qmuse db tables --app-id <id>
+qmuse db records list|get|create|update|delete --app-id <id> --form-id <formId>
+qmuse db permission get --app-id <id> --form-id <formId>
+```
+
+记录写操作受平台数据权限约束；失败以命令输出的 `errorCode`/`errorMessage` 为准。
+
+## 7. 发布与错误恢复
+
+```bash
+qmuse deploy --version <versionId> [--no-wait]   # 固定版本发布（平台安全门禁）
+qmuse release status <releaseId> [--wait]        # 同一查询返回任务详情/检查/地址/失败原因
+qmuse release list --app-id <id>
+```
+
+失败恢复：`release status` 的 `error`/`mosecStatus`/`infosecResult` + `deploy --version` 重发（幂等受理）。
+账户与成本观测：`qmuse account`（余额/权益/消耗摘要/订阅状态只读）。