跳转到内容

Rust 开发库

无需 Daemon 或官方可执行程序,即可直接使用这些库。连接到正在运行的 Daemon 的应用程序可以使用 HTTP API。

Crate用途
wechat-protocol认证、传输、同步与消息编解码
wechat-profileProfile 密钥、联系人、历史记录、缓存媒体与经过校验的写入器
wechat-calls语音会话与媒体基础组件、PCM 混音及可选的 Opus
wechat-media图像检查与解码
wechat-platform私有文件与操作系统支持

添加依赖

  1. 为所有库选择相同的已发布 Rust 库版本。将下面的 VERSION 替换为该版本号。wechat-calls 与账号所有者客户端 API 首次随 conference 发布版本提供;更早的版本中不包含它们。

    Terminal window
    cargo add wechat-protocol@=VERSION wechat-profile@=VERSION
  2. 使用 Rust 1.93.1+、C 编译器、Make 与 Perl 进行构建。Cargo 会自动解析所依赖的支持库。原生 Opus 还需要 CMake 与 C++ 编译器。

自 2.3.2 之后的版本起,Rust 库的版本号与 CLI、Daemon 和 OpenClaw 插件保持一致,且每次发布都会同时发布全部五个库。此前的库版本(直至 2.2.0)单独编号;请选择 crates.io 上列出的版本。

读取已停止的 Profile

停止 Profile 的写入进程,或提供一致的副本,然后加载受保护的密钥文件。快照标志仅记录调用方的确认,并不会停止其他进程。

use wechat_profile::{KeyFile, ListQuery, ProfileLocation, ProfileReader, ReadOptions};
fn contacts(profile: &str, keys_path: &str) -> wechat_profile::Result<()> {
let reader = ProfileReader::open(
ProfileLocation::new(profile)?, KeyFile::load(keys_path)?, ReadOptions {
stopped_or_consistent_snapshot: true,
..Default::default()
},
)?;
println!("{} contacts", reader.contacts(&ListQuery::default())?.items.len());
Ok(())
}

读取缓存媒体时绝不会发起下载。拥有该 Profile 的应用程序可以使用 OwnedReaderCache,并由其自行同步。

contacts 列出当前的记录行。若需获取某个确切存储身份(包括保留下来的已删除联系人或群聊记录),请使用 reader.contact(username)。在修改联系人或群聊之前,请检查返回的标志位;仅有存储记录并不意味着该对象符合修改条件。

发送单条文本消息

操作均为 NativeClient 上的方法。应用程序负责凭据存储、恢复与 Profile 回写。

  1. 调用 start_qr_login,轮询直至 LoginStatus::Approved,然后调用 complete_login。将返回的 AccountState 传入 NativeClient::from_account(state, options)。克隆出的句柄共享同一个账号所有者。操作不再接受单独的可变账号状态。

  2. 提交前,先记录操作、唯一任务 ID 与 Unix 秒级时间戳。收件人请使用其确切的微信用户名(username):

    use wechat_protocol::{wire, NativeClient, TextSendOptions, TextSendResult};
    async fn send_once(
    client: &NativeClient, recipient: &str, text: &str,
    task_id: &str, created_at: u32,
    ) -> anyhow::Result<TextSendResult> {
    let client_id = wire::client_message_id(task_id.as_bytes());
    anyhow::ensure!(client_id != 0, "Choose another task ID");
    client.send_text(recipient, text, TextSendOptions {
    created_at, client_message_id: client_id, source: None,
    }).await
    }
  3. 检查 accepted、returned_destination_matches 与 returned_client_id_matches。回执中的 server_message_id 并不能证明接收方已播放该消息,也不能证明历史记录已回写。

在代码仓库中运行可执行示例,会显示新的登录二维码并提交一次消息:

Terminal window
cargo run --manifest-path packages/native-client-rust/Cargo.toml -p wechat-protocol --example send_text -- RECIPIENT UNIQUE_TASK_ID "Hello from Rust"

服务端接收后会输出 "accepted": true。--help 不会发起任何网络请求。qr_login、sync_once 与 protobuf 分别演示登录、单页同步以及本地编解码。sync_once 不保存游标;持续接收消息的程序必须先保留同步命令,然后再推进游标。

表情

wechat-media::prepare_sticker 会为调用方拥有的源文件进行准备(可选择适配或裁剪),并返回 GIF、静态图和抽样帧输出。sticker_export_gif 会保留已有的 GIF 字节;export_sticker_pack 会在调用方的文件系统中写入一个所选表情包以及可续传的校验和索引。

NativeClient 提供“我的表情”的分页与元数据、有上限的上传分块、“我的表情”的修改操作、表情包的分页、详情与说明,以及原始的成员关系确认。StickerId::parse 会规范化内容标识;StickerPackId::parse 则将产品标识分开保存。使用这些传输方法的应用需自行负责提交日志和 Profile 回写。读取缓存的 Profile 数据绝不会获取缺失的媒体。

在本工作区内,wechat-core 提供 core.stickers(account)?,这是一个绑定账号的异步句柄,支持 list、get、media、prepare、add_prepared、save_received、move_after、remove、packs、browse、pack、items、add_pack、remove_pack、acquire、acquire_pack、acquire_preview、send、sync 和 job。它负责账号门控并使用已有任务;文件系统导出不属于该句柄。wechat-core 是 Daemon 的实现,并非单独发布的 HTTP 客户端 crate。外部应用可以使用表情 REST 资源。

发送图片与视频

在调用协议发送方法之前,请先准备并上传各个副本。每个方法都会处理两种画质:

方法upload.original: Noneupload.original: Some(...)
NativeClient::send_image高清与缩略图另包含原图
NativeClient::send_video播放版与缩略图另包含原始视频

UploadedImage.original 现为 Option<UploadedMedia>。迁移 Rust 调用方时,请将已有的原图包装为 Some(...),并在读取该字段时处理 None 的情况。使用 Daemon 媒体 API 的应用程序则改为在发送请求中选择画质。

使用通话媒体

请使用相同的 Rust 库版本添加 wechat-calls。它不会打开任何设备,也不会创建 Tokio 运行时。示例请参考其 Crate 指南。

Features用途
默认 native-runtime原生会话与媒体集成,以及协议和 Opus 支持
禁用默认特性 + native-opus不依赖账号的编解码与 PCM 工具
禁用默认特性可移植的 PCM、队列、节拍控制与混音,包括 WebAssembly

高级 client.calls() 门面接口尚未完成。目前完整的通话操作请使用通话 API。Crate 架构说明了各库之间的依赖关系。

Profile 写入

stage_* 准备字节数据,apply_* 应用逻辑更新,publish_* 将字节安装到 Profile 中的路径。这些是 API 名称,并非官方客户端的名称;apply_* 与 publish_* 的职责有部分重叠,且不保证整个操作是原子的。MMKV 暂存会生成加密数据以及匹配的 .crc 元数据。发布时会使用临时文件。WriteOptions::durable_intent_id 指向你事先保存的恢复记录;该库无法验证此记录是否存在。