@zhin.js/adapter-wechat-mp 1.0.1 → 1.1.2

package/lib/webhook.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WeChat MP webhook HTTP: URL verification + inbound message handling.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
+export interface WeChatMpWebhookHandler {
+    readonly config: ResolvedWeChatMpConfig;
+    readonly isOpen: boolean;
+    readonly id: CapabilityId;
+    admit(msg: WeChatMessage): void | Promise<unknown>;
+    /** MsgId 去重缓存（可选；实现见 WeChatMpEndpoint）。 */
+    getCachedReply?(msgId: string): string | undefined;
+    cacheReply?(msgId: string, replyXML: string): void;
+}
+export declare function registerWeChatMpWebhookRoutes(http: HttpHost, handler: WeChatMpWebhookHandler): HttpRouteRegistration[];
+export declare function handleWeChatMpVerification(_request: IncomingMessage, response: ServerResponse, url: URL, config: ResolvedWeChatMpConfig): void;
+export declare function handleWeChatMpMessage(request: IncomingMessage, response: ServerResponse, url: URL, handler: WeChatMpWebhookHandler): Promise<void>;
+export declare function collectPassiveReply(handler: WeChatMpWebhookHandler, wechatMsg: WeChatMessage): Promise<string>;

package/lib/webhook.js

@@ -0,0 +1,152 @@
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { getPassiveReplyCapture, runWithPassiveReplyCapture, } from './passive-reply.js';
+import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, verifySignature, wechatMpInboundConversation, } from './protocol.js';
+const logger = getLogger('wechat-mp');
+export function registerWeChatMpWebhookRoutes(http, handler) {
+    const path = handler.config.path;
+    return [
+        http.route('GET', path, (request, response, url) => {
+            handleWeChatMpVerification(request, response, url, handler.config);
+        }, { summary: 'WeChat MP URL verification', tags: ['wechat-mp'] }),
+        http.route('POST', path, async (request, response, url) => {
+            await handleWeChatMpMessage(request, response, url, handler);
+        }, { summary: 'WeChat MP inbound webhook', tags: ['wechat-mp'] }),
+    ];
+}
+export function handleWeChatMpVerification(_request, response, url, config) {
+    const signature = queryParam(url.searchParams.get('signature'));
+    const msgSignature = queryParam(url.searchParams.get('msg_signature'));
+    const timestamp = queryParam(url.searchParams.get('timestamp'));
+    const nonce = queryParam(url.searchParams.get('nonce'));
+    const echostr = normalizeEchostrParam(queryParam(url.searchParams.get('echostr')));
+    const secureMode = !!(config.encrypt && config.encodingAESKey);
+    const signToCheck = msgSignature || signature;
+    const signPayload = msgSignature
+        ? { signature: msgSignature, timestamp, nonce, echostr }
+        : { signature, timestamp, nonce };
+    if (!signToCheck || !timestamp || !nonce) {
+        response.writeHead(403, { 'Content-Type': 'text/plain' });
+        response.end('Forbidden');
+        return;
+    }
+    if (!verifySignature(config.token, signPayload)) {
+        const expected = computeSignatureHash(config.token, {
+            timestamp,
+            nonce,
+            ...(msgSignature ? { echostr } : {}),
+        });
+        logger.error(formatCompact({
+            op: 'verify',
+            stage: 'sign',
+            ok: false,
+            expectedPrefix: expected.slice(0, 8),
+            gotPrefix: signToCheck.slice(0, 8),
+        }));
+        response.writeHead(403, { 'Content-Type': 'text/plain' });
+        response.end('Forbidden');
+        return;
+    }
+    let body = echostr;
+    if (secureMode && echostr && isEncryptedEchostr(echostr) && config.encodingAESKey) {
+        try {
+            body = decryptEchostr(echostr, config.encodingAESKey, config.appId);
+        }
+        catch (error) {
+            logger.error(formatCompact({
+                op: 'verify',
+                stage: 'decrypt',
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            response.writeHead(403, { 'Content-Type': 'text/plain' });
+            response.end('Forbidden');
+            return;
+        }
+    }
+    response.writeHead(200, { 'Content-Type': 'text/plain' });
+    response.end(body);
+}
+export async function handleWeChatMpMessage(request, response, url, handler) {
+    try {
+        const config = handler.config;
+        const signature = queryParam(url.searchParams.get('signature'));
+        const timestamp = queryParam(url.searchParams.get('timestamp'));
+        const nonce = queryParam(url.searchParams.get('nonce'));
+        const msgSignature = queryParam(url.searchParams.get('msg_signature'));
+        const encryptType = queryParam(url.searchParams.get('encrypt_type'));
+        if (!verifySignature(config.token, { signature, timestamp, nonce })) {
+            logger.error('Invalid signature');
+            response.writeHead(403, { 'Content-Type': 'text/plain' });
+            response.end('Forbidden');
+            return;
+        }
+        let xmlString = await readTextBody(request);
+        if (config.encrypt && encryptType === 'aes' && config.encodingAESKey) {
+            xmlString = await decryptMessage(xmlString, msgSignature, timestamp, nonce, config.token, config.encodingAESKey, config.appId);
+        }
+        const wechatMessage = await parseXMLMessage(xmlString);
+        if (!wechatMessage) {
+            response.writeHead(200, { 'Content-Type': 'text/plain' });
+            response.end('success');
+            return;
+        }
+        // 微信 5s 重推去重：同一 MsgId 直接回放首次回复，避免二次 admit。
+        const msgId = wechatMessage.MsgId;
+        if (msgId && handler.getCachedReply) {
+            const cached = handler.getCachedReply(msgId);
+            if (cached !== undefined) {
+                logger.debug(formatCompact({ op: 'wechat_mp_dedup_replay', msgId }));
+                response.writeHead(200, { 'Content-Type': cached ? 'text/xml' : 'text/plain' });
+                response.end(cached || 'success');
+                return;
+            }
+        }
+        let replyXML = resolveEventPassiveReply(wechatMessage);
+        if (!replyXML && handler.isOpen) {
+            if (config.replyMode === 'passive') {
+                replyXML = await collectPassiveReply(handler, wechatMessage);
+            }
+            else {
+                handler.admit(wechatMessage);
+            }
+        }
+        const encryptReply = !!(replyXML
+            && config.encodingAESKey
+            && encryptType === 'aes'
+            && config.encryptMode === 'secure');
+        if (encryptReply && config.encodingAESKey) {
+            replyXML = encryptMessage(replyXML, config.token, config.encodingAESKey, config.appId, timestamp);
+        }
+        if (msgId && handler.cacheReply) {
+            handler.cacheReply(msgId, replyXML || '');
+        }
+        response.writeHead(200, { 'Content-Type': 'text/xml' });
+        response.end(replyXML || 'success');
+    }
+    catch (error) {
+        logger.error('Error handling WeChat message:', error);
+        response.writeHead(200, { 'Content-Type': 'text/plain' });
+        response.end('success');
+    }
+}
+export async function collectPassiveReply(handler, wechatMsg) {
+    const timeoutMs = handler.config.passiveReplyTimeoutMs;
+    const text = await runWithPassiveReplyCapture(async () => {
+        const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
+        await Promise.race([
+            Promise.resolve(handler.admit(wechatMsg)),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+        return getPassiveReplyCapture()?.text ?? null;
+    });
+    if (!text) {
+        logger.warn(formatCompact({
+            op: 'passive_reply',
+            ok: false,
+            reason: 'timeout_or_empty',
+            timeoutMs,
+        }));
+        return '';
+    }
+    return buildTextReply(wechatMsg, text);
+}

package/lib/wechat-mp-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const wechatMpRuntimeStateToken: import("zhin.js").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/wechat-mp-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * WeChat MP 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `wechat-mp endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+export const wechatMpRuntimeStateToken = defineEndpointRuntimeStateToken('wechat-mp');

package/package.json

@@ -1,26 +1,42 @@
 {
   "name": "@zhin.js/adapter-wechat-mp",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "type": "module",
-  "description": "Zhin.js adapter for WeChat Official Account (微信公众号)",
+  "description": "Zhin.js WeChat Official Account adapter for Plugin Runtime (HTTP webhook)",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "dependencies": {
+    "axios": "^1.19.0",
     "xml2js": "^0.6.2",
-    "axios": "^1.17.0",
-    "form-data": "^4.0.0"
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/skill": "1.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "@zhin.js/host-http": "^1.1.1",
+    "zhin.js": "^1.1.2"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "zhin.js": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/koa": "^3.0.3",
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.2",
     "@types/xml2js": "^0.4.14",
     "typescript": "^6.0.3",
-    "@zhin.js/host-router": "1.0.1",
-    "zhin.js": "2.0.1"
+    "vitest": "^4.1.10",
+    "zhin.js": "1.1.2"
   },
   "keywords": [
     "zhin",
@@ -46,6 +62,10 @@
     "directory": "plugins/adapters/wechat-mp"
   },
   "files": [
+    "adapters",
+    "commands",
+    "plugin.js",
+    "schema.json",
     "src",
     "lib",
     "skills",
@@ -63,9 +83,34 @@
       "import": "./lib/index.js"
     }
   },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "pnpm build:node",
+    "build": "tsc",
     "clean": "rimraf lib",
-    "build:node": "tsc"
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/wechat-mp/tests"
   }
 }

package/plugin.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from 'zhin.js/adapter';
+import { definePlugin } from 'zhin.js';
+import { wechatMpRuntimeStateToken } from "./lib/wechat-mp-runtime-state.js";
+export default definePlugin({
+    name: 'wechat-mp',
+    metadata: {
+        displayName: 'WeChat Official Account Adapter',
+    },
+    setup(context) {
+        // 运行中 endpoint 注册表（wechat-mp endpoint list 的"运行中"数据源）
+        context.resources.provide(wechatMpRuntimeStateToken, createEndpointRuntimeState());
+    },
+});

package/schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "path": {
+      "type": "string",
+      "default": "/wechat/webhook"
+    },
+    "encrypt": {
+      "type": "boolean",
+      "default": false
+    },
+    "encryptMode": {
+      "type": "string",
+      "enum": [
+        "plain",
+        "compatible",
+        "secure"
+      ],
+      "description": "Default follows encrypt: 'plain' when encrypt=false, 'compatible' when encrypt=true"
+    },
+    "replyMode": {
+      "type": "string",
+      "enum": [
+        "passive",
+        "customer_service"
+      ],
+      "default": "passive"
+    },
+    "passiveReplyTimeoutMs": {
+      "type": "number",
+      "default": 4500
+    },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（WeChat OpenID；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted WeChat OpenID"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
+    "endpoints": {
+      "type": "array",
+      "minItems": 1,
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（WeChat OpenID）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted WeChat OpenID"
+            },
+            "description": "本 endpoint 的 trusted 列表"
+          },
+          "appId": {
+            "type": "string",
+            "description": "WeChat MP app ID"
+          },
+          "appSecret": {
+            "type": "string",
+            "description": "WeChat MP app secret"
+          },
+          "token": {
+            "type": "string",
+            "description": "WeChat MP callback token"
+          },
+          "encodingAESKey": {
+            "type": "string",
+            "description": "WeChat MP encoding AES key"
+          },
+          "path": {
+            "type": "string"
+          },
+          "encrypt": {
+            "type": "boolean"
+          },
+          "encryptMode": {
+            "type": "string",
+            "enum": [
+              "plain",
+              "compatible",
+              "secure"
+            ]
+          },
+          "replyMode": {
+            "type": "string",
+            "enum": [
+              "passive",
+              "customer_service"
+            ]
+          },
+          "passiveReplyTimeoutMs": {
+            "type": "number"
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string",
+            "description": "WeChat MP bot name"
+          }
+        },
+        "required": [
+          "id",
+          "appId",
+          "appSecret",
+          "token"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+    }
+  },
+  "required": [
+    "endpoints"
+  ]
+}

package/src/client.ts

@@ -0,0 +1,121 @@
+import type {
+  ResolvedWeChatMpConfig,
+  TokenResponse,
+  WeChatAPIResponse,
+} from './protocol.js';
+import type { WeChatMediaUploadResult } from './media-upload.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+
+export type WeChatMpFetch = (
+  url: string,
+  init?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: Record<string, string>;
+  },
+) => Promise<{ readonly data: unknown }>;
+
+/** Direct WeChat Official Account API client exposed to plugins. */
+export class WeChatMpClient {
+  #accessToken: string | null = null;
+  #tokenExpireTime = 0;
+
+  constructor(
+    readonly config: ResolvedWeChatMpConfig,
+    readonly fetch: WeChatMpFetch,
+  ) {}
+
+  get accessToken(): string | null {
+    return this.#accessToken;
+  }
+
+  get tokenExpired(): boolean {
+    return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+  }
+
+  async refreshAccessToken(): Promise<string> {
+    const { appId, appSecret } = this.config;
+    const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
+    const response = await this.fetch(url);
+    const data = response.data as TokenResponse & WeChatAPIResponse;
+    if (!data.access_token) {
+      throw new Error(data.errmsg
+        ? `Failed to get access token: ${data.errcode} ${data.errmsg}`
+        : 'Failed to get access token');
+    }
+    this.#accessToken = data.access_token;
+    this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
+    return data.access_token;
+  }
+
+  async request<T = unknown>(
+    path: string,
+    init?: Parameters<WeChatMpFetch>[1],
+  ): Promise<T> {
+    if (this.tokenExpired) await this.refreshAccessToken();
+    const separator = path.includes('?') ? '&' : '?';
+    const response = await this.fetch(
+      `https://api.weixin.qq.com${path}${separator}access_token=${this.#accessToken}`,
+      init,
+    );
+    return response.data as T;
+  }
+
+  async sendCustomerService(messageData: unknown): Promise<WeChatAPIResponse> {
+    let result = await this.request<WeChatAPIResponse>(
+      '/cgi-bin/message/custom/send',
+      { method: 'POST', body: messageData },
+    );
+    if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+      await this.refreshAccessToken();
+      result = await this.request<WeChatAPIResponse>(
+        '/cgi-bin/message/custom/send',
+        { method: 'POST', body: messageData },
+      );
+    }
+    return result;
+  }
+
+  async uploadMedia(
+    type: 'image' | 'voice' | 'video',
+    body: unknown,
+  ): Promise<string> {
+    const data = await this.request<WeChatMediaUploadResult>(
+      `/cgi-bin/media/upload?type=${type}`,
+      { method: 'POST', body },
+    );
+    if (data.media_id) return data.media_id;
+    throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
+  }
+
+  async getFollowerIds(): Promise<readonly string[]> {
+    const followers: string[] = [];
+    let nextOpenid = '';
+    do {
+      const data = await this.request<WeChatAPIResponse & {
+        count?: number;
+        data?: { openid?: string[] };
+        next_openid?: string;
+      }>(`/cgi-bin/user/get?next_openid=${encodeURIComponent(nextOpenid)}`);
+      if (data.errcode && data.errcode !== 0) {
+        throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+      }
+      followers.push(...(data.data?.openid ?? []).filter(Boolean));
+      if (Number(data.count ?? 0) < 10_000) break;
+      nextOpenid = data.next_openid ?? '';
+    } while (nextOpenid);
+    return Object.freeze(followers);
+  }
+}
+
+export type WeChatMpClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly 'wechat-mp': { readonly client: WeChatMpClient; readonly events: WeChatMpClientEventMap };
+  }
+}
+
+export const wechatMpClient = defineEndpointClient<WeChatMpClient, WeChatMpClientEventMap>('wechat-mp');