@lark-apaas/miaoda-cli 0.1.33-alpha.59a1bf2 → 0.1.33-alpha.e318de2

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

@@ -103,19 +103,24 @@ async function handleAppMigrate(opts) {
     // 沙箱环境下先停掉 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 让保活拉起）
-    //   - ⚠️ stop 成功后必须恢复：下面整段包在 try/finally 里，任何异常路径都会走 startPreview
+    //   - ⚠️ 恢复条件用 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;
-            (0, logger_1.log)('migrate', `⚠ 停止预览失败 (continuing, 降级为不停 dev 直接重装): ${stopped.error ?? ''}`);
+            const tail = previewMayBeSuspended ? '结束时仍会尝试恢复' : '降级为不停 dev 直接重装';
+            (0, logger_1.log)('migrate', `⚠ 停止预览失败 (continuing, ${tail}): ${stopped.error ?? ''}`);
         }
     }
     const followLatest = config.followLatestPackages ?? [];
@@ -200,12 +205,14 @@ async function handleAppMigrate(opts) {
         }
     }
     finally {
-        // 恢复 dev server —— 只要上面 stop 成功过就必须调，且必须在 finally 里：
+        // 恢复 dev server —— 只要暂停位可能已生效就必须调，且必须在 finally 里：
         // rule 应用 / install / 清 cache 任何一步抛异常都不能把保活留在关闭状态，否则用户沙箱
         // 的预览再也起不来（比迁移失败严重得多）。
         // 无条件恢复（不看 installError）：dev 进程已经被停了，留着不起来只会更糟；新 scripts/dev.js
         // + 新依赖也正是靠这次 start 生效。
-        if (previewStopped) {
+        // 用 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;
@@ -215,15 +222,17 @@ async function handleAppMigrate(opts) {
             }
         }
     }
-    // 降级路径：preview stop 没成功（老版本 code-server / 接口连不上），dev 进程还是老的，
-    // 按历史行为 pkill 掉 dev.js 主进程，靠平台 supervisor 自动重新 exec dev.sh → dev.js，
+    // 降级路径：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 = previewRestarted;
-    if (!previewStopped && installError === undefined && (0, env_1.isSandboxEnv)()) {
+    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' });
@@ -251,17 +260,19 @@ async function handleAppMigrate(opts) {
             devRestarted,
             previewStopped,
             previewStopError,
+            previewMayBeSuspended,
             previewRestarted,
             previewRestartError,
             nextActions: (0, env_1.isSandboxEnv)()
                 ? [
                     'git status / git diff 评估改动并 commit',
                     '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 恢复保活`,
+                            `⚠ dev server(预览)未恢复成功，需手动 curl -X POST ${(0, preview_control_1.resolveCodeServerBaseUrl)()}/api/v1/preview/start 恢复保活（暂停状态只存内存，重启 code-server 亦可自愈）`,
                         ]),
                 ]
                 : [

package/dist/utils/preview-control.js

@@ -20,15 +20,31 @@ const logger_1 = require("../utils/logger");
  * vite 会持续往 `node_modules/.vite/deps` 写文件，`fs.rmSync` 自底向上删到顶层 `rmdir` 时目录
  * 又变非空，直接 `ENOTEMPTY` 失败。先 stop 再删才是干净的做法。
  *
- * ⚠️ 调用契约：**stop 成功后必须保证 start 被调到**（调用方放 `finally`）。保活被关掉后不会
- * 自愈，漏掉 start 会让用户沙箱的预览再也起不来 —— 比迁移失败严重得多。
+ * 服务端语义（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;
-/** start 是恢复动作，值得多试几次；stop 失败可以直接降级，不重试 */
+/**
+ * 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。 */
@@ -37,18 +53,32 @@ function resolveCodeServerBaseUrl() {
     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 = {}) {
-    return postPreview('stop', 1, 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' };
+    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)
@@ -77,15 +107,17 @@ async function postOnce(url, timeoutMs) {
                 url,
                 status: res.status,
                 error: `POST ${url} → ${String(res.status)} ${res.statusText}${detail}`,
+                mayBeSuspended: false,
             };
         }
-        return { ok: true, url, status: res.status };
+        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,
         };
     }
 }

package/package.json

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