@allbluecn/web-app 0.12.0 → 0.12.2

package/src/server/ai-gateway/__tests__/pgvector-memory-adapter.test.ts

@@ -0,0 +1,422 @@
+// @vitest-environment node
+// 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 { describe, it, expect, vi, beforeEach, afterEach } from "vitest"
+
+const mocks = vi.hoisted(() => {
+  const queryRawUnsafe = vi.fn()
+  const executeRawUnsafe = vi.fn()
+  const chatThreadFindUnique = vi.fn()
+  const generateEmbedding = vi.fn()
+  return {
+    queryRawUnsafe,
+    executeRawUnsafe,
+    chatThreadFindUnique,
+    generateEmbedding,
+    prisma: {
+      $queryRawUnsafe: queryRawUnsafe,
+      $executeRawUnsafe: executeRawUnsafe,
+      chatThread: { findUnique: chatThreadFindUnique },
+    },
+  }
+})
+
+vi.mock("@allbluecn/database", () => ({ prisma: mocks.prisma }))
+vi.mock("../embedding", () => ({
+  generateEmbedding: mocks.generateEmbedding,
+}))
+
+import {
+  createPgVectorMemoryAdapter,
+  DEFAULT_MIN_USER_CHARS,
+  DEFAULT_RECALL_TOP_K,
+  DEFAULT_SIMILARITY_THRESHOLD,
+} from "../memory/pgvector-adapter"
+import {
+  createMemoryScopeResolver,
+  MemoryScopeError,
+} from "../memory/scope"
+
+const scope = { threadId: "thread-a", userId: "user-1" } as const
+
+// 检索阶段用例会先撞上零记忆快路径的计数查询：计数必须 > 0，
+// 否则 recall 在调用 embedding 之前就短路返回了——断言仍然全绿，
+// 但该用例其实什么都没测到（「检索异常降级」曾因此静默失真）。
+function seedExistingFacts(count = 1): void {
+  mocks.queryRawUnsafe.mockResolvedValueOnce([{ c: count, lastWrite: null }])
+}
+
+const VECTOR_4 = [0.1, 0.2, 0.3, 0.4]
+
+function makeAdapter(
+  overrides: Parameters<typeof createPgVectorMemoryAdapter>[0] = {},
+) {
+  return createPgVectorMemoryAdapter(overrides)
+}
+
+// save 起始与写入之间推进时间轴，使 latencyMs 断言可预测
+function advanceNowBy(step: number): number {
+  let value = 0
+  vi.spyOn(performance, "now").mockImplementation(() => {
+    value += step
+    return value
+  })
+  return step
+}
+
+function factRow(id: string, similarity: number, content = `内容${id}`) {
+  return {
+    id,
+    content,
+    threadId: "thread-a",
+    createdAt: new Date("2026-09-01T00:00:00Z"),
+    similarity,
+  }
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mocks.executeRawUnsafe.mockResolvedValue(1)
+  mocks.queryRawUnsafe.mockResolvedValue([])
+  mocks.generateEmbedding.mockResolvedValue(VECTOR_4)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe("pgvector MemoryAdapter.save", () => {
+  it("持久化 turn（embedding + 原文）并返回 ok 与 latencyMs", async () => {
+    advanceNowBy(25)
+    const adapter = makeAdapter()
+
+    const receipts = await adapter.save(scope, {
+      user: "我偏好使用深色主题",
+      assistant: "好的，我记住了你偏好深色主题。",
+    })
+
+    expect(receipts).toHaveLength(1)
+    expect(receipts[0]).toMatchObject({ ok: true })
+    expect(receipts[0].latencyMs).toBe(25)
+
+    const [sql, id, userId, threadId, content, embeddingStr] =
+      mocks.executeRawUnsafe.mock.calls[0]
+    expect(String(sql)).toContain('INSERT INTO "memory_facts"')
+    expect(String(sql)).toContain("$5::vector")
+    expect(String(userId)).toBe("user-1")
+    expect(String(threadId)).toBe("thread-a")
+    expect(String(content)).toContain("我偏好使用深色主题")
+    expect(String(embeddingStr)).toBe("[0.1,0.2,0.3,0.4]")
+    expect(String(id)).toMatch(/^[0-9a-f-]{36}$/)
+  })
+
+  it("写入失败返回 ok:false + error，不抛错阻断对话", async () => {
+    advanceNowBy(25)
+    mocks.executeRawUnsafe.mockRejectedValueOnce(
+      new Error('relation "memory_facts" does not exist'),
+    )
+    const adapter = makeAdapter()
+
+    const receipts = await adapter.save(scope, {
+      user: "我偏好使用深色主题",
+      assistant: "好的。",
+    })
+
+    expect(receipts).toHaveLength(1)
+    expect(receipts[0].ok).toBe(false)
+    expect(receipts[0].error).toContain("relation")
+    expect(receipts[0].latencyMs).toBe(25)
+  })
+
+  it("recall 有数据时返回非空 systemPrompt + 带 source 的 fragments", async () => {
+    seedExistingFacts(2)
+    mocks.queryRawUnsafe.mockResolvedValue([
+      factRow("fact-a", 0.9, "用户偏好深色主题"),
+      factRow("fact-b", 0.8, "用户在杭州"),
+    ])
+    const adapter = makeAdapter()
+
+    const result = await adapter.recall(scope, "我一般用深色模式吗")
+
+    expect(mocks.generateEmbedding).toHaveBeenCalledTimes(1)
+    expect(result.systemPrompt).not.toBe("")
+    expect(result.systemPrompt).toContain("用户偏好深色主题")
+    expect(result.fragments).toHaveLength(2)
+    expect(result.fragments![0]).toEqual({
+      text: "用户偏好深色主题",
+      source: "fact-a",
+    })
+  })
+
+  it("检索返回空数组时返回空 systemPrompt（middleware 会跳过注入）", async () => {
+    seedExistingFacts(1)
+    mocks.queryRawUnsafe.mockResolvedValue([])
+    const adapter = makeAdapter()
+
+    const result = await adapter.recall(scope, "随便问问")
+
+    expect(mocks.generateEmbedding).toHaveBeenCalledTimes(1)
+    expect(result).toEqual({ systemPrompt: "" })
+    expect(result.fragments).toBeUndefined()
+  })
+
+  it("recall 用 userId 过滤，跨用户零泄露", async () => {
+    seedExistingFacts(1)
+    mocks.queryRawUnsafe.mockResolvedValue([])
+    const adapter = makeAdapter()
+
+    const result = await adapter.recall(scope, "我在哪里")
+
+    expect(mocks.generateEmbedding).toHaveBeenCalledTimes(1)
+    const [sql, ...values] = mocks.queryRawUnsafe.mock.calls[1]!
+    expect(String(sql)).toContain('WHERE "userId" = $2')
+    expect(String(values[1])).toBe("user-1")
+    expect(result).toEqual({ systemPrompt: "" })
+  })
+
+  it("低于相似度阈值的结果被丢弃", async () => {
+    seedExistingFacts(1)
+    mocks.queryRawUnsafe.mockResolvedValue([
+      factRow("fact-low", DEFAULT_SIMILARITY_THRESHOLD - 0.05, "无关内容"),
+    ])
+    const adapter = makeAdapter()
+
+    expect(await adapter.recall(scope, "查询")).toEqual({ systemPrompt: "" })
+    expect(mocks.generateEmbedding).toHaveBeenCalledTimes(1)
+  })
+
+  it("recall 结果按 topK 截断", async () => {
+    seedExistingFacts(10)
+    mocks.queryRawUnsafe.mockResolvedValue(
+      Array.from({ length: 10 }, (_, i) => factRow(`fact-${i}`, 0.9, `内容${i}`)),
+    )
+    const adapter = makeAdapter()
+
+    const result = await adapter.recall(scope, "查询")
+
+    expect(result.fragments).toHaveLength(DEFAULT_RECALL_TOP_K)
+    expect(mocks.generateEmbedding).toHaveBeenCalledTimes(1)
+  })
+
+  it("缺少 userId 的 scope 不写入也不召回（fail-closed）", async () => {
+    const adapter = makeAdapter()
+
+    expect(
+      await adapter.save(
+        { threadId: "thread-a" },
+        { user: "有效内容", assistant: "回复" },
+      ),
+    ).toEqual([{ ok: false, error: "memory scope missing userId" }])
+    expect(mocks.executeRawUnsafe).not.toHaveBeenCalled()
+
+    expect(await adapter.recall({ threadId: "thread-a" }, "查询")).toEqual({
+      systemPrompt: "",
+    })
+    expect(mocks.queryRawUnsafe).not.toHaveBeenCalled()
+  })
+
+  it("检索异常降级为空注入，不抛错", async () => {
+    seedExistingFacts(1)
+    mocks.generateEmbedding.mockRejectedValueOnce(new Error("embedding down"))
+    const adapter = makeAdapter()
+
+    expect(await adapter.recall(scope, "查询")).toEqual({ systemPrompt: "" })
+    expect(mocks.generateEmbedding).toHaveBeenCalledTimes(1)
+  })
+
+  it("过短/噪音 turn 被过滤，不产生写入也不调 embedding", async () => {
+    const adapter = makeAdapter()
+
+    const receipts = await adapter.save(scope, { user: "嗯", assistant: "好的" })
+
+    expect(receipts).toEqual([])
+    expect(mocks.executeRawUnsafe).not.toHaveBeenCalled()
+    expect(mocks.generateEmbedding).not.toHaveBeenCalled()
+  })
+
+  it("minUserChars 阈值可配置", async () => {
+    const adapter = makeAdapter({ minUserChars: 40 })
+
+    expect(
+      await adapter.save(scope, {
+        user: "这是一条超过阈值的用户输入内容",
+        assistant: "好的，已记住。",
+      }),
+    ).toEqual([])
+    expect(DEFAULT_MIN_USER_CHARS).toBeLessThan(40)
+    expect(mocks.executeRawUnsafe).not.toHaveBeenCalled()
+  })
+
+  it("assistant 为空时不写入", async () => {
+    const adapter = makeAdapter()
+
+    expect(
+      await adapter.save(scope, {
+        user: "足够长的用户输入内容",
+        assistant: "   ",
+      }),
+    ).toEqual([])
+    expect(mocks.executeRawUnsafe).not.toHaveBeenCalled()
+  })
+
+  it("embedding 为空向量时返回失败 receipt", async () => {
+    mocks.generateEmbedding.mockResolvedValue([])
+    const adapter = makeAdapter()
+
+    const receipts = await adapter.save(scope, {
+      user: "足够长的用户输入内容",
+      assistant: "回复",
+    })
+
+    expect(receipts).toHaveLength(1)
+    expect(receipts[0].ok).toBe(false)
+    expect(receipts[0].error).toContain("empty vector")
+    expect(mocks.executeRawUnsafe).not.toHaveBeenCalled()
+  })
+})
+
+describe("pgvector MemoryAdapter.recall 零记忆快路径", () => {
+  it("该用户尚无沉淀时零 embedding 调用", async () => {
+    mocks.queryRawUnsafe.mockResolvedValue([{ c: 0, lastWrite: null }])
+    const adapter = makeAdapter()
+
+    expect(await adapter.recall(scope, "我偏好什么")).toEqual({ systemPrompt: "" })
+    expect(mocks.generateEmbedding).not.toHaveBeenCalled()
+    expect(mocks.queryRawUnsafe).toHaveBeenCalledTimes(1)
+  })
+
+  it("有沉淀时才做 embedding + 向量检索", async () => {
+    mocks.queryRawUnsafe.mockResolvedValueOnce([{ c: 2, lastWrite: null }])
+    mocks.queryRawUnsafe.mockResolvedValue([factRow("fact-a", 0.9, "用户偏好深色主题")])
+    const adapter = makeAdapter()
+
+    const result = await adapter.recall(scope, "我一般用深色模式吗")
+
+    expect(mocks.generateEmbedding).toHaveBeenCalledWith("我一般用深色模式吗")
+    expect(result.systemPrompt).toContain("用户偏好深色主题")
+    expect(mocks.queryRawUnsafe).toHaveBeenCalledTimes(2)
+  })
+
+  it("计数查询先于向量检索（顺序是零成本前提，不可调换）", async () => {
+    seedExistingFacts(3)
+    mocks.queryRawUnsafe.mockResolvedValue([])
+    const adapter = makeAdapter()
+
+    await adapter.recall(scope, "查询")
+
+    expect(String(mocks.queryRawUnsafe.mock.calls[0]![0])).toContain("COUNT(*)")
+    expect(String(mocks.queryRawUnsafe.mock.calls[1]![0])).toContain("<=>")
+  })
+})
+
+describe("pgvector MemoryAdapter.inspect / listFacts", () => {
+  it("inspect 返回快照结构与计数", async () => {
+    mocks.queryRawUnsafe.mockResolvedValue([
+      { c: 7, lastWrite: new Date("2026-09-10T08:00:00Z") },
+    ])
+    const adapter = makeAdapter()
+
+    const snapshot = await adapter.inspect!(scope)
+
+    expect(snapshot.takenAt).toBeTruthy()
+    expect(snapshot.data).toMatchObject({
+      userId: "user-1",
+      threadId: "thread-a",
+      count: 7,
+      lastWrite: new Date("2026-09-10T08:00:00Z").getTime(),
+    })
+  })
+
+  it("inspect 无写入记录时 lastWrite 为 null", async () => {
+    mocks.queryRawUnsafe.mockResolvedValue([{ c: 0, lastWrite: null }])
+    const adapter = makeAdapter()
+
+    expect(await adapter.inspect!(scope)).toMatchObject({
+      data: { userId: "user-1", count: 0, lastWrite: null },
+    })
+  })
+
+  it("listFacts 返回 id/text/source/createdAt 结构", async () => {
+    mocks.queryRawUnsafe.mockResolvedValue([
+      {
+        id: "f1",
+        content: "事实一",
+        threadId: "thread-a",
+        createdAt: new Date("2026-09-01T00:00:00Z"),
+      },
+    ])
+    const adapter = makeAdapter()
+
+    expect(await adapter.listFacts!(scope)).toEqual([
+      {
+        id: "f1",
+        text: "事实一",
+        source: "thread-a",
+        createdAt: "2026-09-01T00:00:00.000Z",
+      },
+    ])
+  })
+
+  it("listFacts 缺少 userId 返回空数组", async () => {
+    const adapter = makeAdapter()
+
+    expect(await adapter.listFacts!({ threadId: "thread-a" })).toEqual([])
+    expect(mocks.queryRawUnsafe).not.toHaveBeenCalled()
+  })
+})
+
+describe("memory scope 归属校验", () => {
+  const fakeCtx = { threadId: "thread-a" } as never
+
+  it("thread 属于当前用户时产出可写 scope", async () => {
+    mocks.chatThreadFindUnique.mockResolvedValue({
+      id: "thread-a",
+      userId: "user-1",
+    })
+    const resolve = createMemoryScopeResolver("user-1")
+
+    expect(await resolve(fakeCtx)).toEqual({
+      threadId: "thread-a",
+      userId: "user-1",
+    })
+  })
+
+  it("thread 属于他人时抛错，不产出可写 scope", async () => {
+    mocks.chatThreadFindUnique.mockResolvedValue({
+      id: "thread-a",
+      userId: "user-2",
+    })
+    const resolve = createMemoryScopeResolver("user-1")
+
+    await expect(resolve(fakeCtx)).rejects.toThrow(MemoryScopeError)
+  })
+
+  it("thread 不存在时抛错", async () => {
+    mocks.chatThreadFindUnique.mockResolvedValue(null)
+    const resolve = createMemoryScopeResolver("user-1")
+
+    await expect(resolve(fakeCtx)).rejects.toThrow(MemoryScopeError)
+  })
+
+  it("归属查询异常时抛错（fail-closed，不误用他人 scope）", async () => {
+    mocks.chatThreadFindUnique.mockRejectedValueOnce(new Error("db down"))
+    const resolve = createMemoryScopeResolver("user-1")
+
+    await expect(resolve(fakeCtx)).rejects.toThrow("db down")
+  })
+})

package/src/server/ai-gateway/__tests__/plugin-lifecycle.test.ts

@@ -0,0 +1,57 @@
+// 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 { describe, it, expect } from "vitest";
+import {
+  pluginDefineDef,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+  pluginInspectListDef,
+  pluginLifecycleDefs,
+} from "../tools/plugin-lifecycle-defs";
+
+describe("plugin lifecycle tool definitions", () => {
+  it("exports all 5 lifecycle tools", () => {
+    expect(pluginLifecycleDefs).toHaveLength(5);
+  });
+
+  it("plugin_define has correct schema", () => {
+    expect(pluginDefineDef.name).toBe("plugin_define");
+    expect(pluginDefineDef.description).toContain("dsh");
+  });
+
+  it("plugin_run has correct schema", () => {
+    expect(pluginRunDef.name).toBe("plugin_run");
+    expect(pluginRunDef.description).toContain("启动");
+  });
+
+  it("plugin_stop has correct schema", () => {
+    expect(pluginStopDef.name).toBe("plugin_stop");
+    expect(pluginStopDef.description).toContain("停止");
+  });
+
+  it("plugin_undefine has correct schema", () => {
+    expect(pluginUndefineDef.name).toBe("plugin_undefine");
+    expect(pluginUndefineDef.description).toContain("删除");
+  });
+
+  it("plugin_inspect_list has correct schema", () => {
+    expect(pluginInspectListDef.name).toBe("plugin_inspect_list");
+    expect(pluginInspectListDef.description).toContain("列出");
+  });
+});