@allbluecn/web-app 0.22.4 → 0.23.1

package/src/lib/hotkeys/registry.ts

@@ -15,92 +15,189 @@
 // 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 { HotkeyCategory, HotkeyDefinition } from "./types"
+import { AppHotkeysStore, defineAppHotkeys, type Hotkey } from "@tanstack/hotkeys"
 
-export const HOTKEY_REGISTRY: HotkeyDefinition[] = [
-  {
-    id: "shortcuts-panel",
-    keys: "Mod+/",
-    scope: "global",
-    descriptionKey: "common_hotkey_desc_shortcutsPanel",
-    category: "导航",
-  },
-  {
-    id: "toggle-sidebar",
-    keys: "Mod+B",
-    scope: "global",
-    descriptionKey: "common_hotkey_desc_toggleSidebar",
-    category: "导航",
-  },
-  {
-    id: "save",
-    keys: "Mod+S",
-    scope: "app",
-    descriptionKey: "common_hotkey_desc_save",
-    category: "编辑",
-  },
-  {
-    id: "close-panel",
-    keys: "Escape",
-    scope: "modal",
-    descriptionKey: "common_hotkey_desc_closePanel",
-    category: "导航",
-  },
-  {
-    id: "copy-message",
-    keys: "Mod+C",
-    scope: "modal",
-    descriptionKey: "common_hotkey_desc_copyMessage",
-    category: "聊天",
-  },
-  {
-    id: "chat-prev",
-    keys: "ArrowUp",
-    scope: "chat-history",
-    descriptionKey: "common_hotkey_desc_chatPrev",
-    category: "聊天",
-  },
-  {
-    id: "chat-next",
-    keys: "ArrowDown",
-    scope: "chat-history",
-    descriptionKey: "common_hotkey_desc_chatNext",
-    category: "聊天",
-  },
-  {
-    id: "command-palette",
-    keys: "Mod+K",
-    scope: "global",
-    descriptionKey: "common_hotkey_desc_commandPalette",
-    category: "导航",
-  },
-  {
-    id: "toggle-theme",
-    keys: "Mod+Shift+L",
-    scope: "global",
-    descriptionKey: "common_hotkey_desc_toggleTheme",
-    category: "视图",
-  },
-  { id: "goto-dashboard", keys: "G D", scope: "global", descriptionKey: "common_hotkey_desc_gotoDashboard", category: "导航" },
-  { id: "goto-chat", keys: "G C", scope: "global", descriptionKey: "common_hotkey_desc_gotoChat", category: "导航" },
-  { id: "goto-agents", keys: "G A", scope: "global", descriptionKey: "common_hotkey_desc_gotoAgents", category: "导航" },
-  { id: "goto-inspiration", keys: "G I", scope: "global", descriptionKey: "common_hotkey_desc_gotoInspiration", category: "导航" },
-  { id: "goto-stories", keys: "G S", scope: "global", descriptionKey: "common_hotkey_desc_gotoStories", category: "导航" },
-  { id: "goto-prd", keys: "G P", scope: "global", descriptionKey: "common_hotkey_desc_gotoPrd", category: "导航" },
-  { id: "goto-design", keys: "G E", scope: "global", descriptionKey: "common_hotkey_desc_gotoDesign", category: "导航" },
-  { id: "goto-test-cases", keys: "G T", scope: "global", descriptionKey: "common_hotkey_desc_gotoTestCases", category: "导航" },
-  { id: "goto-bugs", keys: "G B", scope: "global", descriptionKey: "common_hotkey_desc_gotoBugs", category: "导航" },
-  { id: "goto-knowledge", keys: "G K", scope: "global", descriptionKey: "common_hotkey_desc_gotoKnowledge", category: "导航" },
-  { id: "goto-anyhub", keys: "G H", scope: "global", descriptionKey: "common_hotkey_desc_gotoAnyhub", category: "导航" },
-  { id: "goto-workspaces", keys: "G W", scope: "global", descriptionKey: "common_hotkey_desc_gotoWorkspaces", category: "导航" },
-  { id: "goto-settings", keys: "G M", scope: "global", descriptionKey: "common_hotkey_desc_gotoSettings", category: "导航" },
-  { id: "create-prd-hk", keys: "N P", scope: "global", descriptionKey: "common_hotkey_desc_createPrdHk", category: "操作" },
-  { id: "create-conversation-hk", keys: "N C", scope: "global", descriptionKey: "common_hotkey_desc_createConversationHk", category: "操作" },
-  { id: "create-story-hk", keys: "N S", scope: "global", descriptionKey: "common_hotkey_desc_createStoryHk", category: "操作" },
-] as const
+import type { HotkeyCategory } from "./types"
 
-export function getHotkeysByCategory(category: HotkeyCategory): HotkeyDefinition[] {
-  return HOTKEY_REGISTRY.filter((h) => h.category === category)
+/**
+ * 扩展官方 HotkeyMeta：面板描述走 i18n key（渲染时经 t() 解析，声明期不做
+ * locale 绑定），category 供面板分组。meta 随声明走，仍是单一来源。
+ */
+declare module "@tanstack/hotkeys" {
+  interface HotkeyMeta {
+    /** i18n message key（flat JSON），渲染层经 t() 解析——描述直接展示给用户 */
+    descriptionKey?: string
+    /** 快捷键面板分组 */
+    category?: HotkeyCategory
+  }
+}
+
+/**
+ * 应用级热键声明（官方 defineAppHotkeys 单一来源）。
+ *
+ * 绑定点一律 `useAppHotkeys()` 取声明后传给 `useHotkey(appHotkeys['id'], cb)`
+ * ——声明即绑定，禁止再手写字符串 chord（消灭「注册表与 useHotkey 双轨」）。
+ * 尚无绑定点条目（goto-* / create-*-hk 共 16 条）保持声明，官方
+ * useAppHotkeyList 会标 'inactive'（面板照常展示，行为与旧注册表一致）。
+ *
+ * 序列键为 `['G', 'D']` 元组；scope 省略即官方默认 global（旧手写注册表的
+ * scope 字段是 API 不支持的死字段，随迁移丢弃）。
+ */
+export const appHotkeys = defineAppHotkeys({
+  "shortcuts-panel": {
+    hotkey: "Mod+/",
+    meta: { descriptionKey: "common_hotkey_desc_shortcutsPanel", category: "导航" },
+  },
+  "toggle-sidebar": {
+    hotkey: "Mod+B",
+    meta: { descriptionKey: "common_hotkey_desc_toggleSidebar", category: "导航" },
+    // 绑定点豁免：Mod+B 实际绑定在 shadcn 官方源码 components/ui/sidebar.tsx
+    // （window.addEventListener，禁改），本声明仅供面板展示（inactive 状态）
+  },
+  save: {
+    hotkey: "Mod+S",
+    meta: { descriptionKey: "common_hotkey_desc_save", category: "编辑" },
+  },
+  "close-panel": {
+    hotkey: "Escape",
+    meta: { descriptionKey: "common_hotkey_desc_closePanel", category: "导航" },
+  },
+  "copy-message": {
+    hotkey: "Mod+C",
+    meta: { descriptionKey: "common_hotkey_desc_copyMessage", category: "聊天" },
+  },
+  "chat-prev": {
+    hotkey: "ArrowUp",
+    meta: { descriptionKey: "common_hotkey_desc_chatPrev", category: "聊天" },
+  },
+  "chat-next": {
+    hotkey: "ArrowDown",
+    meta: { descriptionKey: "common_hotkey_desc_chatNext", category: "聊天" },
+  },
+  "command-palette": {
+    hotkey: "Mod+K",
+    meta: { descriptionKey: "common_hotkey_desc_commandPalette", category: "导航" },
+  },
+  "toggle-theme": {
+    hotkey: "Mod+Shift+L",
+    meta: { descriptionKey: "common_hotkey_desc_toggleTheme", category: "视图" },
+  },
+  "goto-dashboard": {
+    hotkey: ["G", "D"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoDashboard", category: "导航" },
+  },
+  "goto-chat": {
+    hotkey: ["G", "C"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoChat", category: "导航" },
+  },
+  "goto-agents": {
+    hotkey: ["G", "A"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoAgents", category: "导航" },
+  },
+  "goto-inspiration": {
+    hotkey: ["G", "I"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoInspiration", category: "导航" },
+  },
+  "goto-stories": {
+    hotkey: ["G", "S"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoStories", category: "导航" },
+  },
+  "goto-prd": {
+    hotkey: ["G", "P"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoPrd", category: "导航" },
+  },
+  "goto-design": {
+    hotkey: ["G", "E"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoDesign", category: "导航" },
+  },
+  "goto-test-cases": {
+    hotkey: ["G", "T"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoTestCases", category: "导航" },
+  },
+  "goto-bugs": {
+    hotkey: ["G", "B"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoBugs", category: "导航" },
+  },
+  "goto-knowledge": {
+    hotkey: ["G", "K"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoKnowledge", category: "导航" },
+  },
+  "goto-anyhub": {
+    hotkey: ["G", "H"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoAnyhub", category: "导航" },
+  },
+  "goto-workspaces": {
+    hotkey: ["G", "W"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoWorkspaces", category: "导航" },
+  },
+  "goto-settings": {
+    hotkey: ["G", "M"],
+    meta: { descriptionKey: "common_hotkey_desc_gotoSettings", category: "导航" },
+  },
+  "create-prd-hk": {
+    hotkey: ["N", "P"],
+    meta: { descriptionKey: "common_hotkey_desc_createPrdHk", category: "操作" },
+  },
+  "create-conversation-hk": {
+    hotkey: ["N", "C"],
+    meta: { descriptionKey: "common_hotkey_desc_createConversationHk", category: "操作" },
+  },
+  "create-story-hk": {
+    hotkey: ["N", "S"],
+    meta: { descriptionKey: "common_hotkey_desc_createStoryHk", category: "操作" },
+  },
+})
+
+/** 让 `useAppHotkeys()` / `useAppHotkeyList()` 获得本应用声明的精确 id 类型 */
+declare module "@tanstack/react-hotkeys" {
+  interface Register {
+    appHotkeys: typeof appHotkeys
+  }
+}
+
+export type AppHotkeyId = keyof typeof appHotkeys
+
+/** 一对互相冲突的声明（无向，已去重） */
+export interface AppHotkeyConflict {
+  id: AppHotkeyId
+  conflictingId: AppHotkeyId
+}
+
+/**
+ * 声明级冲突检测：用官方 AppHotkeysStore.findConflicts 的冲突语义
+ * （scope 相同或任一为 global，且组合键相等或序列互为前缀）对全部 25 条
+ * 声明两两比对。
+ *
+ * 注：官方 `findHotkeyConflicts()` 检测的是**运行时注册表**（HotkeyManager
+ * 已挂载的注册项），启动时注册表为空、无法用于校验声明，故此处走
+ * AppHotkeysStore 的声明级检测（同一冲突语义的官方实现）。
+ */
+export function findAppHotkeyConflicts(): AppHotkeyConflict[] {
+  const store = new AppHotkeysStore(appHotkeys)
+  const seen = new Set<string>()
+  const conflicts: AppHotkeyConflict[] = []
+  for (const id of Object.keys(appHotkeys) as AppHotkeyId[]) {
+    const hotkey = appHotkeys[id].hotkey
+    if (!hotkey) continue
+    for (const other of store.findConflicts(id, hotkey)) {
+      const pair = [id, other.id].sort().join("\u0000")
+      if (seen.has(pair)) continue
+      seen.add(pair)
+      conflicts.push({ id, conflictingId: other.id as AppHotkeyId })
+    }
+  }
+  return conflicts
+}
+
+// 启动期 dev 警告：声明集出现冲突即 console.error（CI/单测另有零冲突断言）
+if (import.meta.env.DEV) {
+  const conflicts = findAppHotkeyConflicts()
+  if (conflicts.length > 0) {
+    console.error(
+      "[hotkeys] 应用热键声明冲突：",
+      conflicts.map((c) => `${c.id} <-> ${c.conflictingId}`).join(", "),
+    )
+  }
 }
 
 export const CATEGORY_ORDER: HotkeyCategory[] = ["导航", "视图", "编辑", "聊天", "操作"]
@@ -112,4 +209,10 @@ export const HOTKEY_CATEGORY_LABEL_KEYS: Record<HotkeyCategory, string> = {
   编辑: "common_hotkey_cat_edit",
   聊天: "common_hotkey_cat_chat",
   操作: "common_hotkey_cat_action",
-}
+}
+
+/** 声明热键 → ShortcutBadge 的空格分隔串（chord 原样，序列两键空格连接） */
+export function formatAppHotkeyForBadge(hotkey: Hotkey | null): string {
+  if (!hotkey) return ""
+  return typeof hotkey === "string" ? hotkey : hotkey.join(" ")
+}

package/src/lib/hotkeys/types.ts

@@ -15,17 +15,5 @@
 // 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/>.
 
-export type HotkeyScope = "global" | "app" | "modal" | "chat-history"
-
 // 「需求」分类在注册表中无条目（审计 🟢），已移除
-export type HotkeyCategory = "导航" | "编辑" | "视图" | "聊天" | "操作"
-
-export interface HotkeyDefinition {
-  id: string
-  keys: string
-  /** @deprecated API 不支持 scope，保留字段供未来扩展 */
-  scope: HotkeyScope
-  /** i18n message key（flat JSON），渲染层经 t() 解析——描述直接展示给用户 */
-  descriptionKey: string
-  category: HotkeyCategory
-}
+export type HotkeyCategory = "导航" | "编辑" | "视图" | "聊天" | "操作"

package/src/lib/pacer.ts

@@ -15,93 +15,15 @@
 // 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 { RateLimiter } from "@tanstack/pacer"
+// 客户端防抖/节流统一出口（服务端限流见 @/server/lib/rate-limit，勿在此复制）
 import { useDebouncedCallback, useDebouncedValue, useDebouncer, useThrottledCallback } from "@tanstack/react-pacer"
 
 export const EDITOR_AUTO_SAVE_MS = 2000
 export const EDITOR_CHANGE_DEBOUNCE_MS = 500
 export const SEARCH_DEBOUNCE_MS = 300
 export const SCROLL_THROTTLE_MS = 150
-export const AI_RATE_LIMIT = {
-  chat: { max: 10, windowMs: 60_000 },
-  execute: { max: 5, windowMs: 60_000 },
-  generatePrototype: { max: 5, windowMs: 60_000 },
-  testProvider: { max: 10, windowMs: 60_000 },
-  detect: { max: 10, windowMs: 60_000 },
-  webSearch: { max: 20, windowMs: 60_000 },
-} as const
-
-export interface RateLimitConfig {
-  max: number
-  windowMs: number
-}
 
 export { useDebouncedCallback }
 export { useDebouncedValue }
 export { useDebouncer }
 export { useThrottledCallback }
-
-interface ServerFnRateLimitResult {
-  allowed: boolean
-  retryAfterMs: number
-}
-
-const limiterCache = new Map<
-  string,
-  { limiter: RateLimiter<(...args: unknown[]) => boolean>; lastAccess: number }
->()
-
-const CACHE_TTL_MS = 5 * 60 * 1000
-
-function purgeStaleEntries() {
-  const now = Date.now()
-  for (const [key, entry] of limiterCache) {
-    if (now - entry.lastAccess > CACHE_TTL_MS) {
-      entry.limiter.reset()
-      limiterCache.delete(key)
-    }
-  }
-}
-
-// 清扫定时器懒启动：workerd 禁止 global scope（模块顶层）设定时器，
-// 首次 getRateLimiter() 调用时才开启（浏览器/Node 行为不变）。
-let purgeTimerStarted = false
-function ensurePurgeTimer() {
-  if (purgeTimerStarted) return
-  purgeTimerStarted = true
-  const timer = setInterval(purgeStaleEntries, 60_000)
-  timer.unref?.()
-}
-
-export function getRateLimiter(
-  key: string,
-  config: RateLimitConfig
-): RateLimiter<(...args: unknown[]) => boolean> {
-  ensurePurgeTimer()
-  const existing = limiterCache.get(key)
-  if (existing) {
-    existing.lastAccess = Date.now()
-    return existing.limiter
-  }
-
-  const limiter = new RateLimiter(() => true, {
-    limit: config.max,
-    window: config.windowMs,
-    windowType: "sliding",
-  })
-
-  limiterCache.set(key, { limiter, lastAccess: Date.now() })
-  return limiter
-}
-
-export function checkRateLimit(
-  key: string,
-  config: RateLimitConfig
-): ServerFnRateLimitResult {
-  const limiter = getRateLimiter(key, config)
-  const allowed = limiter.maybeExecute()
-  return {
-    allowed,
-    retryAfterMs: allowed ? 0 : limiter.getMsUntilNextWindow(),
-  }
-}

package/src/lib/queries/README.md

@@ -0,0 +1,67 @@
+# queryOptions 工厂模式（lib/queries/）
+
+TanStack Query 的 key 与 queryFn 单一来源层。背景：审计（2026-10-31 tanstack usage
+audit）统计全站约 133 处内联 `queryKey` 散落 loader 与组件，key 字面量在
+`useQuery` / `invalidateQueries` / props 传参之间靠人工对齐，漂移只会在运行时
+表现为「缓存失配 / invalidate 不命中」，无编译期信号。官方
+[`queryOptions`](https://tanstack.com/query/latest/docs/framework/react/guides/query-options)
+正为此设计。
+
+## 工厂签名约定
+
+```ts
+// apps/web/src/lib/queries/<module>.ts
+import { queryOptions } from '@tanstack/react-query'
+
+export const XXX_QUERY_KEY = ['xxx'] as const          // 供 invalidate / setQueryData 用
+
+export const xxxQueryOptions = (params) =>
+  queryOptions({
+    queryKey: [...XXX_QUERY_KEY, params.id],           // key 结构与迁移前逐字一致
+    queryFn: () => someServerFn({ data: { id: params.id } }),
+  })
+```
+
+- 命名：`xxxQueryOptions`（分页查询用 `infiniteQueryOptions`，命名
+  `xxxListInfiniteQueryOptions`）。
+- queryFn 直接引用既有 serverFn（`@/server/serverFns/**`，split 安全）。
+- 组件要覆盖单点行为（`staleTime` / `enabled` 等）时用展开：
+  `useQuery({ ...xxxQueryOptions(), staleTime: 30_000 })`——key/fn 仍单一来源。
+
+## 消费口径
+
+| 场景 | 写法 |
+|---|---|
+| loader 预取 | `context.queryClient.ensureQueryData(xxxQueryOptions(...))` |
+| loader 预取分页 | `context.queryClient.fetchInfiniteQuery(xxxListInfiniteQueryOptions(...))` |
+| 组件查询 | `useQuery(xxxQueryOptions(...))` |
+| 组件分页查询 | `useInfiniteQuery(xxxListInfiniteQueryOptions(...))` |
+| 失效 | `queryClient.invalidateQueries({ queryKey: XXX_QUERY_KEY })` |
+| 乐观写 / SSE 写缓存 | `queryClient.setQueryData(XXX_QUERY_KEY, next)` |
+| key 作为 props 传递（如 `detailQueryKey`） | `xxxQueryOptions(id).queryKey` |
+
+## 迁移口径（存量 133 处怎么收）
+
+1. **新代码强制走 queryOptions**：禁止再写内联 `queryKey:` 字面量（约定已入
+   根 AGENTS.md「项目约定」的「新查询必须走 queryOptions 工厂单一来源」条）。
+2. **存量内联 key 被触碰时顺手迁移**：改到某个组件/路由时，把它的内联 key
+   换成对应工厂；没有工厂就先建（本目录一模块一文件，或同域合并）。
+3. **不设专门任务强推**：未触碰的存量保持原样，避免无谓 churn。
+4. **key 结构零漂移是底线**：工厂产出的 key 必须与迁移前字面量逐字一致
+   （含 `undefined` 段位），否则缓存失配。迁移配套单测放
+   `__tests__/xxx-queries.test.ts`，断言两件事：
+   - key 逐字对账历史字面量；
+   - queryFn 调用既有 serverFn 且 data 形状不变（`vi.mock` serverFn 模块后
+     断言调用参数）。
+5. **同 key 不同 queryFn 的既有碰撞**（如 `['teamUsers']` 同时被
+   team-client 与 tiptap mention-dropdown 使用，数据源不同）：迁移时
+   **不要单方面改任何一方的 key**——会静默改变缓存行为。先记录，另行决策。
+
+## 现状（本目录已收拢模块）
+
+| 文件 | key 族 | 备注 |
+|---|---|---|
+| `notifications.ts` | `notifications/*` 五常量 | 自 `hooks/use-notifications` 迁入；列表为 infiniteQueryOptions |
+| `agents.ts` | `agents` / `skills` / `agent-bindings` / `persona-hint` | 新增常量；harness 同键查询已收拢 |
+| `team.ts` | `teamMembers` / `teamInvitations` / `teamUsers` | mention-dropdown 的 `teamUsers` 是另一数据源，未动（见上第 5 条） |
+| `compliance.ts` | `compliance` / `compliance-detail` / `entity-tags` / `favorite-ids` | detail / favorite-ids 双份合并；entityTags / favoriteIds 参数化 `entityType`，`legal`（laws）/ `dictionary` 模块可渐进复用 |

package/src/lib/queries/__tests__/agents-queries.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { QueryClient } from '@tanstack/react-query'
+
+vi.mock('@/server/serverFns/agents/agent-crud', () => ({
+  listAgentsFn: vi.fn().mockResolvedValue([]),
+  createAgentFn: vi.fn(),
+  updateAgentFn: vi.fn(),
+  deleteAgentFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/agents/skill-crud', () => ({
+  listSkillsFn: vi.fn().mockResolvedValue([]),
+  createSkillFn: vi.fn(),
+  updateSkillFn: vi.fn(),
+  deleteSkillFn: vi.fn(),
+}))
+vi.mock('@/server/serverFns/agents/bindings', () => ({
+  listBindingsFn: vi.fn().mockResolvedValue([]),
+  upsertBindingFn: vi.fn(),
+  setDefaultAgentFn: vi.fn(),
+  getPersonaHintFn: vi.fn().mockResolvedValue({ hint: '' }),
+}))
+
+import { listAgentsFn } from '@/server/serverFns/agents/agent-crud'
+import { listSkillsFn } from '@/server/serverFns/agents/skill-crud'
+import { getPersonaHintFn, listBindingsFn } from '@/server/serverFns/agents/bindings'
+import {
+  AGENT_BINDINGS_QUERY_KEY,
+  AGENTS_QUERY_KEY,
+  PERSONA_HINT_QUERY_KEY,
+  SKILLS_QUERY_KEY,
+  agentBindingsQueryOptions,
+  agentsQueryOptions,
+  personaHintQueryOptions,
+  skillsQueryOptions,
+} from '../agents'
+
+const mockedAgents = vi.mocked(listAgentsFn)
+const mockedSkills = vi.mocked(listSkillsFn)
+const mockedBindings = vi.mocked(listBindingsFn)
+const mockedPersonaHint = vi.mocked(getPersonaHintFn)
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+/** queryFn 运行时恒存在（工厂必传），类型上可选故窄化；context 形状对齐 react-query v5 调用面 */
+function invokeQueryFn(
+  options: { queryFn?: (...args: never[]) => unknown },
+  queryKey: readonly unknown[],
+): Promise<unknown> {
+  return (options.queryFn as (c: unknown) => Promise<unknown>)({
+    client: new QueryClient(),
+    queryKey,
+    signal: new AbortController().signal,
+    meta: undefined,
+  })
+}
+
+/** agents key 结构零漂移：与迁移前各组件内联字面量逐字一致（此前无常量，自此收敛单一来源） */
+describe('agents queryOptions key 结构', () => {
+  it('四个 key 常量与历史内联字面量逐字一致', () => {
+    expect(AGENTS_QUERY_KEY).toEqual(['agents'])
+    expect(SKILLS_QUERY_KEY).toEqual(['skills'])
+    expect(AGENT_BINDINGS_QUERY_KEY).toEqual(['agent-bindings'])
+    expect(PERSONA_HINT_QUERY_KEY).toEqual(['persona-hint'])
+  })
+
+  it('各工厂产出对应常量同一引用（invalidate/setQueryData 与 useQuery 同源）', () => {
+    expect(agentsQueryOptions().queryKey).toBe(AGENTS_QUERY_KEY)
+    expect(skillsQueryOptions().queryKey).toBe(SKILLS_QUERY_KEY)
+    expect(agentBindingsQueryOptions().queryKey).toBe(AGENT_BINDINGS_QUERY_KEY)
+    expect(personaHintQueryOptions().queryKey).toBe(PERSONA_HINT_QUERY_KEY)
+  })
+})
+
+/** queryFn 接线：必须调用既有 serverFn 且无参形态与迁移前内联写法一致 */
+describe('agents queryOptions queryFn 接线', () => {
+  it('agents → listAgentsFn()（无参）', async () => {
+    const options = agentsQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedAgents).toHaveBeenCalledWith()
+  })
+
+  it('skills → listSkillsFn()（无参）', async () => {
+    const options = skillsQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedSkills).toHaveBeenCalledWith()
+  })
+
+  it('bindings → listBindingsFn()（无参）', async () => {
+    const options = agentBindingsQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedBindings).toHaveBeenCalledWith()
+  })
+
+  it('persona-hint → getPersonaHintFn()（无参）', async () => {
+    const options = personaHintQueryOptions()
+    await invokeQueryFn(options, options.queryKey)
+    expect(mockedPersonaHint).toHaveBeenCalledWith()
+  })
+})