netstar-ai-chat 1.0.0 → 1.0.2

package/dist/AgentChat/AIMessage.d.ts

@@ -0,0 +1,454 @@
+export type DecisionType = import('./LangchainMessage').DecisionType;
+export type InterruptEvent = import('./LangchainMessage').InterruptEvent;
+export type ResumeDecision = import('./LangchainMessage').ResumeDecision;
+export type CreateAgentDecision = import('./LangchainMessage').CreateAgentDecision;
+export type AnyResumeDecision = import('./LangchainMessage').AnyResumeDecision;
+/** 消息发送者角色 */
+export type ChatRole = 'ai' | 'user';
+/** 工具调用生命周期状态 */
+export type ToolCallStatus = 'error' | 'running' | 'success' | 'waiting';
+/**
+ * Agent 层抛出的原始工具调用事件。
+ * - `running`：工具已被调用，入参已知，等待执行结果。
+ * - `success`：工具执行成功，output 为返回值。
+ * - `error`  ：工具执行失败，error 为错误描述。
+ */
+export interface ToolCallEvent {
+    /** 审批配置（status === 'waiting' 时存在，来自中断事件） */
+    approvalConfig?: {
+        /** 允许的决策类型 */
+        allowedDecisions: import('./LangchainMessage').DecisionType[];
+        /** 操作描述 */
+        description: string;
+        /** 中断事件 ID */
+        interruptId: string;
+    };
+    /** 工具执行耗时（毫秒），status 变为终态后才有值 */
+    durationMs?: number;
+    /** 错误信息（status === 'error' 时存在） */
+    error?: string;
+    /** 调用入参（任意结构，由具体工具定义） */
+    input?: unknown;
+    /** 调用输出（status === 'success' 时存在） */
+    output?: unknown;
+    /** 当前状态 */
+    status: ToolCallStatus;
+    /** 所处轮次序号（0-based），多步 Agent 循环时有值 */
+    stepNumber?: number;
+    /** 事件触发时的 Unix 时间戳（毫秒） */
+    timestamp: number;
+    /** 友好展示标题（优先于 toolName 展示，可选） */
+    title?: string;
+    /** 本次工具调用的唯一 ID（由模型分配） */
+    toolCallId: string;
+    /** 工具名称（程序标识符） */
+    toolName: string;
+}
+/**
+ * 连续文本段，指向宿主消息 `content` 的字符区间 `[start, end)`.
+ * `end === -1` 表示延伸到 `content` 末尾（流式尚未结束时使用）。
+ */
+export interface TextSegment {
+    /** 结束字符索引（不包含，-1 表示到消息末尾） */
+    end: number;
+    /** 起始字符索引（包含） */
+    start: number;
+    type: 'text';
+}
+/** 工具调用占位段，关联一次具体的工具调用 */
+export interface ToolSegment {
+    toolCallId: string;
+    type: 'tool';
+}
+/** 消息内容段（文本段 | 工具调用段） */
+export type ContentSegment = TextSegment | ToolSegment;
+/**
+ * 工具调用时间线中的单条记录。
+ * 由原始 ToolCallEvent 整合而来，包含截断后的预览字符串，
+ * 可直接供 ChatPanel 渲染工具调用节点。
+ */
+export interface ToolTimelineItem {
+    /**
+     * 审批配置（status === 'waiting' 时存在）。
+     * 当工具调用需要人工审批时，存储审批相关的配置信息。
+     */
+    approvalConfig?: {
+        /** 允许的决策类型 */
+        allowedDecisions: import('./LangchainMessage').DecisionType[];
+        /** 入参对象 */
+        args: Record<string, unknown>;
+        /** 操作描述 */
+        description: string;
+        /** 编辑内容（edit 审批时使用） */
+        editContent: string;
+        /** 中断事件 ID */
+        interruptId: string;
+    };
+    /** 工具执行耗时（毫秒） */
+    durationMs?: number;
+    /** 原始错误（供特定工具自定义渲染使用） */
+    error?: string;
+    /** 原始入参（供特定工具自定义渲染使用） */
+    input?: unknown;
+    /** 入参预览文本（已截断） */
+    inputPreview?: string;
+    /** 原始输出（供特定工具自定义渲染使用） */
+    output?: unknown;
+    /**
+     * 结果预览文本（已截断）。
+     * status === 'error' 时为错误信息，success 时为输出内容。
+     */
+    resultPreview?: string;
+    /** 调用发起时间（ms since epoch） */
+    startedAt: number;
+    status: ToolCallStatus;
+    /** 所处步骤序号（0-based） */
+    stepNumber?: number;
+    /** 友好展示标题 */
+    title?: string;
+    toolCallId: string;
+    toolName: string;
+}
+/**
+ * ChatPanel 内部维护的消息结构。
+ * - 用户消息仅含 role / key / content。
+ * - AI 消息在流式输出时 loading 为 true，content 逐字追加；
+ *   如有工具调用，toolTimeline 和 segments 同步更新。
+ */
+export interface ChatMessage {
+    /**
+     * 消息正文（纯文本或 Markdown 字符串）。
+     * AI 消息在流式输出时逐字追加；工具调用不计入此字段。
+     */
+    content: string;
+    /** 消息唯一标识（渲染 key） */
+    key: string;
+    /** 消息是否正在加载（流式输出尚未结束） */
+    loading?: boolean;
+    /** 消息角色 */
+    role: ChatRole;
+    /**
+     * 内容段列表，描述文本与工具调用的交叉顺序。
+     * 无工具调用时为空，全部内容退化为单一文本段。
+     */
+    segments?: ContentSegment[];
+    /** 工具调用时间线（AI 消息专用，用于渲染工具调用节点） */
+    toolTimeline?: ToolTimelineItem[];
+}
+/** 已将字符范围解析为实际文本的渲染段 */
+export interface ResolvedTextSegment {
+    /** 已切片的文本内容，可直接传给 StreamMarkdown */
+    text: string;
+    type: 'text';
+}
+/** 已解析的工具调用渲染段 */
+export interface ResolvedToolSegment {
+    toolCallId: string;
+    type: 'tool';
+}
+/** 可直接供模板 v-for 消费的渲染段联合类型 */
+export type ResolvedSegment = ResolvedTextSegment | ResolvedToolSegment;
+/**
+ * 历史会话摘要条目，用于侧边栏列表展示。
+ * 与具体后端（Dify / 自研）无关，由 Agent 层负责适配。
+ */
+export interface ConversationSummary {
+    /** 会话创建时间（ms since epoch，可选） */
+    createdAt?: number;
+    /** 会话唯一 ID */
+    id: string;
+    /** 会话标题（可能由用户命名或由模型自动生成） */
+    title: string;
+    /** 会话最后更新时间（ms since epoch，可选） */
+    updatedAt?: number;
+}
+/** 历史会话列表响应 */
+export interface ConversationListResult {
+    /** 是否还有更多分页数据 */
+    hasMore: boolean;
+    /** 本页会话摘要列表 */
+    items: ConversationSummary[];
+    /**
+     * 用于加载下一页的游标（通常为末条记录 ID）。
+     * `hasMore === false` 时可忽略。
+     */
+    nextCursor?: string;
+}
+/**
+ * 单条原始消息记录（后端返回的最小结构）。
+ * 与具体后端无关，由 Agent 层负责适配。
+ */
+export interface HistoryMessageRecord {
+    /** AI 回复文本（Markdown） */
+    answer: string;
+    /** 所属会话 ID */
+    conversationId: string;
+    /** 消息创建时间（ms since epoch，可选） */
+    createdAt?: number;
+    /** 原始消息 ID */
+    id: string;
+    /** 用户问题文本 */
+    query: string;
+}
+/** 单条历史对话详情响应 */
+export interface ConversationDetailResult {
+    /** 会话 ID */
+    conversationId: string;
+    /** 是否还有更多历史消息（分页加载时使用） */
+    hasMore: boolean;
+    /** 用于加载更多的游标（通常为首条记录 ID） */
+    nextCursor?: string;
+    /** 原始消息记录列表（按时间升序） */
+    records: HistoryMessageRecord[];
+    /** 对话标题 */
+    title: string;
+}
+/**
+ * 将单条 `HistoryMessageRecord` 转换为 ChatPanel 所需的一对消息（用户 + AI）。
+ *
+ * 转换规则：
+ * - `record.query`  → `ChatMessage { role: 'user', content: query }`
+ * - `record.answer` → `ChatMessage { role: 'ai',   content: answer }`
+ *
+ * @param record  单条原始历史消息
+ * @param keyPrefix 生成唯一 key 的前缀（通常传 record.id）
+ */
+export type HistoryRecordConverter = (record: HistoryMessageRecord, keyPrefix: string) => [userMsg: ChatMessage, aiMsg: ChatMessage];
+/**
+ * 将完整 `ConversationDetailResult` 转换为可直接传入 ChatPanel
+ * `initialMessages` prop 的 `ChatMessage[]` 数组（按时间升序）。
+ */
+export type ConversationDetailConverter = (detail: ConversationDetailResult) => ChatMessage[];
+/**
+ * `replyChange` 事件处理器。
+ * @param delta    本次新增的文本片段（流式增量）
+ * @param allReply 截至目前累积的完整回复内容
+ */
+export type ReplyChangeHandler = (delta: string, allReply: string) => void;
+/** `stop` 事件处理器（Agent 主动停止或被中止时触发） */
+export type StopHandler = () => void;
+/** `toolCall` 事件处理器 */
+export type ToolCallHandler = (event: ToolCallEvent) => void;
+/** `interrupt` 事件处理器（工具调用需要审批时触发） */
+export type InterruptHandler = (event: import('./LangchainMessage').InterruptEvent) => void;
+/** Agent 可透传给上层的事件名 */
+export type AgentEventName = 'interrupt' | 'replyChange' | 'stop' | 'toolCall';
+/** Agent 事件透传载荷 */
+export type AgentEventPayload = {
+    agentKey: string;
+    args: [];
+    event: 'stop';
+} | {
+    agentKey: string;
+    args: [event: import('./LangchainMessage').InterruptEvent];
+    event: 'interrupt';
+} | {
+    agentKey: string;
+    args: [event: ToolCallEvent];
+    event: 'toolCall';
+} | {
+    agentKey: string;
+    args: [reply: string, allReply: string];
+    event: 'replyChange';
+};
+/** Agent 事件透传回调 */
+export type AgentEventCallback = (payload: AgentEventPayload) => void;
+/**
+ * Agent 运行时接口。
+ *
+ * ChatPanel 通过此接口与具体 AI Agent 完全解耦：
+ * 任何实现了该接口的对象均可作为 Agent 传入 ChatPanel。
+ *
+ * 典型实现：`ToolLoopAgentWapper`（见 wrapAgent.ts）
+ */
+export interface AgentRuntime {
+    /**
+     * 向 Agent 提交用户问题并等待本轮回复完成。
+     * 流式文本内容通过 `replyChange` 事件推送，
+     * 工具调用事件通过 `toolCall` 事件推送。
+     * Promise resolve 表示本轮通信结束（成功或被中止）。
+     */
+    ask(query: string): Promise<unknown>;
+    /**
+     * 获取指定会话的历史消息详情，并直接返回可渲染的消息列表。
+     *
+     * 实现方负责将后端原始数据（结构因各后端而异）适配为 `ChatMessage[]`，
+     * 每条历史问答通常展开为 `[userMsg, aiMsg]` 两条记录，按时间升序排列。
+     *
+     * @param conversationId 目标会话 ID
+     * @param cursor 分页游标；首次加载时传 `undefined`，
+     *               后续翻页传上一次响应附带的游标值。
+     * @returns 可直接传入 ChatPanel `initialMessages` prop 的消息数组
+     */
+    getConversationDetail(conversationId: string, cursor?: string): Promise<ChatMessage[]>;
+    /**
+     * 获取历史会话列表（分页）。
+     *
+     * @param cursor 分页游标；首次加载时传 `undefined`，
+     *               后续翻页传上一次响应的 `nextCursor`。
+     * @returns 会话摘要列表及分页信息
+     */
+    listConversations(cursor?: string): Promise<ConversationListResult>;
+    /** 移除事件监听器 */
+    off(event: 'replyChange', handler: ReplyChangeHandler): void;
+    off(event: 'stop', handler: StopHandler): void;
+    off(event: 'toolCall', handler: ToolCallHandler): void;
+    /** 注册事件监听器 */
+    on(event: 'replyChange', handler: ReplyChangeHandler): void;
+    on(event: 'stop', handler: StopHandler): void;
+    on(event: 'toolCall', handler: ToolCallHandler): void;
+    /** 清空 Agent 内部的会话历史（不影响 ChatPanel 的消息列表） */
+    reset(): void;
+    /** 中止当前正在进行的请求，并触发 `stop` 事件 */
+    stop(): void;
+    /**
+     * 是否支持历史会话（可选）。
+     * 实现方根据后端配置判断，例如检查 historyEndpoint 是否已设置。
+     * 未实现时默认视为不支持历史功能。
+     */
+    supportsHistory?(): boolean;
+}
+/**
+ * 携带初始上下文注入能力的扩展 Agent 接口（可选实现）。
+ * 用于在正式对话前向 Agent 注入系统级背景信息，
+ * 如用户画像、会话元数据等。
+ */
+export interface ExtendedAgentRuntime extends AgentRuntime {
+    /** 追加一条初始用户上下文（不计入对话历史展示） */
+    addInitialUserContext(context: string): void;
+    /** 清除全部初始用户上下文 */
+    clearInitialUserContexts(): void;
+    /** 移除中断事件监听器 */
+    offInterrupt(handler: InterruptHandler): void;
+    /** 注册中断事件监听器 */
+    onInterrupt(handler: InterruptHandler): void;
+    /**
+     * 对中断工具调用做出决策后，恢复 SSE 流。
+     * 调用方统一传递 ResumeDecision[]，内部按 resumeMode 转换为对应后端格式。
+     */
+    resume(decisions: import('./LangchainMessage').ResumeDecision[]): Promise<void>;
+    /** 覆盖全部初始用户上下文 */
+    setInitialUserContexts(contexts: string[]): void;
+}
+/**
+ * 传入 ChatPanel `agents` prop 的单个配置项。
+ * 支持多 Agent 切换时，每个 Agent 对应一条记录。
+ */
+export interface AgentOption {
+    /** Agent 运行时实例 */
+    agent: AgentRuntime;
+    /** 用于唯一标识此 Agent，也作为下拉选项的 value */
+    key: string;
+    /** 下拉选择器中展示的友好名称 */
+    label: string;
+    /**
+     * 工具名称 → 自定义渲染组件（可选）。
+     *
+     * 当指定的工具名出现时，ChatPanel 会使用此处配置的组件替换默认
+     * `ToolCallNode`，实现工具级别的自定义 UI。
+     * 未配置的工具名仍回退到默认 `ToolCallNode`。
+     *
+     * 组件须满足 `ToolRendererProps` props 与 `ToolRendererEmits` emits 约定。
+     */
+    toolRenderers?: ToolRendererMap;
+}
+/**
+ * 将任意 payload 序列化为截断后的预览字符串。
+ * - `string`         → 直接使用
+ * - `object / array` → JSON.stringify
+ * - 其他             → String()
+ * - 超出 `maxLength` 时截断并追加 "…"
+ */
+export type PayloadPreviewFormatter = (payload: unknown, maxLength?: number) => string;
+/**
+ * 自定义工具渲染组件的 props 约定。
+ *
+ * 与 `ToolCallNode` 保持完全一致，以便消费方可以直接以相同 prop 接口
+ * 替换默认渲染组件，也可以将 `ToolCallNode` 作为基础组件复用。
+ */
+export interface ToolRendererProps {
+    /** 当前节点是否已展开详情 */
+    expanded: boolean;
+    /** 审批操作是否正在处理中（应据此禁用按钮） */
+    resolving?: boolean;
+    /** 工具在本轮对话中的步骤序号（0-based，可选） */
+    stepNumber?: number;
+    /** 工具调用时间线条目，包含状态、入参、输出等完整上下文 */
+    tool: ToolTimelineItem;
+}
+/**
+ * 自定义工具渲染组件的 emits 约定。
+ *
+ * 组件内部无需关心决策如何提交，只需 emit 对应事件，
+ * ChatPanel 会统一处理并调用 Agent 的 resume 方法。
+ */
+export interface ToolRendererEmits {
+    /** 批准工具操作；actionName 为工具名称或空字符串（由 ChatPanel 自动推断） */
+    approve: (actionName: string) => void;
+    /** 提交修改后批准；editedContent 为修改后的内容 */
+    edit: (actionName: string, editedContent: string) => void;
+    /** 拒绝工具操作 */
+    reject: (actionName: string) => void;
+    /** 切换展开/折叠详情面板 */
+    toggle: () => void;
+}
+/**
+ * 工具名称 → 自定义渲染组件的映射表。
+ *
+ * key 为 `ToolTimelineItem.toolName`，value 为 Vue 组件定义。
+ * 组件应满足 `ToolRendererProps` & `ToolRendererEmits` 约定。
+ *
+ * @example
+ * ```ts
+ * const toolRenderers: ToolRendererMap = {
+ *   search_web: SearchWebToolRenderer,
+ *   run_code:   CodeExecutionRenderer,
+ * };
+ * ```
+ */
+export type ToolRendererMap = Record<string, import('vue').Component>;
+/**
+ * 将 Unix 时间戳（毫秒）格式化为本地时间字符串，
+ * 用于工具调用时间线的时间展示。
+ */
+export type TimestampFormatter = (timestamp: number) => string;
+/**
+ * 将耗时（毫秒）格式化为可读字符串。
+ * 例：120 → "120ms"，1500 → "1.5s"，12000 → "12s"
+ */
+export type DurationFormatter = (durationMs: number) => string;
+/**
+ * 将 `ChatMessage` 的 `segments` 解析为可直接用于模板渲染的段列表。
+ * - 若消息没有 `segments`（无工具调用），退化为单一 `ResolvedTextSegment`。
+ * - `TextSegment` 的字符范围会被切片为实际文本。
+ */
+export type SegmentResolver = (message: ChatMessage) => ResolvedSegment[];
+/**
+ * 将单条 `HistoryMessageRecord` 转换为一对 `ChatMessage`（用户 + AI）。
+ *
+ * 转换规则：
+ * - `record.query`  → `{ role: 'user', content: query }`
+ * - `record.answer` → `{ role: 'ai',   content: answer }`
+ *
+ * @example
+ * ```ts
+ * const [userMsg, aiMsg] = convertHistoryRecord(record, record.id);
+ * ```
+ */
+export declare const convertHistoryRecord: HistoryRecordConverter;
+/**
+ * 将完整 `ConversationDetailResult` 转换为 `ChatMessage[]`，
+ * 可直接传入 ChatPanel 的 `initialMessages` prop。
+ *
+ * 每条 `HistoryMessageRecord` 展开为 `[userMsg, aiMsg]`，
+ * 最终数组按原始记录顺序（时间升序）排列。
+ *
+ * @example
+ * ```ts
+ * const detail = await agent.getConversationDetail(conversationId);
+ * const messages = convertConversationDetail(detail);
+ * // 传入 ChatPanel
+ * // <ChatPanel :initial-messages="messages" ... />
+ * ```
+ */
+export declare const convertConversationDetail: ConversationDetailConverter;

package/dist/AgentChat/AI_HITL_Config.d.ts

@@ -0,0 +1,25 @@
+export type SupportDecisionType = 'approve' | 'edit' | 'reject';
+export interface DecisionOptions {
+    actionName: SupportDecisionType;
+    showName?: string;
+    tooltip?: string;
+}
+export interface AI_HITL_UIConfig {
+    children?: AI_HITL_UIConfig[];
+    component: string;
+    props?: Record<string, any>;
+}
+export interface AI_HITL_Config {
+    allowReplyOnChatInput: boolean;
+    contentUIConfig: {
+        html?: string;
+        serverPage?: {
+            code: string;
+            pageParams?: Record<string, any>;
+        };
+        type: 'html' | 'serverPage' | 'ui';
+        uiConfig?: AI_HITL_UIConfig[];
+    };
+    decisions: DecisionOptions[];
+    onlySubmitReplyMessage: boolean;
+}

package/dist/AgentChat/AI_SDK_AIMessage.d.ts

@@ -0,0 +1,25 @@
+import { ChatMessage, ConversationListResult, ExtendedAgentRuntime } from './AIMessage';
+import { default as EventEmitter } from '../utils/EventEmitter';
+
+interface AI_SDK_AIMessageOptions {
+    agent: any;
+    initialUserContexts?: string[];
+}
+export declare class AI_SDK_AIMessage extends EventEmitter implements ExtendedAgentRuntime {
+    agent: any;
+    private abortController;
+    private history;
+    private initialUserMessages;
+    constructor({ agent, initialUserContexts }: AI_SDK_AIMessageOptions);
+    addInitialUserContext(context: string): void;
+    ask(query: string): Promise<void>;
+    clearInitialUserContexts(): void;
+    getConversationDetail(_conversationId: string, _cursor?: string): Promise<ChatMessage[]>;
+    listConversations(_cursor?: string): Promise<ConversationListResult>;
+    reset(): void;
+    setInitialUserContexts(contexts: string[]): void;
+    stop(): void;
+    supportsHistory(): boolean;
+    private toInitialUserMessage;
+}
+export {};

package/dist/AgentChat/AI_SDK_Save_AIMessage.d.ts

@@ -0,0 +1,44 @@
+import { ChatMessage, ConversationListResult, ExtendedAgentRuntime } from './AIMessage';
+import { default as EventEmitter } from '../utils/EventEmitter';
+type Agent = any;
+interface AI_SDK_AIMessageOptions {
+    agent: any;
+    /** 历史接口鉴权维度：app */
+    app?: string;
+    /**
+     * OpenAI 兼容历史接口基地址。
+     * 例如：`http://localhost:8000/openai/v1/chat`
+     */
+    historyEndpoint?: string;
+    /** 会话列表查询数量 */
+    historyLimit?: number;
+    initialUserContexts?: string[];
+    /** 透传给后端的会话元数据，将通过 x-meta 请求头传递 */
+    meta?: Record<string, unknown>;
+    /** 历史接口鉴权维度：user */
+    user?: string;
+}
+export declare class AI_SDK_Save_AIMessage extends EventEmitter implements ExtendedAgentRuntime {
+    agent: Agent;
+    private abortController;
+    private readonly app;
+    private conversationId;
+    private history;
+    private readonly historyEndpoint;
+    private readonly historyLimit;
+    private initialUserMessages;
+    private readonly meta;
+    private readonly user;
+    constructor({ agent, initialUserContexts, historyEndpoint, user, app, meta, historyLimit, }: AI_SDK_AIMessageOptions);
+    addInitialUserContext(context: string): void;
+    ask(query: string): Promise<void>;
+    clearInitialUserContexts(): void;
+    getConversationDetail(conversationId: string, _cursor?: string): Promise<ChatMessage[]>;
+    listConversations(_cursor?: string): Promise<ConversationListResult>;
+    reset(): void;
+    setInitialUserContexts(contexts: string[]): void;
+    stop(): void;
+    supportsHistory(): boolean;
+    private toInitialUserMessage;
+}
+export {};

package/dist/AgentChat/Dify_SDK_AIMessage.d.ts

@@ -0,0 +1,48 @@
+import { ChatMessage, ConversationListResult, ExtendedAgentRuntime } from './AIMessage';
+import { default as DifySDK } from '../utils/DifySDK';
+
+export interface Dify_SDK_AIMessageOptions {
+    /** Dify 服务地址（默认：http://prd.duolaapp.zijinshe.com） */
+    apiBaseUrl?: string;
+    /** Dify 应用 API Key（必填） */
+    apiKey: string;
+    /**
+     * 传递给 Dify 应用的静态 inputs 字段（对应 Dify 应用中定义的变量）。
+     * 每次请求都会合并此对象。
+     */
+    inputs?: Record<string, any>;
+    /** Dify 用户标识（默认：duola_test） */
+    user?: string;
+}
+/**
+ * 基于 DifySDK 实现的 AgentRuntime。
+ *
+ * 继承 DifySDK 的流式请求、会话管理和 EventEmitter 能力，
+ * 同时满足 ChatPanel 的 ExtendedAgentRuntime 接口规范。
+ *
+ * 事件：
+ * - `replyChange(delta, allReply)` — 文本流增量（由 DifySDK 内部触发）
+ * - `stop()` — 请求结束或被中止（由 DifySDK 内部触发）
+ * - `toolCall` — Dify 原生不支持工具调用，此事件不会触发
+ */
+export declare class Dify_SDK_AIMessage extends DifySDK implements ExtendedAgentRuntime {
+    /** 传递给 Dify 的静态 inputs 字段 */
+    private extraInputs;
+    /** 初始用户上下文列表（新会话时拼接到首条消息） */
+    private initialContexts;
+    constructor({ apiKey, apiBaseUrl, user, inputs, }: Dify_SDK_AIMessageOptions);
+    addInitialUserContext(context: string): void;
+    /**
+     * 向 Dify 发起流式对话请求。
+     *
+     * - 新会话（conversation_id 为空）时，将初始上下文拼接到 query 前。
+     * - 流式文本通过继承自 DifySDK 的 `replyChange` 事件推送。
+     * - 请求结束或中止时触发 `stop` 事件。
+     */
+    ask(query: string): Promise<unknown>;
+    clearInitialUserContexts(): void;
+    getConversationDetail(conversationId: string, _cursor?: string): Promise<ChatMessage[]>;
+    listConversations(cursor?: string): Promise<ConversationListResult>;
+    setInitialUserContexts(contexts: string[]): void;
+    supportsHistory(): boolean;
+}