flare-chat-core 0.2.1 → 0.2.3

package/src/chat-core/app/useCoreChatApp.js

@@ -0,0 +1,115 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { useBasicConversationFacade } from '../facade/useBasicConversationFacade.js';
+
+/**
+ * Core app-level chat orchestration hook.
+ * Owns state/actions mapping for UI component libraries.
+ */
+export default function useCoreChatApp({
+  sessionAPI,
+  messageAPI,
+  stream,
+  functionType,
+  defaultSessionTitle,
+  listParams,
+  createSessionPayload = {},
+} = {}) {
+  const didInitialRefreshRef = useRef(false);
+  const chat = useBasicConversationFacade({
+    sessionAPI,
+    messageAPI,
+    stream,
+    functionType,
+    defaultSessionTitle,
+    listParams,
+    defaultSessionPayload: createSessionPayload,
+  });
+
+  useEffect(() => {
+    if (didInitialRefreshRef.current) {
+      return;
+    }
+    didInitialRefreshRef.current = true;
+    chat.actions.refreshSessionList();
+  }, [chat.actions.refreshSessionList]);
+
+  const viewModel = useMemo(() => ({
+    sessionList: {
+      sessions: chat.state.sessions.items,
+      error: chat.state.sessions.error,
+      activeSessionId: chat.state.session.sessionId,
+      onSelectSession: chat.actions.selectSession,
+      onCreateSession: () => chat.actions.createSession(createSessionPayload),
+      onCreateProject: () => chat.actions.createSession(createSessionPayload),
+      onRenameSession: async (session, nextTitle) => {
+        const sessionId = String(session?.sessionId || session?.session_id || session?.id || '').trim();
+        const title = String(nextTitle || '').trim();
+        if (!sessionId || !title) {
+          return;
+        }
+        await chat.actions.updateTitle(sessionId, title);
+        await chat.actions.refreshSessionList();
+      },
+      onArchiveSession: async (session) => {
+        const sessionId = String(session?.sessionId || session?.session_id || session?.id || '').trim();
+        if (!sessionId || !sessionAPI?.update) {
+          return;
+        }
+        await sessionAPI.update(sessionId, { status: 'archived' });
+        const latestSessions = await chat.actions.refreshSessionList();
+        if (sessionId !== chat.state.session.sessionId) {
+          return;
+        }
+        const nextActive = Array.isArray(latestSessions)
+          ? latestSessions.find((item) => {
+            const id = String(item?.sessionId || item?.session_id || item?.id || '').trim();
+            const status = String(item?.status || 'active').trim();
+            return Boolean(id) && status !== 'archived';
+          })
+          : null;
+        const nextSessionId = String(
+          nextActive?.sessionId
+          || nextActive?.session_id
+          || nextActive?.id
+          || ''
+        ).trim();
+        if (nextSessionId) {
+          await chat.actions.selectSession(nextSessionId);
+          return;
+        }
+        chat.actions.resetSession();
+      },
+      projectItems: Array.isArray(chat.state.sessions.items) && chat.state.sessions.items.length > 0
+        ? null
+        : [],
+    },
+    timeline: {
+      items: chat.state.timeline.items,
+      loading: chat.state.composer.loading,
+    },
+    composer: {
+      value: chat.state.composer.inputValue,
+      loading: chat.state.composer.loading,
+      error: chat.state.composer.error,
+      fileList: chat.state.composer.fileList,
+      hintText: chat.state.session.error
+        ? String(chat.state.session.error?.message || chat.state.session.error)
+        : '',
+      onChange: (event) => chat.actions.setInputValue(event?.target?.value || ''),
+      onSend: (options = {}) => chat.actions.send(options),
+      onAttachFiles: (files) => chat.actions.attachFiles(files),
+      onRemoveFile: (file) => chat.actions.removeFile(file),
+    },
+    toolbar: {
+      onRefreshSessions: chat.actions.refreshSessionList,
+      onCreateSession: () => chat.actions.createSession(createSessionPayload),
+    },
+  }), [chat.actions, chat.state.composer.error, chat.state.composer.fileList, chat.state.composer.inputValue, chat.state.composer.loading, chat.state.session.error, chat.state.session.sessionId, chat.state.sessions.error, chat.state.sessions.items, chat.state.timeline.items, createSessionPayload, sessionAPI]);
+
+  return {
+    chat,
+    viewModel,
+  };
+}
+
+export { useCoreChatApp };

package/src/chat-core/facade/useBasicConversationFacade.js

@@ -0,0 +1,280 @@
+import { useCallback, useMemo } from 'react';
+import useChatSessionReducer from '../session/useChatSessionReducer.js';
+import { useChatInput } from '../input/useChatInput.js';
+import { useSSEStream } from '../stream/useSSEStream.js';
+import { buildTimelineItems } from '../messages/buildTimelineItems.js';
+import { useSessionListController } from '../session/useSessionListController.js';
+import { useStreamSendController } from '../stream/useStreamSendController.js';
+import { useBasicSendHandler } from '../orchestration/useBasicSendHandler.js';
+
+function normalizeRefs(value) {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  return value.filter((item) => item !== undefined && item !== null);
+}
+
+function resolvePromoteSessionPayload(raw = {}) {
+  const source = (
+    raw
+    && typeof raw === 'object'
+    && !Array.isArray(raw)
+  ) ? raw : {};
+  const sessionEnvelope = (
+    source.session
+    && typeof source.session === 'object'
+    && !Array.isArray(source.session)
+  ) ? source.session : {};
+  const payloadEnvelope = (
+    source.payload
+    && typeof source.payload === 'object'
+    && !Array.isArray(source.payload)
+  ) ? source.payload : {};
+  const payloadSessionEnvelope = (
+    payloadEnvelope.session
+    && typeof payloadEnvelope.session === 'object'
+    && !Array.isArray(payloadEnvelope.session)
+  ) ? payloadEnvelope.session : {};
+  const sessionId = String(
+    source.sessionId
+    || sessionEnvelope.session_id
+    || ''
+  ).trim();
+  const title = String(
+    payloadSessionEnvelope.title
+    || ''
+  ).trim();
+  return { sessionId, title };
+}
+
+/**
+ * Basic conversation facade.
+ *
+ * Data flow:
+ * 1) UI intent -> facade action
+ * 2) facade preflight -> round execution
+ * 3) stream event -> session state
+ * 4) selector(buildTimelineItems) -> UI model
+ */
+export default function useBasicConversationFacade({
+  sessionAPI,
+  messageAPI,
+  stream,
+  listParams = {},
+  functionType = 'chat_component_debug',
+  defaultSessionTitle = '新会话',
+  defaultSessionPayload = {},
+} = {}) {
+  const chatSession = useChatSessionReducer({ sessionAPI, messageAPI });
+  const chatInput = useChatInput();
+  const sseStream = useSSEStream(chatSession.sessionId);
+  const runtimeStream = stream || sseStream;
+
+  const sessionList = useSessionListController({
+    sessionAPI,
+    listParams,
+    onFailed: chatSession.setSessionError,
+  });
+
+  const streamSend = useStreamSendController({
+    stream: runtimeStream,
+    onStarted: () => {
+      chatSession.setSessionError(null);
+    },
+    onChunk: (chunk) => {
+      chatSession.appendStreamChunk(chunk);
+    },
+    onFailed: (error) => {
+      chatSession.setSessionError(error);
+    },
+  });
+
+  const resolveSendPreflight = useCallback(async (options = {}) => {
+    const content = String(options?.content ?? chatInput.inputValue ?? '').trim();
+    if (!content) {
+      return { blocked: true };
+    }
+
+    let sessionId = String(chatSession.sessionId || '').trim();
+    let createdNewSession = false;
+    if (!sessionId) {
+      sessionId = await chatSession.createSession({
+        function_type: functionType,
+        title: defaultSessionTitle,
+        ...defaultSessionPayload,
+      });
+      createdNewSession = true;
+    }
+
+    const streamOptions = (
+      options.streamOptions
+      && typeof options.streamOptions === 'object'
+      && !Array.isArray(options.streamOptions)
+    ) ? { ...options.streamOptions } : {};
+    const contextRefs = normalizeRefs(options.context_refs);
+    const knowledgeRefs = normalizeRefs(options.knowledge_refs);
+    if (contextRefs && !Object.prototype.hasOwnProperty.call(streamOptions, 'context_refs')) {
+      streamOptions.context_refs = contextRefs;
+    }
+    if (knowledgeRefs && !Object.prototype.hasOwnProperty.call(streamOptions, 'knowledge_refs')) {
+      streamOptions.knowledge_refs = knowledgeRefs;
+    }
+
+    return {
+      blocked: false,
+      content,
+      sessionId,
+      createdNewSession,
+      preserveInputOnError: options.preserveInputOnError === true,
+      attachedSessionFilesSnapshot: Array.isArray(chatInput.fileList) ? chatInput.fileList : [],
+      streamOptions,
+    };
+  }, [chatInput.fileList, chatInput.inputValue, chatSession, defaultSessionPayload, defaultSessionTitle, functionType]);
+
+  const executeSendRound = useCallback(async ({ sendPreflight }) => {
+    chatSession.appendUserMessage(sendPreflight.content);
+    chatSession.setLastUserMessage(sendPreflight.content);
+    chatSession.resetStreaming();
+    chatInput.clearInput();
+
+    await streamSend.executeStreamSend(
+      sendPreflight.content,
+      {
+        onTextReplace: (content) => {
+          chatSession.replaceStreamContent(content);
+        },
+        onAgentStatus: (agentStatus) => {
+          chatSession.setAgentStatus(agentStatus);
+        },
+        onThinkingTrace: (trace) => {
+          chatSession.setThinkingTrace(trace);
+        },
+        onExecutionTrace: (trace) => {
+          chatSession.setExecutionTrace(trace);
+        },
+        onKnowledgeSearch: (searchPayload) => {
+          chatSession.setKnowledgeSearch(searchPayload);
+        },
+        onSourcingCandidates: (sourcingPayload) => {
+          chatSession.setSourcingCandidates(sourcingPayload);
+        },
+        onKnowledgeCitation: (citationPayload) => {
+          chatSession.setKnowledgeCitation(citationPayload);
+        },
+        onPatchEvent: (patchEvent) => {
+          const patchSession = resolvePromoteSessionPayload(patchEvent);
+          if (!patchSession.sessionId) {
+            return;
+          }
+          if (patchSession.sessionId !== chatSession.sessionId || patchSession.title) {
+            chatSession.promoteSession({
+              sessionId: patchSession.sessionId,
+              ...(patchSession.title ? { title: patchSession.title } : {}),
+            });
+          }
+        },
+        onComplete: async (finalContent, doneMeta = {}) => {
+          const doneSession = resolvePromoteSessionPayload(doneMeta);
+          if (doneSession.sessionId && doneSession.sessionId !== chatSession.sessionId) {
+            chatSession.promoteSession({ sessionId: doneSession.sessionId });
+          }
+
+          chatSession.completeStreaming(finalContent, {
+            session_id: doneSession.sessionId || sendPreflight.sessionId,
+          });
+
+          if (sendPreflight.createdNewSession) {
+            void sessionList.loadSessionList({ background: true });
+          }
+        },
+      },
+      {
+        sessionIdOverride: sendPreflight.sessionId,
+        ...sendPreflight.streamOptions,
+      }
+    );
+  }, [chatInput, chatSession, sessionList, streamSend]);
+
+  const handleSendFailureRecovery = useCallback(({ preserveInputOnError, content }) => {
+    if (preserveInputOnError) {
+      chatInput.handleInputChange({ target: { value: content } });
+    }
+  }, [chatInput]);
+
+  const sendHandler = useBasicSendHandler({
+    resolveSendPreflight,
+    executeSendRound,
+    handleSendFailureRecovery,
+    emptyArray: [],
+  });
+
+  const createSession = useCallback(async (options = {}) => {
+    const mergedOptions = {
+      ...defaultSessionPayload,
+      ...options,
+    };
+    const sessionId = await chatSession.createSession({
+      function_type: functionType,
+      title: String(mergedOptions?.title || defaultSessionTitle),
+      project_id: mergedOptions?.project_id ?? null,
+      user_id: mergedOptions?.user_id ?? null,
+    });
+    await sessionList.loadSessionList({ background: true });
+    return sessionId;
+  }, [chatSession, defaultSessionPayload, defaultSessionTitle, functionType, sessionList]);
+
+  const selectSession = useCallback(async (sessionId) => {
+    await chatSession.loadSession(sessionId);
+  }, [chatSession]);
+
+  const refreshSessionList = useCallback(async () => {
+    return sessionList.loadSessionList({ background: true });
+  }, [sessionList]);
+
+  const timeline = useMemo(() => buildTimelineItems(chatSession, { loading: runtimeStream.loading }), [chatSession, runtimeStream.loading]);
+
+  const state = useMemo(() => ({
+    session: {
+      sessionId: chatSession.sessionId,
+      title: chatSession.sessionTitle,
+      detail: chatSession.sessionDetail,
+      error: chatSession.sessionError,
+    },
+    sessions: {
+      items: sessionList.sessions,
+      loading: sessionList.loading,
+      error: sessionList.error,
+    },
+    composer: {
+      inputValue: chatInput.inputValue,
+      fileList: chatInput.fileList,
+      isDragging: chatInput.isDragging,
+      loading: runtimeStream.loading,
+      error: runtimeStream.error,
+    },
+    timeline,
+  }), [chatInput.fileList, chatInput.inputValue, chatInput.isDragging, chatSession.sessionDetail, chatSession.sessionError, chatSession.sessionId, chatSession.sessionTitle, runtimeStream.error, runtimeStream.loading, sessionList.error, sessionList.loading, sessionList.sessions, timeline]);
+
+  const actions = useMemo(() => ({
+    createSession,
+    selectSession,
+    refreshSessionList,
+    resetSession: chatSession.resetSession,
+    loadSession: chatSession.loadSession,
+    updateTitle: chatSession.updateTitle,
+    setInputValue: (value) => chatInput.handleInputChange({ target: { value } }),
+    clearInput: chatInput.clearInput,
+    attachFiles: chatInput.appendFiles,
+    removeFile: chatInput.handleRemoveFile,
+    send: sendHandler.handleSend,
+    retry: runtimeStream.retry,
+    abort: runtimeStream.abort,
+  }), [chatInput, chatSession.loadSession, chatSession.resetSession, chatSession.updateTitle, createSession, refreshSessionList, runtimeStream.abort, runtimeStream.retry, selectSession, sendHandler.handleSend]);
+
+  return {
+    state,
+    actions,
+  };
+}
+
+export { useBasicConversationFacade };

package/src/chat-core/index.js

@@ -1,6 +1,14 @@
-export { default as useChatSessionReducer, initialState as chatSessionInitialState } from './session/useChatSessionReducer.js';
+export { useChatSessionReducer, initialState as chatSessionInitialState } from './session/index.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';
+export { useSessionListController } from './session/index.js';
+export { useStreamSendController } from './stream/useStreamSendController.js';
+export { useBasicSendHandler } from './orchestration/useBasicSendHandler.js';
+export { useBasicConversationFacade } from './facade/useBasicConversationFacade.js';
+export { useCoreChatApp } from './app/useCoreChatApp.js';
+export { useAppStream } from './app/useAppStream.js';
+export { createMockRuntime } from './app/mockRuntime.js';
+export * from './runtime/runtimeMode.js';

package/src/chat-core/messages/buildTimelineItems.analysis-route.test.mjs

@@ -0,0 +1,36 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildTimelineItems } from './buildTimelineItems.js';
+
+test('buildTimelineItems attaches analysis route metadata on sourcing_candidates artifact', () => {
+  const timeline = buildTimelineItems({
+    messages: [
+      {
+        message_id: 'm1',
+        role: 'user',
+        content: '请分析这些供应商',
+        created_at: '2026-04-21T00:00:00Z',
+      },
+    ],
+    streaming: {
+      content: '',
+      sourcingCandidates: {
+        run_id: 'sourcing-run-1',
+        candidates: [{ supplier_id: 'sup-1' }],
+        analysis_route: {
+          analysis_type: 'sourcing',
+          template_id: 'analysis_sourcing_default',
+          reason_codes: ['ROUTE_SIGNAL_SOURCING_INTENT'],
+          confidence: 0.82,
+        },
+      },
+      roundKey: 'rk-1',
+    },
+  });
+
+  const sourcingItem = timeline.items.find((item) => item.type === 'sourcing_candidates');
+  assert.ok(sourcingItem);
+  assert.equal(sourcingItem.analysisRoute.analysis_type, 'sourcing');
+  assert.equal(sourcingItem.analysisRoute.template_id, 'analysis_sourcing_default');
+});

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

@@ -1,11 +1,41 @@
+const CITATION_HIT_SCORE_THRESHOLD = 0.05;
+
+function hasRenderableCitation(citation = {}) {
+  const score = Number(citation?.score);
+  if (Number.isFinite(score)) {
+    return score >= CITATION_HIT_SCORE_THRESHOLD;
+  }
+  const matchedText = String(citation?.matched_text || citation?.hit_reason || '').trim();
+  if (matchedText.length >= 2) {
+    return true;
+  }
+  const snippet = String(citation?.snippet || '').trim();
+  return snippet.length >= 12;
+}
+
+function normalizeCitationPayload(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null;
+  }
+  const citations = Array.isArray(payload.citations) ? payload.citations : [];
+  const filtered = citations.filter((citation) => hasRenderableCitation(citation));
+  if (filtered.length === 0) {
+    return null;
+  }
+  return {
+    ...payload,
+    citations: filtered,
+  };
+}
+
 export function buildTimelineItems(state = {}, options = {}) {
   const messages = Array.isArray(state.messages) ? state.messages : [];
   const uiCards = Array.isArray(state.uiCards) ? state.uiCards : [];
+  const executionCards = Array.isArray(state.executionCards) ? state.executionCards : [];
   const streaming = state.streaming || {};
   const loading = Boolean(options?.loading);
 
   const items = [];
-
   if (messages.length === 0) {
     return {
       isEmpty: true,
@@ -15,6 +45,17 @@ export function buildTimelineItems(state = {}, options = {}) {
 
   messages.forEach((msg, index) => {
     const messageId = msg.message_id || `msg-fallback-${index}`;
+    const primaryFlow = (
+      msg.primary_flow
+      && typeof msg.primary_flow === 'object'
+      && !Array.isArray(msg.primary_flow)
+    ) ? msg.primary_flow : null;
+    const chooserState = (
+      primaryFlow?.chooser_state
+      && typeof primaryFlow.chooser_state === 'object'
+      && !Array.isArray(primaryFlow.chooser_state)
+    ) ? primaryFlow.chooser_state : null;
+    const authoritativeRoundId = String(primaryFlow?.round_id || '').trim();
     items.push({
       id: messageId,
       type: 'message',
@@ -23,11 +64,48 @@ export function buildTimelineItems(state = {}, options = {}) {
       createdAt: msg.created_at,
       client_request_id: msg.client_request_id || '',
       intake_session_id: msg.intake_session_id || '',
-      roundKey: msg.round_key || '',
+      roundKey: msg.round_key || authoritativeRoundId || '',
+      roundId: authoritativeRoundId,
+      roundState: String(primaryFlow?.round_state || '').trim(),
+      chooserKind: String(chooserState?.kind || '').trim(),
+      chooserVisible: chooserState?.visible === true,
       highlights: msg.highlights ?? [],
       sourceTypes: msg.sourceTypes ?? [],
       attachments: Array.isArray(msg.attachments) ? msg.attachments : [],
+      contextUsage: (
+        msg.context_usage
+        && typeof msg.context_usage === 'object'
+        && !Array.isArray(msg.context_usage)
+      ) ? msg.context_usage : null,
     });
+
+    if (msg.role === 'assistant') {
+      if (msg.knowledge_search && typeof msg.knowledge_search === 'object') {
+        items.push({
+          id: `knowledge-search-${messageId}`,
+          type: 'knowledge_search',
+          payload: msg.knowledge_search,
+          roundKey: String(msg.round_key || authoritativeRoundId || '').trim(),
+        });
+      }
+      if (msg.sourcing_candidates && typeof msg.sourcing_candidates === 'object') {
+        items.push({
+          id: `sourcing-candidates-history-${messageId}`,
+          type: 'sourcing_candidates',
+          payload: msg.sourcing_candidates,
+          roundKey: String(msg.round_key || authoritativeRoundId || '').trim(),
+        });
+      }
+      const historicalCitationPayload = normalizeCitationPayload(msg.knowledge_citation);
+      if (historicalCitationPayload) {
+        items.push({
+          id: `knowledge-citation-${messageId}`,
+          type: 'knowledge_citation',
+          payload: historicalCitationPayload,
+          roundKey: String(msg.round_key || authoritativeRoundId || '').trim(),
+        });
+      }
+    }
   });
 
   if (uiCards.length > 0) {
@@ -38,31 +116,79 @@ export function buildTimelineItems(state = {}, options = {}) {
     });
   }
 
+  if (
+    streaming.knowledgeSearch
+    && typeof streaming.knowledgeSearch === 'object'
+    && !Array.isArray(streaming.knowledgeSearch)
+  ) {
+    items.push({
+      id: `knowledge-search-${String(streaming.knowledgeSearch.run_id || 'latest')}`,
+      type: 'knowledge_search',
+      payload: streaming.knowledgeSearch,
+      roundKey: String(streaming.roundKey || '').trim(),
+    });
+  }
+
+  if (
+    streaming.sourcingCandidates
+    && typeof streaming.sourcingCandidates === 'object'
+    && !Array.isArray(streaming.sourcingCandidates)
+  ) {
+    const analysisRoute = (
+      streaming.sourcingCandidates.analysis_route
+      && typeof streaming.sourcingCandidates.analysis_route === 'object'
+      && !Array.isArray(streaming.sourcingCandidates.analysis_route)
+    )
+      ? streaming.sourcingCandidates.analysis_route
+      : (
+        streaming.analysisRoute
+        && typeof streaming.analysisRoute === 'object'
+        && !Array.isArray(streaming.analysisRoute)
+      )
+        ? streaming.analysisRoute
+        : null;
+    items.push({
+      id: `sourcing-candidates-${String(streaming.sourcingCandidates.run_id || 'latest')}`,
+      type: 'sourcing_candidates',
+      payload: streaming.sourcingCandidates,
+      analysisRoute,
+      roundKey: String(streaming.roundKey || '').trim(),
+    });
+  }
+
+  const streamingCitationPayload = normalizeCitationPayload(streaming.knowledgeCitation);
+  if (streamingCitationPayload) {
+    items.push({
+      id: `knowledge-citation-${String(streamingCitationPayload.run_id || 'latest')}`,
+      type: 'knowledge_citation',
+      payload: streamingCitationPayload,
+      roundKey: String(streaming.roundKey || '').trim(),
+    });
+  }
+
   if (streaming.content) {
     items.push({
       id: 'streaming-message',
       type: 'streaming',
       content: streaming.content,
+      roundKey: String(streaming.roundKey || '').trim(),
     });
   }
 
   const hasThinkingSignal = Boolean(streaming.agentStatus || streaming.thinkingTrace || streaming.executionTrace);
-  if (hasThinkingSignal) {
-    items.push({
-      id: 'thinking-bubble',
-      type: 'thinking',
-      agentStatus: streaming.agentStatus,
-      thinkingTrace: streaming.thinkingTrace,
-      executionTrace: streaming.executionTrace,
-    });
-  } else if (loading && !streaming.content) {
+  if (hasThinkingSignal || loading) {
     items.push({
-      id: 'thinking-bubble-loading',
+      id: hasThinkingSignal ? 'thinking-bubble' : 'thinking-bubble-loading',
       type: 'thinking',
-      agentStatus: {
+      agentStatus: streaming.agentStatus || {
         status: 'running',
         agent: '助手',
       },
+      thinkingTrace: streaming.thinkingTrace,
+      executionTrace: streaming.executionTrace,
+      executionCards,
+      roundKey: String(streaming.roundKey || '').trim(),
+      loading,
     });
   }