refactor(sandbox): enforce preflight schema validation for legacy migration

Author: DigHuang

.agents/design/core/ai/sandbox/user-level-sandbox.md

@@ -50,8 +50,8 @@ sessionWorkDirectory = <workspaceRoot>/sessions/<chatId>
 - 旧 Workspace 中直接位于 `projects/` 下、名称为 Skill Version ID 的运行时缓存目录不迁移。
 - 其他文件保持原相对路径进入目标 session。
 - `sessions/<chatId>` 不存在时，使用 staging + rename 提交为该目录。
-- `sessions/<chatId>` 已存在时，使用 staging + rename 提交为 `sessions/<chatId>/.old`。
-- `.old` 是迁移保留目录，不写迁移 marker；目标目录已存在时视为目录安装完成。
+- `sessions/<chatId>` 已存在时，将 staging 递归合并进 session；同名文件或类型冲突均以
+  session 现有内容为准，旧内容直接舍弃。
 - 单条旧记录安装成功后，同步删除旧 S3 归档并按 `_id` 删除旧实例记录。
 - 旧记录仍存在就是该条迁移尚未完成或清理尚未完成的进度依据。
 
@@ -161,6 +161,12 @@ type SandboxInstance = {
 
 ## 6. 迁移设计
 
+管理员迁移入口首先读取原始 Legacy 文档并执行整表结构预检。App 必须具备合法的
+`sourceType/sourceId/userId/chatId`，Skill 必须具备合法的 `sourceType/sourceId`，公共字段
+和可选配置必须符合 Legacy Zod Schema，且不得残留 beta6 已清理的 `appId/type/metadata.skillId`。
+任一记录失败时直接拒绝整次任务，错误返回 `_id`、`sandboxId`、字段路径和原因；预检通过前
+不写新表、不连接 Sandbox、不访问 S3，也不产生迁移 Track。
+
 ### 6.1 Skill Edit
 
 1. 将旧 Skill Edit 记录复制到新表。
@@ -176,8 +182,9 @@ type SandboxInstance = {
 4. 将每条旧 Sandbox 停止并归档；已归档记录直接复用 S3。
 5. 在目标 Sandbox 的 `.migration/<oldSandboxId>` 解压 staging。
 6. 删除 staging 中直接位于 `projects/` 下且名称为 24 位十六进制 ID 的目录。
-7. 目标 session 不存在时 rename staging 到 session；已存在时 rename 到 `.old`。
-8. 最终目录已存在时视为已安装，校验目录可读后继续清理。
+7. 目标 session 不存在时 rename staging 到 session；已存在时递归合并 staging，目录同名
+   时继续向下合并，文件同名或文件/目录类型冲突时保留 session 现有内容。
+8. 重复执行时已迁入的路径会因目标存在而跳过，保持幂等。
 9. 同步删除旧归档，确认对象不存在后删除 Legacy 记录。
 10. 单次任务读取全部 Legacy 记录；Skill 只迁移表记录，直接并行执行；App 固定并发度
     为 5，按 `sourceId + userId` 分组后组间并发、组内按 Chat 顺序串行。
@@ -192,7 +199,6 @@ type SandboxInstance = {
   并解除临时 `metadata.migration`。
 - 重试先将 `failed` 切回 `migrating`，只查询仍存在的 Legacy 记录。
 - S3 已不存在但确定性目标目录存在时，直接删除残留 Legacy 记录。
-- `.old` 已存在时不覆盖、不生成额外目录，视为目录提交已完成。
 - 真实迁移使用全局 Redis lease，避免两个管理员请求并发写同一 staging 目录。
 - 全部 Legacy 记录完成后，Migration 状态删除，目标 Sandbox 回归普通生命周期。
 
@@ -209,7 +215,7 @@ type SandboxInstance = {
 - 自动 stop/archive/delete 跳过 Migration 记录。
 - Chat 删除不删除共享 Sandbox；App 删除仍删除。
 - Skill 迁移保留完整记录且不删除 S3。
-- App 迁移覆盖默认目录、`.old` 冲突目录、重试、单条清理和最终状态清理。
+- App 迁移覆盖默认目录、新 session 优先的冲突合并、重试、单条清理和最终状态清理。
 
 ## 8. TODO
 
@@ -225,7 +231,7 @@ type SandboxInstance = {
 - [x] 调整 Chat 删除、App 删除、自动 stop/archive/delete 生命周期。
 - [x] 增加同步 S3 归档删除与存在性检查。
 - [x] 实现 Skill Edit Legacy 记录迁移。
-- [x] 实现 App Workspace 分组迁移、staging、`.old` 和逐条清理。
+- [x] 实现 App Workspace 分组迁移、staging、新 session 优先合并和逐条清理。
 - [x] 编写并运行局部单元测试。
 - [x] 运行相关 TypeScript 检查。
 - [x] 最后运行全量测试。

packages/global/test/core/ai/sandbox/constants.test.ts

@@ -39,10 +39,6 @@ describe('generateSandboxId', () => {
 });
 
 describe('generateUserSandboxId', () => {
-  it('is stable for the same App and user across Chats', () => {
-    expect(generateUserSandboxId('app1', 'user1')).toBe(generateUserSandboxId('app1', 'user1'));
-  });
-
   it('changes when App or user changes', () => {
     const id = generateUserSandboxId('app1', 'user1');
     expect(id).not.toBe(generateUserSandboxId('app2', 'user1'));

packages/service/common/middle/tracks/utils.ts

@@ -264,7 +264,6 @@ export const pushTrack = {
           phase: 'failure';
           sandboxId: string;
           step:
-            | 'validate_legacy_record'
             | 'prepare_app_target'
             | 'migrate_skill'
             | 'migrate_app'

packages/service/core/ai/sandbox/application/migration.ts

@@ -18,6 +18,7 @@ import { pushTrack } from '../../../../common/middle/tracks/utils';
 import { getS3SandboxSource } from '../../../../common/s3/sources/sandbox';
 import {
   MongoLegacySandboxInstance,
+  LegacySandboxInstanceZodSchema,
   type LegacySandboxInstanceSchemaType
 } from '../infrastructure/instance/legacySchema';
 import {
@@ -48,7 +49,7 @@ type UserSandboxMigrationParams = {
   dryRun?: boolean;
 };
 
-type LegacyWorkspaceInstallState = 'old' | 'conflict' | 'empty';
+type LegacyWorkspaceInstallState = 'conflict' | 'empty';
 type LegacySandboxCleanupStep =
   | 'delete_sandbox'
   | 'delete_volume'
@@ -100,11 +101,40 @@ type ResolvedLegacyApp = {
   chatId: string;
 };
 
-const resolveLegacySourceId = (doc: LegacySandboxInstanceSchemaType) =>
-  doc.sourceId || doc.appId || doc.metadata?.skillId || undefined;
+/**
+ * 在产生任何迁移副作用前校验整张 Legacy 表。
+ */
+const parseLegacySandboxInstances = (rawDocs: unknown[]): LegacySandboxInstanceSchemaType[] => {
+  const parsedDocs: LegacySandboxInstanceSchemaType[] = [];
+  const failures: string[] = [];
+
+  for (const rawDoc of rawDocs) {
+    const parsed = LegacySandboxInstanceZodSchema.safeParse(rawDoc);
+    if (parsed.success) {
+      parsedDocs.push(parsed.data);
+      continue;
+    }
+
+    const doc = rawDoc && typeof rawDoc === 'object' ? (rawDoc as Record<string, unknown>) : {};
+    const issues = parsed.error.issues
+      .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+      .join('; ');
+    failures.push(
+      `_id=${String(doc._id ?? 'unknown')}, sandboxId=${String(doc.sandboxId ?? 'unknown')} [${issues}]`
+    );
+  }
 
-const isLegacySkillInstance = (doc: LegacySandboxInstanceSchemaType) =>
-  doc.sourceType === ChatSourceTypeEnum.skillEdit || doc.type === SandboxTypeEnum.editDebug;
+  if (failures.length > 0) {
+    throw new Error(
+      [
+        `Legacy Sandbox preflight validation failed for ${failures.length} record(s)`,
+        ...failures
+      ].join('\n')
+    );
+  }
+
+  return parsedDocs;
+};
 
 /**
  * 检查同一 App + User 是否仍有未迁移的 Legacy 记录。
@@ -145,7 +175,7 @@ const toLegacyResource = (doc: LegacySandboxInstanceSchemaType): SandboxResource
   metadata: doc.metadata
 });
 
-/** 检查旧 Workspace 在当前 Chat 目标目录中的提交状态。 */
+/** 检查目标 session 是否已经存在。 */
 export async function inspectLegacyWorkspaceInstallState(params: {
   target: Awaited<ReturnType<typeof getSandboxClient>>;
   chatId: string;
@@ -156,12 +186,9 @@ export async function inspectLegacyWorkspaceInstallState(params: {
     joinSandboxPath(workspaceRoot, 'sessions'),
     getSandboxSessionPathSegment(chatId)
   );
-  const oldDirectory = joinSandboxPath(sessionWorkDirectory, '.old');
   const checkResult = await target.provider.execute(
     [
-      `if [ -d ${shellQuote(oldDirectory)} ]; then`,
-      "  printf '%s' old",
-      `elif [ -d ${shellQuote(sessionWorkDirectory)} ]; then`,
+      `if [ -d ${shellQuote(sessionWorkDirectory)} ]; then`,
       "  printf '%s' conflict",
       'else',
       "  printf '%s' empty",
@@ -174,14 +201,15 @@ export async function inspectLegacyWorkspaceInstallState(params: {
   }
 
   const state = checkResult.stdout.trim();
-  if (state === 'old' || state === 'conflict' || state === 'empty') return state;
+  if (state === 'conflict' || state === 'empty') return state;
   throw new Error(`Unexpected migration target state: ${state || 'empty output'}`);
 }
 
 /**
  * 把一条旧 Workspace 归档安装到目标用户级 Sandbox。
  *
- * session 已存在视为冲突并提交到 `.old`；`.old` 已存在视为此前已提交。
+ * session 不存在时直接提交 staging；已存在时递归合并，所有同名路径以 session
+ * 现有内容为准。
  */
 export async function installLegacyWorkspaceArchive(params: {
   target: Awaited<ReturnType<typeof getSandboxClient>>;
@@ -195,28 +223,25 @@ export async function installLegacyWorkspaceArchive(params: {
     joinSandboxPath(workspaceRoot, 'sessions'),
     getSandboxSessionPathSegment(chatId)
   );
-  const oldDirectory = joinSandboxPath(sessionWorkDirectory, '.old');
   const stagingName = createHash('sha256').update(legacySandboxId).digest('hex').slice(0, 40);
   const stagingDirectory = joinSandboxPath(
     joinSandboxPath(workspaceRoot, '.migration'),
     stagingName
   );
-  const targetState = await inspectLegacyWorkspaceInstallState({ target, chatId });
-  if (targetState === 'old') return;
-
   await restoreSandboxWorkspaceArchiveForMigration({
     sandbox: target.provider,
     workDirectory: stagingDirectory,
     sandboxId: legacySandboxId,
     archiveBody
   });
 
-  const finalDirectory = targetState === 'conflict' ? oldDirectory : sessionWorkDirectory;
+  const sourceDirectory = stagingDirectory;
   const commitResult = await target.provider.execute(
     [
-      `staging=${shellQuote(stagingDirectory)}`,
-      `target=${shellQuote(finalDirectory)}`,
-      `projects="$staging/projects"`,
+      'set -e',
+      `source=${shellQuote(sourceDirectory)}`,
+      `target=${shellQuote(sessionWorkDirectory)}`,
+      'projects="$source/projects"',
       'if [ -d "$projects" ]; then',
       '  find "$projects" -mindepth 1 -maxdepth 1 -type d -exec sh -c \'',
       '    for dir; do',
@@ -226,16 +251,31 @@ export async function installLegacyWorkspaceArchive(params: {
       '    done',
       "  ' sh {} +",
       'fi',
+      'merge_without_overwrite() {',
+      '  source_root=$1',
+      '  target_root=$2',
+      '  for source_path in "$source_root"/* "$source_root"/.[!.]* "$source_root"/..?*; do',
+      '    [ -e "$source_path" ] || [ -L "$source_path" ] || continue',
+      '    name=${source_path##*/}',
+      '    target_path="$target_root/$name"',
+      '    if [ ! -e "$target_path" ] && [ ! -L "$target_path" ]; then',
+      '      mv -- "$source_path" "$target_path"',
+      '    elif [ -d "$source_path" ] && [ ! -L "$source_path" ] && [ -d "$target_path" ] && [ ! -L "$target_path" ]; then',
+      '      merge_without_overwrite "$source_path" "$target_path"',
+      '    fi',
+      '  done',
+      '}',
       'if [ -d "$target" ]; then',
-      '  rm -rf -- "$staging"',
+      '  merge_without_overwrite "$source" "$target"',
+      '  rm -rf -- "$source"',
       '  exit 0',
       'fi',
       'if [ -e "$target" ]; then',
       '  echo "Migration target exists but is not a directory" >&2',
       '  exit 1',
       'fi',
       'mkdir -p "$(dirname "$target")"',
-      'mv -- "$staging" "$target"',
+      'mv -- "$source" "$target"',
       'test -d "$target"'
     ].join('\n'),
     { timeoutMs: MIGRATION_COMMAND_TIMEOUT_MS, maxOutputBytes: 8 * 1024 }
@@ -299,35 +339,25 @@ const runLegacySandboxMigration = async (
 ): Promise<UserSandboxMigrationResult> => {
   const dryRun = params.dryRun ?? true;
   const migrationStartedAt = Date.now();
-  const legacyDocs = await MongoLegacySandboxInstance.find({})
+  const rawLegacyDocs = await MongoLegacySandboxInstance.collection
+    .find({})
     .sort({ lastActiveAt: 1, _id: 1 })
-    .lean<LegacySandboxInstanceSchemaType[]>();
+    .toArray();
+  const legacyDocs = parseLegacySandboxInstances(rawLegacyDocs);
   const skillItems: ResolvedLegacySkill[] = [];
   const appItems: ResolvedLegacyApp[] = [];
-  const failures: UserSandboxMigrationFailure[] = [];
 
   for (const doc of legacyDocs) {
-    const sourceId = resolveLegacySourceId(doc);
-    if (isLegacySkillInstance(doc)) {
-      if (sourceId) skillItems.push({ doc, sourceId });
-      else failures.push({ sandboxId: doc.sandboxId, error: 'Legacy Skill sourceId is missing' });
+    if (doc.sourceType === ChatSourceTypeEnum.skillEdit) {
+      skillItems.push({ doc, sourceId: doc.sourceId });
       continue;
     }
-    if (doc.sourceType && doc.sourceType !== ChatSourceTypeEnum.app) {
-      failures.push({
-        sandboxId: doc.sandboxId,
-        error: `Unsupported Legacy Sandbox sourceType: ${doc.sourceType}`
-      });
-      continue;
-    }
-    if (sourceId && doc.userId && doc.chatId) {
-      appItems.push({ doc, sourceId, userId: doc.userId, chatId: doc.chatId });
-    } else {
-      failures.push({
-        sandboxId: doc.sandboxId,
-        error: 'Legacy App sourceId, userId or chatId is missing'
-      });
-    }
+    appItems.push({
+      doc,
+      sourceId: doc.sourceId,
+      userId: doc.userId,
+      chatId: doc.chatId
+    });
   }
 
   const appGroups = new Map<string, ResolvedLegacyApp[]>();
@@ -344,8 +374,8 @@ const runLegacySandboxMigration = async (
     migratedAppCount: 0,
     appGroupCount: appGroups.size,
     completedAppGroupCount: 0,
-    failedCount: failures.length,
-    failures
+    failedCount: 0,
+    failures: []
   };
   const trackCompleted = () =>
     recordMigrationTrack({
@@ -358,18 +388,6 @@ const runLegacySandboxMigration = async (
     });
 
   await recordMigrationTrack({ runId, phase: 'started', dryRun });
-  await Promise.all(
-    failures.map((failure) =>
-      recordMigrationTrack({
-        runId,
-        phase: 'failure',
-        dryRun,
-        sandboxId: failure.sandboxId,
-        step: 'validate_legacy_record',
-        error: failure.error
-      })
-    )
-  );
   if (dryRun) {
     await trackCompleted();
     return result;
@@ -452,11 +470,6 @@ const runLegacySandboxMigration = async (
           target,
           chatId: item.chatId
         });
-        if (targetState === 'old') {
-          await cleanupMigratedLegacyAppInstance(item.doc);
-          result.migratedAppCount += 1;
-          continue;
-        }
         const archiveSource = getS3SandboxSource();
         const archiveExists = await archiveSource.isWorkspaceArchiveExists({
           sandboxId: item.doc.sandboxId