@tbox.cn/app-template-agent 0.1.0

package/apps/client/src/hooks/useMediaUpload.ts

@@ -0,0 +1,237 @@
+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';
+
+let seq = 0;
+const nid = () => `media_${Date.now()}_${seq++}`;
+const MAX_SIM_PROGRESS = 90; // 模拟进度上限；真正完成才到 100
+
+/** 释放 blob: ObjectURL（仅浏览器环境；移除/清空媒体时调用防内存泄漏） */
+const revokeIfBlob = (src?: string) => {
+  if (src && src.startsWith('blob:') && typeof URL !== 'undefined') {
+    URL.revokeObjectURL(src);
+  }
+};
+
+function fileToType(f: File): MediaType {
+  if (f.type.startsWith('image')) return 'image';
+  if (f.type.startsWith('video')) return 'video';
+  if (f.type.startsWith('audio')) return 'audio';
+  return 'file';
+}
+
+const typeLabel = (t: MediaType) =>
+  t === 'image' ? '图片' : t === 'video' ? '视频' : t === 'audio' ? '音频' : '文件';
+
+/**
+ * 媒体选取 + 上传（走 upload adapter，对齐原模板行为）。
+ * - 浏览器：addFiles(File[])（来自 <input type=file>）；支付宝壳：addFromBridge('image'|'camera'|'video')
+ * - 上传中模拟进度（驱动圆形进度环）；成功填 fileId；safed===false → illegal（未过审）；
+ *   session 过期自动 refresh + 重试一次；失败可 retry。
+ * - 无 upload adapter（session 未就绪）时 Toast 提示，不静默吞掉。
+ */
+export function useMediaUpload(maxTotal = 9, mediaConfig?: MediaConfig) {
+  const adapter = useUploadAdapter();
+  const refreshSession = useRefreshSession();
+  const [items, setItems] = useState<MediaItem[]>([]);
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+  const sourceRef = useRef<Map<string, { source: File | string; type: MediaType; name?: string }>>(new Map());
+  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  const patch = useCallback((id: string, p: Partial<MediaItem>) => {
+    setItems((prev) => prev.map((it) => (it.id === id ? { ...it, ...p } : it)));
+  }, []);
+
+  const clearTimer = (id: string) => {
+    const t = timersRef.current.get(id);
+    if (t !== undefined) {
+      clearTimeout(t);
+      timersRef.current.delete(id);
+    }
+  };
+
+  // 进度模拟：随机间隔 100-500ms、步长 5-15，累加到 MAX_SIM_PROGRESS
+  const startProgressSim = (id: string) => {
+    clearTimer(id);
+    let cur = 0;
+    const next = () => {
+      const delay = Math.floor(Math.random() * 401) + 100;
+      const t = setTimeout(() => {
+        cur = Math.min(cur + Math.floor(Math.random() * 11) + 5, MAX_SIM_PROGRESS);
+        patch(id, { uploadProgress: cur });
+        if (cur < MAX_SIM_PROGRESS) next();
+        else timersRef.current.delete(id);
+      }, delay);
+      timersRef.current.set(id, t);
+    };
+    next();
+  };
+
+  useEffect(
+    () => () => {
+      timersRef.current.forEach((t) => clearTimeout(t));
+      timersRef.current.clear();
+    },
+    [],
+  );
+
+  const doUpload = useCallback(
+    (id: string) => {
+      const rec = sourceRef.current.get(id);
+      if (!adapter || !rec) return;
+      patch(id, { isUploading: true, uploadProgress: 0, uploadFailed: false, uploadError: undefined, illegal: false });
+      startProgressSim(id);
+
+      const done = (res: { fileId: string; mimeType?: string; safed?: boolean }) => {
+        clearTimer(id);
+        patch(id, {
+          fileId: res.fileId,
+          mimeType: res.mimeType,
+          isUploading: false,
+          uploadProgress: 100,
+          ...(res.safed === false ? { illegal: true } : {}),
+        });
+      };
+
+      (async () => {
+        try {
+          done(await adapter.upload(rec.source, { type: rec.type, name: rec.name }));
+        } catch (err) {
+          // session 过期 → 刷新并重试一次
+          if (isSessionExpiredError(err) && refreshSession) {
+            try {
+              const next = await refreshSession();
+              if (next.upload) {
+                done(await next.upload.upload(rec.source, { type: rec.type, name: rec.name }));
+                return;
+              }
+            } catch {
+              /* 重试失败 → 落到下方失败处理 */
+            }
+          }
+          clearTimer(id);
+          patch(id, { isUploading: false, uploadFailed: true, uploadError: String((err as Error)?.message || err) });
+        }
+      })();
+    },
+    [adapter, refreshSession, patch],
+  );
+
+  const enqueue = useCallback(
+    (source: File | string, meta: { type: MediaType; src: string; name?: string; size?: number }) => {
+      if (!adapter) {
+        toast('上传暂不可用（未登录或未配置 TBOX 凭证）');
+        return;
+      }
+      const id = nid();
+      sourceRef.current.set(id, { source, type: meta.type, name: meta.name });
+      setItems((prev) => [
+        ...prev,
+        { id, type: meta.type, src: meta.src, name: meta.name, size: meta.size, isUploading: true, uploadProgress: 0 },
+      ]);
+      doUpload(id);
+    },
+    [adapter, doUpload],
+  );
+
+  const retry = useCallback((id: string) => doUpload(id), [doUpload]);
+
+  const room = () => Math.max(0, maxTotal - itemsRef.current.length);
+
+  // 校验单个待加项：超总数/分类型数量→'stop'（停止本批）；超单文件大小→'skip'（跳过该文件）。
+  // 对齐原模板 useFileUpload 的 checkLimit + checkFileSize。
+  const validate = useCallback(
+    (
+      type: MediaType,
+      size: number | undefined,
+      total: number,
+      typeCount: number,
+    ): 'ok' | 'skip' | 'stop' => {
+      if (total >= maxTotal) {
+        toast(`最多添加 ${maxTotal} 个文件`);
+        return 'stop';
+      }
+      const tc = mediaConfig?.[type];
+      if (tc && typeCount >= tc.maxCount) {
+        toast(`最多添加 ${tc.maxCount} 个${typeLabel(type)}`);
+        return 'stop';
+      }
+      if (tc && size && size > tc.maxSize) {
+        toast(`文件大小不能超过 ${(tc.maxSize / 1048576).toFixed(0)}MB`);
+        return 'skip';
+      }
+      return 'ok';
+    },
+    [maxTotal, mediaConfig],
+  );
+
+  const addFiles = useCallback(
+    (files: File[]) => {
+      let total = itemsRef.current.length;
+      const typeCounts: Record<string, number> = {};
+      for (const it of itemsRef.current) typeCounts[it.type] = (typeCounts[it.type] || 0) + 1;
+      for (const f of files) {
+        const type = fileToType(f);
+        const v = validate(type, f.size, total, typeCounts[type] || 0);
+        if (v === 'stop') break;
+        if (v === 'skip') continue;
+        enqueue(f, { type, src: URL.createObjectURL(f), name: f.name, size: f.size });
+        total += 1;
+        typeCounts[type] = (typeCounts[type] || 0) + 1;
+      }
+    },
+    [enqueue, validate],
+  );
+
+  const addFromBridge = useCallback(
+    async (kind: 'image' | 'camera' | 'video') => {
+      if (!adapter) {
+        toast('上传暂不可用（未登录或未配置 TBOX 凭证）');
+        return;
+      }
+      try {
+        const res =
+          kind === 'video'
+            ? await chooseVideo()
+            : await chooseImage(room(), kind === 'camera' ? ['camera'] : undefined);
+        const type: MediaType = kind === 'video' ? 'video' : 'image';
+        let total = itemsRef.current.length;
+        let typeCount = itemsRef.current.filter((it) => it.type === type).length;
+        for (const f of res?.files || []) {
+          if (!f.data) continue;
+          const v = validate(type, f.size, total, typeCount);
+          if (v === 'stop') break;
+          if (v === 'skip') continue;
+          enqueue(f.data, { type, src: f.data, name: f.name, size: f.size });
+          total += 1;
+          typeCount += 1;
+        }
+      } catch (err) {
+        console.warn('[media] bridge pick failed:', err);
+      }
+    },
+    [adapter, enqueue, validate],
+  );
+
+  const removeItem = useCallback((id: string) => {
+    clearTimer(id);
+    const rec = itemsRef.current.find((it) => it.id === id);
+    revokeIfBlob(rec?.src);
+    sourceRef.current.delete(id);
+    setItems((prev) => prev.filter((it) => it.id !== id));
+  }, []);
+  const clear = useCallback(() => {
+    timersRef.current.forEach((t) => clearTimeout(t));
+    timersRef.current.clear();
+    itemsRef.current.forEach((it) => revokeIfBlob(it.src));
+    sourceRef.current.clear();
+    setItems([]);
+  }, []);
+  const uploading = items.some((it) => it.isUploading);
+
+  return { items, addFiles, addFromBridge, removeItem, retry, clear, uploading };
+}

package/apps/client/src/hooks/usePullDownHistory.ts

@@ -0,0 +1,97 @@
+import { useCallback, useRef, useState } from 'react';
+
+export type PullStatus = 'idle' | 'pulling' | 'ready' | 'loading' | 'noMore';
+
+const DAMPING = 0.4;
+const THRESHOLD = 60;
+
+interface Options {
+  isAtTopRef: React.MutableRefObject<boolean>;
+  isLoadingHistory: boolean;
+  hasMore: boolean;
+  onLoad: () => Promise<void>;
+}
+
+/** 列表顶部下拉加载历史（纯 H5 触摸，去 Taro）。 */
+export function usePullDownHistory({ isAtTopRef, isLoadingHistory, hasMore, onLoad }: Options) {
+  const [pullStatus, setPullStatus] = useState<PullStatus>('idle');
+  const [pullDistance, setPullDistance] = useState(0);
+  const startYRef = useRef(0);
+  const isPullingRef = useRef(false);
+
+  const handleTouchStart = useCallback(
+    (e: React.TouchEvent) => {
+      if (isLoadingHistory || pullStatus === 'loading') return;
+      const touch = e.touches[0];
+      if (!touch) return;
+      startYRef.current = touch.clientY;
+      isPullingRef.current = isAtTopRef.current;
+    },
+    [isLoadingHistory, pullStatus, isAtTopRef],
+  );
+
+  const handleTouchMove = useCallback(
+    (e: React.TouchEvent) => {
+      if (!isPullingRef.current) return;
+      if (isLoadingHistory || pullStatus === 'loading') return;
+      if (!hasMore && pullStatus !== 'pulling' && pullStatus !== 'ready') return;
+
+      const touch = e.touches[0];
+      if (!touch) return;
+      const deltaY = touch.clientY - startYRef.current;
+
+      if (deltaY <= 0) {
+        if (pullStatus !== 'idle') {
+          setPullStatus('idle');
+          setPullDistance(0);
+        }
+        return;
+      }
+
+      try {
+        e.preventDefault();
+      } catch {
+        /* passive listener, ignore */
+      }
+
+      const distance = deltaY * DAMPING;
+      if (!hasMore) {
+        setPullStatus('noMore');
+        setPullDistance(Math.min(distance, THRESHOLD));
+        return;
+      }
+      setPullDistance(distance);
+      setPullStatus(distance > THRESHOLD ? 'ready' : 'pulling');
+    },
+    [isLoadingHistory, pullStatus, hasMore],
+  );
+
+  const handleTouchEnd = useCallback(() => {
+    if (!isPullingRef.current) return;
+    isPullingRef.current = false;
+
+    if (pullStatus === 'ready' && hasMore) {
+      setPullStatus('loading');
+      setPullDistance(THRESHOLD);
+      onLoad()
+        .then(() => {
+          setPullStatus('idle');
+          setPullDistance(0);
+        })
+        .catch(() => {
+          setPullStatus('idle');
+          setPullDistance(0);
+        });
+    } else if (pullStatus === 'noMore') {
+      setTimeout(() => {
+        setPullStatus('idle');
+        setPullDistance(0);
+      }, 1500);
+    } else {
+      setPullStatus('idle');
+      setPullDistance(0);
+    }
+  }, [pullStatus, hasMore, onLoad]);
+
+  return { pullStatus, pullDistance, handleTouchStart, handleTouchMove, handleTouchEnd };
+}

package/apps/client/src/hooks/useTTSAutoPlay.ts

@@ -0,0 +1,80 @@
+import { useEffect } from 'react';
+import { useChatStore } from '@/store/chat';
+import { useTTSAdapter } from '@tbox.cn/app-sdk/client';
+
+const FLUSH_MS = 300; // 累积 delta 后批量送，避免过多 WS 消息
+
+/**
+ * TTS 自动播放：开启后订阅流式消息，**边生成边送** TTS 流式播放（对齐原模板的流式自动朗读）。
+ * 关闭 / 卸载时停止。
+ */
+export function useTTSAutoPlay(enabled: boolean) {
+  const tts = useTTSAdapter();
+
+  useEffect(() => {
+    if (!enabled || !tts || !tts.startStreaming) return;
+
+    let activeId: string | null = null;
+    let prevContent = '';
+    let pending = '';
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const clearTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+    const flush = () => {
+      clearTimer();
+      if (pending) {
+        tts.sendText?.(pending);
+        pending = '';
+      }
+    };
+    const enqueue = (delta: string) => {
+      pending += delta;
+      if (!timer) timer = setTimeout(flush, FLUSH_MS);
+    };
+
+    const handle = (state: ReturnType<typeof useChatStore.getState>) => {
+      const { messages, streamingMsgId } = state;
+      const msg = messages.find((m) => m.id === streamingMsgId);
+
+      // 流结束 / 无流式消息 → 结束这轮
+      if (!msg || msg.status === 'done') {
+        if (activeId) {
+          flush();
+          tts.finishStreaming?.();
+          activeId = null;
+          prevContent = '';
+        }
+        return;
+      }
+      // 新流式消息 → 开一轮
+      if (msg.status === 'streaming' && msg.id !== activeId) {
+        tts.stop();
+        clearTimer();
+        pending = '';
+        activeId = msg.id;
+        prevContent = '';
+        tts.startStreaming?.();
+        return;
+      }
+      // 内容增量 → 入队
+      if (activeId === msg.id && msg.content.length > prevContent.length) {
+        enqueue(msg.content.slice(prevContent.length));
+        prevContent = msg.content;
+      }
+    };
+
+    const unsub = useChatStore.subscribe(handle);
+    handle(useChatStore.getState());
+
+    return () => {
+      unsub();
+      clearTimer();
+      if (activeId) tts.stop();
+    };
+  }, [enabled, tts]);
+}

package/apps/client/src/main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { configureRuntime } from '@tbox.cn/app-sdk/client';
+import App from './app';
+import './styles/global.less';
+
+// H1：环境值注入点（SDK 零 Vite 依赖）——VITE_API_URL 空串 = 同源相对路径
+configureRuntime({ apiBaseUrl: import.meta.env.VITE_API_URL as string | undefined });
+
+const el = document.getElementById('root');
+if (el) {
+  createRoot(el).render(
+    <StrictMode>
+      <App />
+    </StrictMode>,
+  );
+}

package/apps/client/src/modules.ts

@@ -0,0 +1,30 @@
+/**
+ * 客户端模块注册装配文件（与 apps/server/src/modules.ts 逐行同构）。
+ * tbox CLI 协助维护锚点区；你也可以直接编辑自由区。
+ *
+ * 锚点区：@tbox:imports-begin/end（模块 import 行）+ @tbox:register-begin/end（模块数组）
+ * CLI 行为：增量插入/删除模块行，保留非标行。
+ */
+import type { ClientContext, InferModuleCards } from '@tbox.cn/app-sdk/client';
+
+// @tbox:imports-begin
+import { clientModule as moduleWeather } from '@app/module-weather/client';
+// @tbox:imports-end
+
+// @tbox:register-begin
+const modules = [
+  moduleWeather,
+];
+// @tbox:register-end
+
+// 自由区：可做装配级定制——条件注册、顺序调整
+
+/** 注册所有已安装模块（客户端装配——勿与 apps/server/src/modules.ts 混淆） */
+export function registerAll(ctx: ClientContext): void {
+  for (const m of modules) {
+    m.register(ctx);
+  }
+}
+
+// 类型从运行时装配数组自动推导：增删模块后 CardType 自动收缩/扩展（002 §6.7）
+export type CardType = InferModuleCards<(typeof modules)[number]>;

package/apps/client/src/pages/index/index.less

@@ -0,0 +1,43 @@
+.chat-page {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  position: relative;
+  background: #eef2f9;
+
+  &__bg {
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    background-image: linear-gradient(180deg, #9dc6ff 0%, #e5f0ff 63%, #e5f0ff 100%);
+    opacity: 0.66;
+    pointer-events: none;
+  }
+
+  &__body-wrapper {
+    flex: 1;
+    min-height: 0;
+    position: relative;
+    z-index: 1;
+    display: flex;
+    flex-direction: column;
+  }
+
+  &__body {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    overflow-anchor: none;
+    overscroll-behavior: contain;
+    position: relative;
+    padding: 10px 0 8px;
+    width: 100%;
+    max-width: var(--tbox-content-max-width);
+    margin: 0 auto;
+    scrollbar-width: none;
+
+    &::-webkit-scrollbar {
+      display: none;
+    }
+  }
+}

package/apps/client/src/pages/index/index.tsx

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef, useState, type ComponentType } from 'react';
+import { useChatStore } from '@/store/chat';
+import { useTTSAutoPlay } from '@/hooks/useTTSAutoPlay';
+import { MessageBubble } from '@/components/MessageBubble';
+import { ChatInput } from '@/components/ChatInput';
+import { QuickCommands } from '@/components/QuickCommands';
+import ChatHeader from '@/components/ChatHeader';
+import ScrollToBottomButton from '@/components/ScrollToBottomButton';
+import PullDownIndicator from '@/components/PullDownIndicator';
+import { usePullDownHistory } from '@/hooks/usePullDownHistory';
+import { CardRenderer } from '@/cards/CardRenderer';
+import type { ChatInputMessage } from '@/types/chat';
+import './index.less';
+
+export interface ChatLandingProps {
+  onSend: (input: string | ChatInputMessage) => void;
+}
+
+export type ChatLandingComponent = ComponentType<ChatLandingProps>;
+
+interface IndexPageProps {
+  landing?: ChatLandingComponent;
+}
+
+export default function IndexPage({ landing: Landing }: IndexPageProps) {
+  const messages = useChatStore((s) => s.messages);
+  const historyMessages = useChatStore((s) => s.historyMessages);
+  const historyHasMore = useChatStore((s) => s.historyHasMore);
+  const isLoadingHistory = useChatStore((s) => s.isLoadingHistory);
+  const loadMoreHistory = useChatStore((s) => s.loadMoreHistory);
+  const isGenerating = useChatStore((s) => s.isGenerating);
+  const orphanCards = useChatStore((s) => s.orphanCards);
+  const initConversation = useChatStore((s) => s.initConversation);
+  const destroy = useChatStore((s) => s.destroy);
+  const sendMessage = useChatStore((s) => s.sendMessage);
+  const cancelGeneration = useChatStore((s) => s.cancelGeneration);
+  const clearChat = useChatStore((s) => s.clearChat);
+
+  const [ttsAutoPlay, setTtsAutoPlay] = useState(false);
+  const [showScrollToBottom, setShowScrollToBottom] = useState(false);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const isAtTopRef = useRef(false);
+  const isNearBottomRef = useRef(true);
+
+  // TTS 自动播放：开启后边生成边流式朗读
+  useTTSAutoPlay(ttsAutoPlay);
+
+  const send = useCallback((input: string | ChatInputMessage) => sendMessage(input), [sendMessage]);
+
+  const scrollToBottom = useCallback(() => {
+    const el = bodyRef.current;
+    if (el) el.scrollTop = el.scrollHeight;
+    isNearBottomRef.current = true;
+    setShowScrollToBottom(false);
+  }, []);
+
+  const NEAR_BOTTOM = 150;
+  const onScroll = useCallback(() => {
+    const el = bodyRef.current;
+    if (!el) return;
+    isAtTopRef.current = el.scrollTop <= 5;
+    const distanceToBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+    isNearBottomRef.current = distanceToBottom < NEAR_BOTTOM;
+    setShowScrollToBottom(!isNearBottomRef.current);
+  }, []);
+
+  // 下拉加载历史：加载时保持滚动位置（记录加载前高度，加载后补偿）
+  const onLoadHistory = useCallback(async () => {
+    const el = bodyRef.current;
+    const prevHeight = el?.scrollHeight ?? 0;
+    await loadMoreHistory();
+    requestAnimationFrame(() => {
+      const cur = bodyRef.current;
+      if (cur) cur.scrollTop += cur.scrollHeight - prevHeight;
+    });
+  }, [loadMoreHistory]);
+
+  const pull = usePullDownHistory({
+    isAtTopRef,
+    isLoadingHistory,
+    hasMore: historyHasMore,
+    onLoad: onLoadHistory,
+  });
+
+  useEffect(() => {
+    initConversation();
+    return () => destroy();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // 仅在贴近底部时自动滚动，避免打断用户上翻查看历史
+  useEffect(() => {
+    if (isNearBottomRef.current) {
+      const el = bodyRef.current;
+      if (el) el.scrollTop = el.scrollHeight;
+    }
+  }, [messages, orphanCards]);
+
+  return (
+    <div className="chat-page">
+      <div className="chat-page__bg" />
+      <ChatHeader
+        ttsAutoPlay={ttsAutoPlay}
+        onToggleTTS={() => setTtsAutoPlay((v) => !v)}
+        onClearChat={clearChat}
+      />
+
+      <div className="chat-page__body-wrapper">
+        <div
+          className="chat-page__body"
+          ref={bodyRef}
+          onScroll={onScroll}
+          onTouchStart={pull.handleTouchStart}
+          onTouchMove={pull.handleTouchMove}
+          onTouchEnd={pull.handleTouchEnd}
+        >
+          {/* 下拉加载历史指示器 */}
+          <PullDownIndicator status={pull.pullStatus} distance={pull.pullDistance} />
+
+          {/* 历史消息（下拉加载） */}
+          {historyMessages.map((msg) => (
+            <MessageBubble key={msg.id} message={msg} />
+          ))}
+
+          {Landing ? <Landing onSend={send} /> : null}
+
+          {/* 业务旁路 emit 的卡片（如欢迎卡） */}
+          {orphanCards.map((card) => (
+            <CardRenderer key={card.id} card={card} />
+          ))}
+
+          {/* 消息（每条消息下的卡片由 MessageBubble 内部渲染） */}
+          {messages.map((msg) => (
+            <MessageBubble key={msg.id} message={msg} />
+          ))}
+        </div>
+
+        <ScrollToBottomButton visible={showScrollToBottom && isGenerating} onClick={scrollToBottom} />
+      </div>
+
+      <QuickCommands onCommand={send} />
+      <ChatInput generating={isGenerating} onSend={send} onCancel={cancelGeneration} onNewChat={clearChat} />
+    </div>
+  );
+}

package/apps/client/src/platform/AgentChatApp.tsx

@@ -0,0 +1,39 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { AdapterProvider, createPlatformAdapters, type AdapterContextValue } from '@tbox.cn/app-sdk/client';
+import type { TboxSessionData } from '@tbox.cn/app-contracts';
+import IndexPage, { type ChatLandingComponent } from '@/pages/index/index';
+import { authClient, platformApi } from './agent-runtime';
+
+/** 平台默认的全栈对话运行时。普通本地应用无需读取或修改。 */
+export default function AgentChatApp({ landing }: { landing?: ChatLandingComponent }) {
+  const [session, setSession] = useState<TboxSessionData | null>(null);
+  // TTS 不依赖 session，恒可用且保持同一实例（播放状态不因会话刷新丢失）
+  const tts = useMemo(() => createPlatformAdapters().tts, []);
+
+  useEffect(() => {
+    authClient
+      .ensureAuth()
+      .then((auth) => platformApi.getTboxSession(auth.identity.userId))
+      .then(setSession)
+      .catch((err) => console.error('[AgentChatApp] tbox session init failed:', err));
+  }, []);
+
+  const refreshSession = useCallback(async (): Promise<AdapterContextValue> => {
+    platformApi.clearTboxSession();
+    const auth = await authClient.refreshAuth();
+    const data = await platformApi.getTboxSession(auth.identity.userId, true);
+    setSession(data);
+    return { tts, ...createPlatformAdapters(data, { tts }), refreshSession };
+  }, [tts]);
+
+  const adapters = useMemo<AdapterContextValue>(() => {
+    if (!session) return { tts, refreshSession };
+    return { tts, ...createPlatformAdapters(session, { tts }), refreshSession };
+  }, [session, tts, refreshSession]);
+
+  return (
+    <AdapterProvider value={adapters}>
+      <IndexPage landing={landing} />
+    </AdapterProvider>
+  );
+}