@lark-apaas/miaoda-cli 0.1.39-alpha.73a593e → 0.1.39-alpha.ad15159

package/README.md

@@ -52,6 +52,16 @@ miaoda file ls --output json
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 全栈应用的 MCP UI 检查
+
+MCP UI 使用平台预设提供的浏览器检查默认值。`npm run lint` 和 `npm run type:check` 自动覆盖 `server/mcp/ui`，模板统一提供 UI 子命令与类型配置；`lint -- --files` 保留按文件选择检查范围。没有 UI 源码时跳过 UI 检查。
+
+应用增加 `type:check:mcp-ui` 子命令，与 `type:check:client`、`type:check:server` 一起由 `type:check` 聚合。`scripts/typecheck-mcp-ui.js` 只在 UI 源码存在时调用应用安装的 `tsc --noEmit --project tsconfig.mcp-ui.json`；无 UI 或目录为空时成功跳过。根目录 `tsconfig.mcp-ui.json` 提供浏览器、React JSX 和严格类型检查配置，可按应用需要修改；sync 仅在该文件不存在时创建。已有 `server/mcp/ui/tsconfig.json` 的应用优先沿用原配置，保留自定义 paths/types。
+
+UI ESLint 默认配置由平台预设提供，也可用根目录 `eslint.mcp-ui.config.js` / `.cjs` / `.mjs` 定制。`npm run lint` 包含 UI 检查；`--files` 按影响范围检查，shared 变更触发三个环境的类型检查。应用脚本不使用 `node -e` 或 TypeScript 编译器 API。
+
+存量 sync 不改写 ESLint 源码；UI 全局排除项由平台 ESLint 预设提供。TS 仅向已有显式 `exclude` 数组追加目录，保留注释和原项；依赖继承且未显式声明 `exclude` 的自定义配置保持不变并提示人工调整。自定义检查命令保留。lint.js 和 build.sh 仍由平台脚本模板维护，不依赖预设包中的脚本执行入口。
+
 ## 打包可本地访问的静态产物
 
 `miaoda app pack`（默认 `--mode standalone`）把当前应用构建成一份自包含静态产物，可脱离妙搭平台本地打开。

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

@@ -18,7 +18,14 @@ function registerDeployCommandsModern(program) {
         .option('--dir <path>', '项目目录', '.')
         .option('--skip-build', '跳过 build 步骤（已构建好时使用）', false)
         .option('--skip-release', '不创建/更新本地发布单，发布单状态由外部托管', false)
-        .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID 两字段')
+        .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID / sessionID / marker / versionLevel 五字段')
+        // 这三个 flag 只在父命令声明一份，deploy 与 deploy patch 共用。
+        // 不能在 patch 上再声明一遍：commander 遇到父子同名 option 会把值判给父命令，
+        // 子命令拿到空数组，`deploy patch --create x` 会静默失效（deploy-patch-wiring 测试可复现）。
+        // patch 从 deployCmd.opts() 读，与它今天读 --dir 的方式一致。
+        .option('--create <relpath>', '新增文件（可重复）', shared_1.collectRepeatedOption, [])
+        .option('--update <relpath>', '修改文件（可重复）', shared_1.collectRepeatedOption, [])
+        .option('--delete <relpath>', '删除文件（可重复）', shared_1.collectRepeatedOption, [])
         .addHelpText('after', `
 不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
 
@@ -41,14 +48,27 @@ function registerDeployCommandsModern(program) {
   外部据 stdout 返回的 version / preReleaseID 自行建单，并据本命令的
   退出码决定把发布单翻成 Finished 还是 Failed —— 失败态由外部负责，CLI 不再兜底。
   该模式下 releaseID / url 输出为 null（CLI 未建单，无从得知）。
-  注意：--conf 的 checkPointVersion / commitID 唯一消费者是 createLocalRelease，
+  注意：--conf 的四个字段唯一消费者是 createLocalRelease，
   本模式下不生效（静默忽略，不报错），需要关联请在外部建单时自行传递。
 
+--create / --update / --delete（变更文件清单）
+  可重复，值为工程根相对路径（禁绝对路径与 ".."）。deploy patch 消费它做增量发布；
+  在 deploy 下当前是预留口子——只校验路径并记一行日志，不改变上传行为：
+  deploy 仍然全量上传产物，latest 每次被重建为工作区的精确镜像（prune 清理远端多余对象），
+  以此保证 git 仓库与 TOS 资源不会不一致。
+  后续若实现增量上传，从这里取「要 PUT 哪些文件」即可，调用方无需改动；
+  删除仍交给 prune，因为 prune 比对的是完整本地清单，与上传了哪些文件无关。
+
 --conf（关联元信息透传）
-  值为 JSON string，只识别两个字段，其余 key 忽略：
+  值为 JSON string，只识别四个字段，其余 key 忽略：
     checkPointVersion  关联的 checkpoint 版本
     commitID           关联的代码 commit ID
-  两字段均可选；非法 JSON / 非对象 / 字段值非字符串会报错。
+    sessionID          发起本次发布的页面会话 ID，原样透传不做净化
+    marker             本次发布的变更说明，落发布单 description
+  四字段均可选；非法 JSON / 非对象 / 字段值非字符串会报错。
+  versionLevel：本次发布的版本档位。"major" 声明这是一个大版本，历史记录里强制开新组；
+  "minor" 声明是小版本，即使距上次发布超过聚合阈值也不提升。不传则由服务端按
+  时间间隔自动判定，与改造前行为一致——只有会主动声明档位的链路需要传。
 
 JSON 输出（stdout）
   {"data": {"appId": "...", "version": <n>, "url": "...", "releaseID": "...", "preReleaseID": "..."}}
@@ -60,6 +80,8 @@ JSON 输出（stdout）
   $ miaoda deploy --skip-build
   $ miaoda deploy --skip-release
   $ miaoda deploy --conf '{"checkPointVersion":"v3","commitID":"a1b2c3d"}'
+  $ miaoda deploy --conf '{"commitID":"a1b2c3d","sessionID":"<uuid>","marker":"编辑保存：修改 index.html"}'
+  $ miaoda deploy --update index.html --create assets/new.js --delete old.html
 `);
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
         await (0, modern_1.handleDeployModern)({
@@ -68,17 +90,18 @@ JSON 输出（stdout）
             skipBuild: rawOpts.skipBuild,
             skipRelease: rawOpts.skipRelease,
             conf: rawOpts.conf,
+            creates: rawOpts.create,
+            updates: rawOpts.update,
+            deletes: rawOpts.delete,
         });
     }));
     const patchCmd = deployCmd
         .command('patch')
         .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, [])
         .option('--session-id <id>', '会话 ID，发布时透传给下游（可选）')
         .addHelpText('after', `
---dir 为项目目录（与 deploy 同名参数，默认当前目录）。
+--dir / --create / --update / --delete 声明在父命令 deploy 上，本命令共用，用法不变。
+--dir 为项目目录，默认当前目录。
 仅支持 design-html（design_local_deploy）。路径为工程根相对路径（= 服务端 latest 下 key），
 禁绝对路径与 ".."。--create/--update 的本地文件必须存在。改动里含任意 .html（增 / 改 / 删）
 时自动重算并随包更新 routes.json；纯非 .html 改动不动 routes.json。
@@ -98,9 +121,9 @@ JSON 输出
         await (0, index_1.handleDeployPatch)({
             appId: (0, shared_1.resolveAppId)({}),
             dir: deployCmd.opts().dir ?? '.',
-            creates: rawOpts.create,
-            updates: rawOpts.update,
-            deletes: rawOpts.delete,
+            creates: deployCmd.opts().create,
+            updates: deployCmd.opts().update,
+            deletes: deployCmd.opts().delete,
             sessionID: rawOpts.sessionId,
         });
     }));

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

@@ -4,14 +4,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseDeployConf = parseDeployConf;
+exports.parseChangedFiles = parseChangedFiles;
 exports.handleDeployModern = handleDeployModern;
 const node_path_1 = __importDefault(require("node:path"));
 const output_1 = require("../../../utils/output");
 const error_1 = require("../../../utils/error");
 const index_1 = require("../../../services/deploy/modern/index");
-const CONF_EXPECTED = '期望形如 {"checkPointVersion":"...","commitID":"..."} 的 JSON 对象';
+const index_2 = require("../../../services/deploy/modern/patch/index");
+const logger_1 = require("../../../utils/logger");
+const CONF_EXPECTED = '期望形如 {"checkPointVersion":"...","commitID":"...","sessionID":"...","marker":"...","versionLevel":"major"} 的 JSON 对象';
 /**
- * 解析 `--conf` JSON string，只取 checkPointVersion / commitID 两个白名单字段。
+ * 解析 `--conf` JSON string，只取 checkPointVersion / commitID / sessionID / marker / versionLevel 五个白名单字段。
  * - 未传 → 返回 {}（行为不变）。
  * - 非法 JSON / 非 object / 字段值非 string → 抛 DEPLOY_CONF_INVALID。
  * - 空串字段视为未提供（不进 body，保持可选语义）；未知 key 忽略。
@@ -31,7 +34,13 @@ function parseDeployConf(raw) {
     }
     const source = parsed;
     const conf = {};
-    for (const key of ['checkPointVersion', 'commitID']) {
+    for (const key of [
+        'checkPointVersion',
+        'commitID',
+        'sessionID',
+        'marker',
+        'versionLevel',
+    ]) {
         const value = source[key];
         if (value === undefined)
             continue;
@@ -43,6 +52,29 @@ function parseDeployConf(raw) {
     }
     return conf;
 }
+/**
+ * 解析 `--create` / `--update` / `--delete`，校验路径后组成 PatchChangeSet。
+ *
+ * 复用 deploy patch 的 normalizeRel（同一套校验：禁绝对路径、禁 ".."、统一为 posix 相对路径），
+ * 保证两条链路对「变更文件」的接受范围完全一致，调用方从 patch 迁移不会遇到收紧或放宽。
+ *
+ * 当前是预留口子：deploy 仍然全量上传，这里只校验并记一行日志，不参与上传决策。
+ * 三个参数都没传 → 返回 undefined（与不传时行为完全一致，不产生日志）。
+ */
+function parseChangedFiles(opts) {
+    const cs = {
+        creates: (opts.creates ?? []).map((rel) => (0, index_2.normalizeRel)(rel)),
+        updates: (opts.updates ?? []).map((rel) => (0, index_2.normalizeRel)(rel)),
+        deletes: (opts.deletes ?? []).map((rel) => (0, index_2.normalizeRel)(rel)),
+    };
+    const total = cs.creates.length + cs.updates.length + cs.deletes.length;
+    if (total === 0)
+        return undefined;
+    (0, logger_1.log)('deploy', `收到变更文件提示 ${String(total)} 个（create=${String(cs.creates.length)} ` +
+        `update=${String(cs.updates.length)} delete=${String(cs.deletes.length)}）：` +
+        '当前仍为全量上传，未启用增量');
+    return cs;
+}
 /**
  * miaoda deploy（modern scene 专用，CLI 表面对齐 openclaw-cli）
  *
@@ -58,6 +90,10 @@ async function handleDeployModern(opts) {
         skipRelease: opts.skipRelease ?? false,
         checkPointVersion: conf.checkPointVersion,
         commitID: conf.commitID,
+        sessionID: conf.sessionID,
+        marker: conf.marker,
+        versionLevel: conf.versionLevel,
+        changedFiles: parseChangedFiles(opts),
     });
     (0, output_1.emit)({
         data: {

package/dist/config/migrate-configs/vite-react-to-nestjs-react-fullstack.js

@@ -70,6 +70,7 @@ exports.MIGRATE_CONFIG = {
         { type: 'file', from: 'tsconfig.json', to: 'tsconfig.json', overwrite: true },
         { type: 'file', from: 'tsconfig.app.json', to: 'tsconfig.app.json', overwrite: true },
         { type: 'file', from: 'tsconfig.node.json', to: 'tsconfig.node.json', overwrite: true },
+        { type: 'file', from: 'tsconfig.mcp-ui.json', to: 'tsconfig.mcp-ui.json', overwrite: false },
         // ESLint 9 flat config —— vite-react 用 eslint.config.mjs 已删，fullstack 用
         // eslint.config.js (commonjs) + extends @lark-apaas/fullstack-presets；user 通常不改
         { type: 'file', from: 'eslint.config.js', to: 'eslint.config.js', overwrite: true },
@@ -158,10 +159,16 @@ exports.MIGRATE_CONFIG = {
             command: 'tsc --noEmit --project tsconfig.app.json',
             overwrite: true,
         },
+        {
+            type: 'add-script',
+            name: 'type:check:mcp-ui',
+            command: 'node ./scripts/typecheck-mcp-ui.js',
+            overwrite: true,
+        },
         {
             type: 'add-script',
             name: 'type:check',
-            command: 'concurrently -n "server,client" -c "blue,green" "npm run type:check:server" "npm run type:check:client"',
+            command: 'concurrently -n "server,client,mcp-ui" -c "blue,green,magenta" "npm run type:check:server" "npm run type:check:client" "npm run type:check:mcp-ui"',
             overwrite: true,
         },
         // ----- 平台脚本调用链 -----

package/dist/config/sync-configs/nestjs-react-fullstack.js

@@ -159,6 +159,46 @@ exports.SYNC_CONFIG = {
             to: `npx -y ${fullstack_cli_pin_1.FULLSTACK_CLI_PIN_SPEC} sync --disable-gen-openapi`,
             ifStartsWith: 'npx -y @lark-apaas/fullstack-cli sync',
         },
+        // MCP UI 使用独立浏览器配置；仅迁移已知模板命令，不生成 UI 目录；根配置仅在缺失时补齐。
+        {
+            type: 'typescript-exclude',
+            to: 'tsconfig.node.json',
+            path: 'server/mcp/ui',
+        },
+        { type: 'file', from: 'tsconfig.mcp-ui.json', to: 'tsconfig.mcp-ui.json', overwrite: false },
+        {
+            type: 'add-script',
+            name: 'type:check:mcp-ui',
+            command: 'node ./scripts/typecheck-mcp-ui.js',
+            overwrite: false,
+        },
+        {
+            type: 'patch-script',
+            name: 'type:check:mcp-ui',
+            to: 'node ./scripts/typecheck-mcp-ui.js',
+            ifEquals: [
+                'node ./scripts/check.cjs --typecheck-mcp-ui',
+                'node ./scripts/lint.js --typecheck-mcp-ui',
+            ],
+        },
+        {
+            type: 'patch-script',
+            name: 'type:check',
+            to: 'concurrently -n "server,client,mcp-ui" -c "blue,green,magenta" "npm run type:check:server" "npm run type:check:client" "npm run type:check:mcp-ui"',
+            ifEquals: [
+                'node ./scripts/check.cjs --typecheck',
+                'node ./scripts/lint.js --typecheck',
+                'concurrently -n "server,client" -c "blue,green" "npm run type:check:server" "npm run type:check:client"',
+                'concurrently "npm run type:check:server" "npm run type:check:client"',
+                'concurrently "npm run type:check:client" "npm run type:check:server"',
+            ],
+        },
+        {
+            type: 'patch-script',
+            name: 'eslint',
+            to: 'eslint . --quiet',
+            ifEquals: ['eslint . --quiet --ignore-pattern "server/mcp/ui/**"'],
+        },
         // ===== miaoda-cli 本地开发新增规则（fullstack-cli sync 不会执行） =====
         // M1. scripts.dev:local —— 本地用户绕过沙箱判定直接跑本地链路（npm run dev:local）。
         //     dev.sh 在 MIAODA_DEP_CACHE_DIR 非空时跑 dev.js（沙箱保活）、否则 exec dev-local.js；显式 dev:local

package/dist/services/deploy/modern/atoms/local-release.js

@@ -16,6 +16,9 @@ async function createLocalRelease(appId, version, extra) {
         version,
         checkPointVersion: extra?.checkPointVersion,
         commitID: extra?.commitID,
+        sessionID: extra?.sessionID,
+        description: extra?.marker,
+        versionLevel: extra?.versionLevel,
     });
 }
 /**

package/dist/services/deploy/modern/patch/actions.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.normalizeRel = normalizeRel;
 exports.buildTosActions = buildTosActions;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -10,7 +11,12 @@ const error_1 = require("../../../../utils/error");
 const index_1 = require("../../../../api/deploy/index");
 const content_1 = require("./content");
 const routes_1 = require("./routes");
-/** 校验相对路径：禁绝对路径、禁含 ".." 段；normalize 成 posix 相对。 */
+/**
+ * 校验相对路径：禁绝对路径、禁含 ".." 段；normalize 成 posix 相对。
+ *
+ * 导出供 `deploy` 的 `--create` / `--update` / `--delete` 复用同一套校验，
+ * 让两条链路对「变更文件」的接受范围一致，避免两处实现漂移。
+ */
 function normalizeRel(rel) {
     if (node_path_1.default.isAbsolute(rel) || rel.startsWith('/')) {
         throw new error_1.AppError('ARGS_INVALID', `文件路径不能是绝对路径：${rel}`);

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildTosActions = void 0;
+exports.normalizeRel = exports.buildTosActions = void 0;
 exports.patchDesignDeploy = patchDesignDeploy;
 const spark_meta_1 = require("../../../../utils/spark-meta");
 const error_1 = require("../../../../utils/error");
@@ -10,6 +10,7 @@ const template_key_map_1 = require("../template-key-map");
 const actions_1 = require("./actions");
 var actions_2 = require("./actions");
 Object.defineProperty(exports, "buildTosActions", { enumerable: true, get: function () { return actions_2.buildTosActions; } });
+Object.defineProperty(exports, "normalizeRel", { enumerable: true, get: function () { return actions_2.normalizeRel; } });
 /**
  * design-html 增量发布：读本地文件组 TosFileAction（改动含 .html 时带重算的
  * routes.json），调后端 applyTosDiff 应用到 latest。scope 限 design_local_deploy。

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

@@ -28,7 +28,13 @@ async function designLocalPublishPipeline(opts) {
             skipRelease: opts.skipRelease ?? false,
             appId: ctx.appId,
             version: pre.version,
-            extra: { checkPointVersion: opts.checkPointVersion, commitID: opts.commitID },
+            extra: {
+                checkPointVersion: opts.checkPointVersion,
+                commitID: opts.commitID,
+                sessionID: opts.sessionID,
+                marker: opts.marker,
+                versionLevel: opts.versionLevel,
+            },
         });
         try {
             await (0, index_1.uploadDesignArtifacts)({ projectDir: ctx.projectDir, data });

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

@@ -45,7 +45,13 @@ async function localBuildLocalPublishPipeline(opts) {
         skipRelease: opts.skipRelease ?? false,
         appId: ctx.appId,
         version: pre.version,
-        extra: { checkPointVersion: opts.checkPointVersion, commitID: opts.commitID },
+        extra: {
+            checkPointVersion: opts.checkPointVersion,
+            commitID: opts.commitID,
+            sessionID: opts.sessionID,
+            marker: opts.marker,
+            versionLevel: opts.versionLevel,
+        },
     });
     try {
         (0, logger_1.log)('deploy', 'Uploading artifacts...');

package/dist/utils/http.js

@@ -64,13 +64,13 @@ 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）。
+ * 联调未合流的服务端改动时，不要改这个默认值 —— 用 MIAODA_CANARY_HEADER 覆盖，
+ * 或由 agent_tool 按请求 x-tt-env 注入（详见 applyCanaryHeader 与 agent_tool
+ * ExecShellCmd）。改默认值意味着所有沙箱都被带去开发泳道，且历史上多次忘记还原
+ * （boe_miaoda_doubao → ppe_miaoda_ccm → boe_miaoda_ccm → boe_debug_detail_lookup
+ * → boe_creative_history）。
  */
-const DEFAULT_CANARY_HEADER = 'boe_debug_detail_lookup';
+const DEFAULT_CANARY_HEADER = 'prod';
 /**
  * 注入 x-tt-env 小流量头：env 显式设值 > DEFAULT_CANARY_HEADER。
  *

package/dist/utils/sync-rule.js

@@ -43,6 +43,7 @@ const jsonc = __importStar(require("jsonc-parser"));
 const file_ops_1 = require("./file-ops");
 const merge_json_1 = require("./merge-json");
 const logger_1 = require("./logger");
+const typescript_exclude_1 = require("./typescript-exclude");
 /**
  * 顺序执行 SyncRule[]，逐条 apply。一条 rule 报错不影响后续 rule（catch + 记录），最终
  * 在 handler 层决定是否整体 fail。
@@ -106,6 +107,11 @@ function applyOne(rule, opts) {
         case 'patch-script': {
             return applyPatchScript(rule, targetDir, logPrefix);
         }
+        case 'typescript-exclude': {
+            const changed = (0, typescript_exclude_1.excludeTypeScriptPath)(node_path_1.default.join(targetDir, rule.to), rule.path);
+            (0, logger_1.log)(logPrefix, `  ${changed ? '✓' : '○'} ${rule.to} (exclude ${rule.path})`);
+            return { rule, action: changed ? 'patched' : 'noop', path: rule.to };
+        }
         case 'merge-json': {
             return applyMergeJson(rule, sourceRoot, targetDir, logPrefix);
         }
@@ -215,7 +221,10 @@ function applyPatchScript(rule, targetDir, logPrefix) {
         (0, logger_1.log)(logPrefix, `  ○ scripts.${rule.name} (already patched)`);
         return { rule, action: 'noop', path: 'package.json' };
     }
-    if (!current.startsWith(rule.ifStartsWith)) {
+    const matches = rule.ifEquals
+        ? rule.ifEquals.includes(current)
+        : rule.ifStartsWith !== undefined && current.startsWith(rule.ifStartsWith);
+    if (!matches) {
         (0, logger_1.log)(logPrefix, `  ⚠ scripts.${rule.name} customized, skip patch`);
         return { rule, action: 'skipped', path: 'package.json' };
     }

package/dist/utils/typescript-exclude.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.excludeTypeScriptPath = excludeTypeScriptPath;
+const node_fs_1 = __importDefault(require("node:fs"));
+const jsonc_parser_1 = require("jsonc-parser");
+const error_1 = require("./error");
+/** Only append to explicit template excludes; never rewrite inherited user configuration. */
+function excludeTypeScriptPath(filename, excludedPath) {
+    if (!node_fs_1.default.existsSync(filename))
+        return false;
+    const source = node_fs_1.default.readFileSync(filename, 'utf8');
+    const errors = [];
+    const raw = (0, jsonc_parser_1.parse)(source, errors, { allowTrailingComma: true });
+    if (errors.length || !raw || typeof raw !== 'object')
+        throw new error_1.AppError('INVALID_CONFIG', `Invalid exclude array: ${filename}`);
+    if (raw.exclude === undefined) {
+        console.warn(`Cannot safely update inherited excludes in ${filename}; add ${excludedPath} to the effective TypeScript exclude configuration.`);
+        return false;
+    }
+    if (!Array.isArray(raw.exclude) || raw.exclude.some((p) => typeof p !== 'string'))
+        throw new error_1.AppError('INVALID_CONFIG', `Invalid exclude array: ${filename}`);
+    if (raw.exclude.includes(excludedPath))
+        return false;
+    node_fs_1.default.writeFileSync(filename, (0, jsonc_parser_1.applyEdits)(source, (0, jsonc_parser_1.modify)(source, ['exclude', raw.exclude.length], excludedPath, {
+        isArrayInsertion: true,
+        formattingOptions: {
+            insertSpaces: true,
+            tabSize: 2,
+            eol: source.includes('\r\n') ? '\r\n' : '\n',
+        },
+    })));
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.39-alpha.73a593e",
+  "version": "0.1.39-alpha.ad15159",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -51,9 +51,9 @@
     "prettier": "^3.8.3",
     "tsc-alias": "^1.8.11",
     "tsx": "^4.19.4",
-    "typescript": "^5.8.3",
     "vitest": "^4.1.4",
-    "xml2js": "^0.6.2"
+    "xml2js": "^0.6.2",
+    "typescript": "^5.8.3"
   },
   "scripts": {
     "build": "bash scripts/build.sh",

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/build.sh

@@ -210,3 +210,28 @@ else
   echo "   node_modules: $NODE_MODULES_SIZE"
   echo ""
 fi
+
+# 仅成功的全构建生成 backendBuildID；必须在构建、产物准备和依赖裁剪之后。
+# UI/Skill 内容由 SDK 独立计入总 hash；纯前端发布不替换已部署的 backendBuildID。
+if [[ "${only_frontend_change:-false}" != "true" ]]; then
+  node - "$ROOT_DIR/dist" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomUUID } = require('node:crypto');
+const dist = process.argv[2];
+// 防止 build:server 空跑成功、却没有可交付的服务端入口。
+if (!fs.statSync(path.join(dist, 'server/main.js')).isFile()) {
+  throw new Error('Missing server build output: dist/server/main.js');
+}
+// runtime cwd 分别为工程根、dist/（或整包解压到 dist-server/）、旧版 dist/server/。
+// 与 MCP UI/Skill 的交付布局一致：复制产物时保留同一个 UUID，不在启动时生成。
+const files = [
+  path.join(dist, 'mcp-build-id'),
+  path.join(dist, 'dist/mcp-build-id'),
+  path.join(dist, 'server/dist/mcp-build-id'),
+];
+for (const file of files) fs.mkdirSync(path.dirname(file), { recursive: true });
+const buildID = randomUUID();
+for (const file of files) fs.writeFileSync(file, buildID, 'utf8');
+NODE
+fi

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/lint.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 const path = require('node:path');
-const { spawn } = require('node:child_process');
 const fs = require('node:fs');
+const { spawn } = require('node:child_process');
 
 const cwd = process.cwd();
 
@@ -11,30 +11,50 @@ function getBinName(name) {
 }
 
 function runCommand(command, args) {
-  return new Promise((resolve) => {
+  return new Promise(resolve => {
     const child = spawn(command, args, {
       cwd,
       stdio: 'inherit',
       shell: false,
     });
 
-    child.on('close', (code) => resolve(code || 0));
+    child.on('close', code => resolve(code ?? 1));
     child.on('error', () => resolve(1));
   });
 }
 
-function normalizeProjectFile(filePath) {
+// 串行依次执行每个任务，全部跑完后再聚合退出码：
+// 降低并发资源占用、让各任务输出按顺序清晰可读，同时保留“一次暴露所有 lint 问题”的行为。
+async function runTasksSerially(taskSpecs) {
+  let exitCode = 0;
+  for (const [command, args] of taskSpecs) {
+    const code = await runCommand(command, args);
+    if (code !== 0) {
+      exitCode = 1;
+    }
+  }
+  return exitCode;
+}
+
+function normalizeProjectFile(filePath, checkDeleted = false) {
   const absolutePath = path.isAbsolute(filePath)
     ? filePath
     : path.resolve(cwd, filePath);
 
   if (!fs.existsSync(absolutePath)) {
-    console.warn(`[lint] Skip missing file: ${filePath}`);
-    return null;
+    if (!checkDeleted) {
+      console.warn(`[lint] Skip missing file: ${filePath}`);
+      return null;
+    }
+    console.log(`[lint] Deleted file: ${filePath}; checking affected projects`);
   }
 
   const relativePath = path.relative(cwd, absolutePath);
-  if (relativePath.startsWith('..')) {
+  if (
+    relativePath === '..' ||
+    relativePath.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativePath)
+  ) {
     console.warn(`[lint] Skip file outside project: ${filePath}`);
     return null;
   }
@@ -91,25 +111,106 @@ function canRunStylelint() {
 
   if (!pkg.scripts || !pkg.scripts.stylelint) return false;
 
-  return STYLELINT_CONFIG_FILES.some(file => fs.existsSync(path.join(cwd, file)));
+  return STYLELINT_CONFIG_FILES.some(file =>
+    fs.existsSync(path.join(cwd, file))
+  );
+}
+
+const UI_DIR = 'server/mcp/ui';
+
+function uiSourceFiles() {
+  const files = [];
+  function visit(relative) {
+    const absolute = path.join(cwd, relative);
+    if (!fs.existsSync(absolute)) return;
+    if (fs.lstatSync(absolute).isSymbolicLink()) {
+      throw new Error(`MCP UI 检查不支持符号链接: ${relative}`);
+    }
+    for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) {
+      if (['node_modules', 'dist', '.git'].includes(entry.name)) continue;
+      const file = `${relative}/${entry.name}`;
+      if (entry.isSymbolicLink())
+        throw new Error(`MCP UI 检查不支持符号链接: ${file}`);
+      if (entry.isDirectory()) visit(file);
+      else if (isEslintTarget(file) && !/\.d\.(?:ts|mts|cts)$/.test(file))
+        files.push(file);
+    }
+  }
+  visit(UI_DIR);
+  return files.sort();
+}
+
+function uiTasks({ types = true, eslint = true, aggregate = false } = {}) {
+  const sources = uiSourceFiles();
+  if (!sources.length) return [];
+  const tasks = [];
+  // 只在有 UI 源码时读取聚合命令；普通应用不依赖 MCP 配置或脚本。
+  if (types && aggregate) {
+    const scripts = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).scripts || {};
+    types = !/\bnpm\s+run\s+type:check:mcp-ui(?=[\s"';&|)]|$)/.test(scripts['type:check'] || '');
+  }
+  if (types) tasks.push([getBinName('npm'), ['run', 'type:check:mcp-ui']]);
+  if (eslint) {
+    const config = [
+      'eslint.mcp-ui.config.js',
+      'eslint.mcp-ui.config.cjs',
+      'eslint.mcp-ui.config.mjs',
+    ].find(file => fs.existsSync(path.join(cwd, file)));
+    let resolvedConfig = config;
+    if (!resolvedConfig) {
+      try {
+        resolvedConfig =
+          require.resolve('@lark-apaas/fullstack-presets/lib/mcp/eslint-ui.js');
+      } catch {
+        throw new Error(
+          '请升级 @lark-apaas/fullstack-presets 以使用 MCP UI 默认 ESLint 配置，或提供 eslint.mcp-ui.config.cjs'
+        );
+      }
+    }
+    tasks.push([
+      getBinName('npx'),
+      [
+        '--no-install',
+        'eslint',
+        '--config',
+        resolvedConfig,
+        '--quiet',
+        '--max-warnings',
+        '0',
+        ...sources,
+      ],
+    ]);
+  }
+  return tasks;
+}
+
+function isUiFile(file) {
+  return file.startsWith('server/mcp/ui/');
 }
 
 async function runDefaultLint() {
-  const commands = ['npm run eslint', 'npm run type:check'];
+  const taskSpecs = [
+    [getBinName('npm'), ['run', 'eslint']],
+    [getBinName('npm'), ['run', 'type:check']],
+  ];
+
+  taskSpecs.push(...uiTasks({ aggregate: true }));
 
   if (canRunStylelint()) {
-    commands.push('npm run stylelint');
+    taskSpecs.push([getBinName('npm'), ['run', 'stylelint']]);
   } else {
-    console.warn('[lint] Skip stylelint: missing scripts.stylelint or stylelint config');
+    console.warn(
+      '[lint] Skip stylelint: missing scripts.stylelint or stylelint config'
+    );
   }
 
-  const code = await runCommand(getBinName('npx'), ['concurrently', ...commands]);
-  process.exit(code);
+  process.exit(await runTasksSerially(taskSpecs));
 }
 
 async function runSelectiveLint(inputFiles) {
+  const hasUiSources = uiSourceFiles().length > 0;
   const normalizedFiles = Array.from(
-    new Set(inputFiles.map(normalizeProjectFile).filter(Boolean)),
+    new Set(inputFiles.map(file => normalizeProjectFile(file, hasUiSources)).filter(Boolean))
   );
 
   if (normalizedFiles.length === 0) {
@@ -117,15 +218,40 @@ async function runSelectiveLint(inputFiles) {
     process.exit(0);
   }
 
-  const eslintFiles = normalizedFiles.filter(isEslintTarget);
-  const stylelintFiles = normalizedFiles.filter(isStylelintTarget);
+  const eslintFiles = normalizedFiles.filter(
+    file =>
+      fs.existsSync(path.join(cwd, file)) &&
+      isEslintTarget(file) &&
+      (!hasUiSources || (!isUiFile(file) && !file.startsWith('eslint.mcp-ui.config.')))
+  );
+  const stylelintFiles = normalizedFiles.filter(
+    file => fs.existsSync(path.join(cwd, file)) && isStylelintTarget(file)
+  );
   const typeCheckFiles = normalizedFiles.filter(isTypeCheckTarget);
 
   const clientTypeFiles = [];
   const serverTypeFiles = [];
+  const rootConfigChanged = hasUiSources && normalizedFiles.some(file =>
+    /^tsconfig(?:\.[^/]*)?\.json$/.test(file)
+  );
+  if (rootConfigChanged) {
+    clientTypeFiles.push('config');
+    serverTypeFiles.push('config');
+  }
+  let checkUi =
+    rootConfigChanged ||
+    normalizedFiles.some(
+      file =>
+        isUiFile(file) ||
+        file.startsWith('shared/') ||
+        file.startsWith('eslint.mcp-ui.config.') ||
+        file === 'package.json'
+    );
 
   for (const filePath of typeCheckFiles) {
-    if (filePath.startsWith('client/')) {
+    if (hasUiSources && isUiFile(filePath)) {
+      checkUi = true;
+    } else if (filePath.startsWith('client/')) {
       clientTypeFiles.push(filePath);
     } else if (filePath.startsWith('server/')) {
       serverTypeFiles.push(filePath);
@@ -135,36 +261,52 @@ async function runSelectiveLint(inputFiles) {
     }
   }
 
-  const tasks = [];
+  const taskSpecs = [];
 
   if (eslintFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npx'), ['eslint', '--quiet', ...eslintFiles]));
+    taskSpecs.push([getBinName('npx'), ['eslint', '--quiet', ...eslintFiles]]);
   }
 
   if (stylelintFiles.length > 0 && !canRunStylelint()) {
-    console.warn('[lint] Skip stylelint: missing scripts.stylelint or stylelint config');
+    console.warn(
+      '[lint] Skip stylelint: missing scripts.stylelint or stylelint config'
+    );
   } else if (stylelintFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npx'), ['stylelint', '--quiet', ...stylelintFiles]));
+    taskSpecs.push([
+      getBinName('npx'),
+      ['stylelint', '--quiet', ...stylelintFiles],
+    ]);
   }
 
   if (clientTypeFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npm'), ['run', 'type:check:client']));
+    taskSpecs.push([getBinName('npm'), ['run', 'type:check:client']]);
   }
 
   if (serverTypeFiles.length > 0) {
-    tasks.push(runCommand(getBinName('npm'), ['run', 'type:check:server']));
+    taskSpecs.push([getBinName('npm'), ['run', 'type:check:server']]);
   }
 
-  if (tasks.length === 0) {
+  if (checkUi) taskSpecs.push(...uiTasks());
+
+  if (taskSpecs.length === 0) {
     console.log('[lint] No supported files matched for lint');
     process.exit(0);
   }
 
-  const results = await Promise.all(tasks);
-  process.exit(results.some(code => code !== 0) ? 1 : 0);
+  process.exit(await runTasksSerially(taskSpecs));
 }
 
 async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === '--eslint-mcp-ui') {
+    process.exit(await runTasksSerially(uiTasks({ types: false })));
+    return;
+  }
+  if (args.length && !(args[0] === '--files' && args.length > 1)) {
+    throw new Error('用法: lint.js [--files <paths...>]');
+  }
+  if (args[0] === '--files' && args.slice(1).some(arg => arg.startsWith('--')))
+    throw new Error('--files 不可与其他检查模式混用');
   const files = parseFilesArg(process.argv.slice(2));
   if (files === null) {
     await runDefaultLint();
@@ -179,7 +321,7 @@ async function main() {
   await runSelectiveLint(files);
 }
 
-main().catch((error) => {
+main().catch(error => {
   const message = error instanceof Error ? error.message : String(error);
   console.error(`[lint] Failed to run lint: ${message}`);
   process.exit(1);

package/upgrade/templates/nestjs-react-fullstack/templates/scripts/typecheck-mcp-ui.js

@@ -0,0 +1,32 @@
+// MCP UI 是可选浏览器工程；没有源码时跳过，否则直接交给 tsc。
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+function hasSource(dir) {
+  if (!fs.existsSync(dir)) return false;
+  return fs.readdirSync(dir, { withFileTypes: true }).some(entry => {
+    if (['node_modules', 'dist'].includes(entry.name)) return false;
+    if (entry.isDirectory()) return hasSource(path.join(dir, entry.name));
+    return entry.isFile() && /\.(?:[cm]?[jt]sx?)$/.test(entry.name);
+  });
+}
+
+if (hasSource('server/mcp/ui')) {
+  // 已有应用的独立 UI 配置继续生效，避免升级覆盖自定义 paths/types。
+  const config = fs.existsSync('server/mcp/ui/tsconfig.json')
+    ? 'server/mcp/ui/tsconfig.json'
+    : 'tsconfig.mcp-ui.json';
+  const result = spawnSync(
+    process.execPath,
+    [
+      require.resolve('typescript/bin/tsc'),
+      '--noEmit',
+      '--project',
+      config,
+    ],
+    { stdio: 'inherit' }
+  );
+  if (result.error) console.error(result.error.message);
+  process.exitCode = result.status ?? 1;
+}

package/upgrade/templates/nestjs-react-fullstack/templates/tsconfig.mcp-ui.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "types": [],
+    "strict": true,
+    "checkJs": true,
+    "lib": [
+      "ES2020",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@shared/*": [
+        "shared/*"
+      ]
+    }
+  },
+  "include": [
+    "server/mcp/ui/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}