@lark-apaas/miaoda-cli 0.1.24-alpha.28e47ce → 0.1.24-alpha.2eaf5d9

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,16 @@ 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 分支：miaoda | miaoda-modern | miaoda-design | openclaw。有值时忽略 --local，' +
+        '从 @lark-apaas/coding-<pkg>-sandbox-skills 拉包平铺写入，并额外同步 steering ' +
+        '到 .agent/skills/steering/<stack>/（--version 对后者仍生效）')
+        .option('--tgz-key <key>', '配合 --type 使用；老 TCC skillsUpdateTgzKey 值透传，' +
+        '从 skills_versions/all_<X>.tgz 反推出 lane 名 X，再过滤出 -alpha.<X> 版本；缺省走 @latest')
         .addHelpText('after', `
 前置要求
   当前目录（或 --dir）已走过 'miaoda app init'（.spark/meta.json 含 stack）
@@ -41,21 +46,36 @@ function registerSkillsSync(parent) {
     .agents/tech.md
     .claude/skills → ../.agents/skills（软链，让 Claude Code 识别同一份）
 
+  传 --type（沙箱链路，两部分都同步）：
+    .agent/skills/<skill>/...                        ← 业务线 skill，平铺
+    .agent/skills/steering/<stack>/skills/<skill>/   ← steering，同上面默认形态
+    （openclaw 的业务线部分落 skills/ 而非 .agent/skills/）
+
 JSON 输出
   {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false,
             "claudeSkillsLink": "created|updated|noop|conflict"  // 仅 --local 时}}
 
+  传 --type 时：
+  {"data": {"mode": "sandbox", "type": "...", "packageName": "...", "version": "...",
+            "lane": "...", "syncedTop": [...], "targetDir": "...",
+            "steering": {"status": "synced|skipped|failed", ...}}}
+  steering 失败或无 stack 不影响整体成功——业务线 skill 已同步，不该因增量部分阻断
+
 示例
   $ miaoda skills sync                              # 拉 @latest
   $ miaoda skills sync --local                      # 本地 dev / agent 用
   $ miaoda skills sync --version 0.2.0              # 显式指定版本
   $ miaoda skills sync --dir ./my-app
+  # 沙箱链路（由 feida-ai 下发）：业务线 skill + steering 一次同步到位
+  $ miaoda skills sync --type miaoda-modern --tgz-key 'skills_versions/all_demo-lane.tgz'
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         await (0, index_1.handleSkillsSync)({
             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/app/init.js

@@ -60,11 +60,16 @@ async function handleAppInit(opts) {
     const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
     // source_path 导入：当前仅 app_type=modern_html 生效。渲染完模板后、装依赖前叠加进 src/。
     const sourceImport = applySourcePathImport(opts, targetDir);
+    // 本地脚手架门禁：沙箱内所有栈照旧同步（nested，产出 .agent/）；本地只有 LOCAL_STEERING_STACKS
+    // 白名单栈（nestjs-react-fullstack / vite-react）才落地 steering（.claude/.agents）与 logs/。
+    // html / design-html 是纯静态 / 设计产物，本地不需要这套 agent skills 脚手架，整段跳过。
+    const sandbox = (0, env_1.isSandboxEnv)();
+    const scaffoldSteering = sandbox || index_1.LOCAL_STEERING_STACKS.has(stack);
     // 先建 logs/,防止 user 跑 dev 之前 AI/工具 redirect 到 logs/*.log 因为父目录不存在直接挂
     // (dev.js / dev-local.js 自己也建 logs/,但只在它启动后;启动前的 shell redirect 会先于此)。
-    // 仅本地开发需要：沙箱环境由平台 supervisor 拉起 dev,无 init 前的 shell redirect 场景,
-    // 不预建 logs/ 以免在沙箱工作区留空目录。
-    if (!(0, env_1.isSandboxEnv)()) {
+    // 仅本地白名单栈需要：沙箱环境由平台 supervisor 拉起 dev,无 init 前的 shell redirect 场景;
+    // 非白名单栈本地不落 steering 脚手架,也无需预建 logs/。
+    if (!sandbox && scaffoldSteering) {
         (0, logs_dir_1.ensureLogsDir)(targetDir);
     }
     // skills 同步软失败：拉不到 coding-steering 包不该阻断 writeSparkMeta /
@@ -74,21 +79,28 @@ async function handleAppInit(opts) {
     //     跟沙箱端 update-skills.sh 链路对齐
     //   - 本地 → flat (.agents/skills + .claude/skills 软链),
     //     Agent / Claude Code 用同一份;nrf 在本地是主战场,vite-react 等也一样适用
-    const outputLayout = (0, env_1.isSandboxEnv)() ? 'nested' : 'flat';
-    let steeringResult;
+    const outputLayout = sandbox ? 'nested' : 'flat';
+    // 默认空结果：非白名单栈跳过 steering 同步时（scaffoldSteering=false）直接沿用，
+    // 与"拉不到 coding-steering 包"软失败路径共用同一份占位，emit / meta 落盘不受影响。
+    let steeringResult = {
+        version: 'unknown',
+        syncedSkills: [],
+        techSynced: false,
+    };
     let steeringError;
-    try {
-        steeringResult = (0, coding_steering_1.syncCodingSteering)({
-            stack,
-            targetDir,
-            logPrefix: 'init',
-            outputLayout,
-        });
-    }
-    catch (err) {
-        steeringError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
-        steeringResult = { version: 'unknown', syncedSkills: [], techSynced: false };
+    if (scaffoldSteering) {
+        try {
+            steeringResult = (0, coding_steering_1.syncCodingSteering)({
+                stack,
+                targetDir,
+                logPrefix: 'init',
+                outputLayout,
+            });
+        }
+        catch (err) {
+            steeringError = err instanceof Error ? err.message : String(err);
+            (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
+        }
     }
     // 依赖安装：async 模式留到 meta 落盘后派发后台进程（不等装完），同步模式当场装。
     // 同步：装模板钉死的依赖。不带 <pkg>@latest 位置参数,因此 npm 不会改写 package.json/lockfile

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

@@ -6,9 +6,62 @@ 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 file_ops_1 = require("../../../utils/file-ops");
 const spark_meta_1 = require("../../../utils/spark-meta");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
+/**
+ * sandbox 分支下补同步 steering（`.agent/skills/steering/<stack>/`）。
+ *
+ * **绝不抛错**，因为它在 sandbox 链路里是「附加项」而非门禁：
+ *   - 无 `.spark/meta.json` / 无 stack → skipped。对齐老 cp-skills.sh 的
+ *     `[ -n "$STACK" ] && [ "$STACK" != "null" ]` 判断（无 stack 就跳过 steering）。
+ *   - 拉包 / 写盘失败 → failed，但仍让整条 sync 算成功。
+ *
+ * 为什么不能抛：feida-ai 侧 TCC 可配 `allowFailure: false`，一抛就阻断 agent 启动。
+ * 平铺业务线 skill 已经同步好了，不该因为 steering 这个增量部分让用户开不了会话。
+ */
+function syncSteeringForSandbox(params) {
+    let stack;
+    try {
+        const meta = (0, spark_meta_1.readSparkMeta)(params.targetDir);
+        if (meta.stack === undefined || meta.stack === '' || meta.stack === 'null') {
+            return { status: 'skipped', reason: '.spark/meta.json missing stack' };
+        }
+        stack = meta.stack;
+    }
+    catch (err) {
+        return { status: 'skipped', reason: `read .spark/meta.json failed: ${err.message}` };
+    }
+    // 版本口径与下方本地分支保持一致：--version > BOE 的 dist-tag dev > latest
+    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
+    const effectiveVersion = params.version ?? (isBoe ? 'dev' : undefined);
+    try {
+        const r = (0, coding_steering_1.syncCodingSteering)({
+            stack,
+            targetDir: params.targetDir,
+            version: effectiveVersion,
+            // 必须显式传 mode，不能落到 inferMode()：它靠 env MIAODA_DEP_CACHE_DIR 嗅探，
+            // 而 mode 决定读包内哪个 layer（sandbox→`skills/`，local→`skills_local/`）。
+            // `--type` 分支本身就是沙箱语义，嗅探失手会去读不存在的 skills_local/、
+            // 静默同步 0 个 skill。
+            mode: 'sandbox',
+            // 同理固定 nested：落 .agent/skills/steering/<stack>/，与老链路一致
+            outputLayout: 'nested',
+        });
+        return {
+            status: 'synced',
+            stack,
+            version: r.version,
+            syncedSkills: r.syncedSkills,
+            techSynced: r.techSynced,
+        };
+    }
+    catch (err) {
+        return { status: 'failed', reason: err.message };
+    }
+}
 /**
  * miaoda skills sync [--dir <path>] [--version <ver>]
  *
@@ -26,6 +79,57 @@ 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 分支（迁仓后沙箱内由 feida-ai 直接下发调用）。
+    //
+    // 这条分支必须**同时**同步两部分，缺一不可 —— 线上老链路 update-skills.sh 也是两步
+    // （自己 rsync 平铺，再于第 230 行调不带 --type 的 `miaoda skills sync` 写 steering）：
+    //   ① syncSandboxSkills：平铺业务线 skill，rsync 式对齐（保 .keep/.config/steering）
+    //   ② steering：`.agent/skills/steering/<stack>/`，按 .spark/meta.json 的 stack 过滤
+    //   ③ lockDirReadonly：锁只读收尾（update-skills.sh:241），仅沙箱侧路径
+    //
+    // 历史 bug：早期这里 ① 完就 return，steering 既不同步、又被当时的整目录清空删掉，
+    // 沙箱少掉整批技术栈 skill（BOE 实测 scanAllSkills 从 59 掉到 34）。
+    //
+    // `.keep` 语义（update-skills.sh:149）：目标目录挂了 .keep 表示「我手改过，别覆盖」，
+    // ① 会跳过并回报 skippedByKeepFile，此时 ② 也必须跳过 —— 否则 steering 仍被覆写，
+    // 冻结只冻结了一半。
+    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 });
+        const steering = result.skippedByKeepFile
+            ? { status: 'skipped', reason: '.keep file found, sync frozen' }
+            : syncSteeringForSandbox({ targetDir, version: opts.version });
+        // ③ 收尾锁只读（update-skills.sh:241 的 chmod -R a=rX）。必须在 ①② 全部写完之后，
+        //    锁上就写不进去了。`.keep` 冻结时不锁 —— 老链路那条路径是 exit 0 直接走、
+        //    末尾的 chmod 压根不执行，保持一致。
+        //
+        // **只锁沙箱侧**：这里的 result.targetDir 只会是 `.agent/skills` 或 `skills`
+        //   （见 sandbox-skills 的 skillsRoot），都是平台下发的资产根。本地 `--local` 走
+        //   flat layout 输出到 `.agents/`，压根不经过本分支，权限不会被碰。
+        //
+        // 回退风险由解锁侧兜：权限是持久化在磁盘的，代码能回退、磁盘状态不会。所以
+        //   file-ops 的 unlockDirForWrite 在**两处写入前**都调用了（syncSandboxSkills 的
+        //   写入前 + syncCodingSteering 的 nested 分支写入前），任一入口都不会因为
+        //   上一轮的锁而 EACCES。改动这里之前先确认那两处解锁还在。
+        const lockedReadonly = result.skippedByKeepFile ? false : (0, file_ops_1.lockDirReadonly)(result.targetDir);
+        (0, output_1.emit)({
+            data: {
+                mode: 'sandbox',
+                type,
+                packageName: result.packageName,
+                version: result.version,
+                lane: result.lane,
+                syncedTop: result.syncedTop,
+                deleted: result.deleted,
+                skippedByKeepFile: result.skippedByKeepFile,
+                lockedReadonly,
+                targetDir: result.targetDir,
+                steering,
+            },
+        });
+        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/config/migrate-configs/vite-react-to-nestjs-react-fullstack.js

@@ -263,6 +263,10 @@ exports.MIGRATE_CONFIG = {
                 'dotenv',
                 // client-toolkit：替代 lite，业务代码 codemod 后走它
                 '@lark-apaas/client-toolkit',
+                // drizzle-orm —— `gen:db-schema` 生成的 server/database/schema.ts 从
+                // 'drizzle-orm/pg-core' / 'drizzle-orm' 导入 pgTable / sql 等 runtime API,
+                // 缺依赖时 nest build / dev 起来直接 ERR_MODULE_NOT_FOUND。
+                'drizzle-orm',
             ],
             devDependencies: [
                 // nest start / nest build 必需

package/dist/services/app/init/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ASYNC_INSTALL_LOG = exports.runAsyncInstallWorker = exports.dispatchAsyncInstall = exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.IMPORT_SKIP_FILES = exports.IMPORT_SKIP_DIRS = exports.importSourceSrc = exports.TEMPLATE_PACKAGE_BY_STACK = exports.STACK_BY_APP_TYPE = exports.APP_TYPES = exports.SUPPORTED_STACKS = exports.resolveStack = exports.renderTemplate = void 0;
+exports.ASYNC_INSTALL_LOG = exports.runAsyncInstallWorker = exports.dispatchAsyncInstall = exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.IMPORT_SKIP_FILES = exports.IMPORT_SKIP_DIRS = exports.importSourceSrc = exports.TEMPLATE_PACKAGE_BY_STACK = exports.STACK_BY_APP_TYPE = exports.APP_TYPES = exports.LOCAL_STEERING_STACKS = exports.SUPPORTED_STACKS = exports.resolveStack = exports.renderTemplate = void 0;
 var template_1 = require("./template");
 Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
 Object.defineProperty(exports, "resolveStack", { enumerable: true, get: function () { return template_1.resolveStack; } });
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return template_1.SUPPORTED_STACKS; } });
+Object.defineProperty(exports, "LOCAL_STEERING_STACKS", { enumerable: true, get: function () { return template_1.LOCAL_STEERING_STACKS; } });
 Object.defineProperty(exports, "APP_TYPES", { enumerable: true, get: function () { return template_1.APP_TYPES; } });
 Object.defineProperty(exports, "STACK_BY_APP_TYPE", { enumerable: true, get: function () { return template_1.STACK_BY_APP_TYPE; } });
 Object.defineProperty(exports, "TEMPLATE_PACKAGE_BY_STACK", { enumerable: true, get: function () { return template_1.TEMPLATE_PACKAGE_BY_STACK; } });

package/dist/services/app/init/template.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APP_TYPES = exports.STACK_BY_APP_TYPE = exports.SUPPORTED_STACKS = exports.TEMPLATE_PINNED_VERSION_BY_STACK = exports.TEMPLATE_PACKAGE_BY_STACK = void 0;
+exports.APP_TYPES = exports.STACK_BY_APP_TYPE = exports.LOCAL_STEERING_STACKS = exports.SUPPORTED_STACKS = exports.TEMPLATE_PINNED_VERSION_BY_STACK = exports.TEMPLATE_PACKAGE_BY_STACK = void 0;
 exports.resolveStack = resolveStack;
 exports.renderTemplate = renderTemplate;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -27,6 +27,13 @@ exports.TEMPLATE_PACKAGE_BY_STACK = {
  */
 exports.TEMPLATE_PINNED_VERSION_BY_STACK = {};
 exports.SUPPORTED_STACKS = Object.keys(exports.TEMPLATE_PACKAGE_BY_STACK);
+/**
+ * 本地开发（非沙箱）需要落地 agent skills 脚手架（.claude/.agents）与 logs/ 的 stack 白名单。
+ * 只有这些全栈 / 前端框架栈在本地才需要 coding-steering 的 skills；html / design-html 是纯
+ * 静态 / 设计产物，本地无需这套脚手架，init 直接跳过 syncCodingSteering 与 logs 创建。
+ * 沙箱环境不受此白名单约束（所有栈照旧走 nested 同步，产出 .agent/）。
+ */
+exports.LOCAL_STEERING_STACKS = new Set(['nestjs-react-fullstack', 'vite-react']);
 /**
  * app_type（业务类型）→ stack 短名映射。仅在调用方未显式传 --template 时用于解析 stack。
  * 与 src/api/app/types.ts 的 AppType 枚举无关，是独立的业务类型概念。

package/dist/services/deploy/modern/pipelines/design-local.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.designLocalPublishPipeline = designLocalPublishPipeline;
-const spark_meta_1 = require("../../../../utils/spark-meta");
 const error_1 = require("../../../../utils/error");
 const logger_1 = require("../../../../utils/logger");
 const index_1 = require("../atoms/index");
@@ -38,9 +37,6 @@ async function designLocalPublishPipeline(opts) {
             await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
             throw err;
         }
-        if (release.onlineUrl !== undefined && release.onlineUrl !== '') {
-            (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { appUrl: release.onlineUrl });
-        }
         (0, logger_1.log)('deploy', 'Deployed successfully');
         return {
             appId: ctx.appId,

package/dist/services/deploy/modern/pipelines/local.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.localBuildLocalPublishPipeline = localBuildLocalPublishPipeline;
-const spark_meta_1 = require("../../../../utils/spark-meta");
 const error_1 = require("../../../../utils/error");
 const logger_1 = require("../../../../utils/logger");
 const index_1 = require("../atoms/index");
@@ -64,9 +63,6 @@ async function localBuildLocalPublishPipeline(opts) {
         await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
         throw err;
     }
-    if (release.onlineUrl !== undefined && release.onlineUrl !== '') {
-        (0, spark_meta_1.writeSparkMeta)(ctx.projectDir, { appUrl: release.onlineUrl });
-    }
     (0, logger_1.log)('deploy', 'Deployed successfully');
     return {
         appId: ctx.appId,

package/dist/utils/coding-steering.js

@@ -9,6 +9,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const npm_pack_1 = require("../utils/npm-pack");
 const logger_1 = require("../utils/logger");
 const env_1 = require("../utils/env");
+const file_ops_1 = require("../utils/file-ops");
 const STEERING_PACKAGE = '@lark-apaas/coding-steering';
 function inferMode() {
     // 沙箱（MIAODA_DEP_CACHE_DIR 非空）→ sandbox；本地 → local
@@ -63,6 +64,29 @@ function syncCodingSteering(opts) {
                 dstSkillsDir: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'skills'),
                 dstTechPath: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'tech.md'),
             };
+        // 写入前解锁：沙箱链路每轮同步末尾会把 `.agent/skills` chmod -R a=rX 锁成只读
+        // （file-ops 的 lockDirReadonly，对齐 update-skills.sh:241），不解锁下面 mkdir/cp
+        // 就 EACCES。老链路的解锁在 update-skills.sh:160-165 脚本层；这里下沉到写入方，
+        // 沙箱 `--type` 与本地 `skills sync` / `app init` 任一入口都不会漏。
+        //
+        // **只放开真正要写的两处**，不是整棵树递归解锁：
+        //   - `.agent/skills` 本身（**非递归**）：只为了能创建 `steering/` 这个条目
+        //   - `.agent/skills/steering/`（递归）：本函数唯一会改的子树
+        // 那 20 多个平铺业务线 skill 跟 steering 毫无关系，递归解锁会把它们一并打开 ——
+        // 早期就是这么写的，等于用户跑一次 `miaoda skills sync` 就把整个 skills 目录解封了。
+        //
+        // **先判断再动手**：目录没被锁（本地开发者的常态）就一次 chmod 都不跑，权限位一位
+        // 不动。判据是 owner 写位而非 accessSync，理由见 isLockedReadonly 的注释。
+        //
+        // **仅 nested**：flat 的输出根是 `.agents/`，lockDirReadonly 只作用于 `--type` 分支的
+        // `.agent/skills` / `skills`，`.agents/` 永远不会被锁，对它 chmod 纯属多余。
+        const nestedSkillsRoot = node_path_1.default.join(opts.targetDir, '.agent', 'skills');
+        const nestedSteeringDir = node_path_1.default.join(nestedSkillsRoot, 'steering');
+        const shouldRelock = layout === 'nested' && (0, file_ops_1.isLockedReadonly)(nestedSkillsRoot);
+        if (shouldRelock) {
+            (0, file_ops_1.unlockDirForWrite)(nestedSkillsRoot, { recursive: false });
+            (0, file_ops_1.unlockDirForWrite)(nestedSteeringDir);
+        }
         node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
         let techSynced = false;
         const techSrc = node_path_1.default.join(stackDir, 'tech.md');
@@ -96,6 +120,15 @@ function syncCodingSteering(opts) {
         if (layout === 'flat') {
             claudeSkillsLink = ensureClaudeSkillsSymlink(opts.targetDir, logPrefix);
         }
+        // 还原只读锁：解锁与加锁必须对称。否则单独跑一次 `miaoda skills sync` / `app init`
+        // 就把锁永久打开了 —— 老链路里这条命令是 update-skills.sh:230 调的、脚本在 :241
+        // 补了 chmod，单独跑没人补。范围与上面解锁的两处严格一致，先子树后自身。
+        //
+        // 只在「进来时本来就锁着」时还原，所以本地永远不会被莫名锁上。
+        if (shouldRelock) {
+            (0, file_ops_1.lockDirReadonly)(nestedSteeringDir);
+            (0, file_ops_1.lockDirReadonly)(nestedSkillsRoot, { recursive: false });
+        }
         (0, logger_1.log)(logPrefix, `Synced ${String(synced.length)} skill(s), tech.md ${techSynced ? 'yes' : 'no'} (mode=${mode}, layout=${layout})`);
         return {
             version: fetched.version,

package/dist/utils/file-ops.js

@@ -5,6 +5,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeLineFromFile = removeLineFromFile;
 exports.removeLineFromContent = removeLineFromContent;
+exports.unlockDirForWrite = unlockDirForWrite;
+exports.isLockedReadonly = isLockedReadonly;
+exports.lockDirReadonly = lockDirReadonly;
+exports.forceRemove = forceRemove;
+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 logger_1 = require("./logger");
@@ -43,3 +48,99 @@ function removeLineFromContent(content, pattern) {
         changed: filtered.length !== lines.length,
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// 目录权限：沙箱 skill 目录被刻意锁成只读，写入前须解锁、写完须锁回。
+//
+// 背景：老 update-skills.sh 同步末尾 `chmod -R a=rX "$TARGET_DIR"`（:241）把
+// skills 锁成只读——skills 是平台下发的资产，不该被用户/agent 手改；下一轮同步
+// 开头再 `chmod -R u+w`（:160-165）解锁。目录 owner 是沙箱当前用户，虽无写位但
+// 有权改权限，所以不需要 sudo（沙箱容器带 no_new_privileges，sudo 本就被禁）。
+//
+// 放在 file-ops 而非 sandbox-skills：coding-steering 与 sandbox-skills 两条写入
+// 路径都要用，避免其中一方 import 另一方造成方向混乱。
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 解锁目录使其可写（`chmod -R u+w`）。
+ *
+ * 写入被只读锁保护的目录前必须调用，否则 `fs.cpSync` / `fs.rmSync` 报 EACCES。
+ * 只加 owner 写位、不动 g/o，与老链路一致。目录不存在直接返回 false（调用方
+ * 通常紧接着 mkdir）。失败只 debug 不抛：解锁是尽力而为，真写不进去让后续
+ * 写操作自己报错，错误信息更具体。
+ */
+function unlockDirForWrite(dir, opts) {
+    if (!node_fs_1.default.existsSync(dir))
+        return false;
+    const recursive = opts?.recursive ?? true;
+    const args = recursive ? ['-R', 'u+w', dir] : ['u+w', dir];
+    try {
+        (0, node_child_process_1.execFileSync)('chmod', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: chmod ${args.join(' ')} failed: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * 目录当前是否处于只读锁下 —— 判据是 **owner 写位缺失**（`mode & 0o200 === 0`），
+ * 正是 {@link lockDirReadonly} 的 `a=rX` 造成的状态。
+ *
+ * 不用 `fs.accessSync(dir, W_OK)`：那个按**进程 uid** 判定，root 对任何 mode 都返回
+ * 可写（老 update.sh 就以 root 跑过），会把锁着的目录误判成没锁。读 mode 位与 uid 无关。
+ *
+ * 用途是「先判断再决定要不要 chmod」：本地开发者的目录从来不会被我们锁，于是一次
+ * chmod 都不跑，权限位一位不动。
+ */
+function isLockedReadonly(dir) {
+    try {
+        return (node_fs_1.default.statSync(dir).mode & 0o200) === 0;
+    }
+    catch {
+        return false; // 不存在 / stat 失败：当作没锁，让后续写操作自己报错
+    }
+}
+/**
+ * 把目录锁成只读（`chmod -R a=rX`），对齐 update-skills.sh:241。
+ *
+ * `a=rX`：所有人只读；`X` 是大写，只给目录和「原本已有执行位」的文件加 x，
+ * 不会把 SKILL.md 变成可执行。会连 owner 写位一并清掉，所以下一轮写入前必须
+ * {@link unlockDirForWrite}。
+ *
+ * **调用时机必须是全部写入完成之后**——锁上就写不进去了。
+ */
+function lockDirReadonly(dir, opts) {
+    if (!node_fs_1.default.existsSync(dir))
+        return false;
+    const recursive = opts?.recursive ?? true;
+    const args = recursive ? ['-R', 'a=rX', dir] : ['a=rX', dir];
+    try {
+        (0, node_child_process_1.execFileSync)('chmod', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: chmod ${args.join(' ')} failed: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * 强制删除文件或目录，三层兜底：`chmod -R u+w` → `rm -rf` → `fs.rmSync`。
+ *
+ * 为什么不能直接 `fs.rmSync`：删条目需要**父目录**写权限，而 skill 目录常处于
+ * 只读锁下；另外老 update.sh 曾以 root 跑过，可能留下异主文件（如 root-owned 的
+ * `.last-update`），`rmSync{force:true}` 只忽略 ENOENT、遇 EACCES 仍抛。
+ * shell `rm -rf` 对异主文件 / 怪符号链接比 rmSync 宽容，故作主档。
+ */
+function forceRemove(target) {
+    if (!node_fs_1.default.existsSync(target))
+        return;
+    unlockDirForWrite(target);
+    try {
+        (0, node_child_process_1.execFileSync)('rm', ['-rf', target], { stdio: ['ignore', 'ignore', 'pipe'] });
+        if (!node_fs_1.default.existsSync(target))
+            return;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: rm -rf ${target} failed: ${err.message}`);
+    }
+    node_fs_1.default.rmSync(target, { recursive: true, force: true });
+}

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/npm-pack.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickLaneVersion = pickLaneVersion;
 exports.fetchNpmPackage = fetchNpmPackage;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -11,6 +12,38 @@ const node_path_1 = __importDefault(require("node:path"));
 const error_1 = require("./error");
 const logger_1 = require("./logger");
 const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/';
+/**
+ * 从 `npm view <pkg> versions --json` 里过滤出后缀 `-alpha.<X>` 的版本。
+ *
+ * 用于 sandbox-skills 新姿势（2026-08 迁离 lane-<X> dist-tag 之后）：
+ * publish-sandbox-skills.sh 每次发的版本号 = `<base>-alpha.<LANE>-<YYYYMMDDHHMMSS>`，
+ * TCC 里的 X = `<LANE>-<TIMESTAMP>` 全局唯一。反推侧过滤 versions 数组即可精确命中。
+ *
+ * **不 throw 是硬要求**（消费方 fallback @latest 依赖返回 null 判定）：
+ *   - `npm view` 网络挂、包不存在、metadata 解析失败 → 返回 null
+ *   - 无版本匹配 → 返回 null
+ *   - 多版本匹配（理论上不该发生，因 timestamp 精度到秒）→ 字符串排序取最大（timestamp 最大）
+ */
+function pickLaneVersion(packageName, X, registry) {
+    const reg = registry ?? process.env.MIAODA_NPM_REGISTRY ?? DEFAULT_REGISTRY;
+    const suffix = `-alpha.${X}`;
+    try {
+        const stdout = (0, node_child_process_1.execFileSync)('npm', ['view', packageName, 'versions', '--json', '--registry', reg], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const versions = JSON.parse(stdout);
+        if (!Array.isArray(versions))
+            return null;
+        const matched = versions.filter((v) => typeof v === 'string' && v.endsWith(suffix));
+        if (matched.length === 0)
+            return null;
+        // 通常唯一命中（X 含 timestamp 到秒）；多命中时字符串排序取最大（timestamp 更晚）
+        matched.sort();
+        return matched[matched.length - 1] ?? null;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`pickLaneVersion(${packageName}, X=${X}) failed: ${err.message}`);
+        return null;
+    }
+}
 /**
  * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
  * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。

package/dist/utils/sandbox-skills.js

@@ -0,0 +1,271 @@
+"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_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");
+const file_ops_1 = require("../utils/file-ops");
+const PACKAGE_BY_TYPE = {
+    miaoda: '@lark-apaas/coding-miaoda-sandbox-skills',
+    'miaoda-modern': '@lark-apaas/coding-miaoda-sandbox-skills',
+    'miaoda-design': '@lark-apaas/coding-miaoda-sandbox-skills',
+    openclaw: '@lark-apaas/coding-openclaw-sandbox-skills',
+};
+/**
+ * 目标根目录下**永不删除**的控制文件（对齐 `update-skills.sh` 的删除白名单）：
+ *   - `.keep`        沙箱级「冻结 skills」开关，存在即整体跳过同步（见 {@link syncSandboxSkills}）
+ *   - `.config`      沙箱级 tgzKey 覆盖，feida-ai 的 `enableConfigFileOverride` 读它
+ *                    （`getKeepFileTgzKey` → `.agent/skills/.config`），删了会让版本钉死失效
+ *   - `.last-update` 同步时间戳，feida-ai freshness 检查读它；每轮末尾会重写，列进来只是语义完备
+ */
+const PRESERVED_ENTRIES = new Set(['.keep', '.config', '.last-update']);
+/** `.keep` 存在时整体跳过同步的标记文件名，语义同 `update-skills.sh:149`。 */
+const KEEP_FILE = '.keep';
+/**
+ * rsync 式对齐：删掉目标里「源包已不提供」的顶层条目，对齐 `update-skills.sh:196-218`。
+ *
+ * 与整目录清空的区别（后者是本函数取代的旧实现）：
+ *   - 保住 {@link PRESERVED_ENTRIES} 里的控制文件
+ *   - 保住 `steering/` 子树 —— 它由 handler 层的 syncCodingSteering 独占管理
+ *     （`update-skills.sh:207` 平铺型分支同样明确「归 miaoda CLI 管，update.sh 不删不覆盖」）
+ *
+ * 只处理顶层：源包内容本身就是「一个 skill 一个顶层目录」，逐文件比对没有额外收益。
+ */
+function pruneStaleEntries(skillsRoot, sourceTopEntries) {
+    if (!node_fs_1.default.existsSync(skillsRoot))
+        return [];
+    const deleted = [];
+    for (const entry of node_fs_1.default.readdirSync(skillsRoot)) {
+        if (PRESERVED_ENTRIES.has(entry) || entry === 'steering')
+            continue;
+        if (sourceTopEntries.has(entry))
+            continue;
+        const target = node_path_1.default.join(skillsRoot, entry);
+        try {
+            // forceRemove 的 chmod→rm -rf→rmSync 三层兜底对文件同样适用：
+            // 老 update.sh 以 root 跑过、且会 chmod -R 锁只读，直接 rmSync 会 EACCES
+            (0, file_ops_1.forceRemove)(target);
+            deleted.push(entry);
+        }
+        catch (err) {
+            (0, logger_1.debug)(`sandbox-skills: prune ${entry} failed: ${err.message}`);
+        }
+    }
+    return deleted;
+}
+// 合并包内的业务线子目录（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_feat_xxx.tgz  → feat-xxx  (_ sanitize → -)
+ *   skills_versions/all_latest.tgz    → null（走 @latest）
+ *   任何 all_<X>.tgz                  → <X> 里 _ 全部转 -
+ *
+ * **宽进严出**：正则允许 `_` 匹配（兼容老 miaoda-skills 时代 TOS key 含 `_` 的存量 TCC
+ * 命名），但返回时 sanitize 成 `-` —— 对齐 publish-sandbox-skills.sh 侧只发 `-` 版
+ * lane 的现实（npm SemVer pre-release 只允许 `[A-Za-z0-9-]`，不允许 `_`）。
+ * 存量 TCC 里如果有 `all_feat_xxx.tgz` 这种命名，反推出 `feat-xxx` 后能正确命中
+ * npm 上实际发出的 `@lane-feat-xxx` 包，而不是静默 fallback 到 @latest。
+ *
+ * 用 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].replace(/_/g, '-');
+    if (lane === 'latest') {
+        return null;
+    }
+    return lane;
+}
+/**
+ * 主流程：按 type 拉包 + sync 到目标目录。
+ *
+ * sync 策略：**rsync 式对齐**，逐条对应线上真实跑的 `update-skills.sh`（不是
+ * `cp-skills.sh`——那个脚本线上不执行，日志里的 `copied/skipped/deleted` 出自前者）：
+ *   1. 目标目录有 `.keep` → 整体跳过（`update-skills.sh:149`）
+ *   2. 覆盖式写入源包提供的顶层条目
+ *   3. 删掉源包已不提供的顶层条目（{@link pruneStaleEntries}），但保住
+ *      {@link PRESERVED_ENTRIES} 与 `steering/`
+ *
+ * 不用整目录清空：那会删掉 `.config`（沙箱级 tgzKey 覆盖）、`.keep`（冻结开关）
+ * 和 handler 层刚写的 `steering/`，而老链路对这三者都有保护。
+ */
+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 拉包 ----
+    // 新姿势（2026-08 迁离 lane-<X> dist-tag 之后）：
+    //   TCC 里的 X（比如 `feat-migrate-skills-from-miaoda-skills-20260805143512`）
+    //   包含 branch + timestamp，`pickLaneVersion` 走 `npm view <pkg> versions --json`
+    //   过滤 `endsWith('-alpha.' + X)`（因 X 含 timestamp 全局唯一，唯一命中或 0 命中）。
+    //   0 命中 → fallback @latest（对齐旧 TCC 值找不到、灰度切换期间的兜底语义）。
+    //   `pickLaneVersion` 内部对 `npm view` 报错 / 无匹配都返回 null，绝不 throw ——
+    //   目标就是"不挂掉"。
+    let fetched;
+    const laneVersion = lane === null ? null : (0, npm_pack_1.pickLaneVersion)(packageName, lane, opts.registry);
+    if (lane !== null && laneVersion === null) {
+        (0, logger_1.debug)(`sandbox-skills: no npm version matched -alpha.${lane}, fallback to @latest ` +
+            `(TCC 里的 X 可能是老 lane dist-tag 命名 / 已 unpublish / npm view 挂 / 网络断)`);
+    }
+    const primaryVersion = laneVersion ?? 'latest';
+    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 (primaryVersion === 'latest') {
+            throw err;
+        }
+        (0, logger_1.debug)(`sandbox-skills: pack ${primaryVersion} failed, 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');
+        // `.keep` 短路：对齐 update-skills.sh:149-152，沙箱侧放了这个文件即表示
+        // 「我手改过 skills，别覆盖我」，整体跳过同步（含 steering —— 调用方看到
+        // skipped 就不该再往下写）。
+        if (node_fs_1.default.existsSync(node_path_1.default.join(skillsRoot, KEEP_FILE))) {
+            (0, logger_1.debug)(`sandbox-skills: ${KEEP_FILE} found in ${skillsRoot}, skip sync`);
+            return {
+                packageName,
+                version: fetched.version,
+                lane,
+                syncedTop: [],
+                deleted: [],
+                skippedByKeepFile: true,
+                targetDir: skillsRoot,
+            };
+        }
+        // 写入前解锁，对齐 update-skills.sh:160-165：
+        //   上一轮同步末尾会 chmod -R a=rX 锁只读（见 file-ops 的 lockDirReadonly），
+        //   不先解锁，下面 fs.cpSync 覆盖已存在的 skill 目录必 EACCES。
+        // 只加 u+w（不动 g/o），与老链路一致；owner 是沙箱当前用户，无需 sudo。
+        (0, file_ops_1.unlockDirForWrite)(skillsRoot);
+        node_fs_1.default.mkdirSync(skillsRoot, { recursive: true });
+        const syncedTop = [];
+        // 源包提供的全部顶层条目 —— prune 的保留集。与 syncedTop 分开维护：syncedTop 是
+        // 「本轮实际写入」，用于对外汇报；prune 只能依据「源包提供了什么」来判断 stale，
+        // 两者一旦哪天再次分叉（比如某分支又加了跳过写入的条件），拿 syncedTop 当保留集
+        // 就会把没重写的条目误判成 stale 删掉、下一轮再写回来，反复抖动。
+        const sourceTop = new Set();
+        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);
+                    sourceTop.add(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：合并包内 shared/* 到 target。**无条件覆盖**，逐字对齐老 build.sh:42-52 ——
+            // 那里业务线先 `cp -r`（:33-34）、shared 后 `cp -r`（:47），后写覆盖前写，
+            // 即同名时 **shared 赢**。当前包里两边无同名交集，但语义得跟老链路一致。
+            //
+            // 早期这里写成「`fs.existsSync(to)` 就 continue」，有两个问题：
+            //   1. 同名优先级反了（变成业务线赢）；
+            //   2. 更严重 —— existsSync 分不清「本轮业务线刚写的」和「上一轮 shared 自己写的」，
+            //      于是 shared skill 首次落盘后就永久冻结，包里再更新也同步不到已有沙箱
+            //      （沙箱磁盘跨会话保留，每次 update-skills 都会命中 existsSync）。
+            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);
+                    sourceTop.add(entry);
+                    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);
+                sourceTop.add(entry);
+                node_fs_1.default.cpSync(from, to, { recursive: true });
+                syncedTop.push(entry);
+            }
+        }
+        // rsync 式收尾：删掉源包已不提供的顶层条目（对齐 update-skills.sh 的 deleted）。
+        // 保留集用 sourceTop（源包提供的全部）而非 syncedTop（本轮实际写入的）——原因见
+        // sourceTop 声明处的注释：否则 shared skill 会被反复删了又写。
+        const deleted = pruneStaleEntries(skillsRoot, sourceTop);
+        // 写 .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,
+            deleted,
+            skippedByKeepFile: false,
+            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.28e47ce",
+  "version": "0.1.24-alpha.2eaf5d9",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {