110 lines
10 KiB
Markdown
110 lines
10 KiB
Markdown
# 飞书/企微/钉钉 Rust 接入与 SDK 调研
|
||
|
||
> 创建: 2026-10-04 | 状态: ✅ 调研完成
|
||
> 服务于: [devflow集成三方IM-飞书企微钉钉Web-规划设计-2026-10-04.md](./devflow集成三方IM-飞书企微钉钉Web-规划设计-2026-10-04.md) P2/P3/P4
|
||
> 原始材料: [.research/](./.research/)（larkrs 全套 + 本次新增 dingtalk/wecom README 与 crates 数据）
|
||
|
||
## 一、总览：三家选型结论
|
||
|
||
| 维度 | 飞书 | 钉钉 | 企微 |
|
||
|---|---|---|---|
|
||
| **选型** | ⭐ larksuite-oapi-sdk-rs 0.3.12 | ⭐ dingtalk-stream 0.1.7 | ⭐ wecom-aibot-rust-sdk 1.0.2 |
|
||
| 作者 | adamcavendish（非官方，显式对齐 Go 官方 SDK） | spensercai（非官方，对齐官方 Python SDK commit 6381a7b） | camark（非官方，Python 版 wecom/aibot 的 Rust 改写） |
|
||
| 仓库 | github.com/adamcavendish/larksuite-oapi-sdk-rs | github.com/spensercai/dingtalk-stream-sdk-rs | github.com/camark/wecom-aibot-rust-sdk |
|
||
| 最近发版/提交 | 2026-10-03（活跃） | 2026-03-26 | 2026-04-07 |
|
||
| crates 下载（近期） | 4276（openlark-auth 关联） | 3459 | 106 |
|
||
| 连接方式 | **WS 长连接**（features=["ws"]） | **WS Stream Mode** | **WS 长连接**（wss://openws.work.weixin.qq.com）✅ |
|
||
| 免公网回调 | ✅ | ✅ | ✅（智能机器人形态，**非**传统自建应用回调模式） |
|
||
| 流式回复 | ✅ CardKit（CardEntity + sequence 递增） | ✅ 卡片 AI 流式 | ✅ reply_stream（stream_id + finish 标志，支持 Markdown） |
|
||
| 审批按钮回调 | ⚠️ card.action.trigger 新版事件（编译冒烟验证） | ✅ 卡片按钮回调 | ✅ template_card_event（5s 内 update_template_card） |
|
||
| Rust 版本要求 | 1.95+/edition 2024 | 1.85+/edition 2024 | 1.70+（tokio 1.35+） |
|
||
|
||
**核心结论**：三家全部有可用的 Rust 原生 SDK，且三家全部支持 WS 长连接——**df-im-gateway 三平台均不需要公网回调/可信 IP/AES 回调解密**。原规划中「企微接入复杂度最高（回调验签+AES+可信域名）」的判断基于传统自建应用形态，改用**智能机器人**形态后三平台接入复杂度拉平，P4 工作量从 3-4 天降到 2-3 天。
|
||
|
||
## 二、飞书：larksuite-oapi-sdk-rs（已有源码级勘察）
|
||
|
||
详见 [.research/larkrs-readme.md](./.research/larkrs-readme.md) / [larkrs-events-and-channels.md](./.research/larkrs-events-and-channels.md) / [larkrs-cards.md](./.research/larkrs-cards.md) 及任务 P2 描述中的勘察补充。要点：
|
||
|
||
- `features=["channel"]` 一站式：`channel_messaging()` 高层封装（send/reply/reply_in_thread/edit_text/edit_card），uuid 1h 幂等窗口
|
||
- ws feature：bootstrap 握手（POST /callback/ws/endpoint 换 wss URL）+ protobuf framing + 有限重连 + liveness（入站静默 2×ping+5s 判失败）+ write 超时 10s + 回调与收包循环解耦（慢回调不掩盖网关静默）
|
||
- 卡片三套：card::v1（JSON 1.0）/ card::v2（JSON 2.0）/ CardKit 流式（CardEntity 一次发送 + sequence 递增更新，14 天生命周期）；CardDocument 带 JSON Pointer 级严格校验
|
||
- 事件：EventDispatcher typed handler（如 on_p2_im_message_receive_v1），mpsc 队列 + worker 出站 I/O 模式可直接套用（[.research/larkrs-ws-client-example.rs](./.research/larkrs-ws-client-example.rs)）
|
||
- ⚠️ 遗留验证项：CardActionHandler 官方示例是 HTTP webhook 形态；长连接下 card.action.trigger 应经事件通道分发，typed 注册口需编译冒烟确认（docs/card-protocol.md + examples/card_action_handler.rs 已存档）
|
||
- ⚠️ 坑（源码级实证，知识库已沉淀）：卡片回调必须用**新版** card.action.trigger（EventDispatcher 注册）；旧版 card 帧被 ws 客户端直接丢弃（Go SDK v3.12.0 中 WithCardHandler 被注释）
|
||
|
||
## 三、钉钉：dingtalk-stream（本次新调研）
|
||
|
||
完整对齐官方 Python SDK（open-dingtalk/dingtalk-stream-sdk-python @ 6381a7b），结构清晰（client/credential/handlers/messages/card/transport 分层）。
|
||
|
||
**能力覆盖**（[.research/dingtalk-stream-readme.md](./.research/dingtalk-stream-readme.md)）：
|
||
- Stream 协议连接：自动重连 + 60s Keepalive
|
||
- 消息收发：文本/Markdown/卡片；Rust 独有扩展——机器人可收全部 6 种消息类型（audio/file/video 仅单聊）
|
||
- 交互卡片：Markdown / **AI 流式** / 按钮 / 轮播 / RPA 插件——审批按钮与流式都覆盖
|
||
- 事件订阅 + Graph API
|
||
- OAuth2 Token 自动管理（缓存 + 5 分钟提前刷新）
|
||
- 主动单聊：send_oto_message（POST /v1.0/robot/oToMessages/batchSend）
|
||
- 媒体下载：get_all_download_codes 统一提取 + download_bytes_with_limit 流式限速下载
|
||
|
||
**接入姿势**：
|
||
```rust
|
||
let credential = Credential::new(client_id, client_secret);
|
||
let mut client = DingTalkStreamClient::builder(credential)
|
||
.register_callback_handler(ChatbotMessage::TOPIC, handler)
|
||
.build();
|
||
client.start_forever()?;
|
||
```
|
||
Handler trait 回 `(u16, String)` ACK——**注意 ACK 语义与飞书不同**（飞书是 Response 帧回执，钉钉是 handler 返回值）。
|
||
|
||
**评估**：能力全覆盖、架构对齐官方、文档含时序图、有 e2e_test 示例可直接冒烟。社区量小（3459 下载）但对齐官方 Python SDK 降低了漂移风险。备选 dingtalk-stream-sdk 0.2.5（wenhaozhao，更早但更新至 2026-04）可作 fallback。
|
||
|
||
## 四、企微：wecom-aibot-rust-sdk（本次新调研，重大发现）
|
||
|
||
**关键发现：企业微信「智能机器人」走 WS 长连接**（wss://openws.work.weixin.qq.com，bot_id+secret 认证帧），**完全不需要**传统自建应用的公网回调 URL / GET 验签 / POST AES 解密 / 可信 IP 白名单 / 可信域名。
|
||
|
||
**能力覆盖**（[.research/wecom-aibot-readme.md](./.research/wecom-aibot-readme.md)，546 行完整 API 文档）：
|
||
- 连接管理：自动认证 + 心跳保活（30s）+ 指数退避重连（1s→30s 上限，可设无限）
|
||
- 消息分发：text / image / mixed / voice / file 五类 on_message_* 事件
|
||
- **流式回复**：reply_stream(frame, stream_id, content, finish, ...)——stream_id + finish 标志，天然贴合 TunnelEvent::TextDelta 聚合刷新模式
|
||
- 模板卡片：reply_template_card / **reply_stream_with_card**（流式+卡片组合）/ update_template_card（需事件 5s 内调用）
|
||
- 主动推送：send_message(chatid, body)——无需依赖回调帧，Markdown/卡片均可
|
||
- 事件回调：enter_chat（进会话，5s 内 reply_welcome）/ **template_card_event（卡片按钮点击）** / feedback
|
||
- 文件：download_file（AES-256-CBC 自动解密，媒体自带独立 aeskey）+ upload_media（WS 分片上传，media_id 3 天有效）
|
||
- 串行回复队列：同 req_id 回复串行发送自动等回执；可插拔 Logger；tokio 原生
|
||
|
||
**API 形态**：回调式（on_* 闭包注册）+ client 可 clone（Arc 内部）——与 df-im-gateway 的 adapter 模式兼容性极好，直接把 on_message_text 桥到 TunnelCommand::Send。
|
||
|
||
**限制与验证项**：
|
||
1. **形态确认**：智能机器人 vs 自建应用的能力边界需在管理后台确认（智能机器人是否支持群聊场景、可见范围配置）。README 场景以单聊（userid）+ chatid 为主，群聊支持度落地时验证
|
||
2. 模板卡片更新有 **5s 时窗限制**（enter_chat/template_card_event 后 5s 内）——审批卡片的「按钮点击后更新卡片状态」必须用时窗内 update_template_card 或直接发新卡片
|
||
3. 社区量小（346 下载）且为个人项目——锁版本 + 冒烟测试对冲；协议本身简单（WS+JSON 帧），最坏情况自实现成本可控（远低于原 AES 回调模式）
|
||
4. 备选：WecomTeam/wecom-cli 官方系（wecomx-* crate 族，2026-08 活跃）但为 CLI 形态服务化集成不便；传统自建应用路线（wecom-crypto + wecom-rs）仅在智能机器人不满足时启用
|
||
|
||
## 五、对 df-im-gateway 实施的影响
|
||
|
||
### 5.1 规划修正
|
||
1. **§四 四端对比表**：企微「事件接收」从「HTTP 回调（GET 验签+POST AES，需公网 URL）」修正为「WS 长连接（智能机器人形态，免公网回调）」；接入复杂度从「高」降为「中」
|
||
2. **P4 任务描述**：接入路线改为智能机器人（wecom-aibot-rust-sdk），传统回调模式降级为 fallback
|
||
3. **三平台统一形态**：三家全是「WS 长连接出站 + JSON/protobuf 帧 + 卡片流式 + 按钮回调」——df-im-gateway 的 adapter trait 可以高度统一（InboundEvent/OutboundAction 映射逻辑三平台趋同），印证 P0 的 ④ 预留项价值
|
||
|
||
### 5.2 统一技术底座
|
||
| 关注点 | 三家公共形态 | 网关侧统一处理 |
|
||
|---|---|---|
|
||
| 连接 | WS 出站长连接 + 心跳 + 自动重连 | adapter trait 的 connect/health_check 统一签名 |
|
||
| 收消息 | 事件/消息帧 → text content | InboundEvent::Message{chat_id, user, content} |
|
||
| 流式回复 | stream_id + finish 标志（企微）/ CardKit sequence（飞书）/ AI 卡片流式（钉钉） | OutboundAction::StreamChunk{conv_id, delta, finished} → 各 adapter 自映射 |
|
||
| 审批按钮 | 卡片按钮点击事件 | InboundEvent::CardAction{chat_id, action_id, value} → TunnelCommand::Approve |
|
||
| 媒体 | 下载码/aeskey（企微钉钉）、message resource（飞书） | 二期再做，一期纯文本 |
|
||
|
||
### 5.3 风险清单（落地时冒烟）
|
||
| # | 风险 | 对冲 |
|
||
|---|---|---|
|
||
| R1 | 飞书 card.action.trigger 长连接下 typed 注册口未编译验证 | P2 开工首个冒烟项（examples/card_action_handler.rs 已存档） |
|
||
| R2 | 企微智能机器人群聊支持度/可见范围未确认 | P4 开工前管理后台确认；不满足则回退传统自建应用回调路线 |
|
||
| R3 | 三家 SDK 均非官方（个人维护） | 锁精确版本 + e2e 冒烟进 CI + 协议简单最坏自实现 |
|
||
| R4 | 钉钉 SDK handler ACK 语义与飞书 Response 帧不同 | adapter 层各自封装，不追求网关核心层统一 |
|
||
| R5 | 企微卡片 5s 更新时窗 | 审批结果用新卡片回复而非更新原卡片，规避时窗 |
|
||
|
||
## 六、结论
|
||
|
||
三平台 Rust 接入**全部可行且路线统一**（WS 长连接 + SDK 现成 + 卡片流式 + 按钮审批），无阻塞性技术风险。规划文档的 P2/P3/P4 工作量估算维持 3-4 天/平台不变（复杂度下降但均摊了锁版本冒烟与群聊验证成本）；企微从「最繁琐」降为与钉钉同级，**实施顺序可按 Web → 飞书 → 企微 → 钉钉 或按企业实际使用优先级自由排**。
|