@lark-apaas/miaoda-cli 0.1.39-alpha.24bc5ff → 0.1.39-alpha.2937ea8

package/README.md

@@ -48,10 +48,30 @@ miaoda file ls --output json
 | `miaoda observability ...` | 线上日志、链路、前端源码堆栈反查、监控指标、运营指标 |
 | `miaoda comment ...`       | 应用评论：查看评论列表、解决评论（仅 design-html 场景开放）        |
 | `miaoda registry ...`      | 组件 registry：列出 / copy-in SDK 文件（本地执行）                 |
-| `miaoda app ...`           | 应用生命周期：元数据、初始化、平台同步、源码导出、静态产物导出     |
+| `miaoda app ...`           | 应用生命周期：元数据、初始化、外部项目导入、平台同步、源码导出、静态产物导出 |
 
 完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
 
+## 工程初始化、同步与转换
+
+`miaoda app init / import / 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` 补装）。
+- `import`：外部项目导入（平台在 `init` 渲染模板之后、首次 git 提交之前于工程根目录调用）。`--zip <path>` 或 `--zip-url <预签名 URL>` 二选一，`--platform lovable|replit|gemini|zip`（默认 `zip`）。按平台规则把用户代码叠加到 `client/src`、`client/public`、`shared`，其余原样落到 `source_package/`；从不新建 / 覆盖模板托管文件（根 `package.json`、`package-lock.json`、`.npmrc`、`tsconfig*.json`、`vite.config.*`、`eslint.config.*`、`AGENTS.md`、`.githooks/`、`scripts/`、`.spark/`、`node_modules/`、`server/main.ts`、`client/src/index.tsx`），命中时改放 `source_package/` 并记入 `protectedConflicts`。**不合并 package.json、不装依赖**：用户 `package.json` 保留为 `source_package/package.json`，依赖静态分类（`platform_managed` / `present` / `build_chain` / `missing`）写进 `.spark/import/manifest.json`，由 Coding Agent 后续按需安装。先算完整计划、整体暂存再移入，失败时工程原样（`WRITE_FAILED`）；同时写待迁移标记 `.spark/import/MIGRATION_PENDING`（沙箱 skill `import-migration` 以它为加载条件，Coding Agent 迁移完成后删除）；manifest 最后写，存在即视为已导入（`alreadyImported=true`，不再改动）。`--dry-run` 只输出计划；`--rules-json` 覆盖默认排除路径。错误码：`ARGS_INVALID`（退出码 2）、`NOT_INITIALIZED`、`DOWNLOAD_FAILED`、`INVALID_ZIP`（非 zip / 超 50MB / 解压失败）、`WRITE_FAILED`。
+- `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 +142,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/api/deploy/api.js

@@ -50,9 +50,11 @@ async function getErrorLog(req) {
  * GET /v1/pipeline/app/:appID/instance/:instanceID/detail — 轮询发布状态
  *
  * 走 lark.apaas.devops_platform PSM；URL 前缀不同但共用同一管理端 gateway。
+ * 显式带 withTransformApprovalData=true 取审批展示视图（job 上挂 approval）；IDL 默认 false，
+ * 不带时拿不到审批链接与拒绝原因。该参数只改返回投影，无副作用。
  */
 async function queryPipelineInstance(req) {
-    const url = `/v1/pipeline/app/${encodeURIComponent(req.appID)}/instance/${encodeURIComponent(req.instanceID)}/detail`;
+    const url = `/v1/pipeline/app/${encodeURIComponent(req.appID)}/instance/${encodeURIComponent(req.instanceID)}/detail?withTransformApprovalData=true`;
     return (0, http_1.getInnerApi)(url, {
         errPrefix: 'Failed to query pipeline',
         defaultErrCode: DEFAULT_ERR_CODE,

package/dist/api/deploy/approval.js

@@ -49,7 +49,7 @@ function* jobsOf(stages) {
     }
 }
 /**
- * 从 CliQueryPipelineInstance 的 PipelineInstance（接口默认返回审批展示视图）中摘出需要输出的卡点：
+ * 从 CliQueryPipelineInstance 的 PipelineInstance（请求带 withTransformApprovalData=true，返回审批展示视图）中摘出需要输出的卡点：
  * 第一个 status 为 PENDING / REJECTED / FAILED 的 Job.approval。一次发布可以被拦多次
  * （build / db_check / deploy），已通过的卡点可能排在前面，不能取它；流水线串行，需要输出的至多一个。
  * 与妙搭发布面板 findApprovalJob 同一口径。

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

@@ -25,6 +25,7 @@ function registerAppCommands(program, opts = {}) {
     registerAppPack(appCmd);
     if (opts.includeInit) {
         registerAppInit(appCmd);
+        registerAppImport(appCmd);
         registerAppSync(appCmd);
         registerAppMigrate(appCmd);
     }
@@ -40,24 +41,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 +116,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 +129,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 +140,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 +152,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 +174,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 +371,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 +429,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 +459,82 @@ JSON 输出
             skipInstall: rawOpts.skipInstall,
             appId: rawOpts.appId,
             asyncInstall: rawOpts.asyncInstall,
+            strict: rawOpts.strict,
+        });
+    }));
+}
+function registerAppImport(parent) {
+    const cmd = parent
+        .command('import')
+        .description('外部项目导入：把 zip 包（lovable / replit / gemini / 普通 zip）按平台规则叠加进已初始化的工程；不碰模板托管文件、不合并 package.json、不装依赖')
+        .option('--zip <path>', '本地 zip 路径（与 --zip-url 二选一）')
+        .option('--zip-url <url>', 'zip 下载地址（预签名 GET URL，与 --zip 二选一）')
+        .option('--platform <platform>', `来源平台（${index_1.IMPORT_PLATFORMS.join(' / ')}）`, index_1.DEFAULT_IMPORT_PLATFORM)
+        .option('--rules-json <json>', '覆盖默认排除路径：{"excludedPaths": [...]}，提供后整体替换该平台默认值')
+        .option('--dry-run', '只计算并输出放置计划，不写任何文件', false)
+        .option('--dir <path>', '项目目录，默认 cwd（需含 .spark/meta.json）')
+        .addHelpText('after', `
+前置条件
+  工程已经 'miaoda app init' 过（.spark/meta.json 存在），否则报 NOT_INITIALIZED。
+  平台在模板渲染完成、首次 git 提交之前于工程根目录调用；依赖由 init 的后台安装负责，
+  本命令不读写 package.json / package-lock.json / node_modules。
+
+幂等
+  .spark/import/manifest.json 已存在 → 不做任何改动，输出 alreadyImported=true。
+  manifest 最后写入，是导入完成的唯一标记。
+
+导入包处理
+  大小上限 50MB（超出 / 非 zip / 解压失败 → INVALID_ZIP；下载失败 → DOWNLOAD_FAILED）。
+  丢弃 __MACOSX/、.DS_Store、含 ".." 的条目、.git 元数据（.gitignore / .github 保留）、
+  node_modules / dist / build 目录、符号链接。
+  所有条目共享一个不含 "." 的顶层目录时剥掉该目录（gemini 保留原始路径）。
+  超过 60 字节的路径段改名为 truncated-<hash><ext>。
+
+放置规则（未命中的一律放 source_package/<原路径>）
+  lovable  src/** → client/src/**（命中排除路径 → source_package/src/**）；public/** → client/public/**
+  replit   client/src/** → client/src/**（命中排除路径 → source_package/）；shared/** → shared/**；
+           attached_assets/** → client/public/assets/**
+  gemini   components/** → client/src/components/**；services/** → client/src/services/**；
+           types.ts / constants.ts → client/src/
+  zip      src/** → client/src/**（命中排除路径 → source_package/src/**）；public/** → client/public/**；
+           src/components/ui/<name>.<ext> 与工程已有 client/src/components/ui/<name>.* 同名时，
+           删除模板文件、写入用户文件
+  受保护目标（根 package.json / package-lock.json / .npmrc / tsconfig*.json / vite.config.* /
+  eslint.config.* / AGENTS.md / .githooks/ / scripts/ / .spark/ / node_modules/ / server/main.ts /
+  client/src/index.tsx）从不新建或覆盖，命中时改放 source_package/ 并记入 protectedConflicts。
+  用户的 package.json 保留在 source_package/package.json。
+
+原子性
+  先算完整计划、整体暂存，再移入工程；移入前任何失败工程保持原样（WRITE_FAILED）。
+
+依赖清单（.spark/import/manifest.json 的 dependencies，只做静态分析，不安装、不联网）
+  status 优先级：platform_managed（@lark-apaas/*）> excluded（排除依赖）>
+  present（工程已有，附 templateRange）> build_chain（构建链 / 工具链）> missing
+
+JSON 输出
+  {"data": {"imported": true, "alreadyImported": false, "platform": "zip",
+            "fileCounts": {"client/src": 0, "client/public": 0, "shared": 0, "source_package": 0},
+            "manifestPath": ".spark/import/manifest.json", "warnings": [...]}}
+  --dry-run 额外带 "dryRun": true 与 "plan": {placements, deletions, overwrites, excludedPaths,
+            protectedConflicts, replacedTemplateFiles, dependencies}
+
+错误码
+  ARGS_INVALID（退出码 2）/ NOT_INITIALIZED / DOWNLOAD_FAILED / INVALID_ZIP / WRITE_FAILED（退出码 1）
+
+示例
+  $ miaoda app import --zip-url 'https://tos.example.com/demo.zip?sign=...' --platform lovable --json
+  $ miaoda app import --zip ./demo.zip
+  $ miaoda app import --zip ./demo.zip --platform replit --dry-run
+  $ miaoda app import --zip ./demo.zip --rules-json '{"excludedPaths": ["src/legacy/"]}'
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        await (0, index_1.handleAppImport)({
+            zip: rawOpts.zip,
+            zipUrl: rawOpts.zipUrl,
+            platform: rawOpts.platform,
+            rulesJson: rawOpts.rulesJson,
+            dryRun: rawOpts.dryRun,
+            dir: rawOpts.dir,
         });
     }));
 }

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

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAppImport = handleAppImport;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const index_1 = require("../../../services/app/import/index");
+const error_1 = require("../../../utils/error");
+const logger_1 = require("../../../utils/logger");
+const output_1 = require("../../../utils/output");
+function readPackageJson(file, label, warnings) {
+    try {
+        return (0, index_1.readJsonFile)(file);
+    }
+    catch (err) {
+        warnings.push(`${label} 不是合法 JSON，依赖清单按空处理：${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+function readPrevFileCounts(manifestFile) {
+    try {
+        const prev = JSON.parse(node_fs_1.default.readFileSync(manifestFile, 'utf-8'));
+        return prev.fileCounts;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * miaoda app import --zip <path> | --zip-url <url> [--platform <p>] [--rules-json <json>] [--dry-run]
+ *
+ * 外部平台（lovable / replit / gemini / 普通 zip）项目导入：在已 `app init` 的工程里，
+ * 把用户代码按平台规则叠加到 client/ shared/，其余原样落到 source_package/。
+ * 不碰模板托管文件、不合并 package.json、不装依赖 —— 用户 package.json 保留在
+ * source_package/package.json，依赖分析写进 manifest 交给 Coding Agent 后续按需安装。
+ *
+ * 落盘两阶段（先暂存、再 rename），manifest 最后写，作为幂等标记。
+ */
+async function handleAppImport(opts) {
+    const hasZip = Boolean(opts.zip);
+    const hasUrl = Boolean(opts.zipUrl);
+    if (hasZip === hasUrl) {
+        throw new error_1.AppError('ARGS_INVALID', '--zip 与 --zip-url 必须且只能传一个');
+    }
+    const platform = (0, index_1.parsePlatform)(opts.platform);
+    const rules = (0, index_1.resolveImportRules)(platform, opts.rulesJson);
+    const projectDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
+    if (!node_fs_1.default.existsSync(node_path_1.default.join(projectDir, '.spark', 'meta.json'))) {
+        throw new error_1.AppError('NOT_INITIALIZED', `工程未初始化（缺少 .spark/meta.json）：${projectDir}`, {
+            next_actions: ['先执行 miaoda app init --template <stack> 再导入'],
+        });
+    }
+    const manifestFile = (0, index_1.importManifestPath)(projectDir);
+    if (node_fs_1.default.existsSync(manifestFile)) {
+        (0, logger_1.log)('import', `Already imported (${index_1.IMPORT_MANIFEST_REL} exists), skip`);
+        if (!(0, output_1.isJsonMode)())
+            process.stdout.write(`Already imported: ${manifestFile}\n`);
+        (0, output_1.emit)({
+            data: {
+                imported: false,
+                alreadyImported: true,
+                platform,
+                fileCounts: readPrevFileCounts(manifestFile),
+                manifestPath: index_1.IMPORT_MANIFEST_REL,
+                warnings: [],
+            },
+        });
+        return;
+    }
+    const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-import-'));
+    try {
+        const warnings = [];
+        let zipPath;
+        if (opts.zipUrl) {
+            zipPath = node_path_1.default.join(tmpDir, 'import.zip');
+            await (0, index_1.downloadZip)(opts.zipUrl, zipPath);
+        }
+        else {
+            zipPath = node_path_1.default.resolve(opts.zip ?? '');
+            (0, index_1.assertLocalZip)(zipPath);
+        }
+        const extractDir = node_path_1.default.join(tmpDir, 'extracted');
+        warnings.push(...(0, index_1.extractImportZip)(zipPath, extractDir).warnings);
+        const { entries, renamed } = (0, index_1.normalizeEntries)((0, index_1.collectFiles)(extractDir), platform);
+        if (entries.length === 0) {
+            throw new error_1.AppError('INVALID_ZIP', '导入包内没有可导入的文件');
+        }
+        for (const r of renamed)
+            warnings.push(`路径段过长已重命名：${r.from} → ${r.to}`);
+        const plan = (0, index_1.buildImportPlan)({ entries, platform, rules, projectDir });
+        warnings.push(...plan.warnings);
+        for (const c of plan.protectedConflicts) {
+            warnings.push(`目标为模板受保护路径，已改放 ${c.placedAt}：${c.target}`);
+        }
+        if (plan.overwrites.length > 0) {
+            warnings.push(`覆盖了工程中已有的 ${String(plan.overwrites.length)} 个文件`);
+        }
+        const dependencies = analyzeDependencies({
+            entries,
+            extractDir,
+            projectDir,
+            warnings,
+        });
+        if (opts.dryRun) {
+            if (!(0, output_1.isJsonMode)()) {
+                process.stdout.write(`Dry run: ${String(plan.placements.length)} file(s) planned\n`);
+            }
+            (0, output_1.emit)({
+                data: {
+                    imported: false,
+                    alreadyImported: false,
+                    dryRun: true,
+                    platform,
+                    fileCounts: plan.fileCounts,
+                    manifestPath: index_1.IMPORT_MANIFEST_REL,
+                    warnings,
+                    plan: {
+                        placements: plan.placements.map((p) => ({ source: p.source, target: p.target })),
+                        deletions: plan.deletions,
+                        overwrites: plan.overwrites,
+                        excludedPaths: plan.excludedPaths,
+                        protectedConflicts: plan.protectedConflicts,
+                        replacedTemplateFiles: plan.replacedTemplateFiles,
+                        dependencies,
+                    },
+                },
+            });
+            return;
+        }
+        applyWithStaging({ plan, extractDir, projectDir });
+        const manifest = (0, index_1.buildImportManifest)({ platform, plan, dependencies });
+        try {
+            (0, index_1.writeImportPendingMarker)(projectDir);
+            (0, index_1.writeImportManifest)(projectDir, manifest);
+        }
+        catch (err) {
+            throw new error_1.AppError('WRITE_FAILED', `写 ${index_1.IMPORT_MANIFEST_REL} 失败：${err instanceof Error ? err.message : String(err)}`);
+        }
+        (0, logger_1.log)('import', `Imported ${String(plan.placements.length)} file(s) (${platform})`);
+        if (!(0, output_1.isJsonMode)()) {
+            process.stdout.write(`✓ Imported ${String(plan.placements.length)} file(s) from ${platform} package into ${projectDir}\n`);
+        }
+        (0, output_1.emit)({
+            data: {
+                imported: true,
+                alreadyImported: false,
+                platform,
+                fileCounts: plan.fileCounts,
+                manifestPath: index_1.IMPORT_MANIFEST_REL,
+                warnings,
+            },
+        });
+    }
+    finally {
+        node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+function analyzeDependencies(opts) {
+    const pkgEntry = opts.entries.find((e) => e.normalized === 'package.json');
+    if (!pkgEntry)
+        return [];
+    const sourcePkg = readPackageJson(node_path_1.default.join(opts.extractDir, ...pkgEntry.raw.split('/')), '导入包 package.json', opts.warnings);
+    const projectPkg = readPackageJson(node_path_1.default.join(opts.projectDir, 'package.json'), '工程 package.json', opts.warnings);
+    return (0, index_1.classifyDependencies)({ sourcePkg, projectPkg });
+}
+/**
+ * 暂存目录放在工程 .spark/import/ 下：与工程同一文件系统，rename 不会 EXDEV。
+ * 若 .spark/import/ 是本次新建的且导入失败，连目录一起清掉，保证失败时工程原样。
+ */
+function applyWithStaging(opts) {
+    const importDir = node_path_1.default.join(opts.projectDir, '.spark', 'import');
+    const createdImportDir = !node_fs_1.default.existsSync(importDir);
+    const stagingDir = node_path_1.default.join(importDir, `.staging-${String(process.pid)}-${String(Date.now())}`);
+    try {
+        node_fs_1.default.mkdirSync(stagingDir, { recursive: true });
+    }
+    catch (err) {
+        throw new error_1.AppError('WRITE_FAILED', `创建暂存目录失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        (0, index_1.applyImportPlan)({ ...opts, stagingDir });
+    }
+    catch (err) {
+        if (createdImportDir)
+            node_fs_1.default.rmSync(importDir, { recursive: true, force: true });
+        throw err;
+    }
+}

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PACK_MODES = exports.DEFAULT_PACK_MODE = exports.DEFAULT_PACK_OUT = exports.handleAppPack = exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = exports.handleAppExport = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
+exports.DEFAULT_IMPORT_PLATFORM = exports.IMPORT_PLATFORMS = exports.handleAppImport = exports.PACK_MODES = exports.DEFAULT_PACK_MODE = exports.DEFAULT_PACK_OUT = exports.handleAppPack = exports.SUPPORTED_STACKS = exports.handleAppMigrate = exports.UPGRADE_MANIFEST_FILENAME = exports.DEFAULT_EXPORT_OUT = exports.handleAppExport = exports.handleAppUpgrade = exports.handleAppSync = exports.handleAppInit = exports.handleAppUpdate = exports.handleAppGet = void 0;
 var get_1 = require("./get");
 Object.defineProperty(exports, "handleAppGet", { enumerable: true, get: function () { return get_1.handleAppGet; } });
 var update_1 = require("./update");
@@ -24,3 +24,9 @@ Object.defineProperty(exports, "handleAppPack", { enumerable: true, get: functio
 Object.defineProperty(exports, "DEFAULT_PACK_OUT", { enumerable: true, get: function () { return pack_1.DEFAULT_PACK_OUT; } });
 Object.defineProperty(exports, "DEFAULT_PACK_MODE", { enumerable: true, get: function () { return pack_1.DEFAULT_PACK_MODE; } });
 Object.defineProperty(exports, "PACK_MODES", { enumerable: true, get: function () { return pack_1.PACK_MODES; } });
+var import_1 = require("./import");
+Object.defineProperty(exports, "handleAppImport", { enumerable: true, get: function () { return import_1.handleAppImport; } });
+// commands 层渲染 help 用的枚举，同 SUPPORTED_STACKS 走 handler barrel 转发
+var index_2 = require("../../../services/app/import/index");
+Object.defineProperty(exports, "IMPORT_PLATFORMS", { enumerable: true, get: function () { return index_2.IMPORT_PLATFORMS; } });
+Object.defineProperty(exports, "DEFAULT_IMPORT_PLATFORM", { enumerable: true, get: function () { return index_2.DEFAULT_IMPORT_PLATFORM; } });