@zhin.js/adapter-wechat-mp 5.0.1 → 5.0.4

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @zhin.js/adapter-wechat-mp
 
+## 5.0.4
+
+### Patch Changes
+
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [162fa34]
+- Updated dependencies [e40b048]
+- Updated dependencies [f1708c3]
+- Updated dependencies [e53444f]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [a7df753]
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 5.0.3
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - zhin.js@6.0.2
+
 ## 5.0.1
 
 ### Patch Changes

package/README.md

@@ -24,8 +24,8 @@ pnpm add @zhin.js/adapter-wechat-mp
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: openid, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
+入站：`gateway.receive({ conversation: { endpoint, kind: 'private', id: openid }, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → 被动回复 XML（默认）或客服消息 API（`replyMode: customer_service`）
 
 ## 前置条件
 

package/adapters/wechat-mp.js

@@ -20,8 +20,8 @@ export default defineAdapter({
     create(context) {
         const config = resolveWeChatMpConfig(context.config);
         // 注册到插件运行时状态（wechat-mp.endpoint list 的"运行中"数据源）
-        context.use(wechatMpRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: 'webhook',
         });
         return new WeChatMpEndpoint({

package/adapters/wechat-mp.ts

@@ -25,8 +25,8 @@ export default defineAdapter<WeChatMpAdapterConfig>({
   create(context) {
     const config = resolveWeChatMpConfig(context.config);
     // 注册到插件运行时状态（wechat-mp.endpoint list 的"运行中"数据源）
-    context.use(wechatMpRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(wechatMpRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: 'webhook',
     });
     return new WeChatMpEndpoint({

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointFriend, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointFriend, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
@@ -33,10 +33,7 @@ export declare class WeChatMpEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: WeChatMessage): void;
     /**

package/lib/endpoint.js

@@ -2,12 +2,11 @@
  * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
 import axios from 'axios';
-import { formatCompact, getLogger } from '@zhin.js/logger';
-import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, } from './protocol.js';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, wechatMpInboundConversation, } from './protocol.js';
 import { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
 import { getPassiveReplyCapture, recordPassiveReplyText, } from './passive-reply.js';
 import { registerWeChatMpWebhookRoutes } from './webhook.js';
-const logger = getLogger('wechat-mp');
 /** token 失效类错误码：40001/40014 invalid access_token、42001 access_token expired。 */
 const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
 /**
@@ -29,6 +28,7 @@ function defaultFetch(url, init) {
     }).then((response) => ({ data: response.data }));
 }
 export class WeChatMpEndpoint {
+    #logger;
     #options;
     #fetch;
     #routeReleases = [];
@@ -42,6 +42,7 @@ export class WeChatMpEndpoint {
     #started = false;
     management = createWeChatMpEndpointManagement(this);
     constructor(options) {
+        this.#logger = getAdapterLogger('wechat-mp', options.config.id);
         this.#options = options;
         this.#fetch = options.fetch ?? defaultFetch;
     }
@@ -81,15 +82,15 @@ export class WeChatMpEndpoint {
             await this.#refreshAccessToken();
             this.#routeReleases.push(...registerWeChatMpWebhookRoutes(this.#options.http, this));
             this.#startTokenRefreshTimer();
-            logger.debug(formatCompact({
-                endpoint: this.#options.config.name,
+            this.#logger.debug(formatCompact({
+                endpoint: this.#options.config.id,
                 op: 'webhook',
                 path: this.#options.config.path,
             }));
         }
         catch (error) {
             await this.stop();
-            logger.error('Failed to connect WeChat MP bot:', error);
+            this.#logger.error('Failed to connect WeChat MP bot:', error);
             throw error;
         }
     }
@@ -108,22 +109,22 @@ export class WeChatMpEndpoint {
         for (const release of this.#routeReleases.splice(0))
             release();
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (getPassiveReplyCapture()) {
             const text = extractOutboundText(payload);
             recordPassiveReplyText(text);
             return `passive_${Date.now()}`;
         }
         if (this.#options.config.replyMode === 'customer_service') {
-            return this.#sendCustomerService(target, payload);
+            return this.#sendCustomerService(conversation.id, payload);
         }
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
             op: 'send',
             skip: 'passive_outside_webhook',
-            endpoint: this.#options.config.name,
-            target,
+            endpoint: this.#options.config.id,
+            target: `${conversation.kind}:${conversation.id}`,
         }));
         return `passive_skipped_${Date.now()}`;
     }
@@ -131,22 +132,22 @@ export class WeChatMpEndpoint {
     admit(msg) {
         if (!this.#open)
             return;
+        const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.FromUserName,
+            conversation,
+            message: { conversation, id: formatInboundId(msg) },
             content: formatInboundContent(msg),
-            sender: msg.FromUserName,
-            id: formatInboundId(msg),
+            sender: { id: msg.FromUserName },
+            endpointId: this.#options.config.id,
             metadata: Object.freeze({
                 msgType: msg.MsgType,
                 event: msg.Event,
-                endpoint: this.#options.config.name,
                 toUserName: msg.ToUserName,
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'wechat_mp_gateway_receive_failed',
-                target: msg.FromUserName,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -161,7 +162,7 @@ export class WeChatMpEndpoint {
         let result = await this.#postCustomerService(messageData);
         if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
             // 对端提前作废 token（多端共用等）：刷新后重试一次。
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'wechat_mp_token_invalid_retry',
                 errcode: result.errcode,
             }));
@@ -171,7 +172,7 @@ export class WeChatMpEndpoint {
         if (result.errcode && result.errcode !== 0) {
             throw new Error(`WeChat API error: ${result.errcode} - ${result.errmsg}`);
         }
-        logger.debug(formatCompact({ op: 'wechat_mp_send', target, messageId: result.msgid }));
+        this.#logger.debug(formatCompact({ op: 'wechat_mp_send', target, messageId: result.msgid }));
         return result.msgid?.toString() || `cs_${Date.now()}`;
     }
     /**
@@ -202,9 +203,9 @@ export class WeChatMpEndpoint {
                     return item;
                 if (typeof data.media_id === 'string' && data.media_id)
                     return item;
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'wechat_mp_outbound_media_dropped',
-                    endpoint: this.#options.config.name,
+                    endpoint: this.#options.config.id,
                     type: seg.type,
                     reason: 'missing_media_ref',
                 }));
@@ -215,9 +216,9 @@ export class WeChatMpEndpoint {
                 return { type: seg.type, data: { mediaId: media.value } };
             }
             if (!uploadType) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'wechat_mp_outbound_media_dropped',
-                    endpoint: this.#options.config.name,
+                    endpoint: this.#options.config.id,
                     type: seg.type,
                     reason: 'unsupported_segment_type',
                 }));
@@ -228,9 +229,9 @@ export class WeChatMpEndpoint {
                 return { type: seg.type, data: { mediaId } };
             }
             catch (error) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'wechat_mp_media_upload_failed',
-                    endpoint: this.#options.config.name,
+                    endpoint: this.#options.config.id,
                     error: error instanceof Error ? error.message : String(error),
                 }));
                 const alt = typeof data.alt === 'string' && data.alt ? data.alt : `[${seg.type}]`;
@@ -294,7 +295,7 @@ export class WeChatMpEndpoint {
         if (data.access_token) {
             this.#accessToken = data.access_token;
             this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
-            logger.debug(formatCompact({ op: 'token_refresh' }));
+            this.#logger.debug(formatCompact({ op: 'token_refresh' }));
             return;
         }
         throw new Error(data.errmsg
@@ -305,7 +306,7 @@ export class WeChatMpEndpoint {
         this.#tokenRefreshTimer = setInterval(() => {
             if (Date.now() >= this.#tokenExpireTime) {
                 void this.#refreshAccessToken().catch((error) => {
-                    logger.error('Failed to refresh access token in timer:', error);
+                    this.#logger.error('Failed to refresh access token in timer:', error);
                 });
             }
         }, 3_600_000);

package/lib/protocol.d.ts

@@ -3,8 +3,9 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 export interface WeChatMpAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly appId?: string;
     readonly appSecret?: string;
     readonly token?: string;
@@ -31,7 +32,7 @@ export interface WeChatMpAdapterConfig {
 }
 export interface ResolvedWeChatMpConfig {
     readonly context: 'wechat-mp';
-    readonly name: string;
+    readonly id: string;
     readonly appId: string;
     readonly appSecret: string;
     readonly token: string;
@@ -101,6 +102,11 @@ export declare function parseXMLMessage(xmlString: string): Promise<WeChatMessag
 export declare function decryptMessage(encryptedXml: string, msgSignature: string, timestamp: string, nonce: string, token: string, encodingAESKey: string, appId: string): Promise<string>;
 export declare function encryptMessage(replyXml: string, token: string, encodingAESKey: string, appId: string, requestTimestamp?: string): string;
 export declare function buildTextReply(wechatMsg: Pick<WeChatMessage, 'FromUserName' | 'ToUserName'>, content: string): string;
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export declare function wechatMpInboundConversation(endpointKey: string, msg: WeChatMessage): ConversationRef;
 /**
  * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。

package/lib/protocol.js

@@ -12,8 +12,8 @@ export function resolveWeChatMpConfig(config = {}) {
     if (!appId || !appSecret || !token) {
         throw new TypeError('WeChat MP adapter requires appId + appSecret + token (plugins.<key> or endpoints with context: wechat-mp)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.WECHAT_BOT_NAME
         || 'wechat-mp-bot';
     const path = config.path ?? entry?.path ?? '/wechat/webhook';
@@ -26,7 +26,7 @@ export function resolveWeChatMpConfig(config = {}) {
         ?? 4500;
     return {
         context: 'wechat-mp',
-        name,
+        id,
         appId,
         appSecret,
         token,
@@ -170,6 +170,17 @@ export function buildTextReply(wechatMsg, content) {
         '</xml>',
     ].join('');
 }
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export function wechatMpInboundConversation(endpointKey, msg) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'private',
+        id: msg.FromUserName,
+    };
+}
 /**
  * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。

package/lib/webhook.js

@@ -1,6 +1,6 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { getPassiveReplyCapture, runWithPassiveReplyCapture, } from './passive-reply.js';
-import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, verifySignature, } from './protocol.js';
+import { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, formatInboundContent, formatInboundId, 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;
@@ -132,17 +132,17 @@ export async function handleWeChatMpMessage(request, response, url, handler) {
 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([
             handler.gateway.receive({
-                adapter: handler.id,
-                target: wechatMsg.FromUserName,
+                conversation,
+                message: { conversation, id: formatInboundId(wechatMsg) },
                 content: formatInboundContent(wechatMsg),
-                sender: wechatMsg.FromUserName,
-                id: formatInboundId(wechatMsg),
+                sender: { id: wechatMsg.FromUserName },
+                endpointId: handler.config.id,
                 metadata: Object.freeze({
                     msgType: wechatMsg.MsgType,
                     event: wechatMsg.Event,
-                    endpoint: handler.config.name,
                     toUserName: wechatMsg.ToUserName,
                 }),
             }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wechat-mp",
-  "version": "5.0.1",
+  "version": "5.0.4",
   "type": "module",
   "description": "Zhin.js WeChat Official Account adapter for Plugin Runtime (HTTP webhook)",
   "main": "./lib/index.js",
@@ -8,19 +8,20 @@
   "dependencies": {
     "axios": "^1.19.0",
     "xml2js": "^0.6.2",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/schema.json

@@ -32,16 +32,48 @@
       "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",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "WeChat MP bot name"
+          "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",
@@ -58,10 +90,14 @@
           "encodingAESKey": {
             "type": "string",
             "description": "WeChat MP encoding AES key"
+          },
+          "id": {
+            "type": "string",
+            "description": "WeChat MP bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "appId",
           "appSecret",
           "token"

package/src/endpoint.ts

@@ -2,16 +2,17 @@
  * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
 import axios from 'axios';
-import type { EndpointFriend, EndpointInstance, EndpointManagement } from '@zhin.js/adapter';
+import type { EndpointFriend, EndpointInstance, EndpointManagement, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import {
   extractOutboundText,
   formatCustomerServiceBody,
   formatInboundContent,
   formatInboundId,
+  wechatMpInboundConversation,
   type ResolvedWeChatMpConfig,
   type TokenResponse,
   type WeChatAPIResponse,
@@ -29,8 +30,6 @@ import {
 } from './passive-reply.js';
 import { registerWeChatMpWebhookRoutes } from './webhook.js';
 
-const logger = getLogger('wechat-mp');
-
 /** token 失效类错误码：40001/40014 invalid access_token、42001 access_token expired。 */
 const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
 
@@ -71,6 +70,8 @@ function defaultFetch(
 }
 
 export class WeChatMpEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: WeChatMpEndpointOptions;
   readonly #fetch: WeChatMpFetch;
   #routeReleases: HttpRouteRegistration[] = [];
@@ -85,6 +86,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
   readonly management: EndpointManagement = createWeChatMpEndpointManagement(this);
 
   constructor(options: WeChatMpEndpointOptions) {
+    this.#logger = getAdapterLogger('wechat-mp', options.config.id);
     this.#options = options;
     this.#fetch = options.fetch ?? defaultFetch;
   }
@@ -128,14 +130,14 @@ export class WeChatMpEndpoint implements EndpointInstance {
       await this.#refreshAccessToken();
       this.#routeReleases.push(...registerWeChatMpWebhookRoutes(this.#options.http, this));
       this.#startTokenRefreshTimer();
-      logger.debug(formatCompact({
-        endpoint: this.#options.config.name,
+      this.#logger.debug(formatCompact({
+        endpoint: this.#options.config.id,
         op: 'webhook',
         path: this.#options.config.path,
       }));
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect WeChat MP bot:', error);
+      this.#logger.error('Failed to connect WeChat MP bot:', error);
       throw error;
     }
   }
@@ -156,10 +158,10 @@ export class WeChatMpEndpoint implements EndpointInstance {
     }
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (getPassiveReplyCapture()) {
       const text = extractOutboundText(payload);
       recordPassiveReplyText(text);
@@ -167,14 +169,14 @@ export class WeChatMpEndpoint implements EndpointInstance {
     }
 
     if (this.#options.config.replyMode === 'customer_service') {
-      return this.#sendCustomerService(target, payload);
+      return this.#sendCustomerService(conversation.id, payload);
     }
 
-    logger.warn(formatCompact({
+    this.#logger.warn(formatCompact({
       op: 'send',
       skip: 'passive_outside_webhook',
-      endpoint: this.#options.config.name,
-      target,
+      endpoint: this.#options.config.id,
+      target: `${conversation.kind}:${conversation.id}`,
     }));
     return `passive_skipped_${Date.now()}`;
   }
@@ -182,22 +184,22 @@ export class WeChatMpEndpoint implements EndpointInstance {
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: WeChatMessage): void {
     if (!this.#open) return;
+    const conversation = wechatMpInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.FromUserName,
+      conversation,
+      message: { conversation, id: formatInboundId(msg) },
       content: formatInboundContent(msg),
-      sender: msg.FromUserName,
-      id: formatInboundId(msg),
+      sender: { id: msg.FromUserName },
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
         msgType: msg.MsgType,
         event: msg.Event,
-        endpoint: this.#options.config.name,
         toUserName: msg.ToUserName,
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'wechat_mp_gateway_receive_failed',
-        target: msg.FromUserName,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -213,7 +215,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     let result = await this.#postCustomerService(messageData);
     if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
       // 对端提前作废 token（多端共用等）：刷新后重试一次。
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'wechat_mp_token_invalid_retry',
         errcode: result.errcode,
       }));
@@ -223,7 +225,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     if (result.errcode && result.errcode !== 0) {
       throw new Error(`WeChat API error: ${result.errcode} - ${result.errmsg}`);
     }
-    logger.debug(formatCompact({ op: 'wechat_mp_send', target, messageId: result.msgid }));
+    this.#logger.debug(formatCompact({ op: 'wechat_mp_send', target, messageId: result.msgid }));
     return result.msgid?.toString() || `cs_${Date.now()}`;
   }
 
@@ -249,9 +251,9 @@ export class WeChatMpEndpoint implements EndpointInstance {
         // 已物化（mediaId/media_id）的段透传；其余无 canonical 媒体引用，丢弃留痕
         if (typeof data.mediaId === 'string' && data.mediaId) return item;
         if (typeof data.media_id === 'string' && data.media_id) return item;
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'wechat_mp_outbound_media_dropped',
-          endpoint: this.#options.config.name,
+          endpoint: this.#options.config.id,
           type: seg.type,
           reason: 'missing_media_ref',
         }));
@@ -262,9 +264,9 @@ export class WeChatMpEndpoint implements EndpointInstance {
         return { type: seg.type, data: { mediaId: media.value } };
       }
       if (!uploadType) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'wechat_mp_outbound_media_dropped',
-          endpoint: this.#options.config.name,
+          endpoint: this.#options.config.id,
           type: seg.type,
           reason: 'unsupported_segment_type',
         }));
@@ -274,9 +276,9 @@ export class WeChatMpEndpoint implements EndpointInstance {
         const mediaId = await this.#uploadMedia(uploadType, media);
         return { type: seg.type, data: { mediaId } };
       } catch (error) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'wechat_mp_media_upload_failed',
-          endpoint: this.#options.config.name,
+          endpoint: this.#options.config.id,
           error: error instanceof Error ? error.message : String(error),
         }));
         const alt = typeof data.alt === 'string' && data.alt ? data.alt : `[${seg.type}]`;
@@ -349,7 +351,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     if (data.access_token) {
       this.#accessToken = data.access_token;
       this.#tokenExpireTime = Date.now() + (data.expires_in - 300) * 1000;
-      logger.debug(formatCompact({ op: 'token_refresh' }));
+      this.#logger.debug(formatCompact({ op: 'token_refresh' }));
       return;
     }
     throw new Error(
@@ -363,7 +365,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
     this.#tokenRefreshTimer = setInterval(() => {
       if (Date.now() >= this.#tokenExpireTime) {
         void this.#refreshAccessToken().catch((error) => {
-          logger.error('Failed to refresh access token in timer:', error);
+          this.#logger.error('Failed to refresh access token in timer:', error);
         });
       }
     }, 3_600_000);

package/src/protocol.ts

@@ -6,9 +6,10 @@
 import { createHash, createDecipheriv, createCipheriv, randomBytes } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 import * as xml2js from 'xml2js';
+import type { ConversationRef } from '@zhin.js/im-contract';
 
 export interface WeChatMpAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly appId?: string;
   readonly appSecret?: string;
   readonly token?: string;
@@ -36,7 +37,7 @@ export interface WeChatMpAdapterConfig {
 
 export interface ResolvedWeChatMpConfig {
   readonly context: 'wechat-mp';
-  readonly name: string;
+  readonly id: string;
   readonly appId: string;
   readonly appSecret: string;
   readonly token: string;
@@ -98,8 +99,8 @@ export function resolveWeChatMpConfig(config: WeChatMpAdapterConfig = {}): Resol
       'WeChat MP adapter requires appId + appSecret + token (plugins.<key> or endpoints with context: wechat-mp)',
     );
   }
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.WECHAT_BOT_NAME
     || 'wechat-mp-bot';
   const path = config.path ?? entry?.path ?? '/wechat/webhook';
@@ -112,7 +113,7 @@ export function resolveWeChatMpConfig(config: WeChatMpAdapterConfig = {}): Resol
     ?? 4500;
   return {
     context: 'wechat-mp',
-    name,
+    id,
     appId,
     appSecret,
     token,
@@ -310,6 +311,21 @@ export function buildTextReply(
   ].join('');
 }
 
+/**
+ * 入站归一化：公众号只有粉丝单聊场景，一律 kind='private'，id=openid（FromUserName），
+ * 无群/频道容器（parent 恒缺省）。
+ */
+export function wechatMpInboundConversation(
+  endpointKey: string,
+  msg: WeChatMessage,
+): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: 'private',
+    id: msg.FromUserName,
+  };
+}
+
 /**
  * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
  * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。

package/src/webhook.ts

@@ -25,6 +25,7 @@ import {
   readTextBody,
   resolveEventPassiveReply,
   verifySignature,
+  wechatMpInboundConversation,
   type ResolvedWeChatMpConfig,
   type WeChatMessage,
 } from './protocol.js';
@@ -218,17 +219,17 @@ export async function collectPassiveReply(
 ): Promise<string> {
   const timeoutMs = handler.config.passiveReplyTimeoutMs;
   const text = await runWithPassiveReplyCapture(async () => {
+    const conversation = wechatMpInboundConversation(String(handler.id), wechatMsg);
     await Promise.race([
       handler.gateway.receive({
-        adapter: handler.id,
-        target: wechatMsg.FromUserName,
+        conversation,
+        message: { conversation, id: formatInboundId(wechatMsg) },
         content: formatInboundContent(wechatMsg),
-        sender: wechatMsg.FromUserName,
-        id: formatInboundId(wechatMsg),
+        sender: { id: wechatMsg.FromUserName },
+        endpointId: handler.config.id,
         metadata: Object.freeze({
           msgType: wechatMsg.MsgType,
           event: wechatMsg.Event,
-          endpoint: handler.config.name,
           toUserName: wechatMsg.ToUserName,
         }),
       }),