flare-chat-core 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# flare-chat-core
+
+Chat 核心能力包。
+
+职责：
+
+1. 会话状态与生命周期。
+2. 输入状态与文件/拖拽处理。
+3. SSE 流式通信与事件解析。
+4. 消息时间线组装。
+
+不包含：
+
+1. Chat GUI 宿主层。
+2. 生成式 UI 渲染层。

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "flare-chat-core",
+  "private": false,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./index.js": "./src/index.js",
+    "./chat-core/index.js": "./src/chat-core/index.js",
+    "./chat-core/input/useChatInput.js": "./src/chat-core/input/useChatInput.js",
+    "./chat-core/messages/buildTimelineItems.js": "./src/chat-core/messages/buildTimelineItems.js",
+    "./chat-core/session/useChatSessionReducer.js": "./src/chat-core/session/useChatSessionReducer.js",
+    "./chat-core/stream/sse-client.js": "./src/chat-core/stream/sse-client.js",
+    "./chat-core/stream/sse-events.js": "./src/chat-core/stream/sse-events.js",
+    "./chat-core/stream/useSSEStream.js": "./src/chat-core/stream/useSSEStream.js"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  }
+}

package/src/chat-core/index.js

@@ -0,0 +1,6 @@
+export { default as useChatSessionReducer, initialState as chatSessionInitialState } from './session/useChatSessionReducer.js';
+export { useChatInput } from './input/useChatInput.js';
+export { useSSEStream } from './stream/useSSEStream.js';
+export { SSEClient } from './stream/sse-client.js';
+export * from './stream/sse-events.js';
+export { buildTimelineItems } from './messages/buildTimelineItems.js';

package/src/chat-core/input/useChatInput.js

@@ -0,0 +1,70 @@
+import { useState, useCallback } from 'react';
+
+export function useChatInput() {
+  const [inputValue, setInputValue] = useState('');
+  const [fileList, setFileList] = useState([]);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const handleInputChange = useCallback((e) => {
+    setInputValue(e.target.value);
+  }, []);
+
+  const handleFileChange = useCallback(({ fileList: newFileList }) => {
+    setFileList(newFileList);
+  }, []);
+
+  const handleRemoveFile = useCallback((file) => {
+    setFileList((prev) => prev.filter((f) => f.uid !== file.uid));
+  }, []);
+
+  const handleDrop = useCallback((e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragging(false);
+
+    const files = Array.from(e.dataTransfer.files);
+    const newFiles = files.map((file, index) => ({
+      uid: `${Date.now()}-${index}`,
+      name: file.name,
+      size: file.size,
+      type: file.type,
+      originFileObj: file,
+    }));
+
+    setFileList((prev) => [...prev, ...newFiles]);
+    return files.length;
+  }, []);
+
+  const handleDragOver = useCallback((e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragging(true);
+  }, []);
+
+  const handleDragLeave = useCallback((e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setIsDragging(false);
+  }, []);
+
+  const clearInput = useCallback(() => {
+    setInputValue('');
+    setFileList([]);
+  }, []);
+
+  return {
+    inputValue,
+    fileList,
+    isDragging,
+    handleInputChange,
+    handleFileChange,
+    handleRemoveFile,
+    handleDrop,
+    handleDragOver,
+    handleDragLeave,
+    clearInput,
+  };
+}
+
+export default useChatInput;
+

package/src/chat-core/messages/buildTimelineItems.js

@@ -0,0 +1,74 @@
+export function buildTimelineItems(state = {}) {
+  const messages = Array.isArray(state.messages) ? state.messages : [];
+  const executionCards = Array.isArray(state.executionCards) ? state.executionCards : [];
+  const uiCards = Array.isArray(state.uiCards) ? state.uiCards : [];
+  const streaming = state.streaming || {};
+
+  const items = [];
+
+  if (messages.length === 0) {
+    return {
+      isEmpty: true,
+      items: [],
+    };
+  }
+
+  messages.forEach((msg, index) => {
+    const messageId = msg.message_id || `msg-fallback-${index}`;
+    items.push({
+      id: messageId,
+      type: 'message',
+      role: msg.role,
+      content: msg.content,
+      createdAt: msg.created_at,
+      highlights: msg.highlights ?? [],
+      sourceTypes: msg.sourceTypes ?? [],
+    });
+  });
+
+  executionCards
+    .filter(Boolean)
+    .filter((card) => card.step_id !== streaming.executionTrace?.step_id)
+    .forEach((card, index) => {
+      const executionId = card.step_id || `execution-fallback-${index}`;
+      items.push({
+        id: executionId,
+        type: 'execution',
+        executionTrace: card,
+      });
+    });
+
+  if (uiCards.length > 0) {
+    items.push({
+      id: 'conversation-ui-cards',
+      type: 'ui_cards',
+      cards: uiCards,
+    });
+  }
+
+  if (streaming.content) {
+    items.push({
+      id: 'streaming-message',
+      type: 'streaming',
+      content: streaming.content,
+    });
+  }
+
+  if (streaming.agentStatus || streaming.thinkingTrace || streaming.executionTrace) {
+    items.push({
+      id: 'thinking-bubble',
+      type: 'thinking',
+      agentStatus: streaming.agentStatus,
+      thinkingTrace: streaming.thinkingTrace,
+      executionTrace: streaming.executionTrace,
+    });
+  }
+
+  return {
+    isEmpty: false,
+    items,
+  };
+}
+
+export default buildTimelineItems;
+

package/src/chat-core/session/useChatSessionReducer.js

@@ -0,0 +1,446 @@
+import { useReducer, useCallback, useMemo } from 'react';
+
+const SESSION_LOADED = 'SESSION_LOADED';
+const SESSION_RESET = 'SESSION_RESET';
+const SESSION_ERROR = 'SESSION_ERROR';
+const TITLE_UPDATED = 'TITLE_UPDATED';
+const MESSAGES_REFRESHED = 'MESSAGES_REFRESHED';
+const MESSAGE_APPENDED = 'MESSAGE_APPENDED';
+const STREAMING_RESET = 'STREAMING_RESET';
+const STREAMING_CHUNK = 'STREAMING_CHUNK';
+const AGENT_STATUS_SET = 'AGENT_STATUS_SET';
+const THINKING_TRACE_SET = 'THINKING_TRACE_SET';
+const EXECUTION_TRACE_SET = 'EXECUTION_TRACE_SET';
+const STREAMING_DONE = 'STREAMING_DONE';
+const DOC_GENERATED = 'DOC_GENERATED';
+const LEGEND_HINT_SHOWN = 'LEGEND_HINT_SHOWN';
+const EXECUTION_CARD_UPSERTED = 'EXECUTION_CARD_UPSERTED';
+const UI_CARDS_SET = 'UI_CARDS_SET';
+const LAST_USER_MESSAGE_SET = 'LAST_USER_MESSAGE_SET';
+const UI_CARD_UPDATED = 'UI_CARD_UPDATED';
+const INSTANCE_PROFILE_SET = 'INSTANCE_PROFILE_SET';
+
+const initialStreaming = {
+  content: '',
+  agentStatus: null,
+  thinkingTrace: '',
+  executionTrace: null,
+};
+
+export const initialState = {
+  sessionId: null,
+  sessionTitle: '',
+  sessionStatus: 'active',
+  instanceProfile: null,
+  messages: [],
+  executionCards: [],
+  uiCards: [],
+  lastUserMessage: '',
+  generatedDoc: null,
+  streaming: initialStreaming,
+  sessionError: null,
+  legendHintsShown: {
+    knowledge_base: false,
+    ai: false,
+  },
+};
+
+function reducer(state, { type, payload }) {
+  switch (type) {
+    case SESSION_LOADED: {
+      const { sessionId, title, status, messages } = payload;
+      return {
+        ...state,
+        sessionId,
+        sessionTitle: title,
+        sessionStatus: status || 'active',
+        instanceProfile: state.instanceProfile,
+        messages,
+        executionCards: [],
+        uiCards: [],
+        lastUserMessage: '',
+        generatedDoc: null,
+        streaming: initialStreaming,
+        legendHintsShown: initialState.legendHintsShown,
+      };
+    }
+
+    case SESSION_RESET:
+      return { ...initialState, instanceProfile: state.instanceProfile };
+
+    case SESSION_ERROR:
+      return { ...state, sessionError: payload };
+
+    case TITLE_UPDATED:
+      return { ...state, sessionTitle: payload };
+
+    case MESSAGES_REFRESHED:
+      return { ...state, messages: payload };
+
+    case MESSAGE_APPENDED:
+      return {
+        ...state,
+        messages: [...state.messages, payload],
+        lastUserMessage: payload.role === 'user' ? payload.content : state.lastUserMessage,
+      };
+
+    case LAST_USER_MESSAGE_SET:
+      return { ...state, lastUserMessage: payload };
+
+    case UI_CARDS_SET:
+      return { ...state, uiCards: payload };
+
+    case UI_CARD_UPDATED: {
+      const nextCard = payload;
+      return {
+        ...state,
+        uiCards: state.uiCards.map((card) =>
+          card.id === nextCard.id ? { ...card, ...nextCard } : card
+        ),
+      };
+    }
+
+    case INSTANCE_PROFILE_SET:
+      return { ...state, instanceProfile: payload };
+
+    case EXECUTION_CARD_UPSERTED: {
+      const nextCard = payload;
+      const cardKey = nextCard.step_id || `${nextCard.agent}-${nextCard.label}-${nextCard.stage}`;
+      const existingIndex = state.executionCards.findIndex((card) => {
+        const existingKey = card.step_id || `${card.agent}-${card.label}-${card.stage}`;
+        return existingKey === cardKey;
+      });
+
+      const updatedCards = existingIndex >= 0
+        ? state.executionCards.map((card, index) =>
+            index === existingIndex ? { ...card, ...nextCard } : card
+          )
+        : [...state.executionCards, nextCard];
+
+      return {
+        ...state,
+        executionCards: updatedCards.slice(-6),
+      };
+    }
+
+    case STREAMING_RESET:
+      return { ...state, streaming: initialStreaming };
+
+    case STREAMING_CHUNK:
+      return {
+        ...state,
+        streaming: {
+          ...state.streaming,
+          content: state.streaming.content + payload,
+        },
+      };
+
+    case AGENT_STATUS_SET:
+      return {
+        ...state,
+        streaming: { ...state.streaming, agentStatus: payload },
+      };
+
+    case THINKING_TRACE_SET:
+      return {
+        ...state,
+        streaming: { ...state.streaming, thinkingTrace: payload },
+      };
+
+    case EXECUTION_TRACE_SET:
+      return {
+        ...state,
+        streaming: {
+          ...state.streaming,
+          executionTrace: {
+            ...state.streaming.executionTrace,
+            ...payload,
+          },
+        },
+      };
+
+    case STREAMING_DONE: {
+      const newMessages = payload
+        ? [
+            ...state.messages,
+            {
+              message_id: `temp-assistant-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+              role: 'assistant',
+              content: payload,
+              created_at: new Date().toISOString(),
+            },
+          ]
+        : state.messages;
+
+      return {
+        ...state,
+        messages: newMessages,
+        streaming: initialStreaming,
+      };
+    }
+
+    case DOC_GENERATED:
+      return { ...state, generatedDoc: payload };
+
+    case LEGEND_HINT_SHOWN:
+      return {
+        ...state,
+        legendHintsShown: {
+          ...state.legendHintsShown,
+          [payload]: true,
+        },
+      };
+
+    default:
+      return state;
+  }
+}
+
+function requireAPI(api, name) {
+  if (!api) {
+    throw new Error(`${name} is required`);
+  }
+  return api;
+}
+
+export default function useChatSessionReducer(deps = {}) {
+  const { sessionAPI, messageAPI } = deps;
+  const [state, dispatch] = useReducer(reducer, initialState);
+
+  const loadSession = useCallback(async (sessionId) => {
+    const sessionApi = requireAPI(sessionAPI, 'sessionAPI');
+    const messageApi = requireAPI(messageAPI, 'messageAPI');
+
+    const [detail, msgs] = await Promise.all([
+      sessionApi.get(sessionId),
+      messageApi.list(sessionId),
+    ]);
+
+    dispatch({
+      type: SESSION_LOADED,
+      payload: {
+        sessionId,
+        title: detail.title,
+        status: detail.status || 'active',
+        messages: msgs.messages,
+      },
+    });
+  }, [sessionAPI, messageAPI]);
+
+  const createSession = useCallback(async ({
+    function_type,
+    title,
+    ...extraPayload
+  } = {}) => {
+    const sessionApi = requireAPI(sessionAPI, 'sessionAPI');
+    const response = await sessionApi.create({ function_type, title, ...extraPayload });
+
+    dispatch({
+      type: SESSION_LOADED,
+      payload: {
+        sessionId: response.sessionId,
+        title,
+        status: response.status || 'active',
+        messages: [],
+      },
+    });
+
+    return response.sessionId;
+  }, [sessionAPI]);
+
+  const createOrLoadSession = useCallback(async ({
+    function_type,
+    defaultTitle,
+    forceNew = false,
+    ...extraPayload
+  } = {}) => {
+    const sessionApi = requireAPI(sessionAPI, 'sessionAPI');
+    const messageApi = requireAPI(messageAPI, 'messageAPI');
+
+    let sessionId;
+    let title;
+
+    if (forceNew) {
+      title = defaultTitle;
+      const response = await sessionApi.create({ function_type, title, ...extraPayload });
+      sessionId = response.sessionId;
+    } else {
+      const sessionList = await sessionApi.list({
+        function_type,
+        status: 'active',
+        page: 1,
+        page_size: 1,
+        ...extraPayload,
+      });
+
+      if (sessionList.sessions.length > 0) {
+        sessionId = sessionList.sessions[0].sessionId;
+        title = sessionList.sessions[0].title;
+      } else {
+        title = defaultTitle;
+        const response = await sessionApi.create({ function_type, title, ...extraPayload });
+        sessionId = response.sessionId;
+      }
+    }
+
+    const [msgs, detail] = await Promise.all([
+      messageApi.list(sessionId),
+      sessionApi.get(sessionId),
+    ]);
+
+    dispatch({
+      type: SESSION_LOADED,
+      payload: {
+        sessionId,
+        title,
+        status: detail.status || 'active',
+        messages: msgs.messages,
+      },
+    });
+
+    return sessionId;
+  }, [sessionAPI, messageAPI]);
+
+  const resetSession = useCallback(() => {
+    dispatch({ type: SESSION_RESET });
+  }, []);
+
+  const updateTitle = useCallback(async (sessionId, title) => {
+    const sessionApi = requireAPI(sessionAPI, 'sessionAPI');
+    await sessionApi.update(sessionId, { title });
+    dispatch({ type: TITLE_UPDATED, payload: title });
+  }, [sessionAPI]);
+
+  const refreshMessages = useCallback(async (sessionId) => {
+    const messageApi = requireAPI(messageAPI, 'messageAPI');
+    const response = await messageApi.list(sessionId);
+    const messagesWithIds = response.messages.map((msg, index) => ({
+      ...msg,
+      message_id: msg.message_id || `fallback-${Date.now()}-${index}`,
+    }));
+    dispatch({ type: MESSAGES_REFRESHED, payload: messagesWithIds });
+  }, [messageAPI]);
+
+  const appendUserMessage = useCallback((content) => {
+    dispatch({
+      type: MESSAGE_APPENDED,
+      payload: {
+        message_id: `temp-user-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+        role: 'user',
+        content,
+        created_at: new Date().toISOString(),
+      },
+    });
+  }, []);
+
+  const setUICards = useCallback((cards) => {
+    dispatch({ type: UI_CARDS_SET, payload: Array.isArray(cards) ? cards : [] });
+  }, []);
+
+  const updateUICard = useCallback((card) => {
+    dispatch({ type: UI_CARD_UPDATED, payload: card });
+  }, []);
+
+  const setLastUserMessage = useCallback((content) => {
+    dispatch({ type: LAST_USER_MESSAGE_SET, payload: content || '' });
+  }, []);
+
+  const resetStreaming = useCallback(() => {
+    dispatch({ type: STREAMING_RESET });
+  }, []);
+
+  const appendStreamChunk = useCallback((chunk) => {
+    dispatch({ type: STREAMING_CHUNK, payload: chunk });
+  }, []);
+
+  const setAgentStatus = useCallback((agentStatus) => {
+    dispatch({ type: AGENT_STATUS_SET, payload: agentStatus });
+  }, []);
+
+  const setThinkingTrace = useCallback((trace) => {
+    dispatch({ type: THINKING_TRACE_SET, payload: trace });
+  }, []);
+
+  const setExecutionTrace = useCallback((executionTrace) => {
+    dispatch({ type: EXECUTION_TRACE_SET, payload: executionTrace });
+    dispatch({ type: EXECUTION_CARD_UPSERTED, payload: executionTrace });
+  }, []);
+
+  const completeStreaming = useCallback((finalContent) => {
+    dispatch({ type: STREAMING_DONE, payload: finalContent });
+  }, []);
+
+  const setGeneratedDoc = useCallback((doc) => {
+    dispatch({ type: DOC_GENERATED, payload: doc });
+  }, []);
+
+  const markLegendHintShown = useCallback((sourceType) => {
+    dispatch({ type: LEGEND_HINT_SHOWN, payload: sourceType });
+  }, []);
+
+  const setSessionError = useCallback((error) => {
+    dispatch({ type: SESSION_ERROR, payload: error });
+  }, []);
+
+  const setInstanceProfile = useCallback((profile) => {
+    dispatch({ type: INSTANCE_PROFILE_SET, payload: profile || null });
+  }, []);
+
+  return useMemo(() => ({
+    sessionId: state.sessionId,
+    sessionTitle: state.sessionTitle,
+    instanceProfile: state.instanceProfile,
+    messages: state.messages,
+    executionCards: state.executionCards,
+    uiCards: state.uiCards,
+    lastUserMessage: state.lastUserMessage,
+    generatedDoc: state.generatedDoc,
+    streaming: state.streaming,
+    sessionError: state.sessionError,
+    legendHintsShown: state.legendHintsShown,
+    loadSession,
+    createSession,
+    createOrLoadSession,
+    resetSession,
+    updateTitle,
+    refreshMessages,
+    setSessionError,
+    appendUserMessage,
+    setUICards,
+    updateUICard,
+    setLastUserMessage,
+    resetStreaming,
+    appendStreamChunk,
+    setAgentStatus,
+    setThinkingTrace,
+    setExecutionTrace,
+    completeStreaming,
+    setGeneratedDoc,
+    setInstanceProfile,
+    markLegendHintShown,
+  }), [
+    state,
+    loadSession,
+    createSession,
+    createOrLoadSession,
+    resetSession,
+    updateTitle,
+    refreshMessages,
+    setSessionError,
+    appendUserMessage,
+    setUICards,
+    updateUICard,
+    setLastUserMessage,
+    resetStreaming,
+    appendStreamChunk,
+    setAgentStatus,
+    setThinkingTrace,
+    setExecutionTrace,
+    completeStreaming,
+    setGeneratedDoc,
+    setInstanceProfile,
+    markLegendHintShown,
+  ]);
+}
+
+export { useChatSessionReducer };

package/src/chat-core/stream/sse-client.js

@@ -0,0 +1,123 @@
+const API_BASE_URL = import.meta.env.DEV ? '' : import.meta.env.VITE_API_URL || '';
+const DEFAULT_ENDPOINT = '/api/v1/chat/stream';
+
+function joinUrl(baseUrl, endpoint) {
+  if (!baseUrl) {
+    return endpoint;
+  }
+
+  if (!endpoint) {
+    return baseUrl;
+  }
+
+  return `${baseUrl.replace(/\/+$/, '')}/${endpoint.replace(/^\/+/, '')}`;
+}
+
+export class SSEClient {
+  constructor({ endpoint = DEFAULT_ENDPOINT, baseUrl = API_BASE_URL } = {}) {
+    this.abortController = null;
+    this.endpoint = endpoint;
+    this.baseUrl = baseUrl;
+  }
+
+  async sendMessage(sessionOrParams, contentArg, onEventArg, onCompleteArg, onErrorArg, optionsArg = {}) {
+    const isObjectCall = typeof sessionOrParams === 'object' && sessionOrParams !== null;
+    const params = isObjectCall
+      ? sessionOrParams
+      : {
+          sessionId: sessionOrParams,
+          content: contentArg,
+          enabledCapabilities: optionsArg.enabledCapabilities || [],
+        };
+
+    const sessionId = params.sessionId;
+    const content = params.content;
+    const enabledCapabilities = Array.isArray(params.enabledCapabilities) ? params.enabledCapabilities : [];
+    const onEvent = isObjectCall ? contentArg : onEventArg;
+    const onComplete = isObjectCall ? onEventArg : onCompleteArg;
+    const onError = isObjectCall ? onCompleteArg : onErrorArg;
+    const url = params.url || joinUrl(params.baseUrl ?? this.baseUrl, params.endpoint || this.endpoint);
+
+    this.abortController = new AbortController();
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          message: content,
+          session_id: sessionId,
+          enabled_capabilities: enabledCapabilities,
+        }),
+        signal: this.abortController.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      let currentEvent = '';
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          if (line.startsWith('event:')) {
+            currentEvent = line.substring(6).trim();
+            continue;
+          }
+
+          if (!line.startsWith('data:')) {
+            continue;
+          }
+
+          const data = line.substring(5).trim();
+          if (!data || !currentEvent) {
+            continue;
+          }
+
+          try {
+            const eventData = JSON.parse(data);
+            onEvent?.({
+              type: currentEvent,
+              data: eventData,
+            });
+
+            if (currentEvent === 'complete') {
+              onComplete?.();
+              return;
+            }
+          } catch (error) {
+            console.error('SSE 数据解析失败:', error, 'data:', data);
+          }
+        }
+      }
+
+      onComplete?.();
+    } catch (error) {
+      if (error?.name === 'AbortError') {
+        return;
+      }
+
+      onError?.(error instanceof Error ? error.message : '发送消息失败');
+    }
+  }
+
+  abort() {
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+  }
+}
+

package/src/chat-core/stream/sse-events.js

@@ -0,0 +1,425 @@
+/**
+ * SSE 事件规范化层
+ */
+
+/**
+ * @typedef {'thinking'|'searching'|'generating'|'completed'|string} AgentStatusType
+ *
+ * @typedef {Object} AgentStatusPayload
+ * @property {string} agent
+ * @property {AgentStatusType} status
+ * @property {number|null} timestamp
+ *
+ * @typedef {Object} ThinkingTracePayload
+ * @property {string} trace
+ *
+ * @typedef {Object} ExecutionSourcePayload
+ * @property {string} source_type
+ * @property {string} source_label
+ * @property {string} title
+ *
+ * @typedef {Object} ExecutionTracePayload
+ * @property {string} session_id
+ * @property {string} step_id
+ * @property {string} agent
+ * @property {string} stage
+ * @property {string} label
+ * @property {string} detail
+ * @property {string} reason
+ * @property {string} status
+ * @property {Array<ExecutionSourcePayload>} sources
+ * @property {number|null} timestamp
+ *
+ * @typedef {Object} ContentPayload
+ * @property {string} chunk
+ *
+ * @typedef {Object} TracePayload
+ * @property {string} trace
+ * @property {string} summary
+ * @property {string} agent
+ *
+ * @typedef {Object} FieldSource
+ * @property {number|null} confidence
+ *
+ * @typedef {Object} FieldProgressPayload
+ * @property {Record<string, string>} fields
+ * @property {Record<string, FieldSource>} sources
+ * @property {number|null} progress
+ * @property {Array<string>} collected
+ * @property {Array<string>} missing
+ * @property {Object|null} last_field
+ * @property {string|null} refresh_reason
+ *
+ * @typedef {Object} DocPayload
+ * @property {Object|null} doc
+ *
+ * @typedef {Object} CapabilitySuggestionPayload
+ * @property {string} type
+ * @property {string} reason
+ * @property {string} benefit
+ * @property {number} confidence
+ * @property {number} estimated_cost
+ *
+ * @typedef {Object} ModeArtifactPayload
+ * @property {string} mode_key
+ * @property {string|null} project_id
+ * @property {string} message_excerpt
+ * @property {string} render_hint
+ *
+ * @typedef {Object} FieldDefinition
+ * @property {string} id
+ * @property {string} label
+ * @property {string} priority
+ *
+ * @typedef {Object} FieldsUpdatedPayload
+ * @property {number} total_fields
+ * @property {number} base_fields
+ * @property {number} category_fields
+ * @property {Array<FieldDefinition>} new_fields
+ * @property {string|null} refresh_reason
+ *
+ * @typedef {Object} WorkspaceActivationPayload
+ * @property {string} function_type
+ * @property {string} mode
+ * @property {string} title
+ * @property {boolean} trace_in_chat
+ * @property {string} right_panel
+ * @property {boolean} knowledge_base_available
+ *
+ * @typedef {Object} UICardActionPayload
+ * @property {string} type
+ * @property {Record<string, unknown>} payload
+ *
+ * @typedef {Object} UICardPayload
+ * @property {string} id
+ * @property {string} kind
+ * @property {string} title
+ * @property {string} description
+ * @property {boolean} available
+ * @property {string} status
+ * @property {string} reason
+ * @property {UICardActionPayload|null} action
+ *
+ * @typedef {Object} UICardsPayload
+ * @property {string} scope
+ * @property {Array<UICardPayload>} cards
+ *
+ * @typedef {Object} KnowledgeBaseStatePayload
+ * @property {boolean} enabled
+ * @property {string} status
+ * @property {string} label
+ * @property {string} message
+ *
+ * @typedef {Object} CategoryIdentifiedPayload
+ * @property {string} category
+ * @property {number|null} confidence
+ *
+ * @typedef {Object} SSEErrorPayload
+ * @property {string} message
+ */
+
+export const parseAgentStatus = (raw) => ({
+  agent: raw?.agent ?? '',
+  status: raw?.status ?? '',
+  timestamp: raw?.timestamp ?? null,
+});
+
+export const parseThinkingTrace = (raw) => ({
+  trace: raw?.trace ?? '',
+});
+
+export const parseExecutionTrace = (raw) => ({
+  session_id: raw?.session_id ?? '',
+  step_id: raw?.step_id ?? '',
+  agent: raw?.agent ?? '',
+  stage: raw?.stage ?? '',
+  label: raw?.label ?? '',
+  detail: raw?.detail ?? raw?.trace ?? '',
+  reason: raw?.reason ?? '',
+  status: raw?.status ?? raw?.step_status ?? '',
+  sources: Array.isArray(raw?.sources) ? raw.sources : [],
+  timestamp: raw?.timestamp ?? null,
+});
+
+export const parseContent = (raw) => ({
+  chunk: raw?.content ?? '',
+});
+
+export const parseTrace = (raw) => ({
+  trace: raw?.trace ?? raw?.detail ?? '',
+  summary: raw?.summary ?? raw?.label ?? '',
+  agent: raw?.agent ?? '',
+});
+
+function resolveModeEventPayload(raw) {
+  if (raw?.payload && typeof raw.payload === 'object' && !Array.isArray(raw.payload)) {
+    return raw.payload;
+  }
+
+  return raw && typeof raw === 'object' ? raw : {};
+}
+
+function pickFirstArray(payload, keys) {
+  for (const key of keys) {
+    const value = payload?.[key];
+    if (Array.isArray(value)) {
+      return value;
+    }
+  }
+  return [];
+}
+
+export const parseFieldProgress = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  return {
+    fields: payload?.fields ?? {},
+    sources: payload?.sources ?? {},
+    field_entries: Array.isArray(payload?.field_entries) ? payload.field_entries : [],
+    field_groups: payload?.field_groups && typeof payload.field_groups === 'object' && !Array.isArray(payload.field_groups)
+      ? payload.field_groups
+      : {},
+    extra_fields: Array.isArray(payload?.extra_fields) ? payload.extra_fields : [],
+    progress: payload?.progress ?? null,
+    required_progress: payload?.required_progress ?? null,
+    recommended_progress: payload?.recommended_progress ?? null,
+    optional_progress: payload?.optional_progress ?? null,
+    collected: Array.isArray(payload?.collected) ? payload.collected : [],
+    missing: Array.isArray(payload?.missing) ? payload.missing : [],
+    required_collected: Array.isArray(payload?.required_collected) ? payload.required_collected : [],
+    required_missing: Array.isArray(payload?.required_missing) ? payload.required_missing : [],
+    recommended_collected: Array.isArray(payload?.recommended_collected) ? payload.recommended_collected : [],
+    recommended_missing: Array.isArray(payload?.recommended_missing) ? payload.recommended_missing : [],
+    optional_collected: Array.isArray(payload?.optional_collected) ? payload.optional_collected : [],
+    optional_missing: Array.isArray(payload?.optional_missing) ? payload.optional_missing : [],
+    last_field: payload?.last_field ?? null,
+    refresh_reason: payload?.refresh_reason ?? null,
+    field_definitions: Array.isArray(payload?.field_definitions) ? payload.field_definitions : [],
+    required_fields: Array.isArray(payload?.required_fields) ? payload.required_fields : [],
+    recommended_fields: Array.isArray(payload?.recommended_fields) ? payload.recommended_fields : [],
+    optional_fields: Array.isArray(payload?.optional_fields) ? payload.optional_fields : [],
+    field_priorities: payload?.field_priorities && typeof payload.field_priorities === 'object' && !Array.isArray(payload.field_priorities)
+      ? payload.field_priorities
+      : {},
+  };
+};
+
+export const parseDoc = (raw) => ({
+  doc: raw?.doc ?? null,
+});
+
+export const parseCapabilitySuggestion = (raw) => ({
+  type: raw?.type ?? '',
+  reason: raw?.reason ?? '',
+  benefit: raw?.benefit ?? '',
+  confidence: raw?.confidence ?? 0,
+  estimated_cost: raw?.estimated_cost ?? 0,
+});
+
+export const parseRequirementDraft = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  const draft = payload?.draft && typeof payload.draft === 'object' && !Array.isArray(payload.draft)
+    ? payload.draft
+    : {};
+
+  return {
+    mode_key: payload?.mode_key ?? '',
+    project_id: payload?.project_id ?? null,
+    message_excerpt: payload?.message_excerpt ?? '',
+    draft: {
+      ...draft,
+      fields: Array.isArray(draft.fields) ? draft.fields : [],
+    },
+    render_hint: payload?.render_hint ?? 'requirement_draft',
+  };
+};
+
+export const parseNextActions = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  const actions = Array.isArray(payload?.actions)
+    ? payload.actions
+    : (Array.isArray(payload?.next_actions) ? payload.next_actions : []);
+  return {
+    mode_key: payload?.mode_key ?? '',
+    project_id: payload?.project_id ?? null,
+    message_excerpt: payload?.message_excerpt ?? '',
+    actions,
+    completion_state: payload?.completion_state ?? '',
+    required_missing: Array.isArray(payload?.required_missing) ? payload.required_missing : [],
+    recommended_missing: Array.isArray(payload?.recommended_missing) ? payload.recommended_missing : [],
+    optional_missing: Array.isArray(payload?.optional_missing) ? payload.optional_missing : [],
+    ready_for_sourcing: payload?.ready_for_sourcing ?? null,
+    status: payload?.status ?? '',
+    reason: payload?.reason ?? '',
+    render_hint: payload?.render_hint ?? 'next_actions',
+  };
+};
+
+export const parseSourcingCandidates = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  const missing = pickFirstArray(payload, ['missing', 'base_missing', 'missing_fields', 'required_missing']);
+  return {
+    mode_key: payload?.mode_key ?? '',
+    project_id: payload?.project_id ?? null,
+    message_excerpt: payload?.message_excerpt ?? '',
+    missing,
+    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
+    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
+    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
+    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
+    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
+    base_ready_for_matching: payload?.base_ready_for_matching === true,
+    mode_state: payload?.mode_state ?? '',
+    candidate_count: Number.isFinite(payload?.candidate_count) ? payload.candidate_count : null,
+    is_placeholder: payload?.is_placeholder ?? null,
+    required_missing: Array.isArray(payload?.required_missing) ? payload.required_missing : [],
+    recommended_missing: Array.isArray(payload?.recommended_missing) ? payload.recommended_missing : [],
+    optional_missing: Array.isArray(payload?.optional_missing) ? payload.optional_missing : [],
+    actions: Array.isArray(payload?.actions) ? payload.actions : [],
+    candidates: pickFirstArray(payload, ['candidates', 'sourcing_candidates', 'candidate_list', 'results']),
+    reasoning: Array.isArray(payload?.reasoning) ? payload.reasoning : [],
+    summary: payload?.sourcing_summary ?? payload?.summary ?? null,
+    render_hint: payload?.render_hint ?? 'sourcing_candidates',
+  };
+};
+
+export const parseRiskSummary = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  const risks = pickFirstArray(payload, ['risks', 'risk_items', 'items', 'risk_list']);
+  const sources = pickFirstArray(payload, ['sources', 'references', 'evidence']);
+  return {
+    mode_key: payload?.mode_key ?? '',
+    project_id: payload?.project_id ?? null,
+    message_excerpt: payload?.message_excerpt ?? '',
+    mode_state: payload?.mode_state ?? '',
+    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
+    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
+    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
+    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
+    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
+    base_ready_for_matching: payload?.base_ready_for_matching === true,
+    is_placeholder: payload?.is_placeholder ?? null,
+    actions: Array.isArray(payload?.actions) ? payload.actions : [],
+    risks,
+    sources,
+    summary: payload?.risk_summary ?? payload?.summary ?? null,
+    render_hint: payload?.render_hint ?? 'risk_summary',
+  };
+};
+
+export const parseShortlistUpdated = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  const shortlist = pickFirstArray(payload, ['shortlist', 'shortlist_updated', 'selected_candidates', 'items']);
+  return {
+    mode_key: payload?.mode_key ?? '',
+    project_id: payload?.project_id ?? null,
+    message_excerpt: payload?.message_excerpt ?? '',
+    mode_state: payload?.mode_state ?? '',
+    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
+    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
+    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
+    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
+    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
+    base_ready_for_matching: payload?.base_ready_for_matching === true,
+    shortlist,
+    status: payload?.status ?? payload?.state ?? '',
+    reason: payload?.reason ?? payload?.message ?? '',
+    selected_count: Number.isFinite(payload?.selected_count) ? payload.selected_count : null,
+    is_placeholder: payload?.is_placeholder ?? null,
+    actions: Array.isArray(payload?.actions) ? payload.actions : [],
+    render_hint: payload?.render_hint ?? 'shortlist_updated',
+  };
+};
+
+export const parseEvaluationReportReady = (raw) => {
+  const payload = resolveModeEventPayload(raw);
+  const nestedReport = payload?.evaluation_report_ready
+    && typeof payload.evaluation_report_ready === 'object'
+    && !Array.isArray(payload.evaluation_report_ready)
+      ? payload.evaluation_report_ready
+      : {};
+  const reportSource = payload?.report
+    || nestedReport.report
+    || nestedReport;
+  const report = reportSource && typeof reportSource === 'object' && !Array.isArray(reportSource)
+    ? reportSource
+    : {};
+  const compareTable = pickFirstArray(payload, ['compare_table', 'comparison_table', 'compare_rows'])
+    || pickFirstArray(report, ['compare_table', 'comparison_table', 'compare_rows'])
+    || pickFirstArray(nestedReport, ['compare_table', 'comparison_table', 'compare_rows']);
+
+  return {
+    mode_key: payload?.mode_key ?? '',
+    project_id: payload?.project_id ?? null,
+    message_excerpt: payload?.message_excerpt ?? '',
+    mode_state: payload?.mode_state ?? '',
+    base_fields: Array.isArray(payload?.base_fields) ? payload.base_fields : [],
+    base_collected: Array.isArray(payload?.base_collected) ? payload.base_collected : [],
+    base_missing: Array.isArray(payload?.base_missing) ? payload.base_missing : [],
+    base_total: Number.isFinite(payload?.base_total) ? payload.base_total : 0,
+    base_progress: Number.isFinite(payload?.base_progress) ? payload.base_progress : null,
+    base_ready_for_matching: payload?.base_ready_for_matching === true,
+    is_placeholder: payload?.is_placeholder ?? null,
+    actions: Array.isArray(payload?.actions) ? payload.actions : [],
+    report: {
+      ...report,
+      sections: Array.isArray(report.sections) ? report.sections : [],
+    },
+    compare_table: payload?.compare_table
+      ?? payload?.comparison_table
+      ?? payload?.compare_rows
+      ?? report?.compare_table
+      ?? report?.comparison_table
+      ?? report?.compare_rows
+      ?? nestedReport?.compare_table
+      ?? nestedReport?.comparison_table
+      ?? nestedReport?.compare_rows
+      ?? compareTable,
+    render_hint: payload?.render_hint ?? 'evaluation_report_ready',
+  };
+};
+
+export const parseWorkspaceActivation = (raw) => ({
+  function_type: raw?.function_type ?? '',
+  mode: raw?.mode ?? '',
+  title: raw?.title ?? '',
+  trace_in_chat: raw?.trace_in_chat === true,
+  right_panel: raw?.right_panel ?? '',
+  knowledge_base_available: raw?.knowledge_base_available === true,
+});
+
+export const parseUICards = (raw) => ({
+  scope: raw?.scope ?? 'conversation',
+  cards: Array.isArray(raw?.cards) ? raw.cards : [],
+});
+
+export const parseKnowledgeBaseState = (raw) => ({
+  enabled: raw?.enabled === true,
+  status: raw?.status ?? '',
+  label: raw?.label ?? '',
+  message: raw?.message ?? '',
+});
+
+export const parseCategoryIdentified = (raw) => ({
+  category: raw?.category ?? raw?.level3 ?? '',
+  confidence: raw?.confidence ?? null,
+});
+
+export const parseFieldsUpdated = (raw) => ({
+  total_fields: raw?.total_fields ?? 0,
+  base_fields: raw?.base_fields ?? 0,
+  category_fields: raw?.category_fields ?? 0,
+  new_fields: Array.isArray(raw?.new_fields) ? raw.new_fields : [],
+  refresh_reason: raw?.refresh_reason ?? null,
+});
+
+export const parseInstanceProfile = (raw) => ({
+  product_name: raw?.instance_profile?.product_name ?? raw?.product_name ?? '',
+  brand_tag: raw?.instance_profile?.brand_tag ?? raw?.brand_tag ?? '',
+  logo_text: raw?.instance_profile?.logo_text ?? raw?.logo_text ?? '',
+  logo_url: raw?.instance_profile?.logo_url ?? raw?.logo_url ?? '',
+  ui_labels: raw?.instance_profile?.ui_labels ?? raw?.ui_labels ?? {},
+});
+
+export const parseSSEError = (raw) => ({
+  message: raw?.message ?? '发生错误',
+});

package/src/chat-core/stream/useSSEStream.js

@@ -0,0 +1,209 @@
+import { useRef, useState, useCallback } from 'react';
+import { SSEClient } from './sse-client.js';
+import {
+  parseAgentStatus,
+  parseThinkingTrace,
+  parseExecutionTrace,
+  parseContent,
+  parseTrace,
+  parseFieldProgress,
+  parseDoc,
+  parseRequirementDraft,
+  parseNextActions,
+  parseSourcingCandidates,
+  parseRiskSummary,
+  parseShortlistUpdated,
+  parseEvaluationReportReady,
+  parseWorkspaceActivation,
+  parseUICards,
+  parseKnowledgeBaseState,
+  parseCategoryIdentified,
+  parseCapabilitySuggestion,
+  parseFieldsUpdated,
+  parseInstanceProfile,
+  parseSSEError,
+} from './sse-events.js';
+
+function classifyError(errorMessage) {
+  if (!errorMessage) return 'unknown';
+
+  const lowerMsg = errorMessage.toLowerCase();
+  if (lowerMsg.includes('network') || lowerMsg.includes('fetch')) return 'network';
+  if (lowerMsg.includes('timeout') || lowerMsg.includes('timed out')) return 'timeout';
+  if (/\b(500|502|503|504)\b/.test(lowerMsg)) return 'api';
+  return 'unknown';
+}
+
+export function useSSEStream(sessionId) {
+  const clientRef = useRef(new SSEClient());
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const accumulatedRef = useRef('');
+  const lastMessageRef = useRef({ content: '', handlers: {} });
+
+  const send = useCallback(async (content, handlers = {}, options = {}) => {
+    const resolvedSessionId = options.sessionIdOverride || sessionId;
+    if (!resolvedSessionId || !content.trim()) return;
+
+    lastMessageRef.current = { content, handlers, options };
+    setError(null);
+    accumulatedRef.current = '';
+    setLoading(true);
+
+    const {
+      onAgentStatus,
+      onThinkingTrace,
+      onExecutionTrace,
+      onContent,
+      onTrace,
+      onWorkspaceActivation,
+      onUICards,
+      onKnowledgeBaseState,
+      onFieldProgress,
+      onRequirementDraft,
+      onNextActions,
+      onSourcingCandidates,
+      onRiskSummary,
+      onShortlistUpdated,
+      onEvaluationReportReady,
+      onCategoryIdentified,
+      onFieldsUpdated,
+      onInstanceProfile,
+      onDoc,
+      onCapabilitySuggestion,
+      onError,
+      onComplete,
+    } = handlers;
+
+    const eventHandler = (event) => {
+      switch (event.type) {
+        case 'agent_status':
+          onAgentStatus?.(parseAgentStatus(event.data));
+          break;
+        case 'thinking_trace':
+          onThinkingTrace?.(parseThinkingTrace(event.data));
+          break;
+        case 'execution_trace':
+        case 'step_started':
+        case 'step_updated':
+        case 'step_completed':
+        case 'step_failed':
+          onExecutionTrace?.(parseExecutionTrace(event.data));
+          break;
+        case 'content': {
+          const { chunk } = parseContent(event.data);
+          accumulatedRef.current += chunk;
+          onContent?.(chunk);
+          break;
+        }
+        case 'trace':
+          onTrace?.(parseTrace(event.data));
+          break;
+        case 'workspace_activation':
+          onWorkspaceActivation?.(parseWorkspaceActivation(event.data));
+          break;
+        case 'ui_cards':
+          onUICards?.(parseUICards(event.data));
+          break;
+        case 'knowledge_base_state':
+          onKnowledgeBaseState?.(parseKnowledgeBaseState(event.data));
+          break;
+        case 'field_progress':
+          onFieldProgress?.(parseFieldProgress(event.data));
+          break;
+        case 'requirement_draft':
+          onRequirementDraft?.(parseRequirementDraft(event.data));
+          break;
+        case 'next_actions':
+          onNextActions?.(parseNextActions(event.data));
+          break;
+        case 'sourcing_candidates':
+          onSourcingCandidates?.(parseSourcingCandidates(event.data));
+          break;
+        case 'risk_summary':
+          onRiskSummary?.(parseRiskSummary(event.data));
+          break;
+        case 'shortlist_updated':
+          onShortlistUpdated?.(parseShortlistUpdated(event.data));
+          break;
+        case 'evaluation_report_ready':
+          onEvaluationReportReady?.(parseEvaluationReportReady(event.data));
+          break;
+        case 'category_identified':
+          onCategoryIdentified?.(parseCategoryIdentified(event.data));
+          break;
+        case 'fields_updated':
+          onFieldsUpdated?.(parseFieldsUpdated(event.data));
+          break;
+        case 'instance_profile':
+          onInstanceProfile?.(parseInstanceProfile(event.data));
+          break;
+        case 'doc':
+          onDoc?.(parseDoc(event.data));
+          break;
+        case 'capability_suggestion':
+          onCapabilitySuggestion?.(parseCapabilitySuggestion(event.data));
+          break;
+        case 'error':
+          onError?.(parseSSEError(event.data));
+          break;
+        default:
+          console.warn('[SSE] unknown event type:', event.type);
+      }
+    };
+
+    const completeHandler = () => {
+      setLoading(false);
+      onComplete?.(accumulatedRef.current);
+      accumulatedRef.current = '';
+    };
+
+    const transportErrorHandler = (errorMessage) => {
+      setLoading(false);
+      const errorType = classifyError(errorMessage);
+      setError({ message: errorMessage, type: errorType });
+      onError?.({ message: errorMessage });
+      accumulatedRef.current = '';
+    };
+
+    const requestOptions = {
+      sessionId: resolvedSessionId,
+      content,
+      enabledCapabilities: Array.isArray(options.enabledCapabilities) ? options.enabledCapabilities : [],
+      endpoint: options.endpoint,
+      baseUrl: options.baseUrl,
+      url: options.url,
+    };
+
+    if (!requestOptions.enabledCapabilities.length) {
+      delete requestOptions.enabledCapabilities;
+    }
+
+    if (!requestOptions.endpoint) delete requestOptions.endpoint;
+    if (!requestOptions.baseUrl) delete requestOptions.baseUrl;
+    if (!requestOptions.url) delete requestOptions.url;
+
+    await clientRef.current.sendMessage(
+      requestOptions,
+      eventHandler,
+      completeHandler,
+      transportErrorHandler
+    );
+  }, [sessionId]);
+
+  const retry = useCallback(async () => {
+    const { content, handlers, options } = lastMessageRef.current;
+    if (!content) return;
+    await send(content, handlers, options);
+  }, [send]);
+
+  const abort = useCallback(() => {
+    clientRef.current.abort();
+    setLoading(false);
+    accumulatedRef.current = '';
+  }, []);
+
+  return { send, loading, error, retry, abort };
+}
+
+export default useSSEStream;

package/src/index.js

@@ -0,0 +1 @@
+export * from './chat-core/index.js';