@allbluecn/web-app 0.22.4 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allbluecn/web-app",
-  "version": "0.22.4",
+  "version": "0.23.1",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "files": [
@@ -62,6 +62,7 @@
     "@allbluecn/collab-core": "0.2.0",
     "@allbluecn/database": "0.12.1",
     "@allbluecn/kernel": "0.12.0",
+    "@allbluecn/sync-core": "0.5.4",
     "@ariakit/react": "^0.4.28",
     "@auth/core": "^0.41.2",
     "@auth/prisma-adapter": "^2.11.2",
@@ -69,7 +70,6 @@
     "@aws-sdk/credential-providers": "3.1131.0",
     "@base-ui/react": "^1.8.0",
     "@date-fns/tz": "^1.5.0",
-    "@devframes/vite": "1.0.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/dom": "0.5.0",
     "@dnd-kit/react": "^0.5.0",
@@ -114,8 +114,6 @@
     "@tanstack/ai-client": "1.0.0",
     "@tanstack/ai-code-mode": "1.0.0",
     "@tanstack/ai-codex": "1.0.0",
-    "@tanstack/ai-devtools-core": "1.0.0",
-    "@tanstack/ai-event-client": "1.0.0",
     "@tanstack/ai-fal": "1.0.0",
     "@tanstack/ai-gemini": "1.0.0",
     "@tanstack/ai-grok": "1.0.0",
@@ -134,11 +132,10 @@
     "@tanstack/ai-sandbox-vercel": "1.0.0",
     "@tanstack/ai-skills": "1.0.0",
     "@tanstack/ai-utils": "1.0.0",
-    "@tanstack/db": "1.0.0-rc.1",
+    "@tanstack/charts": "^1.1.0",
     "@tanstack/hotkeys": "^0.18.0",
     "@tanstack/markdown": "^1.0.0",
     "@tanstack/pacer": "^0.23.1",
-    "@tanstack/query-db-collection": "1.5.0",
     "@tanstack/react-form": "2.0.0-alpha.3",
     "@tanstack/react-hotkeys": "^0.17.0",
     "@tanstack/react-pacer": "^0.24.1",
@@ -238,8 +235,7 @@
     "tailwind-merge": "^3.5.0",
     "tw-animate-css": "^1.4.0",
     "yjs": "^13.6.33",
-    "zod": "^4.6.7",
-    "@allbluecn/sync-core": "0.5.4"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@babel/parser": "^8.0.4",
@@ -251,9 +247,6 @@
     "@playwright/mcp": "^0.0.75",
     "@playwright/test": "^1.60.0",
     "@tailwindcss/vite": "^4.3.3",
-    "@tanstack/devtools": "0.15.0",
-    "@tanstack/devtools-ui": "0.7.1",
-    "@tanstack/react-ai-devtools": "1.0.0",
     "@tanstack/react-query-devtools": "5.104.5",
     "@tanstack/react-router-devtools": "1.167.2",
     "@testing-library/jest-dom": "7.0.1",
@@ -293,9 +286,6 @@
     "version": "7.8.0",
     "seed": "tsx ../../packages/database/seed.ts"
   },
-  "optionalDependencies": {
-    "@tauri-apps/api": "^2.11.1"
-  },
   "scripts": {
     "dev": "vite --port 3000",
     "build": "vite build",

package/src/__tests__/integration/login-email-acceptance.test.ts

@@ -9,6 +9,12 @@ vi.mock('@tanstack/react-start', () => ({
   createServerFn: (config: any) => {
     const api: any = {
       _validator: undefined,
+      // 被测 fn（register/confirm/forgot）均为白名单公开流，无 middleware 链；
+      // 此处仅为模块加载期 .middleware() 链式调用兼容（email-verification 模块
+      // 内 resendVerificationEmailFn 已迁 authContextMiddleware）
+      middleware(_mws: unknown[]) {
+        return this
+      },
       validator(schema: any) {
         this._validator = schema
         return this
@@ -26,6 +32,16 @@ vi.mock('@tanstack/react-start', () => ({
     }
     return api
   },
+  // auth-context.ts 依赖 createMiddleware({ type: 'function' }).server(fn)：
+  // mock 产出与真实 middleware 同构形状，模块加载期即可求值
+  createMiddleware: (opts: any) => {
+    const mw: any = { options: { type: opts?.type } }
+    mw.server = (fn: Function) => {
+      mw.options.server = fn
+      return mw
+    }
+    return mw
+  },
 }))
 
 vi.mock('@tanstack/react-start/server', () => ({

package/src/__tests__/story-view.test.ts

@@ -33,6 +33,11 @@ vi.mock("@tanstack/react-start", () => ({
   createServerFn: (config: any) => {
     const api: any = {
       _validator: undefined,
+      _middlewares: [] as any[],
+      middleware(mws: any[]) {
+        this._middlewares.push(...mws);
+        return this;
+      },
       validator(schema: any) {
         this._validator = schema;
         return this;
@@ -43,13 +48,40 @@ vi.mock("@tanstack/react-start", () => ({
           if (this._validator && data !== undefined) {
             data = this._validator.parse ? this._validator.parse(data) : data;
           }
-          return fn({ data });
+          // 迁移后经 .middleware([authContextMiddleware]) 注入 context.user：
+          // 依序执行 middleware 的 server 段，真实鉴权链由被 mock 的 auth-helpers 承接
+          let context: any = {};
+          for (const mw of this._middlewares) {
+            const serverFn = mw?.options?.server;
+            if (!serverFn) continue;
+            const result = await serverFn({
+              data,
+              context,
+              method: "POST",
+              serverFnMeta: {},
+              signal: new AbortController().signal,
+              next: async (inner: any) => ({ context: { ...context, ...(inner?.context ?? {}) } }),
+            });
+            context = result.context;
+          }
+          return fn({ data, context });
         };
         return wrapped;
       },
     };
     return api;
   },
+  // auth-context.ts 依赖 createMiddleware({ type: 'function' }).server(fn)：
+  // mock 产出与真实 middleware 同构的 { options: { server } } 形状，
+  // 供上方 handler 包装器执行 server 段注入 context.user
+  createMiddleware: (opts: any) => {
+    const mw: any = { options: { type: opts?.type } };
+    mw.server = (fn: Function) => {
+      mw.options.server = fn;
+      return mw;
+    };
+    return mw;
+  },
 }));
 
 vi.mock("@tanstack/react-start/server", () => ({

package/src/components/agents/__tests__/agent-bindings-tab.test.tsx

@@ -0,0 +1,221 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// agent-bindings 乐观更新竞态回归（TanStack 优化任务 12 / audit P1#9）。
+//
+// 旧实现在 handleChange 里手写 setQueryData 乐观写 + catch 手动回滚，缺
+// cancelQueries——mutation 前已在途的 refetch 若在乐观写之后才 resolve，
+// 会把乐观值覆盖回旧值（官方 Optimistic Updates 指南明确警告的场景：
+// 用户看到选择被"弹回"旧值，直到 invalidate 的二次 refetch 才恢复）。
+// 迁移后走官方 onMutate（cancelQueries + 快照 + 乐观写）/ onError（回滚）
+// / onSettled（invalidate）三段式：在途 refetch 在 mutation 启动时即被
+// 取消，其迟到的旧值永不落缓存。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act, cleanup, render, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+vi.mock('@/server/serverFns/agents/agent-crud', () => ({
+  listAgentsFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/agents/skill-crud', () => ({
+  listSkillsFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/agents/bindings', () => ({
+  listBindingsFn: vi.fn(),
+  upsertBindingFn: vi.fn(),
+  setDefaultAgentFn: vi.fn(),
+  getPersonaHintFn: vi.fn(),
+}))
+
+import { AgentBindingsTab } from '../agent-bindings-tab'
+import { AGENT_BINDINGS_QUERY_KEY } from '@/lib/queries/agents'
+import { listAgentsFn } from '@/server/serverFns/agents/agent-crud'
+import { listBindingsFn, upsertBindingFn } from '@/server/serverFns/agents/bindings'
+
+type Row = {
+  bizKey: string
+  agentId: string
+  agent: { id: string; name: string; avatarEmoji: string | null; isDefault: boolean } | null
+}
+
+const BOUND_KEY = 'story.pm'
+const OTHER_KEY = 'label.suggest'
+
+type AgentDto = Awaited<ReturnType<typeof listAgentsFn>>[number]
+
+/** 补齐 listAgentsFn 真实 DTO 的必填字段，组件只用 id/name/avatarEmoji/isDefault */
+const makeAgent = (
+  over: { id: string; name: string; avatarEmoji: string | null; isDefault: boolean },
+): AgentDto => ({
+  description: null,
+  systemPrompt: '',
+  allowedTools: [],
+  model: null,
+  temperature: null,
+  greeting: null,
+  suggestedPrompts: null,
+  knowledgeBaseIds: [],
+  createdAt: new Date('2026-01-01T00:00:00Z'),
+  updatedAt: new Date('2026-01-01T00:00:00Z'),
+  ...over,
+})
+
+const agentA = makeAgent({ id: 'agent-a', name: 'A 助手', avatarEmoji: '🤖', isDefault: true })
+const agentB = makeAgent({ id: 'agent-b', name: 'B 助手', avatarEmoji: null, isDefault: false })
+const agentC = makeAgent({ id: 'agent-c', name: 'C 助手', avatarEmoji: null, isDefault: false })
+
+const row = (bizKey: string, agent: AgentDto): Row => ({
+  bizKey,
+  agentId: agent.id,
+  agent: { id: agent.id, name: agent.name, avatarEmoji: agent.avatarEmoji, isDefault: agent.isDefault },
+})
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+const clients: QueryClient[] = []
+
+function renderTab() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  })
+  clients.push(client)
+  render(
+    <QueryClientProvider client={client}>
+      <AgentBindingsTab />
+    </QueryClientProvider>,
+  )
+  return client
+}
+
+/** 定位「已绑定指定 agent 名」那一行的 Select trigger（各业务键行结构一致） */
+async function findBoundTrigger(agentName: string): Promise<HTMLElement> {
+  return waitFor(() => {
+    const el = [...document.querySelectorAll<HTMLElement>('[data-slot="select-trigger"]')].find(
+      (t) => (t.textContent ?? '').includes(agentName),
+    )
+    if (!el) throw new Error(`未渲染出绑定 ${agentName} 的行`)
+    return el
+  })
+}
+
+async function openAndPick(user: ReturnType<typeof userEvent.setup>, trigger: HTMLElement, label: string) {
+  await user.click(trigger)
+  // Base UI popup 经 portal 异步挂载，且关闭后选项 DOM 残留（pointer-events:none），
+  // 必须按「可点击」过滤 + 显式等待（同 select.test.tsx 口径）
+  const option = await waitFor(() => {
+    const el = [...document.querySelectorAll('[role="option"]')].find(
+      (el) => (el.textContent ?? '').includes(label) && getComputedStyle(el).pointerEvents !== 'none',
+    )
+    if (!el) throw new Error(`选项 ${label} 未打开`)
+    return el
+  })
+  await user.click(option)
+}
+
+const readBoundAgentId = (client: QueryClient, bizKey: string) =>
+  client.getQueryData<Row[]>(AGENT_BINDINGS_QUERY_KEY)?.find((r) => r.bizKey === bizKey)?.agentId
+
+beforeEach(() => {
+  // shouldAdvanceTime：让 RTL waitFor 的轮询 timer 走真实节奏，否则 fake timer
+  // 下 polling 永不触发、waitFor 全部超时；调度确定性仍由显式 advance 控制
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+  // 兜底实现（各用例按需覆盖）：避免 mockImplementationOnce 泄漏时 queryFn 返回 undefined
+  vi.mocked(listAgentsFn).mockResolvedValue([])
+  vi.mocked(listBindingsFn).mockResolvedValue([])
+  vi.mocked(upsertBindingFn).mockResolvedValue(undefined as never)
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  // reset 而非 clear：mockClear 不清 mockImplementationOnce 队列，上一用例未消费的
+  // 一次性实现会泄漏到下一用例（首用例的 afterInvalidate 泄漏曾让次用例首拉挂起）
+  vi.resetAllMocks()
+  clients.length = 0
+})
+
+describe('AgentBindingsTab 乐观更新（官方 onMutate 通道）', () => {
+  it('在途 refetch 迟到返回旧值不覆盖乐观绑定（cancelQueries 竞态防线），终态为新值', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    const firstLoad = deferred<Row[]>()
+    const inFlight = deferred<Row[]>()
+    const mutation = deferred<{ ok: true }>()
+    const afterInvalidate = deferred<Row[]>()
+
+    vi.mocked(listBindingsFn)
+      .mockImplementationOnce(() => firstLoad.promise)
+      .mockImplementationOnce(() => inFlight.promise)
+      .mockImplementationOnce(() => afterInvalidate.promise)
+    vi.mocked(listAgentsFn).mockResolvedValue([agentA, agentB, agentC])
+    vi.mocked(upsertBindingFn).mockImplementation(() => mutation.promise)
+
+    const client = renderTab()
+
+    // 首屏加载完成：story.pm 绑定 agent-a
+    firstLoad.resolve([row(BOUND_KEY, agentA)])
+    await waitFor(() => expect(readBoundAgentId(client, BOUND_KEY)).toBe('agent-a'))
+
+    // mutation 前触发一次 refetch（模拟他处失效/聚焦重拉），延迟返回旧值
+    void client.invalidateQueries({ queryKey: AGENT_BINDINGS_QUERY_KEY })
+    await waitFor(() => expect(listBindingsFn).toHaveBeenCalledTimes(2))
+
+    // 用户把 story.pm 切到 agent-b：乐观写立刻落地，服务端调用挂起
+    const trigger = await findBoundTrigger('A 助手')
+    await openAndPick(user, trigger, 'B 助手')
+    await waitFor(() => expect(readBoundAgentId(client, BOUND_KEY)).toBe('agent-b'))
+    expect(upsertBindingFn).toHaveBeenCalledTimes(1)
+    // 乐观写不得触发新拉取（取消/失效只允许出现在官方通道的固定时机）
+    expect(listBindingsFn).toHaveBeenCalledTimes(2)
+
+    // 竞态核心断言：在途 refetch 此刻 resolve 旧值，乐观值必须不被覆盖
+    await act(async () => {
+      inFlight.resolve([row(BOUND_KEY, agentA)])
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    expect(readBoundAgentId(client, BOUND_KEY)).toBe('agent-b')
+
+    // mutation 成功 → onSettled invalidate 拉取服务端真相 → 终态为新值
+    mutation.resolve({ ok: true })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    await waitFor(() => expect(listBindingsFn).toHaveBeenCalledTimes(3))
+    afterInvalidate.resolve([row(BOUND_KEY, agentB)])
+    await waitFor(() => expect(client.getQueryData<Row[]>(AGENT_BINDINGS_QUERY_KEY)).toEqual([row(BOUND_KEY, agentB)]))
+    expect(readBoundAgentId(client, BOUND_KEY)).toBe('agent-b')
+
+    // UI 终态：trigger 回显新选项
+    await waitFor(() => {
+      const el = [...document.querySelectorAll('[data-slot="select-trigger"]')].find((t) =>
+        (t.textContent ?? '').includes('B 助手'),
+      )
+      expect(el).toBeTruthy()
+    })
+  })
+
+  it('mutation 失败按快照回滚本 bizKey 行，不覆盖其他键的并发变更', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    vi.mocked(listBindingsFn).mockResolvedValue([row(BOUND_KEY, agentA), row(OTHER_KEY, agentC)])
+    vi.mocked(listAgentsFn).mockResolvedValue([agentA, agentB, agentC])
+    vi.mocked(upsertBindingFn).mockRejectedValue(new Error('boom'))
+
+    const client = renderTab()
+
+    await waitFor(() => expect(client.getQueryData<Row[]>(AGENT_BINDINGS_QUERY_KEY)).toHaveLength(2))
+
+    const trigger = await findBoundTrigger('A 助手')
+    await openAndPick(user, trigger, 'B 助手')
+
+    // 失败后：story.pm 回滚为 agent-a，label.suggest 行不受影响
+    await waitFor(() => expect(readBoundAgentId(client, BOUND_KEY)).toBe('agent-a'))
+    expect(readBoundAgentId(client, OTHER_KEY)).toBe('agent-c')
+  })
+})

package/src/components/agents/__tests__/agents-page.test.tsx

@@ -0,0 +1,284 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// agents-page 删除乐观更新竞态回归（TanStack 优化任务 12）。
+//
+// 旧实现在删除 serverFn 成功后才 setQueryData 移除 + invalidate，无
+// cancelQueries：确认删除到服务端返回之间 UI 无任何反馈，且在途 refetch
+// （mutation 前触发）可能把已删项写回缓存。迁移为官方三段式后：onMutate
+// 里 cancelQueries + 乐观移除（删除即时生效、在途旧值被取消不落缓存）、
+// onError 回滚快照、onSettled invalidate 对齐服务端真相。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { createElement, Fragment, type ReactNode } from 'react'
+
+vi.mock('@/server/serverFns/agents/agent-crud', () => ({
+  listAgentsFn: vi.fn(),
+  createAgentFn: vi.fn(),
+  updateAgentFn: vi.fn(),
+  deleteAgentFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/agents/skill-crud', () => ({
+  listSkillsFn: vi.fn(),
+  createSkillFn: vi.fn(),
+  updateSkillFn: vi.fn(),
+  deleteSkillFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/agents/bindings', () => ({
+  listBindingsFn: vi.fn(),
+  upsertBindingFn: vi.fn(),
+  setDefaultAgentFn: vi.fn(),
+  getPersonaHintFn: vi.fn(),
+}))
+vi.mock('@/lib/ai/use-knowledge-bases', () => ({
+  useKnowledgeBases: vi.fn(() => []),
+}))
+// 删除流程不经过计费门控；useFeature 的 billing 查询链与本任务无关，直接放行
+vi.mock('@/components/billing/feature-gate', async () => {
+  const react = (await import('react')) as typeof import('react')
+  return {
+    FeatureGate: ({ children }: { children?: ReactNode }) =>
+      createElement(Fragment, null, children),
+  }
+})
+
+import { AgentsPage } from '../agents-page'
+import { AGENTS_QUERY_KEY, SKILLS_QUERY_KEY } from '@/lib/queries/agents'
+import { listAgentsFn, deleteAgentFn } from '@/server/serverFns/agents/agent-crud'
+import { listSkillsFn, deleteSkillFn } from '@/server/serverFns/agents/skill-crud'
+import { m } from '@/paraglide/messages.js'
+
+type AgentDto = Awaited<ReturnType<typeof listAgentsFn>>[number]
+
+/** 补齐 listAgentsFn 真实 DTO 必填字段（卡片只消费 id/name/description/isDefault 等） */
+const makeAgent = (over: { id: string; name: string; isDefault?: boolean }): AgentDto => ({
+  description: null,
+  avatarEmoji: null,
+  systemPrompt: '',
+  allowedTools: [],
+  model: null,
+  temperature: null,
+  greeting: null,
+  suggestedPrompts: null,
+  knowledgeBaseIds: [],
+  isDefault: false,
+  createdAt: new Date('2026-01-01T00:00:00Z'),
+  updatedAt: new Date('2026-01-01T00:00:00Z'),
+  ...over,
+})
+
+const agentX = makeAgent({ id: 'agent-x', name: 'X 智能体' })
+const agentY = makeAgent({ id: 'agent-y', name: 'Y 智能体', isDefault: true })
+
+type SkillDto = Awaited<ReturnType<typeof listSkillsFn>>[number]
+
+/** 补齐 listSkillsFn 真实 DTO 必填字段（卡片只消费 id/name/title/template） */
+const makeSkill = (over: { id: string; name: string; title: string }): SkillDto => ({
+  userId: 'u1',
+  template: 'tpl',
+  createdAt: new Date('2026-01-01T00:00:00Z'),
+  updatedAt: new Date('2026-01-01T00:00:00Z'),
+  ...over,
+})
+
+const skillX = makeSkill({ id: 'skill-x', name: 'skill-x', title: 'X 技能' })
+const skillY = makeSkill({ id: 'skill-y', name: 'skill-y', title: 'Y 技能' })
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+const clients: QueryClient[] = []
+
+function renderPage() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  })
+  clients.push(client)
+  render(
+    <QueryClientProvider client={client}>
+      <AgentsPage />
+    </QueryClientProvider>,
+  )
+  return client
+}
+
+const readCache = (client: QueryClient, key: readonly unknown[]) =>
+  client.getQueryData<Array<{ id: string }>>(key) ?? []
+
+/** 确认 NameConfirmDialog（输入预期名称 + 点击确认按钮） */
+async function confirmDeleteDialog(
+  user: ReturnType<typeof userEvent.setup>,
+  expectedName: string,
+  confirmText: string,
+) {
+  const dialog = await screen.findByRole('dialog')
+  fireEvent.change(within(dialog).getByPlaceholderText(
+    m.common_nameConfirm_inputPlaceholder({ expectedName }),
+  ), { target: { value: expectedName } })
+  fireEvent.click(within(dialog).getByRole('button', { name: confirmText }))
+}
+
+/** 打开 agent 卡片的行内菜单并点击删除项 */
+async function openAgentMenuAndDelete(user: ReturnType<typeof userEvent.setup>, agentName: string) {
+  const card = await screen.findByText(agentName)
+  const trigger = card.closest('[data-slot="card"]')?.querySelector('[data-slot="dropdown-menu-trigger"]')
+  if (!trigger) throw new Error('未找到 agent 卡片菜单触发器')
+  await user.click(trigger as HTMLElement)
+  const item = await waitFor(() => {
+    const el = [...document.querySelectorAll('[role="menuitem"]')].find(
+      (el) => (el.textContent ?? '').includes(m.agents_card_delete()) &&
+        getComputedStyle(el).pointerEvents !== 'none',
+    )
+    if (!el) throw new Error('菜单未打开')
+    return el
+  })
+  await user.click(item)
+}
+
+beforeEach(() => {
+  // shouldAdvanceTime：让 RTL waitFor 的轮询 timer 走真实节奏；调度确定性仍由显式 advance 控制
+  vi.useFakeTimers({ shouldAdvanceTime: true })
+  vi.mocked(listAgentsFn).mockResolvedValue([])
+  vi.mocked(listSkillsFn).mockResolvedValue([])
+  vi.mocked(deleteAgentFn).mockResolvedValue(undefined as never)
+  vi.mocked(deleteSkillFn).mockResolvedValue(undefined as never)
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+  // reset 而非 clear：mockClear 不清 mockImplementationOnce 队列，会泄漏到下一用例
+  vi.resetAllMocks()
+  clients.length = 0
+})
+
+describe('AgentsPage 删除乐观更新（官方 onMutate 通道）', () => {
+  it('agent 删除即时乐观移除，在途 refetch 返回旧列表不复活已删项，终态与服务端一致', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    const inFlight = deferred<AgentDto[]>()
+    const mutation = deferred<{ success: true }>()
+    const afterInvalidate = deferred<AgentDto[]>()
+
+    vi.mocked(listAgentsFn)
+      .mockImplementationOnce(() => Promise.resolve([agentX, agentY]))
+      .mockImplementationOnce(() => inFlight.promise)
+      .mockImplementationOnce(() => afterInvalidate.promise)
+    vi.mocked(deleteAgentFn).mockImplementation(() => mutation.promise)
+
+    const client = renderPage()
+    await screen.findByText('X 智能体')
+
+    // mutation 前触发一次 refetch（在途、延迟返回仍含已删项的旧列表）
+    void client.invalidateQueries({ queryKey: AGENTS_QUERY_KEY })
+    await waitFor(() => expect(listAgentsFn).toHaveBeenCalledTimes(2))
+
+    await openAgentMenuAndDelete(user, 'X 智能体')
+    await confirmDeleteDialog(user, 'X 智能体', m.agents_agent_deleteConfirmText())
+
+    // 乐观移除即时生效（不等服务端返回），且不触发新拉取
+    await waitFor(() => {
+      expect(readCache(client, AGENTS_QUERY_KEY).find((a) => a.id === 'agent-x')).toBeUndefined()
+    })
+    expect(deleteAgentFn).toHaveBeenCalledTimes(1)
+    expect(listAgentsFn).toHaveBeenCalledTimes(2)
+
+    // 竞态核心断言：在途 refetch 此刻返回仍含 agent-x 的旧列表，不得复活已删项
+    await act(async () => {
+      inFlight.resolve([agentX, agentY])
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    expect(readCache(client, AGENTS_QUERY_KEY).find((a) => a.id === 'agent-x')).toBeUndefined()
+
+    // 服务端确认 → onSettled invalidate → 终态列表无 agent-x
+    mutation.resolve({ success: true })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    await waitFor(() => expect(listAgentsFn).toHaveBeenCalledTimes(3))
+    afterInvalidate.resolve([agentY])
+    await waitFor(() => {
+      expect(readCache(client, AGENTS_QUERY_KEY).map((a) => a.id)).toEqual(['agent-y'])
+    })
+    await waitFor(() => expect(screen.queryByText('X 智能体')).toBeNull())
+  })
+
+  it('skill 删除乐观移除 + 在途旧值不复活（同构竞态）', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    const inFlight = deferred<SkillDto[]>()
+    const mutation = deferred<{ success: true }>()
+    const afterInvalidate = deferred<SkillDto[]>()
+
+    vi.mocked(listSkillsFn)
+      .mockImplementationOnce(() => Promise.resolve([skillX, skillY]))
+      .mockImplementationOnce(() => inFlight.promise)
+      .mockImplementationOnce(() => afterInvalidate.promise)
+    vi.mocked(deleteSkillFn).mockImplementation(() => mutation.promise)
+
+    const client = renderPage()
+
+    // 切到 skills tab
+    fireEvent.click(screen.getByRole('tab', { name: new RegExp(m.agents_page_tabs_skills()) }))
+    await screen.findByText('X 技能')
+
+    void client.invalidateQueries({ queryKey: SKILLS_QUERY_KEY })
+    await waitFor(() => expect(listSkillsFn).toHaveBeenCalledTimes(2))
+
+    // SkillCard 根节点为无 data-slot 的 .group div；卡片内含编辑/删除两个按钮，按图标类区分
+    const skillCard = await screen.findByText('X 技能')
+    const cardRoot = skillCard.closest('.group')!
+    const deleteBtn = [...cardRoot.querySelectorAll('button')].find((b) =>
+      b.querySelector('.lucide-trash-2'),
+    )
+    if (!deleteBtn) throw new Error('未找到 skill 删除按钮')
+    fireEvent.click(deleteBtn)
+    await confirmDeleteDialog(user, 'X 技能', m.agents_skill_deleteConfirmText())
+
+    await waitFor(() => {
+      expect(readCache(client, SKILLS_QUERY_KEY).find((s) => s.id === 'skill-x')).toBeUndefined()
+    })
+    expect(deleteSkillFn).toHaveBeenCalledTimes(1)
+    expect(listSkillsFn).toHaveBeenCalledTimes(2)
+
+    await act(async () => {
+      inFlight.resolve([skillX, skillY])
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    expect(readCache(client, SKILLS_QUERY_KEY).find((s) => s.id === 'skill-x')).toBeUndefined()
+
+    mutation.resolve({ success: true })
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(50)
+    })
+    await waitFor(() => expect(listSkillsFn).toHaveBeenCalledTimes(3))
+    afterInvalidate.resolve([skillY])
+    await waitFor(() => {
+      expect(readCache(client, SKILLS_QUERY_KEY).map((s) => s.id)).toEqual(['skill-y'])
+    })
+  })
+
+  it('agent 删除失败回滚快照（卡片重新出现）', async () => {
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+    vi.mocked(listAgentsFn).mockResolvedValue([agentX, agentY])
+    vi.mocked(deleteAgentFn).mockRejectedValue(new Error('boom'))
+
+    const client = renderPage()
+    await screen.findByText('X 智能体')
+
+    await openAgentMenuAndDelete(user, 'X 智能体')
+    await confirmDeleteDialog(user, 'X 智能体', m.agents_agent_deleteConfirmText())
+
+    // 乐观移除后服务端失败 → onError 回滚快照
+    await waitFor(() => {
+      expect(readCache(client, AGENTS_QUERY_KEY).find((a) => a.id === 'agent-x')).toBeDefined()
+    })
+    expect(readCache(client, AGENTS_QUERY_KEY).find((a) => a.id === 'agent-y')).toBeDefined()
+  })
+})