@zhin.js/adapter-wechat-mp 3.0.3 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @zhin.js/adapter-wechat-mp
 
+## 4.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 4.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 3.0.3
 
 ### Patch Changes

package/README.md

@@ -38,7 +38,7 @@ pnpm add @zhin.js/adapter-wechat-mp
 | **回复模式** | 默认 `replyMode: passive`（订阅号被动回复）；服务号可设 `customer_service` |
 | **消息加密** | 可选；`encrypt: true` + `encodingAESKey`；`encryptMode: compatible`（默认）或 `secure` |
 
-必填字段：`appId`、`appSecret`、`token`。
+必填字段（`endpoints[i]`）：`name`、`appId`、`appSecret`、`token`。
 
 ## 最小配置
 
@@ -46,11 +46,12 @@ pnpm add @zhin.js/adapter-wechat-mp
 # zhin.config.yml（Plugin Runtime）
 plugins:
   wechat-mp:
-    name: my-wechat-bot
-    appId: "${WECHAT_APP_ID}"
-    appSecret: "${WECHAT_APP_SECRET}"
-    token: "${WECHAT_TOKEN}"
     path: /wechat/webhook
+    endpoints:
+      - name: my-wechat-bot
+        appId: "${WECHAT_APP_ID}"
+        appSecret: "${WECHAT_APP_SECRET}"
+        token: "${WECHAT_TOKEN}"
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-wechat-mp`（`instanceKey: wechat-mp`）。

package/adapters/wechat-mp.ts

@@ -9,18 +9,31 @@ import {
   resolveWeChatMpConfig,
   type WeChatMpAdapterConfig,
 } from '../src/protocol.js';
+import { wechatMpRuntimeStateToken } from '../src/wechat-mp-runtime-state.js';
 
 export { WeChatMpEndpoint } from '../src/endpoint.js';
 export type { WeChatMpEndpointOptions, WeChatMpFetch } from '../src/endpoint.js';
 
 export default defineAdapter<WeChatMpAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // 客服消息图片经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传）；
+  // 公众号无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'upload'],
+    interactive: 'text',
+  },
   create(context) {
+    const config = resolveWeChatMpConfig(context.config);
+    // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
+    context.use(wechatMpRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: 'webhook',
+    });
     return new WeChatMpEndpoint({
       id: context.id,
       gateway: context.use(messageGatewayToken),
       http: context.use(httpHostToken),
-      config: resolveWeChatMpConfig(context.config),
+      config,
     });
   },
 });

package/commands/endpoint/add/[name:string].ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../../src/wechat-mp-endpoint-commands.js';
+
+export default wechatMpEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../src/wechat-mp-endpoint-commands.js';
+
+export default wechatMpEndpointCommands.list;

package/commands/endpoint/remove/[name:string].ts

@@ -0,0 +1,3 @@
+import { wechatMpEndpointCommands } from '../../../src/wechat-mp-endpoint-commands.js';
+
+export default wechatMpEndpointCommands.remove;

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointFriend, EndpointInstance, EndpointManagement } 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';
@@ -19,12 +19,16 @@ export interface WeChatMpEndpointOptions {
 }
 export declare class WeChatMpEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: WeChatMpEndpointOptions);
     /** Used by webhook handler. */
     get isOpen(): boolean;
     get config(): ResolvedWeChatMpConfig;
     get id(): CapabilityId;
     get gateway(): MessageGateway;
+    /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
+    getCachedReply(msgId: string): string | undefined;
+    cacheReply(msgId: string, replyXML: string): void;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -35,4 +39,10 @@ export declare class WeChatMpEndpoint implements EndpointInstance {
     }): Promise<string>;
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg: WeChatMessage): void;
+    /**
+     * 关注者列表（GET /cgi-bin/user/get，按 next_openid 分页，每页最多 10000）。
+     * 该接口只回 openid 不回昵称；昵称需逐个调 user/info（成本高且依赖用户授权），
+     * 这里 nickname 用 openid 占位，由 Console 侧自行理解。
+     */
+    getFollowers(): Promise<readonly EndpointFriend[]>;
 }

package/lib/endpoint.js

@@ -3,10 +3,13 @@
  */
 import axios from 'axios';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, } from './protocol.js';
+import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, } from './protocol.js';
+import { buildMediaUploadForm, readOutboundImageMedia, 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]);
 function defaultFetch(url, init) {
     return axios({
         url,
@@ -22,8 +25,12 @@ export class WeChatMpEndpoint {
     #accessToken = null;
     #tokenExpireTime = 0;
     #tokenRefreshTimer;
+    /** MsgId → 首次回复 XML（微信 5s 重推去重，有界 LRU）。 */
+    #replyCache = new Map();
+    static #REPLY_CACHE_LIMIT = 1000;
     #open = false;
     #started = false;
+    management = createWeChatMpEndpointManagement(this);
     constructor(options) {
         this.#options = options;
         this.#fetch = options.fetch ?? defaultFetch;
@@ -41,6 +48,21 @@ export class WeChatMpEndpoint {
     get gateway() {
         return this.#options.gateway;
     }
+    /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
+    getCachedReply(msgId) {
+        return this.#replyCache.get(msgId);
+    }
+    cacheReply(msgId, replyXML) {
+        if (this.#replyCache.has(msgId))
+            this.#replyCache.delete(msgId);
+        this.#replyCache.set(msgId, replyXML);
+        while (this.#replyCache.size > WeChatMpEndpoint.#REPLY_CACHE_LIMIT) {
+            const oldest = this.#replyCache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#replyCache.delete(oldest);
+        }
+    }
     async start() {
         if (this.#started)
             return;
@@ -104,7 +126,7 @@ export class WeChatMpEndpoint {
             target: msg.FromUserName,
             content: formatInboundContent(msg),
             sender: msg.FromUserName,
-            id: msg.MsgId || `${msg.CreateTime}`,
+            id: formatInboundId(msg),
             metadata: Object.freeze({
                 msgType: msg.MsgType,
                 event: msg.Event,
@@ -120,18 +142,107 @@ export class WeChatMpEndpoint {
         });
     }
     async #sendCustomerService(target, payload) {
-        if (!this.#accessToken)
+        // 发送前检查过期（不只判 null）：过期 token 直接刷新，不白跑一次 40001。
+        if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
             await this.#refreshAccessToken();
-        const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.#accessToken}`;
-        const messageData = formatCustomerServiceBody(target, payload);
-        const response = await this.#fetch(url, { method: 'POST', body: messageData });
-        const result = response.data;
+        }
+        const materialized = await this.#materializeOutboundMedia(payload);
+        const messageData = formatCustomerServiceBody(target, materialized);
+        let result = await this.#postCustomerService(messageData);
+        if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+            // 对端提前作废 token（多端共用等）：刷新后重试一次。
+            logger.warn(formatCompact({
+                op: 'wechat_mp_token_invalid_retry',
+                errcode: result.errcode,
+            }));
+            await this.#refreshAccessToken();
+            result = await this.#postCustomerService(messageData);
+        }
         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 }));
         return result.msgid?.toString() || `cs_${Date.now()}`;
     }
+    /**
+     * 客服消息 image 段只接受 media_id：canonical MediaRef（base64/本地路径/URL）
+     * 先经 /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     */
+    async #materializeOutboundMedia(payload) {
+        if (!Array.isArray(payload))
+            return payload;
+        return Promise.all(payload.map(async (item) => {
+            if (typeof item === 'string' || !item || typeof item !== 'object')
+                return item;
+            const seg = item;
+            if (seg.type !== 'image')
+                return item;
+            const data = seg.data ?? {};
+            const media = readOutboundImageMedia(data);
+            if (!media)
+                return item;
+            try {
+                const mediaId = await this.#uploadMedia('image', media);
+                return { type: 'image', data: { mediaId } };
+            }
+            catch (error) {
+                logger.warn(formatCompact({
+                    op: 'wechat_mp_media_upload_failed',
+                    endpoint: this.#options.config.name,
+                    error: error instanceof Error ? error.message : String(error),
+                }));
+                const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
+                return { type: 'text', data: { text: alt } };
+            }
+        }));
+    }
+    /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
+    async #uploadMedia(type, media) {
+        const binary = await resolveMediaBinary(media);
+        const form = buildMediaUploadForm(binary);
+        const url = `https://api.weixin.qq.com/cgi-bin/media/upload?access_token=${this.#accessToken}&type=${type}`;
+        const response = await this.#fetch(url, { method: 'POST', body: form });
+        const data = response.data;
+        if (data.media_id)
+            return data.media_id;
+        throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
+    }
+    async #postCustomerService(messageData) {
+        const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.#accessToken}`;
+        const response = await this.#fetch(url, { method: 'POST', body: messageData });
+        return response.data;
+    }
+    /**
+     * 关注者列表（GET /cgi-bin/user/get，按 next_openid 分页，每页最多 10000）。
+     * 该接口只回 openid 不回昵称；昵称需逐个调 user/info（成本高且依赖用户授权），
+     * 这里 nickname 用 openid 占位，由 Console 侧自行理解。
+     */
+    async getFollowers() {
+        if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
+            await this.#refreshAccessToken();
+        }
+        const friends = [];
+        let nextOpenid = '';
+        do {
+            const url = `https://api.weixin.qq.com/cgi-bin/user/get?access_token=${this.#accessToken}&next_openid=${encodeURIComponent(nextOpenid)}`;
+            const response = await this.#fetch(url);
+            const data = response.data;
+            if (data.errcode && data.errcode !== 0) {
+                throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+            }
+            for (const openid of data.data?.openid ?? []) {
+                if (typeof openid === 'string' && openid) {
+                    friends.push({ user_id: openid, nickname: openid, remark: '' });
+                }
+            }
+            const fetched = Number(data.count ?? 0);
+            nextOpenid = typeof data.next_openid === 'string' ? data.next_openid : '';
+            // 满页（10000）才可能有下一页；不足一页即到底，避免依赖 next_openid 回显语义。
+            if (fetched < 10_000)
+                break;
+        } while (nextOpenid);
+        return friends;
+    }
     async #refreshAccessToken() {
         const { appId, appSecret } = this.#options.config;
         const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
@@ -157,3 +268,9 @@ export class WeChatMpEndpoint {
         }, 3_600_000);
     }
 }
+function createWeChatMpEndpointManagement(endpoint) {
+    return Object.freeze({
+        // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
+        listFriends: () => endpoint.getFollowers(),
+    });
+}

package/lib/index.d.ts

@@ -1,4 +1,5 @@
-export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, type ResolvedWeChatMpConfig, type TokenResponse, type WeChatAPIResponse, type WeChatMessage, type WeChatMpAdapterConfig, type WeChatWireSegment, } from './protocol.js';
+export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, type ResolvedWeChatMpConfig, type TokenResponse, type WeChatAPIResponse, type WeChatMessage, type WeChatMpAdapterConfig, type WeChatWireSegment, } from './protocol.js';
 export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, type PassiveReplyCapture, } from './passive-reply.js';
 export { WeChatMpEndpoint, type WeChatMpEndpointOptions, type WeChatMpFetch, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, type WeChatMediaUploadResult, } from './media-upload.js';
 export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, type WeChatMpWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,4 +1,5 @@
-export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, } from './protocol.js';
+export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, } from './protocol.js';
 export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, } from './passive-reply.js';
 export { WeChatMpEndpoint, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, } from './webhook.js';

package/lib/media-upload.d.ts

@@ -0,0 +1,22 @@
+import { type MediaRef } from '@zhin.js/core';
+export interface MediaBinary {
+    readonly data: Buffer;
+    readonly mimeType: string;
+    readonly fileName: string;
+}
+export interface WeChatMediaUploadResult {
+    readonly type?: string;
+    readonly media_id?: string;
+    readonly created_at?: number;
+    readonly errcode?: number;
+    readonly errmsg?: string;
+}
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export declare function resolveMediaBinary(media: MediaRef, download?: (url: string) => Promise<Buffer>): Promise<MediaBinary>;
+/** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
+export declare function buildMediaUploadForm(binary: MediaBinary): FormData;
+/**
+ * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
+ * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ */
+export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -0,0 +1,60 @@
+/**
+ * WeChat MP 临时素材上传（客服消息 image 段需要 media_id）。
+ * 接口：POST https://api.weixin.qq.com/cgi-bin/media/upload?access_token=…&type=image
+ * 与客服消息同属公众号基础接口域，不引入额外授权域
+ * （客服消息本身要求已认证服务号；订阅号无客服消息权限，上传同样不可用）。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+const MIME_EXT = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/bmp': 'bmp',
+};
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(media, download = defaultDownload) {
+    const mimeType = media.mime_type ?? 'image/png';
+    const ext = MIME_EXT[mimeType] ?? 'png';
+    if (media.kind === 'base64') {
+        const value = media.value.startsWith('base64://')
+            ? media.value.slice('base64://'.length)
+            : media.value;
+        return { data: Buffer.from(value, 'base64'), mimeType, fileName: `image.${ext}` };
+    }
+    if (media.kind === 'path') {
+        const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+        return { data: await readFile(path), mimeType, fileName: basename(path) };
+    }
+    return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+}
+async function defaultDownload(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+    if (!response.ok)
+        throw new Error(`download failed: HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+}
+/** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
+export function buildMediaUploadForm(binary) {
+    // Buffer 的 ArrayBufferLike 不满足 BlobPart（SharedArrayBuffer 分支），拷贝为 Uint8Array<ArrayBuffer>
+    const bytes = new Uint8Array(binary.data.byteLength);
+    bytes.set(binary.data);
+    const form = new FormData();
+    form.append('media', new Blob([bytes], { type: binary.mimeType }), binary.fileName);
+    return form;
+}
+/**
+ * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
+ * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ */
+export function readOutboundImageMedia(data) {
+    if (typeof data.mediaId === 'string' && data.mediaId)
+        return undefined;
+    if (typeof data.media_id === 'string' && data.media_id)
+        return undefined;
+    if (isMediaRef(data.media))
+        return data.media;
+    return mediaRefFromLegacyData(data);
+}

package/lib/protocol.d.ts

@@ -101,6 +101,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;
+/**
+ * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
+ * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。
+ */
+export declare function formatInboundId(msg: WeChatMessage): string;
 /** Build inbound text for MessageGateway.receive. */
 export declare function formatInboundContent(msg: WeChatMessage): string;
 /**

package/lib/protocol.js

@@ -170,6 +170,17 @@ export function buildTextReply(wechatMsg, content) {
         '</xml>',
     ].join('');
 }
+/**
+ * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
+ * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。
+ */
+export function formatInboundId(msg) {
+    if (msg.MsgId)
+        return msg.MsgId;
+    return [msg.CreateTime, msg.Event, msg.EventKey]
+        .filter((part) => part != null && part !== '')
+        .join(':');
+}
 /** Build inbound text for MessageGateway.receive. */
 export function formatInboundContent(msg) {
     switch (msg.MsgType) {

package/lib/webhook.d.ts

@@ -12,6 +12,9 @@ export interface WeChatMpWebhookHandler {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
     admit(msg: WeChatMessage): void;
+    /** 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;

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, 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, } from './protocol.js';
 const logger = getLogger('wechat-mp');
 export function registerWeChatMpWebhookRoutes(http, handler) {
     const path = handler.config.path;
@@ -90,6 +90,17 @@ export async function handleWeChatMpMessage(request, response, url, handler) {
             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') {
@@ -106,6 +117,9 @@ export async function handleWeChatMpMessage(request, response, url, handler) {
         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');
     }
@@ -124,7 +138,7 @@ export async function collectPassiveReply(handler, wechatMsg) {
                 target: wechatMsg.FromUserName,
                 content: formatInboundContent(wechatMsg),
                 sender: wechatMsg.FromUserName,
-                id: wechatMsg.MsgId || `${wechatMsg.CreateTime}`,
+                id: formatInboundId(wechatMsg),
                 metadata: Object.freeze({
                     msgType: wechatMsg.MsgType,
                     event: wechatMsg.Event,

package/lib/wechat-mp-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const wechatMpEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

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

@@ -0,0 +1,19 @@
+/**
+ * `wechat-mp endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { wechatMpRuntimeStateToken } from './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/lib/wechat-mp-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const wechatMpRuntimeStateToken: import("@zhin.js/plugin-runtime").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,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wechat-mp",
-  "version": "3.0.3",
+  "version": "4.0.1",
   "type": "module",
   "description": "Zhin.js WeChat Official Account adapter for Plugin Runtime (HTTP webhook)",
   "main": "./lib/index.js",
@@ -8,18 +8,19 @@
   "dependencies": {
     "axios": "^1.18.0",
     "xml2js": "^0.6.2",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -57,6 +58,7 @@
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -89,6 +91,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,8 +1,14 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin } from '@zhin.js/plugin-runtime';
+import { wechatMpRuntimeStateToken } from './src/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

@@ -3,14 +3,6 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "wechat-mp-bot"
-    },
-    "appId": { "type": "string" },
-    "appSecret": { "type": "string" },
-    "token": { "type": "string" },
-    "encodingAESKey": { "type": "string" },
     "path": {
       "type": "string",
       "default": "/wechat/webhook"
@@ -21,18 +13,68 @@
     },
     "encryptMode": {
       "type": "string",
-      "enum": ["plain", "compatible", "secure"],
+      "enum": [
+        "plain",
+        "compatible",
+        "secure"
+      ],
       "description": "Default follows encrypt: 'plain' when encrypt=false, 'compatible' when encrypt=true"
     },
     "replyMode": {
       "type": "string",
-      "enum": ["passive", "customer_service"],
+      "enum": [
+        "passive",
+        "customer_service"
+      ],
       "default": "passive"
     },
     "passiveReplyTimeoutMs": {
       "type": "number",
       "default": 4500
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "WeChat MP bot name"
+          },
+          "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"
+          }
+        },
+        "required": [
+          "name",
+          "appId",
+          "appSecret",
+          "token"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
   },
-  "required": ["appId", "appSecret", "token"]
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -2,7 +2,7 @@
  * WeChatMpEndpoint — lifecycle, outbound, admit, access token refresh.
  */
 import axios from 'axios';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointFriend, EndpointInstance, EndpointManagement } 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';
@@ -11,11 +11,18 @@ import {
   extractOutboundText,
   formatCustomerServiceBody,
   formatInboundContent,
+  formatInboundId,
   type ResolvedWeChatMpConfig,
   type TokenResponse,
   type WeChatAPIResponse,
   type WeChatMessage,
 } from './protocol.js';
+import {
+  buildMediaUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type WeChatMediaUploadResult,
+} from './media-upload.js';
 import {
   getPassiveReplyCapture,
   recordPassiveReplyText,
@@ -24,6 +31,9 @@ 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]);
+
 export type WeChatMpFetch = (
   url: string,
   init?: { readonly method?: string; readonly body?: unknown; readonly headers?: Record<string, string> },
@@ -56,8 +66,12 @@ export class WeChatMpEndpoint implements EndpointInstance {
   #accessToken: string | null = null;
   #tokenExpireTime = 0;
   #tokenRefreshTimer?: ReturnType<typeof setInterval>;
+  /** MsgId → 首次回复 XML（微信 5s 重推去重，有界 LRU）。 */
+  readonly #replyCache = new Map<string, string>();
+  static readonly #REPLY_CACHE_LIMIT = 1000;
   #open = false;
   #started = false;
+  readonly management: EndpointManagement = createWeChatMpEndpointManagement(this);
 
   constructor(options: WeChatMpEndpointOptions) {
     this.#options = options;
@@ -81,6 +95,21 @@ export class WeChatMpEndpoint implements EndpointInstance {
     return this.#options.gateway;
   }
 
+  /** 微信 5s 重推去重：见过该 MsgId 时返回首次回复 XML（含空串=success）。 */
+  getCachedReply(msgId: string): string | undefined {
+    return this.#replyCache.get(msgId);
+  }
+
+  cacheReply(msgId: string, replyXML: string): void {
+    if (this.#replyCache.has(msgId)) this.#replyCache.delete(msgId);
+    this.#replyCache.set(msgId, replyXML);
+    while (this.#replyCache.size > WeChatMpEndpoint.#REPLY_CACHE_LIMIT) {
+      const oldest = this.#replyCache.keys().next().value;
+      if (oldest === undefined) break;
+      this.#replyCache.delete(oldest);
+    }
+  }
+
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
@@ -147,7 +176,7 @@ export class WeChatMpEndpoint implements EndpointInstance {
       target: msg.FromUserName,
       content: formatInboundContent(msg),
       sender: msg.FromUserName,
-      id: msg.MsgId || `${msg.CreateTime}`,
+      id: formatInboundId(msg),
       metadata: Object.freeze({
         msgType: msg.MsgType,
         event: msg.Event,
@@ -164,11 +193,22 @@ export class WeChatMpEndpoint implements EndpointInstance {
   }
 
   async #sendCustomerService(target: string, payload: unknown): Promise<string> {
-    if (!this.#accessToken) await this.#refreshAccessToken();
-    const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.#accessToken}`;
-    const messageData = formatCustomerServiceBody(target, payload);
-    const response = await this.#fetch(url, { method: 'POST', body: messageData });
-    const result = response.data as WeChatAPIResponse;
+    // 发送前检查过期（不只判 null）：过期 token 直接刷新，不白跑一次 40001。
+    if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
+      await this.#refreshAccessToken();
+    }
+    const materialized = await this.#materializeOutboundMedia(payload);
+    const messageData = formatCustomerServiceBody(target, materialized);
+    let result = await this.#postCustomerService(messageData);
+    if (result.errcode && TOKEN_INVALID_ERRCODES.has(Number(result.errcode))) {
+      // 对端提前作废 token（多端共用等）：刷新后重试一次。
+      logger.warn(formatCompact({
+        op: 'wechat_mp_token_invalid_retry',
+        errcode: result.errcode,
+      }));
+      await this.#refreshAccessToken();
+      result = await this.#postCustomerService(messageData);
+    }
     if (result.errcode && result.errcode !== 0) {
       throw new Error(`WeChat API error: ${result.errcode} - ${result.errmsg}`);
     }
@@ -176,6 +216,86 @@ export class WeChatMpEndpoint implements EndpointInstance {
     return result.msgid?.toString() || `cs_${Date.now()}`;
   }
 
+  /**
+   * 客服消息 image 段只接受 media_id：canonical MediaRef（base64/本地路径/URL）
+   * 先经 /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   */
+  async #materializeOutboundMedia(payload: unknown): Promise<unknown> {
+    if (!Array.isArray(payload)) return payload;
+    return Promise.all(payload.map(async (item) => {
+      if (typeof item === 'string' || !item || typeof item !== 'object') return item;
+      const seg = item as { type?: unknown; data?: Record<string, unknown> };
+      if (seg.type !== 'image') return item;
+      const data = seg.data ?? {};
+      const media = readOutboundImageMedia(data);
+      if (!media) return item;
+      try {
+        const mediaId = await this.#uploadMedia('image', media);
+        return { type: 'image', data: { mediaId } };
+      } catch (error) {
+        logger.warn(formatCompact({
+          op: 'wechat_mp_media_upload_failed',
+          endpoint: this.#options.config.name,
+          error: error instanceof Error ? error.message : String(error),
+        }));
+        const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
+        return { type: 'text', data: { text: alt } };
+      }
+    }));
+  }
+
+  /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
+  async #uploadMedia(type: 'image', media: Parameters<typeof resolveMediaBinary>[0]): Promise<string> {
+    const binary = await resolveMediaBinary(media);
+    const form = buildMediaUploadForm(binary);
+    const url = `https://api.weixin.qq.com/cgi-bin/media/upload?access_token=${this.#accessToken}&type=${type}`;
+    const response = await this.#fetch(url, { method: 'POST', body: form });
+    const data = response.data as WeChatMediaUploadResult;
+    if (data.media_id) return data.media_id;
+    throw new Error(`WeChat media upload failed: ${data.errcode ?? 'unknown'} ${data.errmsg ?? ''}`.trim());
+  }
+
+  async #postCustomerService(messageData: unknown): Promise<WeChatAPIResponse> {
+    const url = `https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=${this.#accessToken}`;
+    const response = await this.#fetch(url, { method: 'POST', body: messageData });
+    return response.data as WeChatAPIResponse;
+  }
+
+  /**
+   * 关注者列表（GET /cgi-bin/user/get，按 next_openid 分页，每页最多 10000）。
+   * 该接口只回 openid 不回昵称；昵称需逐个调 user/info（成本高且依赖用户授权），
+   * 这里 nickname 用 openid 占位，由 Console 侧自行理解。
+   */
+  async getFollowers(): Promise<readonly EndpointFriend[]> {
+    if (!this.#accessToken || Date.now() >= this.#tokenExpireTime) {
+      await this.#refreshAccessToken();
+    }
+    const friends: EndpointFriend[] = [];
+    let nextOpenid = '';
+    do {
+      const url = `https://api.weixin.qq.com/cgi-bin/user/get?access_token=${this.#accessToken}&next_openid=${encodeURIComponent(nextOpenid)}`;
+      const response = await this.#fetch(url);
+      const data = response.data as WeChatAPIResponse & {
+        count?: number;
+        data?: { openid?: string[] };
+        next_openid?: string;
+      };
+      if (data.errcode && data.errcode !== 0) {
+        throw new Error(`WeChat API error: ${data.errcode} - ${data.errmsg}`);
+      }
+      for (const openid of data.data?.openid ?? []) {
+        if (typeof openid === 'string' && openid) {
+          friends.push({ user_id: openid, nickname: openid, remark: '' });
+        }
+      }
+      const fetched = Number(data.count ?? 0);
+      nextOpenid = typeof data.next_openid === 'string' ? data.next_openid : '';
+      // 满页（10000）才可能有下一页；不足一页即到底，避免依赖 next_openid 回显语义。
+      if (fetched < 10_000) break;
+    } while (nextOpenid);
+    return friends;
+  }
+
   async #refreshAccessToken(): Promise<void> {
     const { appId, appSecret } = this.#options.config;
     const url = `https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=${appId}&secret=${appSecret}`;
@@ -204,3 +324,10 @@ export class WeChatMpEndpoint implements EndpointInstance {
     }, 3_600_000);
   }
 }
+
+function createWeChatMpEndpointManagement(endpoint: WeChatMpEndpoint): EndpointManagement {
+  return Object.freeze<EndpointManagement>({
+    // 公众号无群/频道概念；关注者即"好友"（nickname 为 openid 占位，见 getFollowers）。
+    listFriends: () => endpoint.getFollowers(),
+  });
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export {
   extractOutboundText,
   formatCustomerServiceBody,
   formatInboundContent,
+  formatInboundId,
   isEncryptedEchostr,
   normalizeEchostrParam,
   parseXMLMessage,
@@ -36,6 +37,14 @@ export {
   type WeChatMpFetch,
 } from './endpoint.js';
 
+export {
+  buildMediaUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type MediaBinary,
+  type WeChatMediaUploadResult,
+} from './media-upload.js';
+
 export {
   registerWeChatMpWebhookRoutes,
   handleWeChatMpVerification,

package/src/media-upload.ts

@@ -0,0 +1,78 @@
+/**
+ * WeChat MP 临时素材上传（客服消息 image 段需要 media_id）。
+ * 接口：POST https://api.weixin.qq.com/cgi-bin/media/upload?access_token=…&type=image
+ * 与客服消息同属公众号基础接口域，不引入额外授权域
+ * （客服消息本身要求已认证服务号；订阅号无客服消息权限，上传同样不可用）。
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
+
+export interface MediaBinary {
+  readonly data: Buffer;
+  readonly mimeType: string;
+  readonly fileName: string;
+}
+
+export interface WeChatMediaUploadResult {
+  readonly type?: string;
+  readonly media_id?: string;
+  readonly created_at?: number;
+  readonly errcode?: number;
+  readonly errmsg?: string;
+}
+
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/bmp': 'bmp',
+};
+
+/** 从 canonical MediaRef 解析二进制：base64 解码 / 本地读盘 / URL 下载。 */
+export async function resolveMediaBinary(
+  media: MediaRef,
+  download: (url: string) => Promise<Buffer> = defaultDownload,
+): Promise<MediaBinary> {
+  const mimeType = media.mime_type ?? 'image/png';
+  const ext = MIME_EXT[mimeType] ?? 'png';
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('base64://')
+      ? media.value.slice('base64://'.length)
+      : media.value;
+    return { data: Buffer.from(value, 'base64'), mimeType, fileName: `image.${ext}` };
+  }
+  if (media.kind === 'path') {
+    const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
+    return { data: await readFile(path), mimeType, fileName: basename(path) };
+  }
+  return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+}
+
+async function defaultDownload(url: string): Promise<Buffer> {
+  const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
+export function buildMediaUploadForm(binary: MediaBinary): FormData {
+  // Buffer 的 ArrayBufferLike 不满足 BlobPart（SharedArrayBuffer 分支），拷贝为 Uint8Array<ArrayBuffer>
+  const bytes = new Uint8Array(binary.data.byteLength);
+  bytes.set(binary.data);
+  const form = new FormData();
+  form.append('media', new Blob([bytes], { type: binary.mimeType }), binary.fileName);
+  return form;
+}
+
+/**
+ * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
+ * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ */
+export function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined {
+  if (typeof data.mediaId === 'string' && data.mediaId) return undefined;
+  if (typeof data.media_id === 'string' && data.media_id) return undefined;
+  if (isMediaRef(data.media)) return data.media;
+  return mediaRefFromLegacyData(data);
+}

package/src/protocol.ts

@@ -310,6 +310,17 @@ export function buildTextReply(
   ].join('');
 }
 
+/**
+ * 入站消息 id：普通消息用 MsgId；无 MsgId 的事件消息拼 Event/EventKey，
+ * 避免只用秒级 CreateTime 时同秒多事件 id 碰撞。
+ */
+export function formatInboundId(msg: WeChatMessage): string {
+  if (msg.MsgId) return msg.MsgId;
+  return [msg.CreateTime, msg.Event, msg.EventKey]
+    .filter((part) => part != null && part !== '')
+    .join(':');
+}
+
 /** Build inbound text for MessageGateway.receive. */
 export function formatInboundContent(msg: WeChatMessage): string {
   switch (msg.MsgType) {

package/src/webhook.ts

@@ -17,6 +17,7 @@ import {
   decryptMessage,
   encryptMessage,
   formatInboundContent,
+  formatInboundId,
   isEncryptedEchostr,
   normalizeEchostrParam,
   parseXMLMessage,
@@ -36,6 +37,9 @@ export interface WeChatMpWebhookHandler {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
   admit(msg: WeChatMessage): void;
+  /** MsgId 去重缓存（可选；实现见 WeChatMpEndpoint）。 */
+  getCachedReply?(msgId: string): string | undefined;
+  cacheReply?(msgId: string, replyXML: string): void;
 }
 
 export function registerWeChatMpWebhookRoutes(
@@ -157,6 +161,18 @@ export async function handleWeChatMpMessage(
       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) {
@@ -183,6 +199,10 @@ export async function handleWeChatMpMessage(
       );
     }
 
+    if (msgId && handler.cacheReply) {
+      handler.cacheReply(msgId, replyXML || '');
+    }
+
     response.writeHead(200, { 'Content-Type': 'text/xml' });
     response.end(replyXML || 'success');
   } catch (error) {
@@ -204,7 +224,7 @@ export async function collectPassiveReply(
         target: wechatMsg.FromUserName,
         content: formatInboundContent(wechatMsg),
         sender: wechatMsg.FromUserName,
-        id: wechatMsg.MsgId || `${wechatMsg.CreateTime}`,
+        id: formatInboundId(wechatMsg),
         metadata: Object.freeze({
           msgType: wechatMsg.MsgType,
           event: wechatMsg.Event,

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

@@ -0,0 +1,20 @@
+/**
+ * `wechat-mp endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { wechatMpRuntimeStateToken } from './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/src/wechat-mp-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * 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');