@tbox.cn/app-template-agent 0.7.5 → 0.9.0

package/packages/agent-ui-kit/src/hooks/use-drag-gesture.ts

@@ -0,0 +1,129 @@
+/**
+ * 容器级拖拽手势绑定（pointer 优先，touch 回退）。
+ *
+ * 两条必须绕开 React 合成事件的理由：
+ * 1. React 的 touchmove 注册在 root 上且是 passive，其中的 preventDefault() 必然失败——
+ *    桌面靠 overscroll-behavior 兜住，web-view（旧 WebKit）会被原生滚动吞掉手势。
+ * 2. 触摸设备上需要覆盖单指轻扫与单指拖拽，两者都只经 touch/pointer 通道。
+ *
+ * 因此统一在容器元素上绑 Pointer Events（非 passive），无 PointerEvent 的运行时回退 touch。
+ * 页面不再往 JSX 上绑手势事件，避免同一手势走两遍。
+ *
+ * **刻意不响应鼠标拖拽**（pointerType === 'mouse'）：桌面按住鼠标拖动页面不是自然交互
+ * （那里的惯例是选中文本），桌面的下拉意图由触控板双指滑动表达、走 wheel 通道。
+ */
+import { useEffect, useRef } from 'react';
+
+export interface DragGestureHandlers {
+  onStart: (point: { clientY: number }) => void;
+  /** 返回 true 表示本次由手势接管，需阻止原生滚动。 */
+  onMove: (point: { clientY: number }) => boolean;
+  onEnd: () => void;
+  onCancel?: () => void;
+}
+
+export interface UseDragGestureOptions extends DragGestureHandlers {
+  scrollRef?: React.RefObject<HTMLElement | null>;
+  disabled?: boolean;
+}
+
+export function useDragGesture({
+  scrollRef,
+  disabled,
+  onStart,
+  onMove,
+  onEnd,
+  onCancel,
+}: UseDragGestureOptions): void {
+  // handler 存 ref：容器监听只在 disabled/元素变化时重绑，避免每次渲染 add/remove 抖动
+  const handlersRef = useRef<DragGestureHandlers>({ onStart, onMove, onEnd, onCancel });
+  handlersRef.current = { onStart, onMove, onEnd, onCancel };
+
+  useEffect(() => {
+    const el = scrollRef?.current;
+    if (!el || disabled) return undefined;
+
+    const usePointer = typeof window !== 'undefined' && 'PointerEvent' in window;
+    let dragging = false;
+
+    const preventIfTaken = (event: Event, taken: boolean) => {
+      if (taken && event.cancelable) event.preventDefault();
+    };
+
+    // ── pointer 路径（mouse / touch / pen 统一）──
+    /** 鼠标不参与拖拽手势：桌面下拉意图走 wheel（触控板双指），见文件头说明。 */
+    const isDragPointer = (e: PointerEvent) => e.pointerType !== 'mouse';
+
+    const onPointerDown = (e: PointerEvent) => {
+      if (!isDragPointer(e)) return;
+      dragging = true;
+      handlersRef.current.onStart({ clientY: e.clientY });
+    };
+    const onPointerMove = (e: PointerEvent) => {
+      if (!dragging || !isDragPointer(e)) return;
+      preventIfTaken(e, handlersRef.current.onMove({ clientY: e.clientY }));
+    };
+    const onPointerUp = () => {
+      if (!dragging) return;
+      dragging = false;
+      handlersRef.current.onEnd();
+    };
+    const onPointerCancel = () => {
+      if (!dragging) return;
+      dragging = false;
+      (handlersRef.current.onCancel ?? handlersRef.current.onEnd)();
+    };
+
+    // ── touch 回退（无 PointerEvent 的旧 WebView）──
+    const onTouchStart = (e: TouchEvent) => {
+      const touch = e.touches[0];
+      if (!touch) return;
+      dragging = true;
+      handlersRef.current.onStart({ clientY: touch.clientY });
+    };
+    const onTouchMove = (e: TouchEvent) => {
+      const touch = e.touches[0];
+      if (!touch || !dragging) return;
+      preventIfTaken(e, handlersRef.current.onMove({ clientY: touch.clientY }));
+    };
+    const onTouchEnd = () => {
+      if (!dragging) return;
+      dragging = false;
+      handlersRef.current.onEnd();
+    };
+    const onTouchCancel = () => {
+      if (!dragging) return;
+      dragging = false;
+      (handlersRef.current.onCancel ?? handlersRef.current.onEnd)();
+    };
+
+    if (usePointer) {
+      el.addEventListener('pointerdown', onPointerDown, { passive: true });
+      el.addEventListener('pointermove', onPointerMove, { passive: false });
+      el.addEventListener('pointerup', onPointerUp, { passive: true });
+      el.addEventListener('pointercancel', onPointerCancel, { passive: true });
+      // 指针移出容器（鼠标拖到窗口外松开）同样收口，否则位移悬挂
+      el.addEventListener('pointerleave', onPointerUp, { passive: true });
+    } else {
+      el.addEventListener('touchstart', onTouchStart, { passive: true });
+      el.addEventListener('touchmove', onTouchMove, { passive: false });
+      el.addEventListener('touchend', onTouchEnd, { passive: true });
+      el.addEventListener('touchcancel', onTouchCancel, { passive: true });
+    }
+
+    return () => {
+      if (usePointer) {
+        el.removeEventListener('pointerdown', onPointerDown);
+        el.removeEventListener('pointermove', onPointerMove);
+        el.removeEventListener('pointerup', onPointerUp);
+        el.removeEventListener('pointercancel', onPointerCancel);
+        el.removeEventListener('pointerleave', onPointerUp);
+      } else {
+        el.removeEventListener('touchstart', onTouchStart);
+        el.removeEventListener('touchmove', onTouchMove);
+        el.removeEventListener('touchend', onTouchEnd);
+        el.removeEventListener('touchcancel', onTouchCancel);
+      }
+    };
+  }, [disabled, scrollRef]);
+}

package/packages/agent-ui-kit/src/hooks/use-pull-down-history.ts

@@ -0,0 +1,241 @@
+/**
+ * 下拉加载历史 React 薄包装（机器见 pull-down-machine.ts）。
+ * wrapper 职责：machine 存 ref、状态镜像 useState、noMore 定时 reset、取消手势 reset、
+ * hasMore false→true 跃迁 reset（G9：分页游标重置后手势死区复活）及异步加载 in-flight 门控。
+ * 滚动位置真源在页面（isAtTopRef 只读透传）；store 的 isLoadingHistory 仍是跨调用业务防抖权威。
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPullDownMachine, NO_MORE_HOLD_MS, WHEEL_IDLE_RESET_MS } from '../utils/pull-down-machine';
+import { useDragGesture } from './use-drag-gesture';
+import { hapticTap } from '../utils/haptics';
+import type { PullStatus } from '../utils/pull-down-machine';
+
+export interface UsePullDownHistoryOptions {
+  isAtTopRef: React.MutableRefObject<boolean>;
+  isLoadingHistory: boolean;
+  hasMore: boolean;
+  onLoad: () => Promise<void>;
+  /** 鉴权或运行时尚未就绪时禁用手势，避免发出归属不明的历史请求。 */
+  disabled?: boolean;
+  /**
+   * 滚动容器 ref。传入后整套手势由容器上的原生监听接管（pointer 优先、touch 回退、非 passive）：
+   * React 合成事件是 passive 阻止不了原生滚动，且只监听 touch 会漏掉 pointerType=mouse
+   * 的输入（开发者工具模拟器与桌面浏览器）。传了就**不要**再往 JSX 绑手势事件，否则走两遍。
+   */
+  scrollRef?: React.RefObject<HTMLElement | null>;
+}
+
+export function usePullDownHistory(opts: UsePullDownHistoryOptions): {
+  pullStatus: PullStatus;
+  pullDistance: number;
+  handleTouchStart: (e: React.TouchEvent) => void;
+  handleTouchMove: (e: React.TouchEvent) => void;
+  handleTouchEnd: () => void;
+  handleTouchCancel: () => void;
+  handleWheel: (e: React.WheelEvent) => void;
+} {
+  const { isAtTopRef, isLoadingHistory, hasMore, onLoad, disabled, scrollRef } = opts;
+  const machineRef = useRef(createPullDownMachine());
+  const [pullStatus, setPullStatus] = useState<PullStatus>('idle');
+  const [pullDistance, setPullDistance] = useState(0);
+  const noMoreTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const loadInFlightRef = useRef<Promise<void> | null>(null);
+  const wheelIdleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  /** 本次连续滚动是否已触发过加载——惯性未停前不允许第二次。 */
+  const wheelLockedRef = useRef(false);
+
+  // 跨过触发线那一刻给一次轻触反馈：手势语义从「还在拉」变成「松手即加载」，
+  // 值得一个非视觉的确认信号（fail-soft，平台不支持即静默）。
+  const prevStatusRef = useRef<PullStatus>('idle');
+
+  const sync = useCallback(() => {
+    const { status, distance } = machineRef.current.getState();
+    if (status === 'ready' && prevStatusRef.current !== 'ready') hapticTap();
+    prevStatusRef.current = status;
+    setPullStatus(status);
+    setPullDistance(distance);
+  }, []);
+
+  const triggerLoad = useCallback(() => {
+    if (loadInFlightRef.current) return;
+    const task: Promise<void> = onLoad()
+      .catch(() => undefined)
+      .finally(() => {
+        if (loadInFlightRef.current === task) loadInFlightRef.current = null;
+        machineRef.current.reset();
+        sync();
+      });
+    loadInFlightRef.current = task;
+  }, [onLoad, sync]);
+
+  const handleTouchStart = useCallback(
+    (e: React.TouchEvent) => {
+      if (disabled) return;
+      const touch = e.touches[0];
+      if (!touch) return;
+      machineRef.current.touchStart(touch.clientY);
+    },
+    [disabled],
+  );
+
+  /** 推进机器并返回「是否需要阻止原生滚动」——合成事件与原生监听共用同一条逻辑。 */
+  const advanceTouchMove = useCallback(
+    (touch: { clientY: number }): boolean => {
+      if (disabled) return false;
+      const { preventDefault } = machineRef.current.touchMove({
+        clientY: touch.clientY,
+        isAtTop: isAtTopRef.current,
+        hasMore,
+        isLoading: isLoadingHistory,
+      });
+      sync();
+      return preventDefault;
+    },
+    [disabled, hasMore, isLoadingHistory, isAtTopRef, sync],
+  );
+
+  // 容器 ref 在场时由原生监听接管整套手势（pointer 优先，覆盖 mouse/touch/pen）
+  useDragGesture({
+    scrollRef,
+    disabled,
+    onStart: (point) => machineRef.current.touchStart(point.clientY),
+    onMove: advanceTouchMove,
+    onEnd: () => {
+      const { shouldLoad, holdNoMore } = machineRef.current.touchEnd({ hasMore });
+      if (shouldLoad) {
+        triggerLoad();
+      } else if (holdNoMore) {
+        if (noMoreTimerRef.current) clearTimeout(noMoreTimerRef.current);
+        noMoreTimerRef.current = setTimeout(() => {
+          machineRef.current.reset();
+          sync();
+        }, NO_MORE_HOLD_MS);
+      }
+      sync();
+    },
+    onCancel: () => {
+      machineRef.current.reset();
+      sync();
+    },
+  });
+
+  const handleTouchMove = useCallback(
+    (e: React.TouchEvent) => {
+      const touch = e.touches[0];
+      if (!touch) return;
+      if (advanceTouchMove(touch)) {
+        try {
+          e.preventDefault();
+        } catch {
+          /* React 合成事件为 passive：此路径下阻止不了，容器 ref 形态才是权威 */
+        }
+      }
+    },
+    [advanceTouchMove],
+  );
+
+  const handleTouchEnd = useCallback(() => {
+    if (disabled) return;
+    const { shouldLoad, holdNoMore } = machineRef.current.touchEnd({ hasMore });
+    if (shouldLoad) {
+      triggerLoad();
+    } else if (holdNoMore) {
+      if (noMoreTimerRef.current) clearTimeout(noMoreTimerRef.current);
+      noMoreTimerRef.current = setTimeout(() => {
+        machineRef.current.reset();
+        sync();
+      }, NO_MORE_HOLD_MS);
+    }
+    sync();
+  }, [disabled, hasMore, sync, triggerLoad]);
+
+  const handleTouchCancel = useCallback(() => {
+    machineRef.current.reset();
+    sync();
+  }, [sync]);
+
+  /**
+   * wheel 没有「松手」事件，用「静默 WHEEL_IDLE_RESET_MS」代替手势结束：
+   * 到期才复位视觉并解锁。惯性期间每个事件都会重设它，因此锁一直有效。
+   */
+  const scheduleWheelIdle = useCallback(() => {
+    if (wheelIdleTimerRef.current) clearTimeout(wheelIdleTimerRef.current);
+    wheelIdleTimerRef.current = setTimeout(() => {
+      machineRef.current.wheelIdle();
+      wheelIdleTimerRef.current = null;
+      wheelLockedRef.current = false;
+      sync();
+    }, WHEEL_IDLE_RESET_MS);
+  }, [sync]);
+
+  /** 推进 wheel 并返回「是否需要吞掉本次滚动」。原生监听与合成事件共用。 */
+  const advanceWheel = useCallback(
+    (deltaY: number): boolean => {
+      if (disabled) return false;
+      // 触发后到滚动停止之间：吞掉惯性。加载会把 scrollTop 抬到前插位置，
+      // 上方随即出现可滚空间，残余惯性会继续把它带走——落位就白设了。
+      if (wheelLockedRef.current) {
+        scheduleWheelIdle();
+        return true;
+      }
+      const { shouldLoad } = machineRef.current.wheel({
+        deltaY,
+        isAtTop: isAtTopRef.current,
+        hasMore,
+        isLoading: isLoadingHistory,
+      });
+      sync();
+      if (shouldLoad) {
+        wheelLockedRef.current = true;
+        triggerLoad();
+        scheduleWheelIdle();
+        return true;
+      }
+      scheduleWheelIdle();
+      return false;
+    },
+    [disabled, hasMore, isLoadingHistory, isAtTopRef, scheduleWheelIdle, sync, triggerLoad],
+  );
+
+  // 原生非 passive 绑定：React 的 onWheel 同样是 passive，preventDefault 无效，
+  // 吞不掉惯性。与 touch 通道同理（见 use-drag-gesture 文件头）。
+  useEffect(() => {
+    const el = scrollRef?.current;
+    if (!el || disabled) return undefined;
+    const onWheel = (e: WheelEvent) => {
+      if (advanceWheel(e.deltaY) && e.cancelable) e.preventDefault();
+    };
+    el.addEventListener('wheel', onWheel, { passive: false });
+    return () => el.removeEventListener('wheel', onWheel);
+  }, [advanceWheel, disabled, scrollRef]);
+
+  const handleWheel = useCallback(
+    (e: React.WheelEvent) => {
+      if (disabled) return;
+      // 传了 scrollRef 时手势已由原生监听接管，此路径仅为不传 ref 的旧用法保留
+      if (scrollRef?.current) return;
+      advanceWheel(e.deltaY);
+    },
+    [advanceWheel, disabled, scrollRef],
+  );
+
+  // G9：hasMore false→true 跃迁（分页游标重置）→ 机器复位（noMore 残留死区复活）
+  const prevHasMoreRef = useRef(hasMore);
+  useEffect(() => {
+    if (prevHasMoreRef.current === false && hasMore) {
+      machineRef.current.reset();
+      sync();
+    }
+    prevHasMoreRef.current = hasMore;
+  }, [hasMore, sync]);
+
+  // unmount 清理 noMore 定时器
+  useEffect(() => {
+    return () => {
+      if (noMoreTimerRef.current) clearTimeout(noMoreTimerRef.current);
+      if (wheelIdleTimerRef.current) clearTimeout(wheelIdleTimerRef.current);
+    };
+  }, []);
+
+  return { pullStatus, pullDistance, handleTouchStart, handleTouchMove, handleTouchEnd, handleTouchCancel, handleWheel };
+}

package/packages/agent-ui-kit/src/hooks/use-pull-down-wheel-native.test.ts

@@ -0,0 +1,64 @@
+// @vitest-environment happy-dom
+/**
+ * wheel 原生通道用例。核心契约：触发加载后到滚动停止之间，惯性 wheel 必须被 preventDefault
+ * 吞掉——加载会把 scrollTop 抬到前插位置，上方随即出现可滚空间，残余惯性会把落位带走。
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { createRoot } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import { createElement, useRef } from 'react';
+import { usePullDownHistory } from './use-pull-down-history';
+import { WHEEL_TRIGGER_ACCUM } from '../utils/pull-down-machine';
+
+function wheelEvent(deltaY: number) {
+  const e = new Event('wheel', { bubbles: true, cancelable: true }) as WheelEvent;
+  Object.defineProperty(e, 'deltaY', { value: deltaY });
+  return e;
+}
+
+function setup(onLoad: () => Promise<void>) {
+  const el = document.createElement('div');
+  document.body.appendChild(el);
+  const Host = () => {
+    const isAtTopRef = useRef(true);
+    usePullDownHistory({
+      isAtTopRef,
+      isLoadingHistory: false,
+      hasMore: true,
+      onLoad,
+      scrollRef: { current: el },
+    });
+    return null;
+  };
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  flushSync(() => createRoot(host).render(createElement(Host)));
+  return el;
+}
+
+describe('usePullDownHistory：wheel 原生通道', () => {
+  it('N1 未触发时不吞滚动（页面照常滚）', () => {
+    const el = setup(async () => {});
+    const e = wheelEvent(-10);
+    el.dispatchEvent(e);
+    expect(e.defaultPrevented).toBe(false);
+  });
+
+  it('N2 越阈触发后吞掉后续惯性，落位不被带走', async () => {
+    const onLoad = vi.fn(async () => {});
+    const el = setup(onLoad);
+
+    const trigger = wheelEvent(-(WHEEL_TRIGGER_ACCUM + 20));
+    el.dispatchEvent(trigger);
+    expect(onLoad).toHaveBeenCalledTimes(1);
+    expect(trigger.defaultPrevented).toBe(true);
+
+    // 惯性尾巴：既不得二次触发，也不得让原生滚动继续
+    for (let i = 0; i < 5; i += 1) {
+      const inertia = wheelEvent(-80);
+      el.dispatchEvent(inertia);
+      expect(inertia.defaultPrevented).toBe(true);
+    }
+    expect(onLoad).toHaveBeenCalledTimes(1);
+  });
+});

package/{apps/client → packages/agent-ui-kit}/src/hooks/useMediaUpload.ts

@@ -5,9 +5,9 @@ const mediaLogger = createLogger('media');
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useUploadAdapter, useRefreshSession, chooseImage, chooseVideo } from '@tbox.cn/app-sdk/client';
 
-import { isSessionExpiredError } from '@/utils/session-error';
-import { toast } from '@/utils/toast';
-import type { MediaItem, MediaType, MediaConfig } from '@/types/chat';
+import { isSessionExpiredError } from '../utils/session-error';
+import { toast } from '../utils/toast';
+import type { MediaItem, MediaType, MediaConfig } from '../types';
 
 let seq = 0;
 const nid = () => `media_${Date.now()}_${seq++}`;

package/{apps/client → packages/agent-ui-kit}/src/hooks/useTTSAutoPlay.ts

@@ -1,5 +1,6 @@
 import { useEffect } from 'react';
-import { useChatStore } from '@/store/chat';
+import type { CoreChatState } from '@tbox.cn/app-sdk/client';
+import { useChatStoreApi } from '../store-context';
 import { useTTSAdapter } from '@tbox.cn/app-sdk/client';
 
 const FLUSH_MS = 300; // 累积 delta 后批量送，避免过多 WS 消息
@@ -10,6 +11,7 @@ const FLUSH_MS = 300; // 累积 delta 后批量送，避免过多 WS 消息
  */
 export function useTTSAutoPlay(enabled: boolean) {
   const tts = useTTSAdapter();
+  const store = useChatStoreApi();
 
   useEffect(() => {
     if (!enabled || !tts || !tts.startStreaming) return;
@@ -37,7 +39,7 @@ export function useTTSAutoPlay(enabled: boolean) {
       if (!timer) timer = setTimeout(flush, FLUSH_MS);
     };
 
-    const handle = (state: ReturnType<typeof useChatStore.getState>) => {
+    const handle = (state: CoreChatState) => {
       const { messages, streamingMsgId } = state;
       const msg = messages.find((m) => m.id === streamingMsgId);
 
@@ -68,13 +70,13 @@ export function useTTSAutoPlay(enabled: boolean) {
       }
     };
 
-    const unsub = useChatStore.subscribe(handle);
-    handle(useChatStore.getState());
+    const unsub = store.subscribe(handle);
+    handle(store.getState());
 
     return () => {
       unsub();
       clearTimer();
       if (activeId) tts.stop();
     };
-  }, [enabled, tts]);
+  }, [enabled, tts, store]);
 }

package/packages/agent-ui-kit/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @app/agent-ui-kit：Agent 对话壳 UI 组件包（源码发布，单一模板统一化 W2-1）。
+ *
+ * 消费面：应用经 `<ChatPage store cards slots .../>` 单点装配（或自组 KitChatProvider 树）；
+ * 域模块（如 mall-home）经 home 槽渲染函数自持域 UI——kit 组件零域语义。
+ * 主题：`@app/agent-ui-kit/theme`（applyTheme）+ `theme/index.less`（配合纯 CSS 主题包级联）。
+ */
+
+// ── 首屏页面与注入位 ──
+export { ChatPage } from './ChatPage';
+export type { ChatPageProps } from './ChatPage';
+// ── 行为面（W2-3 收口：SDK client 导出退役后宿主——下拉加载历史手势族）──
+export { usePullDownHistory } from './hooks/use-pull-down-history';
+export type { UsePullDownHistoryOptions } from './hooks/use-pull-down-history';
+export {
+  KitChatProvider,
+  useChatStore,
+  useChatStoreApi,
+  useChatCards,
+  useChatRawCards,
+  useClientSlots,
+} from './store-context';
+export type { KitChatContextValue } from './store-context';
+
+// ── chat 设置（构建期快照 + HELLO_ACK 水合） ──
+export { configureChatConfigDefaults, useChatConfigStore } from './chat-config';
+export type { QuickCommand } from './chat-config';
+
+// ── 主题 ──
+export { applyTheme, currentTheme } from './theme/theme';
+
+// ── 卡片渲染（context 注册表注入） ──
+export { CardRenderer, RawCardRenderer } from './components/CardRenderer';
+
+// ── 壳组件族 ──
+export { MessageBubble } from './components/MessageBubble';
+export { ChatInput } from './components/ChatInput';
+export { QuickCommands } from './components/QuickCommands';
+export { MediaList } from './components/MediaList';
+export { ActionBar, CopyButton, getMessageCopyText } from './components/ActionBar';
+export { DebugButton } from './components/ActionBar/DebugButton';
+export { default as ChatHeader } from './components/ChatHeader';
+export { default as HistoryEntry } from './components/HistoryEntry';
+export { default as PullDownIndicator } from './components/PullDownIndicator';
+export { default as ReasoningBlock } from './components/ReasoningBlock';
+export { default as ScrollToBottomButton } from './components/ScrollToBottomButton';
+export { default as ToolCallBlock } from './components/ToolCallBlock';
+
+// ── hooks / utils ──
+export { useTTSAutoPlay } from './hooks/useTTSAutoPlay';
+export { useMediaUpload } from './hooks/useMediaUpload';
+export { toast } from './utils/toast';
+export type { ToastTone } from './utils/toast';
+export { copyText } from './utils/copyText';
+export { previewImages } from './utils/imagePreview';
+
+// ── 类型（协议类型 re-export 单一来源 + UI 层约定） ──
+export type {
+  ChatInputMessage,
+  ChatMessage,
+  FileTypeConfig,
+  InputMethod,
+  MediaConfig,
+  MediaItem,
+  MediaType,
+  MessageRole,
+  MessageStatus,
+  ToolCallInfo,
+} from './types';

package/packages/agent-ui-kit/src/store-context.tsx

@@ -0,0 +1,92 @@
+/**
+ * KitChatProvider：壳组件的 store 注入位（单一模板统一化 W2-1）。
+ *
+ * 壳组件不 import 应用 store——经 React context 读取注入的 store 与卡片注册表；
+ * 应用在 `<ChatPage store={useChatStore} cards={CHAT_REGISTRY} rawCards={CARD_REGISTRY}/>`
+ * 一处装配（或自组 KitChatProvider 树）。
+ *
+ * useChatStore 调用签名与 zustand 绑定 hook 逐字兼容（`useChatStore((s)=>s.x)`）——
+ * 组件代码从应用 store 迁移零改写（仅 import 来源变化）。
+ */
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import type { CardComponent, TboxCardPayload } from '@tbox.cn/app-contracts';
+import type { ClientSlotRegistry, CoreChatState, CoreChatStore } from '@tbox.cn/app-sdk/client';
+
+export interface KitChatContextValue {
+  /** 应用注入的 chat store（zustand 绑定 hook + API） */
+  readonly store: CoreChatStore;
+  /** 聊天入口卡片注册表（模块注册 + 组合层覆盖） */
+  readonly cards: Record<string, CardComponent>;
+  /** 原始形态卡片注册表（无覆盖；详情弹层等防嵌套消费） */
+  readonly rawCards: Record<string, CardComponent>;
+  /** 客户端槽注册表（home 首期唯一槽；缺席 = chat 流形态） */
+  readonly slots?: ClientSlotRegistry;
+  /**
+   * 旁路/消息卡内联流过滤（域注入；缺省恒等）：域声明哪些卡不进内联流
+   * （由域浮层自持，如 mall 会员门禁卡系）——同时参与 home-first 形态判定。
+   */
+  readonly filterInlineCards?: (cards: readonly TboxCardPayload[]) => TboxCardPayload[];
+}
+
+const IDENTITY_FILTER = (cards: readonly TboxCardPayload[]): TboxCardPayload[] => [...cards];
+
+const KitChatContext = createContext<KitChatContextValue | null>(null);
+
+export function KitChatProvider({
+  store,
+  cards,
+  rawCards,
+  slots,
+  filterInlineCards,
+  children,
+}: KitChatContextValue & { children: ReactNode }) {
+  const value = useMemo<KitChatContextValue>(
+    () => ({
+      store,
+      cards,
+      rawCards,
+      ...(slots ? { slots } : {}),
+      ...(filterInlineCards ? { filterInlineCards } : {}),
+    }),
+    [store, cards, rawCards, slots, filterInlineCards],
+  );
+  return <KitChatContext.Provider value={value}>{children}</KitChatContext.Provider>;
+}
+
+function useKitChatContext(): KitChatContextValue {
+  const value = useContext(KitChatContext);
+  if (!value) {
+    throw new Error('KitChatProvider 缺席：kit 组件须在 <ChatPage>（或自组 Provider）内使用');
+  }
+  return value;
+}
+
+/** 选择器读取（镜像 zustand 绑定 hook 调用签名；组件从 context 取 store）。 */
+export function useChatStore<T>(selector: (state: CoreChatState) => T): T {
+  return useKitChatContext().store(selector);
+}
+
+/** store API（getState/subscribe；effect/事件回调场景）。 */
+export function useChatStoreApi(): CoreChatStore {
+  return useKitChatContext().store;
+}
+
+/** 聊天入口卡片注册表（MessageBubble 等卡渲染消费）。 */
+export function useChatCards(): Record<string, CardComponent> {
+  return useKitChatContext().cards;
+}
+
+/** 原始形态卡片注册表（RawCardRenderer 消费）。 */
+export function useChatRawCards(): Record<string, CardComponent> {
+  return useKitChatContext().rawCards;
+}
+
+/** 客户端槽注册表（home 槽；缺席 = chat 流形态）。 */
+export function useClientSlots(): ClientSlotRegistry | undefined {
+  return useKitChatContext().slots;
+}
+
+/** 旁路/消息卡内联流过滤器（域注入；缺省恒等）。 */
+export function useInlineCardFilter(): (cards: readonly TboxCardPayload[]) => TboxCardPayload[] {
+  return useKitChatContext().filterInlineCards ?? IDENTITY_FILTER;
+}

package/packages/agent-ui-kit/src/test/setup.ts

@@ -0,0 +1,7 @@
+/**
+ * vitest 全局 setup：React act() 环境声明单一真源。
+ * 此前散落各用例内联声明、多数漏声明（act 告警刷屏 CI 日志）；
+ * 统一收敛后新用例自动继承，无需逐文件记忆。node 环境纯逻辑用例设此全局无副作用。
+ */
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean })
+  .IS_REACT_ACT_ENVIRONMENT = true;