feat: 为全部 39 个 Rust 源文件添加系统性中文注释

为整个项目添加了详尽的中文文档注释，覆盖所有模块：

入口与架构:
- main.rs — 架构图、数据流、4 个关键设计决策
- cli.rs — 所有 CLI 子命令中文化
- Cargo.toml — 每个依赖的作用说明
- channel/mod.rs — 渠道标识设计意图

核心守护进程与消息队列:
- daemon.rs — 三消费者架构图、审批流
- queue/* — 公平轮转算法、路由调度架构

LLM 层:
- types.rs — Role/Message/ToolCall 等每个字段含义
- provider.rs — Provider trait 设计 + SSE 解析
- conversation.rs — 工具循环流程图、摘要机制
- deepseek.rs — API 请求格式

上下文管理:
- context/types.rs — ChatSession 消息生命周期
- context/builder.rs — Token 预算管理策略
- context/tools.rs — MemoryStore 双写策略

工具系统:
- tools/mod.rs — 两层元工具架构图
- tools/approval.rs — 审批流程
- tools/definitions.rs — 声明式工具三要素
- tools/subprocess.rs — 执行流程 + 缓存策略

数据库与状态:
- db/* — 5 张表用途、回退策略
- state.rs — 文件存储回退方案
- scheduler.rs — SKIP LOCKED 防重复

已废弃模块:
- ipc.rs — 旧 UDS 协议
- worker.rs — 旧 vs 新架构对比

src/wechat/client.rs

@@ -6,7 +6,24 @@ use std::time::Duration;
 use tokio::sync::Mutex;
 use tracing::{debug, info, warn};
 
-/// 微信 iLink Bot API 客户端
+/// ## 微信 iLink Bot API 客户端
+///
+/// ### 职责
+/// 封装了与微信 iLink Bot API 的所有通信，包括：
+/// * 扫码登录流程（获取二维码、轮询状态）
+/// * 消息接收（长轮询 getUpdates）
+/// * 消息发送（sendMessage）
+/// * 生命周期管理（notifyStart/notifyStop）
+///
+/// ### 线程安全
+/// `#[derive(Clone)]` + 内部 `Arc<Mutex<>>` 保证所有方法可以在 tokio task 间共享。
+///
+/// ### API 端点
+/// * 二维码: `{base_url}/ilink/bot/get_bot_qrcode`
+/// * 登录状态: `{base_url}/ilink/bot/get_qrcode_status`
+/// * 收消息: `{base_url}/ilink/bot/getupdates`
+/// * 发消息: `{base_url}/ilink/bot/sendmessage`
+/// * 注册监听: `{base_url}/ilink/bot/msg/notifystart`
 #[derive(Clone)]
 pub struct WeChatClient {
     http: HttpClient,
@@ -46,7 +63,10 @@ impl WeChatClient {
 
     // ─── 公共方法 ───
 
-    /// 获取登录二维码链接
+    /// ## 获取登录二维码链接
+///
+    /// 调用 iLink API `/ilink/bot/get_bot_qrcode` 获取二维码。
+    /// 二维码内容是一个 URL，浏览器打开后显示二维码图片。
     pub async fn get_qrcode(&self) -> Result<(String, String), String> {
         let url = format!(
             "{}/ilink/bot/get_bot_qrcode?bot_type={}",
@@ -68,7 +88,16 @@ impl WeChatClient {
         Ok((resp.qrcode, resp.qrcode_img_content))
     }
 
-    /// 轮询扫码状态
+    /// ## 轮询扫码状态（带 35 秒超时的长轮询）
+    ///
+    /// 调用 iLink API 检查用户是否已扫码。
+    /// * `wait` — 继续等待
+    /// * `scaned` — 已扫码，等待确认
+    /// * `scaned_but_redirect` — IDC 重定向（切换到 redirect_host）
+    /// * `confirmed` — 登录成功
+    /// * `expired` — 二维码过期
+    ///
+    /// 网络错误不会导致退出，而是返回 `wait` 让调用者继续轮询。
     pub async fn poll_qr_status(
         &self,
         qrcode: &str,
@@ -358,6 +387,12 @@ impl WeChatClient {
 
     // ─── 内部方法 ───
 
+    /// ## 公共请求头
+///
+    /// 每个请求都携带以下头信息：
+    /// * `Content-Type: application/json`
+    /// * `iLink-App-ClientVersion` — 客户端版本号编码
+    /// * `X-WECHAT-UIN` — 随机 uint32 → base64 编码的会话标识
     fn common_headers() -> reqwest::header::HeaderMap {
         let mut headers = reqwest::header::HeaderMap::new();
         headers.insert(

src/wechat/types.rs

@@ -116,7 +116,12 @@ pub struct RefMessage {
     pub title: Option<String>,
 }
 
-/// 消息条目（支持 text/image/voice/file/video）
+/// ## 消息条目 —— 消息的具体内容
+///
+/// 支持 5 种消息类型：text(1), image(2), voice(3), file(4), video(5)。
+/// 每种类型有对应的 `*_item` 字段，其他字段保持 None。
+///
+/// `text()` 便捷方法用于快速构造文本消息（发送消息时使用）。
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MessageItem {
     #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
@@ -183,7 +188,18 @@ impl Default for MessageItem {
     }
 }
 
-// ─── 微信消息 ───
+/// ## 微信消息结构
+///
+/// 对应 iLink API 返回的单个消息。所有字段都是 Option 的，
+/// 因为不同消息类型携带不同字段。
+///
+/// ### 关键字段
+/// * `msg_type` — 消息类型：1=用户消息(TYPE_USER), 2=机器人消息(TYPE_BOT)
+/// * `from_user_id` — 发送者微信 ID
+/// * `to_user_id` — 接收者微信 ID
+/// * `item_list` — 消息内容列表（支持 text/image/voice/file/video）
+/// * `context_token` — 微信上下文令牌（用于多轮对话的上下文恢复）
+/// * `group_id` — 群聊 ID（群消息时非空）
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct WeixinMessage {