@lark-apaas/miaoda-cli 0.1.16-alpha.0 → 0.1.16-alpha.452772a

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

@@ -1,6 +1,7 @@
 "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");
@@ -30,8 +31,13 @@ function registerAppMigrate(parent) {
     const supportedDesc = (0, index_2.listSupportedMigrations)()
         .map((m) => `${m.from} → ${m.to}`)
         .join(', ');
-    const cmd = parent
-        .command('migrate')
+    // 渐进式披露：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')
@@ -40,19 +46,6 @@ function registerAppMigrate(parent) {
 已支持的迁移路径
   ${supportedDesc || '(none)'}
 
-执行流
-  1. 校验 .spark/meta.json 存在且当前 stack 匹配 --from（或自动读 meta）
-  2. 按 (from, to) 在 src/config/migrate-configs/ 取 MigrateConfig
-  3. 顺序执行 rules：
-       move-directory / move-file   → 用户领地搬到新布局（src → client/src 等）
-       delete-file / delete-directory → 清理老 stack 的残留文件
-       delete-json-keys             → 从 user package.json 删 vite-react 专属字段
-       file / directory             → 拷新 stack 的模板资产覆盖
-       merge-json                   → package.json 等字段级深合并
-       add-script / patch-script / add-line / remove-line → 局部修补
-       set-stack                    → 收尾切 .spark/meta.json 的 stack 字段
-  4. 不做 npm install —— 让用户自行 review 改动后再装依赖（package-lock.json 已删）
-
 JSON 输出
   {"data": {"from": "...", "to": "...",
             "appliedRules": [{"type": "...", "action": "...", "path": "...", "detail": "..."}],
@@ -72,6 +65,7 @@ JSON 输出
             to: rawOpts.to,
         });
     }));
+    parent.addCommand(cmd, { hidden: true });
 }
 function registerAppSync(parent) {
     const cmd = parent

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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (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"));
@@ -30,11 +31,12 @@ const logger_1 = require("../../../utils/logger");
  *   2. 拿到 (from, to) 对应的 MigrateConfig 与模板源根目录
  *   3. 顺序执行 rules：move-* → delete-* → delete-json-keys → file/directory →
  *      merge-json → set-stack
- *   4. emit 结果；不做 npm install（用户接下来跑 `npm install` 或 `miaoda app sync` 时自然装）
+ *   4. 清掉 node_modules（package-lock.json 已经在 rules 里 delete），跑 npm install
+ *      物化新依赖集合 —— migrate 改了 dependencies / devDependencies 集合（删 lite +
+ *      加 NestJS 全套），不重装就跑不起来
  *
  * 不做事：
  *   - 不自动 commit / stash —— 让用户自己用 git review 改动
- *   - 不跑 npm install —— 留给后续 sync 或用户手动
  *   - 不动 .agent/skills/（那是 miaoda skills sync 的事，迁移后用户应该单独跑一次切到新 stack 的 skills）
  */
 async function handleAppMigrate(opts) {
@@ -94,6 +96,40 @@ async function handleAppMigrate(opts) {
     // 的 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 物化新依赖集合
+    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
+    // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
+    // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
+    const installArgs = [
+        'install',
+        '--no-audit',
+        '--no-fund',
+        '--ignore-scripts',
+        '--registry',
+        (0, index_2.resolveNpmInstallRegistry)(),
+    ];
+    (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}`);
+    }
     (0, output_1.emit)({
         data: {
             from,
@@ -106,9 +142,9 @@ async function handleAppMigrate(opts) {
                 detail: r.detail,
             })),
             ...summarizeResults(results),
+            installError,
             nextActions: [
                 'git status / git diff 评估改动并 commit',
-                'npm install 装新依赖（package-lock.json 已被删除，将重新生成）',
                 'miaoda skills sync 同步到新 stack 的 agent skills',
             ],
         },

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

@@ -2,16 +2,28 @@
 /**
  * vite-react → nestjs-react-fullstack 的跨 stack 迁移规则。
  *
- * 分类原则（与飞书 wiki 设计文档对齐）：
- *   - 用户领地（src / public / shared / .env / .spark_project）：原样保留，搬到新布局位置；
- *   - 模板领地（vite.config / tsconfig / scripts / .githooks / lint 配置 / 入口 html 等）：
- *     用 fullstack 模板版本整体替换；
- *   - package.json：字段级 merge —— 顶层 user 字段（name/version/private）保留，依赖列表
- *     做 set union（template 同名包覆盖版本号 → 避免依赖冲突），scripts 同名替换为 template
- *     版本。
+ * 设计原则：**最小改动**。只动 fullstack 形态必须的文件 / package.json key，user 已有
+ * 的 vite.config / tsconfig / eslint / prettier / tailwind / postcss / components.json
+ * 等业务配置一律**保留**，不被 template 整体覆盖。
  *
- * 模板资产来源：upgrade/templates/nestjs-react-fullstack/templates/（cli 内嵌的脚手架资产，
- * 与 sync 共享同一份）。
+ * 步骤：
+ *   1. src/ public/ 搬到 client/ 下（fullstack 布局）
+ *   2. 清掉 vite-react 时代的根 index.html / eslint.config.mjs / package-lock.json
+ *   3. 删 user package.json 里 lite SDK 相关 key（保留 coding-preset-vite-react）
+ *   4. 把 NestJS server runtime 拷进来（server/ + nest-cli.json + tsconfig.node.json
+ *      + 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）
+ *   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 /
+ *      server-log 4 件套，vite 8080 反代 HTML / API 到 nest 3000
+ *   9. set-stack 切 .spark/meta.json
+ *
+ * 跟 SDK 的协作：client-toolkit@1.2.52+ 顶层 single-entry 完整 re-export 了
+ * client-toolkit-lite 全部 48 项 API（fullstack-plugin#1124），所以 codemod 只换
+ * 包名、specifier 列表不动就够。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIGRATE_CONFIG = void 0;
@@ -20,92 +32,184 @@ exports.MIGRATE_CONFIG = {
     to: 'nestjs-react-fullstack',
     rules: [
         // ===== 1. 用户领地搬迁 =====
-        // src/ 是 vite-react 的业务代码根，fullstack 拆 client/server，全部归 client/src/
         { type: 'move-directory', from: 'src', to: 'client/src' },
-        // public/ 是 vite 端的静态资源根，跟随 client/
         { type: 'move-directory', from: 'public', to: 'client/public' },
-        // shared/ 在两边布局相同，不动。.env / .spark_project 同理，不写规则即可。
-        // ===== 2. 清理 vite-react 专属残留 =====
-        // 根 index.html 被 client/index.html 取代（fullstack 模板自己带）
+        // shared/ 不动（两边布局相同）；.env / .spark_project 同理。
+        // ===== 2. 清理 vite-react 残留 =====
+        // 根 index.html 被 client/index.html 取代（fullstack 用 HBS 渲染）
         { type: 'delete-file', to: 'index.html' },
-        // ESLint 9 flat config 文件名变了
+        // ESLint 9 flat config 文件名变了（user eslint.config.mjs → eslint.config.js）
         { type: 'delete-file', to: 'eslint.config.mjs' },
-        // 依赖集合变了，lockfile 重新生成（首次 npm install 时）
+        // 依赖集合变了，lockfile 重新生成
         { type: 'delete-file', to: 'package-lock.json' },
-        // ===== 3. 从 user package.json 删除 vite-react 专属字段 =====
-        // 这步在 merge-json 之前，确保 vite-react 的 preset 不残留。
-        // merge-json 是"template 覆盖同名 key + user 多出 key 保留"，所以 user 的 vite-react
-        // 专属字段不会被自动清理 —— 必须显式删。
-        //
-        // 注意：不删 dependencies.@lark-apaas/client-toolkit-lite —— lite 是 vite-react 时代的
-        // 入门 wrapper（顶层 38 个 export），完整版 @lark-apaas/client-toolkit 只暴露 ~20 个
-        // 对等出口（components/* / hooks/* / utils/* / tools/* / 顶层 alias），剩下 ~18 个 lite
-        // symbol（copyToClipboard / getAppId / clsxWithTw / isMobile / avatarImages 等）在 full
-        // 公共 API 里没有对等物。lite 跟 full 不是简单替换关系，而是不同抽象层级。强行替换
-        // 会让 build 失败；让两个包共存（lite 很轻量）是当前的现实选择。后续若 client-toolkit
-        // 补全 utility 出口，可启用 src/utils/codemod-client-toolkit-lite.ts 里已实现的 codemod
-        // rule（在 MigrateRule 联合里有 CodemodClientToolkitLiteRule 类型）。
+        // ===== 3. 从 user package.json 删 vite-react 专属字段 =====
+        // 注意保留 devDependencies.@lark-apaas/coding-preset-vite-react —— user 迁移后
+        // vite.config 仍用它（开 fullstack 模式即可），不切到 fullstack-vite-preset。
         {
             type: 'delete-json-keys',
             to: 'package.json',
             keys: [
                 // 顶层 "type": "module" —— vite-react ESM 入口约定，nestjs CommonJS 不需要
                 'type',
-                // vite-react 的 vite preset，nestjs 用 fullstack-vite-preset
-                'devDependencies.@lark-apaas/coding-preset-vite-react',
-                // vite-react 的 ESLint preset
-                'devDependencies.@lark-apaas/coding-presets-react',
+                // lite SDK：codemod 后 import 走 client-toolkit 顶层
+                'dependencies.@lark-apaas/client-toolkit-lite',
             ],
         },
-        // ===== 4. 模板资产覆盖 / 新增 =====
-        // 顶层配置文件：直接用 fullstack 模板版本覆盖（用户改过的话靠 git diff 兜底自查）
-        { type: 'file', from: 'vite.config.ts', to: 'vite.config.ts', overwrite: true },
+        // ===== 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 入口
+        { 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；
+        // 整体覆盖到 fullstack 版本（include 改 client/** + shared/**、extends fullstack-presets）。
+        // user 自己加的 paths / strict 等设置如有需要，按 git diff 手动加回。
         { 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 },
+        // 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 },
-        { type: 'file', from: 'nest-cli.json', to: 'nest-cli.json', overwrite: true },
-        { type: 'file', from: 'postcss.config.js', to: 'postcss.config.js', overwrite: true },
-        { type: 'file', from: 'tailwind.config.ts', to: 'tailwind.config.ts', overwrite: true },
-        { type: 'file', from: 'components.json', to: 'components.json', overwrite: true },
-        { type: 'file', from: '.prettierrc', to: '.prettierrc', overwrite: true },
-        { type: 'file', from: '.stylelintrc.js', to: '.stylelintrc.js', overwrite: true },
-        // renderTemplate 拉 tarball 时会把 _gitignore / _npmrc 占位名重命名回 .gitignore / .npmrc，
-        // 所以 from 也写 dot-form
-        { type: 'file', from: '.gitignore', to: '.gitignore', overwrite: true },
-        { type: 'file', from: '.npmrc', to: '.npmrc', overwrite: true },
-        // client 入口：用 nestjs 模板的 index.tsx 覆盖（含 Toaster / defaultTheme），原 vite-react
-        // 入口在前面 move-directory 时已搬到 client/src/index.tsx
+        // client/index.html：HBS 模板（fullstack 用，vite-react 用根 index.html 已删）
         { type: 'file', from: 'client/index.html', to: 'client/index.html', overwrite: true },
-        { type: 'file', from: 'client/src/index.tsx', to: 'client/src/index.tsx', overwrite: true },
-        // 整目录复制（不存在则创建，存在则递归覆盖同名文件）
-        // server/：NestJS SSR runtime，固定模板，不需要业务定制
-        { type: 'directory', from: 'server', to: 'server', overwrite: true },
-        // scripts/：dev / build / lint / hooks 全套脚本
+        // scripts/ 整目录：fullstack 形态启动 / 构建 / lint 所需的 8 个平台脚本（dev.sh /
+        // dev.js / dev-local.js / build.sh / lint.js / prune-smart.js / run.sh / hooks/）。
+        // dev.sh exec node dev.js，dev.js 才是并发起 nest + vite 的核心 —— 漏一个 dev 跑不起来。
+        // overwrite: true：这些脚本由平台 cli 维护，user 一般不改；按 fullstack 版本覆盖。
         { type: 'directory', from: 'scripts', to: 'scripts', overwrite: true },
-        // .githooks/：pre-commit
-        { type: 'directory', from: '.githooks', to: '.githooks', overwrite: true },
-        // shared/ 是用户领地（不在 move 阶段动），但 fullstack 模板带了 shared/api.interface.ts 之类
-        // 的 fallback 文件 —— 用 overwrite: false 把 template 新增的文件加入 user shared/，user
-        // 已有同名文件保持不动。
+        // .githooks（fallback，user 已有则保留）
+        { type: 'directory', from: '.githooks', to: '.githooks', overwrite: false },
+        // shared/ fallback（user 已有同名文件保留，template 新增文件加入）
         { type: 'directory', from: 'shared', to: 'shared', overwrite: false },
-        // .env 同样 fallback —— user 已有 .env 保留，否则用 template 的（默认 logger 配置）
+        // .env fallback（user 没有时用 template 默认）
         { type: 'file', from: '.env', to: '.env', overwrite: false },
-        // ===== 5. package.json 字段级 merge =====
-        // 用 template 的 partial pkg（只含 dependencies / devDependencies / scripts）deep merge
-        // 进 user pkg：
-        //   - 顶层 user 字段（name / version / private）保留 —— template 不写这些字段
-        //   - dependencies / devDependencies：template 覆盖同名版本号，user 业务 deps 保留
-        //   - scripts：template 同名脚本覆盖 user 同名脚本，user 自定义脚本保留
-        // 模板源是 upgrade/templates/nestjs-react-fullstack/templates/package.json
+        // ===== 5. 加 fullstack 形态必需的 scripts =====
+        // 这些 scripts 用 user 现有的可能性低（vite-react 没有 nest 相关 script），直接覆盖
+        {
+            type: 'add-script',
+            name: 'dev',
+            command: './scripts/dev.sh',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'dev:server',
+            command: 'NODE_ENV=development nest start --watch',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'dev:client',
+            command: 'NODE_ENV=development vite --config vite.config.ts',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build',
+            command: './scripts/build.sh',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build:server',
+            command: 'NODE_ENV=production nest build',
+            overwrite: true,
+        },
         {
-            type: 'merge-json',
+            type: 'add-script',
+            name: 'build:client',
+            command: 'NODE_ENV=production vite build --config vite.config.ts',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'build:prod',
+            command: 'npm run build:server && npm run build:client',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'start',
+            command: 'NODE_ENV=production node main.js',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'type:check:server',
+            command: 'tsc --noEmit --project tsconfig.node.json',
+            overwrite: true,
+        },
+        {
+            type: 'add-script',
+            name: 'type:check:client',
+            command: 'tsc --noEmit --project tsconfig.app.json',
+            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"',
+            overwrite: true,
+        },
+        // ===== 6. 从 fullstack template 取版本号加 NestJS 强依赖（精确白名单） =====
+        // 不走 merge-json（template 130+ devDeps 全 merge 会污染 user 业务依赖集合）；
+        // 白名单只列 fullstack 启动能跑起来必需的最小集。
+        {
+            type: 'add-deps-from-template',
             from: 'package.json',
             to: 'package.json',
+            dependencies: [
+                // NestJS server 核心
+                '@nestjs/core',
+                '@nestjs/common',
+                '@nestjs/platform-express',
+                '@nestjs/config',
+                '@nestjs/axios',
+                '@nestjs/swagger',
+                // 妙搭 fullstack server SDK（main.ts / view module 等都依赖）
+                '@lark-apaas/fullstack-nestjs-core',
+                // HBS 模板引擎（client/index.html 渲染）
+                'hbs',
+                // NestJS runtime 必需
+                'reflect-metadata',
+                'rxjs',
+                'tslib',
+                // DTO 校验 / 转换
+                'class-transformer',
+                'class-validator',
+                // .env 加载（scripts/dev.sh 用到 dotenv-cli 风格）
+                'dotenv',
+                // client-toolkit：替代 lite，业务代码 codemod 后走它
+                '@lark-apaas/client-toolkit',
+            ],
+            devDependencies: [
+                // nest start / nest build 必需
+                '@nestjs/cli',
+                '@nestjs/testing',
+                // server ts 编译
+                'ts-node',
+                '@types/express',
+                '@types/hbs',
+                '@types/node',
+                // 并发跑 nest + vite（scripts/dev.sh 用 concurrently）
+                'concurrently',
+                // fullstack server 端 tsconfig.node.json 通过 extends 引这个包
+                // （@lark-apaas/fullstack-presets/lib/simple/tsconfig/tsconfig.node.json）;
+                // 不装会导致 nest build / type:check:server / vite dev 解析 tsconfig 时 ENOENT
+                '@lark-apaas/fullstack-presets',
+            ],
         },
-        // ===== 6. 切 stack =====
-        // 收尾：把 .spark/meta.json 的 stack 切到 nestjs-react-fullstack，后续 miaoda app sync
-        // 会按新 stack 的 SyncConfig 跑
+        // ===== 7. 业务代码 codemod：lite → client-toolkit 包名替换 =====
+        // client-toolkit@1.2.52+ 顶层完整 re-export lite 全部 48 项，specifier 列表不动。
+        // 同时扫 shared/（client/server 共享代码也可能引 lite 类型 / utils）。
+        { type: 'codemod-client-toolkit-lite', root: 'client/src' },
+        { type: 'codemod-client-toolkit-lite', root: 'shared' },
+        // ===== 8. vite.config codemod：加 { fullstack: true } 第二参 =====
+        // user vite.config 现在是 defineConfig({...}) 单参；fullstack 形态需要 vite 8080
+        // 反代 HTML / API 到 nest 3000，coding-preset-vite-react 用 fullstack option 启用
+        // 这一行为（详见 fullstack-plugin coding-preset-vite-react#fullstack）。
+        { type: 'codemod-vite-config-fullstack', to: 'vite.config.ts' },
+        // ===== 9. 切 stack =====
         { type: 'set-stack', stack: 'nestjs-react-fullstack' },
     ],
 };

package/dist/config/sync-configs/design-stack.js

@@ -42,7 +42,7 @@ exports.SYNC_CONFIG = {
             command: 'node scripts/hooks/run-precommit.js',
             overwrite: false,
         },
-        // 2. .gitignore 卫生：移除 package-lock.json + 加 .agent/
+        // 2. .gitignore 卫生：移除 package-lock.json + 加 .agent/ / .npm_cache
         {
             type: 'remove-line',
             to: '.gitignore',
@@ -53,6 +53,11 @@ exports.SYNC_CONFIG = {
             to: '.gitignore',
             line: '.agent/',
         },
+        {
+            type: 'add-line',
+            to: '.gitignore',
+            line: '.npm_cache',
+        },
         // 3. 老 npm scripts 迁移（裸 fullstack-cli → 钉版 npx）。两条 ifStartsWith 分别覆盖
         //    "裸 fullstack-cli"（最老形态）和 "npx 未钉版" 形态，统一升到 FULLSTACK_CLI_PIN_SPEC。
         {

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

@@ -113,6 +113,12 @@ exports.SYNC_CONFIG = {
             to: '.gitignore',
             line: '.agent/',
         },
+        // 7a. 确保 .gitignore 包含 .npm_cache 目录
+        {
+            type: 'add-line',
+            to: '.gitignore',
+            line: '.npm_cache',
+        },
         // 8. 同步 .spark_project 配置文件（总是覆盖）
         {
             type: 'file',

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.TEMPLATE_PACKAGE_BY_STACK = exports.SUPPORTED_STACKS = exports.renderTemplate = void 0;
+exports.resolveNpmInstallRegistry = exports.installDependencies = exports.writeSparkMeta = exports.readSparkMeta = exports.TEMPLATE_PACKAGE_BY_STACK = exports.SUPPORTED_STACKS = exports.renderTemplate = void 0;
 var template_1 = require("./template");
 Object.defineProperty(exports, "renderTemplate", { enumerable: true, get: function () { return template_1.renderTemplate; } });
 Object.defineProperty(exports, "SUPPORTED_STACKS", { enumerable: true, get: function () { return template_1.SUPPORTED_STACKS; } });
@@ -10,3 +10,4 @@ Object.defineProperty(exports, "readSparkMeta", { enumerable: true, get: functio
 Object.defineProperty(exports, "writeSparkMeta", { enumerable: true, get: function () { return spark_meta_1.writeSparkMeta; } });
 var install_1 = require("./install");
 Object.defineProperty(exports, "installDependencies", { enumerable: true, get: function () { return install_1.installDependencies; } });
+Object.defineProperty(exports, "resolveNpmInstallRegistry", { enumerable: true, get: function () { return install_1.resolveNpmInstallRegistry; } });

package/dist/utils/codemod-client-toolkit-lite.js

@@ -1,21 +1,22 @@
 "use strict";
 /**
- * Codemod：把 `@lark-apaas/client-toolkit-lite` 的 import 改写到 `@lark-apaas/client-toolkit`
- * 的对应子路径。
+ * Codemod：把 `@lark-apaas/client-toolkit-lite` 的 import 改写到 `@lark-apaas/client-toolkit`。
  *
  * 用于 `miaoda app migrate vite-react → nestjs-react-fullstack`：迁移后让两个包共存属于
- * lib 冗余（两份 react / 两套主题 / 两套 axios），所以扫 client/src 把 lite import 改写到
- * full 等价子路径，然后用 delete-json-keys 移除 lite dep。
+ * lib 冗余（两份 react / 两套主题 / 两套 axios），所以扫 user 代码把 lite import 改写到
+ * full，然后用 delete-json-keys 移除 lite dep。
  *
- * 表的来源：grep client-toolkit lib/ 目录定位每个 lite symbol 的 d.ts 路径，subpath 取相对
- * 路径。同 symbol 多个 d.ts 时按优先级选最合理的——例如 AppContainer 优先 `components/` 而
- * 非 `apis/components/`（跟 fullstack template 自带 client/src/index.tsx 的约定一致）。
+ * 实现策略：单行包名替换。
+ *
+ * client-toolkit 自 v1.2.48 起在顶层 single-entry 完整 re-export 了 client-toolkit-lite
+ * 的全部 48 项（components / hooks / utils / integrations / logger / trace / types /
+ * constants），跟 lite 同名同签 —— 所以 codemod 只需把 import 来源包名从 `-lite` 换掉，
+ * specifier 列表完全不动。CSS `@import` 同理（client-toolkit 顶层加了 ./styles.css 别名）。
  *
  * 边界：
  *   - 仅处理形如 `import [type] { A, B as C } from '@lark-apaas/client-toolkit-lite'` 的
- *     单行 named import。default import / namespace import / 跨多行 specifier 表当作 unmapped。
- *   - 表里没有的 symbol：保留原 import 行 + 加一行 `// TODO[migrate]: ...` 注释；后续 build
- *     会因为 lite dep 被删而失败，提示用户手动处理。
+ *     named import；default import / namespace import / 跨多行 specifier 当前不识别，
+ *     但只要 `from '...lite'` 在同一行，包名替换仍有效（regex 抓 from 段）。
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -26,68 +27,10 @@ exports.rewriteCssText = rewriteCssText;
 exports.rewriteText = rewriteText;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-/** lite 38 个 export → full 子路径的映射表 */
-const SYMBOL_MAP = {
-    // === 组件（apis/components 是 lite 兼容层，components 是基础层） ===
-    ActiveLink: { subpath: 'apis/components/ActiveLink' },
-    AppContainer: { subpath: 'components/AppContainer' },
-    ErrorRender: { subpath: 'components/ErrorRender' },
-    NavLink: { subpath: 'apis/components/NavLink' },
-    PagePlaceholder: { subpath: 'components/PagePlaceholder' },
-    QueryProvider: { subpath: 'components/QueryProvider' },
-    UniversalLink: { subpath: 'apis/components/UniversalLink' },
-    Welcome: { subpath: 'apis/components/Welcome' },
-    // === 类型 ===
-    AppInfoPayload: { subpath: 'types/common' },
-    IFileAttachment: { subpath: 'apis/udt-types' },
-    IJson: { subpath: 'apis/udt-types' },
-    IUserProfile: { subpath: 'apis/udt-types' },
-    LogLevel: { subpath: 'logger/log-types' },
-    LogWithMeta: { subpath: 'logger/log-types' },
-    TrackKey: { subpath: 'types/tea' },
-    TrackParams: { subpath: 'types/tea' },
-    // === 图片资源（lite 端用了 alias：avatar→avatarImages 等） ===
-    avatarImages: { subpath: 'apis/constants/img-resources/avatar', sourceName: 'avatar' },
-    bannerImages: { subpath: 'apis/constants/img-resources/banner', sourceName: 'banner' },
-    coverImages: { subpath: 'apis/constants/img-resources/cover', sourceName: 'cover' },
-    // === Hooks ===
-    useAppInfo: { subpath: 'hooks/useAppInfo' },
-    useCurrentUserProfile: { subpath: 'hooks/useCurrentUserProfile' },
-    useIsMobile: { subpath: 'hooks/useIsMobile' },
-    useLogout: { subpath: 'hooks/useLogout' },
-    // === Utils / 工具函数 ===
-    axiosForBackend: { subpath: 'utils/getAxiosForBackend' },
-    capabilityClient: { subpath: '' }, // 在 full 顶层 export
-    clsxWithTw: { subpath: 'utils/utils' },
-    copyToClipboard: { subpath: 'utils/copyToClipboard' },
-    getAppId: { subpath: 'utils/getAppId' },
-    getAppInfo: { subpath: 'integrations/getAppInfo' },
-    getAxiosForBackend: { subpath: 'utils/getAxiosForBackend' },
-    getCsrfToken: { subpath: 'utils/getCsrfToken' },
-    getCurrentUserProfile: { subpath: 'integrations/getCurrentUserProfile' },
-    getDataloom: { subpath: 'apis/dataloom' },
-    getEnvPath: { subpath: 'utils/getEnvPath' },
-    getWsPath: { subpath: 'utils/utils' },
-    initAxiosConfig: { subpath: 'utils/axiosConfig' },
-    initObservable: { subpath: 'runtime/observable' },
-    isIOS: { subpath: 'utils/deviceType' },
-    isIpad: { subpath: 'utils/deviceType' },
-    isMobile: { subpath: 'utils/deviceType' },
-    isPreview: { subpath: 'utils/utils' },
-    logger: { subpath: 'apis/logger' },
-    normalizeBasePath: { subpath: 'utils/utils' },
-    reportTeaEvent: { subpath: 'components/AppContainer/utils/tea' },
-    resolveAppUrl: { subpath: 'utils/resolveAppUrl' },
-    safeStringify: { subpath: 'utils/safeStringify' },
-    scopedStorage: { subpath: 'apis/utils/scopedStorage' },
-    trace: { subpath: 'trace/index' },
-};
 const LITE_PKG = '@lark-apaas/client-toolkit-lite';
 const FULL_PKG = '@lark-apaas/client-toolkit';
 /**
  * 递归扫描 rootDir 下的 .ts/.tsx/.js/.jsx/.css 文件，把 lite import 改写到 full。
- * css 里 `@import "@lark-apaas/client-toolkit-lite/styles.css"` 同样要重写到
- * `@lark-apaas/client-toolkit/lib/index.css`，否则 css build 会因 lite dep 被删而 ENOENT。
  */
 function rewriteLiteImports(rootDir) {
     const result = {
@@ -108,8 +51,7 @@ function rewriteLiteImports(rootDir) {
         if (!before.includes(LITE_PKG))
             continue;
         const rel = node_path_1.default.relative(rootDir, file);
-        const { text, count, unmapped } = isJs ? rewriteText(before, rel) : rewriteCssText(before, rel);
-        result.unmapped.push(...unmapped);
+        const { text, count } = isJs ? rewriteText(before, rel) : rewriteCssText(before, rel);
         if (count > 0) {
             node_fs_1.default.writeFileSync(file, text);
             result.filesChanged.push(rel);
@@ -119,128 +61,35 @@ function rewriteLiteImports(rootDir) {
     return result;
 }
 /**
- * css 改写器：把 `@import "@lark-apaas/client-toolkit-lite/styles.css"` 重写到 full 的入口
- * `@lark-apaas/client-toolkit/lib/index.css`；其他 lite styles 子路径（如 `styles/*`）
- * 在 full 里没有对等物，留下 TODO 注释让用户手动处理。
+ * css 改写器：单行包名替换。`@import "@lark-apaas/client-toolkit-lite/<path>"` →
+ * `@import "@lark-apaas/client-toolkit/<path>"`。其中 styles.css 在 full 端已加同名别名
+ * 指向 ./lib/index.css。
  */
-function rewriteCssText(source, fileLabel) {
-    const unmapped = [];
+function rewriteCssText(source, _fileLabel) {
     let count = 0;
-    const lines = source.split('\n');
-    const out = [];
-    // 匹配 `@import "@lark-apaas/client-toolkit-lite/<path>";` 或 single quote
-    const re = /^(\s*)@import\s+['"]@lark-apaas\/client-toolkit-lite\/([^'"]+)['"]\s*;?\s*$/;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const m = re.exec(line);
-        if (!m) {
-            out.push(line);
-            continue;
-        }
-        const captures = m;
-        const indent = captures[1] ?? '';
-        const subpath = captures[2] ?? '';
-        if (subpath === 'styles.css') {
-            out.push(`${indent}@import "${FULL_PKG}/lib/index.css";`);
-            count++;
-        }
-        else {
-            // styles/* 等子路径 full 没对等物，保留原行 + TODO（build 会失败）
-            out.push(line);
-            out.push(`${indent}/* TODO[migrate]: @lark-apaas/client-toolkit-lite/${subpath} has no known mapping in @lark-apaas/client-toolkit; replace manually. */`);
-            unmapped.push({ file: fileLabel, symbol: subpath, line: i + 1 });
-        }
-    }
-    return { text: out.join('\n'), count, unmapped };
+    const re = /(@import\s+['"])@lark-apaas\/client-toolkit-lite(\/[^'"]*)?(['"])/g;
+    const text = source.replace(re, (_match, p1, sub, p3) => {
+        count++;
+        return `${p1}${FULL_PKG}${sub ?? ''}${p3}`;
+    });
+    return { text, count, unmapped: [] };
 }
-/** 对单个文件文本做改写。导出供单测直接验证。 */
-function rewriteText(source, fileLabel) {
-    const unmapped = [];
+/**
+ * JS/TS 文件改写器：把任何 `from '@lark-apaas/client-toolkit-lite'` 改成 full 包名。
+ * specifier 列表完全保留 —— full 顶层 single-entry 已经兼容 lite 全部 48 项 export。
+ *
+ * 同样兼容 dynamic import / require / `export ... from` 等其他形式（只要包名字符串在）。
+ */
+function rewriteText(source, _fileLabel) {
     let count = 0;
-    const lines = source.split('\n');
-    const out = [];
-    // 匹配单行 named import：捕获 indent / `type ` 修饰符 / specifier 段
-    const reImport = /^(\s*)import\s+(type\s+)?\{([^}]+)\}\s+from\s+['"]@lark-apaas\/client-toolkit-lite['"]\s*;?\s*$/;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const m = reImport.exec(line);
-        if (!m) {
-            out.push(line);
-            continue;
-        }
-        // RegExp.exec 返回 string[]，但 optional capture group 实际可能是 undefined。
-        // 显式 cast 让 TS narrow 配合 eslint no-unnecessary-condition 不报"永远 truthy"。
-        const captures = m;
-        const indent = captures[1] ?? '';
-        const wholeIsType = captures[2] !== undefined;
-        const specifiers = parseSpecifiers(captures[3] ?? '');
-        // 按 target subpath 分组（同 subpath 的 specifier 合并到一条 import）
-        const groups = new Map();
-        const localUnmapped = [];
-        for (const spec of specifiers) {
-            // SYMBOL_MAP 是 Record，TS 默认推断索引返回非 undefined；用 hasOwnProperty 做 narrow
-            if (!Object.prototype.hasOwnProperty.call(SYMBOL_MAP, spec.imported)) {
-                localUnmapped.push(spec.imported);
-                unmapped.push({ file: fileLabel, symbol: spec.imported, line: i + 1 });
-                continue;
-            }
-            const info = SYMBOL_MAP[spec.imported];
-            const target = info.subpath ? `${FULL_PKG}/${info.subpath}` : FULL_PKG;
-            const sourceName = info.sourceName ?? spec.imported;
-            const isType = wholeIsType || spec.isType;
-            const entry = groups.get(target) ?? { items: [], allTypes: true };
-            entry.items.push({ source: sourceName, local: spec.local, isType });
-            entry.allTypes = entry.allTypes && isType;
-            groups.set(target, entry);
-            count++;
-        }
-        if (groups.size === 0) {
-            // 全部 unmapped：保留原行 + TODO 注释
-            out.push(line);
-            out.push(`${indent}// TODO[migrate]: '${localUnmapped.join(', ')}' has no known mapping from '${LITE_PKG}' to '${FULL_PKG}'; replace manually before building.`);
-            continue;
-        }
-        // 输出 group 化的新 import 行（同 target 下区分 type-only / 混合）
-        for (const [target, { items, allTypes }] of groups) {
-            if (allTypes) {
-                const inner = items.map(fmtSpec).join(', ');
-                out.push(`${indent}import type { ${inner} } from '${target}';`);
-            }
-            else {
-                // 把 type 和非 type 分两条输出更稳：避免 `import { type X, Y }` 在某些工具链下不被支持
-                const typeItems = items.filter((it) => it.isType);
-                const valItems = items.filter((it) => !it.isType);
-                if (typeItems.length > 0) {
-                    out.push(`${indent}import type { ${typeItems.map(fmtSpec).join(', ')} } from '${target}';`);
-                }
-                out.push(`${indent}import { ${valItems.map(fmtSpec).join(', ')} } from '${target}';`);
-            }
-        }
-        if (localUnmapped.length > 0) {
-            out.push(`${indent}// TODO[migrate]: '${localUnmapped.join(', ')}' has no known mapping from '${LITE_PKG}' to '${FULL_PKG}'; replace manually before building.`);
-        }
-    }
-    return { text: out.join('\n'), count, unmapped };
-}
-function fmtSpec(s) {
-    return s.local === s.source ? s.source : `${s.source} as ${s.local}`;
-}
-function parseSpecifiers(raw) {
-    const out = [];
-    for (const part of raw.split(',')) {
-        const t = part.trim();
-        if (!t)
-            continue;
-        const m = /^(type\s+)?([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?$/.exec(t);
-        if (!m)
-            continue;
-        const captures = m;
-        const imported = captures[2];
-        if (imported === undefined)
-            continue;
-        out.push({ isType: captures[1] !== undefined, imported, local: captures[3] ?? imported });
-    }
-    return out;
+    // 既匹配 `from 'pkg'` 也匹配 `from "pkg"`，单双引号都管。
+    // 同时覆盖 `import('pkg')` / `require('pkg')` 等其他常见形态。
+    const re = /(['"])@lark-apaas\/client-toolkit-lite(['"])/g;
+    const text = source.replace(re, (_match, p1, p2) => {
+        count++;
+        return `${p1}${FULL_PKG}${p2}`;
+    });
+    return { text, count, unmapped: [] };
 }
 function* walk(dir) {
     for (const entry of node_fs_1.default.readdirSync(dir, { withFileTypes: true })) {

package/dist/utils/migrate-rule.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyMigrateRules = applyMigrateRules;
+exports.rewriteViteConfigForFullstack = rewriteViteConfigForFullstack;
+exports.rewriteAliasSrcPaths = rewriteAliasSrcPaths;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const sync_rule_1 = require("./sync-rule");
@@ -38,6 +40,14 @@ function applyMigrateRules(rules, opts) {
             results.push(applyCodemodLite(rule, opts));
             continue;
         }
+        if (rule.type === 'codemod-vite-config-fullstack') {
+            results.push(applyCodemodViteConfigFullstack(rule, opts));
+            continue;
+        }
+        if (rule.type === 'add-deps-from-template') {
+            results.push(applyAddDepsFromTemplate(rule, opts));
+            continue;
+        }
         // 前面 if 已经把 migrate 专用 rule 都 narrow 掉，剩下的必然是 SyncRule
         const [syncResult] = (0, sync_rule_1.applySyncRules)([rule], opts);
         results.push(syncResult);
@@ -164,6 +174,130 @@ function applyCodemodLite(rule, opts) {
         detail,
     };
 }
+function applyCodemodViteConfigFullstack(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const rel = rule.to ?? 'vite.config.ts';
+    const dest = node_path_1.default.join(opts.targetDir, rel);
+    if (!node_fs_1.default.existsSync(dest)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rel} (not found, skip)`);
+        return { rule, action: 'skipped', path: rel };
+    }
+    const before = node_fs_1.default.readFileSync(dest, 'utf-8');
+    const { text, aliasRewriteCount } = rewriteViteConfigForFullstack(before);
+    if (aliasRewriteCount === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rel} (no src alias path to rewrite)`);
+        return { rule, action: 'noop', path: rel };
+    }
+    node_fs_1.default.writeFileSync(dest, text);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rel} (rewrote ${aliasRewriteCount.toString()} alias path(s) src → client/src)`);
+    return {
+        rule,
+        action: 'patched',
+        path: rel,
+        detail: `${aliasRewriteCount.toString()} alias path(s)`,
+    };
+}
+/**
+ * 把 vite.config.ts 里 alias 字符串里 `src` 起头的路径重写到 `client/src`。
+ *
+ * vite-react 时代 user 业务代码在 `src/`，迁移后搬到 `client/src/`，vite.config
+ * 里的 alias（典型如 `'@': path.resolve(__dirname, 'src')`）必须同步改：
+ *   path.resolve(<args>, 'src')        → 'src' 替换为 'client/src'
+ *   path.resolve(<args>, 'src/<rest>') → 同上
+ *   path.join(<args>, 'src')           → 同上
+ *   './src' / './src/<rest>' 字符串    → './client/src' / './client/src/<rest>'
+ * 边界：仅匹配整段 'src' 起头（避免 'sub/src' 误改），保留单/双引号原样。
+ *
+ * 注：fullstack 形态识别 **不再** 通过 `defineConfig` 的 option 第二参，而是
+ * 由 `coding-preset-vite-react` 内部读 `process.env.MIAODA_APP_TYPE === '3'`
+ * 自动判断（fullstack stack 的 archType 是 3）—— 所以 vite.config 完全不需要
+ * 加 option，只需 alias 路径同步即可。
+ */
+function rewriteViteConfigForFullstack(source) {
+    const { text, count } = rewriteAliasSrcPaths(source);
+    return { text, aliasRewriteCount: count };
+}
+/**
+ * vite.config 里 alias 路径重写：`src` 起头的路径加 `client/` 前缀。
+ *
+ * 匹配的形态（不限制在 resolve.alias 块内 —— vite.config 顶层很少出现非 alias 用的
+ * `src` 字符串，业务 import 走 `@/...`，所以全文匹配是安全的）：
+ *
+ *   path.resolve(<args>, 'src')             → path.resolve(<args>, 'client/src')
+ *   path.resolve(<args>, 'src/<rest>')      → path.resolve(<args>, 'client/src/<rest>')
+ *   path.join(<args>, 'src')                → 同上
+ *   './src' / './src/<rest>'（独立字符串）  → './client/src' / './client/src/<rest>'
+ *
+ * 已含 `client/src` 的不动（视为已迁移），`sub/src` 之类（src 不在词首）不动。
+ */
+function rewriteAliasSrcPaths(source) {
+    let count = 0;
+    // path.resolve(...) / path.join(...) 的最后一个参数是 'src' 或 'src/...' 起头
+    // 匹配 ['"]src[/'"]，保留引号
+    const pathCallRe = /(\bpath\s*\.\s*(?:resolve|join)\s*\([^)]*?,\s*)(['"`])(src)(\/[^'"`]*)?(['"`])/g;
+    let next = source.replace(pathCallRe, (_match, prefix, q1, _src, rest, q2) => {
+        count++;
+        return `${prefix}${q1}client/src${rest ?? ''}${q2}`;
+    });
+    // 独立的相对路径字符串字面量 './src' 或 './src/...'（不在 path.resolve 参数里）
+    // 注意：path.resolve / join 已被上一步处理，这里只匹配剩下的 './src...' 字面量。
+    // 这种用法在 vite.config 较少（典型是直接给 alias 字符串值），但兜底处理。
+    const relativeRe = /(['"`])\.\/(src)(\/[^'"`]*)?(['"`])/g;
+    next = next.replace(relativeRe, (_match, q1, _src, rest, q2) => {
+        count++;
+        return `${q1}./client/src${rest ?? ''}${q2}`;
+    });
+    return { text: next, count };
+}
+function applyAddDepsFromTemplate(rule, opts) {
+    const logPrefix = opts.logPrefix ?? 'migrate';
+    const userPath = node_path_1.default.join(opts.targetDir, rule.to ?? 'package.json');
+    const tplPath = node_path_1.default.join(opts.sourceRoot, rule.from ?? 'package.json');
+    if (!node_fs_1.default.existsSync(userPath)) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to ?? 'package.json'} (not found, skip add-deps-from-template)`);
+        return { rule, action: 'skipped', path: rule.to ?? 'package.json' };
+    }
+    if (!node_fs_1.default.existsSync(tplPath)) {
+        (0, logger_1.log)(logPrefix, `  ⚠ template ${rule.from ?? 'package.json'} not found, skip add-deps-from-template`);
+        return { rule, action: 'skipped', path: rule.to ?? 'package.json' };
+    }
+    const userText = node_fs_1.default.readFileSync(userPath, 'utf-8');
+    const userJson = JSON.parse(userText);
+    const tplJson = JSON.parse(node_fs_1.default.readFileSync(tplPath, 'utf-8'));
+    const added = [];
+    const missingInTpl = [];
+    for (const grp of ['dependencies', 'devDependencies']) {
+        const whitelist = rule[grp] ?? [];
+        if (whitelist.length === 0)
+            continue;
+        userJson[grp] ??= {};
+        for (const dep of whitelist) {
+            // 在 template 里找版本号：优先 tpl 同 grp，其次另一 grp（template 可能把 dep 写在
+            // dependencies/devDependencies 任一处，跟 user 当前 grp 不一定一致）
+            const tplVersion = tplJson[grp]?.[dep] ??
+                (grp === 'dependencies' ? tplJson.devDependencies?.[dep] : tplJson.dependencies?.[dep]);
+            if (tplVersion === undefined) {
+                missingInTpl.push(dep);
+                continue;
+            }
+            userJson[grp][dep] = tplVersion;
+            added.push(`${grp}.${dep}`);
+        }
+    }
+    if (added.length === 0 && missingInTpl.length === 0) {
+        (0, logger_1.log)(logPrefix, `  ○ ${rule.to ?? 'package.json'} (no deps to add)`);
+        return { rule, action: 'noop', path: rule.to ?? 'package.json' };
+    }
+    const trailing = userText.endsWith('\n') ? '\n' : '';
+    node_fs_1.default.writeFileSync(userPath, JSON.stringify(userJson, null, 2) + trailing);
+    (0, logger_1.log)(logPrefix, `  ✓ ${rule.to ?? 'package.json'} (added ${added.length.toString()} dep(s)${missingInTpl.length > 0 ? `; ${missingInTpl.length.toString()} missing in template: ${missingInTpl.join(', ')}` : ''})`);
+    return {
+        rule,
+        action: 'patched',
+        path: rule.to ?? 'package.json',
+        detail: added.join(','),
+    };
+}
 /**
  * 按 dot path 删除嵌套对象里的一个 leaf key。返回是否真的删了一项。
  * 不支持包含 `.` 的字段名（实际 dep 名 / scripts 名不会含 `.`，够用）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.16-alpha.0",
+  "version": "0.1.16-alpha.452772a",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {
@@ -17,20 +17,6 @@
     "dist",
     "upgrade"
   ],
-  "scripts": {
-    "build": "bash scripts/build.sh",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "lint": "eslint src/ --max-warnings 0",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "test": "vitest run --project=unit",
-    "test:watch": "vitest --project=unit",
-    "test:integration": "vitest run --project=integration",
-    "dev": "node --import tsx src/main.ts",
-    "cli": "node --env-file-if-exists=integration/.env --import tsx src/main.ts",
-    "prepare": "husky",
-    "prepublishOnly": "pnpm format:check && pnpm lint && pnpm build && pnpm test"
-  },
   "keywords": [
     "miaoda",
     "cli",
@@ -65,5 +51,16 @@
     "vitest": "^4.1.4",
     "xml2js": "^0.6.2"
   },
-  "packageManager": "pnpm@10.16.1+sha512.0e155aa2629db8672b49e8475da6226aa4bdea85fdcdfdc15350874946d4f3c91faaf64cbdc4a5d1ab8002f473d5c3fcedcd197989cf0390f9badd3c04678706"
-}
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src/ --max-warnings 0",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "vitest run --project=unit",
+    "test:watch": "vitest --project=unit",
+    "test:integration": "vitest run --project=integration",
+    "dev": "node --import tsx src/main.ts",
+    "cli": "node --env-file-if-exists=integration/.env --import tsx src/main.ts"
+  }
+}