@lark-apaas/miaoda-cli 0.1.46 → 0.1.47

package/README.md

@@ -52,6 +52,25 @@ miaoda file ls --output json
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 工程初始化、同步与转换
+
+`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`、`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 脚本的安全沙箱，不限制脚本主动访问其他绝对路径。
+
+临时模板目录清理失败只加入 `warnings`（`path`、系统错误 `code`、`message`），不影响 `status`。
+
+全栈 / design-stack 的 `postinstall` 只升级完整历史平台值（`fullstack-cli action-plugin init` 或 `npx -y @lark-apaas/fullstack-cli action-plugin init`），目标为 `npx -y @lark-apaas/fullstack-cli@latest action-plugin init`；`latest` 是渠道，不是固定版本。带追加命令、参数或用户指定版本的值保留。`migrate` 在原目录执行正常 npm 安装生命周期，包括用户脚本及依赖补丁；生命周期失败即 `install` 阶段失败，保留现场。
+
 ## 全栈应用的 MCP UI 检查
 
 创建 MCP UI 时，Agent 在 `server/mcp/ui` 中同时生成 `tsconfig.json` 和 `eslint.config.cjs`，修改 UI 或其 shared 依赖后主动运行独立检查。模板和 CLI 不生成 UI 配置，也不将 UI 检查接入主工程 lint/type:check。
@@ -122,6 +141,7 @@ miaoda registry add deck-slide --overwrite         # 目标已存在时覆盖（
 ## 环境变量
 
 - `MIAODA_APP_ID`：默认应用 ID，等价于 `--app-id`。
+- `MIAODA_MIGRATE_STEP_TIMEOUT_MS`：`app migrate` 单个依赖安装 / 构建步骤的超时（毫秒），默认 20 分钟。
 - `MIAODA_CANARY_HEADER`：HTTP 请求的 `x-tt-env` 小流量头取值。未设置时默认 `boe_miaoda_ccm`；设为空字符串则不带该头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。值形如 `ppe_xxx` 时额外带上 `x-use-ppe: 1`。
 
 ## 输出契约

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

@@ -40,24 +40,74 @@ function registerAppMigrate(parent) {
     // 用 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）')
+        .description('工程转换原语：原目录内按 MigrateConfig 预检冲突 → 定向转换 → 安装；冲突按调用目的即停或按模板覆盖，失败保留现场')
         .requiredOption('--to <stack>', '目标 stack 短名')
-        .option('--from <stack>', '源 stack；默认读 .spark/meta.json 当前 stack')
-        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .option('--from <stack>', '源 stack；默认按磁盘实际布局识别（识别不了再读 .spark/meta.json）')
+        .option('--dir <path>', '项目目录，默认 cwd')
+        .option('--purpose <purpose>', '调用目的：manual / upgrade / history_restore；决定冲突策略（见下文），同时用于记录与关联', 'manual')
+        .option('--operation-ref <id>', '调用方已有的操作 / 任务关联标识，原样回显')
+        .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
 已支持的迁移路径
   ${supportedDesc || '(none)'}
+  磁盘已是目标布局（同目标）时走 repair：补齐适配 / 安装 / 构建，不返回 NOOP。
+
+文件规则
+  明确托管的平台脚本（scripts 清单 + .githooks/pre-commit）按模板更新，scripts/ 下用户文件保留；
+  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）；
+                    沙箱里只向工作目录为本工程的 dev 进程发重启信号，
+                    restartSignalSent / devRestarted 只表示发出了重启信号
+  status=conflict   conflicts 给出具体路径 / ID，冲突文件不覆盖
+  status=failed     failure.stage / failure.code 给出失败阶段与原因，现场保留、不自动回滚
+  originalIntact=true 仅表示失败发生在任何工程写入之前；写入后为 false（部分改动见 changes）。
+  失败后对同一工程重跑同目标 migrate 即按真实布局 repair（可接续安装 / 构建）。
+  非 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": {"from": "...", "to": "...",
-            "appliedRules": [{"type": "...", "action": "...", "path": "...", "detail": "..."}],
-            "moved": [...], "deleted": [...], "synced": [...], "merged": [...], "patched": [...],
-            "skipped": N,
-            "nextActions": [...]}}
+  {"data": {"status": "converted|conflict|failed", "mode": "migrate|repair", "runId": "...",
+            "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,
+            "restartSignalSent": false, "readiness": {"status": "...", "detail": "..."},
+            "appliedRules": [...], "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 --purpose upgrade --operation-ref op_demo_xxx
   $ miaoda app migrate --to nestjs-react-fullstack --dir /path/to/app
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
@@ -65,6 +115,9 @@ JSON 输出
             dir: rawOpts.dir,
             from: rawOpts.from,
             to: rawOpts.to,
+            appId: rawOpts.appId,
+            purpose: rawOpts.purpose,
+            operationRef: rawOpts.operationRef,
         });
     }));
     parent.addCommand(cmd, { hidden: true });
@@ -75,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）。
@@ -85,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 → 删除
@@ -97,12 +151,18 @@ 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（已应用的文件规则保留，
+     重跑 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），
+  同名更新；scripts/ 下其他用户文件保留。内容未变化的规则报 noop，连续 sync 不产生漂移。
 
   stack 未纳入 sync 范围（无 SyncConfig 且无 upgrade/templates/<stack>/，如 design-html
   buildless 静态 HTML）→ 跳过同步（no-op, skipped=true），退出码 0，不阻断 dev/启动链路。
 
 JSON 输出
-  {"data": {"stack": "...",
+  {"data": {"stack": "...", "status": "succeeded|failed", "failedStage": "install",
             "appliedRules": [{"type": "...", "action": "...", "path": "...", "detail": "..."}],
             "syncedFiles": [...],
             "mergedJsonFiles": [{"path": "...", "keys": [...]}],
@@ -113,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,
         });
     }));
 }
@@ -308,14 +370,22 @@ 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；新初始化时同步安装失败也以退出码 1 结束', false)
         .addOption((0, shared_1.appIdOption)())
         .addHelpText('after', `
 幂等
-  .spark/meta.json 已存在时直接退出（initialized=false, reason=already_initialized），
-  不再触发 template 渲染、不重新跑 upgrade/templates 同步、不重新拉 skills、不安装依赖。
-  meta.json 在 init 流程最后才写，写了 = 已完整成功一次；
+  .spark/meta.json 已存在时不再渲染 / 安装（initialized=false, reason=already_initialized），
+  不覆盖已有业务代码；同时输出 ready 与 problems（工程就绪核验结果）。
+  meta 存在不等于就绪：--strict 时 problems 非空（meta 损坏、stack 与请求不符、必要文件缺失、
+  依赖未安装、上次 init/sync/migrate 失败）退出码 1，供平台严格调用判断。
   上一次失败留下半渲染状态时（package.json 在但 meta.json 没在）允许重跑。
 
+依赖安装失败
+  同步安装失败时 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 字段；
   未提供则不写。运行端命令（deploy / file / plugin 等）仍优先读 MIAODA_APP_ID env，
@@ -358,7 +428,8 @@ function registerAppInit(parent) {
   与 --skip-install 互斥。
 
 JSON 输出
-  已初始化：{"data": {"initialized": false, "reason": "already_initialized", "targetDir": "..."}}
+  已初始化：{"data": {"initialized": false, "reason": "already_initialized", "targetDir": "...",
+                     "ready": true|false, "problems": [{"code": "...", "message": "..."}]}}
   新初始化：{"data": {"initialized": true, "template": "...", "templateVersion": "...", "steeringVersion": "...",
                      "appId": "...", "appType": "modern_html", "sourceImported": true, "importedFileCount": 7,
                      "platformStackFound": true, "platformSyncedFiles": [...],
@@ -387,6 +458,7 @@ JSON 输出
             skipInstall: rawOpts.skipInstall,
             appId: rawOpts.appId,
             asyncInstall: rawOpts.asyncInstall,
+            strict: rawOpts.strict,
         });
     }));
 }

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

@@ -15,6 +15,7 @@ const logs_dir_1 = require("../../../utils/logs-dir");
 const env_1 = require("../../../utils/env");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
+const engineering_state_1 = require("../../../utils/engineering-state");
 /**
  * miaoda app init
  *
@@ -32,24 +33,56 @@ const output_1 = require("../../../utils/output");
  * 的版本（没经 sync 覆盖）；首次 install 装的也是 template 钉的版本（没升 latest），
  * package.json 跟 template 完全一致。dev.sh 入口的 sync 会修正这些 drift。
  *
- * 幂等：.spark/meta.json 存在即表示已完整成功一次，直接退出，不重跑任何子步骤。
+ * 幂等：.spark/meta.json 存在时不重跑渲染 / 安装（不覆盖业务代码），但会做只读就绪核验并输出
+ * ready / problems —— meta 存在不等于就绪；--strict 时未就绪退出码 1。
  * 半渲染状态（package.json 在但 meta.json 不在）会重新跑完整流程。
+ *
+ * 同步安装失败：meta 仍写出（脚手架已渲染，避免重跑覆盖已开始编辑的文件），本地执行记录标为
+ * 失败，输出 status=failed / failedStage=install。只有 --strict（平台严格调用）以退出码 1 结束；
+ * 不带 --strict 时退出码 0 —— lark-cli `+init` 等调用方按退出码判成败，且依赖由后续
+ * `miaoda app sync`（dev.sh 入口）补装，安装抖动不能让整条初始化失败。
  */
 async function handleAppInit(opts) {
     await Promise.resolve();
     const targetDir = opts.targetDir ?? process.cwd();
     const metaPath = node_path_1.default.join(targetDir, '.spark', 'meta.json');
     if (node_fs_1.default.existsSync(metaPath)) {
+        let expectedStack;
+        if (opts.template || opts.appType) {
+            try {
+                expectedStack = (0, index_1.resolveStack)({ template: opts.template, appType: opts.appType });
+            }
+            catch (err) {
+                // 非严格调用保持历史行为：已初始化时不因参数校验失败而报错
+                if (opts.strict)
+                    throw err;
+            }
+        }
+        const check = (0, index_1.checkWorkspaceReady)({ targetDir, expectedStack });
         if (!(0, output_1.isJsonMode)()) {
             process.stdout.write(`Already initialized: ${metaPath}\n`);
+            for (const p of check.problems) {
+                process.stdout.write(`  ✗ ${p.code}: ${p.message}\n`);
+            }
         }
         (0, output_1.emit)({
             data: {
                 initialized: false,
                 reason: 'already_initialized',
                 targetDir,
+                stack: check.stack,
+                ready: check.ready,
+                problems: check.problems,
             },
         });
+        if (opts.strict && !check.ready) {
+            (0, output_1.emitError)(new error_1.AppError('WORKSPACE_NOT_READY', check.problems.map((p) => `${p.code}: ${p.message}`).join('; '), {
+                next_actions: [
+                    '按 problems 修复：依赖 / 文件问题执行 miaoda app sync，布局不符执行 miaoda app migrate',
+                ],
+            }));
+            process.exitCode = 1;
+        }
         return;
     }
     const stack = (0, index_1.resolveStack)({ template: opts.template, appType: opts.appType });
@@ -130,21 +163,29 @@ async function handleAppInit(opts) {
         app_id: opts.appId,
     });
     // async 模式：meta 已落盘（= 脚手架就绪），再派发后台安装并立即返回（不等装完）。
+    // 执行记录先标 running，后台 worker 结束时改写为 succeeded / failed；中断则停留在 running。
     let asyncDispatch;
     if (opts.asyncInstall) {
+        recordInitState(targetDir, 'running', 'install');
         asyncDispatch = (0, index_1.dispatchAsyncInstall)({ targetDir });
     }
+    const installFailed = installResult?.source === 'failed';
+    if (installResult !== undefined) {
+        recordInitState(targetDir, installFailed ? 'failed' : 'succeeded', installResult.source === 'skipped' ? 'install-skipped' : 'install', installResult.error);
+    }
     if (!(0, output_1.isJsonMode)()) {
         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`);
+            process.stdout.write(`${installFailed ? '✗' : '✓'} Initialized ${stack} (template ${tplResult.version}, steering ${steeringResult.version}, install ${installResult.source}) in ${targetDir}\n`);
         }
     }
     (0, output_1.emit)({
         data: {
             initialized: true,
+            status: installFailed ? 'failed' : 'succeeded',
+            failedStage: installFailed ? 'install' : undefined,
             template: stack,
             templatePackage: tplResult.packageName,
             templateVersion: tplResult.version,
@@ -177,8 +218,39 @@ async function handleAppInit(opts) {
                     cacheZip: installResult?.cacheZip,
                     installError: installResult?.error,
                 }),
+            nextActions: installFailed
+                ? [
+                    '检查 npm 输出定位安装错误（网络 / registry / 依赖冲突），修复后执行 miaoda app sync 补装依赖',
+                ]
+                : undefined,
         },
     });
+    if (installFailed) {
+        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) {
+    try {
+        (0, engineering_state_1.writeEngineeringState)(targetDir, {
+            operation: 'init',
+            status,
+            stage,
+            code: status === 'failed' ? 'INIT_INSTALL_FAILED' : undefined,
+            message: error?.slice(0, 500),
+        });
+    }
+    catch (err) {
+        (0, logger_1.log)('init', `⚠ failed to record engineering state: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /**
  * 处理 --source-path 导入：当前仅 app_type=modern_html 生效。