@lark-apaas/miaoda-cli 0.1.39-alpha.8b4b278 → 0.1.39-alpha.8eeaf6e

package/README.md

@@ -56,9 +56,14 @@ miaoda file ls --output json
 
 `miaoda app init / sync / migrate` 管理本地应用工程（平台调用方与本地开发共用）：
 
-- `init`：按 `--template` 或 `--app-type` 渲染模板（`full_stack → nestjs-react-fullstack`，`frontend / jspage → vite-react`）。工程已存在时不重新渲染、不覆盖业务代码，只输出就绪核验结果 `ready / problems`；`--strict` 下未就绪（meta 损坏、stack 不符、必要文件缺失、依赖未安装、上次操作失败）退出码 1。同步安装失败输出 `status=failed` 并退出码 1。
-- `sync`：按 stack 的同步规则更新平台托管内容。全栈工程的托管文件是明确清单（`scripts/dev.sh`、`dev.js`、`dev-local.js`、`build.sh`、`run.sh`、`lint.js`、`prune-smart.js`、`hooks/run-precommit.js` 与 `.githooks/pre-commit`），`scripts/` 下其他用户文件保留；连续执行无漂移。依赖安装失败输出 `status=failed` 并退出码 1。
-- `migrate`（不在 help 列表中展示）：工程转换原语，在原工程目录内执行。目标模板先渲染到临时模板目录（不复制用户工程），再只读预检冲突：同路径不同内容、重复插件 ID、无法确定的 package.json / tsconfig / vite.config / index.html 形态等返回 `status=conflict` 与具体路径，工程不写入。预检通过后在原目录定向转换（`src/ public/ → client/`、插件迁 `server/capabilities`、配置定向适配），执行中出现的冲突即停、不覆盖用户不同内容；随后在原目录安装依赖并完整构建（`npm run build`）。任一阶段失败退出码 1，`failure.stage` 给出 `install` / `verify` 等阶段，现场保留、不自动回滚；`originalIntact=true` 仅表示失败发生在任何工程写入之前，写入后一律为 false（已写入文件见 `changes`）。磁盘已是目标布局时走 repair（补齐适配 / 安装 / 构建，保留已有 `node_modules` 接续安装），不返回 NOOP；meta 已是目标 stack 不代表上次成功，以 `.spark/local/engineering-state.json` 的终态为准。放弃转换由调用方按代码版本恢复。输出包含源 / 目标 stack、模板与 CLI 版本、真实阶段结果与冲突路径；运行 readiness 由调用方核验（`readiness.status=pending_caller_verification`），`restartSignalSent` 只表示发出了重启信号。执行期间的并发编辑由调用方现有互斥与调度保证。
+- `init`：按 `--template` 或 `--app-type` 渲染模板（`full_stack → nestjs-react-fullstack`，`frontend / jspage → vite-react`）。工程已存在时不重新渲染、不覆盖业务代码，只输出就绪核验结果 `ready / problems`；`--strict` 下未就绪（meta 损坏、stack 不符、必要文件缺失、依赖未安装、上次操作失败）退出码 1。同步安装失败输出 `status=failed`、`failedStage=install`；退出码只在 `--strict` 时为 1，不带 `--strict` 时为 0（依赖由后续 `sync` 补装）。
+- `sync`：按 stack 的同步规则更新平台托管内容。全栈工程的托管文件是明确清单（`scripts/dev.sh`、`dev.js`、`dev-local.js`、`build.sh`、`run.sh`、`lint.js`、`prune-smart.js`、`hooks/run-precommit.js` 与 `.githooks/pre-commit`），`scripts/` 下其他用户文件保留；连续执行无漂移。依赖安装失败输出 `status=failed`、`failedStage=install`；退出码只在 `--strict`（平台严格调用）时为 1，不带 `--strict` 时为 0，`dev.sh` 与 lark-cli `+init` 不带它。
+- `migrate`（不在 help 列表中展示）：工程转换原语，在原工程目录内执行。目标模板先渲染到临时模板目录（不复制用户工程），再只读预检冲突（同路径不同内容、重复插件 ID、自定义同名 script、无法确定的 package.json / tsconfig / vite.config / index.html 形态等），随后在原目录定向转换（`src/ public/ → client/`、插件迁 `server/capabilities`、配置定向适配）并安装依赖；迁移配置声明了验证步骤时再执行验证（vite-react → 全栈不做完整构建）。冲突按 `--purpose` 决定的策略处理，结果字段 `conflictPolicy` 给出本次策略：
+  - `stop`（`--purpose upgrade` / `history_restore`，平台调用）：预检发现冲突返回 `status=conflict` 与具体路径，工程不写入；执行中才出现的冲突即停、不覆盖用户不同内容。
+  - `overwrite`（`--purpose manual`，默认；feida-ai 升级全栈与本机手动执行）且跨 stack 转换：冲突处按模板覆盖并继续 —— 自定义同名 script 改成平台命令，tsconfig、`server/main.ts` / `app.module.ts`、无法适配的 `index.html` 换成模板，定制的 `eslint.config.mjs` 删除，`src/ public/` 与 `client/` 下同名文件由前者覆盖。被替换的用户内容逐条列在 `overwritten`（`path` / `reason` / `with`），不备份、不自动提交，需要时从 git 历史找回。无可替换模板内容的保留用户内容并给出 `code=MIGRATE_CONFLICT_KEPT` 的 warning：自定义 `prepare` script、不同文件的重复插件 ID（两份都搬入）、未用平台 preset 的 `vite.config.ts`（只改 alias）、非 `.ts` 的 vite 配置。文件 / 目录类型不一致与 `package.json` 不可解析仍按冲突停止。
+  - `keep`（`--purpose manual` 且磁盘已是目标布局）：冲突处保留用户在已转换工程上的改动（同样给出 `MIGRATE_CONFLICT_KEPT` warning），其余照常修复。
+
+  不安全的符号链接在任何策略下都按冲突停止（见下）。任一阶段失败退出码 1，`failure.stage` 给出 `install` / `verify` 等阶段，现场保留、不自动回滚；例外是 `--purpose manual` 只有依赖安装失败时：结果仍是 `status=failed`、`install.status=failed`，退出码 0，由调用方补装（平台调用 `upgrade` / `history_restore` 仍为 1）。`--app-id` / `MIAODA_APP_ID` 与 meta 的 `app_id` 不一致时，沙箱内按当前应用改写 meta（复制来的工程，warning `MIGRATE_APP_ID_REWRITTEN`），本机拒绝（`MIGRATE_APP_ID_MISMATCH`）。`originalIntact=true` 仅表示失败发生在任何工程写入之前，写入后一律为 false（已写入文件见 `changes`）。磁盘已是目标布局时走 repair（补齐适配 / 安装，保留已有 `node_modules` 接续安装），不返回 NOOP；meta 已是目标 stack 不代表上次成功，以 `.spark/local/engineering-state.json` 的终态为准。放弃转换由调用方按代码版本恢复。输出包含源 / 目标 stack、模板与 CLI 版本、真实阶段结果与冲突路径；运行 readiness 由调用方核验（`readiness.status=pending_caller_verification`）。沙箱内只向工作目录就是被转换目录的 dev 进程发重启信号（在工程副本等其他目录执行不影响正在运行的应用），`restartSignalSent` 只表示发出了重启信号。执行期间的并发编辑由调用方现有互斥与调度保证。
 
 `migrate` 不自动解引用工程外文件。迁移涉及的文件或父目录存在符号链接时，在规则执行前返回 `MIGRATE_UNSAFE_SYMLINK` 和具体 `conflicts[].path`；请改为工程拥有的普通文件或目录后重试。`html → design-html` 的 `src → .` 涉及整个工程根目录。原目录 install/build 前拒绝绝对链接、工程外链接、无法解析的链接及指向排除目录的链接；未触及且在工程内解析的相对业务链接保留，安装生成的普通 `node_modules/.bin` 相对链接允许。规则执行后、安装后及构建前再次检查链接边界。扫描失败返回 `MIGRATE_SYMLINK_CHECK_FAILED`；失败或链接冲突在安全的 `.spark/local` 写入终态，状态写路径不安全时不写入并给出 warning。该检查不是 npm 脚本的安全沙箱，不限制脚本主动访问其他绝对路径。
 

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

@@ -40,11 +40,11 @@ function registerAppMigrate(parent) {
     // 用 addCommand(cmd, { hidden: true }) 而非 parent.command(...)，因为 commander 13
     // 的 fluent `.command()` 不支持设置 hidden。
     const cmd = new commander_1.Command('migrate')
-        .description('工程转换原语：原目录内按 MigrateConfig 预检冲突 → 定向转换 → 安装 → 严格验证；冲突不覆盖用户内容，失败保留现场')
+        .description('工程转换原语：原目录内按 MigrateConfig 预检冲突 → 定向转换 → 安装；冲突按调用目的即停或按模板覆盖，失败保留现场')
         .requiredOption('--to <stack>', '目标 stack 短名')
         .option('--from <stack>', '源 stack；默认按磁盘实际布局识别（识别不了再读 .spark/meta.json）')
         .option('--dir <path>', '项目目录，默认 cwd')
-        .option('--purpose <purpose>', '调用目的：manual / upgrade / copy_adapt / history_restore（只用于记录与关联）', 'manual')
+        .option('--purpose <purpose>', '调用目的：manual / upgrade / history_restore；决定冲突策略（见下文），同时用于记录与关联', 'manual')
         .option('--operation-ref <id>', '调用方已有的操作 / 任务关联标识，原样回显')
         .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
@@ -54,28 +54,51 @@ function registerAppMigrate(parent) {
 
 文件规则
   明确托管的平台脚本（scripts 清单 + .githooks/pre-commit）按模板更新，scripts/ 下用户文件保留；
-  src/ public/ 搬入 client/、插件迁 server/capabilities，同路径不同内容或重复插件 ID → 冲突；
-  server / shared 只补平台缺失文件，app.module.ts 定向注册平台模块；package.json scripts、
-  tsconfig、vite.config、index.html 定向适配，无法确定的形态 → 冲突，不整文件覆盖。
+  src/ public/ 搬入 client/、插件迁 server/capabilities；server / shared 只补平台缺失文件，
+  app.module.ts 定向注册平台模块；package.json scripts、tsconfig、vite.config、index.html 定向适配。
+  同路径不同内容、重复插件 ID、自定义同名 script、无法确定的配置形态即为冲突，按冲突策略处理。
+
+冲突策略（conflictPolicy，由 --purpose 与磁盘布局决定）
+  stop       --purpose upgrade / history_restore（平台调用）：预检发现冲突即停、工程不写入；
+             执行中才出现的冲突即停，不覆盖用户内容
+  overwrite  --purpose manual（默认）且跨 stack 转换：冲突处按模板覆盖 —— 自定义同名 script 改成平台命令，
+             tsconfig / server 入口 / 无法适配的 index.html 换成模板，定制的 eslint.config.mjs 删除，
+             src/ public/ 与 client/ 同名文件由前者覆盖，被替换的列在 overwritten；
+             自定义 prepare script、不同文件的重复插件 ID（两份都搬入）、未用平台 preset 的 vite.config（只改 alias）、
+             非 .ts 的 vite 配置保留用户内容，记为 code=MIGRATE_CONFLICT_KEPT 的 warning；
+             文件 / 目录类型不一致、package.json 不可解析仍按冲突停止
+  keep       --purpose manual 且磁盘已是目标布局（repair）：冲突处保留用户内容（warning 同上），其余照常修复
+  不安全的符号链接在任何策略下都按冲突停止（MIGRATE_UNSAFE_SYMLINK）。
 
 结果语义
-  status=converted  原目录内文件适配、依赖安装、严格验证（全栈为完整构建）全部完成；
-                    运行 readiness 由调用方核验（readiness.status=pending_caller_verification），
+  status=converted  原目录内文件适配、依赖安装、配置了的验证步骤全部完成；
+                    运行 readiness 由调用方核验（readiness.status=pending_caller_verification）；
+                    沙箱里只向工作目录为本工程的 dev 进程发重启信号，
                     restartSignalSent / devRestarted 只表示发出了重启信号
   status=conflict   conflicts 给出具体路径 / ID，冲突文件不覆盖
   status=failed     failure.stage / failure.code 给出失败阶段与原因，现场保留、不自动回滚
   originalIntact=true 仅表示失败发生在任何工程写入之前；写入后为 false（部分改动见 changes）。
   失败后对同一工程重跑同目标 migrate 即按真实布局 repair（可接续安装 / 构建）。
-  非 converted 退出码为 1。
+  非 converted 退出码为 1。例外：--purpose manual 时只有依赖安装失败（failure.stage=install），
+  结果仍是 status=failed、install.status=failed，但退出码 0 —— 文件已转换，依赖由调用方补装；
+  平台调用（upgrade / history_restore）安装失败仍为退出码 1。
+
+应用身份（app_id）
+  --app-id / MIAODA_APP_ID 与 .spark/meta.json 的 app_id 不一致时：
+    沙箱内 → 视为复制来的工程，按当前应用改写 meta.app_id（随转换写入），warnings 给出
+             code=MIGRATE_APP_ID_REWRITTEN
+    本机   → 拒绝（MIGRATE_APP_ID_MISMATCH），不渲染、不写入
 
 JSON 输出
   {"data": {"status": "converted|conflict|failed", "mode": "migrate|repair", "runId": "...",
-            "purpose": "...", "operationRef": "...",
+            "purpose": "...", "conflictPolicy": "stop|overwrite|keep", "operationRef": "...",
             "source": {"metaStack": "...", "detectedStack": "...", "stack": "..."},
             "target": {"stack": "...", "templatePackage": "...", "templateVersion": "...", "cliVersion": "..."},
             "stages": [{"name": "preflight|render|precheck|apply|install|verify|restart", "status": "...", "durationMs": 0}],
             "failure": {"stage": "...", "code": "...", "message": "...", "retryable": true},
             "conflicts": [{"path": "...", "reason": "...", "with": "...", "id": "..."}],
+            "overwritten": [{"path": "...", "reason": "...", "with": "..."}],
+            "warnings": [{"path": "...", "code": "MIGRATE_CONFLICT_KEPT", "message": "..."}],
             "changes": {"added": [...], "modified": [...], "deleted": [...]},
             "install": {"status": "ok|failed|not_run"}, "verify": {"status": "...", "steps": [...]},
             "originalIntact": true,
@@ -105,6 +128,7 @@ function registerAppSync(parent) {
         .alias('upgrade')
         .description('一站式同步：按 stack 的 SyncRule 全套 apply + 按钉死版本表升 @lark-apaas/* deps + npm install')
         .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .option('--strict', '平台严格调用：依赖安装失败时以退出码 1 结束', false)
         .addHelpText('after', `
 别名
   miaoda app sync 与 miaoda app upgrade 等价（upgrade 是历史别名，新调用方请用 sync）。
@@ -115,7 +139,7 @@ function registerAppSync(parent) {
        file           → 单文件覆盖（可选 onlyIfExists / overwrite）
        merge-json     → JSON deep merge（可选 arrayMerge by key 去重）
        add-script     → npm script 不存在时添加（overwrite=false 默认不覆盖）
-       patch-script   → npm script 以指定前缀开头时改写（守护用户自定义）
+       patch-script   → npm script 以指定前缀开头、或整值匹配平台旧值时改写（守护用户自定义）
        add-line       → 行不存在时追加到文件
        remove-line    → 行存在时移除
        delete-file/delete-directory → 删除
@@ -127,8 +151,8 @@ function registerAppSync(parent) {
   4. npm install --no-audit --no-fund --ignore-scripts。--ignore-scripts 是为绕开
      action-plugin postinstall 在 npm install 时缺平台 env 的卡点（需要时再
      FORCE_AUTHN_INNERAPI_DOMAIN=... npm install 手动跑一次）。
-     安装是必要步骤：失败时输出 status=failed、failedStage=install 与 installError，退出码 1
-     （已应用的文件规则保留，重跑 sync 幂等补齐）。
+     安装失败时输出 status=failed、failedStage=install 与 installError（已应用的文件规则保留，
+     重跑 sync 幂等补齐）。退出码：--strict 时为 1；不带 --strict 时为 0，调用方按 status 判断。
 
   nestjs-react-fullstack 的平台托管文件是明确清单（scripts/dev.sh、dev.js、dev-local.js、
   build.sh、run.sh、lint.js、prune-smart.js、hooks/run-precommit.js 与 .githooks/pre-commit），
@@ -149,11 +173,13 @@ JSON 输出
 示例
   $ miaoda app sync
   $ miaoda app sync --dir /path/to/app
+  $ miaoda app sync --strict  # 平台调用：安装失败退出码 1
   $ miaoda app upgrade        # 等价于 miaoda app sync
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         await (0, index_1.handleAppSync)({
             dir: rawOpts.dir,
+            strict: rawOpts.strict,
         });
     }));
 }
@@ -344,7 +370,7 @@ function registerAppInit(parent) {
         .option('--conf [json]', 'init 配置 JSON。支持 {"version": "<template 版本>"}，默认 latest')
         .option('--skip-install', '跳过依赖安装', false)
         .option('--async-install', '派发后台进程装依赖并立即返回（与 --skip-install 互斥）', false)
-        .option('--strict', '平台严格调用：工程已存在时核验是否真正就绪（meta 可解析、stack 匹配、必要文件、依赖安装、上次操作结果），未就绪退出码 1', false)
+        .option('--strict', '平台严格调用：工程已存在时核验是否真正就绪（meta 可解析、stack 匹配、必要文件、依赖安装、上次操作结果），未就绪退出码 1；新初始化时同步安装失败也以退出码 1 结束', false)
         .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
 幂等
@@ -355,9 +381,10 @@ function registerAppInit(parent) {
   上一次失败留下半渲染状态时（package.json 在但 meta.json 没在）允许重跑。
 
 依赖安装失败
-  同步安装失败时 init 输出 status=failed、failedStage=install 并以退出码 1 结束；
-  已渲染的脚手架与 meta 保留（避免重跑时覆盖已开始编辑的文件），本地执行记录标为 install_failed，
+  同步安装失败时 init 输出 status=failed、failedStage=install 与 installError；
+  已渲染的脚手架与 meta 保留（避免重跑时覆盖已开始编辑的文件），本地执行记录标为失败，
   后续 'miaoda app sync' 会补装依赖，--strict 在补装前报告未就绪。
+  退出码：--strict 时为 1；不带 --strict 时为 0，调用方按 status 判断。
 
 应用身份（app_id）
   --app-id <id>（或 MIAODA_APP_ID env）提供时写入 .spark/meta.json 的 app_id 字段；

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

@@ -37,8 +37,10 @@ const engineering_state_1 = require("../../../utils/engineering-state");
  * ready / problems —— meta 存在不等于就绪；--strict 时未就绪退出码 1。
  * 半渲染状态（package.json 在但 meta.json 不在）会重新跑完整流程。
  *
- * 同步安装失败是失败：meta 仍写出（脚手架已渲染，避免重跑覆盖已开始编辑的文件），本地执行
- * 记录标为失败，输出 status=failed / failedStage=install 并退出码 1。
+ * 同步安装失败：meta 仍写出（脚手架已渲染，避免重跑覆盖已开始编辑的文件），本地执行记录标为
+ * 失败，输出 status=failed / failedStage=install。只有 --strict（平台严格调用）以退出码 1 结束；
+ * 不带 --strict 时退出码 0 —— lark-cli `+init` 等调用方按退出码判成败，且依赖由后续
+ * `miaoda app sync`（dev.sh 入口）补装，安装抖动不能让整条初始化失败。
  */
 async function handleAppInit(opts) {
     await Promise.resolve();
@@ -224,11 +226,16 @@ async function handleAppInit(opts) {
         },
     });
     if (installFailed) {
-        (0, output_1.emitError)(new error_1.AppError('INIT_INSTALL_FAILED', `npm install failed: ${installResult?.error ?? ''}`, {
-            retryable: true,
-            next_actions: ['修复安装错误后执行 miaoda app sync 补装依赖'],
-        }));
-        process.exitCode = 1;
+        if (opts.strict) {
+            (0, output_1.emitError)(new error_1.AppError('INIT_INSTALL_FAILED', `npm install failed: ${installResult?.error ?? ''}`, {
+                retryable: true,
+                next_actions: ['修复安装错误后执行 miaoda app sync 补装依赖'],
+            }));
+            process.exitCode = 1;
+        }
+        else {
+            (0, logger_1.log)('init', '⚠ npm install failed (continuing; run `miaoda app sync` to install later)');
+        }
     }
 }
 function recordInitState(targetDir, status, stage, error) {

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

@@ -9,6 +9,7 @@ const index_1 = require("../../../services/app/migrate/index");
 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 package_json_1 = __importDefault(require("../../../../package.json"));
 /**
  * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>] [--purpose <p>] [--operation-ref <id>]
@@ -16,14 +17,16 @@ const package_json_1 = __importDefault(require("../../../../package.json"));
  * 工程转换原语的 CLI 入口：参数校验 + 结构化输出，转换流程在 services/app/migrate。
  *
  * 结果语义：
- *   status=converted：原目录内文件适配、依赖安装、严格验证（全栈为完整构建）全部完成。
+ *   status=converted：原目录内文件适配、依赖安装、配置了的验证步骤全部完成。
+ *     conflictPolicy=overwrite 时被模板替换的用户内容列在 overwritten；保留未适配的位置是
+ *     code=MIGRATE_CONFLICT_KEPT 的 warning。
  *     运行 readiness 不在 CLI 内判定（readiness.status=pending_caller_verification）——
- *     沙箱里 restartSignalSent / devRestarted 只表示发出了 pkill 重启信号，不是健康结果。
- *   status=conflict：存在无法确定性处理的冲突（conflicts 给出具体路径 / ID），冲突文件不覆盖；
+ *     沙箱里 restartSignalSent / devRestarted 只表示向本目录的 dev 进程发出了重启信号，不是健康结果。
+ *   status=conflict：存在当前冲突策略下无法处理的冲突（conflicts 给出具体路径 / ID），冲突文件不覆盖；
  *     预检阶段发现时工程未写入（originalIntact=true），应用阶段发现时可能已有部分改动。
  *   status=failed：某阶段失败（failure.stage / code），现场原样保留、不自动回滚；
  *     originalIntact=true 仅表示失败发生在任何工程写入之前。
- *   非 converted 一律退出码 1。
+ *   非 converted 退出码 1，唯一例外见 isLenientInstallFailure：manual 调用只是依赖没装上时退出码 0。
  *
  * 同目标（磁盘已是目标布局）不再返回 MIGRATE_NOOP：走 repair 模式补齐适配 / 安装 / 构建，
  * 支持"平台已新但恢复了旧代码"与"目标 meta 已写、安装未完成"的样本。
@@ -50,6 +53,10 @@ async function handleAppMigrate(opts) {
     });
     const data = toOutput(outcome, sandbox);
     (0, output_1.emit)({ data });
+    if (isLenientInstallFailure(outcome)) {
+        (0, logger_1.log)('migrate', '⚠ npm install failed (continuing): 文件已转换，依赖需调用方补装');
+        return;
+    }
     if (outcome.status !== 'converted') {
         // 结构化结果在 stdout；stderr 同时给出一条标准错误，便于只看退出码 / stderr 的调用方
         (0, output_1.emitError)(new error_1.AppError(outcome.failure?.code ?? 'MIGRATE_FAILED', outcome.failure?.message ?? outcome.status, {
@@ -59,12 +66,25 @@ async function handleAppMigrate(opts) {
         process.exitCode = 1;
     }
 }
+/**
+ * manual 调用（feida-ai 升级全栈 / html → design-html、本机手动执行）只是依赖没装上：结果仍是
+ * status=failed、install.status=failed，但退出码 0。这些调用方只看退出码：退出码非 0 时，升级全栈
+ * 照样切应用类型、却跳过它自己的 `npm install --force` 补装；design-html 不回写库里的 stack，
+ * 而下一轮读到已转换的 meta 又跳过迁移，库与沙箱永久不一致。文件已转换、依赖可补装，
+ * 按 0.1.46 的软失败交还调用方。平台调用（upgrade / history_restore）按结构化结果推进，保持严格。
+ */
+function isLenientInstallFailure(outcome) {
+    return (outcome.purpose === 'manual' &&
+        outcome.status === 'failed' &&
+        outcome.failure?.stage === 'install');
+}
 function toOutput(outcome, sandbox) {
     return {
         status: outcome.status,
         mode: outcome.mode,
         runId: outcome.runId,
         purpose: outcome.purpose,
+        conflictPolicy: outcome.conflictPolicy,
         operationRef: outcome.operationRef,
         from: outcome.source.stack,
         to: outcome.target.stack,
@@ -75,6 +95,7 @@ function toOutput(outcome, sandbox) {
         failure: outcome.failure,
         warnings: outcome.warnings,
         conflicts: outcome.conflicts,
+        overwritten: outcome.overwritten,
         changes: outcome.changes,
         appliedRules: outcome.results.map((r) => ({
             type: r.rule.type,
@@ -114,13 +135,22 @@ function nextActions(outcome, sandbox) {
             '如需放弃本次转换，由调用方按代码版本（如 git）恢复原工程',
         ];
     }
+    const policyActions = [];
+    if (outcome.overwritten.length > 0) {
+        policyActions.push('overwritten 列出的用户改动已被模板替换：用 git diff 核对，需要保留的业务改动从 git 历史手动合回');
+    }
+    if (outcome.warnings.some((w) => w.code === 'MIGRATE_CONFLICT_KEPT')) {
+        policyActions.push('warnings 中 MIGRATE_CONFLICT_KEPT 的位置保留了用户内容、未按目标 stack 适配，按需手动调整');
+    }
     return sandbox
         ? [
+            ...policyActions,
             '调用方核验沙箱 dev 进程与预览 readiness（restartSignalSent 只表示发出了重启信号）',
             'git status / git diff 评估改动并 commit',
             'miaoda skills sync 同步到新 stack 的 agent skills',
         ]
         : [
+            ...policyActions,
             '重启 dev 进程让新 scripts/dev.js + 新依赖生效：重跑 npm run dev，并验证预览',
             'git status / git diff 评估改动并 commit',
             'miaoda skills sync 同步到新 stack 的 agent skills',

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

@@ -47,7 +47,7 @@ const MANAGED_PLATFORM_PACKAGES = {
     '@lark-apaas/http-client': 'latest',
 };
 /**
- * miaoda app sync [--dir <path>]
+ * miaoda app sync [--dir <path>] [--strict]
  *
  * 一站式同步：把当前 stack 的 sync 规则全套 apply 到 user app，对齐沙箱里
  * `npm run upgrade → npx fullstack-cli sync` 的行为，并补 miaoda-cli 本地开发独有规则。
@@ -108,8 +108,9 @@ async function handleAppSync(opts) {
     (0, logs_dir_1.ensureLogsDir)(targetDir);
     // 3. snapshot 当前 user app 装的管控包版本，供 install 后 diff 用
     const beforeSpecs = snapshotManagedDepSpecs(targetDir);
-    // 4. npm install —— 必要步骤：失败时仍输出完整的规则应用结果，但 status=failed + 退出码 1，
-    //    不把"文件同步了、依赖没装上"报成成功。已应用的规则保留（规则幂等，重跑 sync 补齐）。
+    // 4. npm install —— 失败时仍输出完整的规则应用结果，status=failed，不把"文件同步了、依赖没装上"
+    //    报成成功；已应用的规则保留（规则幂等，重跑 sync 补齐）。只有 --strict 以退出码 1 结束：
+    //    dev.sh 与 lark-cli `+init` 不带 --strict，后者按退出码判成败，安装抖动不能让它整条失败。
     // 把 user app 装着的**所有**管控包显式作为 `<pkg>@latest` 位置参数传给 npm install:
     //   - npm 自然会把 spec 改写成 ^具体最新版,lockfile 同步更新 → 不需要 sync 主动改 spec
     //   - 没装的管控包不动 (sync 的职责是对齐,不是塞依赖)
@@ -137,7 +138,9 @@ async function handleAppSync(opts) {
     }
     catch (err) {
         installError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('sync', `✗ npm install failed: ${installError}`);
+        (0, logger_1.log)('sync', opts.strict
+            ? `✗ npm install failed: ${installError}`
+            : `⚠ npm install failed (continuing): ${installError}`);
     }
     // 5. install 之后再读一次 package.json，diff 出 npm 实际改写的 spec
     const afterSpecs = snapshotManagedDepSpecs(targetDir);
@@ -160,7 +163,7 @@ async function handleAppSync(opts) {
                 : undefined,
         },
     });
-    if (failed) {
+    if (failed && opts.strict) {
         (0, output_1.emitError)(new error_1.AppError('SYNC_INSTALL_FAILED', `npm install failed: ${installError ?? ''}`, {
             retryable: true,
             next_actions: ['修复安装错误（网络 / registry / 依赖冲突）后重跑 miaoda app sync'],

package/dist/config/fullstack-managed-files.js

@@ -49,8 +49,9 @@ function managedFileRules() {
 }
 /**
  * 托管构建脚本的配套依赖：build.sh 的智能裁剪（prune-smart.js）require('@vercel/nft')，模板与
- * 沙箱镜像都不提供它。migrate / repair 后的验证要跑完整 npm run build，所以对未声明的工程补
- * devDependencies（版本为实测的 0.30.4）；已声明的用户版本不降级、不覆盖。
+ * 沙箱镜像都不提供它。迁移后的工程第一次完整构建（发布或本地 npm run build）会用到，所以
+ * migrate / repair 对未声明的工程补 devDependencies（版本为实测的 0.30.4）；已声明的用户版本
+ * 不降级、不覆盖。
  */
 exports.FULLSTACK_MANAGED_BUILD_DEV_DEPENDENCIES = {
     '@vercel/nft': '0.30.4',

package/dist/config/migrate-configs/html-to-design-html.js

@@ -19,7 +19,7 @@
  *   - 不从 design-html template 拷任何文件（模板本身只有 _gitignore + package.json；
  *     用户已有的 .gitignore 是 html 版超集，保留无害）
  *   - 不动 README.md / .npmrc / .env —— 部署时均被 EXCLUDES 过滤
- *   - 不管 dev 进程 / MIAODA_APP_TYPE 切换（平台职责；沙箱 pkill 匹配的
+ *   - 不管 dev 进程 / MIAODA_APP_TYPE 切换（平台职责；沙箱重启信号匹配的
  *     scripts/dev.js 在 html 项目里不存在，自然跳过）
  *
  * handler 收尾的 npm install 照常跑：devserver 依赖删掉后重新生成精简 lockfile，

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

@@ -2,7 +2,7 @@
 /**
  * vite-react → nestjs-react-fullstack 的跨 stack 迁移规则。
  *
- * 设计原则：**明确托管清单 + 定向适配 + 冲突停止**。
+ * 设计原则：**明确托管清单 + 定向适配 + 冲突按调用方策略处理**。
  *   - 明确托管的平台文件（scripts 清单、.githooks/pre-commit）按兼容模板整文件更新；清单外的
  *     scripts/ 用户文件保留。
  *   - 业务代码、server/shared、插件不整目录覆盖：只补平台启动所需的缺失文件，已有 app.module.ts
@@ -10,20 +10,22 @@
  *   - package.json / tsconfig / vite.config / index.html 等混合配置只改本次运行要求的部分，
  *     保留 alias、paths、用户编译选项、HTML 自定义 head、额外 scripts 等业务部分。
  *   - 无法确定性处理（同路径不同内容、同 ID 插件、自定义同名 script、不支持的配置形态）一律
- *     action=conflict 不写入；执行前对原目录预检可识别冲突（不写盘），执行中出现的冲突即停止，
- *     不覆盖用户内容。
+ *     action=conflict。冲突策略 stop（平台调用）下：执行前对原目录预检可识别冲突（不写盘），执行中
+ *     出现的冲突即停止，不覆盖用户内容；overwrite（手动 / Agent 调用）下按各规则说明用模板替换，
+ *     替换不了的保留用户内容（见 config/migrate.ts 各规则类型）。
  *
  * 步骤：
  *   1. src/ public/ 搬到 client/ 下（同名不同内容 → 冲突）
- *   2. 旧 stack 平台残留：eslint.config.mjs 仅在是平台默认内容时删除；lockfile 删除（依赖集合变化）
+ *   2. 旧 stack 平台残留：补 eslint.config.js 并带上旧配置的 globalIgnores，eslint.config.mjs 仅在是
+ *      平台默认内容时删除；lockfile 删除（依赖集合变化）
  *   3. 删 user package.json 里 lite SDK / type=module
  *   4. server 平台启动文件按缺失补齐 + app.module.ts 定向注册 PlatformModule / ViewModule
- *   5. nest-cli.json 合并、tsconfig 三件套定向适配、eslint/stylelint 缺失补齐
+ *   5. nest-cli.json 合并、tsconfig 三件套定向适配（exclude 随布局改写）、stylelint 缺失补齐
  *   6. 根 index.html → client/index.html（HBS 骨架 + 用户 head/body 自定义部分）
  *   7. 托管脚本清单更新；shared / .env 缺失补齐
  *   8. 插件 shared/capabilities → server/capabilities（重复 ID 检查）
  *   9. scripts 定向适配（旧平台写法改写、自定义同名冲突）
- *  10. 从 fullstack template/package.json 取版本号，精确加 NestJS 强依赖白名单
+ *  10. 从 fullstack template/package.json 取版本号，精确加 NestJS 强依赖白名单（SWC 钉 lockfile 版本）
  *  11. codemod：lite → client-toolkit；vite.config alias src → client/src
  *  12. set-stack 切 .spark/meta.json
  *
@@ -43,6 +45,23 @@ const fullstack_managed_files_1 = require("../../config/fullstack-managed-files"
 const VITE_REACT_DEFAULT_ESLINT = 'import\\{globalIgnores\\}from"eslint/config"' +
     'import\\{eslintPresets\\}from"@lark-apaas/coding-presets-react"' +
     'exportdefault\\[(globalIgnores\\(\\[("[^"]*",?)*\\]\\),?)?\\.\\.\\.eslintPresets\\.client,?\\]';
+/**
+ * 早期 vite-react 模板（coding-template-vite-react 0.1.8～0.1.17，2026-05～06 初）默认的
+ * eslint.config.mjs（规范化后）：自包含的 flat config，直接引 @eslint/js / typescript-eslint /
+ * react-hooks / react-refresh，没有平台 preset。忽略列表允许不同。
+ */
+const VITE_REACT_EARLY_DEFAULT_ESLINT = 'importjsfrom"@eslint\\/js"' +
+    'importglobalsfrom"globals"' +
+    'importreactHooksfrom"eslint-plugin-react-hooks"' +
+    'importreactRefreshfrom"eslint-plugin-react-refresh"' +
+    'importtseslintfrom"typescript-eslint"' +
+    'import\\{defineConfig,globalIgnores\\}from"eslint\\/config"' +
+    'exportdefaultdefineConfig\\(\\[' +
+    'globalIgnores\\(\\[("[^"]*",?)*\\]\\),' +
+    '\\{files:\\["\\*\\*\\/\\*\\.\\{ts,tsx\\}"\\],' +
+    'extends:\\[js\\.configs\\.recommended,tseslint\\.configs\\.recommended,reactHooks\\.configs\\.flat\\.recommended,reactRefresh\\.configs\\.vite,\\],' +
+    'languageOptions:\\{ecmaVersion:2020,globals:globals\\.browser,\\},' +
+    'rules:\\{"react-refresh\\/only-export-components":"off","@typescript-eslint\\/no-unused-vars":"off","@typescript-eslint\\/no-explicit-any":"off","@typescript-eslint\\/no-empty-object-type":"off","@typescript-eslint\\/no-require-imports":"off","no-empty":"off","prefer-const":"off","no-unused-labels":"off",\\},\\},\\]\\)';
 exports.MIGRATE_CONFIG = {
     from: 'vite-react',
     to: 'nestjs-react-fullstack',
@@ -52,11 +71,16 @@ exports.MIGRATE_CONFIG = {
         { type: 'move-directory', from: 'public', to: 'client/public', onConflict: 'fail' },
         // shared/ 不动（两边布局相同）；.env / .spark_project 同理。
         // ===== 2. 清理 vite-react 平台残留 =====
-        // ESLint 9 flat config 文件名变了（eslint.config.mjs → eslint.config.js）；用户改过则冲突
+        // ESLint 9 flat config 文件名变了（eslint.config.mjs → eslint.config.js）：先补新配置（用户已有则
+        // 保留），把旧配置 globalIgnores 的条目带过去 —— vite-react 模板排除了 **/components/ui/**，
+        // 不带过去 shadcn 组件会被 lint，组件里引用新版 react-hooks 规则的 disable 注释报"规则不存在"。
+        { type: 'file', from: 'eslint.config.js', to: 'eslint.config.js', overwrite: false },
+        { type: 'carry-eslint-ignores', from: 'eslint.config.mjs', to: 'eslint.config.js' },
+        // 旧配置用户改过则冲突
         {
             type: 'remove-known-default',
             to: 'eslint.config.mjs',
-            knownDefaults: [VITE_REACT_DEFAULT_ESLINT],
+            knownDefaults: [VITE_REACT_DEFAULT_ESLINT, VITE_REACT_EARLY_DEFAULT_ESLINT],
             reason: 'customized ESLint config (eslint.config.mjs) cannot be converted automatically; move custom rules into eslint.config.js extending @lark-apaas/fullstack-presets, then retry',
         },
         // 依赖集合变了，lockfile 由原目录里的 npm install 重新生成。
@@ -101,11 +125,14 @@ exports.MIGRATE_CONFIG = {
             role: 'app',
             from: 'tsconfig.app.json',
             to: 'tsconfig.app.json',
-            legacyExtends: ['@lark-apaas/coding-presets-react/lib/tsconfig/tsconfig.app.json'],
+            legacyExtends: [
+                '@lark-apaas/coding-presets-react/lib/tsconfig/tsconfig.app.json',
+                // 早期模板（0.1.8～0.1.17）的 preset 包名
+                '@lark-apaas/coding-presets/lib/tsconfig/tsconfig.app.json',
+            ],
         },
         { type: 'adapt-tsconfig', role: 'node', from: 'tsconfig.node.json', to: 'tsconfig.node.json' },
-        // ESLint / stylelint：缺失时补模板（用户已有则保留）
-        { type: 'file', from: 'eslint.config.js', to: 'eslint.config.js', overwrite: false },
+        // stylelint：缺失时补模板（用户已有则保留）；eslint.config.js 已在第 2 步补齐
         // package.json 的 `stylelint` script + precommit 会调它，缺配置时报 `No configuration provided`
         { type: 'file', from: '.stylelintrc.js', to: '.stylelintrc.js', overwrite: false },
         // ===== 6. HTML 入口：根 index.html → client/index.html（HBS） =====
@@ -183,6 +210,7 @@ exports.MIGRATE_CONFIG = {
                     name: 'prepare',
                     command: 'chmod +x .githooks/pre-commit 2>/dev/null; git config core.hooksPath .githooks 2>/dev/null || true',
                     legacy: ['node scripts/setup-git-hooks.mjs'],
+                    keepCustom: true,
                 },
                 {
                     name: 'upgrade',
@@ -269,6 +297,10 @@ exports.MIGRATE_CONFIG = {
                 // 配套的 .stylelintrc.js 由上面 file rule 从 template 搬过来。
                 'stylelint',
             ],
+            // SWC 钉模板 lockfile 里的精确版本：迁移删了用户 lockfile，^range 会解析到模板发布之后的
+            // 新版本（@swc/core 1.16.18 在沙箱里加载 native binding 失败，nest 起不来）。钉 lockfile
+            // 版本后与同版本模板新建的应用一致，模板升级 SWC 时自动跟随。
+            exactFromLock: ['@swc/cli', '@swc/core'],
         },
         // 10b. 托管构建脚本的配套依赖（@vercel/nft，build.sh → prune-smart.js）：缺失才补固定版本，
         //      已声明保持用户版本。迁移 / repair 的验证要跑完整 npm run build。
@@ -286,6 +318,9 @@ exports.MIGRATE_CONFIG = {
             to: 'vite.config.ts',
             template: 'vite.config.ts',
             requirePreset: '@lark-apaas/coding-preset-vite-react',
+            // 早期模板（0.1.8～0.1.10）的 preset 包名：配置里只有 defineConfig({ resolve.alias })，换包等价；
+            // 新包在 followLatestPackages 里，安装时补上
+            legacyPresets: ['@lark-apaas/coding-vite-preset'],
         },
         // ===== 12. 切 stack =====
         { type: 'set-stack', stack: 'nestjs-react-fullstack' },
@@ -295,7 +330,7 @@ exports.MIGRATE_CONFIG = {
     //     这些 API 当前只在 alpha 版本里。template caret range 不匹配 pre-release，必须显式 latest。
     //   - coding-preset-vite-react：本次切到 MIAODA_APP_TYPE='3' env 检测，老版本 preset 不认 env。
     followLatestPackages: ['@lark-apaas/client-toolkit', '@lark-apaas/coding-preset-vite-react'],
-    // 成功必须包含完整构建：首次 FaaS 发布需要可启动 server、页面资源与 run.sh
-    verify: [['run', 'build']],
+    // 不配置 verify（不做完整构建）：发布时 DevOps 构建机会完整构建一次，转换问题在预览 / 发布时暴露；
+    // 沙箱里跑模板 build.sh 还会经裸名 `npx fullstack-cli` 解析到公网同名第三方包。
 };
 exports.default = exports.MIGRATE_CONFIG;

package/dist/services/app/migrate/restart.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * 沙箱内重启被转换工程的 dev 进程：向 `node …scripts/dev.js` 主进程发 SIGTERM，由平台
+ * supervisor 重新 exec dev.sh → dev.js 加载新脚本与依赖。这只是重启信号，新进程是否健康由
+ * 调用方核验。
+ *
+ * 只认工作目录等于被转换目录的进程：dev.js 启动即 chdir 到自己所在的工程根，cwd 唯一对应它
+ * 服务的工程。按命令行全局匹配会连带杀掉同一沙箱里其他目录的预览进程（例如在工程副本里执行
+ * migrate 时，真实应用的预览也被重启）。.spark/meta.json 的 app_id 区分不了副本与原工程，沙箱
+ * 也没有所有调用方都会设置的工作区路径环境变量，所以都不用来判定。
+ *
+ * 读 /proc 是 Linux-only：只在沙箱（恒为 Linux）调用；/proc 不可读时视为没有可重启的进程。
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signalDevRestart = signalDevRestart;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const DEV_PROCESS_RE = /node.*scripts\/dev\.js/;
+/** 返回已发出重启信号的进程号；没有命中返回空数组 */
+function signalDevRestart(projectDir, deps = {}) {
+    const procRoot = deps.procRoot ?? '/proc';
+    const kill = deps.kill ??
+        ((pid) => {
+            process.kill(pid, 'SIGTERM');
+        });
+    let project;
+    let entries;
+    try {
+        project = node_fs_1.default.realpathSync(projectDir);
+        entries = node_fs_1.default.readdirSync(procRoot);
+    }
+    catch {
+        return [];
+    }
+    const signaled = [];
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry) || Number(entry) === process.pid)
+            continue;
+        try {
+            const cmdline = node_fs_1.default
+                .readFileSync(node_path_1.default.join(procRoot, entry, 'cmdline'), 'utf-8')
+                .replaceAll('\0', ' ');
+            if (!DEV_PROCESS_RE.test(cmdline))
+                continue;
+            // 内核给出的 cwd 已是解析过符号链接的绝对路径
+            if (node_fs_1.default.readlinkSync(node_path_1.default.join(procRoot, entry, 'cwd')) !== project)
+                continue;
+            kill(Number(entry));
+            signaled.push(Number(entry));
+        }
+        catch {
+            // 进程已退出或无权读取：不是本工程可重启的进程
+        }
+    }
+    return signaled;
+}