@yanhaidao/wecom 2.0.2 → 2.2.4

package/src/channel.ts

@@ -6,15 +6,15 @@ import type {
 import {
   buildChannelConfigSchema,
   DEFAULT_ACCOUNT_ID,
-  deleteAccountFromConfigSection,
-  formatPairingApproveHint,
   setAccountEnabledInConfigSection,
 } from "openclaw/plugin-sdk";
 
-import { listWecomAccountIds, resolveDefaultWecomAccountId, resolveWecomAccount } from "./accounts.js";
-import { WecomConfigSchema } from "./config-schema.js";
-import type { ResolvedWecomAccount } from "./types.js";
-import { registerWecomWebhookTarget } from "./monitor.js";
+import { resolveWecomAccounts } from "./config/index.js";
+import { WecomConfigSchema } from "./config/index.js";
+import type { ResolvedAgentAccount, ResolvedBotAccount } from "./types/index.js";
+import { registerAgentWebhookTarget, registerWecomWebhookTarget } from "./monitor.js";
+import { wecomOnboardingAdapter } from "./onboarding.js";
+import { wecomOutbound } from "./outbound.js";
 
 const meta = {
   id: "wecom",
@@ -34,12 +34,43 @@ function normalizeWecomMessagingTarget(raw: string): string | undefined {
   return trimmed.replace(/^(wecom|wechatwork|wework|qywx):/i, "").trim() || undefined;
 }
 
+type ResolvedWecomAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  bot?: ResolvedBotAccount;
+  agent?: ResolvedAgentAccount;
+};
+
+/**
+ * **resolveWecomAccount (解析账号配置)**
+ * 
+ * 从全局配置中解析出 WeCom 渠道的配置状态。
+ * 兼容 Bot 和 Agent 两种模式的配置检查。
+ */
+function resolveWecomAccount(cfg: OpenClawConfig): ResolvedWecomAccount {
+  const enabled = (cfg.channels?.wecom as { enabled?: boolean } | undefined)?.enabled !== false;
+  const accounts = resolveWecomAccounts(cfg);
+  const bot = accounts.bot;
+  const agent = accounts.agent;
+  const configured = Boolean(bot?.configured || agent?.configured);
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    enabled,
+    configured,
+    bot,
+    agent,
+  };
+}
+
 export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
   id: "wecom",
   meta,
+  onboarding: wecomOnboardingAdapter,
   capabilities: {
     chatTypes: ["direct", "group"],
-    media: false,
+    media: true,
     reactions: false,
     threads: false,
     polls: false,
@@ -49,9 +80,9 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
   reload: { configPrefixes: ["channels.wecom"] },
   configSchema: buildChannelConfigSchema(WecomConfigSchema),
   config: {
-    listAccountIds: (cfg) => listWecomAccountIds(cfg as OpenClawConfig),
-    resolveAccount: (cfg, accountId) => resolveWecomAccount({ cfg: cfg as OpenClawConfig, accountId }),
-    defaultAccountId: (cfg) => resolveDefaultWecomAccountId(cfg as OpenClawConfig),
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg) => resolveWecomAccount(cfg as OpenClawConfig),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
     setAccountEnabled: ({ cfg, accountId, enabled }) =>
       setAccountEnabledInConfigSection({
         cfg: cfg as OpenClawConfig,
@@ -60,24 +91,28 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         enabled,
         allowTopLevel: true,
       }),
-    deleteAccount: ({ cfg, accountId }) =>
-      deleteAccountFromConfigSection({
-        cfg: cfg as OpenClawConfig,
-        sectionKey: "wecom",
-        clearBaseFields: ["name", "webhookPath", "token", "encodingAESKey", "receiveId", "streamPlaceholderContent", "welcomeText"],
-        accountId,
-      }),
+    deleteAccount: ({ cfg }) => {
+      const next = { ...(cfg as OpenClawConfig) };
+      if (next.channels?.wecom) {
+        const channels = { ...(next.channels ?? {}) } as Record<string, unknown>;
+        delete (channels as Record<string, unknown>).wecom;
+        return { ...next, channels } as OpenClawConfig;
+      }
+      return next;
+    },
     isConfigured: (account) => account.configured,
     describeAccount: (account): ChannelAccountSnapshot => ({
       accountId: account.accountId,
       name: account.name,
       enabled: account.enabled,
       configured: account.configured,
-      webhookPath: account.config.webhookPath ?? "/wecom",
+      webhookPath: account.bot?.config ? "/wecom/bot" : account.agent?.config ? "/wecom/agent" : "/wecom",
     }),
     resolveAllowFrom: ({ cfg, accountId }) => {
-      const account = resolveWecomAccount({ cfg: cfg as OpenClawConfig, accountId });
-      return (account.config.dm?.allowFrom ?? []).map((entry) => String(entry));
+      const account = resolveWecomAccount(cfg as OpenClawConfig);
+      // 与其他渠道保持一致：直接返回 allowFrom，空则允许所有人
+      const allowFrom = account.agent?.config.dm?.allowFrom ?? account.bot?.config.dm?.allowFrom ?? [];
+      return allowFrom.map((entry) => String(entry));
     },
     formatAllowFrom: ({ allowFrom }) =>
       allowFrom
@@ -85,21 +120,7 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
         .filter(Boolean)
         .map((entry) => entry.toLowerCase()),
   },
-  security: {
-    resolveDmPolicy: ({ cfg, accountId, account }) => {
-      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
-      const useAccountPath = Boolean((cfg as OpenClawConfig).channels?.wecom?.accounts?.[resolvedAccountId]);
-      const basePath = useAccountPath ? `channels.wecom.accounts.${resolvedAccountId}.` : "channels.wecom.";
-      return {
-        policy: account.config.dm?.policy ?? "pairing",
-        allowFrom: (account.config.dm?.allowFrom ?? []).map((entry) => String(entry)),
-        policyPath: `${basePath}dm.policy`,
-        allowFromPath: `${basePath}dm.allowFrom`,
-        approveHint: formatPairingApproveHint("wecom"),
-        normalizeEntry: (raw) => raw.trim().toLowerCase(),
-      };
-    },
-  },
+  // security 配置在 WeCom 中不需要，框架会通过 resolveAllowFrom 自动判断
   groups: {
     // WeCom bots are usually mention-gated by the platform in groups already.
     resolveRequireMention: () => true,
@@ -115,17 +136,7 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
     },
   },
   outbound: {
-    deliveryMode: "direct",
-    chunkerMode: "text",
-    textChunkLimit: 20480,
-    sendText: async () => {
-      return {
-        channel: "wecom",
-        ok: false,
-        messageId: "",
-        error: new Error("WeCom intelligent bot only supports replying within callbacks (no standalone sendText)."),
-      };
-    },
+    ...wecomOutbound,
   },
   status: {
     defaultRuntime: {
@@ -153,46 +164,82 @@ export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
       name: account.name,
       enabled: account.enabled,
       configured: account.configured,
-      webhookPath: account.config.webhookPath ?? "/wecom",
+      webhookPath: account.bot?.config ? "/wecom/bot" : account.agent?.config ? "/wecom/agent" : "/wecom",
       running: runtime?.running ?? false,
       lastStartAt: runtime?.lastStartAt ?? null,
       lastStopAt: runtime?.lastStopAt ?? null,
       lastError: runtime?.lastError ?? null,
       lastInboundAt: runtime?.lastInboundAt ?? null,
       lastOutboundAt: runtime?.lastOutboundAt ?? null,
-      dmPolicy: account.config.dm?.policy ?? "pairing",
+      dmPolicy: account.bot?.config.dm?.policy ?? "pairing",
     }),
   },
   gateway: {
+    /**
+     * **startAccount (启动账号)**
+     * 
+     * 插件生命周期：启动
+     * 职责：
+     * 1. 检查配置是否有效。
+     * 2. 注册 Bot Webhook (`/wecom`, `/wecom/bot`)。
+     * 3. 注册 Agent Webhook (`/wecom/agent`)。
+     * 4. 更新运行时状态 (Running)。
+     * 5. 返回停止回调 (Cleanup)。
+     */
     startAccount: async (ctx) => {
       const account = ctx.account;
-      if (!account.configured) {
+      const bot = account.bot;
+      const agent = account.agent;
+      const botConfigured = Boolean(bot?.configured);
+      const agentConfigured = Boolean(agent?.configured);
+
+      if (!botConfigured && !agentConfigured) {
         ctx.log?.warn(`[${account.accountId}] wecom not configured; skipping webhook registration`);
         ctx.setStatus({ accountId: account.accountId, running: false, configured: false });
-        return { stop: () => {} };
+        return { stop: () => { } };
       }
-      const path = (account.config.webhookPath ?? "/wecom").trim();
-      const unregister = registerWecomWebhookTarget({
-        account,
-        config: ctx.cfg as OpenClawConfig,
-        runtime: ctx.runtime,
-        // The HTTP handler resolves the active PluginRuntime via getWecomRuntime().
-        // The stored target only needs to be decrypt/verify-capable.
-        core: ({} as unknown) as any,
-        path,
-        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
-      });
-      ctx.log?.info(`[${account.accountId}] wecom webhook registered at ${path}`);
+
+      const unregisters: Array<() => void> = [];
+      if (bot && botConfigured) {
+        for (const path of ["/wecom", "/wecom/bot"]) {
+          unregisters.push(
+            registerWecomWebhookTarget({
+              account: bot,
+              config: ctx.cfg as OpenClawConfig,
+              runtime: ctx.runtime,
+              // The HTTP handler resolves the active PluginRuntime via getWecomRuntime().
+              // The stored target only needs to be decrypt/verify-capable.
+              core: ({} as unknown) as any,
+              path,
+              statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+            }),
+          );
+        }
+        ctx.log?.info(`[${account.accountId}] wecom bot webhook registered at /wecom and /wecom/bot`);
+      }
+      if (agent && agentConfigured) {
+        unregisters.push(
+          registerAgentWebhookTarget({
+            agent,
+            config: ctx.cfg as OpenClawConfig,
+            runtime: ctx.runtime,
+          }),
+        );
+        ctx.log?.info(`[${account.accountId}] wecom agent webhook registered at /wecom/agent`);
+      }
+
       ctx.setStatus({
         accountId: account.accountId,
         running: true,
         configured: true,
-        webhookPath: path,
+        webhookPath: botConfigured ? "/wecom/bot" : "/wecom/agent",
         lastStartAt: Date.now(),
       });
       return {
         stop: () => {
-          unregister();
+          for (const unregister of unregisters) {
+            unregister();
+          }
           ctx.setStatus({
             accountId: account.accountId,
             running: false,

package/src/config/accounts.ts

@@ -0,0 +1,99 @@
+/**
+ * WeCom 账号解析与模式检测
+ */
+
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type {
+    WecomConfig,
+    WecomBotConfig,
+    WecomAgentConfig,
+    WecomNetworkConfig,
+    ResolvedBotAccount,
+    ResolvedAgentAccount,
+    ResolvedMode,
+    ResolvedWecomAccounts,
+} from "../types/index.js";
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+/**
+ * 检测配置中启用的模式
+ */
+export function detectMode(config: WecomConfig | undefined): ResolvedMode {
+    if (!config) return { bot: false, agent: false };
+
+    const botConfigured = Boolean(
+        config.bot?.token && config.bot?.encodingAESKey
+    );
+    const agentConfigured = Boolean(
+        config.agent?.corpId && config.agent?.corpSecret && config.agent?.agentId &&
+        config.agent?.token && config.agent?.encodingAESKey
+    );
+
+    return { bot: botConfigured, agent: agentConfigured };
+}
+
+/**
+ * 解析 Bot 模式账号
+ */
+function resolveBotAccount(config: WecomBotConfig): ResolvedBotAccount {
+    return {
+        accountId: DEFAULT_ACCOUNT_ID,
+        enabled: true,
+        configured: Boolean(config.token && config.encodingAESKey),
+        token: config.token,
+        encodingAESKey: config.encodingAESKey,
+        receiveId: config.receiveId?.trim() ?? "",
+        config,
+    };
+}
+
+/**
+ * 解析 Agent 模式账号
+ */
+function resolveAgentAccount(config: WecomAgentConfig, network?: WecomNetworkConfig): ResolvedAgentAccount {
+    const agentIdRaw = config.agentId;
+    const agentId = typeof agentIdRaw === "number" ? agentIdRaw : Number(agentIdRaw);
+
+    return {
+        accountId: DEFAULT_ACCOUNT_ID,
+        enabled: true,
+        configured: Boolean(
+            config.corpId && config.corpSecret && agentId &&
+            config.token && config.encodingAESKey
+        ),
+        corpId: config.corpId,
+        corpSecret: config.corpSecret,
+        agentId,
+        token: config.token,
+        encodingAESKey: config.encodingAESKey,
+        config,
+        network,
+    };
+}
+
+/**
+ * 解析 WeCom 账号 (双模式)
+ */
+export function resolveWecomAccounts(cfg: OpenClawConfig): ResolvedWecomAccounts {
+    const wecom = cfg.channels?.wecom as WecomConfig | undefined;
+
+    if (!wecom || wecom.enabled === false) {
+        return {};
+    }
+
+    const mode = detectMode(wecom);
+
+    return {
+        bot: mode.bot && wecom.bot ? { ...resolveBotAccount(wecom.bot), network: wecom.network } : undefined,
+        agent: mode.agent && wecom.agent ? resolveAgentAccount(wecom.agent, wecom.network) : undefined,
+    };
+}
+
+/**
+ * 检查是否有任何模式启用
+ */
+export function isWecomEnabled(cfg: OpenClawConfig): boolean {
+    const accounts = resolveWecomAccounts(cfg);
+    return Boolean(accounts.bot?.configured || accounts.agent?.configured);
+}

package/src/config/index.ts

@@ -0,0 +1,11 @@
+/**
+ * WeCom 配置模块导出
+ */
+
+export { WecomConfigSchema, type WecomConfigInput } from "./schema.js";
+export {
+    detectMode,
+    resolveWecomAccounts,
+    isWecomEnabled,
+} from "./accounts.js";
+export { resolveWecomEgressProxyUrl, resolveWecomEgressProxyUrlFromNetwork } from "./network.js";

package/src/config/network.ts

@@ -0,0 +1,16 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+import type { WecomConfig, WecomNetworkConfig } from "../types/index.js";
+
+export function resolveWecomEgressProxyUrlFromNetwork(network?: WecomNetworkConfig): string | undefined {
+  const env = (process.env.OPENCLAW_WECOM_EGRESS_PROXY_URL ?? process.env.WECOM_EGRESS_PROXY_URL ?? "").trim();
+  if (env) return env;
+
+  const fromCfg = network?.egressProxyUrl?.trim() ?? "";
+  return fromCfg || undefined;
+}
+
+export function resolveWecomEgressProxyUrl(cfg: OpenClawConfig): string | undefined {
+  const wecom = cfg.channels?.wecom as WecomConfig | undefined;
+  return resolveWecomEgressProxyUrlFromNetwork(wecom?.network);
+}

package/src/config/schema.ts

@@ -0,0 +1,104 @@
+/**
+ * WeCom 配置 Schema (Zod)
+ */
+
+import { z } from "zod";
+
+/**
+ * **dmSchema (单聊配置)**
+ * 
+ * 控制单聊行为（如允许名单、策略）。
+ * @property enabled - 是否启用单聊 [默认: true]
+ * @property policy - 访问策略: "pairing" (需配对, 默认), "allowlist" (仅在名单), "open" (所有人), "disabled" (禁用)
+ * @property allowFrom - 允许的用户ID或群ID列表 (仅当 policy="allowlist" 时生效)
+ */
+const dmSchema = z.object({
+    enabled: z.boolean().optional(),
+    policy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+}).optional();
+
+/**
+ * **mediaSchema (媒体处理配置)**
+ * 
+ * 控制媒体文件的下载和缓存行为。
+ * @property tempDir - 临时文件下载目录
+ * @property retentionHours - 临时文件保留时间（小时）
+ * @property cleanupOnStart - 启动时是否自动清理旧文件
+ * @property maxBytes - 允许下载的最大字节数
+ */
+const mediaSchema = z.object({
+    tempDir: z.string().optional(),
+    retentionHours: z.number().optional(),
+    cleanupOnStart: z.boolean().optional(),
+    maxBytes: z.number().optional(),
+}).optional();
+
+/**
+ * **networkSchema (网络配置)**
+ * 
+ * 控制 HTTP 请求行为，特别是出站代理。
+ * @property timeoutMs - 请求超时时间 (毫秒)
+ * @property retries - 重试次数
+ * @property retryDelayMs - 重试间隔 (毫秒)
+ * @property egressProxyUrl - 出站 HTTP 代理 (如 "http://127.0.0.1:7890")
+ */
+const networkSchema = z.object({
+    timeoutMs: z.number().optional(),
+    retries: z.number().optional(),
+    retryDelayMs: z.number().optional(),
+    egressProxyUrl: z.string().optional(),
+}).optional();
+
+/**
+ * **botSchema (Bot 模式配置)**
+ * 
+ * 用于配置企业微信内部机器人 (Webhook 模式)。
+ * @property token - 企业微信后台设置的 Token
+ * @property encodingAESKey - 企业微信后台设置的 EncodingAESKey
+ * @property receiveId - (可选) 接收者ID，通常不用填
+ * @property streamPlaceholderContent - (可选) 流式响应中的占位符，默认为 "Thinking..."或空
+ * @property welcomeText - (可选) 用户首次对话时的欢迎语
+ * @property dm - 单聊策略覆盖配置
+ */
+const botSchema = z.object({
+    token: z.string(),
+    encodingAESKey: z.string(),
+    receiveId: z.string().optional(),
+    streamPlaceholderContent: z.string().optional(),
+    welcomeText: z.string().optional(),
+    dm: dmSchema,
+}).optional();
+
+/**
+ * **agentSchema (Agent 模式配置)**
+ * 
+ * 用于配置企业微信自建应用 (Agent)。
+ * @property corpId - 企业 ID (CorpID)
+ * @property corpSecret - 应用 Secret
+ * @property agentId - 应用 AgentId (数字)
+ * @property token - 回调配置 Token
+ * @property encodingAESKey - 回调配置 EncodingAESKey
+ * @property welcomeText - (可选) 欢迎语
+ * @property dm - 单聊策略覆盖配置
+ */
+const agentSchema = z.object({
+    corpId: z.string(),
+    corpSecret: z.string(),
+    agentId: z.union([z.string(), z.number()]),
+    token: z.string(),
+    encodingAESKey: z.string(),
+    welcomeText: z.string().optional(),
+    dm: dmSchema,
+}).optional();
+
+/** 顶层 WeCom 配置 Schema */
+export const WecomConfigSchema = z.object({
+    enabled: z.boolean().optional(),
+    bot: botSchema,
+    agent: agentSchema,
+    media: mediaSchema,
+    network: networkSchema,
+});
+
+export type WecomConfigInput = z.infer<typeof WecomConfigSchema>;

package/src/config-schema.ts

@@ -20,6 +20,7 @@ export const WecomConfigSchema = z.object({
   receiveId: z.string().optional(),
 
   streamPlaceholderContent: z.string().optional(),
+  debounceMs: z.number().optional(),
 
   welcomeText: z.string().optional(),
   dm: dmSchema,
@@ -33,6 +34,7 @@ export const WecomConfigSchema = z.object({
     encodingAESKey: z.string().optional(),
     receiveId: z.string().optional(),
     streamPlaceholderContent: z.string().optional(),
+    debounceMs: z.number().optional(),
     welcomeText: z.string().optional(),
     dm: dmSchema,
   })).optional(),

package/src/crypto/aes.ts

@@ -0,0 +1,108 @@
+/**
+ * WeCom AES-256-CBC 加解密核心
+ * Bot 和 Agent 模式共用
+ */
+
+import crypto from "node:crypto";
+import { CRYPTO } from "../types/constants.js";
+
+export function decodeEncodingAESKey(encodingAESKey: string): Buffer {
+    const trimmed = encodingAESKey.trim();
+    if (!trimmed) throw new Error("encodingAESKey missing");
+    const withPadding = trimmed.endsWith("=") ? trimmed : `${trimmed}=`;
+    const key = Buffer.from(withPadding, "base64");
+    if (key.length !== CRYPTO.AES_KEY_LENGTH) {
+        throw new Error(`invalid encodingAESKey (expected ${CRYPTO.AES_KEY_LENGTH} bytes, got ${key.length})`);
+    }
+    return key;
+}
+
+function pkcs7Pad(buf: Buffer, blockSize: number): Buffer {
+    const mod = buf.length % blockSize;
+    const pad = mod === 0 ? blockSize : blockSize - mod;
+    const padByte = Buffer.from([pad]);
+    return Buffer.concat([buf, Buffer.alloc(pad, padByte[0]!)]);
+}
+
+export function pkcs7Unpad(buf: Buffer, blockSize: number): Buffer {
+    if (buf.length === 0) throw new Error("invalid pkcs7 payload");
+    const pad = buf[buf.length - 1]!;
+    if (pad < 1 || pad > blockSize) {
+        throw new Error("invalid pkcs7 padding");
+    }
+    if (pad > buf.length) {
+        throw new Error("invalid pkcs7 payload");
+    }
+    for (let i = 0; i < pad; i += 1) {
+        if (buf[buf.length - 1 - i] !== pad) {
+            throw new Error("invalid pkcs7 padding");
+        }
+    }
+    return buf.subarray(0, buf.length - pad);
+}
+
+/**
+ * 解密 WeCom 加密消息
+ */
+export function decryptWecomEncrypted(params: {
+    encodingAESKey: string;
+    receiveId?: string;
+    encrypt: string;
+}): string {
+    const aesKey = decodeEncodingAESKey(params.encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+    const decipher = crypto.createDecipheriv("aes-256-cbc", aesKey, iv);
+    decipher.setAutoPadding(false);
+    const decryptedPadded = Buffer.concat([
+        decipher.update(Buffer.from(params.encrypt, "base64")),
+        decipher.final(),
+    ]);
+    const decrypted = pkcs7Unpad(decryptedPadded, CRYPTO.PKCS7_BLOCK_SIZE);
+
+    if (decrypted.length < 20) {
+        throw new Error(`invalid payload (expected >=20 bytes, got ${decrypted.length})`);
+    }
+
+    // 16 bytes random + 4 bytes length + msg + receiveId
+    const msgLen = decrypted.readUInt32BE(16);
+    const msgStart = 20;
+    const msgEnd = msgStart + msgLen;
+    if (msgEnd > decrypted.length) {
+        throw new Error(`invalid msg length (msgEnd=${msgEnd}, total=${decrypted.length})`);
+    }
+    const msg = decrypted.subarray(msgStart, msgEnd).toString("utf8");
+
+    const receiveId = params.receiveId ?? "";
+    if (receiveId) {
+        const trailing = decrypted.subarray(msgEnd).toString("utf8");
+        if (trailing !== receiveId) {
+            throw new Error(`receiveId mismatch (expected "${receiveId}", got "${trailing}")`);
+        }
+    }
+
+    return msg;
+}
+
+/**
+ * 加密明文为 WeCom 格式
+ */
+export function encryptWecomPlaintext(params: {
+    encodingAESKey: string;
+    receiveId?: string;
+    plaintext: string;
+}): string {
+    const aesKey = decodeEncodingAESKey(params.encodingAESKey);
+    const iv = aesKey.subarray(0, 16);
+    const random16 = crypto.randomBytes(16);
+    const msg = Buffer.from(params.plaintext ?? "", "utf8");
+    const msgLen = Buffer.alloc(4);
+    msgLen.writeUInt32BE(msg.length, 0);
+    const receiveId = Buffer.from(params.receiveId ?? "", "utf8");
+
+    const raw = Buffer.concat([random16, msgLen, msg, receiveId]);
+    const padded = pkcs7Pad(raw, CRYPTO.PKCS7_BLOCK_SIZE);
+    const cipher = crypto.createCipheriv("aes-256-cbc", aesKey, iv);
+    cipher.setAutoPadding(false);
+    const encrypted = Buffer.concat([cipher.update(padded), cipher.final()]);
+    return encrypted.toString("base64");
+}

package/src/crypto/index.ts

@@ -0,0 +1,24 @@
+/**
+ * WeCom 加解密模块导出
+ */
+
+// AES 加解密
+export {
+    decodeEncodingAESKey,
+    pkcs7Unpad,
+    decryptWecomEncrypted,
+    encryptWecomPlaintext,
+} from "./aes.js";
+
+// 签名验证
+export {
+    computeWecomMsgSignature,
+    verifyWecomSignature,
+} from "./signature.js";
+
+// XML 辅助
+export {
+    extractEncryptFromXml,
+    extractToUserNameFromXml,
+    buildEncryptedXmlResponse,
+} from "./xml.js";

package/src/crypto/signature.ts

@@ -0,0 +1,43 @@
+/**
+ * WeCom 签名计算与验证
+ */
+
+import crypto from "node:crypto";
+
+function sha1Hex(input: string): string {
+    return crypto.createHash("sha1").update(input).digest("hex");
+}
+
+/**
+ * 计算 WeCom 消息签名
+ */
+export function computeWecomMsgSignature(params: {
+    token: string;
+    timestamp: string;
+    nonce: string;
+    encrypt: string;
+}): string {
+    const parts = [params.token, params.timestamp, params.nonce, params.encrypt]
+        .map((v) => String(v ?? ""))
+        .sort();
+    return sha1Hex(parts.join(""));
+}
+
+/**
+ * 验证 WeCom 消息签名
+ */
+export function verifyWecomSignature(params: {
+    token: string;
+    timestamp: string;
+    nonce: string;
+    encrypt: string;
+    signature: string;
+}): boolean {
+    const expected = computeWecomMsgSignature({
+        token: params.token,
+        timestamp: params.timestamp,
+        nonce: params.nonce,
+        encrypt: params.encrypt,
+    });
+    return expected === params.signature;
+}