修复AI游戏创作启动评审问题

将本地发布身份改为按SpacetimeDB数据目录持久化并兼容迁移旧记录

为开发栈状态补充专用数据目录并拒绝复用旧共享后端

统一处理子进程启动错误、启动期信号和进程组清理

补充身份、后端复用与子进程生命周期回归测试及文档

scripts/dev.mjs

@@ -383,10 +383,11 @@ function buildDevStackSnapshot(runner, updatedAt = new Date().toISOString()) {
   }
 
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     command: runner.command ?? 'all',
     repoRoot,
     database: runner.options.database,
+    spacetimeDataDir: resolve(runner.options.spacetimeDataDir),
     watch: Boolean(runner.options.watch),
     updatedAt,
     services,
@@ -924,7 +925,7 @@ function readLinuxApiServerProcessSnapshot(pid) {
     if (
       error?.code === 'ENOENT' ||
       error?.code === 'EACCES' ||
-      error?.code === 'EPERM'  ||
+      error?.code === 'EPERM' ||
       error?.code === 'ESRCH'
     ) {
       return null;
@@ -1124,7 +1125,11 @@ class DevRunner {
     this.command = command;
     ensureRequiredFiles(command);
     requireCommand('node');
-    if (command === 'api-server' || command === 'all' || command === 'backend') {
+    if (
+      command === 'api-server' ||
+      command === 'all' ||
+      command === 'backend'
+    ) {
       requireCommand('cargo');
     }
     if (
@@ -1319,7 +1324,11 @@ class DevRunner {
       }
     }
 
-    if (command === 'all' || command === 'backend' || command === 'api-server') {
+    if (
+      command === 'all' ||
+      command === 'backend' ||
+      command === 'api-server'
+    ) {
       portConfig.api = {
         host: options.apiHost,
         preferredPort: options.apiPort,
@@ -2490,10 +2499,85 @@ function normalizeSpacetimeServerForIdentity(serverUrl) {
   return url.href.replace(/\/$/u, '');
 }
 
-function resolveLocalSpacetimeApiIdentityPath(dataDir, serverUrl) {
-  const normalizedServer = normalizeSpacetimeServerForIdentity(serverUrl);
-  const serverKey = createHash('sha256').update(normalizedServer).digest('hex');
-  return resolve(dataDir, 'dev-api-identities', `${serverKey}.json`);
+function resolveLocalSpacetimeApiIdentityPath(dataDir) {
+  return resolve(dataDir, 'dev-api-identities', 'local-node.json');
+}
+
+function readLocalSpacetimeApiIdentityRecord(identityPath, expected = {}) {
+  const stat = lstatSync(identityPath);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new Error('记录不是普通文件');
+  }
+  chmodSync(identityPath, 0o600);
+  const payload = JSON.parse(readFileSync(identityPath, 'utf8'));
+  const identity =
+    typeof payload.identity === 'string' ? payload.identity.trim() : '';
+  const token = typeof payload.token === 'string' ? payload.token.trim() : '';
+  if (!identity || !token) {
+    throw new Error('记录缺少 identity 或 token');
+  }
+
+  if (payload.schemaVersion === 2 && payload.scope === 'local-data-dir') {
+    return { identity, token };
+  }
+  if (
+    expected.allowLegacy &&
+    payload.schemaVersion === 1 &&
+    typeof payload.server === 'string' &&
+    isLoopbackSpacetimeServer(payload.server)
+  ) {
+    return { identity, token };
+  }
+  throw new Error('记录格式或 data dir 作用域不匹配');
+}
+
+function migrateLegacyLocalSpacetimeApiIdentity(dataDir) {
+  const identityDir = resolve(dataDir, 'dev-api-identities');
+  if (!existsSync(identityDir)) {
+    return null;
+  }
+
+  const candidates = [];
+  for (const entry of readdirSync(identityDir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) {
+      continue;
+    }
+    const candidatePath = resolve(identityDir, entry.name);
+    if (candidatePath === resolveLocalSpacetimeApiIdentityPath(dataDir)) {
+      continue;
+    }
+    try {
+      candidates.push(
+        readLocalSpacetimeApiIdentityRecord(candidatePath, {
+          allowLegacy: true,
+        }),
+      );
+    } catch {
+      // 无效或非本地旧记录不参与迁移。
+    }
+  }
+
+  const uniqueCandidates = new Map(
+    candidates.map((candidate) => [
+      `${candidate.identity}\n${candidate.token}`,
+      candidate,
+    ]),
+  );
+  if (uniqueCandidates.size === 0) {
+    return null;
+  }
+  if (uniqueCandidates.size > 1) {
+    throw new Error(
+      '同一 SpacetimeDB data dir 下发现多个旧 API identity，无法安全判断数据库 owner；请保留正确 owner 记录后重试',
+    );
+  }
+
+  const [identity] = uniqueCandidates.values();
+  writeLocalSpacetimeApiIdentity({ dataDir, ...identity });
+  console.log(
+    '[dev:spacetime] 已将旧端口作用域 API identity 迁移到 data dir 作用域',
+  );
+  return identity;
 }
 
 function resolveLocalSpacetimeRuntimeServiceBootstrapSecretPath(
@@ -2643,37 +2727,13 @@ function readLocalSpacetimeApiIdentity({ dataDir, serverUrl }) {
     return null;
   }
 
-  const normalizedServer = normalizeSpacetimeServerForIdentity(serverUrl);
-  const identityPath = resolveLocalSpacetimeApiIdentityPath(
-    dataDir,
-    normalizedServer,
-  );
+  const identityPath = resolveLocalSpacetimeApiIdentityPath(dataDir);
   if (!existsSync(identityPath)) {
-    return null;
+    return migrateLegacyLocalSpacetimeApiIdentity(dataDir);
   }
 
   try {
-    const stat = lstatSync(identityPath);
-    if (!stat.isFile() || stat.isSymbolicLink()) {
-      throw new Error('记录不是普通文件');
-    }
-    chmodSync(identityPath, 0o600);
-    const payload = JSON.parse(readFileSync(identityPath, 'utf8'));
-    if (
-      payload.schemaVersion !== 1 ||
-      payload.server !== normalizedServer ||
-      typeof payload.identity !== 'string' ||
-      !payload.identity.trim() ||
-      typeof payload.token !== 'string' ||
-      !payload.token.trim()
-    ) {
-      throw new Error('记录格式或 server 绑定不匹配');
-    }
-
-    return {
-      identity: payload.identity.trim(),
-      token: payload.token.trim(),
-    };
+    return readLocalSpacetimeApiIdentityRecord(identityPath);
   } catch (error) {
     console.warn(
       `[dev:spacetime] 本地 API identity 记录不可用，将重新创建: ${error.message}`,
@@ -2682,17 +2742,8 @@ function readLocalSpacetimeApiIdentity({ dataDir, serverUrl }) {
   }
 }
 
-function writeLocalSpacetimeApiIdentity({
-  dataDir,
-  serverUrl,
-  identity,
-  token,
-}) {
-  const normalizedServer = normalizeSpacetimeServerForIdentity(serverUrl);
-  const identityPath = resolveLocalSpacetimeApiIdentityPath(
-    dataDir,
-    normalizedServer,
-  );
+function writeLocalSpacetimeApiIdentity({ dataDir, identity, token }) {
+  const identityPath = resolveLocalSpacetimeApiIdentityPath(dataDir);
   const tempPath = `${identityPath}.${process.pid}.${randomHex(8)}.tmp`;
   ensureParentDir(identityPath);
 
@@ -2700,8 +2751,8 @@ function writeLocalSpacetimeApiIdentity({
     writeFileSync(
       tempPath,
       `${JSON.stringify({
-        schemaVersion: 1,
-        server: normalizedServer,
+        schemaVersion: 2,
+        scope: 'local-data-dir',
         identity,
         token,
       })}\n`,