MINARA
使用 Minara客戶端與界面消息平臺

Lark / Feishu

通過 tenant_access_token 發送 Lark IM 消息，可選 AES-256-CBC 加密 webhook 事件。

🟡 出站就緒，支持入站。同時覆蓋中國大陸飛書（open.feishu.cn）和國際版 Lark（open.larksuite.com）。入站 webhook 支持 Lark 的全部三種安全模式：驗證 token、加密和簽名 HMAC。

功能概覽

  • 出站文本消息，通過 POST /open-apis/im/v1/messages?receive_id_type=chat_id 發送。tenant access token 緩存 2 小時，並在到期前 5 分鐘自動刷新，高頻發送不會觸及單應用 token 速率限制。
  • 入站 webhook 事件，路徑為 /webhooks/lark。Lark 允許開發者在三種安全模式中任意組合啟用（驗證 token、加密密鑰、HMAC 簽名）。Minara 會自動遵守你在開發者後臺啟用的模式。
  • 域名感知路由。LARK_DOMAIN 決定使用國內飛書還是國際版 Lark，兩者 API 結構完全一致。
  • 當前僅支持文本消息。富文本卡片、圖片和文件將在後續版本支持；tenant token 緩存和簽名 webhook 已在本版本落地。
  • 30,000 字符上限。超長文本會被截斷。

配置步驟

1. 創建應用

  1. 登錄 Lark 開發者後臺（國際版請訪問 Lark international）
  2. 創建自建應用，記錄 App ID（以 cli_ 開頭）和 App Secret
  3. 在「權限與範圍」中授予 im:message:send_as_bot；如需入站消息，還需授予 im:message
  4. 在「事件訂閱」中，將請求 URL 設置為 https://<your-host>/webhooks/lark，複製 Verification Token 和（可選的）Encrypt Key

2. 獲取默認 chat_id

在目標會話（單聊或群聊）中發一條消息，然後通過開發者後臺調用 POST /open-apis/im/v1/messages/list，或用 curl 攜帶 tenant token 查詢，提取 chat_id（格式：oc_xxxxxxxxxxxxxxxx），保存為 LARK_DEFAULT_CHAT_ID。

3. 配置 Minara

minara auth messaging add
# 从列表中选择 `lark`，依次填入 app id、app secret、chat id、
# verification token（若启用了加密还需填写 encrypt key）。

也可直接寫入項目根目錄的 .env 文件：

LARK_APP_ID=cli_xxxxxxxxxxxxxxxx
LARK_APP_SECRET=<opaque secret>
LARK_DEFAULT_CHAT_ID=oc_xxxxxxxxxxxxxxxx
LARK_VERIFICATION_TOKEN=<verification token>
LARK_ENCRYPT_KEY=<encrypt key, optional>
LARK_DOMAIN=open.feishu.cn          # or open.larksuite.com

4. 測試

minara auth messaging test lark

入站 webhook

在 Lark 事件訂閱中，將請求 URL 配置為：

https://<your-host>/webhooks/lark

三種安全模式可疊加使用：

模式環境變量作用
驗證 tokenLARK_VERIFICATION_TOKEN解碼後的 payload 頂層 token 字段須與此值匹配。適用於明文模式及解密後校驗。
加密LARK_ENCRYPT_KEY（可選）設置後，請求體為 {encrypt: "<base64>"}，使用 AES-256-CBC 解密；密鑰為 SHA256(encrypt_key)，IV 為密鑰前 16 字節。
簽名X-Lark-Signature 請求頭（始終可選）對 timestamp + nonce + encrypt_key + body 取 SHA-256，以十六進制寫入請求頭。在後臺開啟後可提供額外完整性校驗。

URL 驗證握手：Lark 發送 {type:"url_verification", challenge:"..."}，Minara 校驗 verification token 後回覆 {challenge}。token 不匹配時返回 403。

限制與注意事項

  • Tenant token 速率限制。Lark 每分鐘每應用最多允許約 100 次 token 獲取請求。2 小時緩存策略遠低於此上限。
  • content 必須是 JSON 編碼的字符串。這是 Lark API 的特殊要求：文本消息也需以 content: JSON.stringify({text: "..."}) 形式發送。Minara 已自動處理。
  • 暫不支持卡片交互。互動卡片的按鈕點擊回調屬於不同的 webhook 事件類型，目前不予解析。

故障排查

「測試消息返回 code 99991663」

  • tenant access token 刷新失敗。請對照開發者後臺檢查 LARK_APP_ID 和 LARK_APP_SECRET。

「入站 webhook 返回 401」

  • 若在後臺啟用了加密模式，但未設置 LARK_ENCRYPT_KEY，所有入站 POST 請求都會解密失敗。請在後臺關閉加密，或補充設置該環境變量。
  • 若啟用了簽名模式，請確認保存的 LARK_ENCRYPT_KEY 與後臺顯示一致（該值同時作為簽名輸入）。

「content field is required (400)」

  • 調用 send_message 時 text 為空字符串。Lark 拒絕空消息體。

參考資料

Slack

Bot token 模式可解鎖完整的 Slack Web API（流式傳輸、文件、表情、臨時消息、定時消息）。Webhook 模式是單 URL 備選方案，支持純文本、Block Kit 塊和線程回覆。

WeCom (企業微信)

企業微信自建應用消息通知，採用 SHA1 排序 + AES-256-CBC 回調信封。適用於企業中國部署的標準通道。

本頁目錄

功能概覽配置步驟1. 創建應用2. 獲取默認 chat_id3. 配置 Minara4. 測試入站 webhook限制與注意事項故障排查參考資料