@lark-apaas/miaoda-cli 0.1.32 → 0.1.33-alpha.dc7b6a0

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

@@ -11,10 +11,12 @@ const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../../../config/migrate-configs/index");
 const index_2 = require("../../../services/app/init/index");
 const migrate_rule_1 = require("../../../utils/migrate-rule");
+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");
 const env_1 = require("../../../utils/env");
+const preview_control_1 = require("../../../utils/preview-control");
 const logger_1 = require("../../../utils/logger");
 /**
  * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
@@ -99,78 +101,141 @@ async function handleAppMigrate(opts) {
     // 的 miaodaTemplate.archType 拿到的动态值，rule 配置时不知道，由 handler 在拿到
     // renderTemplate 结果后单独写。version 也一并写回方便 sync 后续诊断。
     (0, spark_meta_1.writeSparkMeta)(targetDir, { archType: templateArchType, version: templateVersion });
-    // 清掉 user app 的 node_modules —— migrate 改了 dependencies 集合（删 lite + 加 NestJS
-    // 全套）+ rule 已经把 package-lock.json 删了。如果 node_modules 留着，npm install 时旧
-    // 包还在 node_modules 顶层 hoist 树里，可能跟新 package.json spec 撞 peer 冲突
-    // （比如旧 coding-preset-vite-react@1.0.8 peer vite@^8 跟新 vite@^7 撞）。
-    // 软失败：node_modules 不存在不报错。
-    const nodeModulesPath = node_path_1.default.join(targetDir, 'node_modules');
-    if (node_fs_1.default.existsSync(nodeModulesPath)) {
-        (0, logger_1.log)('migrate', '清理 node_modules（dependencies 集合已变）...');
-        node_fs_1.default.rmSync(nodeModulesPath, { recursive: true, force: true });
+    // 沙箱环境下先停掉 dev server（预览）—— 保活由 code-server 管，`pkill dev.js` 会被立刻
+    // 重新拉起，拿不到"停住"的状态。dev server 活着时 vite 持续往 node_modules/.vite/deps 写
+    // 文件，下面 rm node_modules 走到顶层 rmdir 时目录又非空，直接 ENOTEMPTY 失败（历史故障）。
+    // stop 返回成功即代表 dev 进程已确认退出（服务端等到 exit 事件才返回），不需要再 pkill。
+    //   - 只在沙箱内做（本地用户自己管 dev 进程，不该被 CLI 动）
+    //   - 软失败：接口不存在（老版本 code-server 返 404）/ 连不上都不阻断，降级回老路径
+    //     （带重试的 rm + 结尾 pkill 让保活拉起）
+    //   - ⚠️ 恢复条件用 mayBeSuspended 而不是 ok：服务端在抛错前就置了暂停位，stop 失败
+    //     （500 / 超时）时暂停位可能已生效，不恢复就等于永久关掉保活。只有 404 能确定无副作用。
+    let previewStopped = false;
+    let previewMayBeSuspended = false;
+    let previewStopError;
+    if ((0, env_1.isSandboxEnv)()) {
+        (0, logger_1.log)('migrate', '停止 dev server(预览)以便安全重装依赖...');
+        const stopped = await (0, preview_control_1.stopPreview)({ logPrefix: 'migrate' });
+        previewStopped = stopped.ok;
+        previewMayBeSuspended = stopped.mayBeSuspended;
+        if (!stopped.ok) {
+            previewStopError = stopped.error;
+            const tail = previewMayBeSuspended ? '结束时仍会尝试恢复' : '降级为不停 dev 直接重装';
+            (0, logger_1.log)('migrate', `⚠ 停止预览失败 (continuing, ${tail}): ${stopped.error ?? ''}`);
+        }
     }
-    // 跑 npm install 物化新依赖集合 + 把 followLatestPackages 钉 latest
-    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
-    // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
-    // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
     const followLatest = config.followLatestPackages ?? [];
-    const installArgs = [
-        'install',
-        '--no-audit',
-        '--no-fund',
-        '--ignore-scripts',
-        '--registry',
-        (0, index_2.resolveNpmInstallRegistry)(),
-        ...followLatest.map((pkg) => `${pkg}@latest`),
-    ];
-    (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
     let installError;
+    let nodeModulesCleanError;
+    let nodeModulesPurgeStrategy;
+    let nodeModulesTrashLeftover;
+    let previewRestarted = false;
+    let previewRestartError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
-            cwd: targetDir,
-            stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
-        });
-    }
-    catch (err) {
-        installError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
-    }
-    // 重启 dev process 前清 vite cache —— migrate 改了 package.json + lockfile,
-    // 老 vite 进程的 .vite/deps cache 的 lockfileHash 跟新 lockfile 不一致。
-    // 不清的话 supervisor 拉起的新 vite cold start 会立即 "Re-optimizing because
-    // lockfile has changed", re-optimize 期间 ModuleGraph transform cache 跟
-    // deps middleware metadata 短暂不同步, 浏览器请求老 hash 触发
-    // ERR_OUTDATED_OPTIMIZED_DEP → 504 死锁(详见 fullstack-plugin#1143 的 504
-    // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
-    // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
-    //
-    //   - 只在 SANDBOX_ID 非空时做(本地一般不会撞这条链路)
-    //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
-    //   - 软失败:.vite 不存在 / 删失败都不阻断
-    if (installError === undefined &&
-        process.env.SANDBOX_ID !== undefined &&
-        process.env.SANDBOX_ID !== '') {
-        const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
-        if (node_fs_1.default.existsSync(viteCacheDir)) {
-            (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');
-            try {
-                node_fs_1.default.rmSync(viteCacheDir, { recursive: true, force: true });
+        // 清掉 user app 的 node_modules —— migrate 改了 dependencies 集合（删 lite + 加 NestJS
+        // 全套）+ rule 已经把 package-lock.json 删了。如果 node_modules 留着，npm install 时旧
+        // 包还在 node_modules 顶层 hoist 树里，可能跟新 package.json spec 撞 peer 冲突
+        // （比如旧 coding-preset-vite-react@1.0.8 peer vite@^8 跟新 vite@^7 撞）。
+        //   - 用 purgeDirectory（rename 主档）而不是 fs.rmSync：dev server 没停成功时（老
+        //     code-server 没有 preview/stop 路由）vite 还在往 node_modules/.vite/deps 写，rm 走到
+        //     顶层 rmdir 必然 ENOTEMPTY，而 `maxRetries` 不 re-walk、救不了（沙箱实测数据见
+        //     purgeDirectory 注释）。同分区 rename 是原子的，一次就把旧树摘掉。
+        //   - 软失败：摘不掉也继续跑 npm install 让 npm 自己 reconcile —— 半迁移态
+        //     （package-lock 已删 + 新 deps 没装）比"清理不彻底"糟得多。
+        const nodeModulesPath = node_path_1.default.join(targetDir, 'node_modules');
+        if (node_fs_1.default.existsSync(nodeModulesPath)) {
+            (0, logger_1.log)('migrate', '清理 node_modules（dependencies 集合已变）...');
+            const purged = (0, file_ops_1.purgeDirectory)(nodeModulesPath);
+            nodeModulesPurgeStrategy = purged.strategy;
+            nodeModulesTrashLeftover = purged.trashLeftover;
+            if (!purged.purged) {
+                nodeModulesCleanError = purged.error;
+                (0, logger_1.log)('migrate', `⚠ 清理 node_modules 失败 (continuing): ${nodeModulesCleanError ?? ''}`);
+            }
+            else if (purged.trashLeftover !== undefined) {
+                (0, logger_1.log)('migrate', `⚠ node_modules 已移走但残留目录未删净: ${purged.trashLeftover}（不影响 install，需手动清）`);
+            }
+        }
+        // 跑 npm install 物化新依赖集合 + 把 followLatestPackages 钉 latest
+        // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
+        // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
+        // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
+        const installArgs = [
+            'install',
+            '--no-audit',
+            '--no-fund',
+            '--ignore-scripts',
+            '--registry',
+            (0, index_2.resolveNpmInstallRegistry)(),
+            ...followLatest.map((pkg) => `${pkg}@latest`),
+        ];
+        (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
+        try {
+            (0, node_child_process_1.execFileSync)('npm', installArgs, {
+                cwd: targetDir,
+                stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+            });
+        }
+        catch (err) {
+            installError = err instanceof Error ? err.message : String(err);
+            (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
+        }
+        // 重启 dev process 前清 vite cache —— migrate 改了 package.json + lockfile,
+        // 老 vite 进程的 .vite/deps cache 的 lockfileHash 跟新 lockfile 不一致。
+        // 不清的话拉起的新 vite cold start 会立即 "Re-optimizing because
+        // lockfile has changed", re-optimize 期间 ModuleGraph transform cache 跟
+        // deps middleware metadata 短暂不同步, 浏览器请求老 hash 触发
+        // ERR_OUTDATED_OPTIMIZED_DEP → 504 死锁(详见 fullstack-plugin#1143 的 504
+        // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
+        // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
+        //
+        //   - 只在 SANDBOX_ID 非空时做(本地一般不会撞这条链路)
+        //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
+        //   - 软失败:.vite 不存在 / 删失败都不阻断
+        if (installError === undefined &&
+            process.env.SANDBOX_ID !== undefined &&
+            process.env.SANDBOX_ID !== '') {
+            const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
+            if (node_fs_1.default.existsSync(viteCacheDir)) {
+                (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');
+                try {
+                    node_fs_1.default.rmSync(viteCacheDir, { recursive: true, force: true });
+                }
+                catch (err) {
+                    (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${err instanceof Error ? err.message : String(err)}`);
+                }
             }
-            catch (err) {
-                (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    finally {
+        // 恢复 dev server —— 只要暂停位可能已生效就必须调，且必须在 finally 里：
+        // rule 应用 / install / 清 cache 任何一步抛异常都不能把保活留在关闭状态，否则用户沙箱
+        // 的预览再也起不来（比迁移失败严重得多）。
+        // 无条件恢复（不看 installError）：dev 进程已经被停了，留着不起来只会更糟；新 scripts/dev.js
+        // + 新依赖也正是靠这次 start 生效。
+        // 用 previewMayBeSuspended 而非 previewStopped：stop 超时/500 时服务端暂停位已经置上了。
+        // 多余的 start 无害（服务端未暂停且进程在跑时 no-op）。
+        if (previewMayBeSuspended) {
+            (0, logger_1.log)('migrate', '恢复 dev server(预览)...');
+            const started = await (0, preview_control_1.startPreview)({ logPrefix: 'migrate' });
+            previewRestarted = started.ok;
+            if (!started.ok) {
+                previewRestartError = started.error;
+                (0, logger_1.log)('migrate', `✗ 恢复预览失败, 需人工处理: ${started.error ?? ''}`);
             }
         }
     }
-    // 沙箱环境下重启 dev process —— scripts/dev.js 被 fullstack 版本覆盖了,但当前正在
-    // 跑的 node 进程仍按老逻辑工作(只起 vite,没起 nest),整体没切到 fullstack 模式。
-    // 通过 pkill 杀掉 dev.js 主进程,依赖沙箱平台 supervisor 自动重新 exec dev.sh → dev.js,
-    // 新进程用新 deps + 新 scripts,正常进入 fullstack 模式。
+    // 降级路径：preview 接口不存在（老版本 code-server 返 404，确定没进暂停态），dev 进程还是
+    // 老的，按历史行为 pkill 掉 dev.js 主进程，靠平台 supervisor 自动重新 exec dev.sh → dev.js，
+    // 让新 deps + 新 scripts 生效。
     //   - 只在沙箱内做(isSandboxEnv;本地环境用户进程混杂,主动 pkill 风险大)
+    //   - previewMayBeSuspended 时不做 —— 新 code-server 上暂停位管着重建，pkill 无意义；
+    //     进程该由上面的 startPreview 拉起
     //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
     //     留着旧进程让用户先处理 installError
     //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
-    let devRestarted = false;
-    if (installError === undefined && (0, env_1.isSandboxEnv)()) {
+    let devRestarted = previewRestarted;
+    if (!previewMayBeSuspended && installError === undefined && (0, env_1.isSandboxEnv)()) {
         (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');
         try {
             (0, node_child_process_1.execFileSync)('pkill', ['-f', 'node.*scripts/dev\\.js'], { stdio: 'ignore' });
@@ -194,17 +259,35 @@ async function handleAppMigrate(opts) {
             ...summarizeResults(results),
             followLatestPackages: followLatest,
             installError,
+            nodeModulesCleanError,
+            nodeModulesPurgeStrategy,
+            nodeModulesTrashLeftover,
             devRestarted,
-            nextActions: (0, env_1.isSandboxEnv)()
-                ? [
-                    'git status / git diff 评估改动并 commit',
-                    'miaoda skills sync 同步到新 stack 的 agent skills',
-                ]
-                : [
-                    'git status / git diff 评估改动并 commit',
-                    '重启 dev 进程让新 scripts/dev.js + 新依赖生效:重跑 npm run dev(killOrphansByPort 会自动踢掉旧进程)',
-                    'miaoda skills sync 同步到新 stack 的 agent skills',
-                ],
+            previewStopped,
+            previewStopError,
+            previewMayBeSuspended,
+            previewRestarted,
+            previewRestartError,
+            nextActions: [
+                'git status / git diff 评估改动并 commit',
+                ...((0, env_1.isSandboxEnv)()
+                    ? []
+                    : [
+                        '重启 dev 进程让新 scripts/dev.js + 新依赖生效:重跑 npm run dev(killOrphansByPort 会自动踢掉旧进程)',
+                    ]),
+                'miaoda skills sync 同步到新 stack 的 agent skills',
+                // 预览恢复失败时补一条人工兜底动作 —— 暂停位还挂着，预览不会自己起来。
+                // 兜底自愈：暂停位只存 code-server 内存，重启 code-server 也能恢复。
+                ...(previewRestartError === undefined
+                    ? []
+                    : [
+                        `⚠ dev server(预览)未恢复成功，需手动 curl -X POST ${(0, preview_control_1.resolveCodeServerBaseUrl)()}/api/v1/preview/start 恢复保活（暂停状态只存内存，重启 code-server 亦可自愈）`,
+                    ]),
+                // node_modules 已 rename 摘掉但 trash 没删净：不影响 install，但会出现在 git status 里
+                ...(nodeModulesTrashLeftover === undefined
+                    ? []
+                    : [`⚠ 残留目录未清: rm -rf ${nodeModulesTrashLeftover}`]),
+            ],
         },
     });
 }

package/dist/utils/file-ops.js

@@ -8,6 +8,7 @@ exports.removeLineFromContent = removeLineFromContent;
 exports.unlockDirForWrite = unlockDirForWrite;
 exports.lockDirReadonly = lockDirReadonly;
 exports.forceRemove = forceRemove;
+exports.purgeDirectory = purgeDirectory;
 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"));
@@ -124,3 +125,85 @@ function forceRemove(target) {
     }
     node_fs_1.default.rmSync(target, { recursive: true, force: true });
 }
+/** {@link purgeDirectory} 移走目录时用的临时名前缀（相对父目录）。 */
+const PURGE_TRASH_PREFIX = '.miaoda-purge-';
+/**
+ * 删除一个**可能正在被其它进程写入**的目录（典型场景：dev server 活着时清 node_modules）。
+ *
+ * 主档是 `rename` 而不是 `rm`：同分区 rename 是原子的，不受目录内容变化影响，一次就把整棵
+ * 旧树从原路径摘掉；随后再删被移走的 trash（此时原路径已经腾空，删失败也不阻断调用方）。
+ *
+ * ⚠️ 不要改回 `fs.rmSync(..., { maxRetries })`。在沙箱内实测（Node v22）过四种组合：
+ *
+ * ```text
+ *   持续写入 + maxRetries:0            → ENOTEMPTY（241ms）
+ *   持续写入 + maxRetries:5/300ms      → ENOTEMPTY（4836ms，白等 5 轮）
+ *   0.5s 短写入 + maxRetries:5/300ms   → ENOTEMPTY（4747ms）   ← 关键反例
+ *   0.5s 短写入 + 外层重试整个 rmSync  → 成功（717ms）
+ *   持续写入 + shell rm -rf            → 失败
+ *   持续写入 + rename                  → 成功（122ms）
+ * ```
+ *
+ * 原因：`maxRetries` 只重试失败的那一次 `rmdir`，**不会重新 walk 目录**。删除过程中新写进来的
+ * 文件永远不会被 unlink，于是 rmdir 一直 ENOTEMPTY，重试纯属白等。只有重新走一遍（外层重试）
+ * 或干脆 rename 摘掉才有用。
+ *
+ * rename 失败（跨设备 EXDEV、父目录不可写 EPERM 等）时退回“外层重试整个 rmSync”。
+ *
+ * 注意：rename 之后原路径可能被仍在运行的写入方立刻重建（vite 会 `mkdir -p` 回
+ * `node_modules/.vite/deps`）。这不算失败 —— 旧依赖树已经不在原路径了，后续 `npm install`
+ * 能在干净状态上物化新依赖集合。
+ */
+function purgeDirectory(target, opts = {}) {
+    if (!node_fs_1.default.existsSync(target))
+        return { purged: true, strategy: 'absent' };
+    const parent = node_path_1.default.dirname(target);
+    const trash = node_path_1.default.join(parent, `${PURGE_TRASH_PREFIX}${node_path_1.default.basename(target)}-${String(process.pid)}`);
+    try {
+        node_fs_1.default.renameSync(target, trash);
+    }
+    catch (renameErr) {
+        (0, logger_1.debug)(`file-ops: rename ${target} failed: ${renameErr.message}`);
+        return rmSyncWithOuterRetry(target, opts);
+    }
+    try {
+        node_fs_1.default.rmSync(trash, { recursive: true, force: true });
+    }
+    catch (rmErr) {
+        (0, logger_1.debug)(`file-ops: rm trash ${trash} failed: ${rmErr.message}`);
+        return { purged: true, strategy: 'rename', trashLeftover: trash };
+    }
+    return { purged: true, strategy: 'rename' };
+}
+/**
+ * 重试整个 `fs.rmSync`（每次重新 walk 目录），而不是依赖 `maxRetries`（它不 re-walk，见
+ * {@link purgeDirectory} 的实测数据）。
+ */
+function rmSyncWithOuterRetry(target, opts) {
+    const attempts = opts.attempts ?? 4;
+    const delayMs = opts.retryDelayMs ?? 300;
+    let lastErr;
+    for (let i = 1; i <= attempts; i++) {
+        try {
+            node_fs_1.default.rmSync(target, { recursive: true, force: true });
+            return { purged: true, strategy: 'rmSync' };
+        }
+        catch (err) {
+            lastErr = err;
+            if (i < attempts)
+                sleepSync(delayMs);
+        }
+    }
+    return {
+        purged: false,
+        strategy: 'rmSync',
+        error: lastErr instanceof Error ? lastErr.message : String(lastErr),
+    };
+}
+/** 同步等待。这条链路整体是同步的（migrate 的清理阶段），不引入 async 传染。 */
+function sleepSync(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // busy wait —— 只在 rename 失败的兜底路径上跑，最多 3 次 300ms
+    }
+}

package/dist/utils/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pollUntilDone = exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.isSandboxEnv = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
+exports.pollUntilDone = exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.resolveCodeServerBaseUrl = exports.startPreview = exports.stopPreview = exports.isSandboxEnv = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
 var error_1 = require("./error");
 Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return error_1.AppError; } });
 Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return error_1.HttpError; } });
@@ -32,6 +32,10 @@ Object.defineProperty(exports, "postInnerApi", { enumerable: true, get: function
 Object.defineProperty(exports, "getInnerApi", { enumerable: true, get: function () { return http_1.getInnerApi; } });
 var env_1 = require("./env");
 Object.defineProperty(exports, "isSandboxEnv", { enumerable: true, get: function () { return env_1.isSandboxEnv; } });
+var preview_control_1 = require("./preview-control");
+Object.defineProperty(exports, "stopPreview", { enumerable: true, get: function () { return preview_control_1.stopPreview; } });
+Object.defineProperty(exports, "startPreview", { enumerable: true, get: function () { return preview_control_1.startPreview; } });
+Object.defineProperty(exports, "resolveCodeServerBaseUrl", { enumerable: true, get: function () { return preview_control_1.resolveCodeServerBaseUrl; } });
 var time_1 = require("./time");
 Object.defineProperty(exports, "parseTimeToMs", { enumerable: true, get: function () { return time_1.parseTimeToMs; } });
 Object.defineProperty(exports, "parseToMs", { enumerable: true, get: function () { return time_1.parseToMs; } });

package/dist/utils/preview-control.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCodeServerBaseUrl = resolveCodeServerBaseUrl;
+exports.stopPreview = stopPreview;
+exports.startPreview = startPreview;
+const logger_1 = require("../utils/logger");
+/**
+ * 沙箱内 dev server（预览）的显式启停控制。
+ *
+ * 沙箱里 dev server 的保活由 code-server 负责：直接 `pkill dev.js` 只会被保活立刻重新拉起，
+ * 拿不到"停住"这个状态。code-server 为此暴露了两个本地接口：
+ *
+ *   POST <base>/api/v1/preview/stop    停止预览（连带停掉保活）
+ *   POST <base>/api/v1/preview/start   启动预览（恢复保活）
+ *
+ * base 默认 `http://localhost:8080/code-server` —— migrate / sync 这类脚本本身就在沙箱内执行，
+ * 直连 localhost 即可，无需鉴权；`MIAODA_CODE_SERVER_BASE_URL` 可覆盖（本地联调 / 端口变更）。
+ *
+ * 典型用途：migrate 要重装依赖（`rm -rf node_modules` + `npm install`）。dev server 活着时
+ * vite 会持续往 `node_modules/.vite/deps` 写文件，`fs.rmSync` 自底向上删到顶层 `rmdir` 时目录
+ * 又变非空，直接 `ENOTEMPTY` 失败。先 stop 再删才是干净的做法。
+ *
+ * 服务端语义（ide-vscode `src/vs/platform/force/node/preview/previewService.ts`）：
+ *   - stop 先置暂停位（`_suspended`），再等在途创建落地、shutdown 并等进程真正退出。
+ *     **返回成功即代表 dev 进程已死，调用方不需要自己 pkill。**
+ *   - 等退出有 10s 超时，超时按失败处理（HTTP 500）。所以本地超时必须 > 10s，否则会抢在
+ *     服务端给出结论前 abort（见 STOP_TIMEOUT_MS）。
+ *   - ⚠️ 暂停位在 `_doStop()` 第一行就置上，**在抛错之前**。所以 stop 失败 ≠ 没进暂停态：
+ *     除了 404（路由不存在，必然无副作用）以外的任何失败，都必须当成"可能已暂停"去恢复，
+ *     否则保活被永久关掉。见 {@link PreviewControlResult.mayBeSuspended}。
+ *   - 暂停位只存内存，不持久化：code-server 重启会丢状态并重新拉起预览（兜底自愈路径）。
+ *   - start 在已运行时是 no-op；设计态沙箱（miaoda_design）本就不启动预览，start 也是 no-op。
+ *
+ * ⚠️ 调用契约：**只要 stop 可能已经生效就必须保证 start 被调到**（调用方放 `finally`，并按
+ * `mayBeSuspended` 判断）。漏掉 start 会让用户沙箱的预览再也起不来 —— 比迁移失败严重得多。
+ *
+ * 全部 API 都是软失败语义：不抛异常，失败信息放在返回值的 `error` 上，由调用方决定降级路径
+ * （老版本 code-server 没有这两个接口，会返回 404）。
+ */
+const DEFAULT_CODE_SERVER_BASE_URL = 'http://localhost:8080/code-server';
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * stop 的本地超时。必须大于服务端等进程退出的 10s（STOP_TIMEOUT）—— 否则我们会先 abort，
+ * 拿到一个"网络超时"，而服务端那边照样置着暂停位并继续走完流程。
+ */
+const STOP_TIMEOUT_MS = 20_000;
+/** start 是恢复动作，值得多试几次；stop 失败由调用方分类处理，不在这里重试 */
+const START_ATTEMPTS = 3;
+const START_RETRY_DELAY_MS = 500;
+/** code-server 本地基址，去掉尾部斜杠。`MIAODA_CODE_SERVER_BASE_URL` > 默认 localhost:8080。 */
+function resolveCodeServerBaseUrl() {
+    const fromEnv = process.env.MIAODA_CODE_SERVER_BASE_URL;
+    const base = fromEnv !== undefined && fromEnv !== '' ? fromEnv : DEFAULT_CODE_SERVER_BASE_URL;
+    return base.replace(/\/+$/, '');
+}
+/**
+ * 停止预览（dev 进程 + 保活）。返回 `ok` 时进程已确认退出，无需再 pkill。
+ *
+ * 软失败：不抛异常。失败时务必看 `mayBeSuspended` —— 为 true 就必须调 {@link startPreview} 恢复。
+ */
+async function stopPreview(opts = {}) {
+    const res = await postPreview('stop', 1, {
+        ...opts,
+        timeoutMs: opts.timeoutMs ?? STOP_TIMEOUT_MS,
+    });
+    // 404 = 路由不存在（老 code-server），确定没有副作用；其余失败保守认为暂停位可能已置上
+    return { ...res, mayBeSuspended: res.ok || res.status !== 404 };
+}
+/** 启动预览（解除暂停 + 拉起进程）。软失败：不抛异常；内部带重试，因为这是恢复动作。 */
+async function startPreview(opts = {}) {
+    return postPreview('start', START_ATTEMPTS, opts);
+}
+async function postPreview(action, attempts, opts) {
+    const url = `${resolveCodeServerBaseUrl()}/api/v1/preview/${action}`;
+    const logPrefix = opts.logPrefix ?? 'preview';
+    let last = {
+        ok: false,
+        url,
+        error: 'no attempt made',
+        mayBeSuspended: false,
+    };
+    for (let i = 1; i <= attempts; i++) {
+        last = await postOnce(url, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        if (last.ok)
+            return last;
+        if (i < attempts) {
+            (0, logger_1.log)(logPrefix, `⚠ preview ${action} 失败(第 ${String(i)}/${String(attempts)} 次), 重试: ${last.error ?? ''}`);
+            await sleep(START_RETRY_DELAY_MS);
+        }
+    }
+    return last;
+}
+async function postOnce(url, timeoutMs) {
+    try {
+        // 带空 JSON body —— 这两个接口不需要参数，但显式给 content-type 可以避免服务端框架对
+        // 无 body POST 的处理差异。
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: '{}',
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            const detail = await readBodySafe(res);
+            return {
+                ok: false,
+                url,
+                status: res.status,
+                error: `POST ${url} → ${String(res.status)} ${res.statusText}${detail}`,
+                mayBeSuspended: false,
+            };
+        }
+        return { ok: true, url, status: res.status, mayBeSuspended: false };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            url,
+            error: `POST ${url} failed: ${err instanceof Error ? err.message : String(err)}`,
+            mayBeSuspended: false,
+        };
+    }
+}
+async function readBodySafe(res) {
+    try {
+        const text = await res.text();
+        if (!text)
+            return '';
+        return ` ${text.length > 300 ? `${text.slice(0, 300)}...` : text}`;
+    }
+    catch {
+        return '';
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/utils/sandbox-skills.js

@@ -128,7 +128,16 @@ function syncSandboxSkills(opts) {
         (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';
+    // 版本优先级：lane（TCC 显式定向）> BOE 默认 @dev > @latest
+    //
+    // `dev` 通道由 miaoda-coding 的 publish-sandbox-skills-dev.sh 在 develop 分支自动发布
+    // （`<base>-dev.<sha>` + dist-tag `dev`），口径与 coding-steering 完全一致 ——
+    // 后者在本仓 coding-steering 侧也是 `FORCE_FRAMEWORK_ENVIRONMENT=boe` 时默认取 `dev`。
+    //
+    // lane 必须压过 dev：TCC 里配了 tgz-key 就说明是定向灰度（钉某个 feat 分支的快照），
+    // 不能被"BOE 就跟 develop"这条默认规则覆盖掉。
+    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
+    const primaryVersion = laneVersion ?? (isBoe ? 'dev' : 'latest');
     try {
         (0, logger_1.debug)(`sandbox-skills: fetching ${packageName}@${primaryVersion}`);
         fetched = (0, npm_pack_1.fetchNpmPackage)({
@@ -138,6 +147,9 @@ function syncSandboxSkills(opts) {
         });
     }
     catch (err) {
+        // @latest 是最后一档，它再挂就没得降了，直接抛。
+        // lane / dev 拉失败都降到 @latest：dev 通道可能因为 develop 还没发过包而不存在
+        // （dist-tag 缺失 → npm pack 404），这时候不该让整条 sync 挂掉。
         if (primaryVersion === 'latest') {
             throw err;
         }

package/package.json

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