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

package/README.md

@@ -1,14 +1,14 @@
 # @zhin.js/adapter-wechat-mp
 
-Zhin.js 微信公众号适配器，支持微信公众号的消息收发。
+Zhin.js 微信公众号适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
 
 ## 功能特性
 
-- Webhook 事件接收（HTTP 回调）
-- 签名验证
+- Webhook 事件接收（`httpHostToken` GET 验签 + POST 消息）
+- 签名验证与可选 AES 加解密
 - Access Token 自动刷新
 - XML 消息解析
-- 可选消息加密（AES）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -16,105 +16,54 @@ Zhin.js 微信公众号适配器，支持微信公众号的消息收发。
 pnpm add @zhin.js/adapter-wechat-mp
 ```
 
+## Plugin Runtime
+
+- `@zhin.js/adapter` — 约定式 `adapters/wechat-mp/index.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+
+入站：`gateway.receive({ conversation: { endpoint, kind: 'private', id: openid }, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
+
 ## 前置条件
 
 | 要求 | 说明 |
 |------|------|
 | **公众号** | 已注册微信公众号，并在 [微信公众平台](https://mp.weixin.qq.com/) 获取 `AppID`、`AppSecret` |
 | **服务器配置** | 配置 Token（与 `token` 字段一致）；服务器 URL 须公网可访问 |
-| **host-router** | **必需** — 适配器在 `path` 上注册 GET/POST Webhook 路由 |
+| **host-http** | **必需** — Runtime Host 提供 HTTP；适配器在 `path` 上注册 GET/POST |
 | **响应时限** | 微信要求 **5 秒内**响应；超时会导致接入失败 |
-| **回复模式** | 默认 `replyMode: passive`（订阅号被动回复，在 webhook 响应里返回 XML）；服务号可设 `customer_service` 走客服 API |
-| **消息加密** | 可选；`encrypt: true` + `encodingAESKey`；`encryptMode: compatible`（默认，被动回复明文）或 `secure`（被动回复也加密） |
+| **回复模式** | 默认 `replyMode: passive`（订阅号被动回复）；服务号可设 `customer_service` |
+| **消息加密** | 可选；`encrypt: true` + `encodingAESKey`；`encryptMode: compatible`（默认）或 `secure` |
 
-必填字段见 `WeChatMPConfig`：`context`、`name`、`appId`、`appSecret`、`token`、`path`。
+必填字段（`endpoints[i]`）：`id`、`appId`、`appSecret`、`token`。运行时由 AdapterIndex
+把实例级默认值与每个 endpoint 合并；协议实现只接收一份展开后的 endpoint 配置。
 
 ## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-wechat-mp"
-  - "@zhin.js/host-router"
-
-endpoints:
-  - context: wechat-mp
-    name: my-wechat-bot
-    appId: "${WECHAT_APP_ID}"
-    appSecret: "${WECHAT_APP_SECRET}"
-    token: "${WECHAT_TOKEN}"
-    path: /wechat/webhook
-```
-
-## 依赖
-
-- `@zhin.js/host-router` — HTTP 服务（提供 Webhook 路由）
-
-## 配置
-
-### TypeScript 配置
-
-完整选项示例（含可选加密字段）：
-
-```yaml
-endpoints:
-  - context: wechat-mp
-    name: my-wechat-bot
-    appId: ${WECHAT_APP_ID}
-    appSecret: ${WECHAT_APP_SECRET}
-    token: ${WECHAT_TOKEN}
+  wechat-mp:
     path: /wechat/webhook
-    # encodingAESKey: your-aes-key
-    # encrypt: false
+    endpoints:
+      - id: my-wechat-bot
+        appId: "${WECHAT_APP_ID}"
+        appSecret: "${WECHAT_APP_SECRET}"
+        token: "${WECHAT_TOKEN}"
 ```
 
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'wechat-mp',
-      name: 'my-wechat-bot',
-      appId: process.env.WECHAT_APP_ID!,
-      appSecret: process.env.WECHAT_APP_SECRET!,
-      token: process.env.WECHAT_TOKEN!,
-      path: '/wechat/webhook',
-    }
-  ],
-  plugins: ['@zhin.js/adapter-wechat-mp', '@zhin.js/host-router']
-})
-```
-
-## 使用示例
-
-### 注册命令
-
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand } = usePlugin()
-
-addCommand(
-  new MessageCommand('hello')
-    .desc('微信问候')
-    .action((message) => `你好，${message.$sender.name}！`)
-)
-```
-
-### 消息中间件
-
-```typescript
-import { usePlugin } from 'zhin.js'
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-wechat-mp`（`instanceKey: wechat-mp`）。
+Runtime Host（`http`）须已 listen，Webhook 才可达。
 
-const { addMiddleware } = usePlugin()
+### 可选字段
 
-addMiddleware(async (message, next) => {
-  if (message.$adapter === 'wechat-mp') {
-    console.log('收到微信消息:', message.$content)
-  }
-  await next()
-})
-```
+- `path`：Webhook 路径，默认 `/wechat/webhook`
+- `replyMode`：`passive`（默认）| `customer_service`
+- `passiveReplyTimeoutMs`：被动回复等待上限，默认 `4500`
+- `encrypt` / `encodingAESKey` / `encryptMode`
 
 ## 微信公众号配置
 
@@ -128,12 +77,16 @@ addMiddleware(async (message, next) => {
 
 | 现象 | 排查 |
 |------|------|
-| 服务器配置验证失败 | `token` 与公众平台一致；URL 为 `https://<host>/wechat/webhook`；Host 已启动且公网可达 |
-| 收不到用户消息 | 公众号类型是否支持消息接口；用户是否已关注；`path` 与公众平台 URL 一致 |
-| 回复超时 / 无回复 | 默认被动回复须在 **~4.5s** 内完成；AI 过慢会返回 `success` 无正文，可改 `replyMode: customer_service`（需客服接口权限） |
+| 服务器配置验证失败 | `token` 与公众平台一致；URL 为 `https://<host>/wechat/webhook`；Runtime Host 已 listen 且公网可达 |
+| 收不到用户消息 | 公众号类型是否支持消息接口；用户是否已关注；`path` 与公众平台 URL 一致；endpoint 已 `open()` |
+| 回复超时 / 无回复 | 默认被动回复须在 **~4.5s** 内完成；可改 `replyMode: customer_service`（需客服接口权限） |
 | `48001 api unauthorized` | 未认证订阅号无客服 API；保持默认 `replyMode: passive` |
 | 加密模式报错 | `encodingAESKey`、`encrypt` 与公众平台「安全模式」设置一致 |
 
+## AI 工具
+
+技能说明见 `skills/wechat-mp/SKILL.md`。
+
 ## 文档链接
 
 - [微信公众号适配器文档](https://zhin.js.org/adapters/wechat-mp)

package/adapters/wechat-mp/index.js

@@ -0,0 +1,32 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/wechat-mp/index.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WeChatMpEndpoint } from "../../lib/endpoint.js";
+import { resolveWeChatMpConfig, } from "../../lib/protocol.js";
+import { wechatMpRuntimeStateToken } from "../../lib/wechat-mp-runtime-state.js";
+export { WeChatMpEndpoint } from "../../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // 客服消息媒体统一经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传，
+    // kind=file 的 MediaRef 视为既有 media_id 直传）；公众号无卡片交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['upload'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveWeChatMpConfig(context.config);
+        // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
+        context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: 'webhook',
+        });
+        return new WeChatMpEndpoint({
+            id: context.id,
+            http: context.use(httpHostToken),
+            config,
+        });
+    },
+});

package/adapters/wechat-mp/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Convention entry: discover `adapters/wechat-mp/index.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WeChatMpEndpoint } from '../../src/endpoint.js';
+import {
+  resolveWeChatMpConfig,
+  type WeChatMpEndpointConfig,
+} from '../../src/protocol.js';
+import { wechatMpRuntimeStateToken } from '../../src/wechat-mp-runtime-state.js';
+
+export { WeChatMpEndpoint } from '../../src/endpoint.js';
+export type { WeChatMpEndpointOptions } from '../../src/endpoint.js';
+export type { WeChatMpFetch } from '../../src/client.js';
+
+export default defineAdapter<WeChatMpEndpointConfig>({
+  capabilities: ['inbound', 'outbound'],
+  // 客服消息媒体统一经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传，
+  // kind=file 的 MediaRef 视为既有 media_id 直传）；公众号无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['upload'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveWeChatMpConfig(context.config);
+    // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
+    context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: 'webhook',
+    });
+    return new WeChatMpEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      config,
+    });
+  },
+});

package/commands/wechat-mp/endpoint/add/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wechatMpEndpointCommands } from '../../definition.js';
+export default wechatMpEndpointCommands.add;

package/commands/wechat-mp/endpoint/add/[id]/index.ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../definition.js';
+
+export default wechatMpEndpointCommands.add;

package/commands/wechat-mp/endpoint/definition.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `wechat-mp endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/wechat-mp/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { wechatMpRuntimeStateToken } from "../../../lib/wechat-mp-runtime-state.js";
+export const wechatMpEndpointCommands = createEndpointCommands({
+    adapterKey: 'wechat-mp',
+    adapterDisplayName: 'WeChat MP',
+    fields: [
+        { key: 'appId', required: true, env: true, description: '公众号 AppID' },
+        { key: 'appSecret', required: true, env: true, description: '公众号 AppSecret' },
+        { key: 'token', required: true, env: true, description: '服务器配置 token' },
+        { key: 'encodingAESKey', env: true, description: '消息加解密 key' },
+    ],
+    running: (use) => use(wechatMpRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `appId: ${String(entry.appId)}`,
+}, defineCommand);

package/commands/wechat-mp/endpoint/definition.ts

@@ -0,0 +1,20 @@
+/**
+ * `wechat-mp endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/wechat-mp/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { wechatMpRuntimeStateToken } from '../../../src/wechat-mp-runtime-state.js';
+
+export const wechatMpEndpointCommands = createEndpointCommands({
+  adapterKey: 'wechat-mp',
+  adapterDisplayName: 'WeChat MP',
+  fields: [
+    { key: 'appId', required: true, env: true, description: '公众号 AppID' },
+    { key: 'appSecret', required: true, env: true, description: '公众号 AppSecret' },
+    { key: 'token', required: true, env: true, description: '服务器配置 token' },
+    { key: 'encodingAESKey', env: true, description: '消息加解密 key' },
+  ],
+  running: (use) => use(wechatMpRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `appId: ${String(entry.appId)}`,
+}, defineCommand);

package/commands/wechat-mp/endpoint/list/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wechatMpEndpointCommands } from '../definition.js';
+export default wechatMpEndpointCommands.list;

package/commands/wechat-mp/endpoint/list/index.ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../definition.js';
+
+export default wechatMpEndpointCommands.list;

package/commands/wechat-mp/endpoint/remove/[id]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wechatMpEndpointCommands } from '../../definition.js';
+export default wechatMpEndpointCommands.remove;

package/commands/wechat-mp/endpoint/remove/[id]/index.ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../definition.js';
+
+export default wechatMpEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedWeChatMpConfig, WeChatAPIResponse } from './protocol.js';
+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 declare class WeChatMpClient {
+    #private;
+    readonly config: ResolvedWeChatMpConfig;
+    readonly fetch: WeChatMpFetch;
+    constructor(config: ResolvedWeChatMpConfig, fetch: WeChatMpFetch);
+    get accessToken(): string | null;
+    get tokenExpired(): boolean;
+    refreshAccessToken(): Promise<string>;
+    request<T = unknown>(path: string, init?: Parameters<WeChatMpFetch>[1]): Promise<T>;
+    sendCustomerService(messageData: unknown): Promise<WeChatAPIResponse>;
+    uploadMedia(type: 'image' | 'voice' | 'video', body: unknown): Promise<string>;
+    getFollowerIds(): Promise<readonly string[]>;
+}
+export type WeChatMpClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly 'wechat-mp': {
+            readonly client: WeChatMpClient;
+            readonly events: WeChatMpClientEventMap;
+        };
+    }
+}
+export declare const wechatMpClient: import("@zhin.js/adapter").EndpointClientToken<WeChatMpClient, WeChatMpClientEventMap>;

package/lib/client.js

@@ -0,0 +1,70 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+/** Direct WeChat Official Account API client exposed to plugins. */
+export class WeChatMpClient {
+    config;
+    fetch;
+    #accessToken = null;
+    #tokenExpireTime = 0;
+    constructor(config, fetch) {
+        this.config = config;
+        this.fetch = fetch;
+    }
+    get accessToken() {
+        return this.#accessToken;
+    }
+    get tokenExpired() {
+        return !this.#accessToken || Date.now() >= this.#tokenExpireTime;
+    }
+    async refreshAccessToken() {
+        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;
+        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(path, init) {
+        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;
+    }
+    async sendCustomerService(messageData) {
+        let result = await this.request('/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('/cgi-bin/message/custom/send', { method: 'POST', body: messageData });
+        }
+        return result;
+    }
+    async uploadMedia(type, body) {
+        const data = await this.request(`/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() {
+        const followers = [];
+        let nextOpenid = '';
+        do {
+            const data = await this.request(`/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 const wechatMpClient = defineEndpointClient('wechat-mp');

package/lib/endpoint.d.ts

@@ -1,73 +1,32 @@
-import { EventEmitter } from "events";
-import { Endpoint, Message, MessageSegment, SendOptions } from 'zhin.js';
-import { type Router } from "@zhin.js/host-router/router";
-import type { WeChatMPConfig, WeChatMessage } from "./types.js";
-import type { WeChatMPAdapter } from "./adapter.js";
-export declare class WeChatMPEndpoint extends EventEmitter implements Endpoint<WeChatMPConfig, WeChatMessage> {
-    adapter: WeChatMPAdapter;
-    $config: WeChatMPConfig;
-    $connected: boolean;
-    router: Router;
-    private accessToken;
-    private tokenExpireTime;
-    get logger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: WeChatMPAdapter, router: Router, config: WeChatMPConfig);
-    private setupRoutes;
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private handleVerification;
-    private handleMessage;
-    private computeSignatureHash;
-    private verifySignature;
-    private parseXMLMessage;
-    $formatMessage(wechatMsg: WeChatMessage): Message<WeChatMessage>;
-    static parseMessageContent(wechatMsg: WeChatMessage): MessageSegment[];
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
-    private sendCustomerServiceMessage;
-    private formatSendContent;
-    private getReplyMode;
-    private getEncryptMode;
-    private usesPassiveReply;
-    private extractSendText;
-    private collectPassiveReplyXml;
-    private handlePassiveReply;
-    private buildTextReply;
-    private refreshAccessToken;
-    private tokenRefreshTimer?;
-    private startTokenRefreshTimer;
-    getUserInfo(openid: string): Promise<any>;
-    /**
-     * 上传多媒体文件到微信服务器
-     * @param type 媒体类型：image(图片)、voice(语音)、video(视频)、thumb(缩略图)
-     * @param buffer 文件 Buffer
-     * @param filename 文件名（可选，用于确定文件类型）
-     * @returns 微信服务器返回的 media_id
-     */
-    uploadMedia(type: 'image' | 'voice' | 'video' | 'thumb', buffer: Buffer, filename?: string): Promise<string>;
-    /**
-     * 获取文件扩展名
-     */
-    private getFileExtension;
-    /**
-     * 获取 Content-Type
-     */
-    private getContentType;
-    private getAESKey;
-    /** 微信安全模式加密 echostr 为较长 Base64；明文/兼容模式多为短字符串 */
-    private isEncryptedEchostr;
-    /**
-     * 解密安全模式 URL 验证中的 echostr
-     */
-    private decryptEchostr;
-    /**
-     * 解密微信推送的加密消息
-     */
-    private decryptMessage;
-    /**
-     * 加密被动回复消息
-     */
-    private encryptMessage;
+import { Endpoint } from 'zhin.js/adapter';
+import type { EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type ResolvedWeChatMpConfig, type WeChatMessage } from './protocol.js';
+import { WeChatMpClient, type WeChatMpFetch } from './client.js';
+export interface WeChatMpEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: ResolvedWeChatMpConfig;
+    readonly fetch?: WeChatMpFetch;
+}
+export declare class WeChatMpEndpoint extends Endpoint<WeChatMpClient> {
+    #private;
+    readonly client: WeChatMpClient;
+    readonly management: EndpointManagement;
+    constructor(options: WeChatMpEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedWeChatMpConfig;
+    get id(): CapabilityId;
+    /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
+    getCachedReply(msgId: string): string | undefined;
+    cacheReply(msgId: string, replyXML: string): void;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a parsed message when open (non-webhook path). */
+    admit(msg: WeChatMessage): void | Promise<unknown>;
 }
-//# sourceMappingURL=endpoint.d.ts.map