@lark-apaas/miaoda-cli 0.1.33-alpha.e318de2 → 0.1.33-beta.b418cfe

package/dist/cli/commands/deploy/modern.js

@@ -72,7 +72,7 @@ JSON 输出（stdout）
     }));
     const patchCmd = deployCmd
         .command('patch')
-        .description('design-html 增量发布：按文件 create/update/delete，.html 增删时同步 routes.json')
+        .description('design-html 增量发布：按文件 create/update/delete，.html 变动时同步 routes.json')
         .option('--create <relpath>', '新增文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--update <relpath>', '覆盖已有文件（可重复）', shared_1.collectRepeatedOption, [])
         .option('--delete <relpath>', '删除文件（可重复）', shared_1.collectRepeatedOption, [])
@@ -80,10 +80,11 @@ JSON 输出（stdout）
         .addHelpText('after', `
 --dir 为项目目录（与 deploy 同名参数，默认当前目录）。
 仅支持 design-html（design_local_deploy）。路径为工程根相对路径（= 服务端 latest 下 key），
-禁绝对路径与 ".."。--create/--update 的本地文件必须存在。.html 被新增/删除（路由集合变化）
-时自动重算并随包更新 routes.json；纯 --update 现有 .html 只改内容，不动 routes.json。
-routes.json 每项为 {path, file}：path 为相对路径（不含 base 前缀，由消费侧拼接），file 为
-对应源文件（如 / → index.html）。
+禁绝对路径与 ".."。--create/--update 的本地文件必须存在。改动里含任意 .html（增 / 改 / 删）
+时自动重算并随包更新 routes.json；纯非 .html 改动不动 routes.json。
+routes.json 每项为 {path, file, name?}：path 为相对路径（不含 base 前缀，由消费侧拼接），
+file 为对应源文件（如 / → index.html），name 为该 HTML 的 <title> 文本（方案名，可缺省，
+缺省时由消费侧 fallback 到 path）。
 
 JSON 输出
   {"data": {"upsertCount": <n>, "deleteCount": <n>, "actionsSent": <n>, "routesRegenerated": <bool>}}

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

@@ -15,7 +15,6 @@ 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>]
@@ -100,139 +99,78 @@ async function handleAppMigrate(opts) {
     // 的 miaodaTemplate.archType 拿到的动态值，rule 配置时不知道，由 handler 在拿到
     // renderTemplate 结果后单独写。version 也一并写回方便 sync 后续诊断。
     (0, spark_meta_1.writeSparkMeta)(targetDir, { archType: templateArchType, version: templateVersion });
-    // 沙箱环境下先停掉 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 ?? ''}`);
-        }
+    // 清掉 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 });
     }
+    // 跑 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 previewRestarted = false;
-    let previewRestartError;
     try {
-        // 清掉 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 撞）。
-        //   - maxRetries：force 只吞 ENOENT，不管 ENOTEMPTY/EBUSY；这类错误 node 只在
-        //     maxRetries>0 时才重试。停预览失败降级时靠它兜住残余写入。
-        //   - 软失败：删不干净也继续跑 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 集合已变）...');
+        (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(nodeModulesPath, {
-                    recursive: true,
-                    force: true,
-                    maxRetries: 5,
-                    retryDelay: 300,
-                });
+                node_fs_1.default.rmSync(viteCacheDir, { recursive: true, force: true });
             }
             catch (err) {
-                nodeModulesCleanError = err instanceof Error ? err.message : String(err);
-                (0, logger_1.log)('migrate', `⚠ 清理 node_modules 失败 (continuing): ${nodeModulesCleanError}`);
-            }
-        }
-        // 跑 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)}`);
-                }
-            }
-        }
-    }
-    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 ?? ''}`);
+                (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${err instanceof Error ? err.message : String(err)}`);
             }
         }
     }
-    // 降级路径：preview 接口不存在（老版本 code-server 返 404，确定没进暂停态），dev 进程还是
-    // 老的，按历史行为 pkill 掉 dev.js 主进程，靠平台 supervisor 自动重新 exec dev.sh → dev.js，
-    // 让新 deps + 新 scripts 生效。
+    // 沙箱环境下重启 dev process —— scripts/dev.js 被 fullstack 版本覆盖了,但当前正在
+    // 跑的 node 进程仍按老逻辑工作(只起 vite,没起 nest),整体没切到 fullstack 模式。
+    // 通过 pkill 杀掉 dev.js 主进程,依赖沙箱平台 supervisor 自动重新 exec dev.sh → dev.js,
+    // 新进程用新 deps + 新 scripts,正常进入 fullstack 模式。
     //   - 只在沙箱内做(isSandboxEnv;本地环境用户进程混杂,主动 pkill 风险大)
-    //   - previewMayBeSuspended 时不做 —— 新 code-server 上暂停位管着重建，pkill 无意义；
-    //     进程该由上面的 startPreview 拉起
     //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
     //     留着旧进程让用户先处理 installError
     //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
-    let devRestarted = previewRestarted;
-    if (!previewMayBeSuspended && installError === undefined && (0, env_1.isSandboxEnv)()) {
+    let devRestarted = false;
+    if (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' });
@@ -256,24 +194,11 @@ async function handleAppMigrate(opts) {
             ...summarizeResults(results),
             followLatestPackages: followLatest,
             installError,
-            nodeModulesCleanError,
             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 恢复保活（暂停状态只存内存，重启 code-server 亦可自愈）`,
-                        ]),
                 ]
                 : [
                     'git status / git diff 评估改动并 commit',

package/dist/services/deploy/modern/patch/actions.js

@@ -36,8 +36,10 @@ function isHtml(rel) {
 /**
  * 把 changeset 组成 TosFileAction[]：
  *   - create/update 读本地文件、自动编码；delete 仅 FilePath。
- *   - .html 被 create / delete（路由集合变化）时，追加重算 routes.json 的 UPDATE action；
- *     纯 update 现有 .html 只改内容、不改路由集合，不重算 routes.json。
+ *   - 任一 .html 被 create / update / delete 时，追加重算 routes.json 的 UPDATE action。
+ *     update 也算：routes.json 的 name 取自 HTML 的 `<title>`，改方案名就是一次纯 update，
+ *     只按 create/delete 判定会让改名永远进不了 routes.json。
+ *   - 纯非 .html 改动（js / css / 图片）不动 routes.json。
  */
 function buildTosActions(projectDir, cs) {
     const actions = [];
@@ -48,8 +50,8 @@ function buildTosActions(projectDir, cs) {
     for (const rel of cs.deletes) {
         actions.push({ actionType: index_1.TosActionType.DELETE, filePath: normalizeRel(rel) });
     }
-    const routeSetChanged = [...cs.creates, ...cs.deletes].some(isHtml);
-    if (routeSetChanged) {
+    const routesMayChange = [...cs.creates, ...cs.updates, ...cs.deletes].some(isHtml);
+    if (routesMayChange) {
         actions.push({
             actionType: index_1.TosActionType.UPDATE,
             filePath: 'routes.json',

package/dist/services/deploy/modern/patch/html-title.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTitle = extractTitle;
+const node_fs_1 = __importDefault(require("node:fs"));
+/**
+ * 读 `<title>` 时的扫描窗口上限（字节）。title 规范上在 `<head>` 里、正常紧贴文档开头，
+ * 64KB 足以覆盖 head 里塞了内联 style / script 的情况，同时给大 HTML 兜住 IO 上限
+ * （generateRoutes 会遍历工程内所有 .html，不能整文件读）。
+ */
+const HEAD_SCAN_BYTES = 64 * 1024;
+const TITLE_RE = /<title[^>]*>([^<]*)<\/title>/i;
+const HEAD_CLOSE_RE = /<\/head\s*>/i;
+const COMMENT_RE = /<!--[\s\S]*?-->/g;
+const ENTITY_RE = /&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi;
+/** HTML 里可能出现在 title 文本中的命名实体。未列出的原样保留，不做全量实体表。 */
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+/** 把 title 文本里的实体还原成明文——name 是给前端直接当文本渲染的，不该带 `&amp;`。 */
+function decodeEntities(s) {
+    return s.replace(ENTITY_RE, (matched, body) => {
+        if (!body.startsWith('#')) {
+            return NAMED_ENTITIES[body.toLowerCase()] ?? matched;
+        }
+        const code = /^#x/i.test(body) ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+        if (!Number.isInteger(code) || code <= 0 || code > 0x10ffff)
+            return matched;
+        return String.fromCodePoint(code);
+    });
+}
+/** 只读文件头部 HEAD_SCAN_BYTES 字节。尾部可能截断多字节字符，对 title 提取无影响。 */
+function readHead(absPath) {
+    const fd = node_fs_1.default.openSync(absPath, 'r');
+    try {
+        const buf = Buffer.alloc(HEAD_SCAN_BYTES);
+        const bytes = node_fs_1.default.readSync(fd, buf, 0, HEAD_SCAN_BYTES, 0);
+        return buf.subarray(0, bytes).toString('utf-8');
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+/**
+ * 取 HTML 的 `<title>` 文本作为该页面的方案名。
+ *
+ * - 扫描范围截到第一个 `</head>`：body 里的 `<title>` 不算——内联 SVG 图标的 a11y
+ *   `<title>` 很常见，抓到就会把图标描述当成方案名。找不到 `</head>` 时退回整个窗口。
+ * - 先剔 HTML 注释，避免抓到被注释掉的 title。
+ * - 实体还原 + 空白折叠 + trim；空 title / 无 title / 读失败一律返回 undefined，
+ *   由消费侧 fallback 到 path（旧应用没有 title 时保持显示页面地址）。
+ */
+function extractTitle(absPath) {
+    let head;
+    try {
+        head = readHead(absPath);
+    }
+    catch {
+        return undefined;
+    }
+    const headClose = HEAD_CLOSE_RE.exec(head)?.index ?? -1;
+    const scope = (headClose >= 0 ? head.slice(0, headClose) : head).replace(COMMENT_RE, '');
+    const raw = TITLE_RE.exec(scope)?.[1];
+    if (raw === undefined)
+        return undefined;
+    const text = decodeEntities(raw).replace(/\s+/g, ' ').trim();
+    return text === '' ? undefined : text;
+}

package/dist/services/deploy/modern/patch/index.js

@@ -11,7 +11,7 @@ const actions_1 = require("./actions");
 var actions_2 = require("./actions");
 Object.defineProperty(exports, "buildTosActions", { enumerable: true, get: function () { return actions_2.buildTosActions; } });
 /**
- * design-html 增量发布：读本地文件组 TosFileAction（create/delete .html 时带重算的
+ * design-html 增量发布：读本地文件组 TosFileAction（改动含 .html 时带重算的
  * routes.json），调后端 applyTosDiff 应用到 latest。scope 限 design_local_deploy。
  */
 async function patchDesignDeploy(opts) {

package/dist/services/deploy/modern/patch/routes.js

@@ -1,6 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateRoutes = generateRoutes;
+const node_path_1 = __importDefault(require("node:path"));
+const html_title_1 = require("./html-title");
 const source_scan_1 = require("./source-scan");
 /**
  * .html → route path 推导（相对路径，不带 base 前缀）。rel 为 posix 相对路径。
@@ -16,8 +21,9 @@ function toRoute(rel) {
 }
 /**
  * 扫描 projectDir 下所有 .html（套 source-scan 的 EXCLUDES），生成 routes.json 文本（含尾换行）。
- * 每项为 { path, file }：path 为相对路径（不带 CLIENT_BASE_PATH 前缀，由消费侧拼接），
- * file 为该路由对应的原始 .html 源文件。按 path 排序、同 path 取字典序靠前的 file 去重。
+ * 每项为 { path, file, name? }：path 为相对路径（不带 CLIENT_BASE_PATH 前缀，由消费侧拼接），
+ * file 为该路由对应的原始 .html 源文件，name 为该文件 `<title>` 解析出的方案名（可缺省）。
+ * 按 path 排序、同 path 取字典序靠前的 file 去重。
  * 零 html 时输出空数组——不伪造解析不到文件的根路由。
  */
 function generateRoutes(projectDir) {
@@ -27,7 +33,11 @@ function generateRoutes(projectDir) {
         if (!byPath.has(entry.path))
             byPath.set(entry.path, entry);
     }
-    const routes = [...byPath.values()];
+    // title 只读去重后胜出的 file：同 path 多源（foo.html / foo/index.html）时不做无用 IO。
+    const routes = [...byPath.values()].map((entry) => {
+        const name = (0, html_title_1.extractTitle)(node_path_1.default.join(projectDir, entry.file));
+        return name === undefined ? entry : { ...entry, name };
+    });
     return JSON.stringify(routes, null, 2) + '\n';
 }
 function byPathThenFile(a, b) {

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.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;
+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;
 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,10 +32,6 @@ 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/package.json

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

package/dist/utils/preview-control.js

@@ -1,139 +0,0 @@
-"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);
-    });
-}