@yanhaidao/wecom 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# Clawdbot 企业微信（WeCom）Channel 插件
+
+维护者：YanHaidao（VX：YanHaidao）
+
+状态：支持企业微信智能机器人（API 模式）加密回调 + 被动回复（stream）。
+
+## 联系我
+
+微信交流群（扫码入群）：
+
+![企业微信交流群](https://cdn.jsdelivr.net/npm/@yanhaidao/wecom@latest/assets/link-me.jpg)
+
+## 安装
+
+### 从 npm 安装
+```bash
+clawdbot plugins install @yanhaidao/wecom
+clawdbot plugins enable wecom
+clawdbot gateway restart
+```
+
+
+## 配置结构参考
+
+```json5
+{
+  channels: {
+    wecom: {
+      enabled: true,
+      webhookPath: "/wecom",
+      token: "YOUR_TOKEN",
+      encodingAESKey: "YOUR_ENCODING_AES_KEY",
+      receiveId: "YOUR_RECEIVE_ID",
+      dm: { policy: "pairing" }
+    }
+  }
+}
+```
+
+## 接入企业微信
+
+### 搭建企微 Bot（API 模式）
+
+1. 登录企业微信管理后台  
+进入「安全与管理」→「管理工具」→「智能机器人」：`https://work.weixin.qq.com/wework_admin/frame#/manageTools`
+
+2. 创建机器人（务必选择 API 模式）  
+创建机器人时需要填写回调 URL（公网可访问的 HTTPS 地址），例如：`https://example.com/wecom`
+
+3. 记录机器人配置  
+在机器人详情里找到并保存以下信息，后续会写入 Clawdbot 配置：
+- Token
+- EncodingAESKey
+- ReceiveId（如果你的机器人/回调配置需要校验的话）
+
+## 快速开始
+
+1. 启用插件
+```bash
+clawdbot plugins enable wecom
+```
+
+2. 配置企业微信机器人（必需）
+```bash
+clawdbot config set channels.wecom.enabled true
+clawdbot config set channels.wecom.webhookPath "/wecom"
+clawdbot config set channels.wecom.token "YOUR_TOKEN"
+clawdbot config set channels.wecom.encodingAESKey "YOUR_ENCODING_AES_KEY"
+clawdbot config set channels.wecom.receiveId ""
+```
+
+3. 配置 Gateway（示例）
+```bash
+clawdbot config set gateway.mode "local"
+clawdbot config set gateway.bind "0.0.0.0"
+clawdbot config set gateway.port 18789
+```
+
+4. 重启 Gateway
+```bash
+clawdbot gateway restart
+```
+
+5. 验证
+```bash
+clawdbot channels status
+```
+
+## 说明
+
+- webhook 必须是公网 HTTPS。出于安全考虑，建议只对外暴露 `/wecom` 路径。
+- stream 模式：第一次回包可能是占位符；随后 WeCom 会以 `msgtype=stream` 回调刷新拉取完整内容。
+- 限制：仅支持被动回复，不支持脱离回调的主动发送。

package/clawdbot.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "wecom",
+  "channels": ["wecom"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Author: YanHaidao
+ */
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
+
+import { handleWecomWebhookRequest } from "./src/monitor.js";
+import { setWecomRuntime } from "./src/runtime.js";
+import { wecomPlugin } from "./src/channel.js";
+
+const plugin = {
+  id: "wecom",
+  name: "WeCom",
+  description: "Clawdbot WeCom (WeChat Work) intelligent bot channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: ClawdbotPluginApi) {
+    setWecomRuntime(api.runtime);
+    api.registerChannel({ plugin: wecomPlugin });
+    api.registerHttpHandler(handleWecomWebhookRequest);
+  },
+};
+
+export default plugin;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@yanhaidao/wecom",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Clawdbot WeCom (WeChat Work) intelligent bot channel plugin",
+  "author": "YanHaidao (VX: YanHaidao)",
+  "clawdbot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "wecom",
+      "label": "WeCom",
+      "selectionLabel": "WeCom (plugin)",
+      "detailLabel": "WeCom Bot",
+      "docsPath": "/channels/wecom",
+      "docsLabel": "wecom",
+      "blurb": "Enterprise WeCom intelligent bot (API mode) via encrypted webhooks + passive replies.",
+      "aliases": [
+        "wechatwork",
+        "wework",
+        "qywx",
+        "企微",
+        "企业微信"
+      ],
+      "order": 85
+    },
+    "install": {
+      "npmSpec": "@yanhaidao/wecom",
+      "localPath": "extensions/wecom",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {},
+  "peerDependencies": {
+    "clawdbot": ">=2026.1.25"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,73 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+
+import type { ResolvedWecomAccount, WecomAccountConfig, WecomConfig } from "./types.js";
+
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listWecomAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultWecomAccountId(cfg: ClawdbotConfig): string {
+  const wecomConfig = cfg.channels?.wecom as WecomConfig | undefined;
+  if (wecomConfig?.defaultAccount?.trim()) return wecomConfig.defaultAccount.trim();
+  const ids = listWecomAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): WecomAccountConfig | undefined {
+  const accounts = (cfg.channels?.wecom as WecomConfig | undefined)?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as WecomAccountConfig | undefined;
+}
+
+function mergeWecomAccountConfig(cfg: ClawdbotConfig, accountId: string): WecomAccountConfig {
+  const raw = (cfg.channels?.wecom ?? {}) as WecomConfig;
+  const { accounts: _ignored, defaultAccount: _ignored2, ...base } = raw;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...base, ...account };
+}
+
+export function resolveWecomAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedWecomAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = (params.cfg.channels?.wecom as WecomConfig | undefined)?.enabled !== false;
+  const merged = mergeWecomAccountConfig(params.cfg, accountId);
+  const enabled = baseEnabled && merged.enabled !== false;
+
+  const token = merged.token?.trim() || undefined;
+  const encodingAESKey = merged.encodingAESKey?.trim() || undefined;
+  const receiveId = merged.receiveId?.trim() ?? "";
+  const configured = Boolean(token && encodingAESKey);
+
+  return {
+    accountId,
+    name: merged.name?.trim() || undefined,
+    enabled,
+    configured,
+    token,
+    encodingAESKey,
+    receiveId,
+    config: merged,
+  };
+}
+
+export function listEnabledWecomAccounts(cfg: ClawdbotConfig): ResolvedWecomAccount[] {
+  return listWecomAccountIds(cfg)
+    .map((accountId) => resolveWecomAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}
+

package/src/channel.ts

@@ -0,0 +1,212 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelPlugin,
+  ClawdbotConfig,
+} from "clawdbot/plugin-sdk";
+import {
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  setAccountEnabledInConfigSection,
+} from "clawdbot/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";
+
+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|wechatwork|wework|qywx):/i, "").trim() || undefined;
+}
+
+export const wecomPlugin: ChannelPlugin<ResolvedWecomAccount> = {
+  id: "wecom",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: false,
+    reactions: false,
+    threads: false,
+    polls: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.wecom"] },
+  configSchema: buildChannelConfigSchema(WecomConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listWecomAccountIds(cfg as ClawdbotConfig),
+    resolveAccount: (cfg, accountId) => resolveWecomAccount({ cfg: cfg as ClawdbotConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultWecomAccountId(cfg as ClawdbotConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "wecom",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "wecom",
+        clearBaseFields: ["name", "webhookPath", "token", "encodingAESKey", "receiveId", "welcomeText"],
+        accountId,
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account): ChannelAccountSnapshot => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      webhookPath: account.config.webhookPath ?? "/wecom",
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) => {
+      const account = resolveWecomAccount({ cfg: cfg as ClawdbotConfig, accountId });
+      return (account.config.dm?.allowFrom ?? []).map((entry) => String(entry));
+    },
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.toLowerCase()),
+  },
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean((cfg as ClawdbotConfig).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(),
+      };
+    },
+  },
+  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: {
+    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)."),
+      };
+    },
+  },
+  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.config.webhookPath ?? "/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",
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      if (!account.configured) {
+        ctx.log?.warn(`[${account.accountId}] wecom not configured; skipping webhook registration`);
+        ctx.setStatus({ accountId: account.accountId, running: false, configured: false });
+        return { stop: () => {} };
+      }
+      const path = (account.config.webhookPath ?? "/wecom").trim();
+      const unregister = registerWecomWebhookTarget({
+        account,
+        config: ctx.cfg as ClawdbotConfig,
+        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}`);
+      ctx.setStatus({
+        accountId: account.accountId,
+        running: true,
+        configured: true,
+        webhookPath: path,
+        lastStartAt: Date.now(),
+      });
+      return {
+        stop: () => {
+          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-schema.ts

@@ -0,0 +1,36 @@
+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(),
+
+  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(),
+    welcomeText: z.string().optional(),
+    dm: dmSchema,
+  })).optional(),
+});

package/src/crypto.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+
+import { computeWecomMsgSignature, decryptWecomEncrypted, encryptWecomPlaintext } from "./crypto.js";
+
+describe("wecom crypto", () => {
+  it("round-trips plaintext", () => {
+    const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"; // 43 chars base64 (plus '=' padding)
+    const plaintext = JSON.stringify({ hello: "world" });
+    const encrypt = encryptWecomPlaintext({ encodingAESKey, receiveId: "", plaintext });
+    const decrypted = decryptWecomEncrypted({ encodingAESKey, receiveId: "", encrypt });
+    expect(decrypted).toBe(plaintext);
+  });
+
+  it("pads correctly when raw length is a multiple of 32", () => {
+    const encodingAESKey = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG";
+    // raw length = 20 + plaintext.length + receiveId.length; choose plaintext length % 32 === 12
+    const plaintext = "x".repeat(12);
+    const encrypt = encryptWecomPlaintext({ encodingAESKey, receiveId: "", plaintext });
+    const decrypted = decryptWecomEncrypted({ encodingAESKey, receiveId: "", encrypt });
+    expect(decrypted).toBe(plaintext);
+  });
+
+  it("computes sha1 msg signature", () => {
+    const sig = computeWecomMsgSignature({
+      token: "token",
+      timestamp: "123",
+      nonce: "456",
+      encrypt: "ENCRYPT",
+    });
+    expect(sig).toMatch(/^[a-f0-9]{40}$/);
+  });
+});

package/src/crypto.ts

@@ -0,0 +1,133 @@
+import crypto from "node:crypto";
+
+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 !== 32) {
+    throw new Error(`invalid encodingAESKey (expected 32 bytes after base64 decode, got ${key.length})`);
+  }
+  return key;
+}
+
+// WeCom uses PKCS#7 padding with a block size of 32 bytes (not AES's 16-byte block).
+// This is compatible with AES-CBC as 32 is a multiple of 16, but it requires manual padding/unpadding.
+const WECOM_PKCS7_BLOCK_SIZE = 32;
+
+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]!)]);
+}
+
+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");
+  }
+  // Best-effort validation (all padding bytes equal).
+  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);
+}
+
+function sha1Hex(input: string): string {
+  return crypto.createHash("sha1").update(input).digest("hex");
+}
+
+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(""));
+}
+
+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;
+}
+
+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, WECOM_PKCS7_BLOCK_SIZE);
+
+  if (decrypted.length < 20) {
+    throw new Error(`invalid decrypted payload (expected at least 20 bytes, got ${decrypted.length})`);
+  }
+
+  // 16 bytes random + 4 bytes network-order length + msg + receiveId (optional)
+  const msgLen = decrypted.readUInt32BE(16);
+  const msgStart = 20;
+  const msgEnd = msgStart + msgLen;
+  if (msgEnd > decrypted.length) {
+    throw new Error(`invalid decrypted msg length (msgEnd=${msgEnd}, payloadLength=${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;
+}
+
+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, WECOM_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");
+}