MINARA使用 Minara客戶端與界面消息平臺
WeCom (企業微信)
企業微信自建應用消息通知，採用 SHA1 排序 + AES-256-CBC 回調信封。適用於企業中國部署的標準通道。
🟡 支持主動發送，支持接收回調。基於自建應用路徑構建（最常見的部署形態）。使用與微信公眾號相同的 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. 創建自建應用
- 登錄 企業微信管理後臺
- 進入"應用管理" → "自建" → "創建應用"
- 填寫應用基本信息；在應用詳情頁記錄 AgentID 和 Secret
- 企業級 CorpID 位於"我的企業" → "企業信息"
2. 啟用回調（可選，用於入站接收）
- 打開應用詳情頁 → "接收消息" → "設置API接收"
- 將 URL 填寫為
https://<your-host>/webhooks/wecom - 填寫 Token（任意不透明字符串），點擊"隨機"生成 EncodingAESKey（必須為 43 位 base64 字符）
- 點擊"保存"。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=…×tamp=…&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 個字符。請在企業微信控制台重新生成。