@lark-apaas/miaoda-cli 0.1.38 → 0.1.39-alpha.2875384

package/README.md

@@ -52,6 +52,16 @@ miaoda file ls --output json
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 全栈应用的 MCP UI 检查
+
+创建 MCP UI 时，Agent 在 `server/mcp/ui` 中同时生成 `tsconfig.json` 和 `eslint.config.cjs`，修改 UI 或其 shared 依赖后主动运行独立检查。模板和 CLI 不生成 UI 配置，也不将 UI 检查接入主工程 lint/type:check。
+
+主工程保留原 client/server 检查。Agent 从工程根执行 `npx --no-install tsc --noEmit --project server/mcp/ui/tsconfig.json`，再执行 `npx --no-install eslint --config server/mcp/ui/eslint.config.cjs "server/mcp/ui/**/*.{ts,tsx,js,jsx}" --max-warnings 0`；必须检查退出码并修复错误。无需辅助脚本或新增 npm 命令。
+
+CLI 不注入 MCP UI 检查命令；主工程保留原有 client/server 检查，UI 由 Agent 按独立配置执行标准 tsc/eslint。
+
+存量 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/commands/skills/index.js

@@ -53,7 +53,7 @@ function registerSkillsSync(parent) {
 
 JSON 输出
   {"data": {"stack": "...", "version": "...", "syncedSkills": [...], "techSynced": true|false,
-            "claudeSkillsLink": "created|updated|noop|conflict"  // 仅 --local 时}}
+            "claudeSkillsLink": "created|updated|noop|conflict|unsupported"  // 仅 --local 时}}
 
   传 --type 时：
   {"data": {"mode": "sandbox", "type": "...", "packageName": "...", "version": "...",

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

@@ -38,11 +38,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = void 0;
 exports.handleAppExport = handleAppExport;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const api = __importStar(require("../../../api/index"));
+const archive_1 = require("../../../utils/archive");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const logger_1 = require("../../../utils/logger");
@@ -95,11 +95,11 @@ function extractArchive(archivePath, destDir, head) {
     const isZip = head.length >= 4 && head[0] === 0x50 && head[1] === 0x4b;
     const isGzip = head.length >= 2 && head[0] === 0x1f && head[1] === 0x8b;
     if (isZip) {
-        (0, node_child_process_1.execFileSync)('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio: 'pipe' });
+        (0, archive_1.extractZip)(archivePath, destDir);
         return;
     }
     if (isGzip) {
-        (0, node_child_process_1.execFileSync)('tar', ['-xzf', archivePath, '-C', destDir], { stdio: 'pipe' });
+        (0, archive_1.extractTarGz)(archivePath, destDir);
         return;
     }
     throw new error_1.AppError('EXPORT_ARCHIVE_INVALID', '无法识别归档格式（非 zip / tar.gz）', {

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

@@ -16,6 +16,7 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const env_1 = require("../../../utils/env");
 const logger_1 = require("../../../utils/logger");
+const run_npm_1 = require("../../../utils/run-npm");
 /**
  * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
  *
@@ -126,7 +127,7 @@ async function handleAppMigrate(opts) {
     (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
     let installError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
+        (0, run_npm_1.execNpmSync)(installArgs, {
             cwd: targetDir,
             stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
         });
@@ -167,6 +168,8 @@ async function handleAppMigrate(opts) {
     //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
     //     留着旧进程让用户先处理 installError
     //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
+    //   - pkill 是 POSIX-only,但整段被 isSandboxEnv() 包着(沙箱恒为 Linux),
+    //     Windows 本地永远走不到这里,故不需要跨平台封装
     let devRestarted = false;
     if (installError === undefined && (0, env_1.isSandboxEnv)()) {
         (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');

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

@@ -9,7 +9,6 @@ exports.runStackSync = runStackSync;
 exports.summarizeSyncResults = summarizeSyncResults;
 exports.snapshotManagedDepSpecs = snapshotManagedDepSpecs;
 exports.diffManagedSpecs = diffManagedSpecs;
-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 sync_configs_1 = require("../../../config/sync-configs");
@@ -19,6 +18,7 @@ const githooks_1 = require("../../../utils/githooks");
 const logs_dir_1 = require("../../../utils/logs-dir");
 const install_1 = require("../../../services/app/init/install");
 const spark_meta_1 = require("../../../utils/spark-meta");
+const run_npm_1 = require("../../../utils/run-npm");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const logger_1 = require("../../../utils/logger");
@@ -127,7 +127,7 @@ async function handleAppSync(opts) {
     (0, logger_1.log)('sync', `Running npm ${installArgs.join(' ')}...`);
     let installError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
+        (0, run_npm_1.execNpmSync)(installArgs, {
             cwd: targetDir,
             stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
         });

package/dist/cli/handlers/db/sql.js

@@ -47,7 +47,7 @@ const colors_1 = require("../../../utils/colors");
 const fuzzy_match_1 = require("../../../utils/fuzzy-match");
 const index_1 = require("../../../api/db/index");
 const sql_keywords_1 = require("../../../api/db/sql-keywords");
-const node_child_process_1 = require("node:child_process");
+const run_npm_1 = require("../../../utils/run-npm");
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
 /**
@@ -140,20 +140,22 @@ async function maybeSyncAgentSchema(results) {
     (0, logger_1.debug)(`[db sql] DDL detected, running \`npm run gen:db-schema\` in ${projectRoot}`);
     try {
         await new Promise((resolve) => {
-            const proc = (0, node_child_process_1.spawn)('npm', ['run', 'gen:db-schema'], {
+            const proc = (0, run_npm_1.spawnNpm)(['run', 'gen:db-schema'], {
                 stdio: ['ignore', 'pipe', 'pipe'],
                 cwd: projectRoot,
             });
             // --verbose：实时透传到 stderr 看进度；默认完全静默丢弃。
             // 任何路径下子进程输出都不会进入当前 CLI 的 stdout，--json 模式安全。
             // 注：默认路径必须 attach 监听器，否则 pipe 缓冲区写满会反压子进程。
+            // `?.`：stdio 走数组形式时 node 类型上 stdout/stderr 可为 null。这里 fd1/fd2
+            // 显式给了 'pipe'，实际恒非 null；真为 null 也意味着不是 pipe、不存在缓冲反压。
             if (verbose) {
-                proc.stdout.pipe(process.stderr);
-                proc.stderr.pipe(process.stderr);
+                proc.stdout?.pipe(process.stderr);
+                proc.stderr?.pipe(process.stderr);
             }
             else {
-                proc.stdout.on('data', drainChunk);
-                proc.stderr.on('data', drainChunk);
+                proc.stdout?.on('data', drainChunk);
+                proc.stderr?.on('data', drainChunk);
             }
             let timedOut = false;
             const timer = setTimeout(() => {

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/cli/handlers/plugin/plugin-local.js

@@ -56,10 +56,11 @@ exports.readAllCapabilities = readAllCapabilities;
 exports.hydrateCapability = hydrateCapability;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const node_child_process_1 = require("node:child_process");
 const node_module_1 = require("node:module");
+const archive_1 = require("../../../utils/archive");
 const error_1 = require("../../../utils/error");
 const logger_1 = require("../../../utils/logger");
+const run_npm_1 = require("../../../utils/run-npm");
 // ── Project paths ──
 function getProjectRoot() {
     return process.cwd();
@@ -152,7 +153,7 @@ function extractTgzToNodeModules(tgzPath, pluginName) {
     }
     node_fs_1.default.mkdirSync(tempDir, { recursive: true });
     try {
-        (0, node_child_process_1.execSync)(`tar -xzf "${tgzPath}" -C "${tempDir}"`, { stdio: 'pipe' });
+        (0, archive_1.extractTarGz)(tgzPath, tempDir);
         const extractedDir = node_path_1.default.join(tempDir, 'package');
         if (node_fs_1.default.existsSync(extractedDir)) {
             node_fs_1.default.renameSync(extractedDir, targetDir);
@@ -191,7 +192,7 @@ function installMissingDeps(deps) {
     if (deps.length === 0)
         return;
     (0, logger_1.log)('plugin', `Installing missing dependencies: ${deps.join(', ')}`);
-    const result = (0, node_child_process_1.spawnSync)('npm', ['install', ...deps, '--no-save', '--no-package-lock'], {
+    const result = (0, run_npm_1.runNpmSync)(['install', ...deps, '--no-save', '--no-package-lock'], {
         cwd: getProjectRoot(),
         stdio: 'inherit',
     });
@@ -205,7 +206,7 @@ function installMissingDeps(deps) {
     }
 }
 function npmInstall(tgzPath) {
-    const result = (0, node_child_process_1.spawnSync)('npm', ['install', tgzPath, '--no-save', '--no-package-lock', '--ignore-scripts'], { cwd: getProjectRoot(), stdio: 'inherit' });
+    const result = (0, run_npm_1.runNpmSync)(['install', tgzPath, '--no-save', '--no-package-lock', '--ignore-scripts'], { cwd: getProjectRoot(), stdio: 'inherit' });
     if (result.error) {
         throw new error_1.AppError('INTERNAL_NPM_FAILED', `npm install failed: ${result.error.message}`, {
             next_actions: ['确认本机已安装 npm，可 --verbose 查看执行详情'],

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

@@ -14,7 +14,8 @@
  *      + client/index.html 等 fullstack 形态新增的资产）
  *   5. 把 fullstack 必需的 scripts 加到 package.json（dev / build / type:check 等）
  *   6. 从 fullstack template/package.json 取版本号，精确加 NestJS 强依赖白名单
- *      （client-toolkit + 几个 @nestjs/* + fullstack-nestjs-core + hbs 等；不全量 merge）
+ *      （client-toolkit + 几个 @nestjs/* + SWC 工具链 + fullstack-nestjs-core + hbs 等；
+ *      不全量 merge）
  *   7. codemod 业务代码：@lark-apaas/client-toolkit-lite → @lark-apaas/client-toolkit
  *   8. codemod vite.config：defineConfig(...) → defineConfig(..., { fullstack: true })，
  *      让 coding-preset-vite-react 启用 fullstack dev-proxy / html-output / basename /
@@ -58,7 +59,9 @@ exports.MIGRATE_CONFIG = {
         // ===== 4. fullstack 形态必需资产（覆盖 user 已有同名文件） =====
         // server/ 整目录：main.ts / app.module.ts / common/ / modules/view/ 等（fullstack 必需）
         { type: 'directory', from: 'server', to: 'server', overwrite: true },
-        // nest-cli.json：nest build 入口
+        // nest-cli.json：整文件采用当前 fullstack template，除 Nest build 入口外还必须带上
+        // compilerOptions.builder.type=swc 及配套 typeCheck/options。若这里只保留旧的空配置
+        // 或字段级残缺合并，即使 package.json 已补齐 SWC 依赖，Nest 仍会回退到 TSC 构建。
         { type: 'file', from: 'nest-cli.json', to: 'nest-cli.json', overwrite: true },
         // tsconfig.* —— vite-react 时代 tsconfig 配 include: ["src"]，迁完代码搬到 client/src，
         // include 路径不对 + 老 tsconfig.app 还 extends @lark-apaas/coding-presets-react；
@@ -272,6 +275,14 @@ exports.MIGRATE_CONFIG = {
                 // nest start / nest build 必需
                 '@nestjs/cli',
                 '@nestjs/testing',
+                // nest-cli.json 会被上面的 file rule 覆盖成 builder.type=swc。Nest CLI 只负责
+                // 调度 builder，不会自带 SWC 可执行入口和 native compiler；两者必须一起从
+                // 当前目标模板取版本写入迁移后 package.json。若漏掉，前端应用升级成全栈后
+                // 配置已经选择 SWC，但全新的依赖安装树里找不到 @swc/cli/@swc/core，冷启动和
+                // nest build 会失败；开发机旧 node_modules 偶然残留 SWC 时还可能掩盖该问题。
+                // 这里不硬编码版本，保持升级应用与同版本新建全栈应用使用完全相同的 SWC 组合。
+                '@swc/cli',
+                '@swc/core',
                 // server ts 编译
                 'ts-node',
                 '@types/express',

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

@@ -159,6 +159,12 @@ 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',
+        },
         // ===== 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/app/init/async-install.js

@@ -11,13 +11,24 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const env_1 = require("../../../utils/env");
 const install_1 = require("./install");
-/** event marker 目录，写死；写前 mkdir -p。沙箱里 code server 轮询此目录。 */
+/**
+ * event marker 目录，写死 `/tmp/event`；写前 mkdir -p。沙箱里 code server 轮询此目录，
+ * 路径是与平台约定的契约，**不能换成 os.tmpdir()**。所有读写它的代码路径都被
+ * isSandboxEnv() 守着（沙箱恒为 Linux），非沙箱环境不会碰。
+ */
 const EVENT_DIR = '/tmp/event';
 /** 安装成功 marker 名 */
 const MARKER_READY = 'WORKSPACE_READY';
 /** 安装失败 marker 名 */
 const MARKER_FAILED = 'WORKSPACE_FAILED';
-/** 后台 worker stdout/stderr 落盘路径 */
+/**
+ * 后台 worker stdout/stderr 落盘路径，写死 `/tmp/...`。
+ *
+ * 刻意**不**换成 `os.tmpdir()`：这个路径已经是对外契约 —— 写在 async-install 设计
+ * spec 里、`app init` 的 help 文案里、失败 marker 的 `logPath` 字段里，用户与平台
+ * 都按它 cat 日志。Windows 上 Node 会把 `/tmp` 解析到当前盘符根下的 `\tmp\`，
+ * 目录可写、内容可读，功能不受影响，不值得为此破坏契约。
+ */
 exports.ASYNC_INSTALL_LOG = '/tmp/async_install_dep.std.log';
 function nowIso() {
     return new Date().toISOString();

package/dist/services/app/init/install.js

@@ -5,12 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.installDependencies = installDependencies;
 exports.resolveNpmInstallRegistry = resolveNpmInstallRegistry;
-const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const archive_1 = require("../../../utils/archive");
 const error_1 = require("../../../utils/error");
 const logger_1 = require("../../../utils/logger");
+const run_npm_1 = require("../../../utils/run-npm");
 const DEP_CACHE_ENV = 'MIAODA_DEP_CACHE_DIR';
 /**
  * 依赖安装。
@@ -94,7 +95,7 @@ function md5File(filePath) {
 }
 function extractZip(zipPath, targetDir, stdio) {
     try {
-        (0, node_child_process_1.execFileSync)('unzip', ['-q', '-o', zipPath, '-d', targetDir], { stdio });
+        (0, archive_1.extractZip)(zipPath, targetDir, { stdio });
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -129,5 +130,5 @@ function runNpmInstall(targetDir, stdio, extraPackages) {
         args.push(...extraPackages);
     }
     (0, logger_1.log)('init', `npm ${args.join(' ')} in ${targetDir}...`);
-    (0, node_child_process_1.execFileSync)('npm', args, { cwd: targetDir, stdio });
+    (0, run_npm_1.execNpmSync)(args, { cwd: targetDir, stdio });
 }

package/dist/services/deploy/modern/atoms/build.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runBuild = runBuild;
-const node_child_process_1 = require("node:child_process");
 const error_1 = require("../../../../utils/error");
 const logger_1 = require("../../../../utils/logger");
+const run_npm_1 = require("../../../../utils/run-npm");
 const protocol_1 = require("../protocol");
 /**
  * 给 RESOURCE_CDN_PREFIX 补 https:// 协议头：
@@ -33,7 +33,7 @@ function ensureHttpsScheme(v) {
  * 是 runtime 同域相对路径（例如 /app/<appId>/runtime/api/v1/storage/object/<bucket>/），
  * 不补 https scheme，原样注入。顶层 static_cdn_prefix 不再下发。
  *
- * build 失败抛 AppError（execSync 自身会 throw，捕获后包一层加错误码）。
+ * build 失败抛 AppError（execNpmSync 自身会 throw，捕获后包一层加错误码）。
  */
 function runBuild(opts) {
     const staticCred = (0, protocol_1.parsePaasStorageCredential)((0, protocol_1.requireDataKey)(opts.data, protocol_1.DataKey.OUTPUT_STATIC_PAAS_STORAGE_CREDENTIAL), protocol_1.DataKey.OUTPUT_STATIC_PAAS_STORAGE_CREDENTIAL);
@@ -47,7 +47,7 @@ function runBuild(opts) {
     };
     (0, logger_1.log)('deploy', 'Building...');
     try {
-        (0, node_child_process_1.execSync)('npm run build', {
+        (0, run_npm_1.execNpmSync)(['run', 'build'], {
             cwd: opts.projectDir,
             stdio: 'inherit',
             env: buildEnv,

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/atoms/tosutil.js

@@ -18,15 +18,13 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const error_1 = require("../../../../utils/error");
 const logger_1 = require("../../../../utils/logger");
+const which_1 = require("../../../../utils/which");
 function resolveTosutilPath() {
-    try {
-        const resolved = (0, node_child_process_1.execFileSync)('which', ['tosutil'], { encoding: 'utf-8' }).trim();
-        if (resolved)
-            return resolved;
-    }
-    catch {
-        /* fallthrough */
-    }
+    // 用 whichSync 而不是 shell out `which`：Windows 上没有 `which`（对应 `where`），
+    // 且查 PATH 本身不需要子进程。
+    const resolved = (0, which_1.whichSync)('tosutil');
+    if (resolved !== undefined)
+        return resolved;
     throw new error_1.AppError('DEPLOY_TOSUTIL_MISSING', 'tosutil is not installed or not in PATH. modern deploy requires sandbox preinstalled tosutil.');
 }
 function tosutilUploadFromTos(cred) {

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/archive.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetArchiveProbeCache = resetArchiveProbeCache;
+exports.extractTarGz = extractTarGz;
+exports.extractZip = extractZip;
+const node_child_process_1 = require("node:child_process");
+const error_1 = require("../utils/error");
+const logger_1 = require("../utils/logger");
+const which_1 = require("../utils/which");
+/**
+ * 归档解压的跨平台入口 —— 仓库内所有解压必须走这里，禁止再裸写
+ * `execFileSync('unzip', ...)` / `execSync('tar -xzf ...')`。
+ *
+ * 平台差异：
+ *   - `tar`：Linux（GNU tar）、macOS（bsdtar）、Windows 10 1803+（内置 bsdtar）都有，
+ *     且都支持 `-xzf` 解 .tar.gz，所以 tar.gz 一条路走到底。
+ *   - `unzip`：Linux / macOS 常见，**Windows 完全没有**。但 bsdtar 能解 zip，
+ *     所以 zip 走 `unzip → tar` 两级探测：Linux 命中 unzip，Windows 命中 tar。
+ *     （GNU tar 不支持 zip，所以顺序不能反 —— Linux 上必须优先 unzip。）
+ *
+ * 一律用 execFileSync 传参数数组、不过 shell：路径含空格 / 中文 / `&` 时，
+ * 拼字符串交给 cmd.exe 或 sh 重新分词的行为在各平台不一致，且是注入面。
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 为什么**不**换成纯 JS 解压库（adm-zip / yauzl / node-tar）—— 别再尝试了：
+ *
+ * `extractZip` 的主要用途是解依赖缓存 zip（`MIAODA_DEP_CACHE_DIR`），内容是整个
+ * `node_modules/`。实测对比同一个 zip：
+ *
+ *   |          | Unix mode      | 软链                 |
+ *   | unzip    | 755 保留        | 保留                 |
+ *   | adm-zip  | 666（执行位丢） | 被当普通文件解开      |
+ *
+ * `node_modules/.bin/*` 既需要执行位、又大量是软链 —— 用 adm-zip 解出来的缓存，
+ * 沙箱里 `npm run dev` 会直接挂。yauzl 更低层，mode 得自己从
+ * `externalFileAttributes` 还原、软链也要自己判，等于把 unzip 重写一遍。
+ *
+ * node-tar 倒是保权限 + 软链（npm 自己用它装包），但装出来 2.9MB、连传递依赖
+ * +3.7MB —— 而本仓生产依赖总共才 1.7MB，翻 3 倍多。CLI 是 `npx -y` 拉起的
+ * （模板 `scripts/dev.sh` 每次本地启动都会跑 `app sync`），冷启动下载量直接可感。
+ * 外部 tar 在 Linux / macOS / Windows 10 1803+ 都有，不值得为此付这个代价。
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+/** tar 可用性探测结果缓存（单次 CLI 执行期内 PATH 不变） */
+let tarAvailable;
+let unzipAvailable;
+function hasTar() {
+    tarAvailable ??= (0, which_1.whichSync)('tar') !== undefined;
+    return tarAvailable;
+}
+function hasUnzip() {
+    unzipAvailable ??= (0, which_1.whichSync)('unzip') !== undefined;
+    return unzipAvailable;
+}
+/** 仅测试用：清掉可用性探测缓存 */
+function resetArchiveProbeCache() {
+    tarAvailable = undefined;
+    unzipAvailable = undefined;
+}
+/**
+ * 解 .tar.gz / .tgz 到 `destDir`（须已存在）。失败抛 `INTERNAL_EXTRACT_FAILED`。
+ */
+function extractTarGz(archivePath, destDir, options = {}) {
+    if (!hasTar()) {
+        throw new error_1.AppError('INTERNAL_EXTRACT_FAILED', `解压 ${archivePath} 需要 tar，但当前环境 PATH 中找不到`, {
+            next_actions: [
+                'Linux/macOS：安装 tar（通常已内置）',
+                'Windows：升级到 Windows 10 1803+（内置 tar），或安装 Git for Windows 并把其 usr/bin 加入 PATH',
+            ],
+        });
+    }
+    (0, logger_1.debug)(`archive: tar -xzf ${archivePath} -C ${destDir}`);
+    (0, node_child_process_1.execFileSync)('tar', ['-xzf', archivePath, '-C', destDir], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        ...options,
+    });
+}
+/**
+ * 解 .zip 到 `destDir`（须已存在），同名文件覆盖。失败抛 `INTERNAL_EXTRACT_FAILED`。
+ *
+ * unzip 优先（Linux 上唯一可用项），退化到 bsdtar（Windows 上唯一可用项）。
+ */
+function extractZip(archivePath, destDir, options = {}) {
+    const stdio = ['ignore', 'pipe', 'pipe'];
+    if (hasUnzip()) {
+        (0, logger_1.debug)(`archive: unzip -q -o ${archivePath} -d ${destDir}`);
+        (0, node_child_process_1.execFileSync)('unzip', ['-q', '-o', archivePath, '-d', destDir], { stdio, ...options });
+        return;
+    }
+    if (hasTar()) {
+        // bsdtar 按后缀自动识别 zip，故用 -xf 而非 -xzf（zip 不是 gzip 流）。
+        // 覆盖行为与 `unzip -o` 一致：tar 默认覆盖已存在文件。
+        (0, logger_1.debug)(`archive: tar -xf ${archivePath} -C ${destDir}（unzip 不可用，走 bsdtar）`);
+        (0, node_child_process_1.execFileSync)('tar', ['-xf', archivePath, '-C', destDir], { stdio, ...options });
+        return;
+    }
+    throw new error_1.AppError('INTERNAL_EXTRACT_FAILED', `解压 ${archivePath} 需要 unzip 或 tar，但当前环境 PATH 中两者都找不到`, {
+        next_actions: [
+            'Linux：apt-get install unzip / yum install unzip',
+            'Windows：升级到 Windows 10 1803+（内置 tar 可解 zip）',
+        ],
+    });
+}

package/dist/utils/coding-steering.js

@@ -237,7 +237,33 @@ function syncCodingSteering(opts) {
  *   - 已是软链但指错地方：删旧的，建新的（updated）
  *   - 已是普通目录 / 文件：不覆盖，警告并跳过（conflict）—— 用户可能手动放了别的 skills
  *   - 不存在：建新的（created）
+ *
+ * 软链建不出来时返回 unsupported 而不是抛错：Windows 上非管理员且未开「开发者模式」
+ * 时 symlinkSync 报 EPERM，这不该让整条 steering 同步（进而 app init / app sync）失败。
+ * 退化后果是 Claude Code 默认路径读不到 skills —— 功能降级但项目可用，且日志里给了
+ * 明确的开启方式。不做「复制代替软链」的兜底：那会让两份内容各自漂移，比读不到更糟。
+ */
+/**
+ * 建目录软链，失败只 warn 不抛。返回是否建成。
+ *
+ * 主要挡的是 Windows 的 EPERM（创建软链需要 SeCreateSymbolicLinkPrivilege，
+ * 默认只给管理员；开启「开发者模式」后普通用户也可以）。其它 errno 一样按降级处理 ——
+ * 这一步是锦上添花，不值得中断整次同步。
  */
+function trySymlink(linkTarget, linkPath, logPrefix) {
+    try {
+        node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
+        return true;
+    }
+    catch (err) {
+        const code = err.code ?? 'UNKNOWN';
+        const hint = process.platform === 'win32'
+            ? '（Windows 需以管理员运行，或在「设置 → 隐私和安全性 → 开发者选项」开启开发者模式）'
+            : '';
+        (0, logger_2.log)(logPrefix, `  ⚠ .claude/skills 软链创建失败 [${code}]，跳过${hint}；skills 仍在 .agents/skills 下可用`);
+        return false;
+    }
+}
 function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
     const linkPath = node_path_1.default.join(targetDir, '.claude', 'skills');
     const linkTarget = node_path_1.default.join('..', '.agents', 'skills');
@@ -251,7 +277,8 @@ function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
             throw err;
     }
     if (existing === null) {
-        node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
+        if (!trySymlink(linkTarget, linkPath, logPrefix))
+            return 'unsupported';
         (0, logger_2.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink created)`);
         return 'created';
     }
@@ -261,7 +288,8 @@ function ensureClaudeSkillsSymlink(targetDir, logPrefix) {
             return 'noop';
         }
         node_fs_1.default.unlinkSync(linkPath);
-        node_fs_1.default.symlinkSync(linkTarget, linkPath, 'dir');
+        if (!trySymlink(linkTarget, linkPath, logPrefix))
+            return 'unsupported';
         (0, logger_2.log)(logPrefix, `  ✓ .claude/skills → ${linkTarget} (symlink updated, was → ${current})`);
         return 'updated';
     }

package/dist/utils/file-ops.js

@@ -63,7 +63,15 @@ function removeLineFromContent(content, pattern) {
 // 不碰权限 —— 它跑在同一次调用里、紧随 syncSandboxSkills 之后，目录已经可写；
 // 各写入方各自 chmod 会与收尾的 lockDirReadonly 形成隐式耦合，范围一旦不对称就会
 // 出「跑一次 skills sync 把整个 skills 目录解封」这种事。
+//
+// **平台前提**：整套只读锁语义是 POSIX mode 位的，靠 shell `chmod -R` 实现。Windows
+// 没有对应概念（NTFS 用 ACL，mode 位不映射），所以那里直接跳过加解锁 —— 锁和解锁
+// 成对失效，语义仍自洽：目录始终可写，只是少了「防手改」这层保护。这是有意的降级，
+// 不是遗漏；不用 fs.chmodSync 模拟，因为它在 Windows 上对目录基本是 no-op，
+// 只会制造「以为锁上了」的假象。
 // ─────────────────────────────────────────────────────────────────────────────
+/** POSIX mode 位语义是否可用；Windows 上整套只读锁降级为 no-op */
+const SUPPORTS_POSIX_MODE = process.platform !== 'win32';
 /**
  * 解锁目录使其可写（`chmod -R u+w`）。
  *
@@ -71,8 +79,12 @@ function removeLineFromContent(content, pattern) {
  * 只加 owner 写位、不动 g/o，与老链路一致。目录不存在直接返回 false（调用方
  * 通常紧接着 mkdir）。失败只 debug 不抛：解锁是尽力而为，真写不进去让后续
  * 写操作自己报错，错误信息更具体。
+ *
+ * Windows 返回 false（没上过锁，也就无需解锁）。
  */
 function unlockDirForWrite(dir) {
+    if (!SUPPORTS_POSIX_MODE)
+        return false;
     if (!node_fs_1.default.existsSync(dir))
         return false;
     try {
@@ -92,8 +104,12 @@ function unlockDirForWrite(dir) {
  * {@link unlockDirForWrite}。
  *
  * **调用时机必须是全部写入完成之后**——锁上就写不进去了。
+ *
+ * Windows 直接返回 false（不加锁，对应 unlockDirForWrite 也不解锁）。
  */
 function lockDirReadonly(dir) {
+    if (!SUPPORTS_POSIX_MODE)
+        return false;
     if (!node_fs_1.default.existsSync(dir))
         return false;
     try {
@@ -112,18 +128,22 @@ function lockDirReadonly(dir) {
  * 只读锁下；另外老 update.sh 曾以 root 跑过，可能留下异主文件（如 root-owned 的
  * `.last-update`），`rmSync{force:true}` 只忽略 ENOENT、遇 EACCES 仍抛。
  * shell `rm -rf` 对异主文件 / 怪符号链接比 rmSync 宽容，故作主档。
+ *
+ * Windows 上没有 `rm`（也没有异主/只读锁那套前提），直接走 `fs.rmSync` 这一层。
  */
 function forceRemove(target) {
     if (!node_fs_1.default.existsSync(target))
         return;
-    unlockDirForWrite(target);
-    try {
-        (0, node_child_process_1.execFileSync)('rm', ['-rf', target], { stdio: ['ignore', 'ignore', 'pipe'] });
-        if (!node_fs_1.default.existsSync(target))
-            return;
-    }
-    catch (err) {
-        (0, logger_1.debug)(`file-ops: rm -rf ${target} failed: ${err.message}`);
+    if (SUPPORTS_POSIX_MODE) {
+        unlockDirForWrite(target);
+        try {
+            (0, node_child_process_1.execFileSync)('rm', ['-rf', target], { stdio: ['ignore', 'ignore', 'pipe'] });
+            if (!node_fs_1.default.existsSync(target))
+                return;
+        }
+        catch (err) {
+            (0, logger_1.debug)(`file-ops: rm -rf ${target} failed: ${err.message}`);
+        }
     }
     node_fs_1.default.rmSync(target, { recursive: true, force: true });
 }

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/npm-pack.js

@@ -6,12 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.pickLaneVersion = pickLaneVersion;
 exports.extractLaneFromTgzKey = extractLaneFromTgzKey;
 exports.fetchNpmPackage = fetchNpmPackage;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
+const archive_1 = require("./archive");
 const error_1 = require("./error");
 const logger_1 = require("./logger");
+const run_npm_1 = require("./run-npm");
 const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/';
 /**
  * 从 `npm view <pkg> versions --json` 里过滤出后缀 `-alpha.<X>` 的版本。
@@ -29,7 +30,7 @@ function pickLaneVersion(packageName, X, registry) {
     const reg = registry ?? process.env.MIAODA_NPM_REGISTRY ?? DEFAULT_REGISTRY;
     const suffix = `-alpha.${X}`;
     try {
-        const stdout = (0, node_child_process_1.execFileSync)('npm', ['view', packageName, 'versions', '--json', '--registry', reg], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const stdout = (0, run_npm_1.execNpmSyncCapture)(['view', packageName, 'versions', '--json', '--registry', reg], { stdio: ['pipe', 'pipe', 'pipe'] });
         const versions = JSON.parse(stdout);
         if (!Array.isArray(versions))
             return null;
@@ -75,7 +76,7 @@ function extractLaneFromTgzKey(tgzKey) {
     return lane;
 }
 /**
- * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
+ * `npm pack <pkg>@<ver> --registry <r>` + 解压（走 archive 跨平台封装），解到临时目录。
  * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。
  */
 function fetchNpmPackage(opts) {
@@ -85,7 +86,7 @@ function fetchNpmPackage(opts) {
     const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-pack-'));
     try {
         (0, logger_1.debug)(`npm pack ${pkgSpec} --registry ${registry} → ${tmpDir}`);
-        const stdout = (0, node_child_process_1.execFileSync)('npm', ['pack', pkgSpec, '--pack-destination', tmpDir, '--json', '--registry', registry], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const stdout = (0, run_npm_1.execNpmSyncCapture)(['pack', pkgSpec, '--pack-destination', tmpDir, '--json', '--registry', registry], { stdio: ['pipe', 'pipe', 'pipe'] });
         const packInfo = JSON.parse(stdout);
         const tgzFilename = packInfo[0]?.filename;
         const pkgVersion = packInfo[0]?.version ?? version;
@@ -95,9 +96,7 @@ function fetchNpmPackage(opts) {
         const tgzPath = node_path_1.default.join(tmpDir, tgzFilename);
         const extractDir = node_path_1.default.join(tmpDir, 'extracted');
         node_fs_1.default.mkdirSync(extractDir, { recursive: true });
-        (0, node_child_process_1.execFileSync)('tar', ['-xzf', tgzPath, '-C', extractDir], {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        (0, archive_1.extractTarGz)(tgzPath, extractDir);
         return {
             extractDir: node_path_1.default.join(extractDir, 'package'),
             version: pkgVersion,

package/dist/utils/run-npm.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execNpmSync = execNpmSync;
+exports.execNpmSyncCapture = execNpmSyncCapture;
+exports.runNpmSync = runNpmSync;
+exports.spawnNpm = spawnNpm;
+const cross_spawn_1 = __importDefault(require("cross-spawn"));
+const error_1 = require("../utils/error");
+const logger_1 = require("../utils/logger");
+/**
+ * 跨平台 npm 执行入口 —— 仓库内**所有** npm 调用必须走这里，禁止再裸写
+ * `execFileSync('npm', ...)` / `spawnSync('npm', ...)` / `spawn('npm', ...)`，
+ * 也禁止直接 import `cross-spawn` 绕过这层（两条都由 ESLint 强制）。
+ *
+ * 为什么必须封装：Windows 上 npm 不是可执行文件而是 `npm.cmd` 批处理包装。
+ *   - `execFile` / `spawn` 不带 shell 时按可执行文件解析，命中不到 `npm` → ENOENT；
+ *   - 自 Node 18.20.2 / 20.12.2（CVE-2024-27980）起，不带 `shell: true` 执行
+ *     `.cmd` / `.bat` 会直接抛 EINVAL，连"碰巧能跑"都不再成立。
+ *
+ * 为什么用 `cross-spawn` 而不是自己处理：正确的做法不只是"加 shell"。cross-spawn
+ * 在 Windows 上先判断目标是否真可执行文件，只在需要时切到 cmd.exe，并对参数做完整的
+ * 元字符转义（还专门处理了 `node_modules/.bin/*.cmd` 这类 cmd-shim 需要**双重**转义
+ * 的情况）。这些边角自己写必定漏，而它是 5000 万周下载量级的生态基建。
+ *
+ * 这层封装自身只做三件事：钉死命令名为 `npm`、把 spawn 结果的失败语义统一成
+ * `AppError`、给调用点一个稳定的收口位置。
+ */
+/** npm 子进程失败时统一抛的错误码 */
+const NPM_FAILED_CODE = 'NPM_COMMAND_FAILED';
+/** stderr 被 pipe 时，附进错误信息的尾部长度上限（避免把整篇 npm 日志灌进 message） */
+const STDERR_TAIL_LIMIT = 800;
+/**
+ * 取 stderr 尾部拼进错误信息。
+ *
+ * 参数刻意收窄成结构类型并显式带 `null`：node 的 `SpawnSyncReturns.stderr` 类型上是
+ * 非空的，但 `stdio: 'inherit' | 'ignore'` 时运行时实际为 null（输出已直出或丢弃）。
+ * 照类型写会漏掉这种情况，照运行时写又会被 no-unnecessary-condition 判成多余判断 ——
+ * 所以在这里把真实契约写清楚。
+ */
+function stderrTail(result) {
+    const raw = result.stderr;
+    if (raw === null || raw === undefined)
+        return '';
+    const text = typeof raw === 'string' ? raw : raw.toString('utf-8');
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return '';
+    const tail = trimmed.length > STDERR_TAIL_LIMIT ? trimmed.slice(-STDERR_TAIL_LIMIT) : trimmed;
+    return `\n${tail}`;
+}
+/**
+ * 把 spawnSync 结果里的失败翻译成 AppError。
+ *
+ * 两类失败要分开报，因为处置动作不同：
+ *   - `error` 非空 = 进程根本没起来（npm 不在 PATH、权限问题）；
+ *   - `status !== 0` = npm 起来了但命令失败（装包失败、脚本报错），此时 stderr 才有内容。
+ */
+function assertNpmOk(args, result) {
+    if (result.error) {
+        throw new error_1.AppError(NPM_FAILED_CODE, `npm 启动失败（npm ${args.join(' ')}）：${result.error.message}`, {
+            next_actions: ['确认本机已安装 npm 且在 PATH 中', '可加 --verbose 查看执行详情'],
+        });
+    }
+    if (result.status !== 0) {
+        const code = result.status === null ? `signal ${String(result.signal)}` : `exit ${String(result.status)}`;
+        throw new error_1.AppError(NPM_FAILED_CODE, `npm ${args.join(' ')} 失败（${code}）${stderrTail(result)}`, { next_actions: ['检查上方 npm 输出定位具体错误'] });
+    }
+}
+/**
+ * 同步跑 npm，失败抛 `NPM_COMMAND_FAILED`（对齐原先 `execFileSync('npm', args)` 的
+ * "失败即抛"语义）。`stdio` 等选项原样透传。
+ */
+function execNpmSync(args, options = {}) {
+    (0, logger_1.debug)(`run-npm: npm ${args.join(' ')}`);
+    const result = cross_spawn_1.default.sync('npm', args, options);
+    assertNpmOk(args, result);
+}
+/**
+ * 同步跑 npm 并拿回 stdout 字符串，失败抛 `NPM_COMMAND_FAILED`。
+ * 用于需要解析输出的场景（如 `npm pack --json`）。
+ */
+function execNpmSyncCapture(args, options = {}) {
+    (0, logger_1.debug)(`run-npm: npm ${args.join(' ')} (capture)`);
+    const result = cross_spawn_1.default.sync('npm', args, { ...options, encoding: 'utf-8' });
+    assertNpmOk(args, result);
+    return result.stdout;
+}
+/**
+ * 同步跑 npm，**不抛错**，返回 spawnSync 结果（对齐 `spawnSync('npm', args)` 的语义）。
+ * 调用方自行判 `error` / `status` —— 用于需要把失败当正常分支处理的场景。
+ */
+function runNpmSync(args, options = {}) {
+    (0, logger_1.debug)(`run-npm: npm ${args.join(' ')} (no-throw)`);
+    return cross_spawn_1.default.sync('npm', args, options);
+}
+function spawnNpm(args, options = {}) {
+    (0, logger_1.debug)(`run-npm: npm ${args.join(' ')} (async)`);
+    return (0, cross_spawn_1.default)('npm', args, options);
+}

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);
         }

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/dist/utils/which.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whichSync = whichSync;
+const which_1 = __importDefault(require("which"));
+/**
+ * 跨平台可执行文件查找 —— 仓库内查 PATH 的唯一入口，禁止 shell out `which`。
+ *
+ * 为什么不 shell out：`which` 在 Windows 上不存在（对应的是 `where`），而 `where`
+ * 的输出格式与退出码语义又跟 `which` 不同。
+ *
+ * 为什么用社区 `which` 包而不是自己遍历 PATH：Windows 要按 PATHEXT 逐个后缀试探
+ * （`npm` 实际是 `npm.cmd`），POSIX 要看执行位，还有 all / delimiter 这些边角。
+ * 这些是 npm 官方维护的 `which` 已经做完并被全生态验证过的事，自己写只会漏。
+ *
+ * 保留这层薄封装而不是让各处直接 `import which`，是为了：
+ *   1. 把 `null`（社区库的「没找到」）归一成仓库内统一的 `undefined` optional 语义；
+ *   2. 留一个收口点 —— 换实现、加缓存、加平台特例都只改这里；
+ *   3. 配合 ESLint no-restricted-imports，保证不会有人绕过去直接用。
+ */
+function whichSync(name) {
+    if (name === '')
+        return undefined;
+    return which_1.default.sync(name, { nothrow: true }) ?? undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.38",
+  "version": "0.1.39-alpha.2875384",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -29,12 +29,16 @@
   "dependencies": {
     "@lark-apaas/http-client": "^0.1.5",
     "commander": "^13.1.0",
+    "cross-spawn": "^7.0.6",
     "jsonc-parser": "^3.3.1",
     "ora": "^5.4.1",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "which": "^7.0.0"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22.15.3",
+    "@types/which": "^3.0.4",
     "@typescript-eslint/eslint-plugin": "^8.58.2",
     "@typescript-eslint/parser": "^8.58.2",
     "@vitest/coverage-v8": "^4.1.4",

package/upgrade/templates/nestjs-react-fullstack/templates/nest-cli.json

@@ -11,15 +11,6 @@
         "outDir": "dist/server",
         "watchAssets": true
       }
-    ],
-    "plugins": [
-      {
-        "name": "@nestjs/swagger",
-        "options": {
-          "introspectComments": true,
-          "classValidatorShim": true
-        }
-      }
     ]
   }
-}
+}