@cloudbase/agent-adapter-wx 0.0.18 → 0.0.19

package/README.md

@@ -5,35 +5,62 @@ WeChat adapter for AG-Kit - Forward LLM messages to WeChat platforms
 ## Features
 
 ✅ **Multi-Platform Support**: WeChat Mini Program, Official Account (Service/Subscription), Enterprise WeChat Customer Service
+✅ **Express Handler**: Ready-to-use `createWxMessageHandler` for Express servers
+✅ **Agent Adapter**: `WeChatAgent` wraps any AG-UI agent with WeChat integration
+✅ **CloudBase History**: `WeChatHistoryManager` with CloudBase database storage
 ✅ **Automatic Token Management**: Built-in caching and refresh mechanism
-✅ **Type-Safe**: Full TypeScript support with Zod validation
-✅ **Simple API**: Easy-to-use interface for sending messages
-✅ **Batch Operations**: Send multiple messages at once
-✅ **Async Support**: Fire-and-forget message sending
+✅ **Type-Safe**: Full TypeScript support
+✅ **Async/Sync Reply**: Supports both sync HTTP response and async message sending
 
 ## Installation
 
 ```bash
 npm install @cloudbase/agent-adapter-wx
 # or
-yarn add @cloudbase/agent-adapter-wx
-# or
 pnpm add @cloudbase/agent-adapter-wx
 ```
 
 ## Quick Start
 
+### Express Server Handler
+
+```typescript
+import express from "express";
+import { createWxMessageHandler, WeChatAgent } from "@cloudbase/agent-adapter-wx";
+
+const app = express();
+app.use(express.json());
+
+// Create handler with agent factory
+const wxHandler = createWxMessageHandler(
+  async ({ request, options }) => {
+    const agent = new WeChatAgent({
+      agent: yourBaseAgent,
+      wechatConfig: {
+        platform: WeChatPlatform.SERVICE,
+        appId: process.env.WECHAT_APP_ID!,
+        appSecret: process.env.WECHAT_APP_SECRET!,
+      },
+    });
+    return { agent };
+  },
+  { logger: console }
+);
+
+app.post("/wx/message", wxHandler);
+```
+
+### Direct Message Sending
+
 ```typescript
 import { WeChatSender, WeChatPlatform } from "@cloudbase/agent-adapter-wx";
 
-// Initialize sender
 const sender = new WeChatSender({
   platform: WeChatPlatform.MINI_APP,
   appId: "your-app-id",
   appSecret: "your-app-secret",
 });
 
-// Send a message
 await sender.send({
   toUser: "user-openid",
   message: {
@@ -43,38 +70,89 @@ await sender.send({
 });
 ```
 
-## Usage Examples
+## Core Components
 
-### Send LLM Response to WeChat
+### createWxMessageHandler
+
+Express route handler for WeChat message webhook. Handles the complete message flow:
+
+1. Parse incoming WeChat message
+2. Validate message type (text/voice)
+3. Handle retry logic for unverified accounts (11-second rule)
+4. Process "继续" command for async replies
+5. Run agent and return response
 
 ```typescript
-import { WeChatSender, WeChatPlatform } from "@cloudbase/agent-adapter-wx";
+import { createWxMessageHandler } from "@cloudbase/agent-adapter-wx";
 
-// Initialize for WeChat Mini Program
-const sender = new WeChatSender({
-  platform: WeChatPlatform.MINI_APP,
-  appId: process.env.WECHAT_APP_ID!,
-  appSecret: process.env.WECHAT_APP_SECRET!,
+const handler = createWxMessageHandler(createAgent, {
+  logger: console, // optional logger
 });
 
-// Get response from any LLM (OpenAI, Claude, etc.)
-const llmResponse = await getLLMResponse("What is the weather today?");
+app.post("/wx/callback", handler);
+```
 
-// Send to WeChat
-await sender.send({
-  toUser: "user-openid",
-  message: {
-    content: llmResponse.content,
-    type: "text",
+**Bot ID Resolution Priority:**
+1. `SCF_FUNCTIONNAME` environment variable
+2. Parsed from request URL via `utils.parseBotId()`
+3. Parsed from `HOSTNAME` environment variable
+4. Fallback: `"agent-id"`
+
+### WeChatAgent
+
+Wraps any AG-UI `AbstractAgent` with WeChat-specific functionality:
+
+```typescript
+import { WeChatAgent, WeChatPlatform, WeChatSendMode } from "@cloudbase/agent-adapter-wx";
+
+const wechatAgent = new WeChatAgent({
+  agent: yourBaseAgent,
+  wechatConfig: {
+    platform: WeChatPlatform.SERVICE,
+    appId: "your-app-id",
+    appSecret: "your-app-secret",
+    sendMode: WeChatSendMode.AITOOLS, // or WeChatSendMode.LOCAL
   },
-  recommendQuestions: [
-    "What about tomorrow?",
-    "Show me the forecast",
-    "Temperature details",
-  ],
+  recommendQuestions: ["Question 1", "Question 2"],
 });
 ```
 
+### WeChatHistoryManager
+
+CloudBase database storage for chat history (singleton pattern):
+
+```typescript
+import { WeChatHistoryManager } from "@cloudbase/agent-adapter-wx";
+
+// Initialize (requires TCB_ENV or CLOUDBASE_ENV)
+const historyManager = WeChatHistoryManager.getInstance({
+  envId: "your-cloudbase-env", // or set TCB_ENV env var
+  collectionName: "wx_chat_history", // default
+  botId: "your-bot-id",
+});
+
+// Save to history
+await historyManager.saveToHistory({
+  messageId: "msg-123",
+  role: "user",
+  content: "Hello",
+  threadId: "conversation-id",
+  createdAt: Date.now(),
+  metadata: {
+    sender: "user-openid",
+    triggerSrc: "WXService",
+  },
+});
+
+// Get previous reply
+const previous = await historyManager.getPreviousReply(
+  "conversation-id",
+  "msg-123"
+);
+```
+
+## Usage Examples
+
 ### Enterprise WeChat Customer Service
 
 ```typescript
@@ -98,124 +176,94 @@ await sender.send({
 ### Batch Sending
 
 ```typescript
-const messages = [
-  {
-    toUser: "user1",
-    message: { content: "Message 1", type: "text" as const },
-  },
-  {
-    toUser: "user2",
-    message: { content: "Message 2", type: "text" as const },
-  },
-];
-
-const results = await sender.sendBatch(messages);
-console.log(results);
-```
-
-### Async Sending (Fire and Forget)
-
-```typescript
-// Send without waiting for response
-sender.sendAsync({
-  toUser: "user-openid",
-  message: {
-    content: "Notification message",
-    type: "text",
-  },
-});
+const results = await sender.sendBatch([
+  { toUser: "user1", message: { content: "Message 1", type: "text" } },
+  { toUser: "user2", message: { content: "Message 2", type: "text" } },
+]);
 ```
 
 ## API Reference
 
-### WeChatSender
-
-#### Constructor
-
-```typescript
-new WeChatSender(config: WeChatConfig)
-```
-
-#### Methods
-
-- `send(options: SendMessageOptions, originMsg?: any): Promise<WeChatAPIResponse>`
-- `sendBatch(messages: SendMessageOptions[]): Promise<WeChatAPIResponse[]>`
-- `sendAsync(options: SendMessageOptions, originMsg?: any): Promise<void>`
-- `clearCache(): void`
-- `getConfig(): WeChatConfig`
-
 ### Types
 
 #### WeChatPlatform
 
 ```typescript
 enum WeChatPlatform {
-  CUSTOM_SERVICE = "WXCustomerService",
-  MINI_APP = "WXMiniapp",
-  SERVICE = "WXService",
-  SUBSCRIPTION = "WXSubscription",
+  CUSTOM_SERVICE = "WXCustomerService", // 企业微信客服
+  MINI_APP = "WXMiniApp",               // 微信小程序
+  SERVICE = "WXService",                // 微信服务号
+  SUBSCRIPTION = "WXSubscription",      // 微信订阅号
 }
 ```
 
-#### WeChatConfig
+#### WeChatSendMode
 
 ```typescript
-interface WeChatConfig {
-  platform: WeChatPlatform;
-  appId: string;
-  appSecret: string;
-  openKfId?: string;
-  tokenCacheTTL?: number; // default: 7200000 (2 hours)
+enum WeChatSendMode {
+  LOCAL = "local",     // Use WeChatSender (local development)
+  AITOOLS = "aitools", // Use aitools SDK (cloud function)
 }
 ```
 
-#### SendMessageOptions
+#### HistoryEntry
 
 ```typescript
-interface SendMessageOptions {
-  toUser: string;
-  message: {
-    content: string;
-    type: "text" | "image" | "event" | "voice";
-    imageUrl?: string;
+interface HistoryEntry {
+  id?: string;
+  messageId: string;
+  role: "user" | "assistant" | "system";
+  content?: string;
+  threadId: string;
+  createdAt: number;
+  botId?: string;
+  runId?: string;
+  needAsyncReply?: boolean;
+  status?: string;
+  type?: string;
+  metadata?: {
+    sender?: string;
+    triggerSrc?: string;
+    originMsg?: string;
+    replyTo?: string;
+    reply?: string;
+    image?: string;
+    recommendQuestions?: string[];
   };
-  recommendQuestions?: string[];
-  msgId?: string;
 }
 ```
 
-## Platform-Specific Notes
+### WeChatSender Methods
 
-### WeChat Mini Program
-- Uses customer service message API
-- Requires user to interact with mini program first
+- `send(options, originMsg?): Promise<WeChatAPIResponse>`
+- `sendBatch(messages): Promise<WeChatAPIResponse[]>`
+- `sendAsync(options, originMsg?): Promise<void>`
+- `clearCache(): void`
 
-### Official Account (Service/Subscription)
-- Uses customer service message API
-- User must follow the account
+### WeChatHistoryManager Methods
 
-### Enterprise WeChat Customer Service
-- Requires `openKfId` configuration
-- Supports message threading with `msgId`
+- `getInstance(config?): WeChatHistoryManager` - Get singleton instance
+- `getPreviousReply(threadId, messageId?): Promise<HistoryEntry | null>`
+- `saveToHistory(record): Promise<void>`
+- `updateContent(threadId, messageId, content): Promise<void>`
 
-## Error Handling
+## Environment Variables
 
-```typescript
-try {
-  await sender.send({
-    toUser: "user-openid",
-    message: { content: "Hello", type: "text" },
-  });
-} catch (error) {
-  console.error("Failed to send message:", error);
-}
-```
-
-## License
+| Variable | Description |
+|----------|-------------|
+| `TCB_ENV` or `CLOUDBASE_ENV` | CloudBase environment ID (required for history) |
+| `SCF_FUNCTIONNAME` | Cloud function name (used as bot ID) |
+| `HOSTNAME` | Container hostname (fallback for bot ID) |
 
-ISC
+## Platform-Specific Notes
 
-## Contributing
+| Platform | Trigger Source | Async Reply |
+|----------|---------------|-------------|
+| Mini Program | `WXMiniApp` | Always async |
+| Service Account | `WXService` | Based on verification |
+| Subscription | `WXSubscription` | Based on verification |
+| Enterprise CS | `WXCustomerService` | Always async |
 
-Contributions are welcome! Please open an issue or submit a pull request.
+## License
 
+ISC

package/dist/index.js

@@ -350,6 +350,20 @@ function createWxMessageHandler(createAgent, options) {
       );
       let skipAI = false;
       let isEnd = false;
+      const isUnverifiedAccount = ["WXSubscription", "WXService"].includes(triggerSrc) && !wxVerify;
+      if (!isUnverifiedAccount) {
+        const existingUserMsg = await agent.getPreviousReply(
+          msgData.conversation,
+          msgData.recordId
+        );
+        if (existingUserMsg) {
+          logger.info?.("[WX] Duplicate callback detected, skipping:", {
+            recordId: msgData.recordId,
+            conversation: msgData.conversation
+          });
+          return res.json({});
+        }
+      }
       const msgType = extractMsgType(callbackData);
       const validation = validateMessageType(msgType);
       if (!validation.isValid) {