@wwlocal/aibot-plugin-node 20260409.20.0

package/dist/esm/types/src/adapters/types.d.ts

@@ -0,0 +1,373 @@
+/**
+ * 可插拔智能体适配器 - 类型定义
+ *
+ * 定义适配器接口规范和相关类型，所有适配器必须实现 AgentAdapter 接口
+ */
+import type { RuntimeLogger, DeliverPayload, DeliverInfo, AgentEndpoint } from "../interface.js";
+/**
+ * 适配器接口 — 所有智能体平台适配器必须实现
+ */
+export interface AgentAdapter {
+    /** 适配器唯一标识（对应配置中的 provider 字段） */
+    readonly name: string;
+    /** 人类可读的显示名称 */
+    readonly displayName: string;
+    /**
+     * 将统一的转发请求转换为平台特定的 HTTP 请求并执行
+     *
+     * @param request  - 标准化的转发请求（文本、媒体、引用等）
+     * @param endpoint - 智能体端点配置（URL、认证、模型等）
+     * @param callbacks - 回调函数集（deliver、onReplyStart、onError）
+     * @returns 最终的完整回复文本
+     */
+    forward(request: AdapterRequest, endpoint: AgentEndpoint, callbacks: AdapterCallbacks): Promise<string>;
+}
+/**
+ * 标准化的适配器请求
+ */
+export interface AdapterRequest {
+    /** 用户消息文本 */
+    text: string;
+    /** 媒体文件列表 */
+    mediaPaths?: Array<{
+        path: string;
+        contentType?: string;
+    }>;
+    /** 引用内容 */
+    quoteContent?: string;
+    /** 中止信号 */
+    abortSignal?: AbortSignal;
+    /** 运行时日志 */
+    runtime?: RuntimeLogger;
+    /** 扩展上下文（适配器可按需使用） */
+    context?: AdapterContext;
+    /** 对话历史消息（用于多轮对话） */
+    historyMessages?: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+}
+/**
+ * 适配器扩展上下文
+ */
+export interface AdapterContext {
+    /** 账号 ID（用于会话隔离，防止多账号历史串联） */
+    accountId?: string;
+    /** 企微用户 ID（用于 Dify 的 user 字段等场景） */
+    userId?: string;
+    /** 企微聊天 ID（用于 Dify 会话管理等场景） */
+    chatId?: string;
+    /** 聊天类型 */
+    chatType?: "single" | "group";
+    /** 其他自定义字段 */
+    [key: string]: unknown;
+}
+/**
+ * 适配器回调集
+ */
+export interface AdapterCallbacks {
+    /** 内容投递回调（中间帧/最终帧） */
+    deliver: (payload: DeliverPayload, info: DeliverInfo) => Promise<void>;
+    /** 首次收到回复时触发 */
+    onReplyStart?: () => Promise<void>;
+    /** 错误回调 */
+    onError?: (err: Error, info: {
+        kind: string;
+    }) => void;
+}
+/** OpenAI 消息格式 */
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string | ChatContentPart[];
+}
+/** 多模态内容部分 */
+export type ChatContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: string;
+    };
+};
+/** OpenAI Chat Completions 请求体 */
+export interface ChatCompletionsRequest {
+    model?: string;
+    messages: ChatMessage[];
+    stream?: boolean;
+    [key: string]: unknown;
+}
+/** SSE 流式响应中的 delta 片段 */
+export interface StreamDelta {
+    choices?: Array<{
+        delta?: {
+            content?: string;
+            role?: string;
+            reasoning_content?: string;
+        };
+        finish_reason?: string | null;
+    }>;
+}
+/** 非流式响应 */
+export interface ChatCompletionsResponse {
+    choices?: Array<{
+        message?: {
+            content?: string;
+            role?: string;
+            reasoning_content?: string;
+        };
+        finish_reason?: string;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+        completion_tokens_details?: {
+            reasoning_tokens?: number;
+        };
+    };
+}
+/** DeepSeek 推理内容展示策略 */
+export type ReasoningDisplayMode = "show" | "hide" | "collapse";
+/** DeepSeek 适配器扩展配置 */
+export interface DeepSeekProviderOptions {
+    /** 推理过程展示策略（默认 collapse） */
+    reasoningDisplay?: ReasoningDisplayMode;
+}
+/** Dify 应用类型 */
+export type DifyAppType = "chat" | "completion" | "workflow";
+/** Dify 适配器扩展配置 */
+export interface DifyProviderOptions {
+    /** Dify 应用类型（默认 chat） */
+    difyAppType?: DifyAppType;
+    /** Dify 应用变量（对应 inputs 参数） */
+    difyInputs?: Record<string, string>;
+    /** 固定用户标识（为空时使用企微 userid） */
+    difyUser?: string;
+    /** 是否在流式中展示 Workflow 节点执行进度（默认 false） */
+    showWorkflowProgress?: boolean;
+}
+/** Dify Chat Messages 请求体 */
+export interface DifyChatRequest {
+    /** 用户输入内容 */
+    query: string;
+    /** 用户标识 */
+    user: string;
+    /** 响应模式：streaming 或 blocking */
+    response_mode: "streaming" | "blocking";
+    /** 会话 ID（多轮对话） */
+    conversation_id?: string;
+    /** 应用变量 */
+    inputs?: Record<string, string>;
+    /** 文件列表 */
+    files?: DifyFile[];
+}
+/** Dify 文件类型 */
+export interface DifyFile {
+    type: "image" | "document" | "audio" | "video" | "custom";
+    transfer_method: "remote_url" | "local_file";
+    url?: string;
+    upload_file_id?: string;
+}
+/** Dify 文件上传响应 */
+export interface DifyFileUploadResponse {
+    id: string;
+    name: string;
+    size: number;
+    extension: string;
+    mime_type: string;
+    created_by: string;
+    created_at: number;
+}
+/** Dify SSE 事件类型 */
+export type DifyEventType = "message" | "message_end" | "message_file" | "message_replace" | "text_chunk" | "text_replace" | "workflow_started" | "workflow_finished" | "node_started" | "node_finished" | "node_retry" | "iteration_started" | "iteration_next" | "iteration_completed" | "loop_started" | "loop_next" | "loop_completed" | "workflow_paused" | "agent_log" | "error" | "ping";
+/** Dify SSE 事件数据 */
+export interface DifySSEEvent {
+    event: DifyEventType;
+    task_id?: string;
+    message_id?: string;
+    conversation_id?: string;
+    /** ChatBot 模式下的文本增量（message / message_replace 事件） */
+    answer?: string;
+    /** Chatflow 模式下的文本片段（text_chunk 事件） */
+    text?: string;
+    created_at?: number;
+    metadata?: {
+        usage?: {
+            prompt_tokens?: number;
+            completion_tokens?: number;
+            total_tokens?: number;
+        };
+    };
+    id?: string;
+    type?: string;
+    belongs_to?: string;
+    url?: string;
+    workflow_run_id?: string;
+    data?: {
+        id?: string;
+        workflow_id?: string;
+        status?: string;
+        outputs?: Record<string, unknown>;
+        error?: string;
+        node_id?: string;
+        node_type?: string;
+        title?: string;
+        index?: number;
+        inputs?: Record<string, unknown>;
+        iteration_id?: string;
+        loop_id?: string;
+        sequence_number?: number;
+        retry_index?: number;
+    };
+    status?: number;
+    code?: string;
+    message?: string;
+}
+/** Anthropic 适配器扩展配置 */
+export interface AnthropicProviderOptions {
+    /** 思维链展示策略（默认 collapse） */
+    reasoningDisplay?: ReasoningDisplayMode;
+    /** Anthropic API 要求必传的 max_tokens（默认 4096） */
+    maxTokens?: number;
+    /** Anthropic API 版本头 anthropic-version（默认 "2023-06-01"） */
+    anthropicVersion?: string;
+    /** 是否使用 x-api-key 头认证（false 时用 Bearer Token，默认 true） */
+    useXApiKey?: boolean;
+}
+/** Anthropic Messages API 请求体 */
+export interface AnthropicMessagesRequest {
+    model: string;
+    messages: AnthropicMessage[];
+    max_tokens: number;
+    stream?: boolean;
+    system?: string;
+    [key: string]: unknown;
+}
+/** Anthropic 消息格式 */
+export interface AnthropicMessage {
+    role: "user" | "assistant";
+    content: string | AnthropicContentBlock[];
+}
+/** Anthropic 内容块 */
+export type AnthropicContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+} | {
+    type: "thinking";
+    thinking: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+};
+/** Anthropic 非流式响应 */
+export interface AnthropicMessagesResponse {
+    id: string;
+    type: "message";
+    role: "assistant";
+    content: AnthropicResponseContentBlock[];
+    model: string;
+    stop_reason: string | null;
+    stop_sequence: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+/** Anthropic 响应内容块 */
+export type AnthropicResponseContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinking";
+    thinking: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+};
+/** Anthropic SSE 事件类型 */
+export type AnthropicSSEEventType = "message_start" | "content_block_start" | "content_block_delta" | "content_block_stop" | "message_delta" | "message_stop" | "ping" | "error";
+/** Anthropic SSE 事件数据 */
+export interface AnthropicSSEEvent {
+    type: AnthropicSSEEventType;
+    /** message_start 事件中的 message 信息 */
+    message?: {
+        id: string;
+        type: string;
+        role: string;
+        model: string;
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+        };
+    };
+    /** content_block_start 事件的内容块序号 */
+    index?: number;
+    /** content_block_start 事件的内容块信息 */
+    content_block?: {
+        type: string;
+        text?: string;
+        thinking?: string;
+    };
+    /** content_block_delta 事件的增量 */
+    delta?: {
+        type: string;
+        text?: string;
+        thinking?: string;
+        partial_json?: string;
+        stop_reason?: string;
+        stop_sequence?: string | null;
+    };
+    /** message_delta 事件的 usage */
+    usage?: {
+        output_tokens: number;
+    };
+    /** error 事件 */
+    error?: {
+        type: string;
+        message: string;
+    };
+}
+/** Webhook 适配器扩展配置 */
+export interface WebhookProviderOptions {
+    /** 请求体模板，支持变量替换 */
+    requestTemplate?: Record<string, unknown>;
+    /** 响应 JSON 中文本内容的字段路径（支持点号嵌套） */
+    responseTextField?: string;
+    /** 流式 SSE 中文本增量的字段路径 */
+    streamEventField?: string;
+    /** 流式结束标记（默认 "[DONE]"） */
+    streamEndMarker?: string;
+    /** HTTP 方法（默认 "POST"） */
+    method?: string;
+}
+/**
+ * 适配器注册表接口
+ */
+export interface IAdapterRegistry {
+    /** 注册适配器 */
+    register(adapter: AgentAdapter): void;
+    /** 按 provider 名称获取适配器 */
+    get(provider: string): AgentAdapter | undefined;
+    /** 列出所有已注册适配器 */
+    list(): AgentAdapter[];
+    /**
+     * 解析并返回适配器
+     * 1. 优先使用 endpoint.provider 指定的适配器
+     * 2. 若 provider 未配置，尝试从 url 自动推断
+     * 3. 兜底使用 openai 适配器
+     */
+    resolve(endpoint: AgentEndpoint): AgentAdapter;
+}

package/dist/esm/types/src/adapters/webhook-adapter.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Webhook 适配器
+ *
+ * 适用于：企业自建的非标准 HTTP API
+ *
+ * 核心机制：通过配置定义请求和响应的字段映射模板，无需编写代码
+ *
+ * 支持的模板变量：
+ * - {{text}} - 用户消息文本
+ * - {{user}} - 用户 ID
+ * - {{chatId}} - 聊天 ID
+ * - {{chatType}} - 聊天类型（single/group）
+ */
+import type { AgentEndpoint } from "../interface.js";
+import { BaseAdapter } from "./base-adapter.js";
+import type { AdapterRequest, AdapterCallbacks } from "./types.js";
+/**
+ * Webhook 适配器
+ */
+export declare class WebhookAdapter extends BaseAdapter {
+    readonly name = "webhook";
+    readonly displayName = "Custom Webhook";
+    /**
+     * 获取 Webhook 配置选项
+     */
+    private getOptions;
+    /**
+     * 转发请求到 Webhook API
+     */
+    forward(request: AdapterRequest, endpoint: AgentEndpoint, callbacks: AdapterCallbacks): Promise<string>;
+    /**
+     * 构建请求体（应用模板变量替换）
+     */
+    private buildRequestBody;
+    /**
+     * 递归应用模板变量替换
+     */
+    private applyTemplate;
+    /**
+     * 从对象中按路径获取值
+     *
+     * @param obj 源对象
+     * @param path 字段路径（如 "data.reply.text"）
+     */
+    private getValueByPath;
+    /**
+     * 处理流式响应
+     */
+    private handleStreamResponse;
+    /**
+     * 处理非流式响应
+     */
+    private handleNonStreamResponse;
+}

package/dist/esm/types/src/agent-forwarder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 智能体转发器（适配器调度层）
+ *
+ * 核心模块，负责：
+ * 1. 根据端点配置解析对应的适配器
+ * 2. 读取对话历史，注入到适配器请求中
+ * 3. 调用适配器执行转发
+ * 4. AI 回复后，将用户消息和 AI 回复保存到对话历史
+ * 5. 通过 deliver 回调驱动 monitor 的流式回复逻辑
+ *
+ * v1.1.0 重构：从 OpenAI 专用转发器改为可插拔适配器调度层
+ * v1.1.1 新增：多轮对话上下文记忆
+ */
+import type { AgentEndpoint, ForwardOptions } from "./interface.js";
+/**
+ * 将企微消息转发到外部智能体
+ *
+ * 完整流程：
+ * 1. 根据 endpoint.provider 解析适配器
+ * 2. 读取对话历史（如果 maxHistoryRounds > 0）
+ * 3. 构建适配器请求（含对话历史）
+ * 4. 调用 adapter.forward() 执行转发
+ * 5. 通过 deliver 回调驱动 monitor 的流式回复
+ * 6. AI 回复完成后，保存本轮对话到历史
+ */
+export declare function forwardToAgent(options: ForwardOptions): Promise<void>;
+/**
+ * 查找并返回匹配的智能体端点
+ */
+export declare function resolveAgentEndpoint(agents: AgentEndpoint[], agentName?: string): AgentEndpoint | undefined;
+export { resolveAdapter, getRegisteredAdapters, adapterRegistry, } from "./adapters/index.js";
+export type { AgentAdapter, AdapterRequest, AdapterCallbacks, AdapterContext, } from "./adapters/index.js";

package/dist/esm/types/src/ca-cert.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 自签名 CA 证书运行时注入模块
+ *
+ * 背景：
+ *   NODE_EXTRA_CA_CERTS 环境变量只在 Node.js 进程启动时读取一次，
+ *   但用户配置 caCert 可能在运行时加载，此时进程已在运行，
+ *   所以不能依赖 NODE_EXTRA_CA_CERTS。
+ *
+ * 原理：
+ *   Node.js 所有 TLS 连接最终都会调用 tls.createSecureContext()，
+ *   我们在这一层做拦截（monkey-patch），将自签名 CA 证书追加到
+ *   每次创建的 TLS 上下文中，从而覆盖全部网络出口。
+ *
+ * 安全性说明：
+ *   - 仅追加 CA 证书，不禁用证书验证
+ *   - 不覆盖系统默认 CA 列表，只在默认列表基础上追加
+ *   - patch 是幂等的，多次调用只生效一次
+ *   - 调用 removeCaCertPatch() 可还原到原始状态
+ *
+ * 副作用：
+ *   patch 是进程全局的，会影响同一进程中所有 TLS 连接。
+ */
+/**
+ * 校验证书文件是否存在且为有效 PEM 格式
+ *
+ * @param certPath - 证书文件的绝对路径
+ * @returns 校验结果
+ */
+export declare function validateCaCertFile(certPath: string): {
+    ok: true;
+    content: string;
+    fullPath: string;
+} | {
+    ok: false;
+    error: string;
+    fullPath: string;
+};
+/**
+ * 将自签名 CA 证书注入到 Node.js 全局 TLS 层
+ *
+ * @param certPath - 证书文件的绝对路径（PEM 格式）
+ * @param logger - 可选的日志函数
+ * @returns true 表示注入成功，false 表示跳过或失败
+ */
+export declare function injectCaCert(certPath: string, logger?: (...args: any[]) => void): boolean;
+/**
+ * 移除 CA 证书的 monkey-patch，还原到 Node.js 原始行为
+ */
+export declare function removeCaCertPatch(logger?: (...args: any[]) => void): void;
+/**
+ * 检查当前是否已注入 CA 证书
+ */
+export declare function isCaCertInjected(): boolean;

package/dist/esm/types/src/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 插件配置加载模块
+ *
+ * 从 JSON 配置文件加载插件配置，校验必填字段，提供合理默认值
+ */
+import type { PluginConfig, AccountConfig, ResolvedAccount } from "./interface.js";
+/**
+ * 从 JSON 文件加载插件配置
+ *
+ * @param configPath - 配置文件路径
+ * @returns 解析后的配置
+ */
+export declare function loadConfig(configPath: string): PluginConfig;
+/**
+ * 解析账号配置，填充默认值，关联智能体端点
+ */
+export declare function resolveAccount(account: AccountConfig, config: PluginConfig): ResolvedAccount;
+/**
+ * 解析所有启用的账号配置
+ */
+export declare function resolveAllAccounts(config: PluginConfig): ResolvedAccount[];
+/**
+ * 打印已加载的适配器列表（启动日志）
+ */
+export declare function logRegisteredAdapters(): void;
+/**
+ * 打印配置的智能体端点信息（启动日志）
+ */
+export declare function logAgentEndpoints(config: PluginConfig): void;

package/dist/esm/types/src/const.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 企业微信私有部署渠道常量定义
+ */
+/**
+ * 渠道 ID
+ */
+export declare const CHANNEL_ID: "wecomserver";
+/**
+ * 企业微信私有部署 WebSocket 命令枚举
+ */
+export declare enum WeComCommand {
+    /** 认证订阅 */
+    SUBSCRIBE = "aibot_subscribe",
+    /** 心跳 */
+    PING = "ping",
+    /** 企业微信推送消息 */
+    AIBOT_CALLBACK = "aibot_callback",
+    /** 响应消息 */
+    AIBOT_RESPONSE = "aibot_response"
+}
+/** 图片下载超时时间（毫秒） */
+export declare const IMAGE_DOWNLOAD_TIMEOUT_MS = 30000;
+/** 文件下载超时时间（毫秒） */
+export declare const FILE_DOWNLOAD_TIMEOUT_MS = 60000;
+/** 消息发送超时时间（毫秒） */
+export declare const REPLY_SEND_TIMEOUT_MS = 15000;
+/** 消息处理总超时时间（毫秒） */
+export declare const MESSAGE_PROCESS_TIMEOUT_MS: number;
+/** WebSocket 心跳间隔（毫秒） */
+export declare const WS_HEARTBEAT_INTERVAL_MS = 30000;
+/** WebSocket 连接断开时的最大重连次数 */
+export declare const WS_MAX_RECONNECT_ATTEMPTS = 10;
+/** WebSocket 认证失败时的最大重试次数 */
+export declare const WS_MAX_AUTH_FAILURE_ATTEMPTS = 5;
+/** messageStates Map 条目的最大 TTL（毫秒），防止内存泄漏 */
+export declare const MESSAGE_STATE_TTL_MS: number;
+/** messageStates Map 清理间隔（毫秒） */
+export declare const MESSAGE_STATE_CLEANUP_INTERVAL_MS = 60000;
+/** messageStates Map 最大条目数 */
+export declare const MESSAGE_STATE_MAX_SIZE = 500;
+/** "思考中"流式消息占位内容 */
+export declare const THINKING_MESSAGE = "<think></think>";
+/** 仅包含图片时的消息占位符 */
+export declare const MEDIA_IMAGE_PLACEHOLDER = "<media:image>";
+/** 仅包含文件时的消息占位符 */
+export declare const MEDIA_DOCUMENT_PLACEHOLDER = "<media:document>";
+/** monitor 层中间帧 deliver 节流：最小发送间隔（毫秒） */
+export declare const MONITOR_DELIVER_THROTTLE_MS = 1000;
+/** monitor 层中间帧 deliver 节流：最少新增字符数才触发 deliver */
+export declare const MONITOR_DELIVER_MIN_DELTA = 30;
+/** 默认媒体大小上限（MB） */
+export declare const DEFAULT_MEDIA_MAX_MB = 5;
+/** 文本分块大小上限 */
+export declare const TEXT_CHUNK_LIMIT = 4000;
+/** 图片大小上限（字节）：10MB */
+export declare const IMAGE_MAX_BYTES: number;
+/** 视频大小上限（字节）：10MB */
+export declare const VIDEO_MAX_BYTES: number;
+/** 语音大小上限（字节）：2MB */
+export declare const VOICE_MAX_BYTES: number;
+/** 文件大小上限（字节）：20MB */
+export declare const FILE_MAX_BYTES: number;
+/** 文件绝对上限（字节）：超过此值无法发送，等于 FILE_MAX_BYTES */
+export declare const ABSOLUTE_MAX_BYTES: number;
+/** 上传分片大小（字节，Base64 编码前）：512KB */
+export declare const UPLOAD_CHUNK_SIZE: number;
+/** 版本检查事件名称（SDK 事件监听用） */
+export declare const EVENT_ENTER_CHECK_UPDATE = "event.enter_check_update";
+/** 版本检查事件回复命令名称 */
+export declare const CMD_ENTER_EVENT_REPLY = "ww_ai_robot_enter_event";
+/** WSClient scene 参数：企微 AI 机器人场景 */
+export declare const SCENE_WECOM_AIBOT = 1;
+/** 合法的模板卡片 card_type 列表 */
+export declare const VALID_CARD_TYPES: string[];

package/dist/esm/types/src/conversation-manager.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 对话历史管理器
+ *
+ * 按 chatId 维护多轮对话的 messages 数组（内存缓存）
+ * - 支持配置最大保留轮数（maxRounds）
+ * - 带 TTL 自动过期（默认 2 小时）
+ * - 带容量上限防止内存泄漏
+ *
+ * 一轮对话 = 一条 user 消息 + 一条 assistant 消息
+ */
+/** 对话历史中的消息 */
+export interface HistoryMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/** 对话管理器配置 */
+export interface ConversationManagerOptions {
+    /** 每个对话最大保留轮数（默认 20 轮 = 40 条消息） */
+    maxRounds?: number;
+    /** 对话过期时间（毫秒，默认 7200000 即 2 小时） */
+    ttlMs?: number;
+    /** 最大缓存对话数（默认 500） */
+    maxConversations?: number;
+}
+export declare class ConversationManager {
+    private cache;
+    private readonly maxRounds;
+    private readonly ttlMs;
+    private readonly maxConversations;
+    constructor(options?: ConversationManagerOptions);
+    /**
+     * 获取指定对话的历史消息
+     *
+     * 返回按时间排列的 user/assistant 消息数组
+     * 如果对话已过期或不存在，返回空数组
+     */
+    getHistory(chatId: string): HistoryMessage[];
+    /**
+     * 添加一条用户消息到对话历史
+     */
+    addUserMessage(chatId: string, content: string): void;
+    /**
+     * 添加一条 AI 回复消息到对话历史
+     */
+    addAssistantMessage(chatId: string, content: string): void;
+    /**
+     * 清除指定对话的历史
+     */
+    clearHistory(chatId: string): void;
+    /**
+     * 清除所有对话历史
+     */
+    clearAll(): void;
+    /**
+     * 获取当前缓存的对话数量（用于调试/监控）
+     */
+    get size(): number;
+    /**
+     * 确保 chatId 对应的条目存在
+     */
+    private ensureEntry;
+    /**
+     * 裁剪消息数量，保留最近 maxRounds 轮
+     *
+     * 一轮 = user + assistant = 2 条消息
+     * 最多保留 maxRounds * 2 条消息
+     */
+    private trimMessages;
+    /**
+     * 淘汰最旧的对话（LRU 策略）
+     */
+    private evictOldest;
+}
+/**
+ * 获取全局对话管理器（懒初始化）
+ */
+export declare function getConversationManager(options?: ConversationManagerOptions): ConversationManager;
+/**
+ * 重置全局对话管理器（用于测试或重新配置）
+ */
+export declare function resetConversationManager(options?: ConversationManagerOptions): ConversationManager;