@qmuse/qmuse-cli 1.0.0-dev.0

package/dist/import/preflight.js

@@ -0,0 +1,246 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import ignore from 'ignore';
+const IGNORED_DIRECTORIES = new Set([
+    '.git', '.agents', '.local', '.qmuse', 'node_modules', 'dist', 'build', '.vite', '.turbo',
+]);
+const IGNORED_ROOT_FILES = new Set(['AGENTS.md']);
+const LOCAL_CONTROL_FILES = new Set(['.qmuse-cli.json']);
+const SENSITIVE_FILE_NAMES = new Set([
+    '.netrc', '.npmrc', '.pnpmrc', '.pypirc', '.yarnrc', '.yarnrc.yml',
+    'credentials.json', 'id_ed25519', 'id_rsa', 'service-account.json',
+]);
+const SENSITIVE_DIRECTORIES = new Set(['.aws', '.azure', '.gnupg', '.ssh']);
+const SENSITIVE_EXTENSIONS = new Set(['.jks', '.key', '.keystore', '.p12', '.pem', '.pfx']);
+const MAX_FILE_COUNT = 20_000;
+const MAX_FILE_BYTES = 100 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 500 * 1024 * 1024;
+const MAX_INSPECT_TEXT_BYTES = 2 * 1024 * 1024;
+const TEXT_EXTENSIONS = new Set([
+    '.css', '.cjs', '.html', '.js', '.jsx', '.json', '.less', '.md', '.mjs',
+    '.mts', '.scss', '.sass', '.ts', '.tsx', '.txt', '.yaml', '.yml',
+]);
+const ASSET_MIME_TYPES = {
+    '.avif': 'image/avif',
+    '.eot': 'application/vnd.ms-fontobject',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.ogg': 'audio/ogg',
+    '.otf': 'font/otf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.ttf': 'font/ttf',
+    '.wav': 'audio/wav',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+const ENV_PATTERNS = [
+    /import\.meta\.env\.([A-Z][A-Z0-9_]*)/gu,
+    /import\.meta\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/gu,
+    /process\.env\.([A-Z][A-Z0-9_]*)/gu,
+    /process\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/gu,
+];
+const PUBLIC_ENV_KEY = /^(?:VITE_|REACT_APP_)[A-Z0-9_]+$/u;
+const UNSUPPORTED_PRIVATE_RUNTIME = '@alipay/weavefox-vibe-web';
+const CLOUD_PROVIDER_PATTERNS = [
+    ['supabase', /from\s+['"]@supabase\/supabase-js['"]/u],
+    ['firebase', /from\s+['"]firebase(?:\/[^'"]+)?['"]/u],
+    ['appwrite', /from\s+['"](?:node-)?appwrite['"]/u],
+    ['pocketbase', /from\s+['"]pocketbase['"]/u],
+];
+const RUNTIME_SOURCE_EXTENSIONS = new Set([
+    '.cjs', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx',
+]);
+const SECRET_CONTENT_PATTERNS = [
+    /-----BEGIN (?:EC |OPENSSH |RSA )?PRIVATE KEY-----/u,
+    /(?:^|\n)\s*(?:AWS_SECRET_ACCESS_KEY|_authToken)\s*=/u,
+    /["']private_key["']\s*:\s*["']-----BEGIN PRIVATE KEY/u,
+];
+function rejectUnsupportedPrivateRuntime() {
+    throw new Error(`暂不支持依赖 ${UNSUPPORTED_PRIVATE_RUNTIME} 的项目：QMuse 隔离构建环境无法安装该内网包`);
+}
+function isDotEnv(name) {
+    return name === '.env' || name.startsWith('.env.');
+}
+function normalizeRelativePath(value) {
+    const normalized = value.replace(/\\/gu, '/');
+    if (!normalized ||
+        normalized.startsWith('/') ||
+        normalized === '..' ||
+        normalized.startsWith('../') ||
+        normalized.includes('/../') ||
+        normalized.includes('\0')) {
+        throw new Error(`源码包含不安全路径：${value}`);
+    }
+    return normalized;
+}
+async function collectFiles(rootDir) {
+    const rootStat = await lstat(rootDir).catch(() => undefined);
+    if (!rootStat?.isDirectory()) {
+        throw new Error(`目录不存在或不可读：${rootDir}`);
+    }
+    if (rootStat.isSymbolicLink()) {
+        throw new Error('导入目录不能是符号链接');
+    }
+    const files = [];
+    let totalBytes = 0;
+    const rootIgnore = ignore();
+    const gitIgnorePath = path.join(rootDir, '.gitignore');
+    try {
+        rootIgnore.add(await readFile(gitIgnorePath, 'utf8'));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT')
+            throw error;
+    }
+    async function visit(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of entries) {
+            if (directory === rootDir && IGNORED_ROOT_FILES.has(entry.name))
+                continue;
+            if (LOCAL_CONTROL_FILES.has(entry.name))
+                continue;
+            if (entry.name === '.DS_Store' ||
+                entry.name.endsWith('.log') ||
+                entry.name.endsWith('.tsbuildinfo'))
+                continue;
+            if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            if (isDotEnv(entry.name))
+                continue;
+            const absolutePath = path.join(directory, entry.name);
+            const stat = await lstat(absolutePath);
+            const relativePath = normalizeRelativePath(path.relative(rootDir, absolutePath));
+            const ignorePath = stat.isDirectory() ? `${relativePath}/` : relativePath;
+            if (rootIgnore.ignores(ignorePath))
+                continue;
+            if (stat.isSymbolicLink()) {
+                throw new Error(`不支持符号链接：${relativePath}`);
+            }
+            if (stat.isDirectory()) {
+                if (SENSITIVE_DIRECTORIES.has(entry.name)) {
+                    throw new Error(`源码包含敏感凭证目录，拒绝上传：${relativePath}`);
+                }
+                await visit(absolutePath);
+                continue;
+            }
+            if (!stat.isFile()) {
+                throw new Error(`不支持的文件类型：${relativePath}`);
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                throw new Error(`单文件超过 100MB：${relativePath}`);
+            }
+            if (SENSITIVE_FILE_NAMES.has(entry.name) ||
+                SENSITIVE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+                throw new Error(`源码包含敏感凭证文件，拒绝上传：${relativePath}`);
+            }
+            if (stat.size <= MAX_INSPECT_TEXT_BYTES) {
+                const content = await readFile(absolutePath, 'utf8');
+                if (SECRET_CONTENT_PATTERNS.some(pattern => pattern.test(content))) {
+                    throw new Error(`源码疑似包含明文凭证，拒绝上传：${relativePath}`);
+                }
+            }
+            files.push({
+                absolutePath,
+                relativePath,
+                sizeBytes: stat.size,
+                sha256: await sha256File(absolutePath),
+            });
+            totalBytes += stat.size;
+            if (files.length > MAX_FILE_COUNT) {
+                throw new Error(`源码文件数超过 ${MAX_FILE_COUNT}`);
+            }
+            if (totalBytes > MAX_TOTAL_BYTES) {
+                throw new Error('源码未压缩大小超过 500MB');
+            }
+        }
+    }
+    await visit(rootDir);
+    return files;
+}
+async function updateHashFromFile(hash, filePath) {
+    for await (const chunk of createReadStream(filePath))
+        hash.update(chunk);
+}
+async function sha256File(filePath) {
+    const hash = createHash('sha256');
+    await updateHashFromFile(hash, filePath);
+    return hash.digest('hex');
+}
+export async function preflightImport(directory) {
+    const rootDir = path.resolve(directory);
+    const files = await collectFiles(rootDir);
+    const packageFile = files.find(file => file.relativePath === 'package.json');
+    if (!packageFile)
+        throw new Error('一期仅支持包含 package.json 的 React 项目');
+    let packageJson;
+    try {
+        packageJson = JSON.parse(await readFile(packageFile.absolutePath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`package.json 无效：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const dependencies = { ...packageJson.devDependencies, ...packageJson.dependencies };
+    if (!dependencies.react)
+        throw new Error('一期仅支持 React 项目');
+    if (dependencies[UNSUPPORTED_PRIVATE_RUNTIME])
+        rejectUnsupportedPrivateRuntime();
+    const sourceHash = createHash('sha256');
+    const envKeys = new Set();
+    const cloudProviders = new Set();
+    for (const file of files) {
+        sourceHash.update(file.relativePath);
+        sourceHash.update('\0');
+        await updateHashFromFile(sourceHash, file.absolutePath);
+        sourceHash.update('\0');
+        if (TEXT_EXTENSIONS.has(path.extname(file.relativePath).toLowerCase()) &&
+            file.sizeBytes <= MAX_INSPECT_TEXT_BYTES) {
+            const content = await readFile(file.absolutePath, 'utf8');
+            if (content.includes(`'${UNSUPPORTED_PRIVATE_RUNTIME}'`) ||
+                content.includes(`"${UNSUPPORTED_PRIVATE_RUNTIME}"`)) {
+                rejectUnsupportedPrivateRuntime();
+            }
+            for (const pattern of ENV_PATTERNS) {
+                pattern.lastIndex = 0;
+                for (const match of content.matchAll(pattern)) {
+                    if (match[1] && PUBLIC_ENV_KEY.test(match[1]))
+                        envKeys.add(match[1]);
+                }
+            }
+            if (!file.relativePath.endsWith('.d.ts') &&
+                RUNTIME_SOURCE_EXTENSIONS.has(path.extname(file.relativePath).toLowerCase())) {
+                for (const [provider, pattern] of CLOUD_PROVIDER_PATTERNS) {
+                    if (pattern.test(content))
+                        cloudProviders.add(provider);
+                }
+            }
+        }
+    }
+    const assets = files.flatMap(file => {
+        const mimeType = ASSET_MIME_TYPES[path.extname(file.relativePath).toLowerCase()];
+        return mimeType
+            ? [{ sourcePath: file.relativePath, mimeType, sizeBytes: file.sizeBytes }]
+            : [];
+    });
+    return {
+        rootDir,
+        title: packageJson.name?.trim() || path.basename(rootDir),
+        sourceHash: sourceHash.digest('hex'),
+        fileCount: files.length,
+        totalBytes: files.reduce((sum, file) => sum + file.sizeBytes, 0),
+        envKeys: [...envKeys].sort(),
+        cloudProviders: [...cloudProviders].sort(),
+        assets,
+        files,
+    };
+}

package/dist/import/project.js

@@ -0,0 +1,189 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export const QMUSE_PROJECT_PATH = '.qmuse/project.json';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 ${field} 必须是非空字符串`);
+    }
+    return value;
+}
+function normalizeApiBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${QMUSE_PROJECT_PATH} 包含无效 apiBaseUrl：${value}`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 apiBaseUrl 必须使用 HTTP(S)`);
+    }
+    url.hash = '';
+    url.search = '';
+    url.pathname = url.pathname.replace(/\/+$/u, '') || '/';
+    return url.toString().replace(/\/$/u, '');
+}
+function parseTarget(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 ${field} 无效`);
+    return {
+        apiBaseUrl: normalizeApiBaseUrl(requireNonEmptyString(value.apiBaseUrl, `${field}.apiBaseUrl`)),
+        appId: requireNonEmptyString(value.appId, `${field}.appId`),
+        spaceId: requireNonEmptyString(value.spaceId, `${field}.spaceId`),
+        lastVersionId: requireNonEmptyString(value.lastVersionId, `${field}.lastVersionId`),
+        lastSourceHash: requireNonEmptyString(value.lastSourceHash, `${field}.lastSourceHash`),
+        updatedAt: requireNonEmptyString(value.updatedAt, `${field}.updatedAt`),
+    };
+}
+function parsePendingImport(value, field) {
+    if (!isRecord(value))
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 ${field} 无效`);
+    const operation = requireNonEmptyString(value.operation, `${field}.operation`);
+    if (operation !== 'CREATE' && operation !== 'UPDATE') {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 ${field}.operation 无效`);
+    }
+    return {
+        apiBaseUrl: normalizeApiBaseUrl(requireNonEmptyString(value.apiBaseUrl, `${field}.apiBaseUrl`)),
+        jobId: requireNonEmptyString(value.jobId, `${field}.jobId`),
+        operation,
+        sourceHash: requireNonEmptyString(value.sourceHash, `${field}.sourceHash`),
+        spaceId: requireNonEmptyString(value.spaceId, `${field}.spaceId`),
+        createdAt: requireNonEmptyString(value.createdAt, `${field}.createdAt`),
+    };
+}
+function parseEnvironmentMap(value, field, parse) {
+    if (!isRecord(value))
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 ${field} 必须是对象`);
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (!['prod', 'pre', 'local'].includes(key)) {
+            throw new Error(`${QMUSE_PROJECT_PATH} 的 ${field}.${key} 不是受支持的环境`);
+        }
+        result[key] = parse(item, `${field}.${key}`);
+    }
+    return result;
+}
+function parseManifest(value) {
+    if (!isRecord(value))
+        throw new Error(`${QMUSE_PROJECT_PATH} 必须是 JSON 对象`);
+    if (value.schemaVersion !== 1) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 schemaVersion 不受支持`);
+    }
+    if (value.projectKind !== 'QMUSE_TEMPLATE') {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 projectKind 必须是 QMUSE_TEMPLATE`);
+    }
+    if (value.appType !== 'GENERAL') {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 appType 必须是 GENERAL`);
+    }
+    if (!Number.isSafeInteger(value.packageVersion) || Number(value.packageVersion) < 1) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 packageVersion 无效`);
+    }
+    if (!isRecord(value.skillVersions)) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 skillVersions 必须是对象`);
+    }
+    const skillVersions = {};
+    for (const [name, version] of Object.entries(value.skillVersions)) {
+        skillVersions[requireNonEmptyString(name, 'skillVersions key')] = requireNonEmptyString(version, `skillVersions.${name}`);
+    }
+    const defaultSpaceId = value.defaultSpaceId === undefined
+        ? undefined
+        : requireNonEmptyString(value.defaultSpaceId, 'defaultSpaceId');
+    return {
+        schemaVersion: 1,
+        packageVersion: Number(value.packageVersion),
+        projectKind: 'QMUSE_TEMPLATE',
+        appType: 'GENERAL',
+        templateCommit: requireNonEmptyString(value.templateCommit, 'templateCommit'),
+        skillVersions,
+        ...(defaultSpaceId ? { defaultSpaceId } : {}),
+        targets: parseEnvironmentMap(value.targets, 'targets', parseTarget),
+        ...(value.pendingImports === undefined
+            ? {}
+            : { pendingImports: parseEnvironmentMap(value.pendingImports, 'pendingImports', parsePendingImport) }),
+    };
+}
+export function resolveProjectEnvironment(cfg, explicitEnvironment) {
+    if (explicitEnvironment)
+        return explicitEnvironment;
+    const apiBaseUrl = normalizeApiBaseUrl(cfg.baseUrl);
+    if (apiBaseUrl === 'https://api.qmuse.cn')
+        return 'prod';
+    if (apiBaseUrl === 'https://api-pre.qmuse.cn')
+        return 'pre';
+    if (apiBaseUrl === 'http://127.0.0.1:7001' || apiBaseUrl === 'http://local.dev.alipay.net:7001') {
+        return 'local';
+    }
+    throw new Error('受管 QMuse 项目使用自定义 API 地址时必须显式指定 --env prod|pre|local');
+}
+export async function loadManagedProject(rootDir, cfg, explicitEnvironment) {
+    const manifestPath = path.join(rootDir, QMUSE_PROJECT_PATH);
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 不是有效 JSON：${error instanceof Error ? error.message : String(error)}`);
+    }
+    const manifest = parseManifest(json);
+    const environment = resolveProjectEnvironment(cfg, explicitEnvironment);
+    const target = manifest.targets[environment];
+    const pending = manifest.pendingImports?.[environment];
+    const expectedApiBaseUrl = normalizeApiBaseUrl(cfg.baseUrl);
+    for (const binding of [target, pending]) {
+        if (binding && normalizeApiBaseUrl(binding.apiBaseUrl) !== expectedApiBaseUrl) {
+            throw new Error(`${QMUSE_PROJECT_PATH} 的 ${environment} 绑定与当前 API 地址不一致`);
+        }
+    }
+    return { manifestPath, manifest, environment, target };
+}
+export async function saveManagedProject(context) {
+    const temporaryPath = `${context.manifestPath}.${process.pid}.${randomUUID()}.tmp`;
+    const content = `${JSON.stringify(context.manifest, null, 2)}\n`;
+    try {
+        await writeFile(temporaryPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await rename(temporaryPath, context.manifestPath);
+    }
+    catch (error) {
+        const { rm } = await import('node:fs/promises');
+        await rm(temporaryPath, { force: true });
+        throw error;
+    }
+}
+export function setPendingImport(context, pending) {
+    context.manifest.pendingImports = {
+        ...context.manifest.pendingImports,
+        [context.environment]: pending,
+    };
+}
+export function clearPendingImport(context, jobId) {
+    if (context.manifest.pendingImports?.[context.environment]?.jobId !== jobId)
+        return;
+    const pendingImports = { ...context.manifest.pendingImports };
+    delete pendingImports[context.environment];
+    context.manifest.pendingImports = Object.keys(pendingImports).length ? pendingImports : undefined;
+}
+export function completeManagedImport(context, input) {
+    context.manifest.targets[context.environment] = {
+        apiBaseUrl: normalizeApiBaseUrl(input.apiBaseUrl),
+        appId: input.appId,
+        spaceId: input.spaceId,
+        lastVersionId: input.versionId,
+        lastSourceHash: input.sourceHash,
+        updatedAt: new Date().toISOString(),
+    };
+    context.target = context.manifest.targets[context.environment];
+    clearPendingImport(context, input.jobId);
+}

package/dist/import/source-manifest.js

@@ -0,0 +1,15 @@
+export const SOURCE_MANIFEST_PATH = '.local/qmuse-import/source-manifest-v1.json';
+export function createSourceManifest(preflight) {
+    return {
+        version: 1,
+        algorithm: 'sha256-path-content-v1',
+        sourceHash: preflight.sourceHash,
+        fileCount: preflight.fileCount,
+        totalBytes: preflight.totalBytes,
+        files: preflight.files.map(file => ({
+            path: file.relativePath,
+            sizeBytes: file.sizeBytes,
+            sha256: file.sha256,
+        })),
+    };
+}

package/dist/logger.js

@@ -0,0 +1,28 @@
+/** 轻量终端日志器，避免引入额外依赖。 */
+const COLORS = {
+    info: s => `\x1b[36m${s}\x1b[0m`,
+    success: s => `\x1b[32m${s}\x1b[0m`,
+    warn: s => `\x1b[33m${s}\x1b[0m`,
+    error: s => `\x1b[31m${s}\x1b[0m`,
+    dim: s => `\x1b[2m${s}\x1b[0m`,
+};
+const ICON = {
+    info: '›',
+    success: '✓',
+    warn: '!',
+    error: '✗',
+    dim: '·',
+};
+function emit(level, msg) {
+    const icon = COLORS[level](`${ICON[level]}`);
+    // eslint-disable-next-line no-console
+    console.log(`${icon} ${msg}`);
+}
+export const log = {
+    info: (m) => emit('info', m),
+    success: (m) => emit('success', m),
+    warn: (m) => emit('warn', m),
+    error: (m) => emit('error', m),
+    dim: (m) => emit('dim', m),
+    raw: (m) => process.stdout.write(m),
+};

package/dist/login.js

@@ -0,0 +1,178 @@
+/**
+ * QMuse 网页确认登录：服务端创建短期请求，浏览器确认后由 CLI 轮询换取会话。
+ */
+import { execFile } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import * as api from './api.js';
+import { buildUrl } from './client.js';
+import { apiOrigin, loadConfig, saveConfig } from './config.js';
+import { log } from './logger.js';
+const SESSION_EXCHANGE_POLL_INTERVAL_MS = 2_000;
+const SESSION_EXCHANGE_POLL_TIMEOUT_MS = 120_000;
+const SESSION_EXCHANGE_TOKEN_PATTERN = /^muse_session_exchange_[A-Za-z0-9_-]{43}$/;
+const SESSION_EXCHANGE_PENDING_CODES = new Set(['SESSION_EXCHANGE_PENDING']);
+let rl = null;
+const pendingLines = [];
+let lineWaiter = null;
+function ensureRl() {
+    if (rl)
+        return;
+    rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: process.stdin.isTTY === true,
+    });
+    rl.on('line', (line) => {
+        if (lineWaiter) {
+            const waiter = lineWaiter;
+            lineWaiter = null;
+            waiter(line);
+        }
+        else {
+            pendingLines.push(line);
+        }
+    });
+}
+export function prompt(question) {
+    ensureRl();
+    process.stdout.write(question);
+    return new Promise(resolve => {
+        if (pendingLines.length > 0) {
+            resolve(pendingLines.shift());
+        }
+        else {
+            lineWaiter = resolve;
+        }
+    }).then(answer => answer.trim());
+}
+export function closePrompt() {
+    if (rl) {
+        rl.close();
+        rl = null;
+    }
+}
+export function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : 'xdg-open';
+    return new Promise(resolve => {
+        execFile(command, [url], error => resolve(!error));
+    });
+}
+export function persistSession(sessionId, targetConfig = loadConfig()) {
+    const origin = apiOrigin(targetConfig.baseUrl);
+    if (!origin)
+        throw new Error('登录目标不是有效的 HTTP(S) 地址');
+    const config = {
+        ...loadConfig(),
+        baseUrl: targetConfig.baseUrl,
+        apiPrefix: targetConfig.apiPrefix,
+        webBaseUrl: targetConfig.webBaseUrl,
+        sessionId,
+        credentialOrigin: origin,
+    };
+    const path = saveConfig(config, true);
+    log.success(`登录态已保存到 ${path}`);
+    return path;
+}
+export async function loginBrowser(cfg, options = {}, dependencyOverrides) {
+    const dependencies = {
+        createRequest: api.createSessionExchangeRequest,
+        open: openBrowser,
+        consume: api.consumeSessionExchangeToken,
+        verify: api.exchangeSessionCookie,
+        persist: persistSession,
+        now: Date.now,
+        wait: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+        ...dependencyOverrides,
+    };
+    log.info('正在创建 QMuse CLI 登录请求...');
+    if (options.logRequestDetails) {
+        log.dim(`登录请求接口：${buildUrl(cfg, '/api/login/session-exchange/request')}`);
+    }
+    const request = await dependencies.createRequest({ cfg });
+    const token = request.data?.token;
+    const expiresInSeconds = request.data?.expiresInSeconds;
+    if (!request.ok ||
+        !token ||
+        !SESSION_EXCHANGE_TOKEN_PATTERN.test(token) ||
+        typeof expiresInSeconds !== 'number' ||
+        !Number.isFinite(expiresInSeconds) ||
+        expiresInSeconds <= 0) {
+        return {
+            success: false,
+            method: 'browser',
+            message: `创建登录请求失败：${request.errorMessage ?? request.errorCode ?? `HTTP ${request.status}`}`,
+        };
+    }
+    const authUrl = new URL('/cli-auth', cfg.webBaseUrl);
+    authUrl.searchParams.set('request', token);
+    if (options.logRequestDetails) {
+        log.warn('以下调试信息包含短期有效的一次性登录凭证，请勿分享');
+        log.dim(`登录页面：${authUrl.toString()}`);
+        log.dim(`request token：${token}`);
+    }
+    log.info('正在打开 QMuse 登录页面...');
+    log.info(`确认码：${token.slice(-6).toUpperCase()}`);
+    if (!await dependencies.open(authUrl.toString())) {
+        return {
+            success: false,
+            method: 'browser',
+            message: '无法打开 QMuse 登录页面，请检查系统默认浏览器配置后重试',
+        };
+    }
+    log.info('等待网页确认登录...');
+    const deadline = dependencies.now() + Math.min(SESSION_EXCHANGE_POLL_TIMEOUT_MS, expiresInSeconds * 1000);
+    while (dependencies.now() < deadline) {
+        const exchanged = await dependencies.consume(token, { cfg });
+        const sessionId = exchanged.data?.sessionId;
+        if (exchanged.ok && sessionId) {
+            const verified = await dependencies.verify(sessionId, { cfg });
+            if (!verified.ok || !verified.data?.sessionId) {
+                return {
+                    success: false,
+                    method: 'browser',
+                    message: `登录态校验失败：${verified.errorMessage ?? verified.errorCode ?? `HTTP ${verified.status}`}`,
+                };
+            }
+            dependencies.persist(verified.data.sessionId, cfg);
+            return { success: true, sessionId: verified.data.sessionId, method: 'browser' };
+        }
+        if (!SESSION_EXCHANGE_PENDING_CODES.has(exchanged.errorCode || '')) {
+            return {
+                success: false,
+                method: 'browser',
+                message: `同步登录态失败：${exchanged.errorMessage ?? exchanged.errorCode ?? `HTTP ${exchanged.status}`}`,
+            };
+        }
+        const remaining = deadline - dependencies.now();
+        if (remaining > 0) {
+            await dependencies.wait(Math.min(SESSION_EXCHANGE_POLL_INTERVAL_MS, remaining));
+        }
+    }
+    return {
+        success: false,
+        method: 'browser',
+        message: '等待网页确认超时，请重新执行 qmuse login',
+    };
+}
+export async function loginStatus(cfg) {
+    if (!(cfg.sessionId || '').trim() || cfg.credentialOrigin !== apiOrigin(cfg.baseUrl)) {
+        return { success: false, method: 'browser', message: '当前环境未登录，请先执行 qmuse login' };
+    }
+    const result = await api.exchangeSessionCookie(cfg.sessionId, { cfg });
+    if (!result.ok || !result.data?.sessionId) {
+        return {
+            success: false,
+            method: 'browser',
+            message: `会话无效或已过期：${result.errorMessage ?? result.errorCode ?? `HTTP ${result.status}`}`,
+        };
+    }
+    if (result.data.sessionId !== cfg.sessionId) {
+        persistSession(result.data.sessionId, cfg);
+    }
+    return {
+        success: true,
+        sessionId: result.data.sessionId,
+        method: 'browser',
+        message: '会话有效（已续期）',
+    };
+}

package/dist/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from 'node:module';
+const packageMetadata = createRequire(import.meta.url)('../package.json');
+export const QMUSE_CLI_NAME = 'qmuse-cli';
+export const QMUSE_CLI_VERSION = typeof packageMetadata.version === 'string' && packageMetadata.version.trim()
+    ? packageMetadata.version.trim()
+    : 'unknown';
+export const QMUSE_CLI_DISTRIBUTION = typeof packageMetadata.name === 'string' && packageMetadata.name.startsWith('@qmuse/')
+    ? 'PUBLIC'
+    : 'INTERNAL';