@qmuse/qmuse-cli 1.0.11 → 1.0.12

package/README.md

@@ -10,6 +10,20 @@
 npm install -g @qmuse/qmuse-cli
 ```
 
+## AI 编程工具技能
+
+官方技能随 CLI 包离线分发，支持 Codex、Claude Code、Cursor、Trae、CodeBuddy、Qoder 和 Qwen Code。
+
+```bash
+qmuse agent-skill list
+qmuse agent-skill install --agent cursor
+qmuse agent-skill status --agent cursor --json
+```
+
+工具标识依次为 `codex`、`claude`、`cursor`、`trae`、`codebuddy`、`qoder`、`qwen`。省略 `--agent` 时按本机目录探测；多个目录时在终端选择，脚本需显式指定目标。自定义路径用 `--target "$HOME/my-tool/skills"`，CLI 自动追加 `/qmuse-cli`。
+
+安装后核对 `installed.address` 和 `installed.upToDate`；状态同时检查版本、缺失文件及内容变化。`qmuse upgrade` 升级后同步已有的默认安装和已登记的自定义目录，保留用户修改。详细步骤见 [技能安装说明](https://www.qmuse.cn/skill-setup.md)。
+
 ## 快速开始
 
 ```bash

package/dist/agent-skill.js

@@ -15,11 +15,59 @@ 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');
+    const supported = SKILL_AGENTS.find(item => item.id === agent);
+    if (!supported)
+        throw new Error(`未知工具 ${agent}。支持：${SKILL_AGENTS.map(item => item.id).join(', ')}；其他工具请使用 --target <skills 目录>。`);
+    return path.join(homedir(), supported.directory, 'skills');
+}
+/** 安装、发现和升级同步共用的工具目录。 */
+export const SKILL_AGENTS = [
+    { id: 'codex', name: 'Codex', directory: '.codex' },
+    { id: 'claude', name: 'Claude Code', directory: '.claude' },
+    { id: 'cursor', name: 'Cursor', directory: '.cursor' },
+    { id: 'trae', name: 'Trae', directory: '.trae' },
+    { id: 'codebuddy', name: 'CodeBuddy', directory: '.codebuddy' },
+    { id: 'qoder', name: 'Qoder', directory: '.qoder' },
+    { id: 'qwen', name: 'Qwen Code', directory: '.qwen' },
+];
+function skillTargetsFile() {
+    return path.join(homedir(), '.qmuse-cli', 'skill-targets.json');
+}
+function rememberedSkillTargets(file) {
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : [];
+}
+/** 仅在 CLI 安装成功后登记，便于升级找到非默认目录；不存凭证或上报本机路径。 */
+export function rememberSkillTarget(targetRoot, agent, file = skillTargetsFile()) {
+    const root = path.resolve(targetRoot);
+    const targets = rememberedSkillTargets(file);
+    const previous = targets.find(item => item.targetRoot === root);
+    if (previous && previous.agent === agent)
+        return;
+    const next = targets.filter(item => item.targetRoot !== root);
+    next.push({ targetRoot: root, ...(agent ? { agent } : {}) });
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+}
+export function listSkillTargets(file = skillTargetsFile()) {
+    const targets = SKILL_AGENTS.map(agent => ({
+        agent: agent.id,
+        name: agent.name,
+        targetRoot: defaultTargetForAgent(agent.id),
+        detected: existsSync(path.join(homedir(), agent.directory)),
+        custom: false,
+    }));
+    for (const saved of rememberedSkillTargets(file)) {
+        if (targets.some(item => item.targetRoot === saved.targetRoot))
+            continue;
+        targets.push({
+            agent: saved.agent ?? 'custom',
+            name: `${SKILL_AGENTS.find(item => item.id === saved.agent)?.name ?? '自定义工具'}（自定义目录）`,
+            targetRoot: saved.targetRoot,
+            detected: existsSync(saved.targetRoot),
+            custom: true,
+        });
+    }
+    return targets.map(target => ({ ...target, ...skillStatus(target.targetRoot) }));
 }
 export function manifestPath(targetRoot) {
     return path.join(targetRoot, 'qmuse-cli', MANIFEST_FILE);
@@ -81,27 +129,51 @@ export function skillStatus(targetRoot) {
         };
         walk(installDir);
     }
-    let modifiedFiles = [];
-    for (const [relative, digest] of packaged) {
+    const modifiedFiles = [];
+    const missingFiles = [];
+    const outdatedFiles = [];
+    const staleFiles = [];
+    for (const relative of new Set([...packaged.keys(), ...(manifest?.installedFiles ?? [])])) {
+        if (relative === MANIFEST_FILE)
+            continue;
+        const digest = packaged.get(relative);
         const file = path.join(installDir, relative);
-        if (!existsSync(file))
+        if (!present.has(relative)) {
+            if (digest)
+                missingFiles.push(relative);
             continue;
+        }
         try {
-            if (fileSha256(readFileSync(file, 'utf8')) !== digest)
+            const installed = fileSha256(readFileSync(file, 'utf8'));
+            if (installed === digest)
+                continue;
+            if (installed !== manifest?.installedDigests?.[relative])
                 modifiedFiles.push(relative);
+            else if (digest)
+                outdatedFiles.push(relative);
+            else
+                staleFiles.push(relative);
+        }
+        catch {
+            modifiedFiles.push(relative);
         }
-        catch { /* 不可读视为已修改 */ }
     }
-    modifiedFiles = modifiedFiles.filter(name => name !== MANIFEST_FILE);
-    report.installed = manifest || present.size > 0 ? {
+    const matchesPackagedContent = missingFiles.length === 0 && modifiedFiles.length === 0 && outdatedFiles.length === 0 && staleFiles.length === 0;
+    report.installed = existsSync(installDir) ? {
         address: installDir,
         agent: manifest?.agent,
         cliVersion: manifest?.cliVersion,
         matchesPackagedVersion: manifest?.cliVersion === QMUSE_CLI_VERSION,
         installedAt: manifest?.installedAt,
-        presentFiles: present.size,
+        presentFiles: packaged.size - missingFiles.length,
         expectedFiles: packaged.size,
         modifiedFiles,
+        missingFiles,
+        outdatedFiles,
+        staleFiles,
+        complete: missingFiles.length === 0,
+        matchesPackagedContent,
+        upToDate: report.packagedAvailable && manifest?.cliVersion === QMUSE_CLI_VERSION && matchesPackagedContent,
     } : undefined;
     return report;
 }
@@ -116,11 +188,15 @@ export function installAgentSkill(options) {
     // 已装文件与包内不一致时分两类：用户确实改过（保护）／上游内容变更（应刷新）。
     const userModified = [];
     const upstreamChanged = [];
+    const missingFiles = [];
+    const staleFiles = [];
     if (existsSync(installDir)) {
         for (const [relative, digest] of packaged) {
             const file = path.join(installDir, relative);
-            if (!existsSync(file))
+            if (!existsSync(file)) {
+                missingFiles.push(relative);
                 continue;
+            }
             let installed;
             try {
                 installed = fileSha256(readFileSync(file, 'utf8'));
@@ -137,10 +213,29 @@ export function installAgentSkill(options) {
             else
                 userModified.push(relative);
         }
+        for (const relative of previous?.installedFiles ?? []) {
+            if (packaged.has(relative) || relative === MANIFEST_FILE)
+                continue;
+            const file = path.join(installDir, relative);
+            if (!existsSync(file))
+                continue;
+            let installed;
+            try {
+                installed = fileSha256(readFileSync(file, 'utf8'));
+            }
+            catch {
+                installed = undefined;
+            }
+            const baseline = previous?.installedDigests?.[relative];
+            if (baseline && installed === baseline)
+                staleFiles.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) {
+        if (sameVersion && userModified.length === 0 && upstreamChanged.length === 0 && missingFiles.length === 0 && staleFiles.length === 0) {
             // 已安装内容与包完全一致：幂等返回，不重写文件。
             const manifest = previous;
             return { address: installDir, installedFiles: [...packaged.keys()], manifest, replaced: false };
@@ -171,13 +266,9 @@ export function installAgentSkill(options) {
             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; // 清单本体重写
+    else {
+        // 只清理新包不再提供、且内容仍与上次安装摘要一致的旧文件。
+        for (const staleFile of staleFiles) {
             const target = path.join(installDir, staleFile);
             try {
                 if (existsSync(target))
@@ -217,15 +308,18 @@ export function installAgentSkill(options) {
 export function syncInstalledSkills(options = {}) {
     const candidates = [];
     const agentRoots = options.agentRoots ?? {};
-    for (const agent of options.agents ?? ['codex', 'claude']) {
+    for (const agent of options.agents ?? SKILL_AGENTS.map(item => item.id)) {
         candidates.push({ root: agentRoots[agent] ?? defaultTargetForAgent(agent), agent });
     }
     for (const root of options.extraTargets ?? [])
         candidates.push({ root });
+    for (const saved of rememberedSkillTargets(options.targetsFile ?? skillTargetsFile())) {
+        candidates.push({ root: saved.targetRoot, agent: saved.agent });
+    }
     const results = [];
     const seen = new Set();
     for (const candidate of candidates) {
-        const installDir = path.join(candidate.root, 'qmuse-cli');
+        const installDir = path.resolve(candidate.root, 'qmuse-cli');
         if (!existsSync(installDir) || seen.has(installDir))
             continue;
         seen.add(installDir);

package/dist/api.js

@@ -12,8 +12,8 @@ export function consumeSessionExchangeToken(token, opts) {
     return apiCall('POST', '/api/login/session-exchange/consume', { token }, { anonymous: true, ...opts });
 }
 /** 查询服务端实际登录身份，不触发 /api/user/me 的奖励和活跃副作用。 */
-export function whoami(cfg) {
-    return apiCall('GET', '/api/user/whoami', undefined, cfg);
+export function whoami(cfg, options = {}) {
+    return apiCall('GET', '/api/user/whoami', undefined, { cfg, ...options });
 }
 export function listSpaces(pageIndex = 1, pageSize = 20, cfg) {
     const path = `/api/space/list?pageIndex=${pageIndex}&pageSize=${pageSize}`;

package/dist/app/chat.js

@@ -150,7 +150,7 @@ async function readChatStream(res, result, opts) {
         const type = chatEventType(payload);
         opts.onEvent?.({ sequence: ++result.eventCount, type, payload });
         if (type === 'finish') {
-            terminal = 'SUCCEEDED';
+            terminal = sawInterrupt ? 'WAITING_INPUT' : 'SUCCEEDED';
             return true;
         }
         if (type === 'error' || type === 'llm-error' || type === 'data-llm-error') {
@@ -162,7 +162,9 @@ async function readChatStream(res, result, opts) {
             const record = payload;
             if (type === 'tool-input-start' || type === 'tool-input-end')
                 result.toolConsumed = true;
-            const interrupts = record.interrupts
+            const interrupts = record.__interrupt__
+                ?? record.data?.__interrupt__
+                ?? record.interrupts
                 ?? record.data?.interrupts;
             if (Array.isArray(interrupts) && interrupts.length > 0)
                 sawInterrupt = true;

package/dist/app/create.js

@@ -138,7 +138,9 @@ function extractInterrupts(payload) {
         return false;
     const data = payload.data;
     const candidates = [
+        payload.__interrupt__,
         payload.interrupts,
+        data && typeof data === 'object' ? data.__interrupt__ : undefined,
         data && typeof data === 'object' ? data.interrupts : undefined,
     ];
     return candidates.some(candidate => Array.isArray(candidate) && candidate.length > 0);
@@ -269,7 +271,7 @@ export async function createAppChat(cfg, input, opts = {}) {
             const type = chatEventType(payload);
             opts.onEvent?.({ sequence, type, payload });
             if (type === 'finish') {
-                terminal = 'SUCCEEDED';
+                terminal = sawInterrupt ? 'WAITING_INPUT' : 'SUCCEEDED';
                 return true;
             }
             if (type === 'error' || type === 'llm-error' || type === 'data-llm-error') {

package/dist/cli.js

@@ -8,12 +8,14 @@ import { recordOperation, withOperationLog } from './operation-log.js';
  */
 import { loadConfig, saveConfig, deleteSession, findConfigPath } from './config.js';
 import { hasAuth, apiCall } from './client.js';
-import { log } from './logger.js';
+import { log, setStructuredOutput } from './logger.js';
 import * as api from './api.js';
 import * as login from './login.js';
 import { prompt, closePrompt } from './login.js';
 import { randomBytes } from 'node:crypto';
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { createImportArchive } from './import/archive.js';
@@ -45,7 +47,7 @@ import { recordEvent, setTelemetryCommand, currentCommandLabel } from './telemet
 import { trackCommand } from './tracker.js';
 import { buildCliError, sanitizeMessage } from './errors.js';
 import { checkVersionGate, defaultUpgradeCommand, envPolicyProvider, registryPolicyProvider, shouldUpgrade } from './version-gate.js';
-import { installAgentSkill, skillStatus, syncInstalledSkills, defaultTargetForAgent } from './agent-skill.js';
+import { installAgentSkill, skillStatus, syncInstalledSkills, defaultTargetForAgent, listSkillTargets, rememberSkillTarget } from './agent-skill.js';
 import { startDevelopment } from './dev/index.js';
 import { createProject } from './create.js';
 import { pullProject } from './pull.js';
@@ -895,8 +897,11 @@ async function cmdDeploy(command, flags) {
     recordEvent({ kind: 'cli.task.state', route: '/api/deploy/create', stage: 'accepted',
         operationId: deployId || undefined, result: 'ok' });
     const wait = await waitDeployResult(deployId, cfg, { noWait: flags['--no-wait'] === true });
+    const success = !wait.timedOut && !!wait.ticket
+        && wait.ticket.status !== 'DEPLOY_FAILED' && wait.ticket.status !== 'CANCEL'
+        && (!wait.lastError || wait.ticket.status === 'DEPLOYED');
     const payload = {
-        success: !wait.timedOut,
+        success,
         appId,
         versionId,
         deployId: deployId || undefined,
@@ -918,8 +923,7 @@ async function cmdDeploy(command, flags) {
         else if (!flags['--no-wait'])
             log.info('继续查询：qmuse release status ' + deployId);
     }
-    if (wait.timedOut || payload.status === 'DEPLOY_FAILED' || payload.status === 'CANCEL')
-        process.exitCode = 1;
+    process.exitCode = success ? 0 : 1;
     // T01.08：发布终态来源（receipt 由服务端任务记录，这里保留 CLI 端可观测尾部）。
     recordEvent({ kind: 'cli.task.state', route: '/api/deploy/query', stage: 'terminal',
         operationId: deployId || undefined, status: wait.timedOut ? 'timeout' : String(payload.status ?? 'unknown').toLowerCase(),
@@ -937,14 +941,17 @@ async function cmdRelease(command, flags) {
         const wait = await waitDeployResult(releaseId, cfg, { noWait: flags['--wait'] !== true });
         const summary = summarizeDeployTicket(wait.ticket);
         const lookupFailed = !wait.ticket;
+        const success = !wait.timedOut && !lookupFailed
+            && summary.status !== 'DEPLOY_FAILED' && summary.status !== 'CANCEL'
+            && (!wait.lastError || summary.status === 'DEPLOYED');
+        process.exitCode = success ? 0 : 1;
         if (flags['--json'] === true) {
-            output({ success: !wait.timedOut && !lookupFailed && summary.status !== 'DEPLOY_FAILED' && summary.status !== 'CANCEL', timedOut: wait.timedOut || undefined, error: wait.lastError, ...summary }, flags);
+            output({ success, timedOut: wait.timedOut || undefined, error: wait.lastError, ...summary }, flags);
             return;
         }
         log.info(`发布单 ${releaseId} 状态：${String(summary.status ?? 'UNKNOWN')}${wait.timedOut ? '（等待超时）' : ''}`);
         if (summary.publishUrl)
             log.success(`发布地址：${String(summary.publishUrl)}`);
-        process.exitCode = wait.timedOut || summary.status === 'DEPLOY_FAILED' || summary.status === 'CANCEL' ? 1 : 0;
         return;
     }
     if (sub === 'list') {
@@ -1141,6 +1148,7 @@ async function cmdWhoami(flags) {
         failApi(result, '查询当前用户失败');
     }
     const currentUser = result.data;
+    trackCommand('whoami', cfg, currentUser.userId);
     const tenantName = tenantDisplayName(currentUser.tenantCode, currentUser.tenantName);
     if (flags['--json'] === true) {
         output({
@@ -1243,7 +1251,7 @@ async function readCreateContent(flags) {
         }
     }
     if (!file && process.stdin.isTTY === true) {
-        fail('用法: qmuse app create <web|h5> --file <路径|->（--file - 从管道读取）');
+        fail('用法: qmuse app create <web|h5|ai> --file <路径|->（--file - 从管道读取）');
     }
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -1688,8 +1696,10 @@ async function cmdChat(command, flags) {
         }
         else {
             log.error(`恢复未完成：${result.status}${result.errorText ? `，${result.errorText}` : ''}`);
-            process.exitCode = result.status === 'WAITING_INPUT' ? 2 : 1;
         }
+        process.exitCode = result.status === 'SUCCEEDED' ? 0
+            : result.status === 'WAITING_INPUT' ? 2
+                : result.status === 'INTERRUPTED' ? 130 : 1;
         // T01.04：恢复流终态来源（同一会话 checkpoint，不重跑首轮生成）。
         recordEvent({ kind: 'cli.sse.result', route: '/api/chat', result: result.status.toLowerCase(), operationId });
         return;
@@ -1773,8 +1783,10 @@ async function cmdChat(command, flags) {
         }
         else {
             log.error(`对话未完成：${result.status}${result.errorText ? `，${result.errorText}` : ''}`);
-            process.exitCode = result.status === 'WAITING_INPUT' ? 2 : 1;
         }
+        process.exitCode = result.status === 'SUCCEEDED' ? 0
+            : result.status === 'WAITING_INPUT' ? 2
+                : result.status === 'INTERRUPTED' ? 130 : 1;
         // T01.04：已有会话 continue 流终态来源。
         recordEvent({ kind: 'cli.sse.result', route: '/api/chat', result: result.status.toLowerCase(), operationId });
         return;
@@ -2292,8 +2304,8 @@ async function cmdDb(command, flags) {
     const appId = pickString(flags, '--app-id');
     const formId = pickString(flags, '--form-id');
     const env = pickString(flags, '--cloud-env') ?? 'dev';
-    if (!appId || !formId)
-        fail('用法: qmuse db <子命令> --app-id <appId> --form-id <formId>');
+    if (!appId)
+        fail('用法: qmuse db <子命令> --app-id <appId>');
     if (sub === 'tables') {
         const r = await queryAppMetadata(appId, ((await listAppVersions(appId, cfg)).data?.list ?? [])[0]?.id ?? '', cfg);
         if (!r.ok || !r.data)
@@ -2301,6 +2313,8 @@ async function cmdDb(command, flags) {
         output(r.data, flags);
         return;
     }
+    if (!formId)
+        fail('用法: qmuse db <子命令> --app-id <appId> --form-id <formId>');
     if (sub === 'permission' && command[2] === 'get') {
         const r = await queryFormAuth(appId, formId, cfg);
         if (!r.ok || !r.data)
@@ -2573,7 +2587,7 @@ async function cmdInfo(command, flags) {
             { domain: '数据调试', entry: 'data-source list|info、db tables|records|permission', requires: '会话+appId（记录写操作依赖平台数据权限）' },
             { domain: '云服务与环境', entry: 'cloud init|enable|status|environment retry|pull-env|set-secret|schema', requires: '会话+权益' },
             { domain: '函数、秘密、沙箱', entry: 'fn …、secret list|create|delete|sync …、sandbox status|logs|health|restart|setting-get', requires: '会话+appId；沙箱写操作依赖平台沙箱通道' },
-            { domain: '官方 Skill', entry: 'agent-skill install|status（指南随 CLI 包内分发）', requires: '本地安装目标' },
+            { domain: '官方 Skill', entry: 'agent-skill list|install|status（指南随 CLI 包内分发）', requires: '本地安装目标' },
         ],
         unsupported: [
             { capability: '套餐与订阅（购买型）', reason: 'PC 端承载；CLI 仅读订阅状态（account overview 汇总，缺少契约时标注 unsupported）' },
@@ -2597,7 +2611,7 @@ async function cmdInfo(command, flags) {
  * 策略读不到时一律放行——闸门不可用绝不锁死用户。
  */
 async function enforceVersionGate(root, flags) {
-    if (root === undefined)
+    if (root === undefined || root === 'upgrade')
         return;
     const gateEnabled = process.env.QMUSE_VERSION_GATE !== 'off';
     if (!gateEnabled)
@@ -2635,7 +2649,7 @@ async function cmdUpgrade(command, flags) {
     if (command.length > 1)
         fail('用法：qmuse upgrade [--json]', { code: 'INVALID_ARGUMENTS' });
     log.info('检查最新版本…');
-    const provider = registryPolicyProvider({ distribution: QMUSE_CLI_DISTRIBUTION, timeoutMs: 5000 });
+    const provider = registryPolicyProvider({ distribution: QMUSE_CLI_DISTRIBUTION, timeoutMs: 5000, refresh: true });
     const snapshot = await provider();
     if (!snapshot?.latest) {
         fail('无法获取最新版本信息', {
@@ -2662,11 +2676,13 @@ async function cmdUpgrade(command, flags) {
         log.info('正在升级…');
     }
     const distribution = QMUSE_CLI_DISTRIBUTION;
+    const packageName = distribution === 'PUBLIC' ? '@qmuse/qmuse-cli' : '@alipay/qmuse-cli';
     const args = distribution === 'PUBLIC'
-        ? ['install', '-g', `@qmuse/qmuse-cli@${latest}`, '--registry=https://registry.npmjs.org/']
-        : ['install', '-g', `@alipay/qmuse-cli@${latest}`];
+        ? ['install', '-g', `${packageName}@${latest}`, '--registry=https://registry.npmjs.org/']
+        : ['install', '-g', `${packageName}@${latest}`];
     const result = await new Promise((resolve) => {
         const child = spawn('npm', args, { stdio: flags['--json'] === true ? 'pipe' : 'inherit', shell: process.platform === 'win32' });
+        child.stdout?.resume();
         let stderr = '';
         child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
         child.on('close', (code) => resolve(code === 0 ? { ok: true } : { ok: false, detail: stderr.slice(-500) }));
@@ -2680,7 +2696,7 @@ async function cmdUpgrade(command, flags) {
         });
     }
     // 升级成功后顺带同步「已存在」的官方指南安装（不新建目标、不覆盖用户修改、失败不影响升级结论）。
-    const skillSync = syncInstalledSkills();
+    const skillSync = await syncUpgradedSkills(packageName);
     if (flags['--json'] === true) {
         output({ success: true, from: current, to: latest, skillSync }, flags);
         return;
@@ -2688,6 +2704,24 @@ async function cmdUpgrade(command, flags) {
     log.success(`已升级到 ${latest}`);
     reportSkillSync(skillSync);
 }
+/** 从安装后的全局包启动新进程，避免旧进程的模块缓存把旧版本写入安装清单。 */
+async function syncUpgradedSkills(packageName) {
+    const execFileAsync = promisify(execFile);
+    let address = packageName;
+    try {
+        const { stdout: root } = await execFileAsync('npm', ['root', '-g'], {
+            encoding: 'utf8', shell: process.platform === 'win32',
+        });
+        address = path.join(root.trim(), packageName);
+        const moduleUrl = pathToFileURL(path.join(address, 'dist', 'agent-skill.js')).href;
+        const script = `import { syncInstalledSkills } from ${JSON.stringify(moduleUrl)}; process.stdout.write(JSON.stringify(syncInstalledSkills()));`;
+        const { stdout } = await execFileAsync(process.execPath, ['--input-type=module', '--eval', script], { encoding: 'utf8' });
+        return JSON.parse(stdout);
+    }
+    catch (error) {
+        return [{ address, outcome: 'failed', detail: sanitizeMessage(error instanceof Error ? error.message : String(error)) }];
+    }
+}
 /** 输出指南同步结果（升级前后共用）。 */
 function reportSkillSync(items) {
     if (items.length === 0) {
@@ -2798,8 +2832,11 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   release status <releaseId> [--wait]              查询发布任务详情/检查/地址/失败原因
   release list --app-id <id>                       查询应用发布记录（--last 查最近一次）
   info [--app-id <id>]                             CLI 版本/环境/绑定/模板约束/云架构/能力
-  agent-skill install --agent codex                安装包内官方研发指南（--target 覆盖；--force 覆盖修改）
-  agent-skill status [--agent codex|--target <dir>] 查询指南安装状态与用户修改
+  agent-skill list                                列出支持的工具、探测目录和安装状态
+  agent-skill install [--agent <tool>]             安装包内指南；省略工具时探测并选择
+    --agent codex|claude|cursor|trae|codebuddy|qoder|qwen
+    --target <skills-dir>                         自定义父目录（自动追加 /qmuse-cli）；--force 覆盖修改
+  agent-skill status [--agent <tool>|--target <dir>] 查询版本、缺失文件与用户修改；省略目标时列出全部
   upgrade                                          自查最新版本并升级 CLI（--json 结构化输出）
   account overview|benefit|points …                 空间余额/权益/喵币消耗/订阅状态（--space-id）
   data-source list|info                            应用数据源与表元数据（--app-id）
@@ -2813,7 +2850,7 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   sandbox logs --app-id <id>                       现有接口可提供的构建/任务诊断日志
       [--sandbox-id <id>] [--version-id <id>] [--build-id <id>]
   sandbox health|restart|setting-get|ensure        沙箱其余只读与显式重启入口
-  app create <web|h5> --file <路径|->               统一创建应用并开始首轮生成（预发接口）
+  app create <web|h5|ai> --file <路径|->            创建应用并开始首轮生成
       [--title <title>] [--space-id <id>] [--request-id <cc_时间戳_随机hex>]
       [--model <model>] [--no-open] [--json|--ndjson]
   app list [--space-id <id>] [--keyword <kw>]        查询空间应用列表
@@ -2862,6 +2899,7 @@ async function main() {
         return;
     }
     const { command, flags } = parseArgs(argv);
+    setStructuredOutput(flags['--json'] === true || flags['--ndjson'] === true);
     if (flags['--help'] === true || flags['-h'] === true) {
         recordCommandEvent(currentCommandLabel(command), 0, Date.now());
         process.stdout.write(HELP);
@@ -2878,14 +2916,15 @@ async function main() {
     const commandStartedAt = Date.now();
     recordEvent({ kind: 'cli.command.start', command: commandLabel,
         environment: str(flags, '--env') });
-    // MAU：模拟 Tracert dwcookie 协议上报到蚂蚁采集平台
-    trackCommand(commandLabel.replace(/ /gu, '-'), resolveCfg(flags));
     const finishUpdateNotice = startUpdateNotice({
         enabled: root === 'import' && process.stderr.isTTY === true && flags['--json'] !== true,
         notify: message => process.stderr.write(`${message}\n`),
     });
     process.once('exit', finishUpdateNotice);
     try {
+        // whoami 直接复用业务响应中的身份，其余命令的身份查询与采集共享短预算。
+        if (root !== 'whoami')
+            trackCommand(commandLabel.replace(/ /gu, '-'), resolveCfg(flags));
         // 版本闸门（失败降级放行）：blocked 拒绝执行，warning 告警，notice 仅退出提示。
         await enforceVersionGate(root, flags);
         switch (root) {
@@ -3054,19 +3093,69 @@ async function main() {
 /** S01：官方 CLI Skill 的离线安装与状态查询（指南随包内分发，不新增对话命令）。 */
 async function cmdAgentSkill(command, flags) {
     const sub = command[1];
-    const agent = pickString(flags, '--agent') ?? (pickString(flags, '--target') ? undefined : 'codex');
+    if (!['list', 'install', 'status'].includes(sub)) {
+        fail(`未知 agent-skill 子命令: ${sub ?? '(空)'}。可用: list / install / status（指南随 CLI 包内分发）`);
+    }
+    let agent = pickString(flags, '--agent');
     const explicitTarget = pickString(flags, '--target');
-    const targetRoot = explicitTarget
-        ? explicitTarget.replace(/^\$HOME(?=\/|$)/u, homedir())
+    // 即使指定了 --target，也拒绝未知的工具名，避免拼写错误被静默接受。
+    if (agent)
+        defaultTargetForAgent(agent);
+    let targetRoot = explicitTarget
+        ? path.resolve(explicitTarget.replace(/^(?:\$HOME|~)(?=\/|$)/u, homedir()))
         : agent ? defaultTargetForAgent(agent) : undefined;
+    const printStatus = (report) => {
+        const installed = report.installed;
+        if (!installed)
+            return;
+        log.info(`已安装：${installed.address}`);
+        log.info(`安装版本：${installed.cliVersion ?? '(手动安装，无元数据)'}${installed.upToDate ? '（与 CLI 一致，文件完整）' : '（需检查或重新安装）'}`);
+        if (installed.missingFiles.length)
+            log.warn(`缺失文件：${installed.missingFiles.join(', ')}`);
+        if (installed.outdatedFiles.length || installed.staleFiles.length)
+            log.warn('指南内容已过期，重新安装可更新。');
+        if (installed.modifiedFiles.length)
+            log.warn(`用户修改保留中：${installed.modifiedFiles.join(', ')}（覆盖需 --force）`);
+    };
+    if (sub === 'list' || (sub === 'status' && !targetRoot)) {
+        const targets = listSkillTargets();
+        if (flags['--json'] === true)
+            output({ targets }, flags);
+        else {
+            for (const target of targets) {
+                const selection = target.custom ? `--target ${target.targetRoot}` : `--agent ${target.agent}`;
+                log.info(`${target.name}（${selection}）：${target.targetRoot}；${target.detected ? '已发现目录' : '未发现目录'}；${target.installed ? (target.installed.upToDate ? '指南已更新' : '指南需检查') : '未安装指南'}`);
+                if (sub === 'status')
+                    printStatus(target);
+            }
+        }
+        return;
+    }
     if (sub === 'install') {
-        if (!targetRoot)
-            fail('用法: qmuse agent-skill install --agent codex [--target <dir>] [--force] [--json]');
+        if (!targetRoot) {
+            const detected = listSkillTargets().filter(target => target.detected);
+            if (detected.length === 0)
+                fail('未发现支持的工具目录。请执行 qmuse agent-skill list，再用 --agent <工具> 或 --target <skills 目录> 指定安装位置。');
+            let chosen = detected[0];
+            if (detected.length > 1) {
+                const choices = detected.map((target, index) => `${index + 1}. ${target.name}：${target.targetRoot}`).join('\n');
+                if (process.stdin.isTTY !== true || flags['--json'] === true) {
+                    fail(`发现多个工具目录，请用 --agent <工具> 或 --target <skills 目录> 选择当前工具：\n${choices}`);
+                }
+                const answer = Number(await prompt(`选择当前工具：\n${choices}\n请输入编号：`));
+                if (!Number.isInteger(answer) || answer < 1 || answer > detected.length)
+                    fail('无效编号，未安装指南。');
+                chosen = detected[answer - 1];
+            }
+            targetRoot = chosen.targetRoot;
+            agent = chosen.agent;
+        }
         const result = installAgentSkill({
             targetRoot,
             agent: agent ?? 'custom',
             force: flags['--force'] === true,
         });
+        rememberSkillTarget(targetRoot, agent ?? 'custom');
         // T01.11：安装事件（记录指南版本与目标助手类型，不记录本机私有路径）。
         recordEvent({ kind: 'cli.skill.event', stage: 'install', result: 'ok',
             agent: agent ?? 'custom', target: 'skill-content' });
@@ -3080,7 +3169,7 @@ async function cmdAgentSkill(command, flags) {
     }
     if (sub === 'status') {
         if (!targetRoot)
-            fail('用法: qmuse agent-skill status [--agent codex] [--target <dir>] [--json]');
+            fail('用法: qmuse agent-skill status [--agent <工具>] [--target <skills 目录>] [--json]');
         const report = skillStatus(targetRoot);
         // T01.11：状态查询事件。
         recordEvent({ kind: 'cli.skill.event', stage: 'status', result: report.installed ? 'ok' : 'not-installed' });
@@ -3090,17 +3179,11 @@ async function cmdAgentSkill(command, flags) {
         }
         log.info(`包内指南版本：${report.packagedVersion}（${report.packagedAvailable ? `${report.packagedFiles} 个文件` : '缺失，请重装 CLI'}）`);
         if (!report.installed)
-            log.warn('当前目标未安装官方指南；执行 qmuse agent-skill install --agent codex');
-        else {
-            log.info(`已安装：${report.installed.address}`);
-            log.info(`安装版本：${report.installed.cliVersion ?? '(早期安装，无元数据)'}${report.installed.matchesPackagedVersion ? '（与 CLI 一致）' : '（与当前 CLI 不一致，建议重新安装）'}`);
-            if (report.installed.modifiedFiles.length > 0) {
-                log.warn(`用户修改保留中：${report.installed.modifiedFiles.join(', ')}（覆盖需 --force）`);
-            }
-        }
+            log.warn('当前目标未安装官方指南；用相同的 --agent 或 --target 执行 qmuse agent-skill install。');
+        else
+            printStatus(report);
         return;
     }
-    fail(`未知 agent-skill 子命令: ${sub ?? '(空)'}。可用: install / status（指南随 CLI 包内分发）`);
 }
 /** 帮助/版本等无命令上下文路径的结束事件（T01.01 覆盖帮助与版本输出）。 */ function recordCommandEvent(label, exitCode, startedAt) {
     setTelemetryCommand(label);

package/dist/logger.js

@@ -13,10 +13,13 @@ const ICON = {
     error: '✗',
     dim: '·',
 };
+let structuredOutput = false;
+export function setStructuredOutput(enabled) {
+    structuredOutput = enabled;
+}
 function emit(level, msg) {
     const icon = COLORS[level](`${ICON[level]}`);
-    // eslint-disable-next-line no-console
-    console.log(`${icon} ${msg}`);
+    (structuredOutput ? process.stderr : process.stdout).write(`${icon} ${msg}\n`);
 }
 export const log = {
     info: (m) => emit('info', m),

package/dist/tracker.js

@@ -11,6 +11,8 @@
  *  - C 位：每个命令一个 click 事件
  */
 import { randomUUID } from 'node:crypto';
+import { hasAuth } from './client.js';
+const TRACKING_TIMEOUT_MS = 500;
 const COLLECT_URL = 'https://collect.alipay.com/dwcookie';
 const QMUSE_WEB_ORIGIN = 'https://www.qmuse.cn';
 const SPM_A = 'a5400'; // QMuse Web 的 SPM A 位（config/config.ts tracert.spmAPos）
@@ -71,31 +73,29 @@ const SPM_MAP = {
 };
 const CLIENT_ID = randomUUID();
 const BIZ_TYPE = 'qmuse';
-let cachedUserId = null;
-/** 从 CLI 会话获取 userId（fire-and-forget；拿不到用空串，采集平台会丢这条但主流程不受影响） */
-async function fetchUserId(cfg) {
-    if (cachedUserId !== null)
-        return cachedUserId;
+/** 身份查询与采集共享短预算，不占用业务请求的默认超时。 */
+async function fetchUserId(cfg, signal) {
     try {
         const { whoami } = await import('./api.js');
-        const r = await whoami(cfg);
-        cachedUserId = r.data?.userId?.trim() || '';
+        const r = await whoami(cfg, { signal, timeoutMs: TRACKING_TIMEOUT_MS });
+        return r.data?.userId?.trim() || '';
     }
     catch {
-        cachedUserId = '';
+        return '';
     }
-    return cachedUserId;
 }
 /** 发送 dwcookie 埋点（fire-and-forget，绝不抛出） */
-export function trackCommand(command, cfg) {
+export function trackCommand(command, cfg, knownUserId) {
     const spmC = SPM_MAP[command];
-    if (!spmC)
+    if (!spmC || !hasAuth(cfg))
         return;
     const spm = `${SPM_A}.${SPM_B}.${spmC}`;
     const sessionId = `${CLIENT_ID}_${Date.now()}`;
-    void fetchUserId(cfg)
-        .catch(() => '')
-        .then(userId => {
+    const signal = AbortSignal.timeout(TRACKING_TIMEOUT_MS);
+    void (async () => {
+        const userId = knownUserId?.trim() || await fetchUserId(cfg, signal);
+        if (!userId || signal.aborted)
+            return;
         const fields = [
             'DW-COOKIE',
             sessionId,
@@ -115,16 +115,17 @@ export function trackCommand(command, cfg) {
         fields[22] = '1';
         const data = fields.join(',');
         const body = `data=${encodeURIComponent(data)}`;
-        void fetch(COLLECT_URL, {
+        const response = await fetch(COLLECT_URL, {
             method: 'POST',
             headers: {
                 'content-type': 'application/x-www-form-urlencoded',
                 referer: `${QMUSE_WEB_ORIGIN}/`,
             },
             body,
-            signal: AbortSignal.timeout(5000),
-        }).catch(() => {
-            /* 采集失败不影响业务 */
+            signal,
         });
+        await response.body?.cancel();
+    })().catch(() => {
+        /* 埋点失败或超时不影响业务 */
     });
 }

package/dist/version-gate.js

@@ -65,15 +65,10 @@ export function gateLevel(current, 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';
@@ -82,12 +77,10 @@ export function gateLevel(current, snapshot) {
         return 'ok';
     }
 }
-/** 是否需要升级：预发布版本不判「落后」；缺少最新版本信息时返回 false（降级）。 */
+/** 按 semver 比较是否需要升级；缺少最新版本信息时返回 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);
     }
@@ -167,8 +160,8 @@ export function registryPolicyProvider(options = {}) {
     const url = options.url ?? policyRegistryUrl(distribution);
     const timeoutMs = options.timeoutMs ?? 2500;
     return async () => {
-        // 缓存优先：6 小时内不重复打 registry（每条命令一次请求代价过高）。
-        const cached = readPolicyCache(distribution);
+        // 普通命令复用一小时缓存，主动升级直接查询 registry。
+        const cached = options.refresh ? undefined : readPolicyCache(distribution);
         if (cached)
             return cached;
         const controller = new AbortController();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmuse/qmuse-cli",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "QMuse 命令行客户端：在本地创建/导入 React 项目、与 QMuse 对话、拉取发布与云端调试",
   "type": "module",
   "bin": {
@@ -45,7 +45,6 @@
     "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

@@ -1,30 +1,33 @@
 ---
 name: qmuse-cli
-description: QMuse CLI 官方研发指南：本地工程初始化、导入、应用绑定、远端对话、本地开发、源码同步、云数据与发布。当用户要求使用 QMuse CLI 创建/开发/导入/发布应用到 QMuse，或排查 qmuse 命令问题时使用。
+description: 通过 QMuse 创建、导入、修改、调试、同步或发布应用。用户要求使用 QMuse、操作 qmuse.cn 应用链接，或当前工程已有 QMuse 绑定（.qmuse/project.json 或 .qmuse/app.json）时使用，包括“用 QMuse 做一个应用”“继续修改这个作品”“把本地 React 项目导入 QMuse”及 qmuse 命令排障。普通项目、QMuse 平台或 CLI 自身源码维护沿用仓库研发流程。
 ---
 
 # QMuse CLI 官方指南
 
-总原则：先 `qmuse info --json` 判定上下文（登录态、环境、绑定、云架构），再选择下方分流入口；
-每个命令都可以 `qmuse help` 查看参数，`--json` 拿结构化输出。执行失败时：
-先读取命令输出中的诊断字段（`message`、`errorCode`、`diagnostics`、`.qmuse/last-import-error.json`），
-不要凭猜测重复执行可能创建新资源的操作（重复创建请求只恢复身份，不重跑首轮生成）。
+先识别任务：安装与状态查询在本地完成；操作应用时用 `qmuse info --json` 查看身份、空间和绑定，缺少登录再执行 `qmuse login`。已有应用沿用其 appId 和工程；用户给出应用链接时先读取链接中的 appId 并核对应用，避免另建应用。
+
+使用 `qmuse help` 查参数，`--json` 获取结构化结果。导入、对话和发布失败时，读取输出的诊断字段或 `.qmuse/last-import-error.json`；有 jobId、chatId、requestId 时先查原任务，恢复原操作。
 
 ## 工程与任务分流（先读这里）
 
 | 用户意图 | 入口 | 关键约束 |
 | --- | --- | --- |
-| 初始化一个新的本地工程 | `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）。
+| 初始化新的本地 React 工程 | `qmuse create <dir>` | 创建本地模板；开发后用 import 创建远端应用 |
+| 将本地 React 工程导入 QMuse | `qmuse import <dir>` | 首次导入创建应用，已有绑定则更新同一应用 |
+| 修改已导入的应用 | 修改源码后 `qmuse import .` | 平台基线变化先处理同步冲突，再更新 |
+| 用自然语言创建应用 | `qmuse app create <web\|h5\|ai> --file <路径\|->` | web 网页、h5 移动页面、ai AI 应用；返回 appId、chatId 等身份 |
+| 继续已有应用的对话 | `qmuse chat send --app-id <id> --chat-id <id> --file <路径\|->` | send 必须传 appId 和 chatId；缺少会话时先查询历史 |
+| 回答等待输入的对话 | `qmuse chat resume <chatId> --app-id <id> --interrupt-id <id> --file <回答.json>` | interruptId 来自 chat state 或事件，沿用原会话 |
+| 连接真实云资源本地开发 | `qmuse dev [dir]` | 云绑定应用；用 dev status / stop 管理会话 |
+| 拉取平台最新已保存源码 | `qmuse pull [dir]` | 本地源码偏离同步基线时停止；成功更新前备份原源码和绑定，再应用远端源码 |
+| 单独导出源码 | `qmuse code export --app-id <id> --output <dir>` | 导出最新已保存版；上传使用 import |
+| 发布指定版本 | `qmuse deploy --version <id>`、`qmuse release status <releaseId>` | 按用户要求发布；受理后可用 --no-wait 退出，再查结果 |
+
+首次使用身份、导入、对话、同步和发布命令时，按需阅读 [核心流程](references/core-flows.md)；涉及数据库、云函数、配置或密钥时阅读 [云服务指南](references/cloud.md)。
+
+## 技能安装与升级
+
+本指南随 CLI 包离线分发。用 `qmuse agent-skill list` 查看 Codex、Claude Code、Cursor、Trae、CodeBuddy、Qoder 和 Qwen Code 的目录；`qmuse agent-skill install --agent <工具>` 安装到当前工具。自定义安装用 `--target <skills 父目录>`，CLI 自动追加 `qmuse-cli`。
+
+`qmuse upgrade` 更新 CLI 后会同步已安装的默认目录和已登记的自定义目录，保留用户修改。`qmuse agent-skill status --agent <工具> --json` 中 `installed.upToDate` 同时核对版本与文件内容；缺失文件可重新安装修复。更新后重新读取 SKILL.md，必要时刷新工具的技能列表或开启新会话。

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

@@ -1,4 +1,4 @@
-# 云服务指南（S01.11：匹配现有云服务）
+# 云服务指南
 
 CLI 不复制云规则，只做两件事：识别当前应用的实际架构，然后把操作路由到现有权威入口。
 
@@ -21,9 +21,9 @@ qmuse cloud status --app-id <appId> --json   # effectiveMode、activationStatus
 | 状态/失败原因 | `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` |
+| 数据库/表结构与用量 | `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. 约束
 

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

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