@allbluecn/web-app 0.22.4 → 0.23.1

package/src/server/ai-gateway/sandbox/__tests__/harness-sandbox.test.ts

@@ -64,6 +64,18 @@ vi.mock("@allbluecn/database", () => ({
 
 import { InMemoryRunStore } from "@tanstack/ai"
 import { InMemoryLockStore } from "@tanstack/ai/locks"
+import {
+  InMemorySandboxCheckpointStore,
+  SandboxCheckpointConflictError,
+  SandboxCheckpointDuplicateIdError,
+  SandboxCheckpointInvalidEntryError,
+  SandboxCheckpointInvalidIdError,
+  SandboxCheckpointNotHeadError,
+  SandboxCheckpointParentMismatchError,
+  SandboxCheckpointWriterConflictError,
+  SandboxCheckpointWriterLostError,
+  type SandboxCheckpoint,
+} from "@tanstack/ai-sandbox"
 import { buildSandboxMiddleware } from "../harness-sandbox"
 
 const RUNS = new InMemoryRunStore()
@@ -362,14 +374,7 @@ describe("snapshots messages.loadThread 与 checkpoint store（审计 A3x-2）",
   function snapshotStoresWithCheckpoints() {
     return (mocks.withSandbox.mock.calls[0][1] as {
       snapshots?: {
-        checkpoints?: {
-          get: (id: string) => Promise<unknown>
-          list: (threadId: string) => Promise<unknown[]>
-          getHead: (threadId: string) => Promise<string | null>
-          append: (input: { checkpoint: unknown; writer: { threadId: string } }) => Promise<{ headId: string }>
-          deleteHead: (input: { threadId: string; checkpointId: string }) => Promise<void>
-          acquireWriter: (threadId: string) => Promise<{ ownerToken: string; fence: number }>
-        }
+        checkpoints?: InMemorySandboxCheckpointStore
         persistence?: { stores?: { messages?: { loadThread: (threadId: string) => Promise<unknown[]> } } }
       }
     }).snapshots!
@@ -409,56 +414,262 @@ describe("snapshots messages.loadThread 与 checkpoint store（审计 A3x-2）",
       expect.objectContaining({ where: { threadId: "thread-1" } }),
     )
   })
+})
+
+/**
+ * 官方 InMemorySandboxCheckpointStore 语义（任务 14：替换自建 99 行占位）。
+ *
+ * 占位版吞掉的官方错误语义在此逐条锁定：expectedHead 乐观并发（STALE_HEAD）、
+ * 重复 id、parent 链路一致、写者租约（conflict / lost）、deleteHead 非 head、
+ * id/entry 校验、blob 引用计数。checkpoint store 实例随 buildSandboxMiddleware
+ * 每次新建，用例间天然隔离；占位版的 200 条 FIFO 淘汰随占位一起移除——官方实现
+ * 不设上限，增长由 thread 生命周期（keepAlive 30m reap）约束。
+ */
+describe("官方 InMemorySandboxCheckpointStore 语义（任务 14）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.unstubAllEnvs()
+    delete process.env.DEPLOY_TARGET
+    mocks.resolveSandboxProvider.mockResolvedValue({ provider: { name: "mock" } })
+    mocks.defineSandbox.mockImplementation((config: unknown) => config)
+    mocks.prismaInstanceStore.mockReturnValue({ store: "prisma" })
+    mocks.pgLockStore.mockReturnValue({ lock: "pg" })
+    mocks.sandboxPolicyFor.mockImplementation((level: string) => ({ policy: level }))
+    mocks.withSandbox.mockImplementation((_sandbox: unknown, options: unknown) => options)
+  })
+
+  function store(): InMemorySandboxCheckpointStore {
+    return (mocks.withSandbox.mock.calls[0][1] as {
+      snapshots?: { checkpoints?: InMemorySandboxCheckpointStore }
+    }).snapshots!.checkpoints!
+  }
+
+  const HEX64 = "a".repeat(64)
+
+  function checkpoint(overrides: {
+    id: string
+    threadId: string
+    parentCheckpointId?: string | null
+    createdAt?: number
+    files?: SandboxCheckpoint["files"]
+  }): SandboxCheckpoint {
+    return {
+      id: overrides.id,
+      threadId: overrides.threadId,
+      parentCheckpointId: overrides.parentCheckpointId ?? null,
+      createdAt: overrides.createdAt ?? 1_000,
+      reason: "automatic",
+      files: overrides.files ?? [],
+      conversation: [],
+      artifacts: [],
+    }
+  }
+
+  /** 以合法租约把 checkpoint 追加为当前 head（parent/expectedHead 取实时 head），成功后释放租约。 */
+  async function appendAsHead(
+    s: InMemorySandboxCheckpointStore,
+    id: string,
+    threadId: string,
+    createdAt?: number,
+  ): Promise<string> {
+    const writer = await s.acquireWriter(threadId)
+    const parent = await s.getHead(threadId)
+    const { headId } = await s.append({
+      checkpoint: checkpoint({ id, threadId, createdAt, parentCheckpointId: parent }),
+      expectedHeadId: parent,
+      writer,
+    })
+    await writer.release()
+    return headId
+  }
+
+  it("装配的是官方 InMemorySandboxCheckpointStore 实例（占位实现已移除）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    expect(store()).toBeInstanceOf(InMemorySandboxCheckpointStore)
+  })
+
+  it("append → getHead/get 回放；list 按 createdAt 排序；deleteHead 真删并回退 head 到 parent", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+
+    await appendAsHead(s, "cp-1", "t-1")
+    await appendAsHead(s, "cp-2", "t-1", 2_000)
+    expect(await s.getHead("t-1")).toBe("cp-2")
+
+    const listed = await s.list("t-1")
+    expect(listed.map((c) => c.id)).toEqual(["cp-1", "cp-2"])
+
+    const writer = await s.acquireWriter("t-1")
+    await s.deleteHead({ threadId: "t-1", checkpointId: "cp-2", writer })
+    expect(await s.get("cp-2")).toBeNull()
+    // head 回退到被删 checkpoint 的 parent（cp-1），而非清空——与 append 链式 parent 对齐
+    expect(await s.getHead("t-1")).toBe("cp-1")
+    expect(await s.get("cp-1")).toEqual(checkpoint({ id: "cp-1", threadId: "t-1" }))
+  })
 
-  it("checkpoint store：append 后 getHead 可回放，deleteHead 真删（非 no-op）", async () => {
+  it("append expectedHead 过期 → SandboxCheckpointConflictError（占位版吞掉的 STALE_HEAD 语义）", async () => {
     await buildSandboxMiddleware(baseParams())
-    const cp = snapshotStoresWithCheckpoints().checkpoints!
+    const s = store()
+    await appendAsHead(s, "cp-1", "t-1")
+    const writer = await s.acquireWriter("t-1")
+
+    await expect(
+      s.append({
+        checkpoint: checkpoint({ id: "cp-2", threadId: "t-1", parentCheckpointId: "stale" }),
+        expectedHeadId: "stale",
+        writer,
+      }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointConflictError)
+  })
 
-    const { headId } = await cp.append({ checkpoint: { n: 1 }, writer: { threadId: "t-1" } })
-    expect(await cp.getHead("t-1")).toBe(headId)
-    expect(await cp.get(headId)).toEqual({ n: 1 })
+  it("append 重复 id → SandboxCheckpointDuplicateIdError（先于 head 校验拦截）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+    await appendAsHead(s, "cp-1", "t-1")
+    const writer = await s.acquireWriter("t-1")
+
+    await expect(
+      s.append({
+        checkpoint: checkpoint({ id: "cp-1", threadId: "t-1", parentCheckpointId: "cp-1" }),
+        expectedHeadId: "cp-1",
+        writer,
+      }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointDuplicateIdError)
+  })
 
-    await cp.deleteHead({ threadId: "t-1", checkpointId: headId })
-    expect(await cp.getHead("t-1")).toBeNull()
-    expect(await cp.get(headId)).toBeNull()
+  it("append parent 与 expectedHead 不一致 → SandboxCheckpointParentMismatchError", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+    await appendAsHead(s, "cp-1", "t-1")
+    const writer = await s.acquireWriter("t-1")
+
+    // expectedHead 与真实 head 一致，但 checkpoint.parent 指向别处 → 链路断裂即拒
+    await expect(
+      s.append({
+        checkpoint: checkpoint({ id: "cp-2", threadId: "t-1", parentCheckpointId: null }),
+        expectedHeadId: "cp-1",
+        writer,
+      }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointParentMismatchError)
   })
 
-  it("checkpoint store：deleteHead 仅当 checkpointId 是当前 head 才删（防误删新 head）", async () => {
+  it("append 未持有效写者租约 → SandboxCheckpointWriterLostError（占位版完全忽略 writer）", async () => {
     await buildSandboxMiddleware(baseParams())
-    const cp = snapshotStoresWithCheckpoints().checkpoints!
+    const s = store()
+    await appendAsHead(s, "cp-1", "t-1")
+
+    await expect(
+      s.append({
+        checkpoint: checkpoint({ id: "cp-2", threadId: "t-1", parentCheckpointId: "cp-1" }),
+        expectedHeadId: "cp-1",
+        // 伪造 writer（从未 acquire）：ownerToken/fence 均不匹配
+        writer: { threadId: "t-1", ownerToken: "bogus", fence: 999 },
+      }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointWriterLostError)
+  })
 
-    const first = await cp.append({ checkpoint: { n: 1 }, writer: { threadId: "t-2" } })
-    const second = await cp.append({ checkpoint: { n: 2 }, writer: { threadId: "t-2" } })
+  it("release 后 renew 抛 WriterLostError（租约真正失效，占位版 renew 恒成功）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+    const writer = await s.acquireWriter("t-1")
+    await writer.release()
 
-    // 用旧 head 调 deleteHead → 新 head 不受影响
-    await cp.deleteHead({ threadId: "t-2", checkpointId: first.headId })
-    expect(await cp.getHead("t-2")).toBe(second.headId)
+    await expect(writer.renew()).rejects.toBeInstanceOf(SandboxCheckpointWriterLostError)
   })
 
-  it("checkpoint store：ownerToken 唯一（randomUUID）且 fence 单调递增（写者栅栏生效）", async () => {
+  it("并发 acquireWriter → WriterConflictError；release 后可再取且 ownerToken 唯一 fence 单调", async () => {
     await buildSandboxMiddleware(baseParams())
-    const cp = snapshotStoresWithCheckpoints().checkpoints!
+    const s = store()
 
-    const w1 = await cp.acquireWriter("t-3")
-    const w2 = await cp.acquireWriter("t-3")
-    expect(w1.ownerToken).not.toBe(w2.ownerToken)
+    const w1 = await s.acquireWriter("t-1")
+    await expect(s.acquireWriter("t-1")).rejects.toBeInstanceOf(
+      SandboxCheckpointWriterConflictError,
+    )
+
+    await w1.release()
+    const w2 = await s.acquireWriter("t-1")
+    expect(w2.ownerToken).not.toBe(w1.ownerToken)
     expect(w2.fence).toBeGreaterThan(w1.fence)
   })
 
-  it("checkpoint store：超过 200 条 FIFO 淘汰（长生命周期进程内存不失控）", async () => {
+  it("deleteHead 非 head → SandboxCheckpointNotHeadError（占位版静默 no-op 的语义收紧）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+    const first = await appendAsHead(s, "cp-1", "t-1")
+    await appendAsHead(s, "cp-2", "t-1", 2_000)
+    const writer = await s.acquireWriter("t-1")
+
+    // 用旧 head 调 deleteHead → 抛 NotHeadError，新 head 不受影响
+    await expect(
+      s.deleteHead({ threadId: "t-1", checkpointId: first, writer }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointNotHeadError)
+    expect(await s.getHead("t-1")).toBe("cp-2")
+  })
+
+  it("无效 checkpoint id → SandboxCheckpointInvalidIdError（get/append 同门槛）", async () => {
     await buildSandboxMiddleware(baseParams())
-    const cp = snapshotStoresWithCheckpoints().checkpoints!
+    const s = store()
+
+    await expect(s.get("")).rejects.toBeInstanceOf(SandboxCheckpointInvalidIdError)
+    const writer = await s.acquireWriter("t-1")
+    await expect(
+      s.append({
+        checkpoint: checkpoint({ id: "", threadId: "t-1" }),
+        expectedHeadId: null,
+        writer,
+      }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointInvalidIdError)
+  })
 
-    const headIds: string[] = []
-    for (let i = 0; i < 210; i++) {
-      const r = await cp.append({ checkpoint: { i }, writer: { threadId: "t-fifo" } })
-      headIds.push(r.headId)
-    }
-    // 最老的 10 条被淘汰
-    expect(await cp.get(headIds[0])).toBeNull()
-    expect(await cp.get(headIds[9])).toBeNull()
-    // 新条目仍在
-    expect(await cp.get(headIds[209])).toEqual({ i: 209 })
-    expect(await cp.getHead("t-fifo")).toBe(headIds[209])
+  it("files blobKey 不符内容寻址格式 → SandboxCheckpointInvalidEntryError（占位版来者不拒）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+    const writer = await s.acquireWriter("t-1")
+
+    await expect(
+      s.append({
+        checkpoint: checkpoint({
+          id: "cp-bad",
+          threadId: "t-1",
+          files: [{ path: "src/a.txt", kind: "file", blobKey: "run-no-artifact", size: 3 }],
+        }),
+        expectedHeadId: null,
+        writer,
+      }),
+    ).rejects.toBeInstanceOf(SandboxCheckpointInvalidEntryError)
+  })
+
+  it("listBlobReferences 按 blobKey 计数引用，deleteHead 递减（blob GC 依据）", async () => {
+    await buildSandboxMiddleware(baseParams())
+    const s = store()
+    const blobKey = `sandbox-files/sha256/${HEX64}`
+    const files: SandboxCheckpoint["files"] = [
+      { path: "src/a.txt", kind: "file", blobKey, size: 3 },
+    ]
+
+    const w1 = await s.acquireWriter("t-1")
+    await s.append({
+      checkpoint: checkpoint({ id: "cp-1", threadId: "t-1", files }),
+      expectedHeadId: null,
+      writer: w1,
+    })
+    await w1.release()
+    const w2 = await s.acquireWriter("t-1")
+    await s.append({
+      checkpoint: checkpoint({
+        id: "cp-2",
+        threadId: "t-1",
+        parentCheckpointId: "cp-1",
+        createdAt: 2_000,
+        files,
+      }),
+      expectedHeadId: "cp-1",
+      writer: w2,
+    })
+
+    expect(await s.listBlobReferences()).toEqual([{ key: blobKey, references: 2 }])
+
+    await s.deleteHead({ threadId: "t-1", checkpointId: "cp-2", writer: w2 })
+    expect(await s.listBlobReferences()).toEqual([{ key: blobKey, references: 1 }])
   })
 })

package/src/server/ai-gateway/sandbox/harness-sandbox.ts

@@ -19,11 +19,11 @@ import type { RunStore, AnyTextAdapter } from "@tanstack/ai"
 import {
   defineSandbox,
   withSandbox,
+  InMemorySandboxCheckpointStore,
   type WorkspaceDefinition,
   createSecrets,
   localSource,
 } from "@tanstack/ai-sandbox"
-import { randomUUID } from "node:crypto"
 import { InMemoryLockStore } from "@tanstack/ai/locks"
 import type { PgStreamDurabilityFactory } from "../durability/pg-stream"
 import { pgLockStore } from "../locks/pg-lock"
@@ -39,70 +39,6 @@ import {
 import { codexText, CODEX_MODELS } from "@tanstack/ai-codex"
 import { acpCompatibleText } from "@tanstack/ai-acp"
 import { opencodeText } from "@tanstack/ai-opencode"
-import type { SandboxCheckpointStore } from "@tanstack/ai-sandbox"
-
-/**
- * 内存 checkpoint store 骨架——任务 14 占位，后续接 DB 持久化。
- *
- * 占位不等于放任（审计 2026-10-25 🟡）：append 只增不删会让长生命周期进程
- * 内存持续增长，故设条目上限 FIFO 淘汰；deleteHead 真删 head 指向条目；
- * ownerToken 用 randomUUID（Date.now() 同毫秒并发即重复）；fence 单调递增
- * （恒 0 使写者栅栏失效）。
- */
-const MEMORY_CHECKPOINT_MAX_ENTRIES = 200
-
-function memoryCheckpointStore(): SandboxCheckpointStore {
-  const checkpoints = new Map<string, unknown>()
-  const heads = new Map<string, string>()
-  let fenceCounter = 0
-  return {
-    get: async (_id: string) => (checkpoints.get(_id) ?? null) as never,
-    list: async (threadId: string) => {
-      const prefix = `thread:${threadId}:`
-      return Array.from(checkpoints.entries())
-        .filter(([id]) => id.startsWith(prefix))
-        .map(([, v]) => v as never)
-    },
-    getHead: async (threadId: string) => heads.get(`thread:${threadId}`) ?? null,
-    append: async (input: any) => {
-      const tid = input?.writer?.threadId ?? "unknown"
-      const id = `thread:${tid}:${Date.now()}-${randomUUID().slice(0, 8)}`
-      checkpoints.set(id, input.checkpoint)
-      heads.set(`thread:${tid}`, id)
-      // FIFO 淘汰：Map 迭代按插入序，删到上限以内（head 指向的条目若被淘汰，
-      // getHead 返回的 id 在 get 中自然落空——占位实现的已知边界）。
-      while (checkpoints.size > MEMORY_CHECKPOINT_MAX_ENTRIES) {
-        const oldest = checkpoints.keys().next().value
-        if (oldest === undefined) break
-        checkpoints.delete(oldest)
-      }
-      return { headId: id } as any
-    },
-    deleteHead: async (input: {
-      threadId: string
-      checkpointId: string
-    }) => {
-      // 仅当 input.checkpointId 仍是当前 head 时才删（防误删新 head）。
-      // heads 的 key 与 getHead 同前缀（`thread:<threadId>`），value 是完整
-      // checkpoint id（`thread:<threadId>:<ts>-<uuid>`）。
-      const headKey = `thread:${input.threadId}`
-      const headId = heads.get(headKey)
-      if (headId === undefined || headId !== input.checkpointId) return
-      heads.delete(headKey)
-      checkpoints.delete(headId)
-    },
-    acquireWriter: async (threadId: string) => ({
-      threadId,
-      expiresAt: Date.now() + 60_000,
-      renewAfterMs: 30_000,
-      renew: () => Promise.resolve({ expiresAt: Date.now() + 60_000 } as any),
-      ownerToken: `token-${threadId}-${randomUUID()}`,
-      fence: ++fenceCounter,
-      release: () => Promise.resolve(),
-    }) as any,
-    listBlobReferences: async () => [],
-  } as never
-}
 
 /** 快照恢复的消息上限——与 persistence/message-store.ts 的 LOAD_THREAD_MAX_MESSAGES 同口径。 */
 const SANDBOX_LOAD_THREAD_MAX_MESSAGES = 100
@@ -239,9 +175,12 @@ export async function buildSandboxMiddleware(
           },
         }
       : {}),
-    // snapshots.blobs（artifacts + blobs store）P3b 任务 14 接线收口
+    // snapshots.blobs（artifacts + blobs store）P3b 任务 14 接线收口。
+    // checkpoint store 用官方 InMemorySandboxCheckpointStore（任务 14 替换自建
+    // 占位）：完整写者租约 + expectedHead 乐观并发 + 9 个错误类语义；后续接
+    // DB 持久化时同接口平移。
     snapshots: {
-      checkpoints: memoryCheckpointStore(),
+      checkpoints: new InMemorySandboxCheckpointStore(),
       persistence: {
         stores: {
           messages: {

package/src/server/ai-gateway/source-mode.ts

@@ -18,6 +18,7 @@
 import { prisma } from '@allbluecn/database'
 import type { AiSourceMode } from '@allbluecn/kernel'
 import { AI_SOURCE_MODES } from '@allbluecn/kernel'
+import { GUEST_USER_ID } from '../desktop-guest'
 import { getPorts } from './runtime'
 
 export interface SourceModeSubject {
@@ -25,16 +26,30 @@ export interface SourceModeSubject {
   isGuest: boolean
 }
 
+/** guest 隔离键：aiSourceMode:local-guest（GUEST_USER_ID 统一从 desktop-guest 引用） */
+const GUEST_SOURCE_MODE_KEY = `aiSourceMode:${GUEST_USER_ID}`
+/** 旧全局键：仅迁移读，不回写、不删除 */
+const LEGACY_SOURCE_MODE_KEY = 'aiSourceMode'
+
 /** 读用户当前模型来源模式；null = 未选择（按 byok 现状链路由） */
 export async function resolveSourceMode(subject: SourceModeSubject): Promise<AiSourceMode | null> {
   try {
     if (subject.isGuest) {
-      // ⚠ desktop-only 前置条件（审计 🟡）：aiSourceMode 是全局共享的
-      // desktopSetting key，不按用户隔离。仅 desktop 单 guest（GUEST_USER_ID）
-      // 场景成立；若未来 web 侧出现多 guest/多实例共享该 key，任意 guest 的
-      // 写入会覆盖所有 guest——届时必须给 key 加实例/用户维度后缀。
-      const row = await prisma.desktopSetting.findUnique({ where: { key: 'aiSourceMode' } })
-      const raw = row?.value
+      // guest 键隔离：读写均走 aiSourceMode:${GUEST_USER_ID}，不再共享全局键，
+      // 多 guest/多实例写入互不覆盖。旧全局键仅做迁移读：新键缺失时回落旧值，
+      // 下次写入自然 upsert 落新键；旧键保留不删（桌面单机幂等，无害残留）。
+      const row = await prisma.desktopSetting.findUnique({ where: { key: GUEST_SOURCE_MODE_KEY } })
+      if (!row) {
+        const legacy = await prisma.desktopSetting.findUnique({
+          where: { key: LEGACY_SOURCE_MODE_KEY },
+        })
+        const legacyRaw = legacy?.value
+        if (typeof legacyRaw === 'string' && AI_SOURCE_MODES.includes(legacyRaw as AiSourceMode)) {
+          return legacyRaw as AiSourceMode
+        }
+        return null
+      }
+      const raw = row.value
       if (typeof raw !== 'string' || !AI_SOURCE_MODES.includes(raw as AiSourceMode)) return null
       return raw as AiSourceMode
     }
@@ -55,9 +70,10 @@ export async function resolveSourceMode(subject: SourceModeSubject): Promise<AiS
 
 export async function setSourceMode(subject: SourceModeSubject, mode: AiSourceMode): Promise<void> {
   if (subject.isGuest) {
+    // 写隔离键；旧键不删除（迁移读后首次写入自然落新键）
     await prisma.desktopSetting.upsert({
-      where: { key: 'aiSourceMode' },
-      create: { key: 'aiSourceMode', value: mode },
+      where: { key: GUEST_SOURCE_MODE_KEY },
+      create: { key: GUEST_SOURCE_MODE_KEY, value: mode },
       update: { value: mode },
     })
     return

package/src/server/desktop-bootstrap.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 桌面首启本地影子用户（本地优先改造 P1，规格 §3.1 懒 seed）。
+// 背景：桌面端（Electron + PGlite）免登录发放 guest 会话（desktop-guest.ts），但
+// users 表无行 → assertOwned / assertProjectMembership / requireUserInDb 与各表
+// FK 在 guest 写入时全部失败。解法：首启为 local-guest 建真实影子行（users 一行
+// + 内置「独立需求」项目 + owner member），业务链零改动自然通过。
+// 挂点：serverFns/auth/session.ts getSessionFn 桌面 guest 分支（失败仅 warn 不
+// 阻断会话发放——首启体验优先）。
+
+import { randomUUID } from 'node:crypto'
+import { prisma } from '@allbluecn/database'
+import { ensureBuiltinIndependentProject } from '@/server/builtin-project'
+import {
+  GUEST_EMAIL,
+  GUEST_USER_ID,
+  GUEST_USERNAME,
+  isDesktopServer,
+} from '@/server/desktop-guest'
+import { defaultAvatarConfig, presetBgColors } from '@/lib/avatar/avatar-config'
+
+// 与 desktop-guest.ts 的 guestBgColor 同式（未导出，为不扩散导出面在此重复；两处
+// seed 同为 GUEST_USERNAME，影子行与内存 guest 会话的头像底色恒一致）
+function shadowBgColor(seed: string): string {
+  const sum = [...seed].reduce((acc, ch) => acc + ch.charCodeAt(0), 0)
+  return presetBgColors[sum % presetBgColors.length] as string
+}
+
+/**
+ * 幂等落库本地影子用户（id=local-guest）并复用内置独立项目，返回 GUEST_USER_ID。
+ *
+ * - 非 desktop 部署：防御性早退不触库（正常调用方只在桌面分支触达）。
+ * - upsert 的 update 分支留空：不覆盖用户后续改名/改头像（幂等）。
+ * - password 为随机占位（非 bcrypt 哈希）：guest 不走密码登录，凭据比对必失败，
+ *   杜绝影子行被密码登录复用。
+ * - 头像三件（avatarConfig/bgShape/bgColor）与 buildGuestSession 对齐，经 DB 读
+ *   取用户的路径（成员列表等）与内存 guest 会话渲染一致。
+ */
+export async function ensureLocalShadowUser(): Promise<string> {
+  if (!isDesktopServer()) return GUEST_USER_ID
+
+  await prisma.user.upsert({
+    where: { id: GUEST_USER_ID },
+    create: {
+      id: GUEST_USER_ID,
+      email: GUEST_EMAIL,
+      username: GUEST_USERNAME,
+      password: randomUUID(),
+      avatarConfig: defaultAvatarConfig as object,
+      bgShape: 'square',
+      bgColor: shadowBgColor(GUEST_USERNAME),
+      status: 'ACTIVE',
+    },
+    update: {},
+  })
+
+  await ensureBuiltinIndependentProject(GUEST_USER_ID)
+  return GUEST_USER_ID
+}

package/src/server/lib/__tests__/rate-limit.test.ts

@@ -31,7 +31,6 @@ describe('限流注册表', () => {
     expect(AI_RATE_LIMIT.mediaVideo.max).toBeGreaterThan(0)
     expect(AI_RATE_LIMIT.mediaSpeech.max).toBeGreaterThan(0)
     expect(AI_RATE_LIMIT.mediaTranscription.max).toBeGreaterThan(0)
-    expect(AI_RATE_LIMIT.mediaPoll.max).toBeGreaterThanOrEqual(AI_RATE_LIMIT.mediaImage.max)
     expect(AI_RATE_LIMIT.mediaPrototype.max).toBeGreaterThan(0)
   })
 

package/src/server/lib/rate-limit.ts

@@ -47,8 +47,6 @@ export const AI_RATE_LIMIT = {
   mediaVideo: { max: 5, windowMs: 60_000 },
   mediaSpeech: { max: 10, windowMs: 60_000 },
   mediaTranscription: { max: 10, windowMs: 60_000 },
-  // 轮询端点：任务进行期间会被周期调用，放宽阈值防误伤（仍封死无任务空转滥用）
-  mediaPoll: { max: 60, windowMs: 60_000 },
   mediaPrototype: { max: 5, windowMs: 60_000 },
   aiTask: { max: 5, windowMs: 60_000 },
   // 审计 A2x-serverfns-4 补口：知识库向量索引（embedding 计费调用，单文档建索引；