@xinghunm/ai-chat 1.1.2 → 1.2.1

package/README.md

@@ -55,6 +55,28 @@ const transport = createDefaultChatTransport({
 })
 ```
 
+如果后端协议大体一致，只是模型列表或 `/chat/completions` 请求体需要调整，也可以继续复用默认 transport，只覆盖局部扩展点：
+
+```tsx
+const transport = createDefaultChatTransport({
+  apiBaseUrl: '/ai-api',
+  authToken: 'Bearer your-token-here',
+  resolveModels: async () => ({
+    data: [{ id: 'deepseek-chat', object: 'model' }],
+  }),
+  buildRequestBody: ({ model, mode, content }) => ({
+    model: 'deepseek-chat',
+    base_url: 'https://api.deepseek.com/v1',
+    api_key: 'sk-xxxxx',
+    mode,
+    stream: true,
+    messages: [{ role: 'user', content }],
+  }),
+})
+```
+
+默认 transport 在检测到图片附件时，会自动把用户输入组装成多模态 `messages[].content` 数组，并将图片文件序列化为 Data URL 后发送；如果你自定义 `buildRequestBody`，也会同时收到 `attachments` 参数，可按后端协议自行处理。
+
 ## 完整用法
 
 如需最大灵活性，可在 `AiChatProvider` 内手动组合子组件：
@@ -74,6 +96,7 @@ const transport: ChatTransport = {
     model,
     mode,
     content,
+    attachments,
     onSessionId,
     onUpdate,
     onDone,
@@ -85,7 +108,7 @@ const transport: ChatTransport = {
         method: 'POST',
         signal,
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ sessionId, model, mode, content }),
+        body: JSON.stringify({ sessionId, model, mode, content, attachments }),
       })
       const data = await response.json()
       onSessionId?.(data.sessionId)
@@ -193,6 +216,13 @@ export const CustomChat = () => (
 | `completions` | `"/chat/completions"` | 流式聊天接口路径。     |
 | `terminate`   | `"/chat/terminate"`   | 停止流式响应接口路径。 |
 
+此外还支持两个轻量扩展点：
+
+| 键                 | 类型                                | 说明                                                                           |
+| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------ |
+| `resolveModels`    | `() => Promise<ChatModelsResponse>` | 覆盖默认的 `/models` 请求，直接返回模型列表。                                  |
+| `buildRequestBody` | `(args) => unknown`                 | 覆盖默认的 `/chat/completions` 请求体构造逻辑；`args` 同时包含 `attachments`。 |
+
 ### `AiChatLabels`
 
 所有字段均为可选，未指定的字段回退到 `DEFAULT_AI_CHAT_LABELS` 中的英文默认值。

package/dist/index.d.mts

@@ -42,6 +42,12 @@ interface ChatImageAttachment {
     mimeType: string;
     size: number;
     previewUrl: string;
+    /**
+     * Original file kept for transports that need to upload or serialize the image.
+     *
+     * This is only available for client-originated attachments selected in the composer.
+     */
+    file?: File;
 }
 /**
  * Select option metadata used by plan questionnaires.
@@ -291,6 +297,10 @@ interface ChatTransportStartStreamArgs {
     mode: ChatAgentMode;
     /** User message content that should be sent to the backend. */
     content: string;
+    /**
+     * Optional image attachments selected in the composer and sent alongside the text.
+     */
+    attachments?: ChatImageAttachment[];
     /** Abort signal controlled by the chat composer stop action. */
     signal?: AbortSignal;
     /** Emits normalized streaming patches that should update the assistant message. */
@@ -421,6 +431,17 @@ interface AiChatLabels {
     questionnaireOtherOptionLabel?: string;
     questionnaireOtherPlaceholder?: string;
 }
+/**
+ * State and actions exposed to custom new-chat trigger renderers.
+ */
+interface NewChatTriggerRenderProps {
+    activeSessionId: string | null;
+    isStreaming: boolean;
+    isStopping: boolean;
+    createNewSession: () => void;
+    stopActiveSession: () => Promise<void>;
+    startNewChat: () => Promise<void>;
+}
 /**
  * Default English label values used when no labels are provided.
  */
@@ -482,12 +503,16 @@ declare const AiChatProvider: (props: AiChatProviderProps) => _emotion_react_jsx
 type AiChatProps = Omit<AiChatProviderProps, 'children'> & {
     /** When true, renders the conversation list sidebar. Defaults to false. */
     showConversationList?: boolean;
+    /** When true, renders a lightweight new-chat button without the full conversation list. */
+    showNewChatButton?: boolean;
+    /** Optional renderer used to override the lightweight new-chat trigger UI. */
+    renderNewChatTrigger?: (props: NewChatTriggerRenderProps) => ReactNode;
 };
 /**
  * Top-level AI chat component. Wraps AiChatProvider and composes the full
  * chat UI: optional conversation sidebar + thread + composer.
  */
-declare const AiChat: ({ showConversationList, ...providerProps }: AiChatProps) => _emotion_react_jsx_runtime.JSX.Element;
+declare const AiChat: ({ showConversationList, showNewChatButton, renderNewChatTrigger, ...providerProps }: AiChatProps) => _emotion_react_jsx_runtime.JSX.Element;
 
 /**
  * Endpoint overrides for the built-in HTTP transport adapter.
@@ -511,6 +536,25 @@ interface ChatToolExecutionPolicy {
     /** Approval timeout in seconds, forwarded when approval is enabled. */
     approvalTimeoutSec?: number;
 }
+/**
+ * Arguments passed to a custom request body builder for the default transport.
+ */
+interface DefaultChatTransportRequestBodyBuilderArgs {
+    sessionId?: string;
+    model: string;
+    mode: ChatAgentMode;
+    content: string;
+    attachments?: ChatImageAttachment[];
+}
+/**
+ * Optional builder used to customize the `/chat/completions` request body while
+ * reusing the default streaming transport behavior.
+ */
+type DefaultChatTransportRequestBodyBuilder = (args: DefaultChatTransportRequestBodyBuilderArgs) => unknown;
+/**
+ * Optional model resolver used to override the default `/models` request.
+ */
+type DefaultChatTransportModelsResolver = () => Promise<ChatModelsResponse>;
 /**
  * Options for the built-in HTTP transport adapter.
  */
@@ -523,6 +567,10 @@ interface CreateDefaultChatTransportOptions {
     toolExecutionPolicy?: ChatToolExecutionPolicy;
     /** Optional extra headers appended to each streaming chat completion request. */
     streamHeaders?: Record<string, string>;
+    /** Optional resolver used to override the built-in model catalog request. */
+    resolveModels?: DefaultChatTransportModelsResolver;
+    /** Optional builder used to override the built-in chat completion request body. */
+    buildRequestBody?: DefaultChatTransportRequestBodyBuilder;
     /** Optional transformer used to normalize custom stream packets. */
     transformStreamPacket?: TransformChatStreamPacket;
     /** Optional endpoint overrides for backends that use different paths. */
@@ -533,7 +581,7 @@ interface CreateDefaultChatTransportOptions {
 /**
  * Creates the built-in transport backed by the current HTTP chat API.
  */
-declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, toolExecutionPolicy, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
+declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, toolExecutionPolicy, streamHeaders, resolveModels, buildRequestBody, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
 
 declare const ChatThread: () => _emotion_react_jsx_runtime.JSX.Element;
 
@@ -593,6 +641,7 @@ interface ChatState {
 }
 interface ChatActions {
     createSession: (session: ChatSession) => void;
+    startNewChat: () => void;
     setActiveSession: (sessionId: string | null) => void;
     replaceSessionId: (previousSessionId: string, nextSessionId: string) => void;
     setPreferredMode: (mode: ChatAgentMode) => void;
@@ -612,6 +661,12 @@ type ChatStore = ChatState & ChatActions;
 type ChatStoreInstance = ReturnType<typeof createChatStore>;
 declare const createChatStore: (initialState?: Partial<Pick<ChatState, "preferredMode">>) => zustand_vanilla.StoreApi<ChatStore>;
 
+interface ChatSendRefOptions {
+    /** Explicit target session for programmatic sends triggered from a thread card. */
+    sessionId?: string;
+    /** Whether to consume the composer attachment draft. Defaults to true for composer sends. */
+    includeComposerAttachments?: boolean;
+}
 interface ChatContextValue {
     store: ChatStoreInstance;
     transport: ChatTransport;
@@ -623,9 +678,11 @@ interface ChatContextValue {
     authToken?: string;
     labels: Required<AiChatLabels>;
     /** Stable ref populated by ChatComposer on mount; allows ChatThread to trigger sends. */
-    sendRef: MutableRefObject<(content: string) => Promise<void>>;
-    /** Stable ref populated by ChatComposer on mount; allows ChatThread to replay the last request. */
-    retryRef: MutableRefObject<() => Promise<void>>;
+    sendRef: MutableRefObject<(content: string, options?: ChatSendRefOptions) => Promise<void>>;
+    /** Stable ref populated by ChatComposer on mount; allows ChatThread to replay a session request. */
+    retryRef: MutableRefObject<(sessionId: string) => Promise<void>>;
+    /** Stable ref populated by ChatComposer on mount; allows external controls to stop streaming. */
+    stopRef: MutableRefObject<(sessionId: string) => Promise<void>>;
     /** Optional block renderer used to extend message rendering with custom block types. */
     renderMessageBlock?: ChatMessageBlockRenderer;
     /** Optional handler used to intercept questionnaire submissions before the default send flow. */
@@ -654,4 +711,4 @@ declare const useChatContext: () => ChatContextValue;
  */
 declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
 
-export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type DefaultChatTransportModelsResolver, type DefaultChatTransportRequestBodyBuilder, type DefaultChatTransportRequestBodyBuilderArgs, type ExecutionConfirmationSubmission, type ExecutionProposal, type NewChatTriggerRenderProps, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };

package/dist/index.d.ts

@@ -42,6 +42,12 @@ interface ChatImageAttachment {
     mimeType: string;
     size: number;
     previewUrl: string;
+    /**
+     * Original file kept for transports that need to upload or serialize the image.
+     *
+     * This is only available for client-originated attachments selected in the composer.
+     */
+    file?: File;
 }
 /**
  * Select option metadata used by plan questionnaires.
@@ -291,6 +297,10 @@ interface ChatTransportStartStreamArgs {
     mode: ChatAgentMode;
     /** User message content that should be sent to the backend. */
     content: string;
+    /**
+     * Optional image attachments selected in the composer and sent alongside the text.
+     */
+    attachments?: ChatImageAttachment[];
     /** Abort signal controlled by the chat composer stop action. */
     signal?: AbortSignal;
     /** Emits normalized streaming patches that should update the assistant message. */
@@ -421,6 +431,17 @@ interface AiChatLabels {
     questionnaireOtherOptionLabel?: string;
     questionnaireOtherPlaceholder?: string;
 }
+/**
+ * State and actions exposed to custom new-chat trigger renderers.
+ */
+interface NewChatTriggerRenderProps {
+    activeSessionId: string | null;
+    isStreaming: boolean;
+    isStopping: boolean;
+    createNewSession: () => void;
+    stopActiveSession: () => Promise<void>;
+    startNewChat: () => Promise<void>;
+}
 /**
  * Default English label values used when no labels are provided.
  */
@@ -482,12 +503,16 @@ declare const AiChatProvider: (props: AiChatProviderProps) => _emotion_react_jsx
 type AiChatProps = Omit<AiChatProviderProps, 'children'> & {
     /** When true, renders the conversation list sidebar. Defaults to false. */
     showConversationList?: boolean;
+    /** When true, renders a lightweight new-chat button without the full conversation list. */
+    showNewChatButton?: boolean;
+    /** Optional renderer used to override the lightweight new-chat trigger UI. */
+    renderNewChatTrigger?: (props: NewChatTriggerRenderProps) => ReactNode;
 };
 /**
  * Top-level AI chat component. Wraps AiChatProvider and composes the full
  * chat UI: optional conversation sidebar + thread + composer.
  */
-declare const AiChat: ({ showConversationList, ...providerProps }: AiChatProps) => _emotion_react_jsx_runtime.JSX.Element;
+declare const AiChat: ({ showConversationList, showNewChatButton, renderNewChatTrigger, ...providerProps }: AiChatProps) => _emotion_react_jsx_runtime.JSX.Element;
 
 /**
  * Endpoint overrides for the built-in HTTP transport adapter.
@@ -511,6 +536,25 @@ interface ChatToolExecutionPolicy {
     /** Approval timeout in seconds, forwarded when approval is enabled. */
     approvalTimeoutSec?: number;
 }
+/**
+ * Arguments passed to a custom request body builder for the default transport.
+ */
+interface DefaultChatTransportRequestBodyBuilderArgs {
+    sessionId?: string;
+    model: string;
+    mode: ChatAgentMode;
+    content: string;
+    attachments?: ChatImageAttachment[];
+}
+/**
+ * Optional builder used to customize the `/chat/completions` request body while
+ * reusing the default streaming transport behavior.
+ */
+type DefaultChatTransportRequestBodyBuilder = (args: DefaultChatTransportRequestBodyBuilderArgs) => unknown;
+/**
+ * Optional model resolver used to override the default `/models` request.
+ */
+type DefaultChatTransportModelsResolver = () => Promise<ChatModelsResponse>;
 /**
  * Options for the built-in HTTP transport adapter.
  */
@@ -523,6 +567,10 @@ interface CreateDefaultChatTransportOptions {
     toolExecutionPolicy?: ChatToolExecutionPolicy;
     /** Optional extra headers appended to each streaming chat completion request. */
     streamHeaders?: Record<string, string>;
+    /** Optional resolver used to override the built-in model catalog request. */
+    resolveModels?: DefaultChatTransportModelsResolver;
+    /** Optional builder used to override the built-in chat completion request body. */
+    buildRequestBody?: DefaultChatTransportRequestBodyBuilder;
     /** Optional transformer used to normalize custom stream packets. */
     transformStreamPacket?: TransformChatStreamPacket;
     /** Optional endpoint overrides for backends that use different paths. */
@@ -533,7 +581,7 @@ interface CreateDefaultChatTransportOptions {
 /**
  * Creates the built-in transport backed by the current HTTP chat API.
  */
-declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, toolExecutionPolicy, streamHeaders, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
+declare const createDefaultChatTransport: ({ apiBaseUrl, authToken, toolExecutionPolicy, streamHeaders, resolveModels, buildRequestBody, transformStreamPacket, endpoints, axiosInstance, }: CreateDefaultChatTransportOptions) => ChatTransport;
 
 declare const ChatThread: () => _emotion_react_jsx_runtime.JSX.Element;
 
@@ -593,6 +641,7 @@ interface ChatState {
 }
 interface ChatActions {
     createSession: (session: ChatSession) => void;
+    startNewChat: () => void;
     setActiveSession: (sessionId: string | null) => void;
     replaceSessionId: (previousSessionId: string, nextSessionId: string) => void;
     setPreferredMode: (mode: ChatAgentMode) => void;
@@ -612,6 +661,12 @@ type ChatStore = ChatState & ChatActions;
 type ChatStoreInstance = ReturnType<typeof createChatStore>;
 declare const createChatStore: (initialState?: Partial<Pick<ChatState, "preferredMode">>) => zustand_vanilla.StoreApi<ChatStore>;
 
+interface ChatSendRefOptions {
+    /** Explicit target session for programmatic sends triggered from a thread card. */
+    sessionId?: string;
+    /** Whether to consume the composer attachment draft. Defaults to true for composer sends. */
+    includeComposerAttachments?: boolean;
+}
 interface ChatContextValue {
     store: ChatStoreInstance;
     transport: ChatTransport;
@@ -623,9 +678,11 @@ interface ChatContextValue {
     authToken?: string;
     labels: Required<AiChatLabels>;
     /** Stable ref populated by ChatComposer on mount; allows ChatThread to trigger sends. */
-    sendRef: MutableRefObject<(content: string) => Promise<void>>;
-    /** Stable ref populated by ChatComposer on mount; allows ChatThread to replay the last request. */
-    retryRef: MutableRefObject<() => Promise<void>>;
+    sendRef: MutableRefObject<(content: string, options?: ChatSendRefOptions) => Promise<void>>;
+    /** Stable ref populated by ChatComposer on mount; allows ChatThread to replay a session request. */
+    retryRef: MutableRefObject<(sessionId: string) => Promise<void>>;
+    /** Stable ref populated by ChatComposer on mount; allows external controls to stop streaming. */
+    stopRef: MutableRefObject<(sessionId: string) => Promise<void>>;
     /** Optional block renderer used to extend message rendering with custom block types. */
     renderMessageBlock?: ChatMessageBlockRenderer;
     /** Optional handler used to intercept questionnaire submissions before the default send flow. */
@@ -654,4 +711,4 @@ declare const useChatContext: () => ChatContextValue;
  */
 declare const useChatStore: <T>(selector: (state: ChatStore) => T) => T;
 
-export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type ExecutionConfirmationSubmission, type ExecutionProposal, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };
+export { AiChat, type AiChatLabels, type AiChatProps, AiChatProvider, type AiChatProviderProps, CHAT_AGENT_MODES, CHAT_MESSAGE_RENDER_ORDERS, type ChatAgentMode, ChatComposer, type ChatComposerViewProps, type ChatConfirmationSubmitHandler, ChatConversationList, type ChatImageAttachment, type ChatMessage, type ChatMessageBlock, type ChatMessageBlockRenderer, type ChatMessageBlockRendererProps, type ChatMessageRenderOrder, type ChatMessageStatus, type ChatModel, type ChatParameterSummaryItem, type ChatQuestionnaireSubmitHandler, type ChatRole, type ChatSession, type ChatStreamMessagePatch, type ChatStreamPacketTransformArgs, type ChatStreamPacketUpdate, type ChatSubmissionContext, ChatThread, type ChatToolExecutionPolicy, type ChatTransport, type ChatTransportStartStreamArgs, type CreateDefaultChatTransportOptions, DEFAULT_AI_CHAT_LABELS, DEFAULT_CHAT_AGENT_MODE, type DefaultChatTransportEndpoints, type DefaultChatTransportModelsResolver, type DefaultChatTransportRequestBodyBuilder, type DefaultChatTransportRequestBodyBuilderArgs, type ExecutionConfirmationSubmission, type ExecutionProposal, type NewChatTriggerRenderProps, type PlanQuestionOption, type PlanQuestionSubmissionDetail, type PlanQuestionnaire, type PlanQuestionnaireSubmission, type ResultSummary, type TransformChatStreamPacket, createDefaultChatTransport, useChatContext, useChatStore };