@zhin.js/adapter-wecom 4.0.2 → 4.0.3

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zhin.js/adapter-wecom
 
+## 4.0.3
+
+### 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/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 4.0.2
 
 ### Patch Changes

package/README.md

@@ -23,8 +23,8 @@ pnpm add @zhin.js/adapter-wecom
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-入站：`gateway.receive({ adapter, target: FromUserName, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → 企业微信 `message/send` API
+入站：`gateway.receive({ conversation, message: { conversation, id: MsgId }, content: text, sender, metadata })`（`conversation` 为 `ConversationRef`，`@chatroom` → kind `group`，其余 → kind `private`）  
+出站：`send({ conversation, payload })` → 企业微信 `message/send` API
 
 入站 `metadata.mentioned`：**未接线**。企业微信应用消息回调的 XML 事件不含 mentions/@ 字段，回调里的 `ToUserName` 是 CorpID（企业 ID）而非可比较的 bot 用户 id，配置中也没有 bot id/name 可作可靠判据，故无法可靠识别 @ 机器人。
 

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, 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';
@@ -38,10 +38,7 @@ export declare class WecomEndpoint 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>;
     recallMessage(messageId: string): Promise<void>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: WecomMessage): void;

package/lib/endpoint.js

@@ -1,7 +1,7 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { registerWecomAgentEndpoint } from './wecom-agent-deps.js';
 import { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
-import { buildSendRequestBody, formatInboundContent, formatOutboundBody, resolveChatType, } from './protocol.js';
+import { buildSendRequestBody, formatInboundContent, formatOutboundBody, resolveChatType, wecomInboundConversation, } from './protocol.js';
 import { registerWecomWebhookRoutes } from './webhook.js';
 const logger = getLogger('wecom');
 /**
@@ -64,10 +64,10 @@ export class WecomEndpoint {
         this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         const materialized = await this.#materializeOutboundMedia(payload);
         const content = formatOutboundBody(materialized);
-        const body = buildSendRequestBody(target, content, 
+        const body = buildSendRequestBody(conversation.id, content, 
         // Legacy field: historically written into agentid (preserved for cutover).
         this.#options.config.agentSecret);
         const data = await this.#request('/cgi-bin/message/send', {
@@ -77,7 +77,11 @@ export class WecomEndpoint {
         if (data.errcode !== 0) {
             throw new Error(`Failed to send message: ${data.errmsg} (${data.errcode})`);
         }
-        logger.debug(formatCompact({ op: 'send', endpoint: this.#options.config.name, to: target }));
+        logger.debug(formatCompact({
+            op: 'send',
+            endpoint: this.#options.config.name,
+            to: `${conversation.kind}:${conversation.id}`,
+        }));
         return data.msgid || `${Date.now()}`;
     }
     async recallMessage(messageId) {
@@ -150,12 +154,12 @@ export class WecomEndpoint {
         if (!this.#open)
             return;
         const chatType = resolveChatType(msg.FromUserName);
+        const conversation = wecomInboundConversation(String(this.#options.id), msg);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: msg.FromUserName,
+            conversation,
+            message: { conversation, id: msg.MsgId || `${msg.CreateTime}` },
             content: formatInboundContent(msg),
             sender: msg.FromUserName,
-            id: msg.MsgId || `${msg.CreateTime}`,
             metadata: Object.freeze({
                 msgType: msg.MsgType,
                 event: msg.Event,
@@ -167,7 +171,7 @@ export class WecomEndpoint {
         }).catch((err) => {
             logger.warn(formatCompact({
                 op: 'wecom_gateway_receive_failed',
-                target: msg.FromUserName,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });
@@ -216,7 +220,15 @@ export class WecomEndpoint {
     }
     async sendTextMessage(userId, content) {
         try {
-            await this.send({ target: userId, payload: content });
+            const endpointId = String(this.#options.id);
+            await this.send({
+                conversation: {
+                    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+                    kind: resolveChatType(userId),
+                    id: userId,
+                },
+                payload: content,
+            });
             return true;
         }
         catch (error) {

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface WecomAdapterConfig {
     readonly name?: string;
@@ -86,6 +87,11 @@ export declare function parseXmlMessage(xml: string): WecomMessage | null;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(msg: WecomMessage): string;
 export declare function resolveChatType(fromUserName: string): 'group' | 'private';
+/**
+ * 入站归一化 → ConversationRef：WeCom 无 guild/channel 容器概念，
+ * `@chatroom` 群会话 → kind 'group'，其余（应用消息/单聊）→ kind 'private'。
+ */
+export declare function wecomInboundConversation(endpointId: string, msg: WecomMessage): ConversationRef;
 /**
  * Wire-encode an already-rendered outbound payload into WeCom message/send body parts.
  */

package/lib/protocol.js

@@ -155,6 +155,17 @@ export function formatInboundContent(msg) {
 export function resolveChatType(fromUserName) {
     return fromUserName.endsWith('@chatroom') ? 'group' : 'private';
 }
+/**
+ * 入站归一化 → ConversationRef：WeCom 无 guild/channel 容器概念，
+ * `@chatroom` 群会话 → kind 'group'，其余（应用消息/单聊）→ kind 'private'。
+ */
+export function wecomInboundConversation(endpointId, msg) {
+    return {
+        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        kind: resolveChatType(msg.FromUserName),
+        id: msg.FromUserName,
+    };
+}
 /**
  * Wire-encode an already-rendered outbound payload into WeCom message/send body parts.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,22 @@
     "directory": "plugins/adapters/wecom"
   },
   "dependencies": {
-    "@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/adapter": "1.1.5",
+    "@zhin.js/command": "1.0.7",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@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.5",
+    "@zhin.js/agent": "1.1.3",
+    "@zhin.js/core": "1.5.2",
+    "@zhin.js/host-http": "1.0.6",
+    "@zhin.js/plugin-runtime": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,8 +67,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.3",
+    "zhin.js": "6.0.2"
   },
   "files": [
     "adapters",

package/src/endpoint.ts

@@ -1,7 +1,7 @@
 /**
  * WecomEndpoint — lifecycle, outbound send, inbound admit, OpenAPI helpers for agent tools.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, 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';
@@ -18,6 +18,7 @@ import {
   formatInboundContent,
   formatOutboundBody,
   resolveChatType,
+  wecomInboundConversation,
   type AccessToken,
   type ResolvedWecomConfig,
   type WecomApiResponse,
@@ -114,11 +115,11 @@ export class WecomEndpoint implements EndpointInstance {
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     const materialized = await this.#materializeOutboundMedia(payload);
     const content = formatOutboundBody(materialized);
     const body = buildSendRequestBody(
-      target,
+      conversation.id,
       content,
       // Legacy field: historically written into agentid (preserved for cutover).
       this.#options.config.agentSecret,
@@ -130,7 +131,11 @@ export class WecomEndpoint implements EndpointInstance {
     if (data.errcode !== 0) {
       throw new Error(`Failed to send message: ${data.errmsg} (${data.errcode})`);
     }
-    logger.debug(formatCompact({ op: 'send', endpoint: this.#options.config.name, to: target }));
+    logger.debug(formatCompact({
+      op: 'send',
+      endpoint: this.#options.config.name,
+      to: `${conversation.kind}:${conversation.id}`,
+    }));
     return (data.msgid as string) || `${Date.now()}`;
   }
 
@@ -200,12 +205,12 @@ export class WecomEndpoint implements EndpointInstance {
   admit(msg: WecomMessage): void {
     if (!this.#open) return;
     const chatType = resolveChatType(msg.FromUserName);
+    const conversation = wecomInboundConversation(String(this.#options.id), msg);
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: msg.FromUserName,
+      conversation,
+      message: { conversation, id: msg.MsgId || `${msg.CreateTime}` },
       content: formatInboundContent(msg),
       sender: msg.FromUserName,
-      id: msg.MsgId || `${msg.CreateTime}`,
       metadata: Object.freeze({
         msgType: msg.MsgType,
         event: msg.Event,
@@ -217,7 +222,7 @@ export class WecomEndpoint implements EndpointInstance {
     }).catch((err) => {
       logger.warn(formatCompact({
         op: 'wecom_gateway_receive_failed',
-        target: msg.FromUserName,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });
@@ -264,7 +269,15 @@ export class WecomEndpoint implements EndpointInstance {
 
   async sendTextMessage(userId: string, content: string): Promise<boolean> {
     try {
-      await this.send({ target: userId, payload: content });
+      const endpointId = String(this.#options.id);
+      await this.send({
+        conversation: {
+          endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+          kind: resolveChatType(userId),
+          id: userId,
+        },
+        payload: content,
+      });
       return true;
     } catch (error) {
       logger.error('Failed to send text message:', error);

package/src/protocol.ts

@@ -5,6 +5,7 @@
 
 import { createHash, createDecipheriv, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface WecomAdapterConfig {
@@ -255,6 +256,18 @@ export function resolveChatType(fromUserName: string): 'group' | 'private' {
   return fromUserName.endsWith('@chatroom') ? 'group' : 'private';
 }
 
+/**
+ * 入站归一化 → ConversationRef：WeCom 无 guild/channel 容器概念，
+ * `@chatroom` 群会话 → kind 'group'，其余（应用消息/单聊）→ kind 'private'。
+ */
+export function wecomInboundConversation(endpointId: string, msg: WecomMessage): ConversationRef {
+  return {
+    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    kind: resolveChatType(msg.FromUserName),
+    id: msg.FromUserName,
+  };
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into WeCom message/send body parts.
  */