@allbluecn/web-app 0.12.0 → 0.12.2

package/src/server/ai-gateway/locks/pg-lock.ts

@@ -0,0 +1,111 @@
+import { Pool, type PoolClient } from "pg"
+import { defineLock, type LockStore } from "@tanstack/ai/locks"
+
+/**
+ * PG advisory lock 实现 {@link LockStore}（P3 任务 5）。
+ *
+ * 为什么不用 Prisma 交互式事务 + `pg_advisory_xact_lock`：
+ * Prisma 连接池在 packages/database 里是 `max: 5`，而 `withLock` 的临界区是
+ * sandbox ensure（查实例 → 建沙箱 → 写回），可能长达数十秒。用事务持锁意味着
+ * 临界区期间独占一个 Prisma 连接，5 个并发 ensure 就会耗尽全库连接，把与本临界区
+ * 无关的业务查询一起堵死。advisory xact lock 还有更隐蔽的问题：事务超时回滚会
+ * **静默释放锁**，另一个实例随即进入临界区，两个实例同时操作同一沙箱。
+ *
+ * 因此这里用**独立连接池**拿 session 级 advisory lock：
+ * - `pg_try_advisory_lock(hashtext(key))` 非阻塞探测 + 短轮询，直到拿到或超时
+ * - session 级锁绑定 backend PID，进程崩溃 / 连接断开时 PG 自动释放，无泄漏
+ * - 临界区内的 Prisma 调用走主池，与本池互不干扰
+ * - `unlock` 必须在 `release` 之前——session 级锁随连接归还池后会污染下一个使用者
+ *
+ * desktop（sqlite）不用本实现：chat-stream-builder 按 DEPLOY_TARGET 分支，
+ * desktop → InMemoryLockStore（单进程语义正确），web → pgLockStore()。
+ *
+ * ⚠ 嵌套限制：同一 key 的 `withLock` 内不要再调 `withLock(同 key)`。内层会从池
+ * 拿另一个 backend，`pg_try_advisory_lock` 对**不同 backend** 返回 false，内层
+ * 轮询等待而外层在等内层完成——形成自锁，最终以 ACQUIRE 超时 fail-closed 结束。
+ */
+
+const LOCK_ACQUIRE_TIMEOUT_MS = 60_000
+const LOCK_POLL_MS = 200
+const LOCK_POOL_MAX = 4
+const LOCK_CONNECT_TIMEOUT_MS = 10_000
+
+let lockPool: Pool | undefined
+
+function pool(): Pool {
+  if (!lockPool) {
+    const connectionString = process.env.DATABASE_URL
+    if (!connectionString) {
+      throw new Error("pgLockStore 需要 DATABASE_URL（postgresql 连接串）")
+    }
+    const pool = new Pool({
+      connectionString,
+      max: LOCK_POOL_MAX,
+      connectionTimeoutMillis: LOCK_CONNECT_TIMEOUT_MS,
+    })
+    // 空闲连接上报错不能变成未处理异常；连接会直接从池中剔除。
+    pool.on("error", () => {})
+    process.once("beforeExit", () => {
+      void pool.end()
+    })
+    lockPool = pool
+  }
+  return lockPool
+}
+
+async function acquire(client: PoolClient, key: string): Promise<void> {
+  const deadline = Date.now() + LOCK_ACQUIRE_TIMEOUT_MS
+  for (;;) {
+    const { rows } = await client.query<{ locked: boolean }>(
+      "SELECT pg_try_advisory_lock(hashtext($1)) AS locked",
+      [key],
+    )
+    if (rows[0]?.locked) return
+    if (Date.now() > deadline) {
+      throw new Error(
+        `获取 PG advisory lock 超时（key=${key}，等待 ${LOCK_ACQUIRE_TIMEOUT_MS}ms；` +
+          "持有者可能崩溃或临界区嵌套自锁）",
+      )
+    }
+    await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS))
+  }
+}
+
+async function release(client: PoolClient, key: string): Promise<void> {
+  try {
+    await client.query("SELECT pg_advisory_unlock(hashtext($1))", [key])
+  } catch {
+    // 连接已断开时锁随 backend 结束自动释放；这里的错误不应当覆盖 fn 的结果。
+  }
+}
+
+export function pgLockStore(): LockStore {
+  return defineLock({
+    async withLock<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T> {
+      const client = await pool().connect()
+      try {
+        await acquire(client, key)
+
+        // 连接意外断开意味着锁已随 backend 释放：按契约 abort signal，让 fn
+        // 停止对外可见的变更。正常路径下 fn 结束后才 abort（仅标记，不影响结果）。
+        const controller = new AbortController()
+        const onLost = () => {
+          controller.abort()
+        }
+        client.on("error", onLost)
+        client.on("end", onLost)
+
+        try {
+          return await fn(controller.signal)
+        } finally {
+          client.off("error", onLost)
+          client.off("end", onLost)
+          controller.abort()
+          await release(client, key)
+        }
+      } finally {
+        client.release()
+      }
+    },
+  })
+}

package/src/server/ai-gateway/media/__tests__/generation.spec.ts

@@ -0,0 +1,52 @@
+import { beforeEach, expect, it, vi } from "vitest"
+import type { ImageGenerationResult } from "@tanstack/ai"
+
+const mocks = vi.hoisted(() => ({ thread: vi.fn(), create: vi.fn(), update: vi.fn(), get: vi.fn(), images: vi.fn(), adapter: vi.fn() }))
+vi.mock("@allbluecn/database", () => ({ prisma: {
+  chatThread: { findFirst: mocks.thread },
+  generationRun: { findUnique: mocks.get, findFirst: mocks.get, create: mocks.create, upsert: mocks.create, updateMany: mocks.update },
+} }))
+vi.mock("../adapters.ts", () => ({ resolveImageAdapter: mocks.adapter }))
+import { generateImageForUser } from "../index"
+
+const opts = { userId: "owner", threadId: "thread", adapterKind: "openai", apiKey: "secret", model: "gpt-image-1", prompt: "paint", referenceImage: "data:image/png;base64,aGVsbG8=", sourceRunId: "source" }
+const output: ImageGenerationResult = { id: "provider-result", model: "gpt-image-1", images: [{ b64Json: "bmV3" }] }
+beforeEach(() => {
+  vi.resetAllMocks()
+  mocks.thread.mockResolvedValue({ id: "thread" })
+  mocks.get.mockResolvedValue(null)
+  mocks.create.mockImplementation(async (args) => ({ ...args.data ?? args.create }))
+  mocks.update.mockResolvedValue({ count: 1 })
+  mocks.images.mockResolvedValue(output)
+  mocks.adapter.mockReturnValue({ kind: "image", name: "openai", model: "gpt-image-1", generateImages: mocks.images })
+})
+
+it("runs the real package with image parts and persists user, input, output and terminal state", async () => {
+  const result = await generateImageForUser(opts)
+  expect(mocks.images.mock.calls[0][0].prompt).toEqual([
+    { type: "text", content: "paint" },
+    { type: "image", source: { type: "url", value: opts.referenceImage } },
+  ])
+  const created = mocks.create.mock.calls[0][0]
+  expect(created.data ?? created.create).toMatchObject({ userId: "owner", threadId: "thread", input: { prompt: "paint", sourceRunId: "source" } })
+  expect(result).toMatchObject({ runId: expect.any(String), images: output.images })
+  expect(mocks.update.mock.calls).toEqual(expect.arrayContaining([
+    [expect.objectContaining({ where: expect.objectContaining({ userId: "owner", threadId: "thread" }), data: expect.objectContaining({ result: expect.objectContaining({ images: output.images }) }) })],
+    [expect.objectContaining({ data: expect.objectContaining({ status: "completed", finishedAt: expect.any(Date) }) })],
+  ]))
+})
+it("rejects foreign threads before contacting provider or writing", async () => {
+  mocks.thread.mockResolvedValue(null)
+  await expect(generateImageForUser(opts)).rejects.toThrow("Thread not found")
+  expect(mocks.images).not.toHaveBeenCalled()
+  expect(mocks.create).not.toHaveBeenCalled()
+})
+it("records failed generation and propagates the provider error", async () => {
+  mocks.images.mockRejectedValue(new Error("provider failed"))
+  await expect(generateImageForUser(opts)).rejects.toThrow("provider failed")
+  expect(mocks.update).toHaveBeenCalledWith(expect.objectContaining({ where: expect.objectContaining({ userId: "owner" }), data: expect.objectContaining({ status: "failed", error: "provider failed" }) }))
+})
+it("propagates persistence failure without reporting success", async () => {
+  mocks.update.mockRejectedValue(new Error("storage failed"))
+  await expect(generateImageForUser(opts)).rejects.toThrow("storage failed")
+})

package/src/server/ai-gateway/media/__tests__/index.test.ts

@@ -0,0 +1,116 @@
+// 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/>.
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+
+import { prisma } from "@allbluecn/database"
+import { recordGenerationRun } from "../index"
+
+const MEDIA_TEST_USER_ID = "media-skeleton-test-user"
+const MEDIA_THREAD_ID = "media-skeleton-test-thread"
+
+/**
+ * 真库测试：GenerationRun 落库通道（P3 任务 9 骨架）。
+ *
+ * 只验证骨架本身的三件事：activity/kind 双写口径、Json 三列（result/artifacts/usage）
+ * 真实可写、终态 finishedAt 成对。不测媒体业务——本期不接业务、不注册 FeatureGate。
+ *
+ * ChatThread.userId 是 FK 链（User → ChatThread → GenerationRun），
+ * testkit 不会建 User 行，故 beforeAll 幂等建测试用户，afterAll 级联清理。
+ */
+describe.skipIf(
+  !process.env.DATABASE_URL || process.env.DATABASE_PROVIDER === "sqlite",
+)("recordGenerationRun（真库）", () => {
+  beforeAll(async () => {
+    await prisma.user.upsert({
+      where: { id: MEDIA_TEST_USER_ID },
+      create: {
+        id: MEDIA_TEST_USER_ID,
+        email: `${MEDIA_TEST_USER_ID}@media-skeleton.test`,
+        username: MEDIA_TEST_USER_ID,
+        password: "test-password-unused",
+      },
+      update: {},
+    })
+    await prisma.chatThread.create({
+      data: { id: MEDIA_THREAD_ID, userId: MEDIA_TEST_USER_ID },
+    })
+  })
+
+  afterAll(async () => {
+    await prisma.user.delete({ where: { id: MEDIA_TEST_USER_ID } }).catch(() => {})
+  })
+
+  it("running 态写入：activity/kind 双写同一值，Json 三列可落，finishedAt 为空", async () => {
+    const row = await recordGenerationRun({
+      threadId: MEDIA_THREAD_ID,
+      userId: MEDIA_TEST_USER_ID,
+      activity: "image",
+      provider: "openai",
+      model: "gpt-image-1",
+      status: "running",
+      artifacts: { urls: ["https://example.com/a.png"] },
+      usage: { outputImageCount: 1 },
+    })
+
+    const stored = (await prisma.generationRun.findUnique({ where: { id: row.id } }))!
+    expect(stored.activity).toBe("image")
+    expect(stored.kind).toBe("image")
+    expect(stored.status).toBe("running")
+    expect(stored.provider).toBe("openai")
+    expect(stored.model).toBe("gpt-image-1")
+    expect(stored.artifacts).toEqual({ urls: ["https://example.com/a.png"] })
+    expect(stored.usage).toEqual({ outputImageCount: 1 })
+    expect(stored.result).toBeNull()
+    expect(stored.error).toBeNull()
+    expect(stored.finishedAt).toBeNull()
+    expect(stored.startedAt).toBeInstanceOf(Date)
+    // 骨架只负责建 running 记录，不做状态流转
+    expect(stored.startedAt.getTime()).toBeLessThanOrEqual(Date.now())
+  })
+
+  it("终态写入：completed / failed / interrupted 都填 finishedAt 且 ≥ startedAt", async () => {
+    for (const status of ["completed", "failed", "interrupted"] as const) {
+      const row = await recordGenerationRun({
+        threadId: MEDIA_THREAD_ID,
+        userId: MEDIA_TEST_USER_ID,
+        activity: status === "completed" ? "speech" : "video",
+        status,
+        result: { text: status },
+        error: status === "completed" ? undefined : "provider timeout",
+      })
+
+      const stored = (await prisma.generationRun.findUnique({ where: { id: row.id } }))!
+      expect(stored.status).toBe(status)
+      expect(stored.finishedAt).toBeInstanceOf(Date)
+      expect(stored.finishedAt!.getTime()).toBeGreaterThanOrEqual(
+        stored.startedAt.getTime(),
+      )
+      expect(stored.error).toBe(status === "completed" ? null : "provider timeout")
+    }
+  })
+
+  it("threadId 必须属于真实 ChatThread（FK 约束生效）", async () => {
+    await expect(
+      recordGenerationRun({
+        threadId: "media-skeleton-no-such-thread",
+        userId: MEDIA_TEST_USER_ID,
+        activity: "image",
+        status: "running",
+      }),
+    ).rejects.toThrow()
+  })
+})

package/src/server/ai-gateway/media/__tests__/prototype-schema.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest"
+import { prototypeSchema, stripCodeFence } from "../prototype-schema"
+
+describe("prototype-schema 共享契约", () => {
+  it("prototypeSchema 接受 generate-prototype 形态的组件树", () => {
+    const valid = { message: "ok", components: [{ type: "button", source: "builtin", name: "按钮" }] }
+    expect(prototypeSchema.safeParse(valid).success).toBe(true)
+  })
+  it("prototypeSchema 接受空组件数组（数组无 min 约束）", () => {
+    expect(prototypeSchema.safeParse({ message: "x", components: [] }).success).toBe(true)
+  })
+  it("stripCodeFence 剥离 markdown 代码块", () => {
+    expect(stripCodeFence('```json\n{"a":1}\n```')).toBe('{"a":1}')
+    expect(stripCodeFence('  plain  ')).toBe("plain")
+  })
+  it("stripCodeFence 头 fence 剥离、无尾 fence 不报错", () => {
+    expect(stripCodeFence('```json\n{"a":1}')).toBe('{"a":1}')
+  })
+  it("prototypeSchema 拒绝非法 source 值", () => {
+    const r = prototypeSchema.safeParse({
+      message: "ok",
+      components: [{ type: "button", source: "unknown", name: "按钮" }],
+    })
+    expect(r.success).toBe(false)
+  })
+  it("prototypeSchema 缺 message 字段拒绝", () => {
+    expect(prototypeSchema.safeParse({ components: [] }).success).toBe(false)
+  })
+  it("prototypeSchema 拒绝空串 type", () => {
+    const r = prototypeSchema.safeParse({
+      message: "ok",
+      components: [{ type: "", source: "builtin", name: "按钮" }],
+    })
+    expect(r.success).toBe(false)
+  })
+})

package/src/server/ai-gateway/media/adapters.ts

@@ -0,0 +1,128 @@
+// 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/>.
+
+/**
+ * 媒体生成 adapter 工厂（BYOK 感知）。
+ *
+ * 按 AiProviderConfig.adapterKind 选择 factory。BYOK 场景必须用 `create*` 三参数版
+ * （`createOpenaiImage(model, apiKey, config?)`），而非两参数版——后者 config 是
+ * `Omit<Config, 'apiKey'>`，apiKey 从 env 读，不适合 per-user key。
+ *
+ * 不可用项返回 `{ kind: "unavailable" }`，调用方据此显灰 UI + 引导配置。
+ */
+
+import { createOpenaiImage } from "@tanstack/ai-openai"
+import { createGeminiImage } from "@tanstack/ai-gemini"
+import { createGrokImage } from "@tanstack/ai-grok"
+import { createOpenaiVideo } from "@tanstack/ai-openai"
+import { createGeminiVideo } from "@tanstack/ai-gemini"
+import { createGrokVideo } from "@tanstack/ai-grok"
+import { createOpenaiSpeech } from "@tanstack/ai-openai"
+import { createGrokSpeech } from "@tanstack/ai-grok"
+import { createOpenaiTranscription } from "@tanstack/ai-openai"
+import { createGrokTranscription } from "@tanstack/ai-grok"
+import type { AnyImageAdapter, AnyVideoAdapter, AnyTTSAdapter, AnyTranscriptionAdapter } from "@tanstack/ai"
+
+export type AdapterKind = "openai" | "gemini" | "grok"
+
+interface Unavailable {
+  kind: "unavailable"
+}
+
+export type ImageAdapterResult = AnyImageAdapter | Unavailable
+export type VideoAdapterResult = AnyVideoAdapter | Unavailable
+export type SpeechAdapterResult = AnyTTSAdapter | Unavailable
+export type TranscriptionAdapterResult = AnyTranscriptionAdapter | Unavailable
+
+export interface ResolveAdapterOptions {
+  adapterKind: string
+  apiKey: string
+  model: string
+  baseURL?: string
+}
+
+/**
+ * 按 adapterKind 选择 image adapter factory。
+ * gemini 的 config 用 `httpOptions: { baseUrl }`（ai-gemini@0.20+ breaking change）。
+ */
+export function resolveImageAdapter(opts: ResolveAdapterOptions): ImageAdapterResult {
+  const { adapterKind, apiKey, model, baseURL } = opts
+
+  switch (adapterKind) {
+    case "openai":
+      return createOpenaiImage(model as Parameters<typeof createOpenaiImage>[0], apiKey, baseURL ? { baseURL } : undefined) as ImageAdapterResult
+    case "gemini":
+      return createGeminiImage(model as Parameters<typeof createGeminiImage>[0], apiKey, baseURL ? { httpOptions: { baseUrl: baseURL } } : undefined) as ImageAdapterResult
+    case "grok":
+      return createGrokImage(model as Parameters<typeof createGrokImage>[0], apiKey, baseURL ? { baseURL } : undefined) as ImageAdapterResult
+    default:
+      return { kind: "unavailable" }
+  }
+}
+
+/**
+ * 按 adapterKind 选择 video adapter factory。
+ * gemini 的 config 用 `httpOptions: { baseUrl }`。
+ */
+export function resolveVideoAdapter(opts: ResolveAdapterOptions): VideoAdapterResult {
+  const { adapterKind, apiKey, model, baseURL } = opts
+
+  switch (adapterKind) {
+    case "openai":
+      return createOpenaiVideo(model as Parameters<typeof createOpenaiVideo>[0], apiKey, baseURL ? { baseURL } : undefined) as VideoAdapterResult
+    case "gemini":
+      return createGeminiVideo(model as Parameters<typeof createGeminiVideo>[0], apiKey, baseURL ? { httpOptions: { baseUrl: baseURL } } : undefined) as VideoAdapterResult
+    case "grok":
+      return createGrokVideo(model as Parameters<typeof createGrokVideo>[0], apiKey, baseURL ? { baseURL } : undefined) as VideoAdapterResult
+    default:
+      return { kind: "unavailable" }
+  }
+}
+
+/**
+ * 按 adapterKind 选择 speech (TTS) adapter factory。
+ * gemini 无 TTS 能力。
+ */
+export function resolveSpeechAdapter(opts: ResolveAdapterOptions): SpeechAdapterResult {
+  const { adapterKind, apiKey, model, baseURL } = opts
+
+  switch (adapterKind) {
+    case "openai":
+      return createOpenaiSpeech(model as Parameters<typeof createOpenaiSpeech>[0], apiKey, baseURL ? { baseURL } : undefined) as SpeechAdapterResult
+    case "grok":
+      return createGrokSpeech(model as Parameters<typeof createGrokSpeech>[0], apiKey, baseURL ? { baseURL } : undefined) as SpeechAdapterResult
+    default:
+      return { kind: "unavailable" }
+  }
+}
+
+/**
+ * 按 adapterKind 选择 transcription adapter factory。
+ * gemini 无转写能力。
+ */
+export function resolveTranscriptionAdapter(opts: ResolveAdapterOptions): TranscriptionAdapterResult {
+  const { adapterKind, apiKey, model, baseURL } = opts
+
+  switch (adapterKind) {
+    case "openai":
+      return createOpenaiTranscription(model as Parameters<typeof createOpenaiTranscription>[0], apiKey, baseURL ? { baseURL } : undefined) as TranscriptionAdapterResult
+    case "grok":
+      return createGrokTranscription(model as Parameters<typeof createGrokTranscription>[0], apiKey, baseURL ? { baseURL } : undefined) as TranscriptionAdapterResult
+    default:
+      return { kind: "unavailable" }
+  }
+}