WeCom (企业微信)

🟡 支持主动发送，支持接收回调。基于自建应用路径构建（最常见的部署形态）。使用与微信公众号相同的 SHA1 + AES 信封，共享的 wxcrypt 辅助模块同时覆盖这两个渠道。

功能说明

• 主动文本消息：通过 POST /cgi-bin/message/send 向一个或多个 touser 收件人发送（或用 @all 覆盖整个应用受众）。
• 入站回调事件：接收路径为 /webhooks/wecom。WeCom 对每条回调使用 msg_signature 签名（对 [token, timestamp, nonce, encrypt] 按字典序排列后 SHA1 计算）。消息体以 43 位 EncodingAESKey 进行 AES-256-CBC 加密。
• 每个应用的 access_token 缓存 2 小时，到期自动刷新。
• 当前版本仅支持文本。图片和文件上传（通过"上传媒体"接口）将在后续版本支持。
• 文本消息上限 2048 字符（Markdown 为 4096，暂未接入）。

配置步骤

1. 创建自建应用

1. 登录 企业微信管理后台
2. 进入"应用管理" → "自建" → "创建应用"
3. 填写应用基本信息；在应用详情页记录 AgentID 和 Secret
4. 企业级 CorpID 位于"我的企业" → "企业信息"

2. 启用回调（可选，用于入站接收）

1. 打开应用详情页 → "接收消息" → "设置API接收"
2. 将 URL 填写为 https://<your-host>/webhooks/wecom
3. 填写 Token（任意不透明字符串），点击"随机"生成 EncodingAESKey（必须为 43 位 base64 字符）
4. 点击"保存"。WeCom 会向该 URL 发起 GET 握手；Minara 解密 echostr 后原样返回，完成绑定。

3. 配置 Minara

minara auth messaging add
# 选择 `wecom`；依次填入 corp id、agent id、secret、默认 touser、
# callback token、EncodingAESKey。

或直接设置环境变量：

WECOM_CORP_ID=ww<...>
WECOM_AGENT_ID=1000002
WECOM_SECRET=<application secret>
WECOM_DEFAULT_TOUSER=user1|user2     # 或 @all
WECOM_CALLBACK_TOKEN=<callback token>
WECOM_CALLBACK_AES_KEY=<43-char EncodingAESKey>

WECOM_DEFAULT_TOUSER 遵循企业微信约定：多个用户 ID 用竖线分隔，或使用 @all 覆盖应用全部受众。

4. 测试

minara auth messaging test wecom

默认列表中的每个 touser 都会收到"✅ Minara gateway test ping"。

入站 Webhook

WeCom 的消息签名通过 URL 查询参数传递，而非请求头。Minara 在解密消息体前，先验证 msg_signature 是否与 SHA1(sort([token, timestamp, nonce, encrypt]).join("")) 一致（腾讯旧版 IM 方案）。

GET URL 验证握手：WeCom 发送 ?msg_signature=…&timestamp=…&nonce=…&echostr=<base64>。Minara 校验签名后，用 AES 密钥（IV 取密钥前 16 字节）解密 echostr，并返回明文。Token 或 AES 密钥有误时返回 401 / 500。

解密后的 XML 内容格式：

<xml>
  <ToUserName>...</ToUserName>
  <FromUserName>...</FromUserName>
  <CreateTime>...</CreateTime>
  <MsgType>text</MsgType>
  <Content>...</Content>
  <MsgId>...</MsgId>
</xml>

目前只有 MsgType=text 的消息会转发给 Agent。图片、语音和事件类型将被静默丢弃。

限制与注意事项

• access_token 与 callback token 是两个不同的凭证。 前者是企业微信的应用级 OAuth token，后者是回调签名共享密钥。请在 env 文件中明确区分。
• @all 容易误操作。 它会向应用受众范围内的所有用户发送通知；生产环境请将 WECOM_DEFAULT_TOUSER 固定为具体用户 ID。
• AES 密钥长度有强制要求。 WeCom 要求密钥解码后恰好为 32 字节（填充前为 43 位 base64 字符），长度不符将被拒绝。

故障排查

"Get access token failed (errcode 40013)"

• WECOM_CORP_ID 与该 Secret 所属企业不匹配。

"入站 webhook 返回 401"

• msg_signature 验证失败。最常见原因：WECOM_CALLBACK_TOKEN 存在拼写错误。较少见原因：反向代理移除了签名查询参数。

"signCallbackParams length mismatch"

• WECOM_CALLBACK_AES_KEY 不足 43 个字符。请在企业微信控制台重新生成。

参考

• 环境变量：WECOM_*
• 主动发送：apps/agent/src/messaging/wecom.ts
• 入站规范：apps/agent/src/messaging/inbound/specs/wecom.ts
• 共享加密辅助模块：apps/agent/src/messaging/_shared/wxcrypt.ts
• 企业微信开发平台：developer.work.weixin.qq.com