@zhin.js/adapter-wecom 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @zhin.js/adapter-wecom
 
+## 3.0.2
+
+### Patch Changes
+
+- d5cd4aa: Publish Plugin Runtime entry points and convention modules as JavaScript so
+  installed npm plugins load on Node without TypeScript stripping. Workspace
+  development continues to prefer TypeScript sources for local HMR.
+
+  Remove the unconsumed legacy game hub APIs from game-kit; game navigation and
+  records now use ordinary convention commands owned by the game hub plugin.
+
+- Updated dependencies [d5cd4aa]
+  - @zhin.js/command@1.0.4
+  - zhin.js@5.0.2
+  - @zhin.js/adapter@1.1.2
+  - @zhin.js/core@1.4.2
+  - @zhin.js/agent@1.0.7
+
+## 3.0.1
+
+### Patch Changes
+
+- cdf64e7: 多方向审计修复批（8 面 30+ bug）：
+
+  - **安全**：钉钉 webhook 验签绕过修复（缺 timestamp/sign 一律 403 + ±1h 防重放）；exec-policy fail-closed（换行/`$(`/反引号拒绝、管道逐段过白名单、env dump 复合拆段）；wecom 验签改 timingSafeEqual；config:set 拒绝 `__proto__` 等魔术键、host 键优先防覆写。
+  - **P0 功能**：`zhin packages` scoped 包名解析为空导致 rm -rf 风险；命令数字参数解析失败炸断消息链路（dispatch 捕获 continue）；TaskQueue 监听器首个事件自摘除导致 assistant 队列挂死（+超时后完成不覆盖终态）；DatabaseHost 跨世代共享崩溃（define 幂等 + stop 改进程级）；rss 按不存在 id 列删除改业务键。
+  - **Runtime/HMR**：native watcher 过滤忽略目录（lib/.zhin 不再触发重载风暴）；host 段配置 patch（http.port 等）存在 installResources 时全量重建；capability 目录非 entry 支持文件升级进程重启；documentTransaction 失败回滚。
+  - **CLI 写侧**：config/setup 对 toml 静默假成功改统一 config-file（不支持格式报错）；doctor/onboard 默认配置改新形态 plugins 映射；schedule add 改 --prompt；migrate engines/中文模板误伤/覆盖前备份。
+  - **适配器生命周期**：napcat/milky start 失败竞态与僵尸连接、心跳 close 清理、stop-during-connect settle；slack webhook 二次 writeHead + messageChannelMap LRU。
+  - **Host/向导**：logs/stats 与 inbox 查询改 DB 侧 count/orderBy/limit 下推；save-yaml 写入前校验；zhipu/moonshot baseUrl 必填预填；.env 写入转义 + 幂等合并；setup 数据库密码不再明文落 config；60s fetch 超时与 JSON 守卫。
+
+- 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（无凭据）暂不接。
+- 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/agent@1.0.6
+  - @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
+
 ## 3.0.0
 
 ### Patch Changes

package/adapters/wecom.js

@@ -0,0 +1,35 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/wecom.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / protocol).
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { WecomEndpoint } from "../lib/endpoint.js";
+import { resolveWecomConfig, } from "../lib/protocol.js";
+import { wecomRuntimeStateToken } from "../lib/wecom-runtime-state.js";
+export { WecomEndpoint } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // image 段经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传）；
+    // 无卡片交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url', 'upload'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveWecomConfig(context.config);
+        // 注册到插件运行时状态（wecom endpoint list 的"运行中"数据源）
+        context.use(wecomRuntimeStateToken).endpoints.set(config.name, {
+            name: config.name,
+            mode: 'webhook',
+        });
+        return new WecomEndpoint({
+            id: context.id,
+            gateway: context.use(messageGatewayToken),
+            http: context.use(httpHostToken),
+            config,
+        });
+    },
+});

package/adapters/wecom.ts

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

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

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wecomEndpointCommands } from "../../../lib/wecom-endpoint-commands.js";
+export default wecomEndpointCommands.add;

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

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

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wecomEndpointCommands } from "../../lib/wecom-endpoint-commands.js";
+export default wecomEndpointCommands.list;

package/commands/endpoint/list.ts

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

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

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { wecomEndpointCommands } from "../../../lib/wecom-endpoint-commands.js";
+export default wecomEndpointCommands.remove;

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

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

package/lib/endpoint.d.ts

@@ -9,7 +9,7 @@ import { type ResolvedWecomConfig, type WecomApiResponse, type WecomMessage } fr
 export type WecomFetch = (url: string, init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
-    readonly body?: string;
+    readonly body?: string | FormData;
 }) => Promise<{
     readonly ok: boolean;
     readonly status: number;
@@ -23,6 +23,11 @@ export interface WecomEndpointOptions {
     readonly config: ResolvedWecomConfig;
     readonly fetch?: WecomFetch;
 }
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
 export declare class WecomEndpoint implements EndpointInstance {
     #private;
     constructor(options: WecomEndpointOptions);

package/lib/endpoint.js

@@ -1,8 +1,14 @@
 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 { registerWecomWebhookRoutes } from './webhook.js';
 const logger = getLogger('wecom');
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
 export class WecomEndpoint {
     #options;
     #fetch;
@@ -59,7 +65,8 @@ export class WecomEndpoint {
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
-        const content = formatOutboundBody(payload);
+        const materialized = await this.#materializeOutboundMedia(payload);
+        const content = formatOutboundBody(materialized);
         const body = buildSendRequestBody(target, content, 
         // Legacy field: historically written into agentid (preserved for cutover).
         this.#options.config.agentSecret);
@@ -73,6 +80,50 @@ export class WecomEndpoint {
         logger.debug(formatCompact({ op: 'send', endpoint: this.#options.config.name, to: target }));
         return data.msgid || `${Date.now()}`;
     }
+    /**
+     * message/send 的 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: { media_id: mediaId } };
+            }
+            catch (error) {
+                logger.warn(formatCompact({
+                    op: 'wecom_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) {
+        await this.#ensureAccessToken();
+        const binary = await resolveMediaBinary(media);
+        const form = buildMediaUploadForm(binary);
+        const url = `${this.#options.config.apiBaseUrl}/cgi-bin/media/upload?access_token=${this.#accessToken.access_token}&type=${type}`;
+        const response = await this.#fetch(url, { method: 'POST', body: form });
+        const data = await response.json();
+        if (data.errcode === 0 && data.media_id)
+            return data.media_id;
+        throw new Error(`WeCom media upload failed: ${data.errmsg ?? 'unknown'} (${data.errcode ?? '?'})`);
+    }
     /** Test / internal: admit a parsed message when open (non-webhook path). */
     admit(msg) {
         if (!this.#open)

package/lib/index.d.ts

@@ -2,4 +2,5 @@ export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInbo
 export { getWecomAgentDeps, registerWecomAgentEndpoint, setWecomAgentDeps, type WecomAgentDeps, type WecomAgentEndpoint, } from './wecom-agent-deps.js';
 export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, registerWecomPlatformPermitChecker, wecomGroupPermitResolver, } from './platform-permit.js';
 export { WecomEndpoint, type WecomEndpointOptions, type WecomFetch, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, type WecomMediaUploadResult, } from './media-upload.js';
 export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, type WecomWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -2,4 +2,5 @@ export { buildSendRequestBody, decryptMessage, extractEncryptFromXml, formatInbo
 export { getWecomAgentDeps, registerWecomAgentEndpoint, setWecomAgentDeps, } from './wecom-agent-deps.js';
 export { checkWecomPlatformPermit, normalizeWecomSenderForPermit, platformPermit, registerWecomPlatformPermitChecker, wecomGroupPermitResolver, } from './platform-permit.js';
 export { WecomEndpoint, } from './endpoint.js';
+export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerWecomWebhookRoutes, handleWecomVerificationRequest, handleWecomWebhookRequest, } 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 WecomMediaUploadResult {
+    readonly errcode?: number;
+    readonly errmsg?: string;
+    readonly type?: string;
+    readonly media_id?: string;
+    readonly created_at?: 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,59 @@
+/**
+ * WeCom 临时素材上传（message/send 的 image 段需要 media_id）。
+ * 接口：POST {apiBaseUrl}/cgi-bin/media/upload?access_token=…&type=image
+ * 与 message/send 同属应用消息接口域（同一 access_token），不引入额外授权域。
+ */
+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.media_id === 'string' && data.media_id)
+        return undefined;
+    if (typeof data.mediaId === 'string' && data.mediaId)
+        return undefined;
+    if (isMediaRef(data.media))
+        return data.media;
+    return mediaRefFromLegacyData(data);
+}

package/lib/protocol.js

@@ -2,7 +2,7 @@
  * WeCom (企业微信) protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { createHash, createDecipheriv } from 'node:crypto';
+import { createHash, createDecipheriv, timingSafeEqual } from 'node:crypto';
 export function resolveWecomConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'wecom');
     const corpId = config.corpId ?? entry?.corpId ?? process.env.WECOM_CORP_ID;
@@ -54,7 +54,11 @@ export function verifySignature(token, timestamp, nonce, encrypt, signature) {
         const hash = createHash('sha1')
             .update([token, timestamp, nonce, encrypt].sort().join(''))
             .digest('hex');
-        return hash === signature;
+        const a = Buffer.from(hash);
+        const b = Buffer.from(signature);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
     }
     catch {
         return false;
@@ -188,7 +192,8 @@ export function formatOutboundBody(payload) {
                 if (!hasMedia) {
                     hasMedia = true;
                     mediaType = 'image';
-                    mediaData = { media_id: data.file || data.url };
+                    // media_id 由 endpoint 上传物化写入；file/url 为旧调用方直传 media_id 的兼容入口。
+                    mediaData = { media_id: data.media_id ?? data.mediaId ?? data.file ?? data.url };
                 }
                 break;
             case 'markdown':

package/lib/wecom-endpoint-commands.d.ts

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

package/lib/wecom-endpoint-commands.js

@@ -0,0 +1,19 @@
+/**
+ * `wecom endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { wecomRuntimeStateToken } from './wecom-runtime-state.js';
+export const wecomEndpointCommands = createEndpointCommands({
+    adapterKey: 'wecom',
+    adapterDisplayName: 'WeCom',
+    fields: [
+        { key: 'corpId', required: true, env: true, description: '企业 corpId' },
+        { key: 'agentSecret', required: true, env: true, description: '应用 secret' },
+        { key: 'token', required: true, env: true, description: '回调 token' },
+        { key: 'encodingAESKey', required: true, env: true, description: '回调加解密 key' },
+    ],
+    running: (use) => use(wecomRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `corpId: ${String(entry.corpId)}`,
+}, defineCommand);

package/lib/wecom-runtime-state.d.ts

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

package/lib/wecom-runtime-state.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,20 +34,21 @@
     "directory": "plugins/adapters/wecom"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
+    "@zhin.js/adapter": "1.1.2",
+    "@zhin.js/command": "1.0.4",
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/agent": "1.0.5",
-    "@zhin.js/core": "1.4.0",
-    "@zhin.js/host-http": "1.0.2",
-    "@zhin.js/plugin-runtime": "1.1.0",
-    "zhin.js": "5.0.0"
+    "@zhin.js/adapter": "1.1.2",
+    "@zhin.js/agent": "1.0.7",
+    "@zhin.js/core": "1.4.2",
+    "@zhin.js/host-http": "1.0.3",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.2"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -65,12 +66,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.5",
-    "zhin.js": "5.0.0"
+    "@zhin.js/agent": "1.0.7",
+    "zhin.js": "5.0.2"
   },
   "files": [
     "adapters",
-    "plugin.ts",
+    "commands",
+    "plugin.js",
     "schema.json",
     "src",
     "lib",
@@ -88,13 +90,17 @@
   "zhin": {
     "protocol": 1,
     "type": "plugin",
-    "entry": "./plugin.ts",
+    "entry": "./plugin.js",
     "engine": "^1.0.0",
     "runtime": "trusted",
     "features": [
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
+import { definePlugin } from '@zhin.js/plugin-runtime';
+import { registerWecomPlatformPermitChecker } from "./lib/platform-permit.js";
+import { wecomRuntimeStateToken } from "./lib/wecom-runtime-state.js";
+export default definePlugin({
+    name: 'wecom',
+    metadata: {
+        displayName: 'WeCom (企业微信) Adapter',
+    },
+    setup(context) {
+        // 运行中 endpoint 注册表（wecom endpoint list 的"运行中"数据源）
+        context.resources.provide(wecomRuntimeStateToken, createEndpointRuntimeState());
+        return registerWecomPlatformPermitChecker();
+    },
+});

package/src/endpoint.ts

@@ -7,6 +7,12 @@ import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { registerWecomAgentEndpoint } from './wecom-agent-deps.js';
+import {
+  buildMediaUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type WecomMediaUploadResult,
+} from './media-upload.js';
 import {
   buildSendRequestBody,
   formatInboundContent,
@@ -26,7 +32,7 @@ export type WecomFetch = (
   init?: {
     readonly method?: string;
     readonly headers?: Record<string, string>;
-    readonly body?: string;
+    readonly body?: string | FormData;
   },
 ) => Promise<{
   readonly ok: boolean;
@@ -43,6 +49,11 @@ export interface WecomEndpointOptions {
   readonly fetch?: WecomFetch;
 }
 
+/**
+ * 企业微信服务端 API 无 bot 群列表/群成员列表接口（客户群接口属「客户联系」
+ * 独立授权域，非 bot 社交面），好友/频道概念亦不存在；
+ * 因此本 endpoint 不暴露 EndpointManagement（Console 社交面 RPC 对该平台保持未接线）。
+ */
 export class WecomEndpoint implements EndpointInstance {
   readonly #options: WecomEndpointOptions;
   readonly #fetch: WecomFetch;
@@ -104,7 +115,8 @@ export class WecomEndpoint implements EndpointInstance {
   }
 
   async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const content = formatOutboundBody(payload);
+    const materialized = await this.#materializeOutboundMedia(payload);
+    const content = formatOutboundBody(materialized);
     const body = buildSendRequestBody(
       target,
       content,
@@ -122,6 +134,46 @@ export class WecomEndpoint implements EndpointInstance {
     return (data.msgid as string) || `${Date.now()}`;
   }
 
+  /**
+   * message/send 的 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: { media_id: mediaId } };
+      } catch (error) {
+        logger.warn(formatCompact({
+          op: 'wecom_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> {
+    await this.#ensureAccessToken();
+    const binary = await resolveMediaBinary(media);
+    const form = buildMediaUploadForm(binary);
+    const url = `${this.#options.config.apiBaseUrl}/cgi-bin/media/upload?access_token=${this.#accessToken.access_token}&type=${type}`;
+    const response = await this.#fetch(url, { method: 'POST', body: form });
+    const data = await response.json() as WecomMediaUploadResult;
+    if (data.errcode === 0 && data.media_id) return data.media_id;
+    throw new Error(`WeCom media upload failed: ${data.errmsg ?? 'unknown'} (${data.errcode ?? '?'})`);
+  }
+
   /** Test / internal: admit a parsed message when open (non-webhook path). */
   admit(msg: WecomMessage): void {
     if (!this.#open) return;

package/src/index.ts

@@ -44,6 +44,14 @@ export {
   type WecomFetch,
 } from './endpoint.js';
 
+export {
+  buildMediaUploadForm,
+  readOutboundImageMedia,
+  resolveMediaBinary,
+  type MediaBinary,
+  type WecomMediaUploadResult,
+} from './media-upload.js';
+
 export {
   registerWecomWebhookRoutes,
   handleWecomVerificationRequest,

package/src/media-upload.ts

@@ -0,0 +1,77 @@
+/**
+ * WeCom 临时素材上传（message/send 的 image 段需要 media_id）。
+ * 接口：POST {apiBaseUrl}/cgi-bin/media/upload?access_token=…&type=image
+ * 与 message/send 同属应用消息接口域（同一 access_token），不引入额外授权域。
+ */
+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 WecomMediaUploadResult {
+  readonly errcode?: number;
+  readonly errmsg?: string;
+  readonly type?: string;
+  readonly media_id?: string;
+  readonly created_at?: 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.media_id === 'string' && data.media_id) return undefined;
+  if (typeof data.mediaId === 'string' && data.mediaId) return undefined;
+  if (isMediaRef(data.media)) return data.media;
+  return mediaRefFromLegacyData(data);
+}

package/src/protocol.ts

@@ -3,7 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 
-import { createHash, createDecipheriv } from 'node:crypto';
+import { createHash, createDecipheriv, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
@@ -149,7 +149,10 @@ export function verifySignature(
     const hash = createHash('sha1')
       .update([token, timestamp, nonce, encrypt].sort().join(''))
       .digest('hex');
-    return hash === signature;
+    const a = Buffer.from(hash);
+    const b = Buffer.from(signature);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
   } catch {
     return false;
   }
@@ -289,7 +292,8 @@ export function formatOutboundBody(payload: unknown): WecomSendBody {
         if (!hasMedia) {
           hasMedia = true;
           mediaType = 'image';
-          mediaData = { media_id: data.file || data.url };
+          // media_id 由 endpoint 上传物化写入；file/url 为旧调用方直传 media_id 的兼容入口。
+          mediaData = { media_id: data.media_id ?? data.mediaId ?? data.file ?? data.url };
         }
         break;
       case 'markdown':

package/src/wecom-endpoint-commands.ts

@@ -0,0 +1,20 @@
+/**
+ * `wecom endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { wecomRuntimeStateToken } from './wecom-runtime-state.js';
+
+export const wecomEndpointCommands = createEndpointCommands({
+  adapterKey: 'wecom',
+  adapterDisplayName: 'WeCom',
+  fields: [
+    { key: 'corpId', required: true, env: true, description: '企业 corpId' },
+    { key: 'agentSecret', required: true, env: true, description: '应用 secret' },
+    { key: 'token', required: true, env: true, description: '回调 token' },
+    { key: 'encodingAESKey', required: true, env: true, description: '回调加解密 key' },
+  ],
+  running: (use) => use(wecomRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `corpId: ${String(entry.corpId)}`,
+}, defineCommand);

package/src/wecom-runtime-state.ts

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

package/plugin.ts

@@ -1,12 +0,0 @@
-import { definePlugin } from '@zhin.js/plugin-runtime';
-import { registerWecomPlatformPermitChecker } from './src/platform-permit.js';
-
-export default definePlugin({
-  name: 'wecom',
-  metadata: {
-    displayName: 'WeCom (企业微信) Adapter',
-  },
-  setup() {
-    return registerWecomPlatformPermitChecker();
-  },
-});