@lark-apaas/miaoda-cli 0.1.24-alpha.c761e99 → 0.1.24-alpha.cb67974

package/dist/api/app/api.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAppInfo = getAppInfo;
 exports.updateAppMeta = updateAppMeta;
+exports.getCodeArchive = getCodeArchive;
 const http_1 = require("../../utils/http");
 const devops_error_1 = require("../../utils/devops-error");
 const DEFAULT_ERR_CODE = 'INTERNAL_DEVOPS_ERROR';
@@ -23,3 +24,22 @@ async function updateAppMeta(req) {
     // 路径已带 appID，body 里也保留以匹配 BAM IDL 的 sensitive:"no" 透传约定
     return (0, http_1.postInnerApi)(url, req, envelopeOpts('Failed to update app'));
 }
+/**
+ * GET /api/v1/studio/innerapi/apps/:appID/code-archive?sourceAppID=xxx — 导出源应用源码归档。
+ * 走 studio_server inner 通道（force 身份，服务侧 force→lark 换取后按 DOWNLOAD 鉴权，
+ * 鉴权对象是 sourceAppID），与 comment 域同一 inner 信封；创意应用升级链路（app export）消费。
+ *
+ * path :appID 必须是当前沙箱应用：网关 apaas_force_admin_plugin 强校验 URL appID 与沙箱
+ * AK 绑定应用一致（不一致 400 "appID in url is illegal"），跨应用导出目标因此走 query。
+ */
+async function getCodeArchive(params) {
+    const { appID, sourceAppID, checkpointID } = params;
+    let url = `/api/v1/studio/innerapi/apps/${encodeURIComponent(appID)}/code-archive` +
+        `?sourceAppID=${encodeURIComponent(sourceAppID)}`;
+    if (checkpointID !== undefined && checkpointID > 0) {
+        url += `&checkPointID=${String(checkpointID)}`;
+    }
+    return (0, http_1.getInnerApi)(url, {
+        errPrefix: 'Failed to export code archive',
+    });
+}

package/dist/api/app/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArchType = exports.Source = exports.BizType = exports.AppType = exports.AppMode = exports.AppStatus = exports.appMetaSchema = exports.updateAppMeta = exports.getAppInfo = void 0;
+exports.ArchType = exports.Source = exports.BizType = exports.AppType = exports.AppMode = exports.AppStatus = exports.appMetaSchema = exports.getCodeArchive = exports.updateAppMeta = exports.getAppInfo = void 0;
 var api_1 = require("./api");
 Object.defineProperty(exports, "getAppInfo", { enumerable: true, get: function () { return api_1.getAppInfo; } });
 Object.defineProperty(exports, "updateAppMeta", { enumerable: true, get: function () { return api_1.updateAppMeta; } });
+Object.defineProperty(exports, "getCodeArchive", { enumerable: true, get: function () { return api_1.getCodeArchive; } });
 var schemas_1 = require("./schemas");
 Object.defineProperty(exports, "appMetaSchema", { enumerable: true, get: function () { return schemas_1.appMetaSchema; } });
 var types_1 = require("./types");

package/dist/cli/commands/app/index.js

@@ -21,6 +21,7 @@ function registerAppCommands(program, opts = {}) {
 `);
     registerAppGet(appCmd);
     registerAppUpdate(appCmd);
+    registerAppExport(appCmd);
     if (opts.includeInit) {
         registerAppInit(appCmd);
         registerAppSync(appCmd);
@@ -119,6 +120,54 @@ JSON 输出
         });
     }));
 }
+function registerAppExport(parent) {
+    const cmd = parent
+        .command('export <app-id>')
+        .description('导出指定应用的源码到本工程（创意应用升级：拉取创意稿作只读参考物）')
+        .option('--out <dir>', '输出目录（相对当前目录）', 'source_package/creative')
+        .option('--checkpoint <n>', '按检查点版本导出；缺省为最新提交（HEAD）')
+        .addHelpText('after', `
+说明
+  从服务端导出 <app-id> 对应应用（源应用，可以不是当前应用）的源码归档并解压到 --out
+  目录，导出完成后写 --out/.upgrade-manifest.json（含 sourceAppId / 导出时间 / 文件数），
+  供升级链路幂等判定与 skill 发现使用。调用者须为源应用协作者（服务端 DOWNLOAD 鉴权）。
+  请求以当前应用（MIAODA_APP_ID）为路径主体、源应用走 sourceAppID 参数。
+
+幂等
+  --out 已存在 manifest 且 sourceAppId 一致时跳过导出（skipped=true），重复调用安全。
+
+JSON 输出
+  {"data": {"appId": "...", "out": "source_package/creative", "fileCount": <n>,
+            "archiveName": "...", "skipped": false}}
+  跳过时：{"data": {"appId": "...", "out": "...", "skipped": true, "reason": "already_exported"}}
+
+失败
+  源应用无可导出内容（从未提交过代码）→ EXPORT_EMPTY_ARCHIVE，请先在源应用完成一轮创作。
+  无权限（非源应用协作者）→ 服务端鉴权错误透传。
+
+示例
+  $ miaoda app export app_demo_source
+  $ miaoda app export app_demo_source --out source_package/creative
+  $ miaoda app export app_demo_source --checkpoint 3
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (appId, rawOpts) => {
+        const checkpointRaw = rawOpts.checkpoint;
+        let checkpoint;
+        if (checkpointRaw !== undefined) {
+            checkpoint = Number(checkpointRaw);
+            if (!Number.isInteger(checkpoint) || checkpoint <= 0) {
+                (0, shared_1.failArgs)(`--checkpoint 须为正整数：${checkpointRaw}`);
+            }
+        }
+        await (0, index_1.handleAppExport)({
+            appId,
+            // path :appID 必须是当前沙箱应用（网关 AK 校验），从 MIAODA_APP_ID/app_id 解析
+            currentAppId: (0, shared_1.resolveAppId)({}),
+            out: rawOpts.out,
+            checkpoint,
+        });
+    }));
+}
 function registerAppGet(parent) {
     const cmd = parent
         .command('get')

package/dist/cli/commands/skills/index.js

@@ -21,11 +21,15 @@ function registerSkillsCommands(program) {
 function registerSkillsSync(parent) {
     const cmd = parent
         .command('sync')
-        .description('同步 coding-steering（latest 或指定版本）到 user app')
+        .description('同步 skills 到 user app（默认 coding-steering；带 --type 时走 sandbox-skills）')
         .option('--dir <path>', '项目目录，默认当前目录', '.')
         .option('--version <ver>', 'coding-steering 包版本或 dist-tag，缺省 latest')
         .option('--local', '走本地 dev / agent 输出形态：拷到 .agents/skills 平铺 + 创建 .claude/skills 软链。' +
         '不传时退回老形态：拷到 .agent/skills/steering/<stack>/skills/（跟沙箱端 update-skills.sh 对齐）', false)
+        .option('--type <type>', '走 sandbox-skills 分支：miaoda | miaoda-modern | miaoda-design | openclaw。' +
+        '有值时忽略 --version/--local，改从 @lark-apaas/coding-<pkg>-sandbox 拉对应包写入 .agent/skills/')
+        .option('--tgz-key <key>', '配合 --type 使用；老 TCC skillsUpdateTgzKey 值透传，' +
+        '从 skills_versions/all_<X>.tgz 反推出 dist-tag lane-<X>；缺省走 @latest')
         .addHelpText('after', `
 前置要求
   当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack）
@@ -56,6 +60,8 @@ JSON 输出
             dir: rawOpts.dir,
             version: rawOpts.version,
             local: rawOpts.local,
+            type: rawOpts.type,
+            tgzKey: rawOpts.tgzKey,
         });
     }));
 }

package/dist/cli/handlers/app/export.js

@@ -0,0 +1,191 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = void 0;
+exports.handleAppExport = handleAppExport;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const api = __importStar(require("../../../api/index"));
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const logger_1 = require("../../../utils/logger");
+/** 导出目录默认值：创意升级链路的参考物约定位置。 */
+exports.DEFAULT_EXPORT_OUT = 'source_package/creative';
+/** 升级 manifest 文件名：前置钩子幂等标记 / skill workspace-contains 锚点 / skill 第 0 步信息源。 */
+exports.UPGRADE_MANIFEST_FILENAME = '.upgrade-manifest.json';
+/** 解码后归档大小上限（对齐服务端 UploadHtmlArtifact 的 50MB 口径）。 */
+const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
+/** 校验相对输出路径：禁绝对路径、禁含 ".." 段（与 deploy patch 的 normalizeRel 同口径）。 */
+function normalizeOutDir(rel) {
+    if (node_path_1.default.isAbsolute(rel) || rel.startsWith('/')) {
+        throw new error_1.AppError('ARGS_INVALID', `输出目录不能是绝对路径：${rel}`);
+    }
+    const posix = rel.split(node_path_1.default.sep).join('/').replace(/^\.\//, '');
+    if (posix.split('/').includes('..')) {
+        throw new error_1.AppError('ARGS_INVALID', `输出目录不能包含 "..":${rel}`);
+    }
+    return posix;
+}
+/**
+ * 按魔数识别归档格式并解压到 destDir。
+ * 服务端 GetCodeArchive 的归档名以 .zip 结尾，但底层 git archive 格式由 devops_platform
+ * 决定，历史文档亦有 tar.gz 记载 —— 两种都兼容，识别不了才报错。
+ */
+function extractArchive(archivePath, destDir, head) {
+    const isZip = head.length >= 4 && head[0] === 0x50 && head[1] === 0x4b;
+    const isGzip = head.length >= 2 && head[0] === 0x1f && head[1] === 0x8b;
+    if (isZip) {
+        (0, node_child_process_1.execFileSync)('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio: 'pipe' });
+        return;
+    }
+    if (isGzip) {
+        (0, node_child_process_1.execFileSync)('tar', ['-xzf', archivePath, '-C', destDir], { stdio: 'pipe' });
+        return;
+    }
+    throw new error_1.AppError('EXPORT_ARCHIVE_INVALID', '无法识别归档格式（非 zip / tar.gz）', {
+        next_actions: ['稍后重试 miaoda app export；持续失败请携带 log_id 反馈平台'],
+    });
+}
+function countFiles(dir) {
+    let count = 0;
+    const walk = (cur) => {
+        for (const entry of node_fs_1.default.readdirSync(cur, { withFileTypes: true })) {
+            if (entry.isDirectory())
+                walk(node_path_1.default.join(cur, entry.name));
+            else
+                count += 1;
+        }
+    };
+    walk(dir);
+    return count;
+}
+/**
+ * miaoda app export <app-id> [--out <dir>] [--checkpoint <n>]
+ *
+ * 创意应用升级链路：把源应用（创意稿）的源码从服务端导出到本工程，作为只读参考物。
+ * 链路：studio_server InnerGetCodeArchive（inner 通道，force 身份鉴权：调用者须为源应用
+ * 协作者）→ git archive → 本地解压 → 末尾写 .upgrade-manifest.json（幂等标记 +
+ * skill workspace-contains 锚点 + skill 第 0 步信息源）。
+ *
+ * URL 形状：path :appID 是当前沙箱应用（网关强校验其与沙箱 AK 一致），源应用走 query
+ * sourceAppID —— 跨应用（升级常态：新应用沙箱里导出源创意应用）必须如此。
+ *
+ * 幂等：--out 已存在 manifest 且 sourceAppId 一致时跳过导出直接返回（重试/多轮不重复拉取）。
+ */
+async function handleAppExport(opts) {
+    const appId = (opts.appId || '').trim();
+    if (!appId) {
+        throw new error_1.AppError('ARGS_INVALID', 'app-id 不能为空');
+    }
+    // 当前沙箱应用：网关 AK 校验要求 path :appID 与沙箱绑定应用一致
+    const currentAppId = (opts.currentAppId || '').trim();
+    if (!currentAppId) {
+        throw new error_1.AppError('APP_ID_MISSING', '未指定当前应用', {
+            next_actions: ['设置 export MIAODA_APP_ID=<id>'],
+        });
+    }
+    const outRel = normalizeOutDir(opts.out ?? exports.DEFAULT_EXPORT_OUT);
+    const outDir = node_path_1.default.resolve(process.cwd(), outRel);
+    const manifestPath = node_path_1.default.join(outDir, exports.UPGRADE_MANIFEST_FILENAME);
+    // 幂等：同源应用已导出过则直接复用（前置钩子重试 / 多轮对话不重复拉取）
+    if (node_fs_1.default.existsSync(manifestPath)) {
+        try {
+            const prev = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf-8'));
+            if (prev.sourceAppId === appId) {
+                (0, logger_1.log)('export', `Already exported (manifest matched), skip: ${outRel}`);
+                (0, output_1.emit)({ data: { appId, out: outRel, skipped: true, reason: 'already_exported' } });
+                return;
+            }
+        }
+        catch {
+            // manifest 损坏视为未导出，走覆盖导出
+        }
+    }
+    (0, logger_1.log)('export', `Fetching code archive of ${appId}...`);
+    const resp = await api.app.getCodeArchive({
+        appID: currentAppId,
+        sourceAppID: appId,
+        checkpointID: opts.checkpoint,
+    });
+    const fileBase64 = resp.file ?? '';
+    if (!fileBase64) {
+        throw new error_1.AppError('EXPORT_EMPTY_ARCHIVE', '源应用没有可导出的内容（可能从未提交过代码）', {
+            next_actions: ['请先在源应用完成一轮创作（至少一次成功提交）后重试 miaoda app export'],
+        });
+    }
+    const archive = Buffer.from(fileBase64, 'base64');
+    if (archive.length === 0) {
+        throw new error_1.AppError('EXPORT_EMPTY_ARCHIVE', '归档内容为空，请稍后重试');
+    }
+    if (archive.length > MAX_ARCHIVE_BYTES) {
+        throw new error_1.AppError('EXPORT_ARCHIVE_TOO_LARGE', `归档超过大小上限（${String(archive.length)} > ${String(MAX_ARCHIVE_BYTES)} bytes）`);
+    }
+    // 归档先落临时文件再解压；解压成功前不动已存在的 outDir 内容之外的文件
+    const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-export-'));
+    const archivePath = node_path_1.default.join(tmpDir, resp.name ?? `${appId}.zip`);
+    try {
+        node_fs_1.default.writeFileSync(archivePath, archive);
+        node_fs_1.default.mkdirSync(outDir, { recursive: true });
+        (0, logger_1.log)('export', `Extracting to ${outRel}...`);
+        extractArchive(archivePath, outDir, archive.subarray(0, 4));
+    }
+    finally {
+        node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    // 防御清理：git archive 语义不含 .git，防通道实现变化带出嵌套仓（git 会记 gitlink，
+    // 参考稿进不了提交）；源仓 .gitignore 会成为新仓子树的嵌套忽略规则，极端 case（源仓
+    // force-add 过被自身 ignore 的文件）会让参考稿部分文件被 git add 静默忽略。
+    // 两者对 UX 对照均无价值，解压后移除，保证"进 git 的参考稿 = 导出的全部内容文件"。
+    node_fs_1.default.rmSync(node_path_1.default.join(outDir, '.git'), { recursive: true, force: true });
+    node_fs_1.default.rmSync(node_path_1.default.join(outDir, '.gitignore'), { force: true });
+    const fileCount = countFiles(outDir);
+    const manifest = {
+        sourceAppId: appId,
+        archiveName: resp.name ?? '',
+        checkpointId: opts.checkpoint ?? 0,
+        exportedAt: new Date().toISOString(),
+        fileCount,
+    };
+    node_fs_1.default.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    (0, logger_1.log)('export', 'Exported successfully');
+    (0, output_1.emit)({
+        data: { appId, out: outRel, fileCount, archiveName: manifest.archiveName, skipped: false },
+    });
+}

package/dist/cli/handlers/app/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = exports.handleAppExport = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
@@ -10,6 +10,10 @@ Object.defineProperty(exports, "handleAppInit", { enumerable: true, get: functio
 var sync_1 = require("./sync");
 Object.defineProperty(exports, "handleAppSync", { enumerable: true, get: function () { return sync_1.handleAppSync; } });
 Object.defineProperty(exports, "handleAppUpgrade", { enumerable: true, get: function () { return sync_1.handleAppUpgrade; } });
+var export_1 = require("./export");
+Object.defineProperty(exports, "handleAppExport", { enumerable: true, get: function () { return export_1.handleAppExport; } });
+Object.defineProperty(exports, "DEFAULT_EXPORT_OUT", { enumerable: true, get: function () { return export_1.DEFAULT_EXPORT_OUT; } });
+Object.defineProperty(exports, "UPGRADE_MANIFEST_FILENAME", { enumerable: true, get: function () { return export_1.UPGRADE_MANIFEST_FILENAME; } });
 var migrate_1 = require("./migrate");
 Object.defineProperty(exports, "handleAppMigrate", { enumerable: true, get: function () { return migrate_1.handleAppMigrate; } });
 // commands 层渲染 help 时需要这份枚举；从 handler barrel 转发，避免 commands → services 越界

package/dist/cli/handlers/skills/sync.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleSkillsSync = handleSkillsSync;
 const node_path_1 = __importDefault(require("node:path"));
 const coding_steering_1 = require("../../../utils/coding-steering");
+const sandbox_skills_1 = require("../../../utils/sandbox-skills");
 const spark_meta_1 = require("../../../utils/spark-meta");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
@@ -26,6 +27,25 @@ const output_1 = require("../../../utils/output");
 async function handleSkillsSync(opts) {
     await Promise.resolve();
     const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    // --type 走 sandbox-skills 分支（迁仓后沙箱内 update-skills.sh 调用），跟本地 dev 的
+    // steering 同步逻辑并列——两条路径的目标 / 拉包 / 目录结构完全不同，用 --type 显式路由。
+    if (opts.type !== undefined && opts.type !== '') {
+        const { type, tgzKey } = (0, sandbox_skills_1.validateSandboxSyncOpts)({ type: opts.type, tgzKey: opts.tgzKey });
+        const result = (0, sandbox_skills_1.syncSandboxSkills)({ type, tgzKey, targetDir });
+        (0, output_1.emit)({
+            data: {
+                mode: 'sandbox',
+                type,
+                packageName: result.packageName,
+                version: result.version,
+                lane: result.lane,
+                syncedTop: result.syncedTop,
+                targetDir: result.targetDir,
+            },
+        });
+        return;
+    }
+    // 原有 coding-steering 同步逻辑（本地 dev / miaoda app init 用）
     const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
     if (meta.stack === undefined || meta.stack === '') {
         throw new error_1.AppError('SKILLS_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');

package/dist/main.js

@@ -1,8 +1,45 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const program_1 = require("./cli/program");
+const commander_1 = require("commander");
+const index_1 = require("./cli/commands/index");
+const shared_1 = require("./cli/commands/shared");
+const help_1 = require("./cli/help");
+const config_1 = require("./utils/config");
+const log_id_1 = require("./utils/log_id");
 const output_1 = require("./utils/output");
-const program = (0, program_1.createProgram)();
+const package_json_1 = __importDefault(require("../package.json"));
+// MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）：
+// 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的
+// 子命令）统一走 MiaodaHelp 渲染，避免在每个子命令上重复 configureHelp。
+commander_1.Command.prototype.createHelp = function () {
+    return Object.assign(new help_1.MiaodaHelp(), this.configureHelp());
+};
+const program = new commander_1.Command();
+const { version } = package_json_1.default;
+program
+    .name('miaoda')
+    .description('妙搭平台 CLI，提供数据服务、文件存储等命令行操作。')
+    .usage('<command> [flags]')
+    .version(version, '-v, --version', '显示版本号')
+    .option('--json [fields]', 'JSON 输出，可选字段级选择')
+    .addOption(new commander_1.Option('--output <format>', '输出格式（pretty | json，大小写不敏感）')
+    .choices(['pretty', 'json'])
+    .argParser((0, shared_1.caseInsensitiveChoice)(['pretty', 'json']))
+    .default('pretty'))
+    .option('--verbose', 'debug 日志到 stderr')
+    // 全局接受 -y/--yes：作为 root 全局 option 下发到所有子命令解析（同 --json/--verbose），
+    // 让任意命令带 --yes 都不报 unknown option。对有确认门的破坏性命令生效，其余命令忽略。
+    .option('-y, --yes', '跳过确认提示（对有确认门的命令生效，其余命令忽略）')
+    .helpOption('-h, --help', '显示帮助信息')
+    .hook('preAction', (_thisCmd, actionCmd) => {
+    (0, log_id_1.generateLogId)();
+    const opts = actionCmd.optsWithGlobals();
+    (0, config_1.initConfigFromOpts)(opts);
+});
+(0, index_1.registerCommands)(program);
 program.parseAsync(process.argv).catch((err) => {
     (0, output_1.emitError)(err);
     process.exitCode = 1;

package/dist/utils/http.js

@@ -63,8 +63,14 @@ function createClient(opts) {
 /**
  * 默认灰度泳道。当前 miaoda CLI 接入的新接口（modern deploy 等）只在该泳道生效，
  * 缺省走这个。MIAODA_CANARY_HEADER 可显式覆盖；设为空字符串则去掉头。
+ *
+ * ⚠️ TEMP（creative-upgrade 联调用）：默认泳道临时指向开发泳道 boe_debug_detail_lookup，
+ * 使 alpha 发版进沙箱镜像后，app export / code-archive 等新接口无需 wrapper 即可命中
+ * 尚未合流的 studio_server 改动。
+ * 上线前必须还原为 'boe_miaoda_ccm'，或改为由 agent_tool 按请求 x-tt-env 注入
+ * MIAODA_CANARY_HEADER（详见 http.ts 的 applyCanaryHeader 与 agent_tool ExecShellCmd）。
  */
-const DEFAULT_CANARY_HEADER = 'boe_miaoda_ccm';
+const DEFAULT_CANARY_HEADER = 'boe_debug_detail_lookup';
 /**
  * 注入 x-tt-env 小流量头：env 显式设值 > DEFAULT_CANARY_HEADER。
  *

package/dist/utils/sandbox-skills.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLaneFromTgzKey = extractLaneFromTgzKey;
+exports.syncSandboxSkills = syncSandboxSkills;
+exports.validateSandboxSyncOpts = validateSandboxSyncOpts;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const npm_pack_1 = require("../utils/npm-pack");
+const error_1 = require("../utils/error");
+const logger_1 = require("../utils/logger");
+/**
+ * 覆盖式清空目录：先 shell `rm -rf`，挂了再 fallback 到 fs.rmSync。
+ *
+ * 为什么不直接 fs.rmSync：老沙箱残留的文件可能是**别的用户**写的（例如老 update.sh
+ * 以 root 用户跑，写下 root owned 的 `.last-update`）。`fs.rmSync {force:true}` 只
+ * 吞 ENOENT，遇到 EACCES 直接 throw；而 shell `rm -rf` 对权限的处理更宽松（只要
+ * 对**目录**有写权限就能删掉里面的文件，无视文件本身的 owner/权限）。
+ */
+function forceRemoveDir(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return;
+    try {
+        (0, node_child_process_1.execFileSync)('rm', ['-rf', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
+        if (!node_fs_1.default.existsSync(dir))
+            return;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`sandbox-skills: shell rm -rf ${dir} failed: ${err.message}, fallback to fs.rmSync`);
+    }
+    // Fallback（比如沙箱没 rm、或权限受限）：尽力用 Node fs.rmSync
+    node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+}
+const PACKAGE_BY_TYPE = {
+    miaoda: '@lark-apaas/coding-miaoda-sandbox',
+    'miaoda-modern': '@lark-apaas/coding-miaoda-sandbox',
+    'miaoda-design': '@lark-apaas/coding-miaoda-sandbox',
+    openclaw: '@lark-apaas/coding-openclaw-sandbox',
+};
+// 合并包内的业务线子目录（miaoda / miaoda-modern / miaoda-design）；shared 单独处理。
+const BUSINESS_LINE_BY_TYPE = {
+    miaoda: 'miaoda',
+    'miaoda-modern': 'miaoda-modern',
+    'miaoda-design': 'miaoda-design',
+    openclaw: null, // openclaw 独立包，直接展平
+};
+/**
+ * 从 TCC skillsUpdateTgzKey 反推 lane 名。
+ *   skills_versions/all_feat-xxx.tgz → feat-xxx
+ *   skills_versions/all_latest.tgz   → null（走 @latest）
+ *   任何 all_<X>.tgz                 → <X>
+ *
+ * 用 nullable 而不是空字符串 —— 让调用方能判断"没 lane 就走 latest"。
+ */
+function extractLaneFromTgzKey(tgzKey) {
+    if (tgzKey === undefined || tgzKey === '') {
+        return null;
+    }
+    const match = /(?:^|\/)all_([A-Za-z0-9][A-Za-z0-9_-]*)\.tgz$/.exec(tgzKey);
+    if (match === null) {
+        return null;
+    }
+    const lane = match[1];
+    if (lane === 'latest') {
+        return null;
+    }
+    return lane;
+}
+/**
+ * 主流程：按 type 拉包 + sync 到目标目录。
+ *
+ * sync 策略：**覆盖式写入 + 老文件清理**，对齐老 cp-skills.sh 行为
+ * （`rm -rf $TARGET; mkdir -p $TARGET; cp -r ...`）。
+ */
+function syncSandboxSkills(opts) {
+    const targetDir = node_path_1.default.resolve(opts.targetDir ?? process.cwd());
+    const packageName = PACKAGE_BY_TYPE[opts.type];
+    const businessLine = BUSINESS_LINE_BY_TYPE[opts.type];
+    const lane = extractLaneFromTgzKey(opts.tgzKey);
+    // 优先拉 lane dist-tag；失败 fallback 到 latest（防灰度切换期间 dist-tag 缺失 404）
+    const primaryVersion = lane !== null ? `lane-${lane}` : 'latest';
+    let fetched;
+    try {
+        (0, logger_1.debug)(`sandbox-skills: fetching ${packageName}@${primaryVersion}`);
+        fetched = (0, npm_pack_1.fetchNpmPackage)({
+            packageName,
+            version: primaryVersion,
+            registry: opts.registry,
+        });
+    }
+    catch (err) {
+        if (lane === null) {
+            throw err;
+        }
+        (0, logger_1.debug)(`sandbox-skills: lane ${primaryVersion} not available, fallback to @latest (err: ${err.message})`);
+        fetched = (0, npm_pack_1.fetchNpmPackage)({
+            packageName,
+            version: 'latest',
+            registry: opts.registry,
+        });
+    }
+    try {
+        // 计算 skill 目标根目录：
+        //   - openclaw → <targetDir>/skills/（跟老 cp-skills.sh 的 openclaw 分支对齐，落 $WORKSPACE_DIR/agent/skills）
+        //   - 其它 →     <targetDir>/.agent/skills/
+        const skillsRoot = opts.type === 'openclaw'
+            ? node_path_1.default.join(targetDir, 'skills')
+            : node_path_1.default.join(targetDir, '.agent', 'skills');
+        // 覆盖式：清空目标 skill 根目录（对齐 cp-skills.sh 行为，避免遗留老 skill）
+        // 用 forceRemoveDir 兜底：老沙箱可能残留其他用户写的 stale 文件（例如老 update.sh
+        // 以 root 跑，写下 root owned 的 `.last-update`），fs.rmSync {force:true} 遇到 EACCES
+        // 会 throw。见 forceRemoveDir 注释。
+        forceRemoveDir(skillsRoot);
+        node_fs_1.default.mkdirSync(skillsRoot, { recursive: true });
+        const syncedTop = [];
+        if (businessLine !== null) {
+            // 合并包 miaoda/miaoda-modern/miaoda-design：cp <extractDir>/<business-line>/* 到 target
+            const sourceDir = node_path_1.default.join(fetched.extractDir, businessLine);
+            if (node_fs_1.default.existsSync(sourceDir)) {
+                for (const entry of node_fs_1.default.readdirSync(sourceDir)) {
+                    const from = node_path_1.default.join(sourceDir, entry);
+                    const to = node_path_1.default.join(skillsRoot, entry);
+                    node_fs_1.default.cpSync(from, to, { recursive: true });
+                    syncedTop.push(entry);
+                }
+            }
+            else {
+                (0, logger_1.debug)(`sandbox-skills: source dir ${sourceDir} not found in package (skipped)`);
+            }
+            // shared：sync 合并包内 shared/* 到 target（对齐老 build.sh 的 shared 分发行为）
+            const sharedDir = node_path_1.default.join(fetched.extractDir, 'shared');
+            if (node_fs_1.default.existsSync(sharedDir)) {
+                for (const entry of node_fs_1.default.readdirSync(sharedDir)) {
+                    const from = node_path_1.default.join(sharedDir, entry);
+                    const to = node_path_1.default.join(skillsRoot, entry);
+                    if (node_fs_1.default.existsSync(to)) {
+                        // shared 命中已存在的 skill（如同名）— 保留业务线版本，跳过 shared（对齐老 build.sh：shared 是补丁，同名不覆盖）
+                        (0, logger_1.debug)(`sandbox-skills: shared/${entry} conflicts with business-line skill, skipped`);
+                        continue;
+                    }
+                    node_fs_1.default.cpSync(from, to, { recursive: true });
+                    syncedTop.push(entry);
+                }
+            }
+        }
+        else {
+            // openclaw 独立包：直接把包内所有 skill 目录（除 package.json 等元文件外）平铺到 skillsRoot
+            for (const entry of node_fs_1.default.readdirSync(fetched.extractDir)) {
+                if (entry === 'package.json' || entry === 'README.md' || entry === 'LICENSE')
+                    continue;
+                const from = node_path_1.default.join(fetched.extractDir, entry);
+                const stat = node_fs_1.default.statSync(from);
+                if (!stat.isDirectory())
+                    continue;
+                const to = node_path_1.default.join(skillsRoot, entry);
+                node_fs_1.default.cpSync(from, to, { recursive: true });
+                syncedTop.push(entry);
+            }
+        }
+        // 写 .last-update 时间戳（对齐老 update-skills.sh；供 feida-ai freshness 检查用）
+        const lastUpdatePath = node_path_1.default.join(skillsRoot, '.last-update');
+        node_fs_1.default.writeFileSync(lastUpdatePath, String(Date.now()));
+        return {
+            packageName,
+            version: fetched.version,
+            lane,
+            syncedTop,
+            targetDir: skillsRoot,
+        };
+    }
+    finally {
+        fetched.cleanup();
+    }
+}
+/**
+ * 参数校验：type 白名单 + tgzKey 格式（避免非法值透传到 npm 包名）。
+ */
+function validateSandboxSyncOpts(opts) {
+    const validTypes = ['miaoda', 'miaoda-modern', 'miaoda-design', 'openclaw'];
+    if (opts.type === undefined || !validTypes.includes(opts.type)) {
+        throw new error_1.AppError('SKILLS_INVALID_TYPE', `--type must be one of: ${validTypes.join(', ')} (got: ${opts.type ?? 'undefined'})`);
+    }
+    if (opts.tgzKey !== undefined && opts.tgzKey !== '') {
+        // 校验 tgz key 大致格式（前缀 skills_versions/ + all_ + 允许字符 + .tgz）；避免非法值影响 lane 反推
+        if (!/^[A-Za-z0-9/_\-.]+\.tgz$/.test(opts.tgzKey)) {
+            throw new error_1.AppError('SKILLS_INVALID_TGZ_KEY', `--tgz-key value looks invalid: ${opts.tgzKey}`);
+        }
+    }
+    return { type: opts.type, tgzKey: opts.tgzKey };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.24-alpha.c761e99",
+  "version": "0.1.24-alpha.cb67974",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {

package/dist/cli/program.js

@@ -1,63 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createProgram = createProgram;
-const commander_1 = require("commander");
-const index_1 = require("../cli/commands/index");
-const shared_1 = require("../cli/commands/shared");
-const help_1 = require("../cli/help");
-const version_option_1 = require("../cli/version-option");
-const config_1 = require("../utils/config");
-const log_id_1 = require("../utils/log_id");
-const package_json_1 = __importDefault(require("../../package.json"));
-// 副作用：MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）。
-// 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的子命令）统一走
-// MiaodaHelp 渲染，避免在每个子命令上重复 configureHelp。
-commander_1.Command.prototype.createHelp = function () {
-    return Object.assign(new help_1.MiaodaHelp(), this.configureHelp());
-};
-/**
- * 装配 root program（命令树 + 全局参数 + preAction hook）。
- *
- * 抽成工厂而非写在 main.ts 里，是为了让接线可测 —— main.ts 在 import 期就会 parseAsync，
- * 测试无法 import 它，只能复刻装配，那测到的就不是生产代码。
- * 见 test/cli/program-version-wiring.test.ts。
- *
- * @param argv 供 `--version` 归属判定使用的 argv（process.argv 形态）。显式传入而非直接读
- *             process.argv，同样是为了可测。
- */
-function createProgram(argv = process.argv) {
-    const program = new commander_1.Command();
-    const { version } = package_json_1.default;
-    program.name('miaoda');
-    // 命令树必须先建：shouldExposeRootVersion 要从树上反推「哪些命令自己声明了 --version」。
-    (0, index_1.registerCommands)(program);
-    program
-        .description('妙搭平台 CLI，提供数据服务、文件存储等命令行操作。')
-        .usage('<command> [flags]');
-    // 条件注册：仅当本次 argv 未命中「声明了 --version 的命令路径」时，root 才接管 --version。
-    // 注册位置保持在 option 链首位，否则 -v, --version 会从 Global Flags 第一行掉到末尾。
-    // 详见 src/cli/version-option.ts。
-    if ((0, version_option_1.shouldExposeRootVersion)(program, argv)) {
-        program.version(version, '-v, --version', '显示版本号');
-    }
-    program
-        .option('--json [fields]', 'JSON 输出，可选字段级选择')
-        .addOption(new commander_1.Option('--output <format>', '输出格式（pretty | json，大小写不敏感）')
-        .choices(['pretty', 'json'])
-        .argParser((0, shared_1.caseInsensitiveChoice)(['pretty', 'json']))
-        .default('pretty'))
-        .option('--verbose', 'debug 日志到 stderr')
-        // 全局接受 -y/--yes：作为 root 全局 option 下发到所有子命令解析（同 --json/--verbose），
-        // 让任意命令带 --yes 都不报 unknown option。对有确认门的破坏性命令生效，其余命令忽略。
-        .option('-y, --yes', '跳过确认提示（对有确认门的命令生效，其余命令忽略）')
-        .helpOption('-h, --help', '显示帮助信息')
-        .hook('preAction', (_thisCmd, actionCmd) => {
-        (0, log_id_1.generateLogId)();
-        const opts = actionCmd.optsWithGlobals();
-        (0, config_1.initConfigFromOpts)(opts);
-    });
-    return program;
-}

package/dist/cli/version-option.js

@@ -1,56 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldExposeRootVersion = shouldExposeRootVersion;
-/**
- * root 是否应该注册 `-v, --version`。
- *
- * 背景：Commander 13 默认关闭 positional options，root 的 parseOptions 会扫描整个 argv
- * （这也正是 `--json` / `--verbose` 写在子命令之后仍生效的机制）。因此 root 一旦声明
- * `--version`，任何位置的 `--version` 都会先被 root 的 version listener 命中、打印版本并
- * exit 0，导致 `skills sync --version <ver>` 这类子命令 flag 永远拿不到值。
- *
- * 解法：仅当本次 argv 连续命中「某条自己声明了 --version 的命令路径」时才不注册，把
- * `--version` 让给叶子；其余一切情况照常注册，行为与历史完全一致（例如
- * `miaoda app get --version` 仍打印 CLI 版本）。
- *
- * 路径集从命令树反推，不硬编码 —— 以后任何叶子加 `--version` 都自动纳入。
- *
- * 设计与行为矩阵见
- * docs/superpowers/specs/2026-07-29-root-version-option-collision-design.md。
- */
-function shouldExposeRootVersion(root, argv) {
-    const tokens = argv.slice(2);
-    if (tokens.length === 0)
-        return true;
-    return !collectVersionOwningPaths(root).some((path) => containsPath(tokens, path));
-}
-/**
- * 收集自己声明了 `--version` 的命令路径。
- *
- * 每条路径是一个「段」数组，每段是该层可接受的 token 名（正名 + 全部 alias）。
- * 例如 `skills sync` → `[['skills'], ['sync']]`。
- */
-function collectVersionOwningPaths(root) {
-    const paths = [];
-    const walk = (cmd, trail) => {
-        for (const sub of cmd.commands) {
-            const here = [...trail, [sub.name(), ...sub.aliases()]];
-            if (sub.options.some((o) => o.long === '--version'))
-                paths.push(here);
-            walk(sub, here);
-        }
-    };
-    walk(root, []);
-    return paths;
-}
-/** tokens 里是否存在一段连续子序列，逐位命中 path 各段的正名或 alias。 */
-function containsPath(tokens, path) {
-    outer: for (let i = 0; i + path.length <= tokens.length; i++) {
-        for (let j = 0; j < path.length; j++) {
-            if (!path[j].includes(tokens[i + j]))
-                continue outer;
-        }
-        return true;
-    }
-    return false;
-}