feat(开发脚本): dev:all 支持 --clear-database 并提示本地库 schema 冲突

默认仍写死 --preserve-database（不改默认行为）；显式 --clear-database 时不再传它、逐字透传 dev.mjs 既有语义；根栈因 manual migration / Reordering table 失败时补一段可操作提示（打印库名与 data dir、两条出路、清库会丢数据的警告），提示文案抽成纯函数并补单测；文档补一句

scripts/dev-all.test.ts

@@ -10,10 +10,12 @@ import {
   agcDataDir,
   buildDevAllBaseEnvironment,
   buildDevAllEnvironment,
+  buildLocalSchemaConflictHint,
   buildManagedSpawnOptions,
   buildRootDevArgs,
   buildStartupSummary,
   isHttpReady,
+  isLocalSchemaConflictOutput,
   isSharedRootStackReady,
   renderStartupTable,
   runDevAll,
@@ -249,4 +251,58 @@ describe('dev:all 参数和共享开发栈合同', () => {
     expect(children).toHaveLength(2);
     expect(stopCalls).toEqual([children[1], children[0]]);
   });
+
+  test('默认仍固定保留 AGC 本地库（不改变默认行为）', () => {
+    const args = buildRootDevArgs(['--watch']);
+    expect(args).toContain('--preserve-database');
+    expect(args).not.toContain('--clear-database');
+  });
+
+  test('显式 --clear-database 时不再固定 --preserve-database，开关逐字透传给根栈', () => {
+    const args = buildRootDevArgs(['--clear-database']);
+    expect(args).not.toContain('--preserve-database');
+    expect(args.filter((argument) => argument === '--clear-database')).toHaveLength(
+      1,
+    );
+    expect(args).toEqual([
+      'run',
+      'dev',
+      '--',
+      '--database',
+      agcDatabase,
+      '--spacetime-data-dir',
+      'server-rs/.spacetimedb/ai-game-creator/data',
+      '--no-interactive',
+      '--clear-database',
+    ]);
+  });
+
+  test('识别本地库 schema 冲突的服务端输出', () => {
+    expect(isLocalSchemaConflictOutput('… needs manual migration')).toBe(true);
+    expect(
+      isLocalSchemaConflictOutput(
+        'Reordering table game_distribution_game requires a manual migration',
+      ),
+    ).toBe(true);
+    expect(
+      isLocalSchemaConflictOutput(
+        'Aborting publish due to required manual migration.',
+      ),
+    ).toBe(true);
+    expect(isLocalSchemaConflictOutput('Finished `dev` profile [unoptimized]')).toBe(
+      false,
+    );
+    expect(isLocalSchemaConflictOutput(undefined)).toBe(false);
+  });
+
+  test('本地库 schema 冲突提示含库名/data dir/两条出路/丢数据警告', () => {
+    const hint = buildLocalSchemaConflictHint();
+    expect(hint).toContain(agcDatabase);
+    expect(hint).toContain('server-rs/.spacetimedb/ai-game-creator/data');
+    expect(hint).toContain('npm run dev:all -- --clear-database');
+    expect(hint).toContain('不带 --preserve-database');
+    expect(hint).toContain('都会丢弃该本地库里的数据');
+    expect(hint).toContain('不是代码问题');
+    expect(hint).not.toContain('undefined');
+  });
 });