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

Author: DigHuang

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

@@ -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 记录复制到新表。

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 {
@@ -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 isLegacySkillInstance = (doc: LegacySandboxInstanceSchemaType) =>
-  doc.sourceType === ChatSourceTypeEnum.skillEdit || doc.type === SandboxTypeEnum.editDebug;
+    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}]`
+    );
+  }
+
+  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 记录。
@@ -299,35 +329,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 +364,8 @@ const runLegacySandboxMigration = async (
     migratedAppCount: 0,
     appGroupCount: appGroups.size,
     completedAppGroupCount: 0,
-    failedCount: failures.length,
-    failures
+    failedCount: 0,
+    failures: []
   };
   const trackCompleted = () =>
     recordMigrationTrack({
@@ -358,18 +378,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;

packages/service/core/ai/sandbox/infrastructure/instance/legacySchema.ts

@@ -6,35 +6,56 @@
 import { connectionMongo, getMongoModel } from '../../../../../common/mongo';
 import { SandboxStatusEnum, SandboxTypeEnum } from '@fastgpt/global/core/ai/sandbox/constants';
 import { ChatSourceTypeEnum } from '@fastgpt/global/core/chat/constants';
-import type {
-  SandboxInstanceSchemaType,
-  SandboxProviderType,
-  SandboxStorageType
+import {
+  SandboxLimitSchema,
+  SandboxMetadataSchema,
+  SandboxProviderSchema,
+  SandboxStorageSchema,
+  SharedSandboxStatusSchema
 } from '../../type';
+import z from 'zod';
 
 const { Schema } = connectionMongo;
 
 export const legacyCollectionName = 'agent_sandbox_instances';
 
-export type LegacySandboxInstanceSchemaType = {
-  _id: unknown;
-  provider: SandboxProviderType;
-  sandboxId: string;
-  appId?: string | null;
-  sourceType?: ChatSourceTypeEnum | null;
-  sourceId?: string | null;
-  userId?: string | null;
-  chatId?: string | null;
-  type?: SandboxTypeEnum | null;
-  status: SandboxInstanceSchemaType['status'];
-  lastActiveAt: Date;
-  createdAt?: Date;
-  limit?: SandboxInstanceSchemaType['limit'];
-  storage?: SandboxStorageType | null;
-  metadata?: NonNullable<SandboxInstanceSchemaType['metadata']> & {
-    skillId?: string;
-  };
-};
+const LegacySandboxMetadataSchema = SandboxMetadataSchema.extend({
+  skillId: z.never().optional()
+}).passthrough();
+
+const LegacySandboxCommonSchema = z
+  .object({
+    _id: z.unknown().refine((value) => value !== null && value !== undefined, {
+      message: '_id is required'
+    }),
+    provider: SandboxProviderSchema,
+    sandboxId: z.string().min(1),
+    sourceId: z.string().min(1),
+    status: SharedSandboxStatusSchema,
+    lastActiveAt: z.date(),
+    createdAt: z.date().optional(),
+    limit: SandboxLimitSchema.optional(),
+    storage: SandboxStorageSchema.nullish(),
+    metadata: LegacySandboxMetadataSchema.optional(),
+    appId: z.never().optional(),
+    type: z.never().optional()
+  })
+  .passthrough();
+
+/** beta6 归一化完成后，用户级 Sandbox 迁移允许读取的 Legacy 记录结构。 */
+export const LegacySandboxInstanceZodSchema = z.discriminatedUnion('sourceType', [
+  LegacySandboxCommonSchema.extend({
+    sourceType: z.literal(ChatSourceTypeEnum.app),
+    userId: z.string().min(1),
+    chatId: z.string().min(1)
+  }),
+  LegacySandboxCommonSchema.extend({
+    sourceType: z.literal(ChatSourceTypeEnum.skillEdit),
+    userId: z.string().nullish(),
+    chatId: z.string().nullish()
+  })
+]);
+export type LegacySandboxInstanceSchemaType = z.infer<typeof LegacySandboxInstanceZodSchema>;
 
 const LegacySandboxInstanceSchema = new Schema(
   {

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

@@ -132,7 +132,7 @@ describe('user-level sandbox migration', () => {
     expect(target.provider.execute).toHaveBeenCalledTimes(1);
   });
 
-  it('dry-run groups valid App records and reports invalid Legacy ownership', async () => {
+  it('dry-run groups valid App records and rejects an invalid Legacy structure', async () => {
     await MongoLegacySandboxInstance.collection.insertMany([
       {
         provider: 'opensandbox',
@@ -153,14 +153,6 @@ describe('user-level sandbox migration', () => {
         chatId: 'chat-2',
         status: 'stopped',
         lastActiveAt: new Date()
-      },
-      {
-        provider: 'opensandbox',
-        sandboxId: 'migration-test-invalid',
-        sourceType: ChatSourceTypeEnum.app,
-        sourceId: 'app-2',
-        status: 'stopped',
-        lastActiveAt: new Date()
       }
     ]);
 
@@ -169,31 +161,46 @@ describe('user-level sandbox migration', () => {
     expect(result.legacyAppCount).toBeGreaterThanOrEqual(2);
     expect(result.appGroupCount).toBeGreaterThanOrEqual(1);
     expect(result.migratedAppCount).toBe(0);
-    expect(result.failures).toContainEqual(
-      expect.objectContaining({ sandboxId: 'migration-test-invalid' })
-    );
+    expect(result.failures).toEqual([]);
 
     const migrationTracks = trackMocks.userSandboxMigration.mock.calls.map(([data]) => data);
-    expect(migrationTracks).toHaveLength(3);
+    expect(migrationTracks).toHaveLength(2);
     expect(migrationTracks[0]).toMatchObject({
       phase: 'started',
       dryRun: true
     });
     expect(Object.keys(migrationTracks[0]).sort()).toEqual(['dryRun', 'phase', 'runId']);
     expect(migrationTracks[1]).toMatchObject({
-      phase: 'failure',
-      step: 'validate_legacy_record',
-      sandboxId: 'migration-test-invalid'
-    });
-    expect(migrationTracks[2]).toMatchObject({
       phase: 'completed',
       dryRun: true,
       successCount: expect.any(Number),
       durationMs: expect.any(Number),
       failureCount: expect.any(Number)
     });
     expect(migrationTracks.some(({ phase }) => phase === 'progress')).toBe(false);
-    expect(migrationTracks[2].runId).toBe(migrationTracks[0].runId);
+    expect(migrationTracks[1].runId).toBe(migrationTracks[0].runId);
+
+    await MongoLegacySandboxInstance.collection.insertOne({
+      provider: 'opensandbox',
+      sandboxId: 'migration-test-invalid',
+      sourceType: ChatSourceTypeEnum.app,
+      sourceId: 'app-2',
+      status: 'stopped',
+      lastActiveAt: new Date()
+    });
+    trackMocks.userSandboxMigration.mockClear();
+
+    const error = await migrateLegacySandboxesToUserLevel({ dryRun: true }).catch(
+      (error: unknown) => error
+    );
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toContain(
+      'Legacy Sandbox preflight validation failed for 1 record(s)'
+    );
+    expect((error as Error).message).toContain('sandboxId=migration-test-invalid');
+    expect((error as Error).message).toContain('userId');
+    expect((error as Error).message).toContain('chatId');
+    expect(trackMocks.userSandboxMigration).not.toHaveBeenCalled();
   });
 
   it('keeps migration protection while normalized or raw Legacy App records remain', async () => {

packages/service/test/core/ai/sandbox/infrastructure/instance/model.test.ts

@@ -30,9 +30,6 @@ describe('MongoSandboxInstance model', () => {
 
     const doc = new MongoSandboxInstance(mockInstance);
     expect(doc.sandboxId).toBe(mockInstance.sandboxId);
-    expect(doc).not.toHaveProperty('appId');
-    expect(doc).not.toHaveProperty('chatId');
-    expect(doc).not.toHaveProperty('type');
     expect(doc.status).toBe('running');
     expect(doc?.provider).toBe('opensandbox');
   });

packages/service/test/core/ai/sandbox/infrastructure/instance/repository.test.ts

@@ -38,7 +38,7 @@ describe('sandbox instance repository', () => {
     await MongoSandboxInstance.deleteMany({ sandboxId: new RegExp(`^${prefix}`) });
   });
 
-  it('upserts one App record without persisting Chat-level fields', async () => {
+  it('upserts one App record per logical App user', async () => {
     const sourceId = `${prefix}app-${getNanoid()}`;
     const userId = `${prefix}user-${getNanoid()}`;
     const sandboxId = `${prefix}${getNanoid()}`;
@@ -61,9 +61,6 @@ describe('sandbox instance repository', () => {
 
     const stored = await MongoSandboxInstance.findOne({ sandboxId }).lean();
     expect(stored).toMatchObject({ sourceType: 'app', sourceId, userId, status: 'running' });
-    expect(stored).not.toHaveProperty('chatId');
-    expect(stored).not.toHaveProperty('appId');
-    expect(stored).not.toHaveProperty('type');
     expect(await MongoSandboxInstance.countDocuments({ sourceType: 'app', sourceId, userId })).toBe(
       1
     );

packages/service/test/core/workflow/dispatch/ai/agent/index.test.ts

@@ -457,7 +457,7 @@ describe('dispatchRunAgent user context', () => {
     expect(sandboxReadyBeforeLoop).toBe(true);
     const writeFiles = sandboxWriteFilesMock.mock.calls[0][0];
     expect(writeFiles.map((file: { path: string }) => file.path)).toEqual([
-      'user_files/current.pdf'
+      '/workspace/user_files/current.pdf'
     ]);
     const loopInput = runAgentLoopMock.mock.calls[0][0].input;
     expect(loopInput.systemPrompt).not.toContain('pwd: /workspace');