@lark-apaas/miaoda-cli 0.1.48 → 0.1.49

package/README.md

@@ -48,15 +48,16 @@ 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 / sync / migrate` 管理本地应用工程（平台调用方与本地开发共用）：
+`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`（不在 help 列表中展示，仅供平台调用）：外部项目导入（平台在 `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` 与具体路径，工程不写入；执行中才出现的冲突即停、不覆盖用户不同内容。

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);
     }
@@ -462,6 +463,88 @@ JSON 输出
         });
     }));
 }
+function registerAppImport(parent) {
+    // 与 migrate 同理：import 只由平台（sandbox_console 建应用时）调用，**不暴露给 Agent**。
+    // hidden 后 `miaoda app -h` 不列出，避免 Agent 在已有应用里自行导入 zip 覆盖业务代码；
+    // 显式调用 `miaoda app import ...` 行为不变。
+    const cmd = new commander_1.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>.* 同名时，
+           删除模板文件、写入用户文件（记入 replacedTemplateFiles）；
+           例外：用户文件是 .js / .jsx 而模板有 .ts / .tsx 时保留模板版本，
+           用户文件改放 source_package/ 并记入 protectedConflicts
+  受保护目标（根 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/*）> 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,
+        });
+    }));
+    parent.addCommand(cmd, { hidden: true });
+}
 function parseInitConf(raw) {
     // --conf 为可选值：未传（undefined）、裸 --conf（Commander 给 true）、空/纯空白字符串
     // 一律视为不配置，回退默认（latest）。

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; } });

package/dist/services/app/import/download.js

@@ -0,0 +1,141 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_IMPORT_ZIP_BYTES = void 0;
+exports.downloadZip = downloadZip;
+exports.assertLocalZip = assertLocalZip;
+exports.extractImportZip = extractImportZip;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const archive_1 = require("../../../utils/archive");
+const error_1 = require("../../../utils/error");
+const logger_1 = require("../../../utils/logger");
+const upload_1 = require("../../../services/app/pack/upload");
+/** 导入包大小上限（对齐服务端导入上传口径）。 */
+exports.MAX_IMPORT_ZIP_BYTES = 50 * 1024 * 1024;
+/** 下载超时：50MB 包在沙箱内网拉 TOS 远用不满，给足余量。 */
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+function tooLarge(size) {
+    return new error_1.AppError('INVALID_ZIP', `导入包超过大小上限（${String(size)} > ${String(exports.MAX_IMPORT_ZIP_BYTES)} bytes）`);
+}
+/**
+ * 把预签名 URL 指向的 zip 下载到 destFile。
+ *
+ * 预签名 URL 等同凭证：错误信息与日志一律脱敏（只在 --verbose 的 debug 里给完整地址）。
+ * 超过 50MB 判 INVALID_ZIP（先看 content-length，再在读流时累计兜底）；
+ * 网络失败 / 非 2xx 判 DOWNLOAD_FAILED。
+ */
+async function downloadZip(url, destFile) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new error_1.AppError('ARGS_INVALID', `--zip-url 不是合法 URL：${(0, upload_1.redactUrl)(url)}`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new error_1.AppError('ARGS_INVALID', `--zip-url 只支持 http/https，收到 ${parsed.protocol}`);
+    }
+    (0, logger_1.log)('import', 'Downloading import package...');
+    (0, logger_1.debug)(`import: GET ${url}`);
+    let resp;
+    try {
+        resp = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+    }
+    catch (err) {
+        throw new error_1.AppError('DOWNLOAD_FAILED', `下载导入包失败（${(0, upload_1.redactUrl)(url)}）：${err instanceof Error ? err.message : String(err)}`, { retryable: true });
+    }
+    if (!resp.ok) {
+        throw new error_1.AppError('DOWNLOAD_FAILED', `下载导入包失败（${(0, upload_1.redactUrl)(url)}）：HTTP ${String(resp.status)}`, {
+            retryable: resp.status >= 500 || resp.status === 429,
+            next_actions: ['预签名 URL 可能已过期，重新生成后重试'],
+        });
+    }
+    const declared = Number(resp.headers.get('content-length') ?? '');
+    if (Number.isFinite(declared) && declared > exports.MAX_IMPORT_ZIP_BYTES) {
+        throw tooLarge(declared);
+    }
+    const chunks = [];
+    let total = 0;
+    try {
+        if (resp.body) {
+            const reader = resp.body.getReader();
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                total += value.byteLength;
+                if (total > exports.MAX_IMPORT_ZIP_BYTES) {
+                    await reader.cancel();
+                    throw tooLarge(total);
+                }
+                chunks.push(Buffer.from(value));
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof error_1.AppError)
+            throw err;
+        throw new error_1.AppError('DOWNLOAD_FAILED', `下载导入包失败（${(0, upload_1.redactUrl)(url)}）：${err instanceof Error ? err.message : String(err)}`, { retryable: true });
+    }
+    node_fs_1.default.writeFileSync(destFile, Buffer.concat(chunks, total));
+    return total;
+}
+/** 校验本地 zip：存在、大小不超限。 */
+function assertLocalZip(zipPath) {
+    let stat;
+    try {
+        stat = node_fs_1.default.statSync(zipPath);
+    }
+    catch {
+        throw new error_1.AppError('ARGS_INVALID', `--zip 文件不存在：${zipPath}`);
+    }
+    if (!stat.isFile()) {
+        throw new error_1.AppError('ARGS_INVALID', `--zip 不是文件：${zipPath}`);
+    }
+    if (stat.size > exports.MAX_IMPORT_ZIP_BYTES)
+        throw tooLarge(stat.size);
+}
+function isZipMagic(head) {
+    // PK\x03\x04（常规）/ PK\x05\x06（空归档）
+    return (head.length >= 4 &&
+        head[0] === 0x50 &&
+        head[1] === 0x4b &&
+        ((head[2] === 0x03 && head[3] === 0x04) || (head[2] === 0x05 && head[3] === 0x06)));
+}
+/**
+ * 解压导入包到 destDir（工程外的临时目录）。非 zip / 解压失败 → INVALID_ZIP。
+ *
+ * unzip 对含 "../" 段等可疑条目会剥掉危险段继续解、并以退出码 1（warning）结束；
+ * 这种情况视为成功并记 warning —— 解出的文件仍落在 destDir 内，随后按规则过滤。
+ */
+function extractImportZip(zipPath, destDir) {
+    const fd = node_fs_1.default.openSync(zipPath, 'r');
+    const head = Buffer.alloc(4);
+    try {
+        node_fs_1.default.readSync(fd, head, 0, 4, 0);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+    if (!isZipMagic(head)) {
+        throw new error_1.AppError('INVALID_ZIP', `导入包不是合法 zip：${node_path_1.default.basename(zipPath)}`);
+    }
+    node_fs_1.default.mkdirSync(destDir, { recursive: true });
+    try {
+        (0, archive_1.extractZip)(zipPath, destDir);
+        return { warnings: [] };
+    }
+    catch (err) {
+        if (err instanceof error_1.AppError) {
+            throw new error_1.AppError('INVALID_ZIP', `解压导入包失败：${err.message}`);
+        }
+        const status = err.status;
+        if (status === 1 && node_fs_1.default.readdirSync(destDir).length > 0) {
+            return { warnings: ['解压时 unzip 报告了 warning（可疑条目已被剥离 / 跳过）'] };
+        }
+        throw new error_1.AppError('INVALID_ZIP', `解压导入包失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+}

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readJsonFile = exports.importManifestPath = exports.writeImportManifest = exports.buildImportManifest = exports.classifyDependencies = exports.IMPORT_MANIFEST_VERSION = exports.writeImportPendingMarker = exports.IMPORT_PENDING_MARKER_REL = exports.IMPORT_MANIFEST_REL = exports.FILE_COUNT_KEYS = exports.mapSourcePath = exports.applyImportPlan = exports.buildImportPlan = exports.normalizeEntries = exports.collectFiles = exports.MAX_IMPORT_ZIP_BYTES = exports.extractImportZip = exports.assertLocalZip = exports.downloadZip = exports.isGitRepoDir = exports.getImportedPrefix = exports.sanitizePathSegments = exports.isProtectedTarget = exports.isBuildChainDependency = exports.resolveImportRules = exports.parsePlatform = exports.BUILD_CHAIN_PATTERNS = exports.DEFAULT_IMPORT_RULES = exports.PLATFORM_IMPORT_RULES = exports.SOURCE_PACKAGE_DIR = exports.DEFAULT_IMPORT_PLATFORM = exports.IMPORT_PLATFORMS = void 0;
+var rules_1 = require("./rules");
+Object.defineProperty(exports, "IMPORT_PLATFORMS", { enumerable: true, get: function () { return rules_1.IMPORT_PLATFORMS; } });
+Object.defineProperty(exports, "DEFAULT_IMPORT_PLATFORM", { enumerable: true, get: function () { return rules_1.DEFAULT_IMPORT_PLATFORM; } });
+Object.defineProperty(exports, "SOURCE_PACKAGE_DIR", { enumerable: true, get: function () { return rules_1.SOURCE_PACKAGE_DIR; } });
+Object.defineProperty(exports, "PLATFORM_IMPORT_RULES", { enumerable: true, get: function () { return rules_1.PLATFORM_IMPORT_RULES; } });
+Object.defineProperty(exports, "DEFAULT_IMPORT_RULES", { enumerable: true, get: function () { return rules_1.DEFAULT_IMPORT_RULES; } });
+Object.defineProperty(exports, "BUILD_CHAIN_PATTERNS", { enumerable: true, get: function () { return rules_1.BUILD_CHAIN_PATTERNS; } });
+Object.defineProperty(exports, "parsePlatform", { enumerable: true, get: function () { return rules_1.parsePlatform; } });
+Object.defineProperty(exports, "resolveImportRules", { enumerable: true, get: function () { return rules_1.resolveImportRules; } });
+Object.defineProperty(exports, "isBuildChainDependency", { enumerable: true, get: function () { return rules_1.isBuildChainDependency; } });
+Object.defineProperty(exports, "isProtectedTarget", { enumerable: true, get: function () { return rules_1.isProtectedTarget; } });
+Object.defineProperty(exports, "sanitizePathSegments", { enumerable: true, get: function () { return rules_1.sanitizePathSegments; } });
+Object.defineProperty(exports, "getImportedPrefix", { enumerable: true, get: function () { return rules_1.getImportedPrefix; } });
+Object.defineProperty(exports, "isGitRepoDir", { enumerable: true, get: function () { return rules_1.isGitRepoDir; } });
+var download_1 = require("./download");
+Object.defineProperty(exports, "downloadZip", { enumerable: true, get: function () { return download_1.downloadZip; } });
+Object.defineProperty(exports, "assertLocalZip", { enumerable: true, get: function () { return download_1.assertLocalZip; } });
+Object.defineProperty(exports, "extractImportZip", { enumerable: true, get: function () { return download_1.extractImportZip; } });
+Object.defineProperty(exports, "MAX_IMPORT_ZIP_BYTES", { enumerable: true, get: function () { return download_1.MAX_IMPORT_ZIP_BYTES; } });
+var place_1 = require("./place");
+Object.defineProperty(exports, "collectFiles", { enumerable: true, get: function () { return place_1.collectFiles; } });
+Object.defineProperty(exports, "normalizeEntries", { enumerable: true, get: function () { return place_1.normalizeEntries; } });
+Object.defineProperty(exports, "buildImportPlan", { enumerable: true, get: function () { return place_1.buildImportPlan; } });
+Object.defineProperty(exports, "applyImportPlan", { enumerable: true, get: function () { return place_1.applyImportPlan; } });
+Object.defineProperty(exports, "mapSourcePath", { enumerable: true, get: function () { return place_1.mapSourcePath; } });
+Object.defineProperty(exports, "FILE_COUNT_KEYS", { enumerable: true, get: function () { return place_1.FILE_COUNT_KEYS; } });
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "IMPORT_MANIFEST_REL", { enumerable: true, get: function () { return manifest_1.IMPORT_MANIFEST_REL; } });
+Object.defineProperty(exports, "IMPORT_PENDING_MARKER_REL", { enumerable: true, get: function () { return manifest_1.IMPORT_PENDING_MARKER_REL; } });
+Object.defineProperty(exports, "writeImportPendingMarker", { enumerable: true, get: function () { return manifest_1.writeImportPendingMarker; } });
+Object.defineProperty(exports, "IMPORT_MANIFEST_VERSION", { enumerable: true, get: function () { return manifest_1.IMPORT_MANIFEST_VERSION; } });
+Object.defineProperty(exports, "classifyDependencies", { enumerable: true, get: function () { return manifest_1.classifyDependencies; } });
+Object.defineProperty(exports, "buildImportManifest", { enumerable: true, get: function () { return manifest_1.buildImportManifest; } });
+Object.defineProperty(exports, "writeImportManifest", { enumerable: true, get: function () { return manifest_1.writeImportManifest; } });
+Object.defineProperty(exports, "importManifestPath", { enumerable: true, get: function () { return manifest_1.importManifestPath; } });
+Object.defineProperty(exports, "readJsonFile", { enumerable: true, get: function () { return manifest_1.readJsonFile; } });

package/dist/services/app/import/manifest.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPORT_PENDING_MARKER_REL = exports.IMPORT_MANIFEST_VERSION = exports.IMPORT_MANIFEST_REL = void 0;
+exports.classifyDependencies = classifyDependencies;
+exports.readJsonFile = readJsonFile;
+exports.buildImportManifest = buildImportManifest;
+exports.importManifestPath = importManifestPath;
+exports.writeImportPendingMarker = writeImportPendingMarker;
+exports.writeImportManifest = writeImportManifest;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const rules_1 = require("./rules");
+/** manifest 相对工程根的位置。它是导入的幂等标记，必须最后写。 */
+exports.IMPORT_MANIFEST_REL = '.spark/import/manifest.json';
+exports.IMPORT_MANIFEST_VERSION = 1;
+/**
+ * 「待迁移」标记：导入时与 manifest 一起写入，Coding Agent 完成迁移后删除。
+ * 沙箱 skill `import-migration` 以它的存在为加载条件，删除后该 skill 不再注入。
+ * manifest 则长期保留（导入幂等标记 + 依赖分析记录），两者职责分开。
+ */
+exports.IMPORT_PENDING_MARKER_REL = '.spark/import/MIGRATION_PENDING';
+function readDepField(pkg, field) {
+    if (typeof pkg !== 'object' || pkg === null)
+        return {};
+    const v = pkg[field];
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return {};
+    const out = {};
+    for (const [k, ver] of Object.entries(v)) {
+        out[k] = typeof ver === 'string' ? ver : JSON.stringify(ver);
+    }
+    return out;
+}
+/**
+ * 依赖清单分类（只做静态分析，不装、不联网）。优先级：
+ *   platform_managed（@lark-apaas/*）> present（工程已有，带 templateRange）> build_chain > missing
+ */
+function classifyDependencies(opts) {
+    const projectDeps = {
+        ...readDepField(opts.projectPkg, 'devDependencies'),
+        ...readDepField(opts.projectPkg, 'dependencies'),
+    };
+    const result = [];
+    for (const field of ['dependencies', 'devDependencies']) {
+        for (const [name, requested] of Object.entries(readDepField(opts.sourcePkg, field))) {
+            const dep = { name, requested, field, status: 'missing' };
+            if ((0, rules_1.isPlatformManagedDependency)(name))
+                dep.status = 'platform_managed';
+            else if (Object.prototype.hasOwnProperty.call(projectDeps, name)) {
+                dep.status = 'present';
+                dep.templateRange = projectDeps[name];
+            }
+            else if ((0, rules_1.isBuildChainDependency)(name))
+                dep.status = 'build_chain';
+            result.push(dep);
+        }
+    }
+    return result;
+}
+/** 读 JSON 文件；不存在返回 undefined，解析失败抛出原始错误由调用方决定降级。 */
+function readJsonFile(file) {
+    if (!node_fs_1.default.existsSync(file))
+        return undefined;
+    return JSON.parse(node_fs_1.default.readFileSync(file, 'utf-8'));
+}
+function buildImportManifest(opts) {
+    return {
+        version: exports.IMPORT_MANIFEST_VERSION,
+        platform: opts.platform,
+        importedAt: (opts.now ?? new Date()).toISOString(),
+        sourcePackageJson: opts.plan.hasSourcePackageJson ? `${rules_1.SOURCE_PACKAGE_DIR}/package.json` : null,
+        fileCounts: opts.plan.fileCounts,
+        dependencies: opts.dependencies,
+        excludedPaths: opts.plan.excludedPaths,
+        protectedConflicts: opts.plan.protectedConflicts,
+        replacedTemplateFiles: opts.plan.replacedTemplateFiles,
+    };
+}
+function importManifestPath(projectDir) {
+    return node_path_1.default.join(projectDir, ...exports.IMPORT_MANIFEST_REL.split('/'));
+}
+/** 写「待迁移」标记。必须在 manifest 之前写：manifest 是幂等标记，先写标记再写 manifest，中途失败重跑仍会补齐两者。 */
+function writeImportPendingMarker(projectDir) {
+    const file = node_path_1.default.join(projectDir, ...exports.IMPORT_PENDING_MARKER_REL.split('/'));
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    node_fs_1.default.writeFileSync(file, '本工程由外部项目导入，用户代码尚未迁移完成。迁移全部完成后删除本文件。\n', 'utf-8');
+}
+function writeImportManifest(projectDir, manifest) {
+    const file = importManifestPath(projectDir);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${String(process.pid)}`;
+    node_fs_1.default.writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    node_fs_1.default.renameSync(tmp, file);
+}

package/dist/services/app/import/place.js

@@ -0,0 +1,327 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILE_COUNT_KEYS = void 0;
+exports.collectFiles = collectFiles;
+exports.normalizeEntries = normalizeEntries;
+exports.listProjectUiComponents = listProjectUiComponents;
+exports.mapSourcePath = mapSourcePath;
+exports.buildImportPlan = buildImportPlan;
+exports.applyImportPlan = applyImportPlan;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const error_1 = require("../../../utils/error");
+const rules_1 = require("./rules");
+exports.FILE_COUNT_KEYS = [
+    'client/src',
+    'client/public',
+    'shared',
+    rules_1.SOURCE_PACKAGE_DIR,
+];
+/** 递归列出目录下的普通文件（posix 相对路径）。符号链接一律跳过，防止 zip 里的链接把工程外文件带进来。 */
+function collectFiles(rootDir) {
+    const out = [];
+    const walk = (rel) => {
+        for (const entry of node_fs_1.default.readdirSync(node_path_1.default.join(rootDir, rel), { withFileTypes: true })) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(childRel);
+            else if (entry.isFile())
+                out.push(childRel);
+        }
+    };
+    walk('');
+    return out.sort();
+}
+/**
+ * 规范化导入条目（对齐 merger.go extractZip + normalizeImportedFiles）：
+ *   1. 丢弃含 ".."、__MACOSX/、.DS_Store
+ *   2. 非 gemini：剥公共顶层目录（getImportedPrefix）；gemini 保留原始路径
+ *   3. 超长路径段 hash 截断
+ *   4. 丢弃 .git 元数据与 node_modules / dist / build 目录
+ */
+function normalizeEntries(rawPaths, platform) {
+    const kept = rawPaths.filter((p) => !(0, rules_1.isRawEntrySkipped)(p));
+    const prefix = platform === 'gemini' ? '' : (0, rules_1.getImportedPrefix)(kept);
+    const entries = [];
+    const renamed = [];
+    for (const raw of kept) {
+        if ((0, rules_1.isGitRepoDir)(raw))
+            continue;
+        const stripped = (0, rules_1.removePrefix)(prefix, raw);
+        if (!stripped)
+            continue;
+        const normalized = (0, rules_1.sanitizePathSegments)(stripped);
+        if (normalized !== stripped)
+            renamed.push({ from: stripped, to: normalized });
+        if ((0, rules_1.isGitRepoDir)(normalized) || (0, rules_1.hasSkippedDirSegment)(normalized))
+            continue;
+        entries.push({ raw, normalized });
+    }
+    return { entries, renamed };
+}
+const UI_PREFIX_SRC = 'src/components/ui/';
+const UI_PREFIX_PROJECT = 'client/src/components/ui/';
+const JS_EXTS = new Set(['.js', '.jsx']);
+const TS_EXTS = new Set(['.ts', '.tsx']);
+function stripExt(name) {
+    const ext = node_path_1.default.posix.extname(name);
+    return ext ? name.slice(0, -ext.length) : name;
+}
+/** 工程已有的 UI 组件：basename（去扩展名）→ 相对工程根路径（仅 ui/ 直接子文件）。 */
+function listProjectUiComponents(projectDir) {
+    const result = new Map();
+    const uiDir = node_path_1.default.join(projectDir, ...UI_PREFIX_PROJECT.split('/'));
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(uiDir, { withFileTypes: true });
+    }
+    catch {
+        return result;
+    }
+    for (const d of names) {
+        if (!d.isFile())
+            continue;
+        const base = stripExt(d.name);
+        const list = result.get(base) ?? [];
+        list.push(`${UI_PREFIX_PROJECT}${d.name}`);
+        result.set(base, list);
+    }
+    return result;
+}
+function mapByPrefix(src, from, to) {
+    return src.startsWith(from) ? to + src.slice(from.length) : undefined;
+}
+/** 按平台把规范化源路径映射到工程目标路径（对齐 merger.go 各 merge* 分支）。 */
+function mapSourcePath(src, platform, rules, uiComponents) {
+    const fallback = `${rules_1.SOURCE_PACKAGE_DIR}/${src}`;
+    switch (platform) {
+        case 'lovable': {
+            if (src.startsWith('src/')) {
+                if ((0, rules_1.isExcludedPath)(src, rules.excludedPaths))
+                    return { target: fallback, excluded: true };
+                return { target: `client/${src}`, excluded: false };
+            }
+            const pub = mapByPrefix(src, 'public/', 'client/public/');
+            return { target: pub ?? fallback, excluded: false };
+        }
+        case 'replit': {
+            if (src.startsWith('client/src/')) {
+                if ((0, rules_1.isExcludedPath)(src, rules.excludedPaths))
+                    return { target: fallback, excluded: true };
+                return { target: src, excluded: false };
+            }
+            if (src.startsWith('shared/'))
+                return { target: src, excluded: false };
+            const assets = mapByPrefix(src, 'attached_assets/', 'client/public/assets/');
+            return { target: assets ?? fallback, excluded: false };
+        }
+        case 'gemini': {
+            const mapped = mapByPrefix(src, 'components/', 'client/src/components/') ??
+                mapByPrefix(src, 'services/', 'client/src/services/') ??
+                (src === 'types.ts' ? 'client/src/types.ts' : undefined) ??
+                (src === 'constants.ts' ? 'client/src/constants.ts' : undefined);
+            return { target: mapped ?? fallback, excluded: false };
+        }
+        case 'zip': {
+            if (src.startsWith('src/')) {
+                if (src.startsWith(UI_PREFIX_SRC)) {
+                    const rest = src.slice(UI_PREFIX_SRC.length);
+                    if (!rest.includes('/')) {
+                        const existing = uiComponents.get(stripExt(rest));
+                        if (existing && existing.length > 0) {
+                            // 模板业务组件依赖 TS 版 UI 组件的类型，JS 版替换后会类型报错，保留模板版本
+                            const tsVersion = existing.find((p) => TS_EXTS.has(node_path_1.default.posix.extname(p)));
+                            if (tsVersion && JS_EXTS.has(node_path_1.default.posix.extname(rest))) {
+                                return { target: fallback, excluded: false, uiKept: tsVersion };
+                            }
+                            return { target: `client/${src}`, excluded: false, uiReplaced: existing };
+                        }
+                    }
+                }
+                if ((0, rules_1.isExcludedPath)(src, rules.excludedPaths))
+                    return { target: fallback, excluded: true };
+                return { target: `client/${src}`, excluded: false };
+            }
+            const pub = mapByPrefix(src, 'public/', 'client/public/');
+            return { target: pub ?? fallback, excluded: false };
+        }
+    }
+}
+function countKey(target) {
+    for (const key of exports.FILE_COUNT_KEYS) {
+        if (target === key || target.startsWith(`${key}/`))
+            return key;
+    }
+    return undefined;
+}
+/** 计算完整放置计划（纯计算 + 只读工程目录，不写任何文件）。 */
+function buildImportPlan(opts) {
+    const uiComponents = opts.platform === 'zip'
+        ? listProjectUiComponents(opts.projectDir)
+        : new Map();
+    const byTarget = new Map();
+    const excludedPaths = [];
+    const protectedConflicts = [];
+    const replaced = new Set();
+    const warnings = [];
+    for (const entry of opts.entries) {
+        const src = entry.normalized;
+        const mapped = mapSourcePath(src, opts.platform, opts.rules, uiComponents);
+        let target = mapped.target;
+        if (mapped.excluded)
+            excludedPaths.push(src);
+        if ((0, rules_1.isProtectedTarget)(target)) {
+            const placedAt = `${rules_1.SOURCE_PACKAGE_DIR}/${src}`;
+            protectedConflicts.push({ source: src, target, placedAt });
+            target = placedAt;
+        }
+        else if (mapped.uiKept) {
+            protectedConflicts.push({ source: src, target: mapped.uiKept, placedAt: target });
+        }
+        else if (mapped.uiReplaced) {
+            for (const p of mapped.uiReplaced)
+                replaced.add(p);
+        }
+        if (byTarget.has(target)) {
+            warnings.push(`多个导入文件映射到同一目标，后者覆盖前者：${target}`);
+        }
+        byTarget.set(target, { source: src, raw: entry.raw, target });
+    }
+    const placements = [...byTarget.values()];
+    const fileCounts = {
+        'client/src': 0,
+        'client/public': 0,
+        shared: 0,
+        source_package: 0,
+    };
+    for (const p of placements) {
+        const key = countKey(p.target);
+        if (key)
+            fileCounts[key] += 1;
+    }
+    const replacedTemplateFiles = [...replaced].sort();
+    const deletions = replacedTemplateFiles.filter((p) => !byTarget.has(p));
+    const hasSourcePackageJson = byTarget.has(`${rules_1.SOURCE_PACKAGE_DIR}/package.json`);
+    const overwrites = placements
+        .map((p) => p.target)
+        .filter((t) => !replaced.has(t) && node_fs_1.default.existsSync(node_path_1.default.join(opts.projectDir, ...t.split('/'))))
+        .sort();
+    return {
+        placements,
+        replacedTemplateFiles,
+        deletions,
+        excludedPaths,
+        protectedConflicts,
+        fileCounts,
+        hasSourcePackageJson,
+        overwrites,
+        warnings,
+    };
+}
+function writeFailed(stage, err) {
+    return new error_1.AppError('WRITE_FAILED', `导入写入失败（${stage}）：${err instanceof Error ? err.message : String(err)}`, { next_actions: ['检查磁盘空间 / 目录权限后重试 miaoda app import'] });
+}
+/**
+ * 预检移入目标：rename 遇到「目标已是目录」或「父路径上有普通文件」必然失败，
+ * 在动工程之前拦下，避免移入到一半才报错。
+ */
+function preflightTargets(plan, projectDir) {
+    for (const p of plan.placements) {
+        const segs = p.target.split('/');
+        for (let i = 1; i < segs.length; i += 1) {
+            const parent = node_path_1.default.join(projectDir, ...segs.slice(0, i));
+            if (node_fs_1.default.existsSync(parent) && !node_fs_1.default.statSync(parent).isDirectory()) {
+                throw writeFailed('preflight', new Error(`目标父路径是文件：${segs.slice(0, i).join('/')}（${p.target}）`));
+            }
+        }
+        const dest = node_path_1.default.join(projectDir, ...segs);
+        if (node_fs_1.default.existsSync(dest) && node_fs_1.default.statSync(dest).isDirectory()) {
+            throw writeFailed('preflight', new Error(`目标路径已是目录：${p.target}`));
+        }
+    }
+}
+/** 把工程里已有的 rel 挪进 backupDir，返回暂存位置；不存在则返回 undefined。 */
+function backupExisting(projectDir, backupDir, rel) {
+    const dest = node_path_1.default.join(projectDir, ...rel.split('/'));
+    if (!node_fs_1.default.existsSync(dest))
+        return undefined;
+    const backup = node_path_1.default.join(backupDir, ...rel.split('/'));
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(backup), { recursive: true });
+    node_fs_1.default.renameSync(dest, backup);
+    return backup;
+}
+/** 逆序撤回已执行的移入 / 删除；返回撤回失败的路径（尽力而为，不中断）。 */
+function rollbackMoves(records) {
+    const failed = [];
+    for (const r of [...records].reverse()) {
+        try {
+            node_fs_1.default.rmSync(r.dest, { force: true });
+            if (r.backup) {
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(r.dest), { recursive: true });
+                node_fs_1.default.renameSync(r.backup, r.dest);
+            }
+        }
+        catch {
+            failed.push(r.dest);
+        }
+    }
+    return failed;
+}
+/**
+ * 三阶段落盘：
+ *   1. 全部文件先拷进 stagingDir（工程不动）；任一失败 → 清理暂存，工程保持原样
+ *   2. 预检所有移入目标（目标已是目录 / 父路径是文件）；不通过 → 工程保持原样
+ *   3. 逐个移入工程、删被替换的模板 UI 组件；被覆盖或删除的原文件先挪进暂存目录下的备份，
+ *      中途失败按逆序回滚，工程恢复原样（只可能留下新建的空目录）
+ * 失败一律抛 WRITE_FAILED，调用方不写 manifest，重跑会重新导入。
+ */
+function applyImportPlan(opts) {
+    const { plan, extractDir, projectDir, stagingDir } = opts;
+    // 备份放暂存目录下（同一文件系统，rename 不跨设备），finally 一并清理；
+    // 放置目标都以 client/ shared/ source_package/ 开头，不会与它重名。
+    const backupDir = node_path_1.default.join(stagingDir, '.backup');
+    try {
+        try {
+            for (const p of plan.placements) {
+                const staged = node_path_1.default.join(stagingDir, ...p.target.split('/'));
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(staged), { recursive: true });
+                node_fs_1.default.copyFileSync(node_path_1.default.join(extractDir, ...p.raw.split('/')), staged);
+            }
+        }
+        catch (err) {
+            throw writeFailed('stage', err);
+        }
+        preflightTargets(plan, projectDir);
+        const records = [];
+        try {
+            for (const p of plan.placements) {
+                const staged = node_path_1.default.join(stagingDir, ...p.target.split('/'));
+                const dest = node_path_1.default.join(projectDir, ...p.target.split('/'));
+                const backup = backupExisting(projectDir, backupDir, p.target);
+                records.push({ dest, backup });
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(dest), { recursive: true });
+                node_fs_1.default.renameSync(staged, dest);
+            }
+            for (const rel of plan.deletions) {
+                const backup = backupExisting(projectDir, backupDir, rel);
+                if (backup)
+                    records.push({ dest: node_path_1.default.join(projectDir, ...rel.split('/')), backup });
+            }
+        }
+        catch (err) {
+            const notRestored = rollbackMoves(records);
+            if (notRestored.length > 0) {
+                throw writeFailed('move', new Error(`${err instanceof Error ? err.message : String(err)}；回滚未完成：${notRestored
+                    .map((d) => node_path_1.default.relative(projectDir, d))
+                    .join(', ')}`));
+            }
+            throw writeFailed('move', err);
+        }
+    }
+    finally {
+        node_fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    }
+}

package/dist/services/app/import/rules.js

@@ -0,0 +1,293 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT_ROOT_DIRS = exports.BUILD_CHAIN_PATTERNS = exports.DEFAULT_IMPORT_RULES = exports.PLATFORM_IMPORT_RULES = exports.MAX_PATH_SEGMENT_BYTES = exports.SOURCE_PACKAGE_DIR = exports.DEFAULT_IMPORT_PLATFORM = exports.IMPORT_PLATFORMS = void 0;
+exports.isBuildChainDependency = isBuildChainDependency;
+exports.isPlatformManagedDependency = isPlatformManagedDependency;
+exports.parsePlatform = parsePlatform;
+exports.resolveImportRules = resolveImportRules;
+exports.isGitRepoDir = isGitRepoDir;
+exports.isRawEntrySkipped = isRawEntrySkipped;
+exports.hasSkippedDirSegment = hasSkippedDirSegment;
+exports.getImportedPrefix = getImportedPrefix;
+exports.removePrefix = removePrefix;
+exports.sanitizePathSegments = sanitizePathSegments;
+exports.isExcludedPath = isExcludedPath;
+exports.isProtectedTarget = isProtectedTarget;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_path_1 = __importDefault(require("node:path"));
+const error_1 = require("../../../utils/error");
+const import_source_1 = require("../../../services/app/init/import-source");
+/**
+ * 外部平台导入规则（移植自 studio_server import_svc/merger.go + tcc/import_merger_config.go）。
+ *
+ * 本文件只放纯函数与常量：路径规范化、平台排除清单、受保护目标、构建链依赖识别。
+ * 不做 IO，便于逐条对齐服务端 merger 的单测口径。
+ */
+exports.IMPORT_PLATFORMS = ['lovable', 'replit', 'gemini', 'zip'];
+exports.DEFAULT_IMPORT_PLATFORM = 'zip';
+/** 不进模板工程的文件统一落到这里（用户原 package.json 也在此：source_package/package.json）。 */
+exports.SOURCE_PACKAGE_DIR = 'source_package';
+/** 单个路径段字节上限；超过则 hash 截断重命名，避免沙箱解压 ENAMETOOLONG（对齐 merger.go）。 */
+exports.MAX_PATH_SEGMENT_BYTES = 60;
+/**
+ * 平台排除路径（取线上 TCC ImportMergerConfig 的 excluded_paths，而非代码兜底值）。
+ * 实际生效 = 平台清单 + DEFAULT 清单（对齐 tcc.GetImportExcludedPaths）。
+ *
+ * 不再有排除依赖清单：导入不合并 package.json，依赖由 Coding Agent 参考 manifest 自行安装、
+ * 遇到冲突自行处理。
+ */
+exports.PLATFORM_IMPORT_RULES = {
+    lovable: {
+        excludedPaths: [
+            'src/App.tsx',
+            'src/main.tsx',
+            'src/index.css',
+            'src/hooks/use-mobile.tsx',
+            'src/integrations/supabase',
+            'src/lib/supabase.ts',
+        ],
+    },
+    replit: {
+        excludedPaths: [
+            'client/src/App.tsx',
+            'client/src/main.tsx',
+            'client/src/index.css',
+            'client/src/hooks/use-mobile.tsx',
+        ],
+    },
+    gemini: {
+        excludedPaths: [],
+    },
+    zip: {
+        excludedPaths: [
+            'src/db/',
+            'src/integrations/',
+            'src/hooks/use-supabase-upload.ts',
+            'src/hooks/use-mobile.tsx',
+            'src/App.tsx',
+            'src/main.tsx',
+            'src/index.css',
+            'src/App.jsx',
+            'src/main.jsx',
+        ],
+    },
+};
+exports.DEFAULT_IMPORT_RULES = {
+    excludedPaths: [],
+};
+/**
+ * 构建链 / 工具链依赖：模板已有自己的构建体系，用户包里的这类依赖通常不需要装。
+ * 支持精确名与 `*` 通配（只在末尾或 scope 内使用），集中在此一处便于扩展。
+ */
+exports.BUILD_CHAIN_PATTERNS = [
+    'vite',
+    '@vitejs/*',
+    'vite-plugin-*',
+    '@vite-pwa/*',
+    'rollup',
+    'rollup-plugin-*',
+    '@rollup/*',
+    'esbuild',
+    'webpack',
+    'webpack-*',
+    '@babel/*',
+    'babel-*',
+    'eslint',
+    'eslint-*',
+    '@eslint/*',
+    '@typescript-eslint/*',
+    'typescript-eslint',
+    'typescript',
+    'tailwindcss',
+    '@tailwindcss/*',
+    'postcss',
+    'postcss-*',
+    'autoprefixer',
+    'prettier',
+    'prettier-*',
+    'jest',
+    '@jest/*',
+    'ts-jest',
+    'vitest',
+    '@vitest/*',
+    'react-scripts',
+    '@vue/cli-*',
+    '@types/*',
+    'lovable-tagger',
+    'miaoda-sc-plugin',
+    '@builder.io/vite-plugin-jsx-loc',
+];
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\/]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`);
+}
+const BUILD_CHAIN_REGEXPS = exports.BUILD_CHAIN_PATTERNS.map(globToRegExp);
+function isBuildChainDependency(name) {
+    return BUILD_CHAIN_REGEXPS.some((re) => re.test(name));
+}
+/** @lark-apaas/* 是平台托管依赖，版本由模板 / sync 管，不能按用户包装。 */
+function isPlatformManagedDependency(name) {
+    return name.startsWith('@lark-apaas/');
+}
+function parsePlatform(raw) {
+    const value = (raw ?? exports.DEFAULT_IMPORT_PLATFORM).trim().toLowerCase();
+    if (exports.IMPORT_PLATFORMS.includes(value))
+        return value;
+    throw new error_1.AppError('ARGS_INVALID', `--platform 取值非法：${raw ?? ''}（可选 ${exports.IMPORT_PLATFORMS.join(' / ')}）`);
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+/**
+ * 解析生效规则：平台清单 + DEFAULT 清单；`--rules-json` 提供的字段整体替换对应默认值
+ * （未提供的字段保留默认）。
+ */
+function resolveImportRules(platform, rulesJson) {
+    const rules = {
+        excludedPaths: [
+            ...exports.PLATFORM_IMPORT_RULES[platform].excludedPaths,
+            ...exports.DEFAULT_IMPORT_RULES.excludedPaths,
+        ],
+    };
+    if (rulesJson === undefined || rulesJson.trim() === '')
+        return rules;
+    let parsed;
+    try {
+        parsed = JSON.parse(rulesJson);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new error_1.AppError('ARGS_INVALID', `--rules-json 必须是合法 JSON：${msg}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new error_1.AppError('ARGS_INVALID', '--rules-json 必须是 JSON 对象');
+    }
+    const obj = parsed;
+    for (const key of ['excludedPaths']) {
+        const v = obj[key];
+        if (v === undefined)
+            continue;
+        if (!isStringArray(v)) {
+            throw new error_1.AppError('ARGS_INVALID', `--rules-json.${key} 必须是字符串数组`);
+        }
+        rules[key] = [...v];
+    }
+    return rules;
+}
+// ── 路径规范化（对齐 merger.go） ────────────
+/** .git 元数据：精确 .git、.git/ 前缀、嵌套 /.git/。不误伤 .gitignore / .github / .gitattributes。 */
+function isGitRepoDir(p) {
+    return p === '.git' || p.startsWith('.git/') || p.includes('/.git/');
+}
+/** zip 解出来的原始条目里需要直接丢弃的（merger.go extractZip 的过滤口径）。 */
+function isRawEntrySkipped(p) {
+    if (p.includes('..'))
+        return true;
+    if (p.startsWith('__MACOSX/'))
+        return true;
+    if (p.endsWith('.DS_Store'))
+        return true;
+    return false;
+}
+/** 目录段命中 node_modules / dist / build（任意层级）即跳过；与 `app init --source-path` 同口径。 */
+function hasSkippedDirSegment(p) {
+    const segments = p.split('/');
+    segments.pop();
+    return segments.some((seg) => seg !== '.git' && import_source_1.IMPORT_SKIP_DIRS.has(seg));
+}
+/**
+ * 放置规则本身认识的工程目录名。用户只压了这些目录（如只打包 src/）时，公共首段就是工程目录本身，
+ * 不是外层包裹目录，不能剥——否则 src/** 会整体落进 source_package/（服务端 merger.go 的同款缺陷，此处修正）。
+ */
+exports.PROJECT_ROOT_DIRS = new Set([
+    'src',
+    'public',
+    'client',
+    'server',
+    'shared',
+    'components',
+    'services',
+    'attached_assets',
+]);
+/**
+ * 导入包的公共顶层目录：所有条目都至少两段、首段一致且首段不含 "."，并且首段不是工程目录名
+ * （PROJECT_ROOT_DIRS），才认为是包裹目录。否则返回 ""（不剥前缀）。
+ */
+function getImportedPrefix(paths) {
+    let common = '';
+    let first = true;
+    for (const p of paths) {
+        const idx = p.indexOf('/');
+        if (idx < 0)
+            return '';
+        const head = p.slice(0, idx);
+        if (head.includes('.'))
+            return '';
+        if (first) {
+            common = head;
+            first = false;
+        }
+        else if (head !== common) {
+            return '';
+        }
+    }
+    return exports.PROJECT_ROOT_DIRS.has(common) ? '' : common;
+}
+function removePrefix(prefix, p) {
+    if (!prefix)
+        return p;
+    return p.startsWith(`${prefix}/`) ? p.slice(prefix.length + 1) : p;
+}
+/** 超过 60 字节的路径段改名为 truncated-<sha256 前 8 字节 hex><ext>（ext 长度 ≤ 20 才保留）。 */
+function sanitizePathSegments(p) {
+    const segments = p.split('/');
+    let rewritten = false;
+    for (let i = 0; i < segments.length; i += 1) {
+        const seg = segments[i];
+        if (Buffer.byteLength(seg, 'utf-8') <= exports.MAX_PATH_SEGMENT_BYTES)
+            continue;
+        let ext = node_path_1.default.posix.extname(seg);
+        if (Buffer.byteLength(ext, 'utf-8') > 20)
+            ext = '';
+        const sum = node_crypto_1.default.createHash('sha256').update(seg, 'utf-8').digest('hex');
+        segments[i] = `truncated-${sum.slice(0, 16)}${ext}`;
+        rewritten = true;
+    }
+    return rewritten ? segments.join('/') : p;
+}
+function isExcludedPath(p, excludedPaths) {
+    return excludedPaths.some((prefix) => prefix !== '' && p.startsWith(prefix));
+}
+// ── 受保护目标 ────────────
+const PROTECTED_ROOT_FILES = new Set([
+    'package.json',
+    'package-lock.json',
+    '.npmrc',
+    'AGENTS.md',
+    'server/main.ts',
+    'client/src/index.tsx',
+]);
+const PROTECTED_ROOT_DIRS = ['.githooks/', 'scripts/', '.spark/', 'node_modules/'];
+const PROTECTED_ROOT_PATTERNS = [
+    /^tsconfig.*\.json$/,
+    /^vite\.config\..+$/,
+    /^eslint\.config\..+$/,
+];
+/**
+ * 工程内模板托管、导入绝不能新建 / 覆盖的目标路径（相对工程根）。
+ * source_package/ 是导入的分流目录，本身不受保护。
+ */
+function isProtectedTarget(target) {
+    if (target.startsWith(`${exports.SOURCE_PACKAGE_DIR}/`))
+        return false;
+    if (PROTECTED_ROOT_FILES.has(target))
+        return true;
+    if (PROTECTED_ROOT_DIRS.some((d) => target.startsWith(d)))
+        return true;
+    if (!target.includes('/') && PROTECTED_ROOT_PATTERNS.some((re) => re.test(target)))
+        return true;
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {