@baimingtao/lbs-agent 1.0.0

package/interfaces/web/frontend/src/hooks/useAgent.ts

@@ -0,0 +1,507 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createWsConnection, createRunId, sendRunCommand, type WsMessage, type RunOptions, type SessionObservability } from '../api/client';
+import type { CatState, ChatMessage, ToolTimelineNode } from '../types';
+
+/** 清理模型输出中的残留标记，返回纯净回答。
+ * 思考过程由 API 级 thinking stream 提供（streamThinkingRef），不依赖文本标记。 */
+function parseThinkingFromResult(text: string): { thinking: string; answer: string } {
+  if (!text) return { thinking: '', answer: '' };
+  const marker = text.search(/\[思考\]/);
+  let answerPart = marker >= 0 ? text.slice(0, marker) : text;
+  let thinkingPart = marker >= 0 ? text.slice(marker + '[思考]'.length) : '';
+
+  // 网关/模型偶尔把最终答案复制到 [思考] 后面；重复内容不应再次进入思考块。
+  const normalizedAnswer = answerPart.replace(/\s+/g, ' ').trim();
+  const normalizedThinking = thinkingPart.replace(/\s+/g, ' ').trim();
+  if (normalizedAnswer && normalizedThinking && normalizedThinking.includes(normalizedAnswer.slice(0, Math.min(80, normalizedAnswer.length)))) {
+    thinkingPart = '';
+  }
+
+  const clean = (value: string) => value
+    .replace(/={3,}\s*Agent:[^\n]*/gi, '')
+    .replace(/Agent:\s*[^\n]*/gi, '')
+    .replace(/Model:\s*[^\n]*/gi, '')
+    .replace(/Tools:\s*[^\n]*/gi, '')
+    .replace(/Task:\s*[^\n]*/gi, '')
+    .replace(/--- 迭代 \d+ (\([^)]+\) )?---/g, '')
+    .replace(/\[思考\]|\[工具\]|\[结果\]|\[思考模式已启用\]/g, '')
+    .trim();
+
+  return { thinking: clean(thinkingPart), answer: clean(answerPart) };
+}
+
+function shorten(value: unknown, max = 180): string {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function isGenericRuntimeMessage(value: unknown): boolean {
+  const text = String(value || '').trim().toLowerCase();
+  return !text || ['iteration started', 'calling llm', 'llm response', 'tool executed'].includes(text);
+}
+
+
+export interface ThinkingStep {
+  type: 'thinking' | 'tool_call' | 'result' | 'iteration' | 'error' | 'verify';
+  label: string;
+  desc: string;
+  tag?: string;
+  time?: string;
+}
+
+export function useAgent(sessionId?: string) {
+  const [connected, setConnected] = useState(false);
+  const [catState, setCatState] = useState<CatState>({ status: 'idle' });
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [lastUsage, setLastUsage] = useState<{ input: number; output: number; cost: string } | null>(null);
+  const [observability, setObservability] = useState<SessionObservability | null>(null);
+  const [lastModel, setLastModel] = useState('');
+  const [lastDuration, setLastDuration] = useState(0);
+  const wsRef = useRef<WebSocket | null>(null);
+  const pendingMsgRef = useRef<Partial<ChatMessage> | null>(null);
+  const streamTextRef = useRef('');
+  const streamThinkingRef = useRef('');
+  const streamIdRef = useRef('');
+  const thinkingStepsRef = useRef<ThinkingStep[]>([]);
+  const thinkingStartRef = useRef(0);
+  const streamFlushRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const typewriterRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const currentThinkMode = useRef(false);
+  const currentSessionIdRef = useRef(sessionId || '');
+  const activeRunIdRef = useRef('');
+  const reconnectTimerRef = useRef<number | null>(null);
+  const connectingRef = useRef(false);
+  const closeHandledRef = useRef(false);
+
+  useEffect(() => {
+    currentSessionIdRef.current = sessionId || '';
+    // 切换会话时清零实时指标，避免残留旧会话数据
+    setObservability(null);
+    setLastModel('');
+    setLastDuration(0);
+  }, [sessionId]);
+
+  useEffect(() => {
+    let disposed = false;
+    const isCurrentRunMessage = (msg: WsMessage) => {
+      if (msg.type === 'connected') return true;
+      if (msg.run_id !== activeRunIdRef.current || msg.session_id !== currentSessionIdRef.current) return false;
+      return true;
+    };
+    const scheduleReconnect = () => {
+      if (disposed || reconnectTimerRef.current !== null || connectingRef.current) return;
+      reconnectTimerRef.current = window.setTimeout(() => {
+        reconnectTimerRef.current = null;
+        connect();
+      }, 2000);
+    };
+    const connect = () => {
+      if (disposed || connectingRef.current || (wsRef.current && wsRef.current.readyState === WebSocket.OPEN)) return;
+      connectingRef.current = true;
+      closeHandledRef.current = false;
+      let ws: WebSocket;
+      ws = createWsConnection((msg: WsMessage) => {
+        if (wsRef.current !== ws) return;
+        if (!isCurrentRunMessage(msg)) return;
+        switch (msg.type) {
+          case 'connected':
+            setConnected(true);
+            // 每次连接或重连都重置状态，彻底防止卡在 running
+            setCatState({ status: 'idle' });
+            pendingMsgRef.current = null;
+            streamTextRef.current = '';
+            streamThinkingRef.current = '';
+            thinkingStepsRef.current = [];
+            thinkingStartRef.current = 0;
+            if (streamFlushRef.current !== null) { clearTimeout(streamFlushRef.current); streamFlushRef.current = null; }
+            streamIdRef.current = '';
+            // 只有没有选中会话时才显示连接提示；切换已有会话不能用欢迎语覆盖历史内容。
+            if (!currentSessionIdRef.current) {
+              setMessages(prev => prev.length ? prev : [{ id: 'welcome', type: 'agent', text: msg.message || '🐾 已连接到 LBS Agent', timestamp: Date.now(), success: true }]);
+            }
+            break;
+          case 'status':
+            setCatState({ status: (msg.cat_state as CatState['status']) || 'idle', iteration: msg.capsules?.iteration, worker: msg.capsules?.worker, latency: msg.capsules?.latency, tokens: msg.capsules?.tokens });
+            // 记录思考开始时间
+            if (msg.cat_state === 'running' && !thinkingStartRef.current) {
+              thinkingStartRef.current = Date.now();
+              thinkingStepsRef.current = [];
+            }
+            break;
+          case 'runtime_event': {
+            const evt = msg as any;
+            const eventType = evt.event_type || '';
+            const payload = evt.payload || {};
+            const phase = payload.phase || '';
+            const transition = payload.transition || '';
+            // 后端事件枚举使用 snake_case 小写；前端比较统一为大写枚举，避免思考步骤静默丢失。
+            const normalizedPhase = String(phase).toUpperCase();
+            const normalizedTransition = String(transition).toUpperCase();
+            const evtMsg = payload.message || '';
+            const iteration = payload.iteration || 0;
+
+            if (!eventType) break;
+
+            // Build structured thinking steps from runtime events
+            const steps = thinkingStepsRef.current;
+            const iterLabel = iteration ? `第${iteration}轮` : '';
+
+            if (normalizedPhase === 'ITERATION' && normalizedTransition === 'ITERATION_START') {
+              const taskText = shorten(payload.task || payload.task_preview || payload.metadata?.task_preview || payload.metadata?.task || '当前用户请求', 1000);
+              steps.push({
+                type: 'iteration',
+                label: iterLabel ? `${iterLabel} · PLAN` : 'PLAN',
+                desc: evtMsg && !isGenericRuntimeMessage(evtMsg)
+                  ? shorten(evtMsg, 260)
+                  : `围绕“${taskText}”整理已知信息，判断是否需要调用工具，并规划本轮行动`,
+                tag: 'PLAN',
+                time: new Date().toLocaleTimeString(),
+              });
+            } else if (normalizedPhase === 'LLM_CALL' && normalizedTransition === 'LLM_REQUEST') {
+              const taskText = shorten(payload.task || payload.task_preview || payload.metadata?.task_preview || payload.metadata?.task || '当前用户请求', 1000);
+              const hasTools = Number(payload.metadata?.tool_count || payload.tool_count || 0) > 0;
+              steps.push({
+                type: 'thinking',
+                label: iterLabel ? `${iterLabel} · LLM` : 'LLM',
+                desc: `分析“${taskText}”：${hasTools ? '判断需要哪些工具、参数和证据' : '判断是否可以直接作答并检查回答边界'}`,
+                tag: payload.metadata?.stream ? 'LLM · 流式' : 'LLM',
+                time: new Date().toLocaleTimeString(),
+              });
+            } else if (normalizedPhase === 'LLM_CALL' && normalizedTransition === 'LLM_RESPONSE') {
+              // 更新最后一步，并把 ACT/REFLECT 的结果落到对应步骤中
+              const last = steps[steps.length - 1];
+              const toolCount = Number(payload.metadata?.tool_calls || payload.tool_calls || 0);
+              if (last && last.type === 'thinking') {
+                last.desc = toolCount > 0
+                  ? `模型完成判断，决定调用 ${toolCount} 个工具获取证据`
+                  : `模型完成分析，形成直接回答（finish=${payload.metadata?.finish_reason || 'stop'}）`;
+                last.tag = toolCount > 0 ? `ACT · ${toolCount}个工具` : 'REFLECT · 直接回答';
+                if (toolCount > 0) {
+                  last.type = 'tool_call';
+                  last.label = `${iterLabel || `第${iteration || '?'}轮`} · ACT`;
+                } else {
+                  last.label = `${iterLabel || `第${iteration || '?'}轮`} · REFLECT`;
+                }
+              }
+            } else if (normalizedPhase === 'TOOL_EXECUTION') {
+              const ok = normalizedTransition === 'PASSED' || normalizedTransition === 'EXECUTED';
+              const toolName = payload.metadata?.tool || payload.metadata?.name || '';
+              steps.push({
+                type: ok ? 'tool_call' : 'error',
+                label: toolName || iterLabel || '工具',
+                desc: ok
+                  ? `已执行 ${toolName || '工具'}，正在把结果回灌给下一轮判断`
+                  : (payload.message || '工具执行异常'),
+                tag: ok ? 'ACT · ✓' : 'ACT · ✗',
+                time: new Date().toLocaleTimeString(),
+              });
+            } else if (normalizedPhase === 'VERIFICATION') {
+              const ok = normalizedTransition === 'PASSED';
+              steps.push({
+                type: 'verify',
+                label: iterLabel || '验证',
+                desc: ok ? '结果验证通过' : (payload.metadata?.error || '验证未通过'),
+                tag: ok ? '✓' : '需重试',
+                time: new Date().toLocaleTimeString(),
+              });
+            } else if (normalizedPhase === 'FINISH') {
+              const ok = normalizedTransition === 'SUCCESS';
+              steps.push({
+                type: ok ? 'result' : 'error',
+                label: '完成',
+                desc: ok ? '任务执行成功' : (payload.metadata?.error || '执行异常'),
+                tag: ok ? '✓' : '',
+                time: new Date().toLocaleTimeString(),
+              });
+            }
+
+            // 更新 thinking steps — 始终实时显示 Agent 执行进度
+            {
+              if (!streamIdRef.current) {
+                const placeholderId = `thinking-${Date.now()}`;
+                streamIdRef.current = placeholderId;
+                setMessages(prev => {
+                  const last = prev[prev.length - 1];
+                  if (last?.id === placeholderId) {
+                    return [...prev.slice(0, -1), { ...last, thinkingSteps: [...steps], streaming: true, timestamp: Date.now() }];
+                  }
+                  return [...prev, { id: placeholderId, type: 'agent', text: '', thinkingSteps: [...steps], streaming: true, timestamp: Date.now() }];
+                });
+              } else {
+                setMessages(prev => {
+                  const last = prev[prev.length - 1];
+                  if (last?.id === streamIdRef.current) {
+                    return [...prev.slice(0, -1), { ...last, thinkingSteps: [...steps], thinking: last.thinking || '' }];
+                  }
+                  return prev;
+                });
+              }
+            }
+            break;
+          }
+          case 'stream_delta': {
+            const delta = msg.text || '';
+            const chunkType = msg.chunk_type || 'text';
+            if (!delta) break;
+            if (chunkType === 'thinking') {
+              streamThinkingRef.current += delta;
+            } else {
+              streamTextRef.current += delta;
+            }
+            if (!streamIdRef.current) streamIdRef.current = `stream-${Date.now()}`;
+            // 节流传 refresh：控制 DOM 更新频率，避免 React 批量导致一大坨
+            if (streamFlushRef.current === null) {
+              const flush = () => {
+                if (!streamIdRef.current) { streamFlushRef.current = null; return; }
+                streamFlushRef.current = null;
+                const sid = streamIdRef.current;
+                const text = streamTextRef.current;
+                const think = currentThinkMode.current ? streamThinkingRef.current : '';
+                const steps = [...thinkingStepsRef.current];
+                setMessages(prev => {
+                  const last = prev[prev.length - 1];
+                  if (last?.id === sid && last.type === 'agent') {
+                    return [...prev.slice(0, -1), { ...last, text, thinking: think, thinkingSteps: steps, streaming: true, timestamp: Date.now() }];
+                  }
+                  return [...prev, { id: sid, type: 'agent', text, thinking: think, thinkingSteps: steps, streaming: true, timestamp: Date.now() }];
+                });
+                // 继续节流
+                streamFlushRef.current = setTimeout(flush, 25);
+              };
+              streamFlushRef.current = setTimeout(flush, 25);
+            }
+            break;
+          }
+          case 'step': {
+            const pending = pendingMsgRef.current || { toolTimeline: [] };
+            const label = msg.phase === 'thinking' ? '正在分析' : msg.phase === 'tool_call' ? '调用工具' : '生成输出';
+            const node: ToolTimelineNode = { phase: msg.phase as ToolTimelineNode['phase'], label, desc: msg.desc || '', tag: msg.tag };
+            pending.toolTimeline = [...(pending.toolTimeline || []), node];
+            pendingMsgRef.current = pending;
+            setCatState(prev => ({ ...prev, status: 'running', iteration: msg.iteration ? String(msg.iteration).padStart(2, '0') : prev.iteration }));
+            break;
+          }
+          case 'output':
+            pendingMsgRef.current = { ...(pendingMsgRef.current || {}), terminalOutput: msg.text || '' };
+            break;
+          case 'done': {
+            const pending = pendingMsgRef.current || {};
+            if (msg.usage) setLastUsage(msg.usage as { input: number; output: number; cost: string });
+            if ((msg as any).model) setLastModel((msg as any).model);
+            if (msg.duration_seconds) setLastDuration(msg.duration_seconds);
+            // 从 done 事件提取上下文可观测数据，动态更新状态栏
+            const ctx = (msg as any).context;
+            if (ctx && typeof ctx === 'object') {
+              const windowTokens = ctx.context_window || 0;
+              const currentTokens = ctx.current_tokens || ctx.estimated_tokens || 0;
+              const compressionHistory: any[] = ctx.compression_history || [];
+              setObservability({
+                context_window: windowTokens,
+                current_tokens: currentTokens,
+                percent: windowTokens ? (currentTokens / windowTokens * 100) : 0,
+                threshold: ctx.threshold || 0,
+                compression_count: compressionHistory.length,
+                compression_enabled: true,
+                last_request: msg.usage as any,
+              });
+            }
+            const steps = thinkingStepsRef.current;
+            const dur = msg.duration_seconds || 0;
+            const rawResult = msg.result || '';
+            const attachmentsUsed = Array.isArray((msg as any).attachments_used) ? (msg as any).attachments_used : [];
+            const attachmentItems = attachmentsUsed.map((item: any) => ({ name: item.name, path: item.path, size: item.size, isImage: Boolean(item.is_image), url: '' }));
+            const errorText = msg.error || msg.result || '任务执行失败';
+            const { thinking: parsedThinking, answer } = parseThinkingFromResult(rawResult);
+            const responseText = msg.success ? answer : errorText;
+            // 合并前一条流式/占位消息的 thinkingSteps，防止丢 steps
+            const showThinking = currentThinkMode.current;
+            const existingStreamText = streamTextRef.current;
+            const existingStreamThinking = streamThinkingRef.current;
+            const fullText = msg.success ? (existingStreamText || responseText) : errorText;
+            const fullThinking = showThinking ? (existingStreamThinking || parsedThinking || '') : '';
+            const displayThinking = showThinking && fullThinking && fullThinking !== fullText ? fullThinking : '';
+            const finalId = `agent-${Date.now()}`;
+            const hasRealStream = Boolean(existingStreamText || existingStreamThinking);
+
+            setMessages(prev => {
+              const last = prev[prev.length - 1];
+              const isPlaceholder = last && (last.id.startsWith('thinking-') || last.id.startsWith('stream-')) && last.type === 'agent';
+              const base = isPlaceholder ? prev.slice(0, -1) : prev;
+              const mergedSteps = showThinking ? (steps.length > 0 ? steps : (last?.thinkingSteps || [])) : [];
+              if (hasRealStream) {
+                return [...base, {
+                  id: isPlaceholder ? last.id : finalId, type: 'agent',
+                  text: fullText, thinking: displayThinking,
+                  timestamp: Date.now(),
+                  toolTimeline: pending.toolTimeline || [], terminalOutput: pending.terminalOutput || responseText, cmd: pending.cmd,
+                  duration: dur, success: Boolean(msg.success),
+                  thinkingSteps: mergedSteps,
+                  attachments_used: attachmentItems,
+                  streaming: false,
+                }];
+              }
+              return [...base, {
+                id: finalId, type: 'agent',
+                text: msg.success ? '' : errorText, thinking: '',
+                timestamp: Date.now(),
+                toolTimeline: pending.toolTimeline || [], terminalOutput: pending.terminalOutput || responseText, cmd: pending.cmd,
+                duration: dur, success: Boolean(msg.success),
+                thinkingSteps: mergedSteps,
+                attachments_used: attachmentItems,
+                streaming: msg.success,
+              }];
+            });
+
+            // seeyon 网关可能一次性返回完整内容：仅在没有真实 stream_delta 时模拟打字机。
+            // 但错误消息不动画——立即显示。
+            if (!hasRealStream && msg.success) {
+              let renderedLen = 0;
+              let renderedThinkLen = 0;
+              const CHUNK_SIZE = 3;
+              const FRAME_MS = 16;
+              const typewriterId = finalId;
+              typewriterRef.current = setInterval(() => {
+                renderedLen = Math.min(renderedLen + CHUNK_SIZE, fullText.length);
+                renderedThinkLen = Math.min(renderedThinkLen + CHUNK_SIZE, fullThinking.length);
+                const finished = renderedLen >= fullText.length && renderedThinkLen >= fullThinking.length;
+                setMessages(prev => {
+                  const last = prev[prev.length - 1];
+                  if (last?.id !== typewriterId) return prev;
+                  return [...prev.slice(0, -1), { ...last, text: fullText.slice(0, renderedLen), thinking: fullThinking.slice(0, renderedThinkLen), streaming: !finished }];
+                });
+                if (finished && typewriterRef.current) {
+                  clearInterval(typewriterRef.current);
+                  typewriterRef.current = null;
+                  setCatState({ status: msg.success ? 'success' : 'error', latency: msg.duration_seconds !== undefined ? `${msg.duration_seconds.toFixed(2)} 秒` : undefined });
+                }
+              }, FRAME_MS);
+            } else {
+              setCatState({ status: msg.success ? 'success' : 'error', latency: msg.duration_seconds !== undefined ? `${msg.duration_seconds.toFixed(2)} 秒` : undefined });
+            }
+
+            thinkingStepsRef.current = [];
+            thinkingStartRef.current = 0;
+            if (streamFlushRef.current) { clearTimeout(streamFlushRef.current); streamFlushRef.current = null; }
+            streamIdRef.current = '';
+            streamTextRef.current = '';
+            streamThinkingRef.current = '';
+            break;
+          }
+        }
+      }, () => {
+        if (wsRef.current !== ws) { ws.close(); return; }
+        connectingRef.current = false;
+        closeHandledRef.current = false;
+        setConnected(true);
+      }, () => {
+        if (wsRef.current !== ws) return;
+        // error 与 close 会连续触发；同一条连接只允许进入一次断线处理。
+        // 否则 error 先把 connectingRef 置 false，close 再触发一次，两个重连定时器会相互覆盖。
+        if (closeHandledRef.current) return;
+        closeHandledRef.current = true;
+        // 检查是否有未完成的任务 — 如果 WebSocket 在 pending 状态下断开，说明任务异常终止
+        const hadPending = pendingMsgRef.current !== null;
+        if (hadPending) {
+          const steps = thinkingStepsRef.current;
+          const dur = thinkingStartRef.current ? ((Date.now() - thinkingStartRef.current) / 1000) : 0;
+          setMessages(prev => [...prev, {
+            id: `error-${Date.now()}`, type: 'agent', text: '连接中断，任务已终止', timestamp: Date.now(),
+            success: false, duration: dur,
+            thinkingSteps: [...steps],
+          }]);
+          pendingMsgRef.current = null;
+          thinkingStepsRef.current = [];
+          thinkingStartRef.current = 0;
+        }
+        setCatState({ status: 'idle' });
+        setConnected(false);
+        connectingRef.current = false;
+        scheduleReconnect();
+      });
+      wsRef.current = ws;
+    };
+    connect();
+    return () => {
+      disposed = true;
+      if (reconnectTimerRef.current !== null) { window.clearTimeout(reconnectTimerRef.current); reconnectTimerRef.current = null; }
+      const ws = wsRef.current;
+      // React StrictMode/HMR 会在第一次握手还处于 CONNECTING 时立刻 cleanup，
+      // 如果这里不复位 connectingRef，第二次 effect 会被 `connectingRef.current` 挡住，
+      // 页面就永远没有当前 WebSocket，发送时报“后端连接尚未就绪”。
+      connectingRef.current = false;
+      closeHandledRef.current = false;
+      if (ws) {
+        // 清掉所有回调，旧 socket 后续 open/error/close 都不能污染新连接状态。
+        ws.onopen = null;
+        ws.onmessage = null;
+        ws.onerror = null;
+        ws.onclose = null;
+        if (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN) {
+          ws.close();
+        }
+      }
+      if (typewriterRef.current !== null) { clearInterval(typewriterRef.current); typewriterRef.current = null; }
+      if (streamFlushRef.current !== null) { clearTimeout(streamFlushRef.current); streamFlushRef.current = null; }
+      streamTextRef.current = '';
+      streamThinkingRef.current = '';
+      thinkingStepsRef.current = [];
+      thinkingStartRef.current = 0;
+      streamIdRef.current = '';
+      activeRunIdRef.current = '';
+      wsRef.current = null;
+    };
+  // WebSocket 是应用级连接，不应该跟随 sessionId 重建。
+  // sessionId 通过 currentSessionIdRef 读取；否则会话初始化/切换时反复 cleanup，
+  // 在 React dev/HMR 下容易把刚建好的连接又关掉，页面就长期显示“未连接”。
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const runCommand = useCallback((cmd: string, task?: string, agent?: string, opts?: RunOptions) => {
+    if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+      setMessages(prev => [...prev, { id: `error-${Date.now()}`, type: 'agent', text: '后端连接尚未就绪，请稍后重试。', timestamp: Date.now(), success: false }]);
+      return false;
+    }
+    const userText = cmd === 'run-agent' ? (task || '') : `执行命令：${cmd}`;
+    setMessages(prev => [...prev, { id: `user-${Date.now()}`, type: 'user', text: userText, timestamp: Date.now() }]);
+    pendingMsgRef.current = { cmd };
+    currentThinkMode.current = opts?.thinkMode ?? false;
+    setCatState({ status: 'running', worker: agent || '命令执行器' });
+    const sid = opts?.sessionId || sessionId;
+    currentSessionIdRef.current = sid || '';
+    const runId = createRunId();
+    activeRunIdRef.current = runId;
+    const sentRunId = sendRunCommand(wsRef.current, cmd, task, agent, sid, { ...opts, runId });
+    if (sentRunId !== runId) activeRunIdRef.current = sentRunId;
+    return true;
+  }, [sessionId]);
+
+  const clearMessages = useCallback(() => {
+    activeRunIdRef.current = '';
+    if (typewriterRef.current !== null) { clearInterval(typewriterRef.current); typewriterRef.current = null; }
+    if (streamFlushRef.current !== null) { clearTimeout(streamFlushRef.current); streamFlushRef.current = null; }
+    streamIdRef.current = '';
+    streamTextRef.current = '';
+    streamThinkingRef.current = '';
+    thinkingStepsRef.current = [];
+    thinkingStartRef.current = 0;
+    pendingMsgRef.current = null;
+    setMessages([]);
+    setCatState({ status: 'idle' });
+  }, []);
+
+  const loadMessages = useCallback((history: ChatMessage[]) => {
+    activeRunIdRef.current = '';
+    if (typewriterRef.current !== null) { clearInterval(typewriterRef.current); typewriterRef.current = null; }
+    if (streamFlushRef.current !== null) { clearTimeout(streamFlushRef.current); streamFlushRef.current = null; }
+    streamIdRef.current = '';
+    streamTextRef.current = '';
+    streamThinkingRef.current = '';
+    thinkingStepsRef.current = [];
+    thinkingStartRef.current = 0;
+    pendingMsgRef.current = null;
+    setMessages(history);
+    setCatState({ status: 'idle' });
+  }, []);
+
+  return { connected, catState, messages, runCommand, clearMessages, loadMessages, lastUsage, observability, lastModel, lastDuration };
+}

package/interfaces/web/frontend/src/hooks/useDashboardData.ts

@@ -0,0 +1,160 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { api } from '../api/client';
+import type { AgentOption, CommandGroupItem, CronItem, ModelHealth, Session, SoulProfile, Usage, Worker } from '../types';
+
+const EMPTY_SESSION: Session = { name: '暂无会话', status: 'idle', statusLabel: '暂无记录', id: '-', metrics: '0 次迭代 / 0 次工具调用' };
+const EMPTY_SOUL: SoulProfile = { name: '默认角色', tags: ['LBS Agent'], desc: '未加载角色配置' };
+const EMPTY_USAGE: Usage = { input: 0, output: 0, cache: 0, cost: '0' };
+const STATUS_LABELS: Record<string, string> = {
+  running: '运行中', completed: '已完成', success: '已完成', failed: '失败', error: '失败', stalled: '已停滞', idle: '空闲',
+};
+
+export function useDashboardData() {
+  const [commands, setCommands] = useState<CommandGroupItem[]>([]);
+  const [agents, setAgents] = useState<AgentOption[]>([]);
+  const [models, setModels] = useState<ModelHealth[]>([]);
+  const [workers, setWorkers] = useState<Worker[]>([]);
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [cronQueue, setCronQueue] = useState<CronItem[]>([]);
+  const [soul, setSoul] = useState<SoulProfile>(EMPTY_SOUL);
+  const [souls, setSouls] = useState<SoulProfile[]>([]);
+  const [usage, setUsage] = useState<Usage>(EMPTY_USAGE);
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(true);
+
+  const load = useCallback(async () => {
+    try {
+      const [commandData, providerData, agentData, workerData, sessionData, cronData, soulData, soulsData, usageData] = await Promise.all([
+        api.getCommands(), api.getProviders(), api.getAgents(), api.getWorkers(), api.getSessions(), api.getCron(), api.getSoul(), api.getSouls(), api.getUsage(),
+      ]);
+      // Filter out removed pages + merge workers into usage
+      const filtered = commandData.groups.map(group => ({
+        key: group.key,
+        title: group.title,
+        commands: group.commands
+          .filter(c => c.name !== 'session-history' && c.name !== 'workers')
+          .map(command => ({ ...command, requiresTask: command.requires_task })),
+      })).filter(group => group.commands.length > 0);
+      setCommands(filtered);
+
+      interface StatusPayload { default_provider?: string; default_model?: string }
+      let defaultProvider = '';
+      let defaultModel = '';
+      try {
+        const statusData = (await api.getStatus()) as StatusPayload;
+        defaultProvider = statusData.default_provider || '';
+        defaultModel = statusData.default_model || '';
+      } catch {
+        // ignore status fetch failure, keep UI usable
+      }
+
+      const flat: ModelHealth[] = [];
+      for (const p of providerData.providers) {
+        const providerHasKey = p.has_api_key;
+        for (const m of (p.models || [])) {
+          const isDefault = p.name === defaultProvider && m === defaultModel;
+          flat.push({
+            name: m,
+            provider: p.name,
+            health: providerHasKey ? 'excellent' : 'warn',
+            statusLabel: isDefault ? '默认' : providerHasKey ? '可用' : '未配置 Key',
+            isDefault,
+          });
+        }
+      }
+      setModels(flat);
+
+      setAgents(agentData.agents.map(agent => ({
+        name: agent.name,
+        displayName: agent.display_name || agent.name,
+        model: agent.model,
+        provider: agent.provider || '',
+        tools: agent.tools || [],
+        fallbackModels: agent.fallback_models,
+        guardrails: agent.guardrails,
+        verification: agent.verification,
+        verificationRules: agent.verification_rules,
+        verificationLevel: agent.verification_level,
+        errorStrategy: agent.error_strategy,
+        timeout: agent.timeout,
+        maxIterations: agent.max_iterations,
+        maxRetries: agent.max_retries,
+        promptFile: agent.prompt_file,
+      })));
+
+      setWorkers(workerData.workers.map(worker => ({
+        name: worker.agent_name || '未命名',
+        status: worker.status === 'running' ? 'active' : worker.success ? 'idle' : 'error',
+        statusLabel: worker.status_label,
+        detail: `${worker.tool_calls} 次工具调用 · ${Number(worker.duration_seconds || 0).toFixed(1)} 秒`,
+      })));
+
+      setSessions(sessionData.sessions.map(item => ({
+        name: item.title || item.task || item.agent_name || '未命名会话',
+        title: item.title,
+        status: item.status || (item.success ? 'completed' : 'error'),
+        statusLabel: STATUS_LABELS[(item.status || '').toLowerCase()] || (item.success ? '已完成' : '失败'),
+        id: item.session_id,
+        createdAt: item.created_at,
+        updatedAt: item.updated_at,
+        metrics: `${item.iterations || 0} 次迭代 / ${item.total_tool_calls || 0} 次工具调用 / ${Number(item.duration_seconds || 0).toFixed(1)} 秒`,
+      })));
+
+      setCronQueue(cronData.jobs.map(job => ({
+        jobId: job.job_id,
+        schedule: job.schedule,
+        name: job.name,
+        nextRun: job.enabled ? (job.next_run_at || '等待计算') : '已暂停',
+        enabled: job.enabled,
+        task: job.task,
+        agentName: job.agent_name,
+      })));
+
+      setSoul({
+        name: soulData.name,
+        tags: ['当前角色', '本地配置'],
+        desc: soulData.content.split('\n').find(line => line.trim() && !line.startsWith('#') && !line.startsWith('---'))?.slice(0, 100) || '当前角色暂无简介',
+      });
+      setSouls(soulsData.souls.map(item => ({ name: item.name, tags: item.name === soulsData.current ? ['当前角色'] : [], desc: item.desc })));
+      setUsage({
+        input: Number(usageData.total_input_tokens || 0) / 1000,
+        output: Number(usageData.total_output_tokens || 0) / 1000,
+        cache: 0,
+        cost: String(parseFloat(String(usageData.total_cost_usd || '0')) || 0),
+      });
+      setError('');
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+    const timer = window.setInterval(() => void load(), 6000);
+    return () => window.clearInterval(timer);
+  }, [load]);
+
+  return useMemo(() => ({
+    commands,
+    agents,
+    models,
+    workers,
+    sessions,
+    session: sessions[0] || EMPTY_SESSION,
+    cronQueue,
+    souls,
+    soul,
+    usage,
+    error,
+    loading,
+    refresh: load,
+    createSession: async (title: string) => {
+      const created = await api.createSession(title);
+      await load();
+      return created;
+    },
+    uploadFile: async (file: File, sessionId: string) => api.uploadFile(file, sessionId),
+  }), [commands, agents, models, workers, sessions, cronQueue, souls, soul, usage, error, loading, load]);
+}