@allbluecn/web-app 0.19.0 → 0.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allbluecn/web-app",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -58,10 +58,10 @@
     "access": "public"
   },
   "dependencies": {
+    "@ag-ui/core": "1.0.0",
     "@allbluecn/collab-core": "0.2.0",
-    "@allbluecn/database": "0.9.3",
+    "@allbluecn/database": "0.9.4",
     "@allbluecn/kernel": "0.10.0",
-    "@ag-ui/core": "1.0.0",
     "@ariakit/react": "^0.4.28",
     "@auth/core": "^0.41.2",
     "@auth/prisma-adapter": "^2.11.2",

package/src/components/ai/ai-chat-prompt.tsx

@@ -56,7 +56,7 @@ export function AiChatPrompt({ hasAiKey }: { hasAiKey?: boolean | null }) {
   // threadId mount 级稳定值（useRef 初始值，绝无 render 路径重新生成）：
   // 1.0 起 threadId 必填，且 useChat 在 connection/选项变化时重建 ChatClient——
   // 每次 render 新值 = 每次发消息开新会话。
-  const threadIdRef = useRef(crypto.randomUUID())
+  const threadIdRef = useRef(crypto.randomUUID());
 
   // reconnect 约束（P1-5）：同 harness/chat-ui.tsx，dev server 故障期减少自动
   // 重放 POST（默认 5 次 → 2 次、退避 250ms → 1s），避免 400 风暴。

package/src/components/ai/global-harness-sidebar/index.tsx

@@ -286,7 +286,7 @@ export function GlobalHarnessSidebar({ hasAiKey }: { hasAiKey?: boolean | null }
   // 空会话态（尚无 activeThreadId）的 threadId 兜底：mount 级稳定 UUID。
   // 缺省时客户端每次发消息 mint 新 thread_*（= 每次开新会话）；真实会话 id
   // 在新建/切换会话后经 activeThreadId 接管。
-  const fallbackThreadIdRef = useRef(crypto.randomUUID())
+  const fallbackThreadIdRef = useRef(crypto.randomUUID());
 
   const chat = useHarnessChat({
     threadId: activeThreadId ?? fallbackThreadIdRef.current,

package/src/components/command/command-palette.tsx

@@ -118,9 +118,12 @@ export function CommandPalette() {
 
   useHotkeys(
     commands
-      .filter((c) => c.shortcut && c.shortcut.length >= 2)
+      // 类型谓词收窄：shortcut 已前移为 HotkeySequence（registry 录入非法
+      // 键名在定义处即 tsc 报错），此处无需再 as 断言
+      .filter((c): c is ResolvedCommand & { shortcut: HotkeySequence } =>
+        !!c.shortcut && c.shortcut.length >= 2)
       .map((c) => ({
-        hotkey: c.shortcut as HotkeySequence,
+        hotkey: c.shortcut,
         callback: () => run(c),
         options: { enabled: !open },
       })),
@@ -149,7 +152,7 @@ export function CommandPalette() {
   )
 }
 
-function resolveShortcut(shortcut: string[]): string {
+function resolveShortcut(shortcut: readonly string[]): string {
   const isMac = typeof navigator !== "undefined"
     && (navigator.platform.toUpperCase().includes("MAC")
       || navigator.userAgent.toUpperCase().includes("MAC"))

package/src/components/harness/__tests__/composer-draft.test.ts

@@ -62,6 +62,24 @@ describe("parseStoredDraft（草稿串 parse 回 doc，修复双重序列化）"
     expect(parseStoredDraft("hello draft")).toBe("hello draft")
   })
 
+  it("doc 缺 content 或 content 非数组（损坏值）拒绝为空 doc；content 空数组合法", () => {
+    // sessionStorage 手改/损坏：content 缺失
+    expect(parseStoredDraft(JSON.stringify({ type: "doc" }))).toEqual({
+      type: "doc",
+      content: [],
+    })
+    // content 为字符串而非数组
+    expect(parseStoredDraft(JSON.stringify({ type: "doc", content: "oops" }))).toEqual({
+      type: "doc",
+      content: [],
+    })
+    // content 空数组仍是合法 doc（原样 parse 回）
+    expect(parseStoredDraft(JSON.stringify({ type: "doc", content: [] }))).toEqual({
+      type: "doc",
+      content: [],
+    })
+  })
+
   it("空串返回空串", () => {
     expect(parseStoredDraft("")).toBe("")
   })

package/src/components/harness/__tests__/harness-workbench-first-send.test.tsx

@@ -0,0 +1,260 @@
+// 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/>.
+
+/**
+ * 空态首条消息孤儿线程修复的回归测试（T5/T8 发现）。
+ *
+ * useHarnessChat 工厂按 threadId 重建 ChatClient（useMemo 依赖 threadId）。
+ * 修复前：空态发送时 handleSend 建会话后直接调用旧渲染闭包里的
+ * chat.sendMessage——旧 client 仍绑定兜底 UUID，首条交换持久化到孤儿线程。
+ * 修复后：先建会话 → setActiveConversationId + pendingSend 槽 → effect 在
+ * hook 重绑定真实会话 id 的提交里消费发送。
+ *
+ * 测试口径：mock useHarnessChat 记录每次渲染绑定的 threadId；sendMessage
+ * 按其所属绑定的 threadId 写入事件日志，createConversationFn 同样写日志。
+ * 断言「先 create 后 send」且 send 的 threadId == 创建的会话 id。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react"
+import type { ReactNode } from "react"
+import HarnessWorkbenchPage from "../harness-workbench-page"
+import { createConversationFn } from "@/server/serverFns/chat/conversations"
+import { stashPendingWorkspaceMessage, PENDING_WORKSPACE_MESSAGE_KEY } from "@/lib/ai/chat-handoff"
+
+const CONV_ID = "conv-real-1"
+
+const h = vi.hoisted(() => {
+  return {
+    // 事件日志：'create:<id>' / 'send:<绑定线程id>'，按发生顺序
+    log: [] as string[],
+    // 每次 useHarnessChat 渲染绑定的 threadId
+    bindings: [] as string[],
+    // 每次 sendMessage 的实参（wire 内容与透传选项）
+    sends: [] as Array<{ threadId: string; content: unknown; sendOptions: unknown }>,
+  }
+})
+
+vi.mock("@/components/harness/chat-ui", () => ({
+  useHarnessChat: (options: { threadId: string }) => {
+    h.bindings.push(options.threadId)
+    return {
+      messages: [],
+      isLoading: false,
+      status: "idle",
+      connectionStatus: "connected",
+      error: undefined,
+      runId: undefined,
+      interrupts: [],
+      sendMessage: (content: unknown, sendOptions?: unknown) => {
+        h.log.push(`send:${options.threadId}`)
+        h.sends.push({ threadId: options.threadId, content, sendOptions })
+        return Promise.resolve()
+      },
+      stop: () => {},
+      clear: () => {},
+      AppChat: () => null,
+    }
+  },
+  useHarnessChatContext: () => ({}),
+}))
+
+vi.mock("@tanstack/react-router", () => ({
+  useNavigate: () => vi.fn(),
+  Link: (props: { to: string; children?: ReactNode }) => (
+    <a href={props.to}>{props.children}</a>
+  ),
+}))
+
+vi.mock("@tanstack/react-query", () => ({
+  useQuery: () => ({ data: undefined }),
+}))
+
+vi.mock("@/lib/auth/auth-client", () => ({
+  useSession: () => ({ data: { user: { hasAiKey: true } } }),
+}))
+
+vi.mock("@/server/serverFns/chat/conversations", () => ({
+  listConversationsFn: vi.fn(() => Promise.resolve([])),
+  createConversationFn: vi.fn(async () => {
+    h.log.push(`create:${CONV_ID}`)
+    return { id: CONV_ID, title: "" }
+  }),
+  updateConversationFn: vi.fn(() => Promise.resolve({})),
+  deleteConversationFn: vi.fn(() => Promise.resolve({})),
+  forkConversationFn: vi.fn(() => Promise.resolve({})),
+}))
+
+vi.mock("@/server/serverFns/agents/agent-crud", () => ({
+  listAgentsFn: vi.fn(() => Promise.resolve([])),
+}))
+
+vi.mock("@/server/serverFns/design/ai/providers", () => ({
+  listAiProvidersFn: vi.fn(() => Promise.resolve([])),
+}))
+
+vi.mock("@/server/serverFns/harness/cancel-run", () => ({
+  cancelRunFn: vi.fn(() => Promise.resolve({})),
+}))
+
+vi.mock("@/lib/ai/use-selected-model", () => ({
+  useSelectedModel: () => ["", vi.fn()] as const,
+}))
+
+vi.mock("@/lib/ai/use-search-capability", () => ({
+  useSearchCapability: () => ({
+    enabled: false,
+    adapterKind: "openrouter",
+    hasNative: true,
+    searxngEnabled: false,
+  }),
+}))
+
+vi.mock("@/lib/ai/use-code-mode-readiness", () => ({
+  useCodeModeReadiness: () => ({ enabled: false }),
+}))
+
+vi.mock("@/components/harness/composer/harness-composer", () => ({
+  HarnessComposer: ({ onSend }: { onSend: (val: string, opts?: unknown) => void }) => (
+    <>
+      <button type="button" onClick={() => onSend("hello there")}>test-send</button>
+      <button
+        type="button"
+        onClick={() => onSend("rich payload", {
+          whenBusy: "interrupt",
+          knowledgeBaseIds: ["kb-1"],
+          attachments: [{
+            type: "image",
+            source: { type: "data", value: "data:image/png;base64,xyz", mimeType: "image/png" },
+          }],
+        })}
+      >
+        test-send-rich
+      </button>
+    </>
+  ),
+}))
+
+vi.mock("@/components/harness/ai-chat-history", () => ({ default: () => null }))
+vi.mock("@/components/harness/agent-preset-picker", () => ({ AgentPresetPicker: () => null }))
+vi.mock("@/components/harness/dock/dock-panel-container", () => ({ DockPanelContainer: () => null }))
+vi.mock("@/components/harness/workbench/workbench-shell", () => ({
+  WorkbenchShell: ({ center }: { center: ReactNode }) => <div>{center}</div>,
+}))
+vi.mock("@/components/harness/code/code-workspace-sidebar", () => ({
+  CodeWorkspaceSidebar: () => null,
+}))
+vi.mock("@/components/confirm-dialog", () => ({ ConfirmDialog: () => null }))
+
+beforeEach(() => {
+  h.log.length = 0
+  h.bindings.length = 0
+  h.sends.length = 0
+  sessionStorage.clear()
+})
+
+afterEach(cleanup)
+
+describe("HarnessWorkbenchPage 空态首条消息", () => {
+  it("先创建会话，且 wire threadId == 创建的会话 id（非兜底 UUID）", async () => {
+    render(<HarnessWorkbenchPage />)
+    fireEvent.click(screen.getByRole("button", { name: "test-send" }))
+    await waitFor(() => {
+      expect(h.log).toEqual([`create:${CONV_ID}`, `send:${CONV_ID}`])
+    })
+    // 无任何发送落在兜底 UUID 线程
+    expect(h.log.filter((l) => l.startsWith("send:"))).toEqual([`send:${CONV_ID}`])
+    // 发送内容为用户输入原文，无 sendOptions 时透传侧不被伪造
+    expect(h.sends).toEqual([
+      { threadId: CONV_ID, content: "hello there", sendOptions: undefined },
+    ])
+  })
+
+  it("会话创建后的再次发送不新建会话，仍绑定同一会话 id", async () => {
+    render(<HarnessWorkbenchPage />)
+    const send = screen.getByRole("button", { name: "test-send" })
+    fireEvent.click(send)
+    await waitFor(() => {
+      expect(h.log).toEqual([`create:${CONV_ID}`, `send:${CONV_ID}`])
+    })
+    fireEvent.click(send)
+    await waitFor(() => {
+      expect(h.log).toEqual([`create:${CONV_ID}`, `send:${CONV_ID}`, `send:${CONV_ID}`])
+    })
+    expect(h.bindings.filter((id) => id === CONV_ID).length).toBeGreaterThan(0)
+    // 两次发送 content 均为原文且都绑定真实会话
+    expect(h.sends).toEqual([
+      { threadId: CONV_ID, content: "hello there", sendOptions: undefined },
+      { threadId: CONV_ID, content: "hello there", sendOptions: undefined },
+    ])
+  })
+
+  it("会话创建失败时放弃发送（不产生孤儿线程）", async () => {
+    vi.mocked(createConversationFn).mockRejectedValueOnce(new Error("boom"))
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+    try {
+      render(<HarnessWorkbenchPage />)
+      fireEvent.click(screen.getByRole("button", { name: "test-send" }))
+      await waitFor(() => {
+        expect(vi.mocked(createConversationFn)).toHaveBeenCalled()
+      })
+      expect(h.log.filter((l) => l.startsWith("send:"))).toEqual([])
+      expect(h.sends).toEqual([])
+    } finally {
+      errorSpy.mockRestore()
+    }
+  })
+
+  it("工作区交接 pending 消息在 mount 时发送到新建会话 id", async () => {
+    stashPendingWorkspaceMessage("handoff hello")
+    render(<HarnessWorkbenchPage />)
+    await waitFor(() => {
+      expect(h.log).toEqual([`create:${CONV_ID}`, `send:${CONV_ID}`])
+    })
+    // 交接内容原文到达发送侧（防槽位内容丢失发空串）
+    expect(h.sends).toEqual([
+      { threadId: CONV_ID, content: "handoff hello", sendOptions: undefined },
+    ])
+    expect(sessionStorage.getItem(PENDING_WORKSPACE_MESSAGE_KEY)).toBeNull()
+  })
+
+  it("空态首条 rich 发送透传 sendOptions 与多模态 content 到真实会话", async () => {
+    render(<HarnessWorkbenchPage />)
+    fireEvent.click(screen.getByRole("button", { name: "test-send-rich" }))
+    await waitFor(() => {
+      expect(h.log).toEqual([`create:${CONV_ID}`, `send:${CONV_ID}`])
+    })
+    // whenBusy / knowledgeBaseIds(body) / 图片 attachments 经 pendingSend 槽零丢失
+    expect(h.sends).toEqual([
+      {
+        threadId: CONV_ID,
+        content: {
+          content: [
+            { type: "text", content: "rich payload" },
+            {
+              type: "image",
+              source: { type: "data", value: "data:image/png;base64,xyz", mimeType: "image/png" },
+            },
+          ],
+        },
+        sendOptions: {
+          whenBusy: "interrupt",
+          body: { knowledgeBaseIds: ["kb-1"] },
+        },
+      },
+    ])
+  })
+})

package/src/components/harness/composer/composer-editor.tsx

@@ -33,7 +33,11 @@ function isDocNode(value: unknown): value is JSONContent {
     typeof value === "object" &&
     value !== null &&
     !Array.isArray(value) &&
-    (value as Record<string, unknown>).type === "doc"
+    (value as Record<string, unknown>).type === "doc" &&
+    // content 形状校验：doc 节点的 content 必须是数组（可为空）。
+    // 防 sessionStorage 手改/损坏值（content 缺失或非数组）直进 TipTap
+    // 触发 schema 断言崩溃。
+    Array.isArray((value as Record<string, unknown>).content)
   )
 }
 

package/src/components/harness/harness-workbench-page.tsx

@@ -64,6 +64,18 @@ export interface HarnessWorkbenchPageProps {
   initialMessages?: UIMessage[]
 }
 
+type HarnessChatInstance = ReturnType<typeof useHarnessChat>
+
+/**
+ * 空态首条消息的延迟发送槽（孤儿线程修复，见 pendingSend effect）。
+ * content/sendOptions 形状跟随 useHarnessChat.sendMessage 的真实签名。
+ */
+interface PendingThreadSend {
+  threadId: string
+  content: Parameters<HarnessChatInstance["sendMessage"]>[0]
+  sendOptions?: Parameters<HarnessChatInstance["sendMessage"]>[1]
+}
+
 export default function HarnessWorkbenchPage({ initialThreadId, initialMessages }: HarnessWorkbenchPageProps) {
   const { data: session } = useSession()
   const hasAiKey = session?.user?.hasAiKey
@@ -132,7 +144,7 @@ export default function HarnessWorkbenchPage({ initialThreadId, initialMessages
   // 空会话态（尚无 activeConversationId）的 threadId 兜底：mount 级稳定 UUID。
   // 缺省时客户端每次发消息 mint 新 thread_*（= 每次开新会话）；真实会话 id
   // 在 handleSend 创建后经 activeConversationId 接管。
-  const fallbackThreadIdRef = useRef(crypto.randomUUID())
+  const fallbackThreadIdRef = useRef(crypto.randomUUID());
 
   const chat = useHarnessChat({
     threadId: activeConversationId ?? initialThreadId ?? fallbackThreadIdRef.current,
@@ -159,6 +171,21 @@ export default function HarnessWorkbenchPage({ initialThreadId, initialMessages
   const activeIdRef = useRef(activeConversationId)
   activeIdRef.current = activeConversationId
   const loadingRef = useRef(false)
+  const [pendingSend, setPendingSend] = useState<PendingThreadSend | null>(null)
+  const creatingConversationRef = useRef(false)
+
+  // 孤儿线程修复（T5/T8）：useHarnessChat 工厂按 threadId 重建 ChatClient
+  // （useMemo 依赖 options.threadId），空态首条发送时 activeConversationId
+  // 尚未经历渲染——直接 chat.sendMessage 会走旧 client 兜底 UUID 线程。
+  // 因此先建会话 → setActiveConversationId + 落 pendingSend 槽 → 本 effect
+  // 在 hook 已重绑定真实会话 id 的那次提交里消费并发送。
+  useEffect(() => {
+    if (!pendingSend) return
+    // 守卫：仅在 hook 已绑定目标会话时才消费（防陈旧槽位误发）
+    if ((activeConversationId ?? initialThreadId) !== pendingSend.threadId) return
+    setPendingSend(null)
+    void chat.sendMessage(pendingSend.content, pendingSend.sendOptions)
+  }, [pendingSend, chat, activeConversationId, initialThreadId])
 
   const loadConversations = useCallback(() => {
     if (initialThreadId != null) return
@@ -237,8 +264,10 @@ export default function HarnessWorkbenchPage({ initialThreadId, initialMessages
       activeIdRef.current = conv.id
       clearHarnessCitations()
       setLatestCitations(undefined)
-      chat.clear()
-      void chat.sendMessage(pending)
+      // 与 handleSend 空态同理：经 pendingSend 槽等 hook 重绑定后再发送，
+      // 避免首条交接消息落进兜底 UUID 孤儿线程（此路径 hook 为全新实例，
+      // 新 client 以空消息起播，无需 clear）
+      setPendingSend({ threadId: conv.id, content: pending })
     }
 
   void (async () => {
@@ -350,35 +379,38 @@ export default function HarnessWorkbenchPage({ initialThreadId, initialMessages
         },
       })
     }
+    // knowledgeBaseIds 通过 body 传递到 forwardedProps
+    const sendOptions = opts ? {
+      whenBusy: opts.whenBusy,
+      body: opts.knowledgeBaseIds ? { knowledgeBaseIds: opts.knowledgeBaseIds } : undefined,
+    } : undefined
+    const content: Parameters<HarnessChatInstance["sendMessage"]>[0]
+      = opts?.attachments && opts.attachments.length > 0
+      // 多模态消息：文本 + 图片 parts
+      ? { content: [{ type: 'text' as const, content: val }, ...opts.attachments] }
+      : val
     if (!activeIdRef.current) {
+      // 空态首条消息：先建会话拿真实 id（失败早退），再经 pendingSend 槽
+      // 等 hook 以新 threadId 重建 client 后发送——直接 sendMessage 会把
+      // 首条交换持久化到兜底 UUID 的孤儿线程（刷新后首条不回显）。
+      if (creatingConversationRef.current) return
+      creatingConversationRef.current = true
       try {
         const conv = await createConversationFn({ data: { agentId: selectedAgentId } })
         setConversations(prev => [conv, ...prev])
         setActiveConversationId(conv.id)
         activeIdRef.current = conv.id
         clearHarnessCitations()
+        setPendingSend({ threadId: conv.id, content, sendOptions })
       } catch (e) {
         console.error('Failed to create conversation:', e)
         return
+      } finally {
+        creatingConversationRef.current = false
       }
+      return
     }
-    // knowledgeBaseIds 通过 body 传递到 forwardedProps
-    const sendOptions = opts ? {
-      whenBusy: opts.whenBusy,
-      body: opts.knowledgeBaseIds ? { knowledgeBaseIds: opts.knowledgeBaseIds } : undefined,
-    } : undefined
-    if (opts?.attachments && opts.attachments.length > 0) {
-      // 多模态消息：文本 + 图片 parts
-      const content = {
-        content: [
-          { type: 'text' as const, content: val },
-          ...opts.attachments
-        ]
-      }
-      void chat.sendMessage(content, sendOptions)
-    } else {
-      void chat.sendMessage(val, sendOptions)
-    }
+    void chat.sendMessage(content, sendOptions)
   }, [chat, selectedAgentId])
 
   const handleStop = useCallback(() => {

package/src/components/tiptap/ui/ai-menu/ai-menu.tsx

@@ -101,7 +101,7 @@ export function AiMenuContent({
 
   // threadId mount 级稳定值（useRef 初始值，绝无 render 路径重新生成）：
   // 1.0 起 threadId 必填，每次 render 新值 = 每次发消息开新会话。
-  const threadIdRef = useRef(crypto.randomUUID())
+  const threadIdRef = useRef(crypto.randomUUID());
 
   const { sendMessage, isLoading, stop, messages } = useChat({
     // reconnect 约束（P1-5）：同 harness/chat-ui.tsx，dev server 故障期减少自动重放 POST

package/src/lib/changelog/sdk-versions.ts

@@ -95,8 +95,8 @@ export const SDK_GROUPS: SdkGroup[] = [
     "items": [
       {
         "name": "@allbluecn/web-app",
-        "version": "v0.19.0",
-        "lastUpdate": "Oct 25, 2026",
+        "version": "v0.19.2",
+        "lastUpdate": "Oct 26, 2026",
         "source": "apps/web/package.json",
         "docsUrl": "https://github.com/allbluecn/allblue"
       },

package/src/lib/commands/types.ts

@@ -15,6 +15,8 @@
 // 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/>.
 
+import type { HotkeySequence } from "@tanstack/hotkeys"
+
 export type CommandAction =
   | { kind: "navigate"; to: string }
   | { kind: "callback"; id: string }
@@ -28,8 +30,8 @@ export interface CommandDefinition {
   group: CommandGroup
   action: CommandAction
   keywords?: string[]
-  /** 序列键（如 ["G","D"]），注册为 useHotkeys */
-  shortcut?: string[]
+  /** 序列键（如 ["G","D"]），注册为 useHotkeys；非法键名在定义处即报 tsc 错误 */
+  shortcut?: HotkeySequence
   /** 组合键（如 ["Mod","Shift","L"]），仅用于面板展示 */
   chord?: string[]
 }

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

@@ -11,6 +11,7 @@ const mocks = vi.hoisted(() => {
   const pgLockStore = vi.fn()
   const generationRunFindMany = vi.fn()
   const generationRunFindUnique = vi.fn()
+  const generationRunUpsert = vi.fn()
   return {
     withSandbox,
     defineSandbox,
@@ -20,6 +21,7 @@ const mocks = vi.hoisted(() => {
     pgLockStore,
     generationRunFindMany,
     generationRunFindUnique,
+    generationRunUpsert,
   }
 })
 
@@ -50,6 +52,7 @@ vi.mock("@allbluecn/database", () => ({
     generationRun: {
       findMany: mocks.generationRunFindMany,
       findUnique: mocks.generationRunFindUnique,
+      upsert: mocks.generationRunUpsert,
     },
   },
 }))
@@ -186,6 +189,11 @@ describe("buildSandboxMiddleware 装配", () => {
 describe("snapshots artifacts/blobs store 装配", () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    // 显式 mockReset 对齐第一个 describe 的卫生标准（clearAllMocks 只清
+    // 调用记录，不清 mockResolvedValue 等实现，跨用例会泄漏）
+    mocks.generationRunFindMany.mockReset()
+    mocks.generationRunFindUnique.mockReset()
+    mocks.generationRunUpsert.mockReset()
     vi.unstubAllEnvs()
     delete process.env.DEPLOY_TARGET
     mocks.resolveSandboxProvider.mockResolvedValue({ provider: { name: "mock" } })
@@ -202,7 +210,11 @@ describe("snapshots artifacts/blobs store 装配", () => {
         persistence?: {
           stores?: {
             artifacts?: { listForThread: (threadId: string) => Promise<Array<Record<string, unknown>>> }
-            blobs?: { get: (key: string) => Promise<{ arrayBuffer: () => Promise<ArrayBuffer> } | null> }
+            blobs?: {
+              get: (key: string) => Promise<{ arrayBuffer: () => Promise<ArrayBuffer> } | null>
+              head: (key: string) => Promise<{ size: number } | null>
+              put: (key: string, body: Uint8Array) => Promise<{ size: number }>
+            }
           }
         }
       }
@@ -255,4 +267,62 @@ describe("snapshots artifacts/blobs store 装配", () => {
       expect.objectContaining({ where: { id: "run-no-artifact" } }),
     )
   })
+
+  it("blobs.put 全新 key 的 create 分支携带真实 threadId/userId（而非 key 充当主外键）", async () => {
+    mocks.generationRunUpsert.mockResolvedValue({})
+    await buildSandboxMiddleware(baseParams({ userId: "user-1" }))
+    const stores = snapshotStores()
+
+    const bytes = new TextEncoder().encode("hello")
+    const result = await stores.blobs!.put("sandbox-files/sha256/abc", bytes)
+
+    expect(result).toEqual({ size: bytes.byteLength })
+    expect(mocks.generationRunUpsert).toHaveBeenCalledTimes(1)
+    const args = mocks.generationRunUpsert.mock.calls[0][0] as {
+      where: { id: string }
+      create: Record<string, unknown>
+    }
+    expect(args.where).toEqual({ id: "sandbox-files/sha256/abc" })
+    // 回归断言：threadId/userId 是真实归属（FK 指向 ChatThread），绝不能是 blob key
+    expect(args.create.threadId).toBe("thread-1")
+    expect(args.create.userId).toBe("user-1")
+    expect(args.create).toMatchObject({
+      id: "sandbox-files/sha256/abc",
+      kind: "sandbox-blob",
+      status: "completed",
+      activity: "sandbox",
+      result: Buffer.from(bytes).toString("base64"),
+    })
+  })
+
+  it("blobs.put 未传 userId 时 create 落 sandbox 标记（desktop 后台路径无 FK 风险）", async () => {
+    mocks.generationRunUpsert.mockResolvedValue({})
+    await buildSandboxMiddleware(baseParams())
+    const stores = snapshotStores()
+
+    await stores.blobs!.put("sandbox-files/sha256/xyz", new Uint8Array([1]))
+
+    const args = mocks.generationRunUpsert.mock.calls[0][0] as {
+      create: Record<string, unknown>
+    }
+    expect(args.create.threadId).toBe("thread-1")
+    expect(args.create.userId).toBe("sandbox")
+  })
+
+  it("blobs.put 已存在 key 走 update 分支仅写 result（既有行为不变）", async () => {
+    mocks.generationRunUpsert.mockResolvedValue({})
+    await buildSandboxMiddleware(baseParams({ userId: "user-1" }))
+    const stores = snapshotStores()
+
+    await stores.blobs!.put("run-existing", new TextEncoder().encode("updated"))
+
+    const args = mocks.generationRunUpsert.mock.calls[0][0] as {
+      where: { id: string }
+      update: Record<string, unknown>
+    }
+    expect(args.where).toEqual({ id: "run-existing" })
+    expect(args.update).toEqual({
+      result: Buffer.from("updated").toString("base64"),
+    })
+  })
 })

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

@@ -251,13 +251,20 @@ export async function buildSandboxMiddleware(
               await prisma.generationRun.upsert({
                 where: { id: key },
                 update: { result: base64 as any },
+                // create 分支必须携带真实 threadId/userId：GenerationRun.threadId
+                // 有 FK 指向 ChatThread（schema.prisma），旧实现误用 blob key 充当
+                // 二者——全新 key（快照捕获经 ai-sandbox putIfAbsent 到达此处时的
+                // 内容寻址 sandbox-files/sha256/<hash>）必然 FK 违反，create 路径
+                // 实际不可用。快照 blob 归属当前会话沙箱，threadId 取 params；
+                // userId 无 FK 仅作归属索引，desktop 后台等无 userId 路径落标记值。
                 create: {
                   id: key,
-                  threadId: key,
-                  userId: key,
+                  threadId: params.threadId,
+                  userId: params.userId ?? "sandbox",
                   kind: "sandbox-blob",
                   status: "completed",
                   result: base64 as any,
+                  activity: "sandbox",
                 },
               })
               return { size: body.length }