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

package/README.md

@@ -154,6 +154,20 @@ qmuse import configure <jobId> --cloud-mode EXTERNAL \
 
 本地等待中断不会取消任务。回到原项目目录，使用 `status <jobId> --wait` 继续等待；任务提示需要补充云服务配置时，使用 `configure`。
 
+## 应用创建与管理
+
+```bash
+qmuse app create web --file ./需求.md        # 统一创建接口：一次请求创建应用并开始首轮生成
+qmuse app list --space-id <spaceId> --keyword 关键词
+qmuse app info <appId>
+qmuse app use <appId>                        # 绑定应用到当前目录（.qmuse/app.json）
+qmuse app current / unlink
+qmuse app update <appId> --title 新标题
+qmuse app delete <appId> --yes               # 不可恢复
+```
+
+退出码：成功/恢复身份 0；等待输入 2；失败 1（应用已保留）；本地中断 130。
+
 ## 本地云联调
 
 需要 Node.js 20.19+（或满足项目 Vite 的版本要求）、已安装依赖的 QMuse 模板、一次成功导入和 READY 云后端。首次需要云服务时，先生成最小业务代码与真实 Schema 并导入，再启动：

package/dist/agent-skill.js

@@ -0,0 +1,257 @@
+/**
+ * 官方 CLI Skill（S01）：指南内容随 CLI 包内分发，默认离线安装。
+ * install：复制包内 skills/qmuse-cli/* 到目标（保护用户已有修改），写安装清单；
+ * status：报告安装目标、版本、来源与文件状态（T01.11 记录 skill 事件）。
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { QMUSE_CLI_VERSION } from './version.js';
+const MANIFEST_FILE = '.qmuse-agent-skill-install.json';
+/** 包内指南目录：dist/agent-skill.js 与 src/agent-skill.ts 均位于包根下一级。 */
+export function packagedSkillRoot() {
+    return fileURLToPath(new URL('../skills/qmuse-cli/', import.meta.url));
+}
+export function defaultTargetForAgent(agent) {
+    if (agent === 'codex')
+        return path.join(homedir(), '.codex', 'skills');
+    if (agent === 'claude')
+        return path.join(homedir(), '.claude', 'skills');
+    return path.join(homedir(), '.qwen', 'skills');
+}
+export function manifestPath(targetRoot) {
+    return path.join(targetRoot, 'qmuse-cli', MANIFEST_FILE);
+}
+function fileSha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** 包内指南清单：相对路径 → sha256。 */
+export function packagedFiles() {
+    const root = packagedSkillRoot();
+    const files = new Map();
+    if (!existsSync(root))
+        return files;
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile()) {
+                files.set(path.relative(root, full).split(path.sep).join('/'), fileSha256(readFileSync(full, 'utf8')));
+            }
+        }
+    };
+    walk(root);
+    return files;
+}
+export function readInstallManifest(targetRoot) {
+    const file = manifestPath(targetRoot);
+    if (!existsSync(file))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        return parsed?.skill === 'qmuse-cli' && parsed.schemaVersion === 1 ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function skillStatus(targetRoot) {
+    const packaged = packagedFiles();
+    const report = {
+        packagedVersion: QMUSE_CLI_VERSION,
+        packagedAvailable: packaged.size > 0 && packaged.has('SKILL.md'),
+        packagedFiles: packaged.size,
+        ...(packaged.has('SKILL.md') ? { packagedSkillSha256: packaged.get('SKILL.md') } : {}),
+    };
+    const manifest = readInstallManifest(targetRoot);
+    const installDir = path.join(targetRoot, 'qmuse-cli');
+    const present = new Set();
+    if (existsSync(installDir)) {
+        const walk = (dir) => {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const full = path.join(dir, entry.name);
+                if (entry.isDirectory())
+                    walk(full);
+                else if (entry.isFile())
+                    present.add(path.relative(installDir, full).split(path.sep).join('/'));
+            }
+        };
+        walk(installDir);
+    }
+    let modifiedFiles = [];
+    for (const [relative, digest] of packaged) {
+        const file = path.join(installDir, relative);
+        if (!existsSync(file))
+            continue;
+        try {
+            if (fileSha256(readFileSync(file, 'utf8')) !== digest)
+                modifiedFiles.push(relative);
+        }
+        catch { /* 不可读视为已修改 */ }
+    }
+    modifiedFiles = modifiedFiles.filter(name => name !== MANIFEST_FILE);
+    report.installed = manifest || present.size > 0 ? {
+        address: installDir,
+        agent: manifest?.agent,
+        cliVersion: manifest?.cliVersion,
+        matchesPackagedVersion: manifest?.cliVersion === QMUSE_CLI_VERSION,
+        installedAt: manifest?.installedAt,
+        presentFiles: present.size,
+        expectedFiles: packaged.size,
+        modifiedFiles,
+    } : undefined;
+    return report;
+}
+/** 安装：检查包内必要文件与版本元数据；目标已有内容不同且未 --force 时拒绝（保护用户修改）。 */
+export function installAgentSkill(options) {
+    const packaged = packagedFiles();
+    if (!packaged.has('SKILL.md')) {
+        throw new Error(`CLI 包内缺少官方指南文件（SKILL.md）：${packagedSkillRoot()}`);
+    }
+    const installDir = path.join(options.targetRoot, 'qmuse-cli');
+    const previous = readInstallManifest(options.targetRoot);
+    // 已装文件与包内不一致时分两类：用户确实改过（保护）／上游内容变更（应刷新）。
+    const userModified = [];
+    const upstreamChanged = [];
+    if (existsSync(installDir)) {
+        for (const [relative, digest] of packaged) {
+            const file = path.join(installDir, relative);
+            if (!existsSync(file))
+                continue;
+            let installed;
+            try {
+                installed = fileSha256(readFileSync(file, 'utf8'));
+            }
+            catch {
+                installed = undefined;
+            }
+            if (installed === digest)
+                continue;
+            const baseline = previous?.installedDigests?.[relative];
+            // 无摘要基线（老版本安装）时按用户修改处理，保持保守语义。
+            if (baseline && installed === baseline)
+                upstreamChanged.push(relative);
+            else
+                userModified.push(relative);
+        }
+    }
+    const sameVersion = previous?.cliVersion === QMUSE_CLI_VERSION;
+    if (options.force !== true) {
+        if (sameVersion && userModified.length === 0 && upstreamChanged.length === 0) {
+            // 已安装内容与包完全一致：幂等返回，不重写文件。
+            const manifest = previous;
+            return { address: installDir, installedFiles: [...packaged.keys()], manifest, replaced: false };
+        }
+        if (userModified.length > 0) {
+            throw new Error(`检测到用户修改过的指南文件（${userModified.join(', ')}）。保留修改请跳过安装；确需覆盖请加 --force。`);
+        }
+    }
+    mkdirSync(options.targetRoot, { recursive: true });
+    if (options.force === true) {
+        // 强制覆盖：仅移除“包内文件 ∪ 上次安装清单”范围的文件（用户自加文件一律保留），最后剪掉空目录。
+        const managed = new Set([...packaged.keys(), MANIFEST_FILE, ...(previous?.installedFiles ?? [])]);
+        if (existsSync(installDir)) {
+            const rm = (dir) => {
+                for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                    const full = path.join(dir, entry.name);
+                    const rel = path.relative(installDir, full).split(path.sep).join('/');
+                    if (entry.isDirectory()) {
+                        rm(full);
+                        if (readdirSync(full).length === 0)
+                            rmSync(full, { recursive: true, force: true }); // 仅剪空目录（递归以兼容目录删除）
+                    }
+                    else if (managed.has(rel)) {
+                        rmSync(full, { force: true });
+                    }
+                }
+            };
+            rm(installDir);
+        }
+    }
+    else if (previous?.installedFiles?.length) {
+        // 升级残留清理：删“上次装的、新包不再提供且未被用户改动核对需要”的文件（无旧 digest，直接按清单删）。
+        for (const staleFile of previous.installedFiles) {
+            if (packaged.has(staleFile))
+                continue; // 新包仍提供 → cpSync 覆盖
+            if (staleFile === MANIFEST_FILE)
+                continue; // 清单本体重写
+            const target = path.join(installDir, staleFile);
+            try {
+                if (existsSync(target))
+                    rmSync(target, { force: true });
+            }
+            catch { /* 清理尽力而为 */ }
+        }
+    }
+    cpSync(packagedSkillRoot(), installDir, { recursive: true });
+    const manifest = {
+        schemaVersion: 1,
+        skill: 'qmuse-cli',
+        cliVersion: QMUSE_CLI_VERSION,
+        ...(options.agent ? { agent: options.agent } : {}),
+        source: 'packaged',
+        installedAt: new Date().toISOString(),
+    };
+    const installedFiles = [...packaged.keys(), MANIFEST_FILE];
+    const installedDigests = Object.fromEntries(packaged.entries());
+    writeFileSync(path.join(installDir, MANIFEST_FILE), `${JSON.stringify({ ...manifest, installedFiles, installedDigests }, null, 2)}\n`, 'utf8');
+    // 安装自检：必要文件必须存在且版本元数据可读。
+    for (const required of ['SKILL.md', 'references/cloud.md', 'references/core-flows.md']) {
+        const file = path.join(installDir, required);
+        if (!existsSync(file) || !statSync(file).isFile()) {
+            throw new Error(`安装自检失败：缺少 ${required}`);
+        }
+    }
+    const persisted = readInstallManifest(options.targetRoot);
+    if (!persisted || !persisted.installedFiles)
+        throw new Error('安装自检失败：版本元数据或文件清单不可读');
+    return { address: installDir, installedFiles, manifest: persisted, replaced: true };
+}
+/**
+ * 升级 CLI 后同步「已存在的」官方指南安装 —— 不创建新目标，不覆盖用户修改。
+ * 供 `qmuse upgrade` 复用：只处理探测得到的既有安装，冲突跳过而非报错。
+ */
+export function syncInstalledSkills(options = {}) {
+    const candidates = [];
+    const agentRoots = options.agentRoots ?? {};
+    for (const agent of options.agents ?? ['codex', 'claude']) {
+        candidates.push({ root: agentRoots[agent] ?? defaultTargetForAgent(agent), agent });
+    }
+    for (const root of options.extraTargets ?? [])
+        candidates.push({ root });
+    const results = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        const installDir = path.join(candidate.root, 'qmuse-cli');
+        if (!existsSync(installDir) || seen.has(installDir))
+            continue;
+        seen.add(installDir);
+        const manifest = readInstallManifest(candidate.root);
+        const base = {
+            address: installDir,
+            ...(candidate.agent ?? manifest?.agent ? { agent: candidate.agent ?? manifest?.agent } : {}),
+        };
+        if (!manifest) {
+            // 没有版本元数据：当作非本工具安装，不触碰。
+            results.push({ ...base, outcome: 'skipped-user-modified', detail: '缺少安装元数据，未改动' });
+            continue;
+        }
+        try {
+            const result = installAgentSkill({ targetRoot: candidate.root, agent: candidate.agent ?? manifest.agent });
+            results.push({ ...base, outcome: result.replaced ? 'refreshed' : 'up-to-date' });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            // 用户改过指南：保留用户版本，不阻断升级。
+            results.push({
+                ...base,
+                outcome: /用户修改过/u.test(message) ? 'skipped-user-modified' : 'failed',
+                detail: message.slice(0, 200),
+            });
+        }
+    }
+    return results;
+}

package/dist/app/account.js

@@ -0,0 +1,23 @@
+/**
+ * 账户域（C29）：Point/Benefit 现有 SPACE 只读契约。
+ * (套餐/订阅由 PC 承载，无独立 CLI 可用接口——清单相应项标注依赖。)
+ */
+import { apiCall } from '../client.js';
+export function pointBalance(spaceId, cfg) {
+    return apiCall('GET', `/api/point/balance?spaceId=${encodeURIComponent(spaceId)}`, undefined, cfg);
+}
+export function pointRecords(spaceId, query = {}, cfg) {
+    return apiCall('POST', '/api/point/records', { spaceId, ...query }, cfg);
+}
+export function pointConsumeStats(spaceId, query = {}, cfg) {
+    const { pageIndex, pageSize, ...rest } = query;
+    return apiCall('POST', '/api/point/records/consume-stats', {
+        spaceId,
+        ...(rest),
+        ...(pageIndex ? { pageIndex: Number(pageIndex) } : {}),
+        ...(pageSize ? { pageSize: Number(pageSize) } : {}),
+    }, cfg);
+}
+export function benefitEntitlements(spaceId, cfg) {
+    return apiCall('GET', `/api/benefit/entitlements?spaceId=${encodeURIComponent(spaceId)}`, undefined, cfg);
+}

package/dist/app/api.js

@@ -0,0 +1,51 @@
+/**
+ * 应用域接口（C03）：基于 musepub AppController 现有契约。
+ *
+ *  - POST /api/app/queryAppListBySpaceId 分页查询空间应用列表
+ *  - POST /api/app/queryAppInfo 查询应用详情
+ *  - POST /api/app/update 白名单字段更新
+ *  - POST /api/app/delete 删除应用
+ */
+import { apiCall } from '../client.js';
+function cleanOptional(value) {
+    const trimmed = value?.trim?.();
+    return trimmed ? trimmed : undefined;
+}
+export function queryAppListBySpaceId(spaceId, query, cfg) {
+    const body = {
+        spaceId,
+        pageIndex: query.pageIndex ?? 1,
+        pageSize: query.pageSize ?? 20,
+    };
+    const keyword = cleanOptional(query.searchKeyword);
+    if (keyword)
+        body.searchKeyword = keyword;
+    const appType = cleanOptional(query.appType);
+    if (appType)
+        body.appType = appType;
+    const publishStatus = cleanOptional(query.publishStatus);
+    if (publishStatus)
+        body.publishStatus = publishStatus;
+    return apiCall('POST', '/api/app/queryAppListBySpaceId', body, cfg);
+}
+export function queryAppInfo(appId, cfg) {
+    return apiCall('POST', '/api/app/queryAppInfo', { appId }, cfg);
+}
+export async function updateApp(appId, patch, cfg) {
+    const body = { appId };
+    if (cleanOptional(patch.title))
+        body.title = patch.title.trim();
+    if (patch.description !== undefined)
+        body.description = patch.description;
+    if (patch.requireLogin !== undefined)
+        body.requireLogin = patch.requireLogin;
+    if (cleanOptional(patch.defaultDevice))
+        body.defaultDevice = patch.defaultDevice.trim();
+    if (Object.keys(body).length === 1) {
+        throw new Error('app update 需要至少一个待修改字段：--title / --description / --require-login / --default-device');
+    }
+    return apiCall('POST', '/api/app/update', body, cfg);
+}
+export function deleteApp(appId, cfg) {
+    return apiCall('POST', '/api/app/delete', { appId }, cfg);
+}

package/dist/app/binding.js

@@ -0,0 +1,48 @@
+/**
+ * 本地应用绑定（C03.06/C03.07/C03.08）。
+ *
+ * 独立的轻量绑定文件 `.qmuse/app.json`：记录当前目录绑定的已有应用，
+ * 供 `qmuse app use / current / unlink` 及后续 dev/publish 命令读取。
+ * 与导入链路的 `.qmuse/project.json` 互不干扰：导入绑定继续由
+ * import/project.ts 管理（含 sourceHash/jobId 等导入语义字段）。
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const APP_BINDING_FILE = join('.qmuse', 'app.json');
+export function loadAppBinding(rootDir = process.cwd()) {
+    const path = join(rootDir, APP_BINDING_FILE);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            && parsed.schemaVersion === 1
+            && typeof parsed.appId === 'string'
+            && parsed.appId.trim()) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveAppBinding(binding, rootDir = process.cwd()) {
+    const path = join(rootDir, APP_BINDING_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    const value = {
+        ...binding,
+        appId: binding.appId.trim(),
+        schemaVersion: 1,
+        boundAt: new Date().toISOString(),
+    };
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    return path;
+}
+export function clearAppBinding(rootDir = process.cwd()) {
+    const path = join(rootDir, APP_BINDING_FILE);
+    if (!existsSync(path))
+        return false;
+    unlinkSync(path);
+    return true;
+}