DingTalk Stream SDK for Rust

钉钉 Stream 模式 SDK 的 Rust 实现，完整对齐 Python 版 dingtalk-stream-sdk-python。

对齐的 Python SDK 版本: commit 6381a7b

功能特性

基于 WebSocket 的钉钉 Stream 协议连接（自动重连、60s Keepalive）
聊天机器人消息收发（文本、Markdown、卡片）
交互式卡片（Markdown / AI 流式 / 按钮 / 轮播 / RPA 插件）
Graph API 支持
事件订阅
OAuth2 Token 自动管理（带缓存与 5 分钟提前刷新）
统一 async/await（基于 tokio）

快速开始

将依赖添加到 Cargo.toml：

[dependencies]
dingtalk-stream = "0.1"

最小示例：

use async_trait::async_trait;
use dingtalk_stream::*;

struct MyHandler;

#[async_trait]
impl CallbackHandler for MyHandler {
    async fn process(&self, message: &messages::frames::MessageBody) -> (u16, String) {
        println!("Received: {}", message.data);
        (AckMessage::STATUS_OK, "OK".to_owned())
    }
}

fn main() {
    let credential = Credential::new("your_client_id", "your_client_secret");
    let handler = MyHandler;

    let mut client = DingTalkStreamClient::builder(credential)
        .register_callback_handler(ChatbotMessage::TOPIC, handler)
        .build();

    client.start_forever().unwrap();
}

更多示例见 examples/ 目录。

项目结构

src/
├── lib.rs              # 公共 API 导出
├── client.rs           # DingTalkStreamClient + Builder
├── credential.rs       # Credential（Debug 遮蔽 secret）
├── error.rs            # 统一错误类型
├── handlers/           # Handler traits (Callback/Event/System/Chatbot/Graph)
├── messages/           # 消息类型 (Frames/Chatbot/CardCallback/Graph)
├── card/               # 卡片系统 (Replier/Instances/Templates)
└── transport/          # 传输层 (HTTP/Token/WebSocket)

文档

端到端测试

复制配置模板并填入凭证：

cp examples/secret.example.toml examples/secret.toml
# 编辑 examples/secret.toml，填入 client_id 和 client_secret

运行测试机器人：
```
cargo run --example e2e_test
```

带媒体下载测试：

cargo run --example e2e_test -- --download-dir /tmp/dingtalk_downloads

通过钉钉向机器人发送消息测试：
- ping → 回复 pong
- echo <text> → 回声
- card → 发送 Markdown 卡片
- info → 显示消息详情

与 Python SDK 的设计差异

Python	Rust	说明
sync + async 双版本	统一 async	消除代码重复
类继承	Trait + 组合	Rust 惯用模式
ThreadPoolExecutor	tokio::spawn	更高效的异步调度
dict 动态类型	强类型 struct + serde	编译期类型安全

Rust SDK 独有功能

以下功能为 Rust SDK 独有，Python SDK 中不存在。同步 Python SDK 时请勿删除（代码中均有 Rust SDK exclusive 标注）。

扩展消息类型

Rust SDK 支持解析钉钉机器人可接收的全部 6 种消息类型，Python SDK 仅支持 text / richText / picture：

消息类型	结构体	场景限制
audio 语音	`AudioContent`	仅单聊
file 文件	`FileContent`	仅单聊
video 视频	`VideoContent`	仅单聊

let msg = ChatbotMessage::from_value(&json)?;
if let Some(fc) = &msg.file_content {
    println!("文件名: {:?}, 下载码: {:?}", fc.file_name, fc.download_code);
}

统一下载码提取

get_all_download_codes() 一次性获取消息中所有媒体的下载码，覆盖 picture / richText 图片 / audio / file / video：

for (media_type, download_code) in msg.get_all_download_codes() {
    let url = replier.get_image_download_url(&download_code).await?;
    let bytes = replier.download_bytes(&url).await?;
}

文件下载

方法	说明
`download_bytes(url)`	下载文件字节内容
`download_bytes_with_limit(url, max_size)`	带大小限制的流式下载（Content-Length 预检 + 累计检查）

主动单聊消息

send_oto_message() 通过 OpenAPI 向指定用户发送单聊消息（对应 POST /v1.0/robot/oToMessages/batchSend）：

replier.send_oto_message(user_id, "sampleText", r#"{"content":"hello"}"#).await?;

环境要求

Rust ≥ 1.85.0（edition 2024）
tokio 异步运行时

License

MIT

dingtalk-stream 0.1.6