初步完成channel->queueu->[tool]->[queue]->[assistant]->channel的流程
【待处理】上下文管理和错误处理。
This commit is contained in:
+256
-349
@@ -1,8 +1,11 @@
|
||||
# wechat 模块使用文档
|
||||
|
||||
`wechat` 是一个封装微信 iLink Bot API 的 Rust crate，负责微信 Bot 的扫码登录、监听器生命周期管理、长轮询收消息和文本消息发送。
|
||||
`wechat` 是微信 iLink Bot API 的 Rust 封装，提供两层能力：
|
||||
|
||||
当前模块只提供库能力，不会自动启动后台任务，也不会自动持久化登录态。业务服务需要主动创建 `WeChatClient`、完成登录或恢复登录态，然后调用收发消息接口。
|
||||
- `WeChatClient`：单账号客户端，负责扫码登录、恢复登录态、注册监听器、长轮询收消息、发送文本消息。
|
||||
- `WeChatMultiAccountManager`：多账号运行时管理器，按账号启动多个独立长轮询任务，并通过事件队列把消息交给业务层。
|
||||
|
||||
设计原则：**一个 `WeChatClient` 只代表一个微信 Bot 账号；多账号监听就是每个账号一个独立长轮询任务**。这样可以保证 `token`、`base_url`、`get_updates_buf` 和 `context_token` 不串账号。
|
||||
|
||||
## 模块结构
|
||||
|
||||
@@ -10,34 +13,30 @@
|
||||
wechat/
|
||||
src/
|
||||
lib.rs # 模块导出
|
||||
client.rs # WeChatClient，封装所有 HTTP API 调用
|
||||
types.rs # iLink Bot API 请求、响应和消息结构
|
||||
client.rs # 单账号 WeChatClient
|
||||
manager.rs # 多账号 WeChatMultiAccountManager
|
||||
types.rs # iLink Bot API 协议类型
|
||||
```
|
||||
|
||||
公开模块：
|
||||
|
||||
```rust
|
||||
pub mod client;
|
||||
pub mod manager;
|
||||
pub mod types;
|
||||
```
|
||||
|
||||
常用类型：
|
||||
常用导入：
|
||||
|
||||
```rust
|
||||
use wechat::client::WeChatClient;
|
||||
use wechat::types::{GetUpdatesResp, LoginResult, MessageItem, WeixinMessage};
|
||||
use wechat::manager::{WeChatAccountConfig, WeChatEvent, WeChatMultiAccountManager};
|
||||
use wechat::types::{MessageItem, WeixinMessage};
|
||||
```
|
||||
|
||||
## Cargo 引用
|
||||
|
||||
本仓库根目录已经把 `wechat` 加入 workspace：
|
||||
|
||||
```toml
|
||||
[workspace]
|
||||
members = ["service", "ai", "common", "wechat"]
|
||||
```
|
||||
|
||||
如果其他 workspace crate 需要使用它，在对应 `Cargo.toml` 里加入：
|
||||
workspace 内其他 crate 使用：
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
@@ -48,29 +47,52 @@ wechat = { path = "../wechat" }
|
||||
|
||||
| 变量 | 必填 | 默认值 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `WEIXIN_BASE_URL` | 否 | `https://ilinkai.weixin.qq.com` | iLink Bot API 地址。测试、代理或私有部署时可覆盖。 |
|
||||
| `WEIXIN_BASE_URL` | 否 | `https://ilinkai.weixin.qq.com` | iLink Bot API 地址。显式传入 `base_url` 时优先使用显式值。 |
|
||||
|
||||
示例：
|
||||
## 单账号使用
|
||||
|
||||
```bash
|
||||
export WEIXIN_BASE_URL="https://ilinkai.weixin.qq.com"
|
||||
单账号生命周期：
|
||||
|
||||
```text
|
||||
WeChatClient::new
|
||||
login 或 set_auth
|
||||
set_updates_buf
|
||||
notify_start
|
||||
receive_messages loop
|
||||
send_text
|
||||
notify_stop
|
||||
```
|
||||
|
||||
## 基本生命周期
|
||||
### 扫码登录
|
||||
|
||||
推荐调用顺序：
|
||||
```rust
|
||||
use wechat::client::WeChatClient;
|
||||
|
||||
1. 创建客户端：`WeChatClient::new(None)`
|
||||
2. 扫码登录：`login(...)`
|
||||
3. 持久化登录结果：保存 `token`、`account_id`、`base_url`
|
||||
4. 注册监听器：`notify_start()`
|
||||
5. 循环拉取消息：`receive_messages()`
|
||||
6. 处理用户消息并回复：`send_text(...)`
|
||||
7. 服务退出前注销监听器：`notify_stop()`
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), String> {
|
||||
let client = WeChatClient::new(None);
|
||||
|
||||
## 快速开始
|
||||
let login = client
|
||||
.login(
|
||||
|qrcode_url| println!("二维码地址: {qrcode_url}"),
|
||||
120,
|
||||
)
|
||||
.await?;
|
||||
|
||||
下面示例会扫码登录，注册监听器，然后持续接收用户文本消息并原样回复。
|
||||
println!("account_id={}", login.account_id);
|
||||
println!("base_url={}", login.base_url);
|
||||
|
||||
// 业务层需要持久化:
|
||||
// login.token
|
||||
// login.account_id
|
||||
// login.base_url
|
||||
// login.user_id
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 恢复登录态并收消息
|
||||
|
||||
```rust
|
||||
use std::time::Duration;
|
||||
@@ -80,23 +102,27 @@ use wechat::types::WeixinMessage;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), String> {
|
||||
let client = WeChatClient::new(None);
|
||||
let mut client = WeChatClient::new(None);
|
||||
|
||||
let login = client
|
||||
.login(
|
||||
|qrcode_url| {
|
||||
println!("二维码地址: {qrcode_url}");
|
||||
},
|
||||
120,
|
||||
client
|
||||
.set_auth(
|
||||
"持久化保存的 token",
|
||||
"持久化保存的 account_id",
|
||||
"持久化保存的 base_url",
|
||||
)
|
||||
.await?;
|
||||
|
||||
println!("登录成功: account_id={}", login.account_id);
|
||||
.await;
|
||||
client
|
||||
.set_updates_buf("持久化保存的 get_updates_buf")
|
||||
.await;
|
||||
|
||||
client.notify_start().await?;
|
||||
|
||||
loop {
|
||||
let updates = client.receive_messages().await?;
|
||||
let latest_buf = client.get_updates_buf().await;
|
||||
|
||||
// 建议每次成功 receive 后持久化 latest_buf。
|
||||
persist_updates_buf(&latest_buf).await;
|
||||
|
||||
for msg in updates.msgs {
|
||||
if msg.msg_type != Some(WeixinMessage::TYPE_USER) {
|
||||
@@ -106,323 +132,210 @@ async fn main() -> Result<(), String> {
|
||||
let Some(from_user_id) = msg.from_user_id.as_deref() else {
|
||||
continue;
|
||||
};
|
||||
|
||||
let Some(text) = msg.text_content() else {
|
||||
continue;
|
||||
};
|
||||
|
||||
client
|
||||
.send_text(from_user_id, &format!("收到: {text}"), msg.context_token.as_deref())
|
||||
.send_text(
|
||||
from_user_id,
|
||||
&format!("收到: {text}"),
|
||||
msg.context_token.as_deref(),
|
||||
)
|
||||
.await?;
|
||||
}
|
||||
|
||||
tokio::time::sleep(Duration::from_secs(1)).await;
|
||||
}
|
||||
}
|
||||
|
||||
async fn persist_updates_buf(_buf: &str) {}
|
||||
```
|
||||
|
||||
## 登录
|
||||
## 多账号监听
|
||||
|
||||
完整登录接口：
|
||||
多账号监听使用 `WeChatMultiAccountManager`。它会为每个账号创建一个独立 `WeChatClient` 和一个独立 tokio 任务：
|
||||
|
||||
```text
|
||||
account A -> WeChatClient A -> getupdates(token A, buf A)
|
||||
account B -> WeChatClient B -> getupdates(token B, buf B)
|
||||
account C -> WeChatClient C -> getupdates(token C, buf C)
|
||||
```
|
||||
|
||||
这不是短轮询刷接口，而是长轮询。单次 `getupdates` 请求通常会被服务端挂起到有消息或超时，因此多个账号对应多个挂起请求是预期模型。
|
||||
|
||||
### 账号配置
|
||||
|
||||
```rust
|
||||
pub async fn login(
|
||||
&self,
|
||||
on_qrcode: impl Fn(&str),
|
||||
timeout_secs: u64,
|
||||
) -> Result<LoginResult, String>
|
||||
use wechat::manager::WeChatAccountConfig;
|
||||
|
||||
let account = WeChatAccountConfig::new(
|
||||
"account_id",
|
||||
"token",
|
||||
"base_url",
|
||||
"get_updates_buf",
|
||||
);
|
||||
```
|
||||
|
||||
参数说明：
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `on_qrcode` | 获取二维码内容后的回调。当前实现会传入 `qrcode_img_content`，通常是可打开或可展示为二维码的内容。 |
|
||||
| `timeout_secs` | 扫码确认总超时时间，单位秒。 |
|
||||
|
||||
返回值：
|
||||
|
||||
```rust
|
||||
pub struct LoginResult {
|
||||
pub token: String,
|
||||
pub account_id: String,
|
||||
pub base_url: String,
|
||||
pub user_id: String,
|
||||
}
|
||||
```
|
||||
|
||||
登录内部流程：
|
||||
|
||||
1. `get_qrcode()` 调用 `/ilink/bot/get_bot_qrcode` 获取二维码。
|
||||
2. 终端渲染二维码，同时打印二维码链接。
|
||||
3. `poll_qr_status()` 轮询 `/ilink/bot/get_qrcode_status`。
|
||||
4. 用户扫码并确认后，把 `bot_token` 和 `ilink_bot_id` 写入客户端内存。
|
||||
5. 返回 `LoginResult`，供业务层持久化。
|
||||
|
||||
扫码状态值：
|
||||
|
||||
| 状态 | 含义 | 当前处理 |
|
||||
| --- | --- | --- |
|
||||
| `wait` | 等待扫码 | 继续轮询 |
|
||||
| `scaned` | 已扫码，等待微信确认 | 提示用户确认 |
|
||||
| `scaned_but_redirect` | 需要切换 IDC | 使用 `redirect_host` 更新轮询地址 |
|
||||
| `confirmed` | 登录成功 | 保存 token/account_id 并返回 |
|
||||
| `expired` | 二维码过期 | 返回错误 |
|
||||
|
||||
## 恢复登录态
|
||||
|
||||
`wechat` 模块不负责把登录态写入数据库或文件。业务层应在登录成功后保存：
|
||||
|
||||
- `LoginResult.token`
|
||||
- `LoginResult.account_id`
|
||||
- `LoginResult.base_url`
|
||||
- `get_updates_buf()` 返回值，建议在每次 `receive_messages()` 成功后保存
|
||||
|
||||
下次启动时恢复：
|
||||
|
||||
```rust
|
||||
let mut client = WeChatClient::new(None);
|
||||
|
||||
client
|
||||
.set_auth(
|
||||
"持久化保存的 token",
|
||||
"持久化保存的 account_id",
|
||||
"持久化保存的 base_url",
|
||||
)
|
||||
.await;
|
||||
|
||||
client
|
||||
.set_updates_buf("持久化保存的 get_updates_buf")
|
||||
.await;
|
||||
|
||||
client.notify_start().await?;
|
||||
```
|
||||
|
||||
注意：`set_auth` 需要 `&mut self`，因此恢复登录态时变量要声明为 `mut`。
|
||||
|
||||
## 注册和注销监听器
|
||||
|
||||
注册监听器：
|
||||
|
||||
```rust
|
||||
client.notify_start().await?;
|
||||
```
|
||||
|
||||
注销监听器：
|
||||
|
||||
```rust
|
||||
client.notify_stop().await?;
|
||||
```
|
||||
|
||||
这两个接口分别调用：
|
||||
|
||||
- `POST /ilink/bot/msg/notifystart`
|
||||
- `POST /ilink/bot/msg/notifystop`
|
||||
|
||||
建议：
|
||||
|
||||
- 登录或恢复登录态后先调用 `notify_start()`，再开始拉消息。
|
||||
- 进程收到退出信号时调用 `notify_stop()`。
|
||||
- 如果进程异常退出，下一次启动后仍应重新调用 `notify_start()`。
|
||||
|
||||
## 接收消息
|
||||
|
||||
接口：
|
||||
|
||||
```rust
|
||||
pub async fn receive_messages(&self) -> Result<GetUpdatesResp, String>
|
||||
```
|
||||
|
||||
响应结构：
|
||||
|
||||
```rust
|
||||
pub struct GetUpdatesResp {
|
||||
pub ret: i32,
|
||||
pub errcode: Option<i32>,
|
||||
pub errmsg: Option<String>,
|
||||
pub msgs: Vec<WeixinMessage>,
|
||||
pub get_updates_buf: String,
|
||||
pub longpolling_timeout_ms: Option<i64>,
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 该接口调用 `/ilink/bot/getupdates`。
|
||||
- 客户端内部维护 `updates_buf`，并在响应里的 `get_updates_buf` 非空时自动更新。
|
||||
- 如果请求超时，当前实现返回一个空消息列表，不视为致命错误。
|
||||
- 如果 `ret != 0` 或 `errcode != 0`，当前实现会写 warn 日志，但仍把响应返回给调用方。
|
||||
|
||||
文本消息提取：
|
||||
|
||||
```rust
|
||||
for msg in updates.msgs {
|
||||
if msg.msg_type == Some(WeixinMessage::TYPE_USER) {
|
||||
if let Some(text) = msg.text_content() {
|
||||
println!("收到文本: {text}");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
消息关键字段：
|
||||
字段说明：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| --- | --- |
|
||||
| `msg_type` | `1` 表示用户消息，`2` 表示 Bot 消息。 |
|
||||
| `from_user_id` | 发送者 ID。回复私聊消息时通常作为 `send_text` 的 `to`。 |
|
||||
| `to_user_id` | 接收者 ID。 |
|
||||
| `group_id` | 群消息 ID，群聊场景可能非空。 |
|
||||
| `item_list` | 消息内容列表，可包含文本、图片、语音、文件、视频。 |
|
||||
| `context_token` | 微信上下文令牌。回复时透传可保持多轮上下文。 |
|
||||
| `account_id` | 微信 iLink Bot 账号 ID，来自登录返回的 `LoginResult.account_id`。 |
|
||||
| `token` | 登录返回的 `LoginResult.token`。 |
|
||||
| `base_url` | 登录返回的 `LoginResult.base_url`。 |
|
||||
| `updates_buf` | 上次轮询保存的 `get_updates_buf`，新账号可传空字符串。 |
|
||||
|
||||
## 发送文本消息
|
||||
|
||||
接口：
|
||||
### 启动多个账号
|
||||
|
||||
```rust
|
||||
pub async fn send_text(
|
||||
&self,
|
||||
to: &str,
|
||||
text: &str,
|
||||
context_token: Option<&str>,
|
||||
) -> Result<String, String>
|
||||
```
|
||||
use wechat::manager::{WeChatAccountConfig, WeChatEvent, WeChatMultiAccountManager};
|
||||
use wechat::types::WeixinMessage;
|
||||
|
||||
参数说明：
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), String> {
|
||||
let (mut manager, mut event_rx) = WeChatMultiAccountManager::new(1024);
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `to` | 接收者用户 ID。通常来自收到消息的 `from_user_id`。 |
|
||||
| `text` | 要发送的文本内容。 |
|
||||
| `context_token` | 可选上下文令牌，建议透传收到消息里的 `context_token`。 |
|
||||
|
||||
返回值是本地生成的 `client_id`，可用于日志追踪。
|
||||
|
||||
示例：
|
||||
|
||||
```rust
|
||||
let client_id = client
|
||||
.send_text(
|
||||
from_user_id,
|
||||
"你好，我是 Bot",
|
||||
msg.context_token.as_deref(),
|
||||
)
|
||||
.await?;
|
||||
|
||||
println!("消息已提交: client_id={client_id}");
|
||||
```
|
||||
|
||||
当前发送实现固定构造：
|
||||
|
||||
- `message_type = 2`，表示 Bot 消息
|
||||
- `message_state = 2`，表示完成态
|
||||
- `item_list = [MessageItem::text(text)]`
|
||||
|
||||
## 非文本消息
|
||||
|
||||
协议类型已经定义了以下消息 item：
|
||||
|
||||
- `TextItem`
|
||||
- `ImageItem`
|
||||
- `VoiceItem`
|
||||
- `FileItem`
|
||||
- `VideoItem`
|
||||
|
||||
当前便捷发送接口只实现了 `send_text()`。如果需要发送图片、文件或视频，需要新增对应的发送方法，构造 `WeixinMessage.item_list` 中的 `MessageItem`。
|
||||
|
||||
接收侧可以通过 `MessageItem.item_type` 判断类型：
|
||||
|
||||
```rust
|
||||
for item in msg.item_list.unwrap_or_default() {
|
||||
match item.item_type {
|
||||
Some(MessageItem::TYPE_TEXT) => {
|
||||
let text = item.text_item.and_then(|v| v.text);
|
||||
println!("文本: {:?}", text);
|
||||
}
|
||||
Some(MessageItem::TYPE_IMAGE) => {
|
||||
println!("图片: {:?}", item.image_item);
|
||||
}
|
||||
Some(MessageItem::TYPE_VOICE) => {
|
||||
println!("语音: {:?}", item.voice_item);
|
||||
}
|
||||
Some(MessageItem::TYPE_FILE) => {
|
||||
println!("文件: {:?}", item.file_item);
|
||||
}
|
||||
Some(MessageItem::TYPE_VIDEO) => {
|
||||
println!("视频: {:?}", item.video_item);
|
||||
}
|
||||
_ => {}
|
||||
let accounts = load_accounts().await;
|
||||
for account in accounts {
|
||||
manager.start_account(account).await?;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 长轮询循环建议
|
||||
while let Some(event) = event_rx.recv().await {
|
||||
match event {
|
||||
WeChatEvent::UpdatesBuf {
|
||||
account_id,
|
||||
updates_buf,
|
||||
} => {
|
||||
persist_updates_buf(&account_id, &updates_buf).await;
|
||||
}
|
||||
WeChatEvent::Message {
|
||||
account_id,
|
||||
message,
|
||||
updates_buf,
|
||||
} => {
|
||||
persist_updates_buf(&account_id, &updates_buf).await;
|
||||
|
||||
推荐业务层把接收循环放到独立 tokio task：
|
||||
|
||||
```rust
|
||||
let client_for_loop = client.clone();
|
||||
|
||||
tokio::spawn(async move {
|
||||
loop {
|
||||
match client_for_loop.receive_messages().await {
|
||||
Ok(updates) => {
|
||||
for msg in updates.msgs {
|
||||
// 处理消息
|
||||
if message.msg_type != Some(WeixinMessage::TYPE_USER) {
|
||||
continue;
|
||||
}
|
||||
|
||||
let Some(from_user_id) = message.from_user_id.as_deref() else {
|
||||
continue;
|
||||
};
|
||||
let Some(text) = message.text_content() else {
|
||||
continue;
|
||||
};
|
||||
|
||||
manager
|
||||
.send_text(
|
||||
&account_id,
|
||||
from_user_id,
|
||||
&format!("账号 {account_id} 收到: {text}"),
|
||||
message.context_token.as_deref(),
|
||||
)
|
||||
.await?;
|
||||
}
|
||||
Err(err) => {
|
||||
tracing::warn!("接收微信消息失败: {err}");
|
||||
tokio::time::sleep(std::time::Duration::from_secs(3)).await;
|
||||
WeChatEvent::PollError { account_id, error } => {
|
||||
tracing::warn!("微信账号轮询失败 account_id={account_id}: {error}");
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- `WeChatClient` 实现了 `Clone`，内部 token、account_id 和 updates_buf 使用 `Arc<Mutex<_>>` 共享。
|
||||
- `receive_messages()` 已经处理普通超时，业务层不需要把空消息视为错误。
|
||||
- 处理消息时建议过滤 `WeixinMessage::TYPE_BOT`，避免重复处理 Bot 自己发出的消息。
|
||||
- 每次成功拉取后可以调用 `get_updates_buf()` 并持久化，降低重启后重复收消息的概率。
|
||||
|
||||
## 与 AI 回复集成示例
|
||||
|
||||
示例逻辑：收到用户文本后调用业务自己的 AI 函数，再把结果发回微信。
|
||||
|
||||
```rust
|
||||
async fn handle_wechat_message(client: &WeChatClient, msg: WeixinMessage) -> Result<(), String> {
|
||||
if msg.msg_type != Some(WeixinMessage::TYPE_USER) {
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
let Some(from_user_id) = msg.from_user_id.as_deref() else {
|
||||
return Ok(());
|
||||
};
|
||||
|
||||
let Some(user_text) = msg.text_content() else {
|
||||
return Ok(());
|
||||
};
|
||||
|
||||
let answer = call_ai(user_text).await?;
|
||||
|
||||
client
|
||||
.send_text(from_user_id, &answer, msg.context_token.as_deref())
|
||||
.await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
async fn call_ai(input: &str) -> Result<String, String> {
|
||||
Ok(format!("AI 回复: {input}"))
|
||||
async fn load_accounts() -> Vec<WeChatAccountConfig> {
|
||||
vec![]
|
||||
}
|
||||
|
||||
async fn persist_updates_buf(_account_id: &str, _buf: &str) {}
|
||||
```
|
||||
|
||||
### 停止账号
|
||||
|
||||
停止单个账号：
|
||||
|
||||
```rust
|
||||
manager.stop_account("account_id").await?;
|
||||
```
|
||||
|
||||
停止全部账号：
|
||||
|
||||
```rust
|
||||
let results = manager.stop_all().await;
|
||||
for (account_id, result) in results {
|
||||
if let Err(err) = result {
|
||||
tracing::warn!("停止微信账号失败 account_id={account_id}: {err}");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`stop_account` 会先中止本地轮询任务，再尽力调用 `notify_stop()`。如果进程直接退出，`Drop` 会 abort 本地任务，但无法异步调用 `notify_stop()`，所以生产环境建议在收到退出信号时显式调用 `stop_all()`。
|
||||
|
||||
## 为什么不能一个轮询监听多个账号
|
||||
|
||||
iLink Bot 的 `getupdates` 是按 `Authorization: Bearer <token>` 鉴权的。一个 token 只对应一个 Bot 账号，服务端不会在同一个请求里返回其他账号的消息。
|
||||
|
||||
必须隔离的账号状态：
|
||||
|
||||
| 状态 | 为什么必须隔离 |
|
||||
| --- | --- |
|
||||
| `token` | 决定当前请求属于哪个账号。 |
|
||||
| `base_url` | 登录可能返回账号实际使用的 IDC 地址。 |
|
||||
| `get_updates_buf` | 轮询游标，混用会导致消息重复、丢失或串账号。 |
|
||||
| `context_token` | 回复上下文，混用会导致回复到错误会话或上下文断裂。 |
|
||||
|
||||
因此多账号正确模型是“多个长轮询任务”，不是“一个共享轮询”。
|
||||
|
||||
## 持久化建议
|
||||
|
||||
本 crate 不绑定数据库或文件系统，业务层应自行持久化以下数据。
|
||||
|
||||
账号表建议字段：
|
||||
|
||||
```text
|
||||
account_id string primary key
|
||||
token string
|
||||
base_url string
|
||||
user_id string optional
|
||||
updates_buf string
|
||||
updated_at timestamp
|
||||
```
|
||||
|
||||
收到 `WeChatEvent::Message` 后，使用事件里的 `updates_buf` 更新对应账号的游标。
|
||||
|
||||
如果要支持主动发送消息，建议额外维护：
|
||||
|
||||
```text
|
||||
account_id
|
||||
from_user_id
|
||||
context_token
|
||||
updated_at
|
||||
```
|
||||
|
||||
收到用户消息时按 `account_id + from_user_id` 保存 `context_token`。主动发送时优先显式传 `account_id`，再取对应用户最近的 `context_token`。
|
||||
|
||||
## 发送消息路由
|
||||
|
||||
多账号场景下发送消息必须明确使用哪个账号：
|
||||
|
||||
```rust
|
||||
manager
|
||||
.send_text(
|
||||
"account_id",
|
||||
"to_user_id",
|
||||
"回复内容",
|
||||
Some("context_token"),
|
||||
)
|
||||
.await?;
|
||||
```
|
||||
|
||||
不建议只按 `to_user_id` 自动推断账号。原因是同一个用户可能和多个 Bot 账号都有会话，自动推断会产生歧义。
|
||||
|
||||
## API 端点
|
||||
|
||||
`WeChatClient` 当前使用以下 iLink Bot API：
|
||||
当前封装使用以下 iLink Bot API：
|
||||
|
||||
| 方法 | 路径 | 用途 |
|
||||
| --- | --- | --- |
|
||||
@@ -433,25 +346,34 @@ async fn call_ai(input: &str) -> Result<String, String> {
|
||||
| `POST` | `/ilink/bot/getupdates` | 长轮询拉取消息 |
|
||||
| `POST` | `/ilink/bot/sendmessage` | 发送消息 |
|
||||
|
||||
请求头由模块内部生成：
|
||||
登录后请求会带：
|
||||
|
||||
- `Content-Type: application/json`
|
||||
- `Content-Length`
|
||||
- `iLink-App-ClientVersion`
|
||||
- `X-WECHAT-UIN`
|
||||
- 登录后请求额外带：
|
||||
- `Authorization: Bearer <token>`
|
||||
- `AuthorizationType: ilink_bot_token`
|
||||
```text
|
||||
Authorization: Bearer <token>
|
||||
AuthorizationType: ilink_bot_token
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
| 场景 | 当前行为 | 建议 |
|
||||
| --- | --- | --- |
|
||||
| 二维码过期 | `login()` 返回 `二维码已过期` | 重新登录。 |
|
||||
| 登录超时 | `login()` 返回 `登录超时` | 增大超时或重新登录。 |
|
||||
| 长轮询超时 | `receive_messages()` 返回空消息 | 正常情况，继续轮询。 |
|
||||
| 游标更新 | manager 发送 `WeChatEvent::UpdatesBuf` | 立即持久化对应账号的 `updates_buf`。 |
|
||||
| 轮询错误 | manager 发送 `WeChatEvent::PollError` 并继续重试 | 记录日志，必要时触发重新登录。 |
|
||||
| token 失效 | API 返回错误或 HTTP 鉴权失败 | 清理该账号 token，重新扫码登录。 |
|
||||
| 多账号重复启动 | `start_account()` 返回错误 | 保证同一 `account_id` 只启动一次。 |
|
||||
|
||||
## 日志
|
||||
|
||||
模块使用 `tracing` 输出日志，主要 target 为：
|
||||
模块使用 `tracing`，主要 target：
|
||||
|
||||
```text
|
||||
ias::auth
|
||||
```
|
||||
|
||||
业务程序可初始化日志：
|
||||
推荐初始化：
|
||||
|
||||
```rust
|
||||
tracing_subscriber::fmt()
|
||||
@@ -459,34 +381,19 @@ tracing_subscriber::fmt()
|
||||
.init();
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
所有公开异步方法当前返回 `Result<_, String>`。
|
||||
|
||||
常见错误：
|
||||
|
||||
| 场景 | 典型错误 | 处理建议 |
|
||||
| --- | --- | --- |
|
||||
| 二维码过期 | `二维码已过期` | 重新调用 `login()`。 |
|
||||
| 登录超时 | `登录超时` | 增大 `timeout_secs` 或重新登录。 |
|
||||
| token 无效 | HTTP 401/403 或接口返回错误 | 清理持久化登录态，重新扫码登录。 |
|
||||
| 长轮询超时 | 返回空 `msgs` | 正常情况，继续下一轮。 |
|
||||
| 网络错误 | `请求失败` | 延迟重试，必要时检查 `WEIXIN_BASE_URL`。 |
|
||||
|
||||
## 当前限制
|
||||
|
||||
- `ILINK_APP_ID` 当前是空字符串。如接入方要求 app id，需要在 `client.rs` 中配置或改造成环境变量。
|
||||
- 登录态只保存在内存中，重启恢复需要业务层调用 `set_auth()` 和 `set_updates_buf()`。
|
||||
- 只提供文本发送便捷方法 `send_text()`。
|
||||
- 群聊回复策略需要业务层结合 `group_id` 和实际 iLink 协议进一步确认。
|
||||
- `send_text()` 当前不解析服务端响应体，只在 HTTP 层确认请求成功后返回本地 `client_id`。
|
||||
- `send_text()` 只封装文本发送。
|
||||
- manager 不内置账号持久化，业务层负责数据库或文件存储。
|
||||
- manager 通过 `JoinHandle::abort()` 停止长轮询任务；如需立即优雅取消 HTTP 请求，可后续在 client 层增加 cancellation 支持。
|
||||
- `ILINK_APP_ID` 当前为空字符串；如果接入方要求 app id，需要在 `client.rs` 中配置或改为环境变量。
|
||||
|
||||
## 排障清单
|
||||
|
||||
1. 确认能访问 `WEIXIN_BASE_URL`。
|
||||
2. 确认扫码后在微信侧完成确认。
|
||||
3. 登录后先调用 `notify_start()`，再调用 `receive_messages()`。
|
||||
4. 如果收不到消息，检查 `get_updates_buf` 是否恢复了过旧状态；必要时清空后重试。
|
||||
5. 如果发送失败，检查 token 是否过期，以及 `to` 是否使用了正确的 `from_user_id`。
|
||||
6. 打开 `ias::auth=debug` 日志观察 API 请求和状态变化。
|
||||
|
||||
1. 确认 `base_url` 可访问。
|
||||
2. 确认账号已经扫码登录并保存了 token。
|
||||
3. 每个账号只启动一个监听任务。
|
||||
4. 每个账号独立保存 `updates_buf`。
|
||||
5. 登录或恢复后先调用 `notify_start()`，再开始 `getupdates`。
|
||||
6. 发送消息时显式指定 `account_id`，并尽量透传 `context_token`。
|
||||
7. 打开 `ias::auth=debug` 查看请求和轮询状态。
|
||||
|
||||
Reference in New Issue
Block a user