@mocrane/wecom 2026.2.5

package/src/channel.ts

@@ -0,0 +1,259 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelPlugin,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  setAccountEnabledInConfigSection,
+} from "openclaw/plugin-sdk";
+
+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",
+  label: "WeCom",
+  selectionLabel: "WeCom (plugin)",
+  docsPath: "/channels/wecom",
+  docsLabel: "wecom",
+  blurb: "Enterprise WeCom intelligent bot (API mode) via encrypted webhooks + passive replies.",
+  aliases: ["wechatwork", "wework", "qywx", "企微", "企业微信"],
+  order: 85,
+  quickstartAllowFrom: true,
+};
+
+function normalizeWecomMessagingTarget(raw: string): string | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  return trimmed.replace(/^(wecom-agent|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: true,
+    reactions: false,
+    threads: false,
+    polls: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.wecom"] },
+  configSchema: buildChannelConfigSchema(WecomConfigSchema),
+  config: {
+    listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+    resolveAccount: (cfg) => resolveWecomAccount(cfg as OpenClawConfig),
+    defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as OpenClawConfig,
+        sectionKey: "wecom",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    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.bot?.config ? "/wecom/bot" : account.agent?.config ? "/wecom/agent" : "/wecom",
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) => {
+      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
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  // security 配置在 WeCom 中不需要，框架会通过 resolveAllowFrom 自动判断
+  groups: {
+    // WeCom bots are usually mention-gated by the platform in groups already.
+    resolveRequireMention: () => true,
+  },
+  threading: {
+    resolveReplyToMode: () => "off",
+  },
+  messaging: {
+    normalizeTarget: normalizeWecomMessagingTarget,
+    targetResolver: {
+      looksLikeId: (raw) => Boolean(raw.trim()),
+      hint: "<userid|chatid>",
+    },
+  },
+  outbound: {
+    ...wecomOutbound,
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      running: snapshot.running ?? false,
+      webhookPath: snapshot.webhookPath ?? null,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      lastInboundAt: snapshot.lastInboundAt ?? null,
+      lastOutboundAt: snapshot.lastOutboundAt ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async () => ({ ok: true }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      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.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;
+      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: () => { } };
+      }
+
+      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: botConfigured ? "/wecom/bot" : "/wecom/agent",
+        lastStartAt: Date.now(),
+      });
+      return {
+        stop: () => {
+          for (const unregister of unregisters) {
+            unregister();
+          }
+          ctx.setStatus({
+            accountId: account.accountId,
+            running: false,
+            lastStopAt: Date.now(),
+          });
+        },
+      };
+    },
+    stopAccount: async (ctx) => {
+      ctx.setStatus({
+        accountId: ctx.account.accountId,
+        running: false,
+        lastStopAt: Date.now(),
+      });
+    },
+  },
+};

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,12 @@
+/**
+ * WeCom 配置模块导出
+ */
+
+export { WecomConfigSchema, type WecomConfigInput } from "./schema.js";
+export {
+    detectMode,
+    resolveWecomAccounts,
+    isWecomEnabled,
+} from "./accounts.js";
+export { resolveWecomEgressProxyUrl, resolveWecomEgressProxyUrlFromNetwork } from "./network.js";
+export { DEFAULT_WECOM_MEDIA_MAX_BYTES, resolveWecomMediaMaxBytes } from "./media.js";

package/src/config/media.ts

@@ -0,0 +1,14 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+// 默认给一个相对“够用”的上限（80MB），避免视频/较大文件频繁触发失败。
+// 仍保留上限以防止恶意大文件把进程内存打爆（下载实现会读入内存再保存）。
+export const DEFAULT_WECOM_MEDIA_MAX_BYTES = 80 * 1024 * 1024;
+
+export function resolveWecomMediaMaxBytes(cfg: OpenClawConfig): number {
+  const raw = (cfg.channels?.wecom as any)?.media?.maxBytes;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  if (Number.isFinite(n) && n > 0) {
+    return Math.floor(n);
+  }
+  return DEFAULT_WECOM_MEDIA_MAX_BYTES;
+}

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

@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const dmSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    policy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+    allowFrom: z.array(allowFromEntry).optional(),
+  })
+  .optional();
+
+export const WecomConfigSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+
+  webhookPath: z.string().optional(),
+  token: z.string().optional(),
+  encodingAESKey: z.string().optional(),
+  receiveId: z.string().optional(),
+
+  streamPlaceholderContent: z.string().optional(),
+  debounceMs: z.number().optional(),
+
+  welcomeText: z.string().optional(),
+  dm: dmSchema,
+
+  defaultAccount: z.string().optional(),
+  accounts: z.object({}).catchall(z.object({
+    name: z.string().optional(),
+    enabled: z.boolean().optional(),
+    webhookPath: z.string().optional(),
+    token: z.string().optional(),
+    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";