@lark-apaas/miaoda-cli 0.1.16 → 0.1.17-alpha.ddef3e9

package/dist/cli/commands/app/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAppCommands = registerAppCommands;
+const commander_1 = require("commander");
 const shared_1 = require("../../../cli/commands/shared");
 const index_1 = require("../../../cli/handlers/app/index");
+const index_2 = require("../../../config/migrate-configs/index");
 const error_1 = require("../../../utils/error");
 function registerAppCommands(program, opts = {}) {
     const description = opts.includeInit
@@ -22,8 +24,49 @@ function registerAppCommands(program, opts = {}) {
     if (opts.includeInit) {
         registerAppInit(appCmd);
         registerAppSync(appCmd);
+        registerAppMigrate(appCmd);
     }
 }
+function registerAppMigrate(parent) {
+    const supportedDesc = (0, index_2.listSupportedMigrations)()
+        .map((m) => `${m.from} → ${m.to}`)
+        .join(', ');
+    // 渐进式披露：migrate 是给妙搭平台 / 用户主动触发的命令，**不暴露给 Agent**。
+    //   - `miaoda app -h` / `miaoda app help` 都不列出此命令
+    //   - 但 `miaoda app migrate --to xxx` 仍能直接调用（仅命令注册时打 hidden 标记，行为不变）
+    //   - `--help` 也不显示 ——commander hidden 命令仅显式 invoke 时才暴露
+    // 用 addCommand(cmd, { hidden: true }) 而非 parent.command(...)，因为 commander 13
+    // 的 fluent `.command()` 不支持设置 hidden。
+    const cmd = new commander_1.Command('migrate')
+        .description('跨 stack 原地迁移：按 MigrateConfig 全套 apply（move + delete + 模板覆盖 + 字段 merge + set-stack）')
+        .requiredOption('--to <stack>', '目标 stack 短名')
+        .option('--from <stack>', '源 stack；默认读 .spark/meta.json 当前 stack')
+        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .addHelpText('after', `
+已支持的迁移路径
+  ${supportedDesc || '(none)'}
+
+JSON 输出
+  {"data": {"from": "...", "to": "...",
+            "appliedRules": [{"type": "...", "action": "...", "path": "...", "detail": "..."}],
+            "moved": [...], "deleted": [...], "synced": [...], "merged": [...], "patched": [...],
+            "skipped": N,
+            "nextActions": [...]}}
+
+示例
+  $ miaoda app migrate --to nestjs-react-fullstack
+  $ miaoda app migrate --from vite-react --to nestjs-react-fullstack
+  $ miaoda app migrate --to nestjs-react-fullstack --dir /path/to/app
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleAppMigrate)({
+            dir: rawOpts.dir,
+            from: rawOpts.from,
+            to: rawOpts.to,
+        });
+    }));
+    parent.addCommand(cmd, { hidden: true });
+}
 function registerAppSync(parent) {
     const cmd = parent
         .command('sync')
@@ -123,6 +166,7 @@ function registerAppInit(parent) {
         .option('--template <stack>', `技术栈短名（${index_1.SUPPORTED_STACKS.join(' / ')}）`)
         .option('--conf <json>', 'init 配置 JSON。支持 {"version": "<template 版本>"}，默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
+        .option('--async-install', '派发后台进程装依赖并立即返回（与 --skip-install 互斥）', false)
         .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
 幂等
@@ -151,17 +195,31 @@ function registerAppInit(parent) {
     为空都会 fallback npm install。
   JSON 模式下子进程 stdout 重定向到 stderr，避免污染最终 emit 的 JSON。
 
+异步安装（--async-install）
+  跳过同步 npm install，派发一个 detached 后台进程装依赖后立即返回。
+  .spark/meta.json 在返回前写出（= 脚手架就绪），install 真实结果由 event marker 表达。
+  仅沙箱（SANDBOX_ID 非空）写 marker（presence 定成败，content 给排障）：
+    成功 → /tmp/event/WORKSPACE_READY
+    失败 → /tmp/event/WORKSPACE_FAILED
+  安装日志：/tmp/async_install_dep.std.log
+  失败恢复：靠后续 'miaoda app sync'（dev.sh 入口 / 沙箱 pod 启动会跑）兜底，init 不重试。
+  与 --skip-install 互斥。
+
 JSON 输出
   已初始化：{"data": {"initialized": false, "reason": "already_initialized", "targetDir": "..."}}
   新初始化：{"data": {"initialized": true, "template": "...", "templateVersion": "...", "steeringVersion": "...",
                      "appId": "...", "platformStackFound": true, "platformSyncedFiles": [...],
                      "installed": true, "installSource": "cache|npm|skipped", "installHash": "...", ...}}
+  async 模式：{"data": {"initialized": true, "asyncInstall": true, "installed": false,
+                      "installSource": "async", "installPid": 123, "installLogPath": "...",
+                      "eventReadyPath": "...", "eventFailedPath": "..."}}
 
 示例
   $ miaoda app init --template vite-react
   $ miaoda app init --template nestjs-react-fullstack --app-id app_xxx
   $ miaoda app init --template vite-react --conf '{"version": "0.1.0"}'
   $ miaoda app init --template vite-react --skip-install
+  $ miaoda app init --template vite-react --async-install
   $ MIAODA_DEP_CACHE_DIR=/tmp/dep-cache miaoda app init --template vite-react
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
@@ -171,6 +229,7 @@ JSON 输出
             conf,
             skipInstall: rawOpts.skipInstall,
             appId: rawOpts.appId,
+            asyncInstall: rawOpts.asyncInstall,
         });
     }));
 }

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

@@ -16,6 +16,7 @@ function registerDeployCommandsModern(program) {
         .description('触发 modern 应用发布：本地构建 + 本地部署（preRelease + localPublish）')
         .option('--dir <path>', '项目目录', '.')
         .option('--skip-build', '跳过 build 步骤（已构建好时使用）', false)
+        .option('--conf <json>', '关联元信息 JSON，仅识别 checkPointVersion / commitID 两字段')
         .addHelpText('after', `
 不要用异步模式或后台模式调用 deploy，否则调用可能提前结束，Agent 会误判发布已完成。
 
@@ -32,6 +33,12 @@ function registerDeployCommandsModern(program) {
   6. savePluginInstances（扫描 dist/output_capabilities/*.json 批量注册）
   7. finalizeLocalRelease(Finished|Failed)
 
+--conf（关联元信息透传）
+  值为 JSON string，只识别两个字段，其余 key 忽略：
+    checkPointVersion  关联的 checkpoint 版本
+    commitID           关联的代码 commit ID
+  两字段均可选；非法 JSON / 非对象 / 字段值非字符串会报错。
+
 JSON 输出（stdout）
   {"data": {"appId": "...", "version": <n>, "url": "...", "releaseID": "...", "preReleaseID": "..."}}
 
@@ -39,12 +46,14 @@ JSON 输出（stdout）
   $ miaoda deploy
   $ miaoda deploy --dir ./my-app
   $ miaoda deploy --skip-build
+  $ miaoda deploy --conf '{"checkPointVersion":"v3","commitID":"a1b2c3d"}'
 `);
     deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
         await (0, modern_1.handleDeployModern)({
             dir: rawOpts.dir ?? '.',
             appId: (0, shared_1.resolveAppId)({}),
             skipBuild: rawOpts.skipBuild,
+            conf: rawOpts.conf,
         });
     }));
 }

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_STACKS = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
@@ -10,6 +10,8 @@ Object.defineProperty(exports, "handleAppInit", { enumerable: true, get: functio
 var sync_1 = require("./sync");
 Object.defineProperty(exports, "handleAppSync", { enumerable: true, get: function () { return sync_1.handleAppSync; } });
 Object.defineProperty(exports, "handleAppUpgrade", { enumerable: true, get: function () { return sync_1.handleAppUpgrade; } });
+var migrate_1 = require("./migrate");
+Object.defineProperty(exports, "handleAppMigrate", { enumerable: true, get: function () { return migrate_1.handleAppMigrate; } });
 // commands 层渲染 help 时需要这份枚举；从 handler barrel 转发，避免 commands → services 越界
 var index_1 = require("../../../services/app/init/index");
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return index_1.SUPPORTED_STACKS; } });

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

@@ -60,6 +60,9 @@ async function handleAppInit(opts) {
             next_actions: [`可用 stack：${index_1.SUPPORTED_STACKS.join(', ')}`],
         });
     }
+    if (opts.asyncInstall && opts.skipInstall) {
+        throw new error_1.AppError('ARGS_INVALID', '--async-install 与 --skip-install 互斥');
+    }
     const version = opts.conf?.version;
     const projectName = node_path_1.default.basename(targetDir);
     const tplResult = (0, index_1.renderTemplate)({ stack, version, targetDir, projectName });
@@ -86,13 +89,17 @@ async function handleAppInit(opts) {
         (0, logger_1.log)('init', `⚠ skills sync failed (continuing init): ${steeringError}`);
         steeringResult = { version: 'unknown', syncedSkills: [], techSynced: false };
     }
-    // 装模板钉死的依赖。不带 <pkg>@latest 位置参数,因此 npm 不会改写 package.json/lockfile
+    // 依赖安装：async 模式留到 meta 落盘后派发后台进程（不等装完），同步模式当场装。
+    // 同步：装模板钉死的依赖。不带 <pkg>@latest 位置参数,因此 npm 不会改写 package.json/lockfile
     // —— "升管控包到 latest" 是 sync 的职责,在 dev.sh 入口跑 `miaoda app sync` 时触发。
-    const installResult = (0, index_1.installDependencies)({
-        targetDir,
-        skip: opts.skipInstall,
-        quietStdout: (0, output_1.isJsonMode)(),
-    });
+    let installResult;
+    if (!opts.asyncInstall) {
+        installResult = (0, index_1.installDependencies)({
+            targetDir,
+            skip: opts.skipInstall,
+            quietStdout: (0, output_1.isJsonMode)(),
+        });
+    }
     // template 自带 .githooks/pre-commit；如果用户项目已 git init,顺便设上 core.hooksPath。
     const hookActivation = (0, githooks_1.activateGitHooks)(targetDir);
     (0, index_1.writeSparkMeta)(targetDir, {
@@ -101,8 +108,18 @@ async function handleAppInit(opts) {
         archType: tplResult.archType,
         app_id: opts.appId,
     });
+    // async 模式：meta 已落盘（= 脚手架就绪），再派发后台安装并立即返回（不等装完）。
+    let asyncDispatch;
+    if (opts.asyncInstall) {
+        asyncDispatch = (0, index_1.dispatchAsyncInstall)({ targetDir });
+    }
     if (!(0, output_1.isJsonMode)()) {
-        process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+        if (opts.asyncInstall && asyncDispatch) {
+            process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install dispatched in background pid ${String(asyncDispatch.pid)}) in ${targetDir}\n`);
+        }
+        else if (installResult) {
+            process.stdout.write(`✓ Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
+        }
     }
     (0, output_1.emit)({
         data: {
@@ -117,11 +134,23 @@ async function handleAppInit(opts) {
             techSynced: steeringResult.techSynced,
             steeringError,
             gitHooks: hookActivation.action,
-            installed: installResult.installed,
-            installSource: installResult.source,
-            installHash: installResult.hash,
-            cacheZip: installResult.cacheZip,
-            installError: installResult.error,
+            ...(opts.asyncInstall && asyncDispatch
+                ? {
+                    asyncInstall: true,
+                    installed: false,
+                    installSource: 'async',
+                    installPid: asyncDispatch.pid,
+                    installLogPath: asyncDispatch.logPath,
+                    eventReadyPath: asyncDispatch.eventReadyPath,
+                    eventFailedPath: asyncDispatch.eventFailedPath,
+                }
+                : {
+                    installed: installResult?.installed,
+                    installSource: installResult?.source,
+                    installHash: installResult?.hash,
+                    cacheZip: installResult?.cacheZip,
+                    installError: installResult?.error,
+                }),
         },
     });
 }

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

@@ -0,0 +1,251 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAppMigrate = handleAppMigrate;
+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 index_1 = require("../../../config/migrate-configs/index");
+const index_2 = require("../../../services/app/init/index");
+const migrate_rule_1 = require("../../../utils/migrate-rule");
+const spark_meta_1 = require("../../../utils/spark-meta");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const logger_1 = require("../../../utils/logger");
+/**
+ * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
+ *
+ * 跨 stack 原地迁移：把 user app 从源 stack（默认 .spark/meta.json 当前 stack）转到目标 stack。
+ * 同一个 git 仓库内进行，不动 git history，所有改动作为 working tree 变更体现，用户跑完后
+ * 自行 `git status` / `git diff` 评估并 commit。
+ *
+ * 跟 sync 的区别：sync 是同 stack 内的版本对齐，migrate 是跨 stack 切换（布局重排、依赖
+ * 集合切换、配置文件全套替换）。两条命令的 rule 引擎共享（applyMigrateRules 内部对
+ * SyncRule 委派给 applySyncRules）。
+ *
+ * 执行流：
+ *   1. 校验 user app 已 init（.spark/meta.json 存在）+ 当前 stack 匹配 from
+ *   2. 拿到 (from, to) 对应的 MigrateConfig 与模板源根目录
+ *   3. 顺序执行 rules：move-* → delete-* → delete-json-keys → file/directory →
+ *      merge-json → set-stack
+ *   4. 清掉 node_modules（package-lock.json 已经在 rules 里 delete），跑 npm install
+ *      物化新依赖集合 —— migrate 改了 dependencies / devDependencies 集合（删 lite +
+ *      加 NestJS 全套），不重装就跑不起来。
+ *      同一条 npm install 顺手把 config.followLatestPackages 钉 `@latest`，覆盖
+ *      template caret range 拉不到 pre-release 的盲区（详见 MigrateConfig 注释）。
+ *
+ * 不做事：
+ *   - 不自动 commit / stash —— 让用户自己用 git review 改动
+ *   - 不动 .agent/skills/（那是 miaoda skills sync 的事，迁移后用户应该单独跑一次切到新 stack 的 skills）
+ */
+async function handleAppMigrate(opts) {
+    await Promise.resolve();
+    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+    if (meta.stack === undefined || meta.stack === '') {
+        throw new error_1.AppError('MIGRATE_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+    }
+    const from = opts.from ?? meta.stack;
+    if (opts.from !== undefined && opts.from !== meta.stack) {
+        throw new error_1.AppError('MIGRATE_FROM_MISMATCH', `--from '${opts.from}' but current stack is '${meta.stack}'`, {
+            next_actions: ['省略 --from 让 cli 自动读 meta.json，或确认 user app 状态'],
+        });
+    }
+    if (from === opts.to) {
+        throw new error_1.AppError('MIGRATE_NOOP', `from and to are both '${from}', nothing to do`);
+    }
+    const config = (0, index_1.getMigrateConfig)(from, opts.to);
+    if (config === null) {
+        const supported = (0, index_1.listSupportedMigrations)()
+            .map((m) => `${m.from} → ${m.to}`)
+            .join(', ');
+        throw new error_1.AppError('MIGRATE_PATH_NOT_SUPPORTED', `no migrate config for '${from}' → '${opts.to}'`, {
+            next_actions: [`已支持：${supported || '(none)'}`],
+        });
+    }
+    // migrate 用 init 同款的 renderTemplate 拉目标 stack 的 npm template tarball 到 tmp，
+    // 再把 tmp 当作 sourceRoot 喂给 applyMigrateRules。这样 migrate config 里 file/directory
+    // rule 的 `from` 引用的是完整的 npm template 渲染产物，不需要在 upgrade/templates/ 重复
+    // 维护一份 server/ + client/ + 全套配置 —— 复杂度由 init 那条链路 amortize。
+    const tmpRoot = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-migrate-'));
+    const projectName = node_path_1.default.basename(targetDir);
+    let templateVersion;
+    let templateArchType;
+    let results;
+    try {
+        const tpl = (0, index_2.renderTemplate)({ stack: opts.to, targetDir: tmpRoot, projectName });
+        templateVersion = tpl.version;
+        templateArchType = tpl.archType;
+        // template package.json 的 user 私有字段（name / version / private 等）不参与 merge —— 否
+        // 则会被 deepMergeJson 当成 template 端"权威值"覆盖 user 项目原本的字段。这里在 tmp 端
+        // 直接 strip 这些字段，让 merge-json rule 只对 dependencies / devDependencies / scripts
+        // 等 schema-level 字段生效。
+        stripUserOwnedFields(node_path_1.default.join(tmpRoot, 'package.json'));
+        (0, logger_1.log)('migrate', `Rendered ${opts.to}@${tpl.version} to tmp, applying ${config.rules.length.toString()} rule(s)`);
+        results = (0, migrate_rule_1.applyMigrateRules)(config.rules, {
+            sourceRoot: tmpRoot,
+            targetDir,
+            logPrefix: 'migrate',
+        });
+    }
+    finally {
+        node_fs_1.default.rmSync(tmpRoot, { recursive: true, force: true });
+    }
+    // archType / version 字段同步：set-stack rule 只切 stack，archType 是从 npm template 包
+    // 的 miaodaTemplate.archType 拿到的动态值，rule 配置时不知道，由 handler 在拿到
+    // renderTemplate 结果后单独写。version 也一并写回方便 sync 后续诊断。
+    (0, spark_meta_1.writeSparkMeta)(targetDir, { archType: templateArchType, version: templateVersion });
+    // 清掉 user app 的 node_modules —— migrate 改了 dependencies 集合（删 lite + 加 NestJS
+    // 全套）+ rule 已经把 package-lock.json 删了。如果 node_modules 留着，npm install 时旧
+    // 包还在 node_modules 顶层 hoist 树里，可能跟新 package.json spec 撞 peer 冲突
+    // （比如旧 coding-preset-vite-react@1.0.8 peer vite@^8 跟新 vite@^7 撞）。
+    // 软失败：node_modules 不存在不报错。
+    const nodeModulesPath = node_path_1.default.join(targetDir, 'node_modules');
+    if (node_fs_1.default.existsSync(nodeModulesPath)) {
+        (0, logger_1.log)('migrate', '清理 node_modules（dependencies 集合已变）...');
+        node_fs_1.default.rmSync(nodeModulesPath, { recursive: true, force: true });
+    }
+    // 跑 npm install 物化新依赖集合 + 把 followLatestPackages 钉 latest
+    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
+    // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
+    // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
+    const followLatest = config.followLatestPackages ?? [];
+    const installArgs = [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--ignore-scripts',
+        '--registry',
+        (0, index_2.resolveNpmInstallRegistry)(),
+        ...followLatest.map((pkg) => `${pkg}@latest`),
+    ];
+    (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
+    let installError;
+    try {
+        (0, node_child_process_1.execFileSync)('npm', installArgs, {
+            cwd: targetDir,
+            stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+        });
+    }
+    catch (err) {
+        installError = err instanceof Error ? err.message : String(err);
+        (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
+    }
+    // 沙箱环境下重启 dev process —— scripts/dev.js 被 fullstack 版本覆盖了,但当前正在
+    // 跑的 node 进程仍按老逻辑工作(只起 vite,没起 nest),整体没切到 fullstack 模式。
+    // 通过 pkill 杀掉 dev.js 主进程,依赖沙箱平台 supervisor 自动重新 exec dev.sh → dev.js,
+    // 新进程用新 deps + 新 scripts,正常进入 fullstack 模式。
+    //   - 只在 SANDBOX_ID 非空时做(本地环境用户进程混杂,主动 pkill 风险大)
+    //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
+    //     留着旧进程让用户先处理 installError
+    //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
+    let devRestarted = false;
+    if (installError === undefined &&
+        process.env.SANDBOX_ID !== undefined &&
+        process.env.SANDBOX_ID !== '') {
+        (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');
+        try {
+            (0, node_child_process_1.execFileSync)('pkill', ['-f', 'node.*scripts/dev\\.js'], { stdio: 'ignore' });
+            devRestarted = true;
+        }
+        catch {
+            // pkill 无匹配进程时退出 1,正常情况(可能 dev 没在跑)
+        }
+    }
+    (0, output_1.emit)({
+        data: {
+            from,
+            to: opts.to,
+            templateVersion,
+            appliedRules: results.map((r) => ({
+                type: r.rule.type,
+                action: r.action,
+                path: r.path,
+                detail: r.detail,
+            })),
+            ...summarizeResults(results),
+            followLatestPackages: followLatest,
+            installError,
+            devRestarted,
+            nextActions: process.env.SANDBOX_ID !== undefined && process.env.SANDBOX_ID !== ''
+                ? [
+                    'git status / git diff 评估改动并 commit',
+                    'miaoda skills sync 同步到新 stack 的 agent skills',
+                ]
+                : [
+                    'git status / git diff 评估改动并 commit',
+                    '重启 dev 进程让新 scripts/dev.js + 新依赖生效:重跑 npm run dev(killOrphansByPort 会自动踢掉旧进程)',
+                    'miaoda skills sync 同步到新 stack 的 agent skills',
+                ],
+        },
+    });
+}
+/**
+ * 从 tmp 端 template package.json 中删除 user 项目通常拥有的字段，避免 merge-json 时这些
+ * 字段被 template 值覆盖。需要 strip 的字段以 npm 模板里"通常专属于具体应用"的为准。
+ */
+function stripUserOwnedFields(pkgPath) {
+    if (!node_fs_1.default.existsSync(pkgPath))
+        return;
+    const json = JSON.parse(node_fs_1.default.readFileSync(pkgPath, 'utf-8'));
+    const userOwned = [
+        'name',
+        'version',
+        'private',
+        'description',
+        'author',
+        'keywords',
+        'license',
+        'repository',
+        'homepage',
+        'bugs',
+    ];
+    let changed = false;
+    for (const key of userOwned) {
+        if (Reflect.deleteProperty(json, key))
+            changed = true;
+    }
+    if (changed) {
+        node_fs_1.default.writeFileSync(pkgPath, JSON.stringify(json, null, 2) + '\n');
+    }
+}
+function summarizeResults(results) {
+    const moved = [];
+    const deleted = [];
+    const synced = [];
+    const merged = [];
+    const patched = [];
+    let skipped = 0;
+    for (const r of results) {
+        if (r.path === undefined)
+            continue;
+        switch (r.action) {
+            case 'moved':
+                moved.push(r.path);
+                break;
+            case 'deleted':
+                deleted.push(r.path);
+                break;
+            case 'synced':
+            case 'created':
+                synced.push(r.path);
+                break;
+            case 'merged':
+                merged.push(r.path);
+                break;
+            case 'patched':
+                patched.push(r.path);
+                break;
+            case 'skipped':
+                skipped++;
+                break;
+            case 'appended':
+            case 'noop':
+                break;
+        }
+    }
+    return { moved, deleted, synced, merged, patched, skipped };
+}

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

@@ -3,10 +3,46 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDeployConf = parseDeployConf;
 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 对象';
+/**
+ * 解析 `--conf` JSON string，只取 checkPointVersion / commitID 两个白名单字段。
+ * - 未传 → 返回 {}（行为不变）。
+ * - 非法 JSON / 非 object / 字段值非 string → 抛 DEPLOY_CONF_INVALID。
+ * - 空串字段视为未提供（不进 body，保持可选语义）；未知 key 忽略。
+ */
+function parseDeployConf(raw) {
+    if (raw === undefined || raw === '')
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new error_1.AppError('DEPLOY_CONF_INVALID', `--conf 不是合法 JSON，${CONF_EXPECTED}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new error_1.AppError('DEPLOY_CONF_INVALID', `--conf 必须是 JSON 对象，${CONF_EXPECTED}`);
+    }
+    const source = parsed;
+    const conf = {};
+    for (const key of ['checkPointVersion', 'commitID']) {
+        const value = source[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string') {
+            throw new error_1.AppError('DEPLOY_CONF_INVALID', `--conf.${key} 必须是字符串，${CONF_EXPECTED}`);
+        }
+        if (value !== '')
+            conf[key] = value;
+    }
+    return conf;
+}
 /**
  * miaoda deploy（modern scene 专用，CLI 表面对齐 openclaw-cli）
  *
@@ -14,10 +50,13 @@ const index_1 = require("../../../services/deploy/modern/index");
  */
 async function handleDeployModern(opts) {
     const projectDir = node_path_1.default.resolve(opts.dir);
+    const conf = parseDeployConf(opts.conf);
     const result = await (0, index_1.runModernDeploy)({
         projectDir,
         appId: opts.appId,
         skipBuild: opts.skipBuild ?? false,
+        checkPointVersion: conf.checkPointVersion,
+        commitID: conf.commitID,
     });
     (0, output_1.emit)({
         data: {

package/dist/config/migrate-configs/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * 跨 stack 迁移注册表 —— 按 (from, to) 二元组查找对应的 MigrateConfig。
+ *
+ * 跟 sync 注册表 (src/config/sync-configs/index.ts) 的关系：sync 一份配置对应一个 stack，
+ * migrate 一份配置对应 (源 stack, 目标 stack) 二元组；模板资产 migrate 在 runtime 从 npm
+ * 拉目标 stack 的 template tarball（init 用同一套 renderTemplate），不再用 upgrade/templates/
+ * 的子集。
+ *
+ * 新增迁移路径：
+ *   1. src/config/migrate-configs/<from>-to-<to>.ts 里 export default MIGRATE_CONFIG
+ *   2. 在 MIGRATE_REGISTRY 加一条
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMigrateConfig = getMigrateConfig;
+exports.listSupportedMigrations = listSupportedMigrations;
+const vite_react_to_nestjs_react_fullstack_1 = __importDefault(require("./vite-react-to-nestjs-react-fullstack"));
+/** key 格式：`<from>:<to>` */
+const MIGRATE_REGISTRY = {
+    'vite-react:nestjs-react-fullstack': vite_react_to_nestjs_react_fullstack_1.default,
+};
+/** 返回 (from, to) 对应的 MigrateConfig；未注册时返回 null。 */
+function getMigrateConfig(from, to) {
+    return MIGRATE_REGISTRY[`${from}:${to}`] ?? null;
+}
+/** 列出已支持的迁移路径，给 handler / 命令 help 用 */
+function listSupportedMigrations() {
+    return Object.keys(MIGRATE_REGISTRY).map((key) => {
+        const [from, to] = key.split(':');
+        return { from, to };
+    });
+}