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

package/dist/services/app/export-standalone/naming.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extFromContentType = extFromContentType;
+exports.localImageName = localImageName;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * `Content-Type` → 文件扩展名。
+ *
+ * 存储 key 常常**不带扩展名**（线上真实形态 `static%2Fdemo_ve_miaoda`），
+ * URL 里推不出类型，只能以服务端响应为准。
+ * 未知类型返回空串 —— 宁可没后缀，也不猜一个错的（错后缀会让浏览器按错误类型解析）。
+ */
+const EXT_BY_MIME = {
+    'image/png': '.png',
+    'image/jpeg': '.jpg',
+    'image/jpg': '.jpg',
+    'image/gif': '.gif',
+    'image/webp': '.webp',
+    'image/svg+xml': '.svg',
+    'image/avif': '.avif',
+    'image/bmp': '.bmp',
+    'image/x-icon': '.ico',
+    'image/vnd.microsoft.icon': '.ico',
+    'image/tiff': '.tiff',
+};
+function extFromContentType(contentType) {
+    if (!contentType)
+        return '';
+    const mime = contentType.split(';')[0].trim().toLowerCase();
+    return EXT_BY_MIME[mime] ?? '';
+}
+/** 只保留文件名安全字符；其余折成 `_`。顺带挡掉 `/` 与 `..`（防 basename 逃出 images/）。 */
+function sanitize(name) {
+    return name.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+}
+/**
+ * URL → `images/` 下的本地文件名。
+ *
+ * 规则：
+ *   1. 剥掉 query/hash 后取 pathname
+ *   2. `decodeURIComponent` 还原（key 常被编码，如 `static%2Fx` → `static/x`）
+ *   3. 取 basename 并清洗危险字符
+ *   4. 追加 **完整 URL（含 query）** 的 8 位 hash —— 保证：
+ *        - 同 URL 幂等（重跑导出不产生新文件）
+ *        - 不同路径同名不互撞
+ *        - 同图不同 `x-tos-process` 参数分开存（处理后的图内容不同）
+ *   5. 扩展名取自 `Content-Type`，URL 里自带的后缀不作数（服务端才是真相）
+ */
+function localImageName(url, contentType) {
+    const pathname = url.split('#')[0].split('?')[0];
+    let decoded = pathname;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        // 畸形 % 转义：退回原串，不抛
+    }
+    const rawBase = decoded.split('/').filter(Boolean).pop() ?? '';
+    const base = sanitize(rawBase).replace(/\.[^.]*$/, '') || 'image';
+    const hash = node_crypto_1.default.createHash('sha1').update(url).digest('hex').slice(0, 8);
+    return `${base}-${hash}${extFromContentType(contentType)}`;
+}

package/dist/services/app/export-standalone/rewrite.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_EXTENSIONS = void 0;
+exports.rewriteTree = rewriteTree;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 需要扫描并改写的文本文件扩展名。
+ * 只列产物里真会出现 URL 的类型 —— `images/` 下的二进制不在其中，
+ * 避免把 PNG 当 UTF-8 读进来再写回去（会损坏文件）。
+ */
+exports.TEXT_EXTENSIONS = new Set([
+    '.html',
+    '.htm',
+    '.css',
+    '.js',
+    '.mjs',
+    '.cjs',
+    // buildless 栈（design-html / html）的源文件**就是产物**，JSX/TS 里的图片
+    // URL 同样要扫要改。漏了这几个扩展名会导致图片下载成功、但 .jsx 里的引用
+    // 仍指向线上绝对路径 —— 真机踩过（app.jsx 里 5 处未改写）。
+    '.jsx',
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.json',
+    '.svg',
+    '.webmanifest',
+]);
+function* walk(dir, rel = '') {
+    for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+        const abs = node_path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* walk(abs, childRel);
+        else
+            yield childRel;
+    }
+}
+/**
+ * 把产物树里所有命中的 URL 改写成 `./images/<name>`。
+ *
+ * **只改写 mapping 里有的 URL** —— 下载失败的原样保留。改成 `./images/xxx` 但文件不存在
+ * 反而制造死链，保留原绝对路径至少在联网访问平台时还能显示。
+ *
+ * 替换顺序按 URL **长度降序**：`/a/k.png` 是 `/a/k.png?x=1` 的前缀，若先替短的，
+ * 长 URL 会被替成 `./images/short.png?x=1` 这种半截产物。
+ *
+ * 用 `split().join()` 而非 `replace(new RegExp(...))`：URL 里含 `?`、`.`、`+`、`$` 等
+ * 正则元字符，转义容易出错；且 `$&` / `$1` 之类替换串语义也是坑。
+ *
+ * 返回实际发生改动的文件相对路径（posix 风格），用于 JSON 输出的 `rewrittenFiles`。
+ */
+function rewriteTree(root, mapping) {
+    if (mapping.size === 0)
+        return [];
+    const entries = [...mapping.entries()].sort((a, b) => b[0].length - a[0].length);
+    const changed = [];
+    for (const rel of walk(root)) {
+        if (!exports.TEXT_EXTENSIONS.has(node_path_1.default.extname(rel).toLowerCase()))
+            continue;
+        const abs = node_path_1.default.join(root, rel);
+        const original = node_fs_1.default.readFileSync(abs, 'utf-8');
+        let next = original;
+        for (const [url, name] of entries) {
+            if (!next.includes(url))
+                continue;
+            next = next.split(url).join(`./images/${name}`);
+        }
+        if (next !== original) {
+            node_fs_1.default.writeFileSync(abs, next, 'utf-8');
+            changed.push(rel);
+        }
+    }
+    return changed.sort();
+}

package/dist/services/app/export-standalone/scan.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * 从构建产物文本里扫出需要本地化的应用存储图片 URL。
+ *
+ * 匹配口径：**只认字面以 `/spark/app/` 开头的同源相对路径**。
+ *
+ * ⚠️ 这是刻意收窄的口径，会漏判其它挂载前缀（`/spark/p/`、`/spark/r/`、`/app/<appId>`、
+ * 反代场景等）。`miaoda-coding` 的 `cd-elements/src/core/tos.ts` 走的是「存储路径中段
+ * 子串匹配」，注释里明确记着「改成前缀匹配会让存储图静默跳过，这个错误犯过一次」。
+ * 本能力**明知该历史仍选择前缀匹配**（决策见设计文档「图片本地化」）。
+ * 若将来要扩范围，正确做法是**切子串匹配**，不是追加枚举前缀。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanSparkAppUrls = scanSparkAppUrls;
+/**
+ * URL 终止字符：引号、反引号、空白、尖括号、圆括号、反斜杠。
+ * 刻意**不含逗号** —— `?x-tos-process=image/resize,w_400` 里逗号是 URL 的一部分，
+ * 排除它会把 query 截断成无效地址。
+ *
+ * 代价：`srcset="a.png 1x,b.png 2x"` 这种逗号后无空格的写法会把两个 URL 粘成一个。
+ * 实际产物里 srcset 由 cd-elements 生成，逗号后带空格，不触发。
+ */
+const SPARK_APP_URL_RE = /\/spark\/app\/[^"'`\s<>()\\]+/g;
+/**
+ * URL 前必须是「token 起始位置」——字符串开头，或前一个字符是分隔符。
+ *
+ * 这条是为了排掉第三方绝对 URL：`https://example.com/spark/app/a/k.png` 里
+ * `/spark/app/` 的前一个字符是 `m`（`.com` 的 m），不是分隔符，因此不命中。
+ *
+ * ⚠️ 不能写成「前一个字符不是 `/`」—— 那个判据对绝对 URL 无效（prev 是 `m` 不是 `/`），
+ * 会把第三方地址误判成同源相对路径。
+ */
+const BOUNDARY_CHARS = new Set([
+    '"',
+    "'",
+    '`',
+    ' ',
+    '\t',
+    '\n',
+    '\r',
+    '(',
+    '=',
+    ',',
+    ';',
+    ':',
+    '{',
+    '[',
+    '<',
+    '>',
+]);
+function isSameOriginRelative(text, index) {
+    if (index === 0)
+        return true;
+    return BOUNDARY_CHARS.has(text[index - 1]);
+}
+/**
+ * 扫出去重后的 URL 列表，保持首次出现的顺序（便于测试断言与日志可读）。
+ */
+function scanSparkAppUrls(text) {
+    const seen = new Set();
+    const out = [];
+    for (const m of text.matchAll(SPARK_APP_URL_RE)) {
+        if (!isSameOriginRelative(text, m.index))
+            continue;
+        const url = m[0];
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        out.push(url);
+    }
+    return out;
+}

package/dist/services/app/export-standalone/strategies.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STANDALONE_SUPPORTED_STACKS = void 0;
+exports.buildStandaloneEnv = buildStandaloneEnv;
+exports.liftNestedEntry = liftNestedEntry;
+exports.resolveStrategy = resolveStrategy;
+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 error_1 = require("../../../utils/error");
+const exclude_patterns_1 = require("../../../utils/exclude-patterns");
+const logger_1 = require("../../../utils/logger");
+const copy_tree_1 = require("./copy-tree");
+const inline_babel_1 = require("./inline-babel");
+exports.STANDALONE_SUPPORTED_STACKS = new Set([
+    'design-html',
+    'html',
+    'vite-react',
+    'nestjs-react-fullstack',
+]);
+/**
+ * standalone 构建 env。
+ *
+ * **不复用 `deploy/modern/atoms/build.ts` 的 `runBuild()`** —— 它的 `ensureHttpsScheme()`
+ * 会把 `'./'` 判成域名（含 `.` 且不以 `/` 开头）拼成 `https://./`，破掉 vite 的 base 替换。
+ *
+ * 删 `MIAODA_APP_ID` 是刻意的：`scripts/build.sh` 写的是
+ * `export CLIENT_BASE_PATH="${MIAODA_APP_ID:+/app/$MIAODA_APP_ID}"`，
+ * 变量为空时整个展开为空串，正好得到我们要的空 base path。
+ */
+function buildStandaloneEnv(base) {
+    const env = { ...base };
+    delete env.MIAODA_APP_ID;
+    delete env.CLIENT_BASE_PATH;
+    env.MIAODA_BUILD_TARGET = 'standalone';
+    env.NODE_ENV = 'production';
+    // vite-react 走 build.sh，由它把 MIAODA_RESOURCE_CDN_PREFIX 映射成 ASSETS_CDN_PATH
+    env.MIAODA_RESOURCE_CDN_PREFIX = './';
+    // nestjs 走 `npm run build:client` 直接调 vite，**没有 build.sh 那层映射** ——
+    // 必须直接给 preset 认的名字，否则 publicPath 为空 → base '/' → 产物里是
+    // `/assets/x.js` 绝对路径，file:// 下指向文件系统根，页面白屏（真机踩过）。
+    // vite-react 那边 build.sh 会用同样的值覆盖它，两条路结果一致。
+    env.ASSETS_CDN_PATH = './';
+    env.STATIC_ASSETS_BASE_URL = './static';
+    return env;
+}
+/** 把 `from` 目录内容并入 `into`（into 已存在，不清空）。from 不存在则静默跳过。 */
+function mergeInto(from, into) {
+    if (!node_fs_1.default.existsSync(from))
+        return;
+    node_fs_1.default.mkdirSync(into, { recursive: true });
+    node_fs_1.default.cpSync(from, into, { recursive: true });
+}
+/**
+ * 把 `<out>/client/index.html` 提到 `<out>/index.html`，并把资源引用降一级。
+ *
+ * **为什么会嵌一层**：vite 按 input 相对 root 的位置放产物 HTML。nestjs 模板的
+ * input 是 `client/index.html`、root 是项目根，所以 HTML 落在 `dist/client/client/`。
+ * 平台构建里 `vite-html-output` 插件负责把它提上来，但 standalone 下**刻意不挂**那个
+ * 插件——它的上移不修相对引用（平台模式 base 是绝对路径，不需要修）。
+ *
+ * **为什么必须同时改路径**：standalone 的 base 是 `./`，产物里写的是 `../assets/x`，
+ * 那是相对 `<out>/client/` 算的。提到 `<out>/` 后就多了一级，指向不存在的
+ * `<out>/../assets/`，页面白屏（实测确认）。层级差恒为 1，故 `../` → `./`。
+ *
+ * 只改 `src` / `href` 属性开头的 `../`，不做全文替换 —— 否则 inline 脚本里的字符串
+ * 常量（如 `var p = "../keep/me"`）会被误伤。
+ */
+function liftNestedEntry(outDir) {
+    const nestedDir = node_path_1.default.join(outDir, 'client');
+    const nestedHtml = node_path_1.default.join(nestedDir, 'index.html');
+    if (!node_fs_1.default.existsSync(nestedHtml))
+        return;
+    const target = node_path_1.default.join(outDir, 'index.html');
+    const html = node_fs_1.default.readFileSync(nestedHtml, 'utf-8');
+    const rebased = html.replace(/\b(src|href)=("|')\.\.\/(?!\.)/gi, (_m, attr, quote) => `${attr}=${quote}./`);
+    node_fs_1.default.writeFileSync(target, rebased, 'utf-8');
+    node_fs_1.default.rmSync(nestedHtml, { force: true });
+    // 只删空目录：嵌套目录里若还有别的文件，留着比静默丢弃安全
+    if (node_fs_1.default.readdirSync(nestedDir).length === 0)
+        node_fs_1.default.rmdirSync(nestedDir);
+}
+/**
+ * 从产物树里删掉 sourcemap（`*.map`）。
+ *
+ * preset 的 prod 配置是 `sourcemap: 'hidden'` —— map 文件会产出，但产物里**没有**
+ * `sourceMappingURL` 注释，即没人引用它。留在 standalone 包里有两个实打实的问题：
+ *
+ * 1. **体积**：实测真实应用 4.7MB map / 5.9MB 总体积，占 80%
+ * 2. **泄源码**：map 的 `sourcesContent` 内嵌原始源码（实测含 12 个业务文件，
+ *    如 `src/lib/utils.ts`）。standalone 包是拿来分发给人的，等于附赠全部源码
+ *
+ * 只对有编译步骤的 stack 调用；buildless 栈（design-html / html）的产物就是源码，
+ * 那里的 `.map`（若有）是用户自己的文件，不该动。
+ */
+function dropSourceMaps(outDir) {
+    const walk = (dir) => {
+        for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+            const abs = node_path_1.default.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(abs);
+            else if (entry.name.toLowerCase().endsWith('.map'))
+                node_fs_1.default.rmSync(abs, { force: true });
+        }
+    };
+    walk(outDir);
+}
+/** 从产物树里删掉 routes.json —— 平台/server 路由用，standalone 无人读取。 */
+function dropRoutesJson(outDir) {
+    node_fs_1.default.rmSync(node_path_1.default.join(outDir, 'routes.json'), { force: true });
+}
+function runProjectBuild(projectDir, command) {
+    try {
+        (0, node_child_process_1.execSync)(command, {
+            cwd: projectDir,
+            stdio: 'inherit',
+            env: buildStandaloneEnv(process.env),
+        });
+    }
+    catch (err) {
+        throw new error_1.AppError('EXPORT_STANDALONE_BUILD_FAILED', `${command} failed: ${err.message}`, { next_actions: ['先手动跑一次该构建命令确认工程本身可构建'] });
+    }
+}
+/** design-html：项目根纯拷贝，套 deploy 同一份 EXCLUDES。 */
+const designHtmlStrategy = ({ projectDir, outDir }) => {
+    (0, logger_1.log)('export-standalone', 'Copying source (design-html)...');
+    (0, copy_tree_1.copyTree)(projectDir, outDir, exclude_patterns_1.EXCLUDES);
+    (0, inline_babel_1.inlineBabelScripts)(outDir);
+    dropRoutesJson(outDir);
+};
+/**
+ * html：拷 `src/`，**跳过 `coding-html-devserver build`**。
+ * 该命令会注入 slardar/tea 外链与 `{{appName}}` HBS 占位符，standalone 全要撤销，
+ * 调它再逐项撤销不如不调（设计文档「html 跳过 coding-html-devserver build」）。
+ */
+const htmlStrategy = ({ projectDir, outDir }) => {
+    (0, logger_1.log)('export-standalone', 'Copying src/ (html)...');
+    (0, copy_tree_1.copyTree)(node_path_1.default.join(projectDir, 'src'), outDir);
+    (0, inline_babel_1.inlineBabelScripts)(outDir);
+    dropRoutesJson(outDir);
+};
+/**
+ * vite-react：跑 `scripts/build.sh`，再把按上传通道拆的四个目录按可访问性合并。
+ * `output_capabilities` 丢弃 —— 平台侧注册用，运行时走已打进 bundle 的
+ * `virtual:capabilities` 虚拟模块，产物目录不引用它。
+ */
+const viteReactStrategy = ({ projectDir, outDir }) => {
+    (0, logger_1.log)('export-standalone', 'Building (vite-react)...');
+    runProjectBuild(projectDir, 'bash scripts/build.sh');
+    const dist = node_path_1.default.join(projectDir, 'dist');
+    node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
+    node_fs_1.default.mkdirSync(outDir, { recursive: true });
+    mergeInto(node_path_1.default.join(dist, 'output'), outDir);
+    mergeInto(node_path_1.default.join(dist, 'output_resource', 'assets'), node_path_1.default.join(outDir, 'assets'));
+    mergeInto(node_path_1.default.join(dist, 'output_static'), node_path_1.default.join(outDir, 'static'));
+    dropSourceMaps(outDir);
+    dropRoutesJson(outDir);
+};
+/**
+ * nestjs-react-fullstack：只跑 `build:client`。
+ * 完整 `scripts/build.sh` 会跑 `action-plugin init` / `gen:openapi` / `nest build` /
+ * `prune-smart`，standalone 只要 client 那一半；且 `action-plugin init` 依赖平台 env，
+ * 是已知易失败点。
+ *
+ * 产物是单目录 `dist/client`，无需合并；但入口 HTML 嵌在 `dist/client/client/` 下
+ * （standalone 不挂 preset 的 vite-html-output 插件），需 `liftNestedEntry` 提到根。
+ */
+const nestjsStrategy = ({ projectDir, outDir }) => {
+    (0, logger_1.log)('export-standalone', 'Building client (nestjs-react-fullstack)...');
+    // 构建到**独立临时目录**，不碰 `dist/client`。
+    //
+    // 两个原因：
+    // 1. preset 设了 `emptyOutDir: false`（它指望 `scripts/build.sh` 先 `rm -rf dist`），
+    //    而我们绕过 build.sh 直接跑 `build:client`，没人清目录 —— 复用 `dist/client`
+    //    会把上次构建的 chunk 一起带进产物（真机见过新旧两个 index-<hash>.js 并存）。
+    // 2. `dist/client` 是平台链路的产物目录（dev 期 html-output 会往里写、NestJS 从
+    //    那儿取 HTML），导出这种旁路动作**不该清它**，否则破坏既有目录结构。
+    //
+    // vite CLI 的 `--outDir` 优先级高于 config，`--emptyOutDir` 覆盖 `emptyOutDir: false`。
+    // 放在 dist/ 下是为了留在 vite root 内（root 外 vite 会告警）。
+    const tmpDist = node_path_1.default.join(projectDir, 'dist', '.standalone-client');
+    try {
+        runProjectBuild(projectDir, `npm run build:client -- --outDir ${JSON.stringify(node_path_1.default.relative(projectDir, tmpDist))} --emptyOutDir`);
+        if (!node_fs_1.default.existsSync(tmpDist)) {
+            throw new error_1.AppError('EXPORT_STANDALONE_EMPTY_OUTPUT', `client 构建产物 ${node_path_1.default.relative(projectDir, tmpDist)} 不存在`);
+        }
+        node_fs_1.default.rmSync(outDir, { recursive: true, force: true });
+        node_fs_1.default.mkdirSync(outDir, { recursive: true });
+        mergeInto(tmpDist, outDir);
+    }
+    finally {
+        // 临时构建目录不留在用户项目里
+        node_fs_1.default.rmSync(tmpDist, { recursive: true, force: true });
+    }
+    liftNestedEntry(outDir);
+    dropSourceMaps(outDir);
+    dropRoutesJson(outDir);
+};
+const STRATEGY_BY_STACK = new Map([
+    ['design-html', designHtmlStrategy],
+    ['html', htmlStrategy],
+    ['vite-react', viteReactStrategy],
+    ['nestjs-react-fullstack', nestjsStrategy],
+]);
+function resolveStrategy(stack) {
+    const strategy = STRATEGY_BY_STACK.get(stack);
+    if (!strategy) {
+        throw new error_1.AppError('EXPORT_STANDALONE_STACK_UNSUPPORTED', `stack "${stack}" 不支持 standalone 导出`, { next_actions: [`支持的 stack：${[...exports.STANDALONE_SUPPORTED_STACKS].join(', ')}`] });
+    }
+    return strategy;
+}

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/services/deploy/modern/patch/source-scan.js

@@ -7,45 +7,8 @@ exports.EXCLUDES = void 0;
 exports.listSourceFiles = listSourceFiles;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-// 与模板 scripts/build.sh 的 rsync EXCLUDES 对齐：这些名字（任意层级 basename）不进产物/不计入路由。
-exports.EXCLUDES = new Set([
-    '.git',
-    'node_modules',
-    'dist',
-    'scripts',
-    'package.json',
-    'package-lock.json',
-    'pnpm-lock.yaml',
-    'yarn.lock',
-    '.gitignore',
-    '.npmrc',
-    // agent / 编辑器配置目录与指令文件：只服务本地开发，不属于应用资产。
-    // 注意 .claude/skills 在 flat layout 下是指向 ../.agents/skills 的软链，而 listSourceFiles
-    // 会 follow 软链，所以必须按 basename 把 .claude 整个排掉，否则 skills 会从软链侧被带进产物。
-    '.agent',
-    '.agents',
-    '.claude',
-    '.codex',
-    '.cursor',
-    '.gemini',
-    '.trae',
-    '.windsurf',
-    '.vscode',
-    '.idea',
-    'AGENTS.md',
-    'CLAUDE.md',
-    'GEMINI.md',
-    'skills',
-    '.env',
-    '.env.local',
-    'README.md',
-    '.DS_Store',
-    '.spark',
-    // 本地开发的临时/运行时目录：tmp 里的 .html 是草稿或中间产物，logs 是本地日志，
-    // 两者既不进产物也不该出现在 routes.json。
-    'tmp',
-    'logs',
-]);
+const exclude_patterns_1 = require("../../../../utils/exclude-patterns");
+Object.defineProperty(exports, "EXCLUDES", { enumerable: true, get: function () { return exclude_patterns_1.EXCLUDES; } });
 /**
  * 递归列出 root 下所有文件的相对 posix 路径，跳过 EXCLUDES（任意层级 basename），
  * 用 statSync 判定目录/文件以 follow 符号链接（含指向目录的软链），断链等无法 stat 的条目跳过。
@@ -54,7 +17,7 @@ function listSourceFiles(root) {
     const out = [];
     const walk = (dir, rel) => {
         for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {
-            if (exports.EXCLUDES.has(entry.name))
+            if (exclude_patterns_1.EXCLUDES.has(entry.name))
                 continue;
             const childRel = rel ? `${rel}/${entry.name}` : entry.name;
             const abs = node_path_1.default.join(dir, entry.name);