@allbluecn/web-app 0.18.2 → 0.19.0

package/src/lib/datetime.ts

@@ -55,7 +55,10 @@ export function formatDate(
 /**
  * 确定性时间戳格式化：固定时区 + date-fns 数字格式，不依赖运行环境 locale/时区。
  * SSR 与客户端输出字节级一致，专治 toLocaleString() 引发的 hydration mismatch。
- * @param date Date 对象或 ISO 字符串
+ * @param date Date 对象或 ISO 字符串（Date | string 均为绝对时刻；string 经
+ *   new Date(iso) 解析后与 Date 同路径转换，两条入口输出字节级一致——任务 11
+ *   详情页「创建时间」(createdAt: string) 与「运行历史」(startedAt: string|Date)
+ *   即经此函数统一口径，同页不存在两种时区）
  * @param fmt date-fns 格式，默认 "yyyy-MM-dd HH:mm"
  */
 export function formatTimestamp(
@@ -132,11 +135,25 @@ export function formatChatDate(date: Date, timezone: string): string {
 
 // ---- 本地日历工具（自 lib/date-utils.ts 并入：按本地时区做日历网格/日键计算，无时区转换） ----
 
-/** 解析 "yyyy-MM-dd" 前缀为本地 Date（避免 UTC 偏移） */
+/**
+ * 解析 "yyyy-MM-dd" 前缀为本地 Date（避免 UTC 偏移）。
+ * 分量越界或非数字返回 Invalid Date（不滚动）；调用方用 `Number.isNaN(d.getTime())` 判定。
+ */
 export function parseDate(s: string): Date {
   const datePart = s.slice(0, 10)
   const [y, m, d] = datePart.split('-').map(Number)
-  return new Date(y, m - 1, d)
+  const date = new Date(y, m - 1, d)
+  if (
+    !Number.isFinite(y) ||
+    !Number.isFinite(m) ||
+    !Number.isFinite(d) ||
+    date.getFullYear() !== y ||
+    date.getMonth() !== m - 1 ||
+    date.getDate() !== d
+  ) {
+    return new Date(NaN)
+  }
+  return date
 }
 
 /** 本地时区 yyyy-MM-dd 日键（与 timezone 版 formatDate 区分） */

package/src/lib/hooks/__tests__/use-synced-state.test.tsx

@@ -0,0 +1,54 @@
+import { useLayoutEffect } from "react";
+import { act, render, renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useSyncedState } from "../use-synced-state";
+
+type Source = { n: number };
+
+describe("useSyncedState", () => {
+  it("初值取源值", () => {
+    const { result } = renderHook(() => useSyncedState<Source>({ n: 1 }));
+    expect(result.current[0]).toEqual({ n: 1 });
+  });
+
+  it("源值引用不变时保留本地更新（拖拽乐观更新不被重置）", () => {
+    const source: Source = { n: 1 };
+    const { result, rerender } = renderHook(({ s }: { s: Source }) => useSyncedState(s), {
+      initialProps: { s: source },
+    });
+
+    act(() => result.current[1]({ n: 2 }));
+    expect(result.current[0]).toEqual({ n: 2 });
+
+    rerender({ s: source });
+    expect(result.current[0]).toEqual({ n: 2 });
+  });
+
+  it("源值引用变化时在提交前同步，不露出陈旧值", () => {
+    const committed: number[] = [];
+
+    function Probe({ source }: { source: Source }) {
+      const [value] = useSyncedState(source);
+      // 不带依赖：记录每一次「提交」（不是每次值变化）——正是要抓出多提交的陈旧帧
+      useLayoutEffect(() => {
+        committed.push(value.n);
+      });
+      return null;
+    }
+
+    const { rerender } = render(<Probe source={{ n: 1 }} />);
+    rerender(<Probe source={{ n: 9 }} />);
+
+    expect(committed).toEqual([1, 9]);
+  });
+
+  it("函数式更新可用，且不因自身更新触发重置", () => {
+    const source: Source = { n: 1 };
+    const { result } = renderHook(({ s }: { s: Source }) => useSyncedState(s), {
+      initialProps: { s: source },
+    });
+
+    act(() => result.current[1]((prev) => ({ n: prev.n + 10 })));
+    expect(result.current[0]).toEqual({ n: 11 });
+  });
+});

package/src/lib/hooks/use-story-panel-open.ts

@@ -0,0 +1,134 @@
+// 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/>.
+
+// 需求详情各子面板折叠状态持久化（localStorage，按 storyId 分桶）。
+// peek 面板与详情路由共享同一状态（同一 story 打开处即可见上次折叠态）。
+import { useEffect, useState, type Dispatch, type SetStateAction } from "react";
+
+const storageKey = (storyId: string) => `allblue.story-panels.${storyId}`;
+
+type PanelState = Record<string, boolean>;
+
+function readState(storyId: string): PanelState {
+  try {
+    const raw = window.localStorage.getItem(storageKey(storyId));
+    return raw ? (JSON.parse(raw) as PanelState) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function useStoryPanelOpen(storyId: string, panelKey: string, defaultOpen = true) {
+  const [open, setOpen] = useState(() => {
+    try {
+      return readState(storyId)[panelKey] ?? defaultOpen;
+    } catch {
+      return defaultOpen;
+    }
+  });
+
+  useEffect(() => {
+    try {
+      const state = readState(storyId);
+      if (state[panelKey] === open) return;
+      const next = { ...state, [panelKey]: open };
+      window.localStorage.setItem(storageKey(storyId), JSON.stringify(next));
+    } catch {
+      // 存储不可用（隐私模式等）：状态仅本次会话内生效
+    }
+  }, [storyId, panelKey, open]);
+
+  return [open, setOpen] as const;
+}
+
+/** 读取某 story 的整桶状态（含 groups/filters 命名空间） */
+function readBucket(storyId: string): {
+  groups?: Record<string, Record<string, boolean>>;
+  filters?: Record<string, Record<string, unknown>>;
+} & PanelState {
+  try {
+    const raw = window.localStorage.getItem(storageKey(storyId));
+    return raw ? (JSON.parse(raw) as ReturnType<typeof readBucket>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 列表内分组标题行的折叠状态持久化（同桶 groups.{panelKey} 命名空间）。
+ * 键为分组 key（含子分组复合键），维度切换后遗留键自然失效。
+ */
+export function useStoryPanelGroupCollapsed(storyId: string, panelKey: string) {
+  const [collapsed, setCollapsed] = useState<Record<string, boolean>>(() => {
+    try {
+      return readBucket(storyId).groups?.[panelKey] ?? {};
+    } catch {
+      return {};
+    }
+  });
+
+  useEffect(() => {
+    try {
+      const bucket = readBucket(storyId);
+      const groups = bucket.groups ?? {};
+      if (JSON.stringify(groups[panelKey]) === JSON.stringify(collapsed)) return;
+      window.localStorage.setItem(
+        storageKey(storyId),
+        JSON.stringify({ ...bucket, groups: { ...groups, [panelKey]: collapsed } }),
+      );
+    } catch {
+      // 存储不可用：状态仅本次会话内生效
+    }
+  }, [storyId, panelKey, collapsed]);
+
+  return [collapsed, setCollapsed] as const;
+}
+
+/**
+ * 列表显示选项持久化（分组/子分组/排序方向，同桶 filters.{panelKey}）。
+ * 读取时与 defaults 合并——存储缺字段/结构漂移自动回退默认值。
+ */
+export function useStoryPanelFilters<T extends object>(
+  storyId: string,
+  panelKey: string,
+  defaults: T,
+): [T, Dispatch<SetStateAction<T>>] {
+  const [filters, setFilters] = useState<T>(() => {
+    try {
+      const stored = readBucket(storyId).filters?.[panelKey] as Partial<T> | undefined;
+      return stored ? { ...defaults, ...stored } : defaults;
+    } catch {
+      return defaults;
+    }
+  });
+
+  useEffect(() => {
+    try {
+      const bucket = readBucket(storyId);
+      const stored = bucket.filters?.[panelKey];
+      if (JSON.stringify(stored) === JSON.stringify(filters)) return;
+      window.localStorage.setItem(
+        storageKey(storyId),
+        JSON.stringify({ ...bucket, filters: { ...bucket.filters, [panelKey]: filters } }),
+      );
+    } catch {
+      // 存储不可用：状态仅本次会话内生效
+    }
+  }, [storyId, panelKey, filters]);
+
+  return [filters, setFilters] as const;
+}

package/src/lib/hooks/use-synced-state.ts

@@ -0,0 +1,17 @@
+import { useState, type Dispatch, type SetStateAction } from "react";
+
+/**
+ * 受控值的「渲染期同步」版 useState：
+ * 源值（通常来自 loader/服务端）引用变化时，在**同一次渲染提交前**同步本地值，
+ * 不会像 useEffect 那样先提交一帧陈旧值（切换分组维度时列头会回落显示原始 key）。
+ * 源值引用不变时保留本地乐观更新（拖拽中途不被重置）。
+ */
+export function useSyncedState<T>(source: T): [T, Dispatch<SetStateAction<T>>] {
+  const [value, setValue] = useState(source);
+  const [syncedSource, setSyncedSource] = useState(source);
+  if (source !== syncedSource) {
+    setSyncedSource(source);
+    setValue(source);
+  }
+  return [value, setValue];
+}

package/src/lib/hotkeys/__tests__/registry.test.ts

@@ -26,7 +26,7 @@ describe("HOTKEY_REGISTRY", () => {
 
   it("序列键条目 keys 为空格分隔的两键（如 'G D'）", () => {
     const seqKeys = HOTKEY_REGISTRY.filter((h) => h.keys.includes(" "))
-    expect(seqKeys.length).toBeGreaterThanOrEqual(19)
+    expect(seqKeys.length).toBeGreaterThanOrEqual(16)
     for (const h of seqKeys) {
       expect(h.keys.split(" ")).toHaveLength(2)
     }

package/src/lib/hotkeys/registry.ts

@@ -90,11 +90,8 @@ export const HOTKEY_REGISTRY: HotkeyDefinition[] = [
   { id: "goto-design", keys: "G E", scope: "global", description: "前往设计", category: "导航" },
   { id: "goto-test-cases", keys: "G T", scope: "global", description: "前往测试用例", category: "导航" },
   { id: "goto-bugs", keys: "G B", scope: "global", description: "前往缺陷", category: "导航" },
-  { id: "goto-acceptance", keys: "G Q", scope: "global", description: "前往验收标准", category: "导航" },
-  { id: "goto-debrief", keys: "G R", scope: "global", description: "前往汇报", category: "导航" },
   { id: "goto-knowledge", keys: "G K", scope: "global", description: "前往知识库", category: "导航" },
   { id: "goto-anyhub", keys: "G H", scope: "global", description: "前往应用中心", category: "导航" },
-  { id: "goto-tags", keys: "G L", scope: "global", description: "前往标签", category: "导航" },
   { id: "goto-workspaces", keys: "G W", scope: "global", description: "前往工作空间", category: "导航" },
   { id: "goto-settings", keys: "G M", scope: "global", description: "前往设置", category: "导航" },
   { id: "create-prd-hk", keys: "N P", scope: "global", description: "新建 PRD", category: "操作" },

package/src/lib/layout-responsive.ts

@@ -0,0 +1,140 @@
+// 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/>.
+
+// 布局窄屏渐进降级（全局 _nav 布局）。
+//
+// **面板宽度由 CSS flex 计算**（内容区 `min-w-120`=480、面板槽 `basis-300`=1200 /
+// shrink / min-w-120）：浏览器同帧布局，避免 JS 用上一帧行宽算 px 造成的逐帧抖动。
+// 本模块只负责**开关判定**（侧栏收起 / 面板转浮层 / AI 转浮层），且一律基于
+// **外层宽度 + 侧栏目标状态预测**的行宽——不读侧栏收放动画的中间态，避免收起过程
+// 中「先浮层后停靠」的状态翻转。
+
+import { createContext, useContext, useEffect } from "react";
+
+/** 内容区（SidebarInset）最小宽度 */
+export const CONTENT_MIN_WIDTH = 480;
+/** 侧边面板（dock）最小宽度 */
+export const DOCK_MIN_WIDTH = 480;
+/** 行内间隙/边距（gap-2 ×2 + pr-2） */
+export const LAYOUT_CHROME_WIDTH = 24;
+/** AI 助手 full 态停靠宽度（对应 w-120 = 30rem） */
+export const AI_DOCKED_WIDTH = 480;
+/** 侧栏展开宽度（16rem） */
+export const SIDEBAR_EXPANDED_WIDTH = 256;
+/** 侧栏收起到图标态宽度（3rem） */
+export const SIDEBAR_ICON_WIDTH = 48;
+/** 阈值回差：已在某态时，需比进入阈值多出该宽度才切回，避免边界反复抖动 */
+export const HYSTERESIS_WIDTH = 48;
+
+export interface LayoutState {
+  /** 侧栏是否因窄屏自动收起到图标态 */
+  sidebarCollapsed: boolean;
+  /** 侧边面板是否转浮层（盖在内容区上） */
+  dockOverlay: boolean;
+  /** AI 助手是否转浮层（盖在侧边面板上） */
+  aiOverlay: boolean;
+}
+
+export const DEFAULT_LAYOUT_STATE: LayoutState = {
+  sidebarCollapsed: false,
+  dockOverlay: false,
+  aiOverlay: false,
+};
+
+export interface ComputeLayoutInput {
+  /** 最外层容器宽度（= 视口宽度）。唯一测量基准：不随侧栏收放动画变化。 */
+  outerWidth: number;
+  /** 当前是否存在侧边面板（dock 形态） */
+  dockPresent: boolean;
+  /** AI 助手是否处于停靠（full 且展开）状态 */
+  aiDocked: boolean;
+}
+
+/** 由外层宽度推导布局状态。纯函数（除 prev 回差外无外部依赖），便于单测。 */
+export function computeLayout(
+  { outerWidth, dockPresent, aiDocked }: ComputeLayoutInput,
+  prev: LayoutState = DEFAULT_LAYOUT_STATE,
+): LayoutState {
+  if (outerWidth <= 0) return DEFAULT_LAYOUT_STATE;
+
+  const ai = aiDocked ? AI_DOCKED_WIDTH : 0;
+  const dockMin = dockPresent ? DOCK_MIN_WIDTH : 0;
+
+  // 侧栏收起：外层放不下「展开侧栏 + 内容最小 + 面板最小 + AI」时收起（已收起需多出回差才展开）
+  const needExpanded = SIDEBAR_EXPANDED_WIDTH + CONTENT_MIN_WIDTH + dockMin + ai + LAYOUT_CHROME_WIDTH;
+  const sidebarThreshold = prev.sidebarCollapsed ? needExpanded + HYSTERESIS_WIDTH : needExpanded;
+  const sidebarCollapsed = outerWidth < sidebarThreshold;
+
+  // 预测可用宽：外层 − 侧栏目标宽 − 行内 chrome（不读侧栏动画中间态）
+  const sidebarWidth = sidebarCollapsed ? SIDEBAR_ICON_WIDTH : SIDEBAR_EXPANDED_WIDTH;
+  const usable = Math.max(0, outerWidth - sidebarWidth - LAYOUT_CHROME_WIDTH);
+
+  // AI 浮层阈值：仅在「连 AI 自身停靠宽度都放不下」的最窄处才转浮层（已浮层时需多出回差才切回）。
+  // 此前用 CONTENT_MIN + ai 会让 AI 在面板刚覆盖内容（内容被盖住、无需再保最小宽）时就过早浮层居中。
+  const aiThreshold = prev.aiOverlay ? ai + HYSTERESIS_WIDTH : ai;
+
+  if (!dockPresent) {
+    return { sidebarCollapsed, dockOverlay: false, aiOverlay: usable < aiThreshold };
+  }
+
+  // 面板可停靠的最小可用宽；低于则转浮层（已浮层时需多出回差才切回）
+  const dockFitWidth = CONTENT_MIN_WIDTH + dockMin + ai;
+  const dockOverlayThreshold = prev.dockOverlay ? dockFitWidth + HYSTERESIS_WIDTH : dockFitWidth;
+  if (usable < dockOverlayThreshold) {
+    return { sidebarCollapsed, dockOverlay: true, aiOverlay: usable < aiThreshold };
+  }
+  return { sidebarCollapsed, dockOverlay: false, aiOverlay: false };
+}
+
+export interface LayoutResponsiveContextValue {
+  layout: LayoutState;
+  setOuterEl: (el: HTMLElement | null) => void;
+  setDockPresent: (v: boolean) => void;
+  setAiDocked: (v: boolean) => void;
+}
+
+export const LayoutResponsiveContext = createContext<LayoutResponsiveContextValue | null>(null);
+
+/** 读取当前布局状态；无 Provider（如单测）时返回默认态（保持旧行为）。 */
+export function useLayoutResponsive(): LayoutState {
+  return useContext(LayoutResponsiveContext)?.layout ?? DEFAULT_LAYOUT_STATE;
+}
+
+/** 读取注册器（挂载测量点 / 上报面板存在性）；无 Provider 时为 null。 */
+export function useLayoutResponsiveSetters(): LayoutResponsiveContextValue | null {
+  return useContext(LayoutResponsiveContext);
+}
+
+/** 侧边面板（dock）挂载时上报「面板存在」，供布局判定。 */
+export function useDockPresence(active: boolean): void {
+  const ctx = useContext(LayoutResponsiveContext);
+  useEffect(() => {
+    if (!ctx) return;
+    ctx.setDockPresent(active);
+    return () => ctx.setDockPresent(false);
+  }, [ctx, active]);
+}
+
+/** AI 助手停靠（full 且展开）时上报，供布局判定。 */
+export function useAiDocked(active: boolean): void {
+  const ctx = useContext(LayoutResponsiveContext);
+  useEffect(() => {
+    if (!ctx) return;
+    ctx.setAiDocked(active);
+    return () => ctx.setAiDocked(false);
+  }, [ctx, active]);
+}

package/src/lib/pacer.ts

@@ -63,12 +63,21 @@ function purgeStaleEntries() {
   }
 }
 
-setInterval(purgeStaleEntries, 60_000)
+// 清扫定时器懒启动：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()

package/src/lib/peek-dock.ts

@@ -0,0 +1,32 @@
+// 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/>.
+
+// 侧边面板（side-dock）布局槽的共享常量。
+//
+// 单独放在 lib 下（无 React / 无业务依赖），供布局壳 sidebar-03 直接引用：
+// 布局壳不应依赖任何业务组件目录（story/testcase/shared-kit 均不引入）。
+
+/** 侧边面板（dock）态的布局级挂载点 id，与 sidebar-03 中的挂载点一致。 */
+export const PEEK_DOCK_SLOT_ID = "peek-dock-panel-slot";
+
+/**
+ * 侧边面板宽度。放在挂载点上（相对外层已确定宽度的一行解析百分比），面板本体
+ * `w-full` 填充——若把该百分比宽度放在面板上，其 `100%` 会相对宽度 auto 的挂载点
+ * 解析，退化为内容宽度（宽度与 side-peek 不一致、且随内容变化而漂移）。
+ * 口径与侧边浮窗（side-peek）保持一致。
+ */
+export const PEEK_SIDE_PANEL_WIDTH_CLASS = "w-[min(100%,max(85vw,560px),1200px)]";

package/src/lib/plugin-runtime/__tests__/plugin-tool-schema-parity.test.ts

@@ -0,0 +1,140 @@
+// 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/>.
+
+// 审查重点 #2：客户端工具 schema 不一致 → 工具静默退化为 generic interrupt
+// （无报错、工具不执行）。本测试钉住「单源定义」：客户端工厂返回的每个工具
+// 的 inputSchema / outputSchema 必须与服务端注册表（plugin-lifecycle-defs）
+// 中同名工具**引用同一 schema 对象**（toolDefinition().client() 按引用复制
+// schema，同引用 ⟺ 同一 toolDefinition 导出）。
+//
+// 服务端动态插件工具（plugin__<id>__<name>）经由共享 builder 单源，见
+// 「动态插件工具 builder」块。测试落点：jsdom/vitest unit（lib/**/__tests__），
+// 不 import plugin-tools.ts / plugin-lifecycle-server.ts（它们顶层 import
+// prisma）；服务端注册表侧以纯净的 plugin-lifecycle-defs 导出为对照基准。
+
+import { describe, expect, it } from "vitest";
+import { buildPluginClientTools } from "@/lib/plugin-runtime/plugin-client-tools";
+import {
+  buildPluginDynamicToolDef,
+  pluginDefineDef as sharedPluginDefineDef,
+  pluginInspectListDef as sharedPluginInspectListDef,
+  pluginRunDef as sharedPluginRunDef,
+  pluginStopDef as sharedPluginStopDef,
+  pluginUndefineDef as sharedPluginUndefineDef,
+} from "@/lib/plugin-runtime/plugin-tool-defs";
+import {
+  pluginDefineDef,
+  pluginInspectListDef,
+  pluginLifecycleDefs,
+  pluginRunDef,
+  pluginStopDef,
+  pluginUndefineDef,
+} from "@/server/ai-gateway/tools/plugin-lifecycle-defs";
+
+// 客户端执行的三件生命周期工具（plugin_define 走审批 interrupt、
+// plugin_inspect_list 纯服务端执行，都不进客户端工厂）
+const CLIENT_EXECUTED_DEFS = [pluginRunDef, pluginStopDef, pluginUndefineDef] as const;
+
+describe("plugin tool schema parity（客户端工具单源 toolDefinition）", () => {
+  it("服务端注册表包含全部 5 件生命周期工具", () => {
+    expect(pluginLifecycleDefs).toHaveLength(5);
+    expect(pluginLifecycleDefs.map((d) => d.name)).toEqual([
+      "plugin_define",
+      "plugin_run",
+      "plugin_stop",
+      "plugin_undefine",
+      "plugin_inspect_list",
+    ]);
+  });
+
+  it("客户端工厂三件工具与同名服务端 def 引用同一 inputSchema / outputSchema", () => {
+    const clientTools = buildPluginClientTools();
+    const byName = new Map(clientTools.map((t) => [t.name, t]));
+
+    for (const def of CLIENT_EXECUTED_DEFS) {
+      const clientTool = byName.get(def.name);
+      expect(clientTool, `客户端工厂缺少工具 ${def.name}`).toBeDefined();
+      // inputSchema 同引用 ⟺ 同一 toolDefinition 导出（单源实锤）
+      expect(clientTool!.inputSchema, `${def.name} inputSchema 必须同引用`).toBe(
+        def.inputSchema
+      );
+      // outputSchema 双侧同在且同引用（1.0 一致性硬约束：缺失/不一致即
+      // 静默退化为 generic interrupt）
+      expect(clientTool!.outputSchema, `${def.name} outputSchema 必须同引用`).toBe(
+        def.outputSchema
+      );
+      // client 半必须挂执行体（0.x 起 execute 缺失 = 工具永不执行）
+      expect(typeof clientTool!.execute).toBe("function");
+      expect(clientTool!.__toolSide).toBe("client");
+      // needsApproval 字面量透传（审批 interrupt 门控依赖）
+      expect(clientTool!.needsApproval).toBe(def.needsApproval);
+    }
+  });
+
+  it("plugin_define / plugin_inspect_list 不进客户端工厂", () => {
+    const names = buildPluginClientTools().map((t) => t.name);
+    expect(names).toEqual(["plugin_run", "plugin_stop", "plugin_undefine"]);
+  });
+
+  it("服务端 def 文件与共享模块是同一批导出（re-export 单源实锤）", () => {
+    expect(pluginDefineDef).toBe(sharedPluginDefineDef);
+    expect(pluginRunDef).toBe(sharedPluginRunDef);
+    expect(pluginStopDef).toBe(sharedPluginStopDef);
+    expect(pluginUndefineDef).toBe(sharedPluginUndefineDef);
+    expect(pluginInspectListDef).toBe(sharedPluginInspectListDef);
+  });
+
+  it("动态插件工具 builder：三段式名称 + inputSchema 同引用 + 双侧同缺 outputSchema", () => {
+    const inputSchema = {
+      type: "object",
+      properties: { q: { type: "string" } },
+      required: ["q"],
+    };
+    const def = buildPluginDynamicToolDef("weather", {
+      name: "lookup",
+      description: "查天气",
+      inputSchema,
+    });
+    expect(def.name).toBe("plugin__weather__lookup");
+    expect(def.description).toBe("[weather] 查天气");
+    // 插件声明的 schema 对象原样同引用进定义（服务端注册同一 builder 同一对象）
+    expect(def.inputSchema).toBe(inputSchema);
+    // outputSchema 双侧同为 undefined（动态工具无输出校验，双侧一致）
+    expect(def.outputSchema).toBeUndefined();
+    expect(def.__toolSide).toBe("definition");
+  });
+
+  it("动态插件工具缺 inputSchema 时回落空对象 schema（与服务端注册口径一致）", () => {
+    const def = buildPluginDynamicToolDef("weather", {
+      name: "ping",
+      description: "探活",
+    });
+    expect(def.inputSchema).toEqual({ type: "object", properties: {} });
+  });
+
+  it("动态插件工具的 client 半挂执行体并沿用名称分派", async () => {
+    const def = buildPluginDynamicToolDef("weather", {
+      name: "lookup",
+      description: "查天气",
+    });
+    const clientTool = def.client(() => Promise.resolve({ ok: true }));
+    expect(clientTool.__toolSide).toBe("client");
+    expect(clientTool.inputSchema).toBe(def.inputSchema);
+    expect(clientTool.outputSchema).toBe(def.outputSchema);
+    expect(typeof clientTool.execute).toBe("function");
+  });
+});