@cloudbase/agent-adapter-wx 0.0.18

package/dist/index.d.mts

@@ -0,0 +1,700 @@
+import { Request, Response } from 'express';
+import { AbstractAgent, AgentConfig, BaseEvent, RunAgentInput } from '@ag-ui/client';
+import { Observable } from 'rxjs';
+import { WxSendMessageInput, aitools } from '@cloudbase/aiagent-framework';
+import { Logger } from '@cloudbase/agent-shared';
+
+/**
+ * WeChat platform types
+ */
+declare enum WeChatPlatform {
+    /** 企业微信客服 */
+    CUSTOM_SERVICE = "WXCustomerService",
+    /** 微信小程序 */
+    MINI_APP = "WXMiniapp",
+    /** 微信服务号 */
+    SERVICE = "WXService",
+    /** 微信订阅号 */
+    SUBSCRIPTION = "WXSubscription"
+}
+/**
+ * Message types
+ */
+declare enum MessageType {
+    TEXT = "text",
+    IMAGE = "image",
+    EVENT = "event",
+    VOICE = "voice"
+}
+/**
+ * WeChat send mode
+ */
+declare enum WeChatSendMode {
+    /** Use local WeChatSender (for local development) */
+    LOCAL = "local",
+    /** Use aitools SDK (for cloud function environment) */
+    AITOOLS = "aitools"
+}
+interface WeChatConfig {
+    platform: WeChatPlatform;
+    appId: string;
+    appSecret: string;
+    openKfId?: string;
+    tokenCacheTTL?: number;
+    sendMode?: WeChatSendMode;
+    context?: any;
+}
+interface MessageContent {
+    content: string;
+    type: MessageType;
+    imageUrl?: string;
+}
+interface SendMessageOptions {
+    toUser: string;
+    message: MessageContent;
+    recommendQuestions?: string[];
+    msgId?: string;
+}
+interface AccessTokenResponse {
+    access_token: string;
+    expires_in: number;
+    errcode?: number;
+    errmsg?: string;
+}
+interface WeChatAPIResponse {
+    errcode: number;
+    errmsg: string;
+    [key: string]: any;
+}
+interface TokenCacheEntry {
+    accessToken: string;
+    expiresAt: number;
+}
+interface WeChatMessage {
+    touser: string;
+    msgtype: string;
+    text?: {
+        content: string;
+    };
+    image?: {
+        media_id?: string;
+        pic_url?: string;
+    };
+    open_kfid?: string;
+    msgid?: string;
+}
+
+/**
+ * WeChat Message Handler - 微信消息处理工具
+ *
+ * 处理调用模型之前的所有逻辑：
+ * - 消息类型校验
+ * - 内容提取
+ * - 消息数据生成
+ * - 发送者/会话提取
+ */
+
+/**
+ * WeChat message input - 微信公众号/服务号/小程序消息
+ */
+interface WeChatCommonInput {
+    toUserName: string;
+    fromUserName: string;
+    createTime: number;
+    msgType: string;
+    msgId: string;
+    content?: string;
+    mediaId?: string;
+    recognition?: string;
+}
+/**
+ * WeChat Work customer service message input - 企业微信客服消息
+ */
+interface WeChatWorkCommonInput {
+    toUserName?: string;
+    externalUserId: string;
+    openKfId: string;
+    msgType: string;
+    msgId: string;
+    sendTime: number;
+    text?: {
+        content: string;
+    };
+    voice?: {
+        mediaId: string;
+    };
+}
+/**
+ * Supported trigger sources - 支持的触发源
+ */
+type WeChatTriggerSrc = WeChatPlatform.SUBSCRIPTION | WeChatPlatform.SERVICE | WeChatPlatform.MINI_APP | WeChatPlatform.CUSTOM_SERVICE;
+/**
+ * Supported message types - 支持的消息类型
+ */
+declare const SUPPORTED_MSG_TYPES: readonly ["text", "voice"];
+type SupportedMsgType = (typeof SUPPORTED_MSG_TYPES)[number];
+/**
+ * Chat history record - 聊天历史记录
+ */
+interface ChatHistoryRecord {
+    recordId: string;
+    botId: string;
+    conversation: string;
+    role: "user" | "assistant";
+    content: string;
+    type: string;
+    triggerSrc: string;
+    sender: string;
+    needAsyncReply: boolean;
+    reply: string;
+    originMsg: string;
+    recommendQuestions: string[];
+    createdAt: number;
+    image?: string;
+    status?: string;
+    traceId?: string;
+    asyncReply?: string;
+    replyTo?: string;
+    event?: string;
+}
+/**
+ * Processed message data - 处理后的消息数据
+ */
+interface ProcessedMsgData {
+    msgData: ChatHistoryRecord;
+    replyMsgData: ChatHistoryRecord;
+}
+/**
+ * Message validation result - 消息校验结果
+ */
+interface MessageValidationResult {
+    isValid: boolean;
+    skipAI: boolean;
+    errorMessage?: string;
+    userErrorMessage?: string;
+}
+/**
+ * Voice message handler type - 语音消息处理器类型
+ */
+type VoiceMessageHandler = (botId: string, triggerSrc: string, mediaId: string) => Promise<{
+    content: string;
+} | null>;
+/**
+ * Validate message type - 校验消息类型
+ */
+declare function validateMessageType(msgType: string): MessageValidationResult;
+/**
+ * Extract message type from origin message - 从原始消息提取消息类型
+ */
+declare function extractMsgType(originMsg: any): string;
+/**
+ * Extract trigger source from origin message - 从原始消息提取触发源
+ */
+declare function extractTriggerSrc(originMsg: any, defaultSrc?: WeChatTriggerSrc): WeChatTriggerSrc;
+/**
+ * Extract text content from WeChat message - 从微信消息提取文本内容
+ */
+declare function extractTextContent(originMsg: any, triggerSrc: WeChatTriggerSrc): string;
+/**
+ * Extract voice media ID from WeChat message - 从微信消息提取语音媒体ID
+ */
+declare function extractVoiceMediaId(originMsg: any, triggerSrc: WeChatTriggerSrc): string;
+/**
+ * Get content from WeChat message (text or voice) - 获取微信消息内容
+ */
+declare function getWxChatContent(originMsg: any, triggerSrc: WeChatTriggerSrc, voiceMessageHandler?: VoiceMessageHandler, botId?: string): Promise<string>;
+/**
+ * Extract sender from origin message - 从原始消息提取发送者
+ */
+declare function extractSender(originMsg: any, triggerSrc: WeChatTriggerSrc): string;
+/**
+ * Extract conversation ID from origin message - 从原始消息提取会话ID
+ */
+declare function extractConversation(originMsg: any, triggerSrc: WeChatTriggerSrc): string;
+/**
+ * Generate record ID - 生成记录ID
+ */
+declare function generateRecordId(triggerSrc: WeChatTriggerSrc, msgId: string, timestamp: number): string;
+/**
+ * Extract message ID from origin message - 从原始消息提取消息ID
+ */
+declare function extractMsgId(originMsg: any): string;
+/**
+ * Extract timestamp from origin message - 从原始消息提取时间戳
+ */
+declare function extractTimestamp(originMsg: any, triggerSrc: WeChatTriggerSrc): number;
+/**
+ * Determine if async reply is needed - 判断是否需要异步回复
+ */
+declare function needAsyncReply(triggerSrc: WeChatTriggerSrc, wxVerify: boolean): boolean;
+/**
+ * WeChat reply message structure
+ */
+interface WeChatReplyMessage {
+    toUserName: string;
+    fromUserName: string;
+    createTime: number;
+    msgType: string;
+    content: string;
+    msgId: string;
+    openKfId?: string;
+}
+/**
+ * Format reply message for WeChat
+ * Used for both sync HTTP response and async aitools sending
+ */
+declare function formatWeChatReplyMessage(callbackData: any, triggerSrc: string, content: string): WeChatReplyMessage;
+/**
+ * Deal message data - 处理微信消息，生成 msgData 和 replyMsgData
+ * 完整实现原 chat_wx.service.ts 中的 dealMsgData 逻辑
+ */
+declare function dealMsgData(originMsg: WxSendMessageInput["callbackData"], triggerSrc: WeChatTriggerSrc, wxVerify: boolean, botId: string): ProcessedMsgData;
+/**
+ * Handle WeChat retry for unverified accounts (11-second rule)
+ * 处理未认证账号的微信重试逻辑（11秒规则）
+ */
+declare function handleWeChatRetry(previousReply: HistoryEntry | null, originMsg: any, triggerSrc: WeChatTriggerSrc): Promise<{
+    shouldSkip: boolean;
+    content?: string;
+}>;
+/**
+ * Check if "继续" command is within 5-minute timeout
+ * 检查"继续"命令是否在5分钟超时内
+ */
+declare function isContinueCommandValid(previousReply: HistoryEntry | null): boolean;
+
+/**
+ * WeChat Chat History Manager
+ * Manages chat history for "continue" command and retry logic
+ * Uses CloudBase database storage
+ */
+
+/**
+ * Message role type
+ */
+type MessageRole = "user" | "assistant" | "system";
+/**
+ * Metadata for history entry (stored in metadata field)
+ */
+interface HistoryEntryMetadata {
+    /** Sender identifier */
+    sender?: string;
+    /** Trigger source (WXSubscription, WXService, etc.) */
+    triggerSrc?: string;
+    /** Original message data */
+    originMsg?: string;
+    /** Reply to message ID */
+    replyTo?: string;
+    /** Reply message ID */
+    reply?: string;
+    /** Image URL if applicable */
+    image?: string;
+    /** Recommended questions */
+    recommendQuestions?: string[];
+}
+/**
+ * History entry for storage
+ * Contains message info plus optional metadata
+ */
+interface HistoryEntry {
+    id?: string;
+    /** Unique message ID (record_id in database) */
+    messageId: string;
+    /** Message role: user, assistant, or system */
+    role: MessageRole;
+    /** Message content */
+    content?: string;
+    /** Thread/Conversation ID */
+    threadId: string;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Bot ID */
+    botId?: string;
+    /** Run ID for tracking agent runs */
+    runId?: string;
+    /** Whether async reply is needed (WeChat specific) */
+    needAsyncReply?: boolean;
+    /** Message status: pending, done, error, cancel */
+    status?: string;
+    /** Message type */
+    type?: string;
+    /** Additional metadata */
+    metadata?: HistoryEntryMetadata;
+}
+interface HistoryManagerConfig {
+    /** CloudBase environment ID */
+    envId?: string;
+    /** CloudBase secret ID */
+    secretId?: string;
+    /** CloudBase secret key */
+    secretKey?: string;
+    /** CloudBase session token */
+    token?: string;
+    /** Collection name, default: wx_chat_history */
+    collectionName?: string;
+    /** Bot ID for filtering */
+    botId?: string;
+}
+/**
+ * WeChat History Manager
+ * Uses CloudBase database storage
+ * Singleton pattern for shared history across adapter and controller
+ */
+declare class WeChatHistoryManager {
+    private static instance;
+    private tcbClient;
+    private collectionName;
+    private botId;
+    private collectionReady;
+    private constructor();
+    static getInstance(config?: HistoryManagerConfig): WeChatHistoryManager;
+    /**
+     * Ensure collection exists, create if not
+     */
+    private ensureCollection;
+    /**
+     * Get previous reply from history
+     */
+    getPreviousReply(threadId: string, messageId?: string | null): Promise<HistoryEntry | null>;
+    /**
+     * Save record to history
+     */
+    saveToHistory(record: HistoryEntry): Promise<void>;
+    /**
+     * Update record content by messageId
+     */
+    updateContent(_threadId: string, messageId: string, content: string): Promise<void>;
+}
+declare const getHistoryManager: typeof WeChatHistoryManager.getInstance;
+
+/**
+ * Configuration for WeChat Agent Adapter
+ */
+interface WeChatAgentConfig extends AgentConfig {
+    /**
+     * The underlying agent to wrap
+     */
+    agent: AbstractAgent;
+    /**
+     * WeChat configuration
+     */
+    wechatConfig: WeChatConfig;
+    /**
+     * Optional: Custom message formatter
+     * Converts agent output to WeChat message format
+     */
+    messageFormatter?: (content: string, event: BaseEvent) => SendMessageOptions;
+    /**
+     * Optional: Filter which events should trigger WeChat messages
+     * Default: only TEXT_MESSAGE_CONTENT events
+     */
+    eventFilter?: (event: BaseEvent) => boolean;
+    /**
+     * Optional: Recommended questions to show after reply
+     */
+    recommendQuestions?: string[];
+    /**
+     * Optional: History manager for saving chat history
+     * If not provided, will use singleton instance
+     */
+    historyManager?: WeChatHistoryManager;
+}
+interface IWxRunAgentInput extends RunAgentInput {
+    forwardedProps: {
+        wxSendmessageInput: WxSendMessageInput;
+        /** Full user message data from dealMsgData */
+        msgData?: {
+            recordId: string;
+            botId: string;
+            conversation: string;
+            role: "user" | "assistant";
+            content: string;
+            type: string;
+            triggerSrc: string;
+            sender: string;
+            needAsyncReply: boolean;
+            reply: string;
+            originMsg: string;
+            recommendQuestions: string[];
+            createdAt: number;
+        };
+        /** Reply metadata for assistant message */
+        replay: {
+            id: string;
+            botId: string;
+            conversation: string;
+            role: "user" | "assistant";
+            content: string;
+            type: string;
+            triggerSrc: string;
+            sender: string;
+            needAsyncReply: boolean;
+            reply: string;
+            originMsg: string;
+            recommendQuestions: string[];
+            createdAt: number;
+        };
+    };
+}
+/**
+ * WeChat Agent Adapter
+ *
+ * Wraps any AbstractAgent and automatically sends its output to WeChat.
+ * All methods are proxied to the underlying agent, with the run() method
+ * enhanced to capture messages and send them via WeChat.
+ *
+ * @example
+ * ```typescript
+ * const myAgent = new SomeAgent({ ... });
+ * const wechatAgent = new WeChatAgentAdapter({
+ *   agent: myAgent,
+ *   wechatConfig: {
+ *     platform: 'work',
+ *     corpId: 'xxx',
+ *     corpSecret: 'xxx'
+ *   }
+ * });
+ *
+ * // Use it like any other agent
+ * wechatAgent.run(input).subscribe(event => {
+ *   // Events are emitted normally
+ *   // AND automatically sent to WeChat
+ * });
+ * ```
+ */
+declare class WeChatAgent extends AbstractAgent {
+    private wrappedAgent;
+    private wechatSender?;
+    private wechatConfig;
+    private _historyManager;
+    private messageFormatter;
+    private eventFilter;
+    private messageBuffer;
+    private recommendQuestions?;
+    aitools?: aitools.AITools;
+    constructor(config: WeChatAgentConfig);
+    /**
+     * Last assembled reply content after run() completes
+     * Controller can read this instead of re-assembling from events
+     */
+    lastReply: string;
+    /**
+     * Whether last run had an error
+     */
+    lastRunHadError: boolean;
+    /**
+     * Get previous reply from history
+     * Used for: retry detection, "继续" command
+     */
+    getPreviousReply(conversation: string, recordId?: string | null): Promise<HistoryEntry | null>;
+    /**
+     * Update message content in history
+     */
+    updateHistoryContent(messageId: string, content: string, threadId: string): Promise<void>;
+    /**
+     * Handle unverified account logic (WXSubscription/WXService)
+     * Handles "继续" command and 11-second retry
+     * Uses existing functions from wechat-message-handler.ts
+     * @returns { needSkipAI, replyContent, isEnd }
+     */
+    handleUnverifiedChat(params: {
+        content: string;
+        conversation: string;
+        previousReply: HistoryEntry | null;
+        callbackData: WxSendMessageInput;
+        triggerSrc: string;
+    }): Promise<{
+        needSkipAI: boolean;
+        replyContent: string;
+        isEnd: boolean;
+    }>;
+    /**
+     * Run method with WeChat integration
+     * Wraps the underlying agent's run() and sends messages to WeChat
+     */
+    run(input: IWxRunAgentInput): Observable<BaseEvent>;
+    /**
+     * Save input message to history at the start of run()
+     * Only saves if the last message is from user role
+     * Uses msgData from forwardedProps for complete data (similar to dealMsgData)
+     */
+    private saveInputToHistory;
+    /**
+     * Handle WeChat message sending based on events
+     */
+    private handleWeChatSending;
+    /**
+     * Send message to WeChat and save to history
+     * Only sends in async mode (needAsyncReply=true)
+     * For sync mode, message is returned via HTTP response by controller
+     */
+    private sendToWeChat;
+    /**
+     * Save reply content to history
+     * Uses replay metadata from forwardedProps for complete data (similar to dealMsgData)
+     */
+    private saveReplyToHistory;
+    /**
+     * Send message via aitools SDK (for cloud function environment)
+     */
+    private sendViaAITools;
+    /**
+     * Format reply message for WeChat HTTP response (sync mode)
+     * Public method for controller to use
+     */
+    formatReplyMessage(callbackData: any, triggerSrc: string, content: string): WeChatReplyMessage;
+    /**
+     * Process reply message to get correct format for different WeChat platforms
+     * Based on chat_wx.service.ts processReplyMsg implementation
+     */
+    private processReplyMsg;
+    /**
+     * Send message via local WeChatSender (for local development)
+     */
+    private sendViaLocalSender;
+}
+
+/**
+ * WeChat Message Controller
+ * Using @cloudbase/agent-adapter-wx for message processing
+ * Directly using sendMessageAGUI handler from @cloudbase/agent-server
+ */
+
+/**
+ * Agent creator function return type
+ */
+interface AgentCreatorResult {
+    agent: AbstractAgent | WeChatAgent | {
+        toAGUIAgent(): AbstractAgent;
+    };
+    cleanup?: () => void;
+}
+/**
+ * Agent creator function type
+ */
+type AgentCreator = (params: {
+    request: Request;
+    options?: {
+        agentId: string;
+    };
+}) => AgentCreatorResult | Promise<AgentCreatorResult>;
+/**
+ * Handler options
+ */
+interface WxMessageHandlerOptions {
+    logger?: Logger;
+}
+/**
+ * Create WeChat message handler
+ * Directly using sendMessageAGUI.handler from @cloudbase/agent-server
+ * Aligned with chat_wx_v2.service.ts logic
+ *
+ * @param createAgent - Function to create agent instance (returns { agent, cleanup?})
+ * @param options - Handler options
+ * @returns Express route handler
+ */
+declare function createWxMessageHandler(createAgent: AgentCreator, options?: WxMessageHandlerOptions): (req: Request, res: Response) => Promise<Response>;
+
+/**
+ * Main WeChat sender class
+ * Provides a simple API to send LLM messages to WeChat platforms
+ */
+declare class WeChatSender {
+    private config;
+    private tokenManager;
+    private messageFormatter;
+    private platformRouter;
+    constructor(config: WeChatConfig);
+    /**
+     * Send a message to WeChat
+     */
+    send(options: SendMessageOptions, originMsg?: any): Promise<WeChatAPIResponse>;
+    /**
+     * Send multiple messages in batch
+     */
+    sendBatch(messages: SendMessageOptions[]): Promise<WeChatAPIResponse[]>;
+    /**
+     * Send message asynchronously (fire and forget)
+     */
+    sendAsync(options: SendMessageOptions, originMsg?: any): Promise<void>;
+    /**
+     * Clear token cache
+     */
+    clearCache(): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): WeChatConfig;
+}
+
+/**
+ * Token manager for WeChat access tokens
+ * Handles token caching and automatic refresh
+ */
+declare class TokenManager {
+    private cache;
+    /**
+     * Get access token (with caching)
+     */
+    getAccessToken(config: WeChatConfig): Promise<string>;
+    /**
+     * Fetch access token from WeChat API
+     */
+    private fetchAccessToken;
+    /**
+     * Get token URL based on platform
+     */
+    private getTokenUrl;
+    /**
+     * Generate cache key
+     */
+    private getCacheKey;
+    /**
+     * Clear token cache
+     */
+    clearCache(config?: WeChatConfig): void;
+}
+
+/**
+ * Message formatter for different WeChat platforms
+ */
+declare class MessageFormatter {
+    /**
+     * Format message for WeChat API
+     */
+    formatMessage(options: SendMessageOptions, platform: WeChatPlatform, originMsg?: any): WeChatMessage;
+    /**
+     * Append recommended questions to content
+     */
+    private withRecommendQuestions;
+    /**
+     * Split long message into chunks
+     */
+    splitLongMessage(content: string, maxLength?: number): string[];
+}
+
+/**
+ * Platform router for sending messages to different WeChat platforms
+ */
+declare class PlatformRouter {
+    private tokenManager;
+    constructor(tokenManager: TokenManager);
+    /**
+     * Send message to WeChat platform
+     */
+    send(message: WeChatMessage, config: WeChatConfig): Promise<WeChatAPIResponse>;
+    /**
+     * Send to Enterprise WeChat Customer Service
+     */
+    private sendToCustomService;
+    /**
+     * Send to WeChat Mini Program
+     */
+    private sendToMiniApp;
+    /**
+     * Send to WeChat Official Account (Service/Subscription)
+     */
+    private sendToOfficialAccount;
+}
+
+export { type AccessTokenResponse, type ChatHistoryRecord, type HistoryEntry, type HistoryManagerConfig, type MessageContent, MessageFormatter, MessageType, type MessageValidationResult, PlatformRouter, type ProcessedMsgData, SUPPORTED_MSG_TYPES, type SendMessageOptions, type SupportedMsgType, type TokenCacheEntry, TokenManager, type VoiceMessageHandler, type WeChatAPIResponse, WeChatAgent, type WeChatAgentConfig, type WeChatCommonInput, type WeChatConfig, WeChatHistoryManager, type WeChatMessage, WeChatPlatform, type WeChatReplyMessage, WeChatSendMode, WeChatSender, type WeChatTriggerSrc, type WeChatWorkCommonInput, createWxMessageHandler, dealMsgData, extractConversation, extractMsgId, extractMsgType, extractSender, extractTextContent, extractTimestamp, extractTriggerSrc, extractVoiceMediaId, formatWeChatReplyMessage, generateRecordId, getHistoryManager, getWxChatContent, handleWeChatRetry, isContinueCommandValid, needAsyncReply, validateMessageType };