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限制与注意事项故障排查参考资料