新增 Web 后台与 AGC 一键开发入口

新增 dev:all 跨平台编排共享后端、主站、后台与 AGC。

保持 npm run dev、npm run agc 及单模块入口行为不变。

补充参数、状态身份、进程退出收束测试。

同步本地开发运维文档、项目概览和决策记录。

scripts/dev-all.test.ts

@@ -0,0 +1,157 @@
+import { EventEmitter } from 'node:events';
+import { resolve } from 'node:path';
+
+import { describe, expect, test } from 'vitest';
+
+import {
+  agcDatabase,
+  agcDataDir,
+  buildDevAllEnvironment,
+  buildRootDevArgs,
+  isSharedRootStackReady,
+  runDevAll,
+  validateDevAllArgs,
+} from './dev-all.mjs';
+type FakeChild = EventEmitter & {
+  pid: number;
+  exitCode: number | null;
+  signalCode: string | null;
+};
+
+function makeReadyState(root = resolve('fixture-root')) {
+  const instanceId = 'dev-fixture';
+  const service = (status = 'running', url = 'http://127.0.0.1:1') => ({
+    repoRoot: root,
+    instanceId,
+    status,
+    url,
+  });
+
+  return {
+    command: 'all',
+    instanceId,
+    repoRoot: root,
+    database: agcDatabase,
+    spacetimeDataDir: agcDataDir,
+    services: {
+      spacetime: service('reused', 'http://127.0.0.1:3101'),
+      'api-server': service('running', 'http://127.0.0.1:8082'),
+      'bgfilter-worker': service('running', 'http://127.0.0.1:8083'),
+      web: service('running', 'http://127.0.0.1:3000'),
+      'admin-web': service('running', 'http://127.0.0.1:3102/admin/'),
+    },
+  };
+}
+
+describe('dev:all 参数和共享开发栈合同', () => {
+  test('根 dev 固定使用 AGC 配套数据库，并保留调用方选项', () => {
+    expect(buildRootDevArgs(['--watch', '--api-port', '9082'])).toEqual([
+      'run',
+      'dev',
+      '--',
+      '--database',
+      agcDatabase,
+      '--spacetime-data-dir',
+      'server-rs/.spacetimedb/ai-game-creator/data',
+      '--preserve-database',
+      '--no-interactive',
+      '--watch',
+      '--api-port',
+      '9082',
+    ]);
+  });
+
+  test('拒绝会破坏单后端拓扑的数据库和 data dir 覆盖', () => {
+    expect(() => validateDevAllArgs(['--database', 'other'])).toThrow(
+      '不能覆盖 --database 或 --spacetime-data-dir',
+    );
+    expect(() => validateDevAllArgs(['--database=other'])).toThrow(
+      '不能覆盖 --database 或 --spacetime-data-dir',
+    );
+    expect(() => validateDevAllArgs(['--spacetime-data-dir', 'other'])).toThrow(
+      '不能覆盖 --database 或 --spacetime-data-dir',
+    );
+    expect(() => validateDevAllArgs(['backend'])).toThrow('只接受 dev 选项');
+  });
+
+  test('预留 AGC Vite 端口并关闭 AGC 自带后台', () => {
+    const baseEnv = { AGC_DEV_ADMIN_WEB: '1' };
+    const env = buildDevAllEnvironment(baseEnv, 3080);
+
+    expect(env.GENARRATIVE_AGC_VITE_PORT).toBe('3080');
+    expect(env.AGC_DEV_ADMIN_WEB).toBe('0');
+    expect(baseEnv.AGC_DEV_ADMIN_WEB).toBe('1');
+  });
+
+  test('仅接受同一工作树、实例、数据库和 data dir 的完整栈', () => {
+    const root = resolve('fixture-root');
+    const ready = makeReadyState(root);
+
+    expect(
+      isSharedRootStackReady(ready, {
+        expectedRepoRoot: root,
+        expectedDatabase: agcDatabase,
+        expectedDataDir: agcDataDir,
+      }),
+    ).toBe(true);
+
+    const wrongInstance = structuredClone(ready);
+    wrongInstance.services.web.instanceId = 'other-instance';
+    expect(
+      isSharedRootStackReady(wrongInstance, {
+        expectedRepoRoot: root,
+        expectedDatabase: agcDatabase,
+        expectedDataDir: agcDataDir,
+      }),
+    ).toBe(false);
+
+    const incomplete = structuredClone(ready);
+    incomplete.services['admin-web'].status = 'idle';
+    expect(
+      isSharedRootStackReady(incomplete, {
+        expectedRepoRoot: root,
+        expectedDatabase: agcDatabase,
+        expectedDataDir: agcDataDir,
+      }),
+    ).toBe(false);
+  });
+
+  test('任一子进程退出时收束另一侧进程树', async () => {
+    const children: FakeChild[] = [];
+    const stopCalls: FakeChild[] = [];
+    let nextPid = 100;
+    const run = runDevAll([], {
+      resolveEndpoint: async () => ({
+        port: 3080,
+        url: 'http://127.0.0.1:3080/',
+      }),
+      spawnProcess: () => {
+        const child = new EventEmitter() as FakeChild;
+        child.pid = nextPid;
+        child.exitCode = null;
+        child.signalCode = null;
+        nextPid += 1;
+        children.push(child);
+        if (children.length === 2) {
+          queueMicrotask(() => {
+            child.exitCode = 1;
+            child.emit('exit', 1, null);
+          });
+        }
+        return child;
+      },
+      waitForRoot: async () => ({}),
+      stopProcessTree: async (child) => {
+        stopCalls.push(child);
+        if (child?.exitCode == null) {
+          child.exitCode = 0;
+          child.emit('exit', 0, null);
+        }
+      },
+    });
+
+    await expect(run).resolves.toBe(1);
+    expect(children).toHaveLength(2);
+    expect(stopCalls).toEqual([children[1], children[0]]);
+  });
+});