chore: keep clippy green on stable Rust

fix: accept WeChat 4.1.7 and newer
feat: expose avatars and image quality metadata
2026-08-29 04:00:55 +00:00 · 2026-08-26 06:36:06 +00:00 · 2026-08-26 06:20:16 +00:00 · 2026-07-22 11:20:16 +08:00 · 2026-07-10 23:09:55 +08:00 · 2026-07-10 19:29:29 +08:00
57 changed files with 1161 additions and 419 deletions
@@ -2,6 +2,44 @@
 All notable changes to this project will be documented in this file.
 ## [Unreleased]
 ### Changed
 - Accept WeChat 4.1.7 and newer for key extraction instead of maintaining a fixed version-prefix allowlist.
 ## [0.7.4] - 2026-07-22
 ### Features
 - **Contact and conversation avatars** — Expose an optional `avatar_url` in contact and enriched session JSON, preferring the small avatar and falling back to the large avatar while remaining compatible with older database schemas
 - **Image quality metadata** — Mark `/api/v1/media` image responses as `full` or `thumbnail`, while continuing to prefer locally available high-resolution/original image files
 ### Maintenance
 - Keep formatting and Clippy clean on the current stable Rust toolchain, and serialize integration-test server startup to avoid ephemeral-port races
 ## [0.7.3] - 2026-07-10
 ### Features
 - **Agent-ready WeChat data layer** — Ship an Agent Skill for Claude Code, Codex, Cursor, and other compatible agents to query and subscribe to local WeChat data
 - **Cross-conversation timeline** — Add `GET /api/v1/timeline` for time-bounded message reads across all conversations in one request, with pagination, ordering, message-type filters, and privacy filtering
 - **Compact timeline output** — Return the conversation identity, sender, direction, timestamp, type, and snippet needed by memory, archive, and reporting agents without duplicating raw message payloads
 ### Performance
 - **Reuse SQLCipher derived keys** — Cache per-database derived keys and reuse them across open, count, refresh, and reopen paths instead of repeating the 256k-round KDF
 - **Bound timeline memory** — Keep only the candidates required for the requested page rather than retaining the complete cross-conversation history during sorting
 - **Faster long-running server queries** — Reuse warm database connections for batch timeline reads, avoiding one CLI process and HTTP round trip per conversation
 ### Documentation and maintenance
 - Rewrite the README around user-facing capabilities: local database access, real-time subscriptions, Agent integration, automation, memory, CRM, and workflow use cases
 - Document Release installation and the bundled Agent Skill
 - Update project dependencies and GitHub Actions
 - Restore clean `cargo fmt --check`, `cargo clippy -- -D warnings`, and full-workspace test baselines
 ## [0.7.2] - 2026-04-06
 ### Features
@@ -2,6 +2,41 @@
 本文件记录项目的所有重要变更。
 ## [未发布]
 ### 变更
 - 密钥提取改为支持 WeChat 4.1.7 及以上版本，不再维护固定版本前缀白名单。
 ## [0.7.4] - 2026-07-22
 ### 功能
 - **联系人和会话头像** — 联系人与会话 JSON 新增可选 `avatar_url`；优先使用小头像、回退大头像，并兼容没有头像字段的旧数据库
 - **图片质量元数据** — `/api/v1/media` 图片响应会标记为 `full` 或 `thumbnail`，并继续优先返回本机已有的高清/原图文件
 ### 维护
 - 适配当前 stable Rust 的格式化和 Clippy 检查，并串行化集成测试服务启动，避免并行抢占临时端口
 ## [0.7.3] - 2026-07-10
 ### 功能
 - **Agent 可用的微信数据层** — 提供 Agent Skill，让 Claude Code、Codex、Cursor 等 Agent 查询和订阅本地微信数据
 - **跨会话时间线** — 新增 `GET /api/v1/timeline`，可在有界时间范围内一次读取所有会话，并支持分页、排序、消息类型筛选和隐私过滤
 - **精简时间线输出** — 返回记忆、归档和报告 Agent 所需的会话、发送者、方向、时间、类型和摘要字段
 ### 性能
 - 复用 SQLCipher 派生密钥，避免在打开、计数、刷新和重开数据库时重复执行 25.6 万轮 KDF
 - 限制时间线排序内存，长驻服务会复用预热的数据库连接
 ### 文档与维护
 - 重写 README，补充 Release 安装方式和 Agent Skill 说明
 - 更新依赖与 GitHub Actions，恢复格式化、Clippy 和全量测试基线
 ## [0.7.2] - 2026-04-06
 ### 功能
@@ -3132,7 +3132,7 @@ checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
 [[package]]
 name = "wx-cli"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "axum",
 "chrono",
@@ -3168,7 +3168,7 @@ dependencies = [
 [[package]]
 name = "wx-context"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "aes",
 "cbc",
@@ -3192,7 +3192,7 @@ dependencies = [
 [[package]]
 name = "wx-db"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "hex",
 "insta",
@@ -3209,7 +3209,7 @@ dependencies = [
 [[package]]
 name = "wx-decrypt"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "aes",
 "cbc",
@@ -3222,7 +3222,7 @@ dependencies = [
 [[package]]
 name = "wx-keychain"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "aes",
 "cbc",
@@ -3244,7 +3244,7 @@ dependencies = [
 [[package]]
 name = "wx-media"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "aes",
 "base64",
@@ -3262,7 +3262,7 @@ dependencies = [
 [[package]]
 name = "wx-monitor"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "aes",
 "cbc",
@@ -3283,7 +3283,7 @@ dependencies = [
 [[package]]
 name = "wx-paths"
-version = "0.7.2"
+version = "0.7.4"
 dependencies = [
 "dirs",
 "libc",
@@ -3,7 +3,7 @@ members = ["crates/wx-decrypt", "crates/wx-keychain", "crates/wx-cli", "crates/w
 resolver = "2"
 [workspace.package]
-version = "0.7.2"
+version = "0.7.4"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/pandorafuture/wx-cli"
@@ -1,11 +1,44 @@
 # wx-cli
-WeChat macOS 数据库解密与查询工具。支持通过 `key extract`（LLDB hook）提取密钥，解密并查询 WeChat 4.1.7.x / 4.1.8.x 的 Apple SEE 加密 SQLite 数据库。
+> 把微信变成 Agent 能读取、能搜索、能实时订阅的数据源。
 wx-cli 直接读取 Mac 上的微信本地数据，让你和 Agent 都能访问自己的聊天记录、联系人、群聊和媒体消息。数据默认留在本机，不需要上传聊天数据库，也不依赖云端导出。
 ## 它能做什么
 - **读取微信本地数据库**：按联系人、群聊、时间范围和消息类型查询历史消息。
 - **搜索全部聊天记录**：从所有会话中查关键词，快速找回客户需求、承诺、文件和讨论结论。
 - **一次读取跨会话时间线**：按时间范围取得所有会话的新消息，适合记忆补全、归档和日报任务。
 - **实时订阅新消息**：用命令行持续监听，或通过 SSE 把新消息实时推给 Agent 和其他程序。
 - **导出与处理内容**：把会话导出为 JSON 或文本，并读取图片、语音、视频等媒体内容。
 - **让 Agent 直接使用**：项目自带 Agent Skill，Claude Code、Codex、Cursor 等工具安装后就知道怎样查询和订阅微信。
 - **提供稳定的本地服务**：REST API 可供个人助理、自动化任务、工作流和多个 Agent 共同使用。
 - **保护不想暴露的内容**：可隐藏指定联系人、群聊、标签或群成员，查询和订阅时自动过滤。
 ## 你可以基于它在微信上做什么
 wx-cli 提供了最关键的两样东西：完整的历史上下文，以及持续发生的实时消息。把它接给 Agent 后，你可以基于这个项目在微信上做任何事，例如：
 - 给 Agent 建立长期微信记忆，自动维护联系人画像和关系上下文；
 - 从聊天里识别待办、承诺、商机、风险和需要跟进的人；
 - 做个人或团队的微信搜索、知识库、CRM、客服和销售助手；
 - 自动生成日报、周报、客户纪要、对账线索和项目进展；
 - 监听关键词或关键联系人，在重要消息出现时触发提醒和工作流；
 - 结合你已有的 Agent 操作或消息发送能力，实现自动回复、业务办理和端到端协作。
 它不是只用来“导出聊天记录”的工具，而是微信之上的 Agent 能力层。
 ## 为什么对 Agent 友好
 - 自带可直接安装的 Skill，不需要每次重新教 Agent 命令和数据格式；
 - 命令行、JSON、REST API 和实时事件订阅覆盖查询与持续运行两类任务；
 - 长驻服务可复用已打开的数据库，适合高频查询和定时记忆任务；
 - 所有能力都以本地数据为中心，便于控制隐私边界。
 ## 支持范围
 - **平台**：macOS（arm64 / Apple Silicon）
- **WeChat 版本**：4.1.7.x / 4.1.8.x
+- **WeChat 版本**：4.1.7 及以上
 ## 前置条件
@@ -60,10 +93,9 @@ source ~/.zshrc
 wx-cli --version
 ```
 ### 让 Agent 直接使用
-### AI 编程助手集成
+本项目提供 [Agent Skill](https://skills.sh)。安装后，Claude Code、Codex、Cursor 等 Agent 可以直接理解 wx-cli 的能力，并帮你读取历史消息、搜索聊天和订阅新消息：
 本项目提供 [Agent Skill](https://skills.sh)，安装后 Claude Code、Codex、Cursor 等 AI 编程助手可直接协助查询微信数据：
 ```bash
 npx skills add pandorafuture/wx-cli
@@ -141,7 +173,13 @@ wx-cli server stop                             # 停止
 wx-cli server restart                          # 重启
 ```
-REST 端点：`/api/v1/health`、`/api/v1/sessions`、`/api/v1/contacts`、`/api/v1/messages`、`/api/v1/search`、`/api/v1/media`、`/api/v1/events`（SSE）。
+REST 端点：`/api/v1/health`、`/api/v1/sessions`、`/api/v1/contacts`、`/api/v1/messages`、`/api/v1/timeline`、`/api/v1/search`、`/api/v1/media`、`/api/v1/events`（SSE）。
 `/api/v1/media` 的图片响应会通过 `X-Wechat-Media-Quality: full|thumbnail` 标明本机返回的是完整图还是缩略图；服务始终优先选择本机已经下载的高清/原图。
 会话与联系人 JSON 在本地数据库有记录时会返回可选的 `avatar_url`，可用于展示个人或群聊头像；没有头像字段的旧数据库会省略该值。
 其中 `/api/v1/timeline?since=<unix>&until=<unix>` 可在一次请求中读取时间范围内所有会话的消息，适合 Agent 记忆补全、归档和批处理，避免逐会话反复调用。
 所有查询命令加 `--format json` 可获取 JSON 格式输出。
@@ -227,4 +265,4 @@ wx-cli/
 - `wx-cli key list` 确认密钥正确
 - `wx-cli info <db>` 检查文件是否为加密状态
- 确认 WeChat 版本在 4.1.7.x / 4.1.8.x 范围内
+- 确认 WeChat 版本不低于 4.1.7
@@ -258,10 +258,13 @@ wx-cli server status / stop / restart                      # 管理服务
 | `GET /api/v1/sessions` | 会话列表 | `limit`, `offset`, `order`, `show_hidden` |
 | `GET /api/v1/contacts` | 联系人列表 | `limit`, `offset`, `search`, `show_hidden` |
 | `GET /api/v1/messages` | 消息查询 | `contact`（必填）, `limit`, `offset`, `since`, `until`, `type`, `order`, `around_sort_seq`, `around_server_id`, `after_sort_seq`, `context`, `show_hidden` |
 | `GET /api/v1/timeline` | 跨全部会话按时间批量读取消息 | `since`（必填）, `until`（必填）, `limit`, `offset`, `type`, `order`, `show_hidden` |
 | `GET /api/v1/media` | 媒体内容直出 | `server_id`（必填）, `talker`（必填）, `format=ogg\|mp3`（仅语音） |
 | `GET /api/v1/search` | 全文搜索 | `q`（必填）, `limit`, `offset` |
 | `GET /api/v1/events` | SSE 事件流 | 无 |
 图片响应会携带 `X-Wechat-Media-Quality: full|thumbnail`。服务会优先返回本机已有的高清/原图文件；若微信只下载过缩略图，则返回 `thumbnail`，调用方不应长期缓存，并可在微信下载原图后重试。
 **认证：** 带 `--token` 启动时须携带 `Authorization: Bearer <token>`。`--host` 不是本机地址时 `--token` 必填。
 当前 HTTP API 为**只读**，没有 send/reply/webhook 等写接口。
@@ -311,13 +314,15 @@ wx-cli sessions                         # 4. 重试查询
 | 命令 | item 关键字段 |
 |------|-------------|
-| sessions | `username`, `display_name`, `summary`, `sort_timestamp`, `direction?` |
+| sessions | `username`, `display_name`, `avatar_url?`, `summary`, `sort_timestamp`, `direction?` |
 | query | `sort_seq`, `server_id`, `msg_type`, `sender`, `content`, `direction` |
-| contacts | `user_name`, `alias`, `remark`, `nick_name`, `phone`, `labels` |
+| timeline API | `sort_seq`, `server_id`, `msg_type`, `sender`, `talker`, `talker_display_name`, `create_time`, `direction`, `snippet`；统一按时间跨会话排序 |
 | contacts | `user_name`, `alias`, `remark`, `nick_name`, `avatar_url?`, `phone`, `labels` |
 | search | `server_id`, `talker`, `sender`, `snippet`, `hit_type` |
 **易混淆字段：**
 - contacts 用 `user_name`（下划线），sessions 用 `username`（无下划线）
 - `avatar_url` 优先取微信小头像地址，缺失时回退大头像地址；本地没有记录时不输出
 - message 的 `sender` 才是消息级 self/other 判断依据
 - `/api/v1/health` 的 `current_account.wxid` 是判断"我发的"的主事实源
@@ -6,7 +6,9 @@ use wx_db::Contact;
 use super::thin_client::{ThinClientCliArgs, ThinClientOptions};
 use crate::output::JsonEnvelope;
 use crate::settings::Settings;
-use crate::util::{effective_limit_all, open_db_core, print_cache_stats, print_detection_note, try_remote_or_local};
+use crate::util::{
    effective_limit_all, open_db_core, print_cache_stats, print_detection_note, try_remote_or_local,
 };
 use crate::visibility_projection::project_contacts_envelope;
 use crate::OutputFormat;
@@ -74,8 +74,7 @@ pub fn cmd_decrypt(
            KeyMaterial::EncKey { key, salt } => {
                wx_decrypt::decrypt_db_direct(db_path, &out_path, key, salt, params)
            }
-            KeyMaterial::EncKeys(pairs) => {
+            KeyMaterial::EncKeys(pairs) => match wx_decrypt::read_main_db_salt_for_path(db_path) {
                match wx_decrypt::read_main_db_salt_for_path(db_path) {
                Ok(db_salt) => match pairs.iter().find(|p| p.salt == db_salt) {
                    Some(pair) => wx_decrypt::decrypt_db_direct(
                        db_path, &out_path, &pair.key, &pair.salt, params,
@@ -83,8 +82,7 @@ pub fn cmd_decrypt(
                    None => Err(wx_decrypt::DecryptError::NoMatchingEncKey),
                },
                Err(e) => Err(e),
-                }
+            },
            }
        };
        match db_result {
@@ -98,9 +96,9 @@ pub fn cmd_decrypt(
                        KeyMaterial::RawKey(key) => {
                            wx_decrypt::decrypt_wal(&wal_path, &out_path, key, params)
                        }
-                        KeyMaterial::EncKey { key, salt } => wx_decrypt::decrypt_wal_direct(
+                        KeyMaterial::EncKey { key, salt } => {
-                            &wal_path, &out_path, key, salt, params,
+                            wx_decrypt::decrypt_wal_direct(&wal_path, &out_path, key, salt, params)
-                        ),
+                        }
                        KeyMaterial::EncKeys(pairs) => {
                            match wx_decrypt::read_main_db_salt_for_path(&wal_path) {
                                Ok(db_salt) => match pairs.iter().find(|p| p.salt == db_salt) {
@@ -7,9 +7,9 @@ use wx_context::{
 };
 use wx_db::{is_group_chat, MessageContent, MessageQuery, SortOrder, MAX_QUERY_LIMIT};
 use crate::cmd::contacts::build_visibility;
 use crate::cmd::export_media::{MediaKind, MediaStats};
 use crate::cmd::query::resolve_talker;
 use crate::cmd::contacts::build_visibility;
 use crate::output::{JsonEnvelope, PagingMeta, StatsMeta};
 use crate::schema::{enrich_message, project_message_items, EnrichedMessage};
 use crate::util::{
@@ -247,10 +247,9 @@ pub fn cmd_export(
    }
    // Resolve media via parallel pipeline (or skip)
-    let (media_map, media_stats, _media_errors) = if no_media || cache.is_none() {
+    let (media_map, media_stats, _media_errors) = if no_media {
        (vec![vec![]; projected.len()], MediaStats::default(), None)
-    } else {
+    } else if let Some(c) = cache.as_ref() {
        let c = cache.as_ref().unwrap();
        let attach_dir = acct.data_dir.join("msg").join("attach");
        let decrypted_media = c.decrypted_root().join("message");
        let hardlink_db = c.decrypted_root().join("hardlink").join("hardlink.db");
@@ -294,6 +293,8 @@ pub fn cmd_export(
        };
        combined.print_report();
        (media_map, stats, Some(combined))
    } else {
        (vec![vec![]; projected.len()], MediaStats::default(), None)
    };
    let total_media: usize = media_map.iter().map(Vec::len).sum();
@@ -421,7 +421,10 @@ impl MediaBridge {
    }
 }
-pub fn export_image_bytes(decoded_data: Vec<u8>, decoded_ext: &str) -> (Vec<u8>, String, bool, bool) {
+pub fn export_image_bytes(
    decoded_data: Vec<u8>,
    decoded_ext: &str,
 ) -> (Vec<u8>, String, bool, bool) {
    if decoded_ext != "wxgf" {
        return (decoded_data, decoded_ext.to_string(), false, false);
    }
@@ -197,10 +197,9 @@ impl VoiceConnectionPool {
    fn open_all(&self) -> Vec<Connection> {
        let mut conns = Vec::new();
        for path in &self.db_paths {
-            if let Ok(conn) = Connection::open_with_flags(
+            if let Ok(conn) =
-                path,
+                Connection::open_with_flags(path, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY)
-                rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
+            {
            ) {
                conns.push(conn);
            }
        }
@@ -209,7 +208,7 @@ impl VoiceConnectionPool {
    pub fn with_connections<R>(&self, f: impl FnOnce(&[Connection]) -> R) -> R {
        thread_local! {
-            static CONNS: RefCell<Option<(u64, Vec<Connection>)>> = RefCell::new(None);
+            static CONNS: RefCell<Option<(u64, Vec<Connection>)>> = const { RefCell::new(None) };
        }
        CONNS.with(|cell| {
            let mut borrow = cell.borrow_mut();
@@ -242,16 +241,12 @@ impl HardlinkConnectionPool {
    }
    fn open(&self) -> Option<Connection> {
-        Connection::open_with_flags(
+        Connection::open_with_flags(&self.db_path, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY).ok()
            &self.db_path,
            rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY,
        )
        .ok()
    }
    pub fn with_connection<R>(&self, f: impl FnOnce(&Connection) -> R) -> Option<R> {
        thread_local! {
-            static CONN: RefCell<Option<(u64, Connection)>> = RefCell::new(None);
+            static CONN: RefCell<Option<(u64, Connection)>> = const { RefCell::new(None) };
        }
        CONN.with(|cell| {
            let mut borrow = cell.borrow_mut();
@@ -299,6 +294,7 @@ pub struct DupMap {
 // ---------------------------------------------------------------------------
 /// Build shared context from account/session info (pre-compute stage).
 #[allow(clippy::too_many_arguments)]
 pub fn build_shared_context(
    attach_dir: PathBuf,
    media_dir: PathBuf,
@@ -432,12 +428,7 @@ pub fn dedup(tasks: Vec<MediaTask>) -> (Vec<MediaTask>, DupMap) {
        unique.push(task);
    }
-    (
+    (unique, DupMap { duplicates })
        unique,
        DupMap {
            duplicates,
        },
    )
 }
 /// Default rayon thread pool size: min(num_cpus, 4).
@@ -469,7 +460,12 @@ pub fn resolve_parallel(
        batches.entry(task.kind()).or_default().push(task);
    }
-    let order = [TaskKind::Image, TaskKind::Voice, TaskKind::Video, TaskKind::File];
+    let order = [
        TaskKind::Image,
        TaskKind::Voice,
        TaskKind::Video,
        TaskKind::File,
    ];
    let mut all_results = Vec::new();
    let mut all_errors = ErrorSummary::default();
@@ -531,7 +527,10 @@ pub fn resolve_parallel(
 fn resolve_one(task: &MediaTask, ctx: &SharedContext) -> ResolvedAsset {
    match task {
        MediaTask::Image { md5, msg_index } => resolve_image(md5, *msg_index, ctx),
-        MediaTask::Voice { server_id, msg_index } => resolve_voice(*server_id, *msg_index, ctx),
+        MediaTask::Voice {
            server_id,
            msg_index,
        } => resolve_voice(*server_id, *msg_index, ctx),
        MediaTask::Video {
            md5,
            create_time,
@@ -668,7 +667,8 @@ fn resolve_voice(server_id: i64, msg_index: usize, ctx: &SharedContext) -> Resol
    let blob = ctx.voice_pool.with_connections(|conns| {
        for conn in conns {
-            if let Ok(b) = wx_media::extract_voice_with_conn_hint(conn, &svr_id, chat_name_id_hint) {
+            if let Ok(b) = wx_media::extract_voice_with_conn_hint(conn, &svr_id, chat_name_id_hint)
            {
                return Some(b);
            }
        }
@@ -750,9 +750,9 @@ fn resolve_video(
    ctx: &SharedContext,
 ) -> ResolvedAsset {
    // Try hardlink DB first
-    let hardlink_result = ctx.hardlink_pool.with_connection(|conn| {
+    let hardlink_result = ctx
-        wx_media::query_hardlink_with_conn(conn, "video", md5)
+        .hardlink_pool
-    });
+        .with_connection(|conn| wx_media::query_hardlink_with_conn(conn, "video", md5));
    let entries = match hardlink_result {
        Some(Ok(e)) => Some(e),
@@ -860,9 +860,9 @@ fn resolve_file(
    ctx: &SharedContext,
 ) -> ResolvedAsset {
    // Try hardlink DB first
-    let hardlink_result = ctx.hardlink_pool.with_connection(|conn| {
+    let hardlink_result = ctx
-        wx_media::query_hardlink_with_conn(conn, "file", md5)
+        .hardlink_pool
-    });
+        .with_connection(|conn| wx_media::query_hardlink_with_conn(conn, "file", md5));
    let entries = match hardlink_result {
        Some(Ok(e)) => Some(e),
@@ -889,7 +889,7 @@ fn resolve_file(
                let filename = format!("{}_{}", md5, entry.file_name);
                if ctx.write_gate.claim(&filename) {
                    let out_path = ctx.output_media_dir.join(&filename);
-                    if let Err(e) = std::fs::copy(&source, &out_path) {
+                    if let Err(e) = std::fs::copy(source, &out_path) {
                        return ResolvedAsset {
                            msg_index,
                            asset: None,
@@ -973,23 +973,19 @@ pub fn collect(
    let mut errors = ErrorSummary::default();
    // Build index from results by msg_index
-    let mut by_index: HashMap<usize, (Option<MediaAsset>, Vec<TaskTag>, Option<ExportError>)> =
+    let mut by_index: HashMap<usize, (Option<MediaAsset>, Vec<TaskTag>)> = HashMap::new();
        HashMap::new();
    for r in results {
        if let Some(e) = r.error {
            errors.errors.push(e);
        }
-        by_index.insert(
+        by_index.insert(r.msg_index, (r.asset, r.tags));
            r.msg_index,
            (r.asset, r.tags, None),
        );
    }
    // Place canonical results — count tags always, copy asset only when present.
    // Matches old MediaBridge: SkippedVideo/SkippedFile stats counted unconditionally;
    // image stats (ThumbnailImage, WxgfTranscoded, WxgfFallback) also counted
    // because canonical always does the full resolve.
-    for (msg_idx, (asset, tags, _)) in &by_index {
+    for (msg_idx, (asset, tags)) in &by_index {
        apply_tags(&mut stats, tags);
        if let Some(a) = asset {
            media_map[*msg_idx].push(a.clone());
@@ -1003,8 +999,12 @@ pub fn collect(
    // This two-step approach matches old MediaBridge behavior where skipped/fallback
    // stats were counted regardless of dedup, but image stats only counted once.
    for (dup_msg_idx, canonical_msg_idx) in &dup_map.duplicates {
-        if let Some((asset, tags, _)) = by_index.get(canonical_msg_idx) {
+        if let Some((asset, tags)) = by_index.get(canonical_msg_idx) {
-            let dup_tags: Vec<TaskTag> = tags.iter().copied().filter(|t| t.counts_on_duplicate()).collect();
+            let dup_tags: Vec<TaskTag> = tags
                .iter()
                .copied()
                .filter(|t| t.counts_on_duplicate())
                .collect();
            apply_tags(&mut stats, &dup_tags);
            if let Some(a) = asset {
                media_map[*dup_msg_idx].push(a.clone());
@@ -1416,7 +1416,10 @@ mod tests {
        // Second task: Voice
        assert!(matches!(
            &tasks[1],
-            MediaTask::Voice { server_id: 2, msg_index: 1 }
+            MediaTask::Voice {
                server_id: 2,
                msg_index: 1
            }
        ));
    }
@@ -1446,7 +1449,11 @@ mod tests {
        let encrypted: Vec<u8> = wxgf.iter().map(|b| b ^ xor_key).collect();
        let username_hash = format!("{:x}", wx_media::md5_hash(talker.as_bytes()));
-        let img_dir = root.join("attach").join(&username_hash).join("2026-03").join("Img");
+        let img_dir = root
            .join("attach")
            .join(&username_hash)
            .join("2026-03")
            .join("Img");
        std::fs::create_dir_all(&img_dir).unwrap();
        std::fs::write(img_dir.join(format!("{md5}.dat")), &encrypted).unwrap();
@@ -1572,10 +1579,7 @@ mod tests {
        let silk = sample_silk();
        create_voice_media_db(
            &media_dir.join("media_0.db"),
-            &[
+            &[(55, 1000, 1, 101, &silk), (55, 1001, 2, 102, &silk)],
                (55, 1000, 1, 101, &silk),
                (55, 1001, 2, 102, &silk),
            ],
        );
        let ctx = Arc::new(build_shared_context(
@@ -64,10 +64,7 @@ pub async fn cmd_key_extract(timeout_secs: u64) -> Result<(), Box<dyn std::error
        Some(matched.base_wxid.clone()),
    );
    store.save_default()?;
-    eprintln!(
+    eprintln!("Key saved to {:?}", wx_keychain::KeyStore::default_path()?);
        "Key saved to {:?}",
        wx_keychain::KeyStore::default_path()?
    );
    Ok(())
 }
@@ -102,8 +99,7 @@ pub fn cmd_key_scan() -> Result<(), Box<dyn std::error::Error>> {
    // Scan process memory.
    eprintln!("Scanning WeChat process memory...");
-    let results =
+    let results = wx_keychain::capture_key_mach(pid, &accounts, &wx_decrypt::MACOS_4_1_7_31)?;
        wx_keychain::capture_key_mach(pid, &accounts, &wx_decrypt::MACOS_4_1_7_31)?;
    // Count total pairs across all results
    let total_pairs: usize = results
@@ -126,11 +122,8 @@ pub fn cmd_key_scan() -> Result<(), Box<dyn std::error::Error>> {
    for r in &results {
        let matched = &r.matched_account;
-        let nickname = wx_keychain::resolve_nickname(
+        let nickname =
-            &matched.data_dir,
+            wx_keychain::resolve_nickname(&matched.data_dir, &r.key_material, &matched.base_wxid)
            &r.key_material,
            &matched.base_wxid,
        )
                .unwrap_or_else(|e| {
                    eprintln!(
                        "  Warning: nickname resolution failed for {}: {e}",
@@ -173,10 +166,7 @@ pub fn cmd_key_scan() -> Result<(), Box<dyn std::error::Error>> {
    }
    store.save_default()?;
-    eprintln!(
+    eprintln!("Keys saved to {:?}", wx_keychain::KeyStore::default_path()?);
        "Keys saved to {:?}",
        wx_keychain::KeyStore::default_path()?
    );
    Ok(())
 }
@@ -39,7 +39,13 @@ fn print_paths_table(summary: &PathsSummary) {
        } else {
            "[missing]"
        };
-        println!("{:<width$}  {:<60}  {}", label, display, status, width = max_label);
+        println!(
            "{:<width$}  {:<60}  {}",
            label,
            display,
            status,
            width = max_label
        );
    }
 }
@@ -298,9 +298,7 @@ fn load_local_query(
    // When limit pushdown was used (non-anchor, non-all), total_rows only reflects the
    // scanned window. Use a lightweight COUNT(*) query to get the actual DB-level total.
    if !has_anchor && !all {
-        let mt_filter = msg_type
+        let mt_filter = msg_type.as_ref().and_then(|s| wx_db::parse_msg_type(s));
            .as_ref()
            .and_then(|s| wx_db::parse_msg_type(s));
        let db_total = db.count_messages(
            &talker,
            since.unwrap_or(0),
@@ -5,7 +5,9 @@ use wx_context::{register_mm_fts_tokenizer, AccountContext, ContactResolver, Res
 use super::thin_client::{ThinClient, ThinClientCliArgs, ThinClientOptions};
 use crate::output::{JsonEnvelope, PagingMeta, StatsMeta};
 use crate::schema::{enrich_message_as_hit, enrich_native_fts_hit, SearchHit};
-use crate::util::{effective_limit_all, open_db_all, print_cache_stats, print_detection_note, try_remote_or_local};
+use crate::util::{
    effective_limit_all, open_db_all, print_cache_stats, print_detection_note, try_remote_or_local,
 };
 use crate::OutputFormat;
 // Unused imports kept for Task 6 cleanup reference:
@@ -67,12 +69,8 @@ fn load_local_search(
            Ok(conn)
        }) {
            Ok(conn) => {
-                match wx_db::native_fts::search_message_fts(
+                match wx_db::native_fts::search_message_fts(&conn, keyword, effective_limit, offset)
-                    &conn,
+                {
                    keyword,
                    effective_limit,
                    offset,
                ) {
                    Ok(result) => {
                        return native_fts_envelope(
                            result,
@@ -23,10 +23,7 @@ struct BridgeState {
    startup_watermark: i64,
 }
-fn should_broadcast_talker(
+fn should_broadcast_talker(visibility: &wx_context::VisibilityIndex, talker: &str) -> bool {
    visibility: &wx_context::VisibilityIndex,
    talker: &str,
 ) -> bool {
    !visibility.is_hidden_talker(talker)
 }
@@ -407,25 +404,40 @@ mod tests {
    #[test]
    fn enrich_messages_filters_hidden_sender_in_group() {
-        let visibility = VisibilityIndex::build(
+        let visibility =
-            &["wxid_spam".to_string()],
+            VisibilityIndex::build(&["wxid_spam".to_string()], &[], &ContactResolver::empty());
            &[],
            &ContactResolver::empty(),
        );
        let msgs = vec![
            wx_db::Message {
-                sort_seq: 1, server_id: 1, msg_type: 1, sub_type: 0,
+                sort_seq: 1,
-                sender: "wxid_spam".to_string(), talker: "group@chatroom".to_string(),
+                server_id: 1,
-                create_time: 100, content: wx_db::MessageContent::Text("spam".into()), status: 0,
+                msg_type: 1,
                sub_type: 0,
                sender: "wxid_spam".to_string(),
                talker: "group@chatroom".to_string(),
                create_time: 100,
                content: wx_db::MessageContent::Text("spam".into()),
                status: 0,
            },
            wx_db::Message {
-                sort_seq: 2, server_id: 2, msg_type: 1, sub_type: 0,
+                sort_seq: 2,
-                sender: "wxid_normal".to_string(), talker: "group@chatroom".to_string(),
+                server_id: 2,
-                create_time: 101, content: wx_db::MessageContent::Text("hello".into()), status: 0,
+                msg_type: 1,
                sub_type: 0,
                sender: "wxid_normal".to_string(),
                talker: "group@chatroom".to_string(),
                create_time: 101,
                content: wx_db::MessageContent::Text("hello".into()),
                status: 0,
            },
        ];
-        let result = enrich_messages(msgs, "wxid_me", &ContactResolver::empty(), "group@chatroom", &visibility);
+        let result = enrich_messages(
            msgs,
            "wxid_me",
            &ContactResolver::empty(),
            "group@chatroom",
            &visibility,
        );
        assert_eq!(result.len(), 1, "hidden sender message should be filtered");
        assert_eq!(result[0].message.sender, "wxid_normal");
    }
@@ -433,11 +445,8 @@ mod tests {
    #[test]
    fn session_sender_redaction_in_bridge() {
        use crate::schema::project_session_sender;
-        let visibility = VisibilityIndex::build(
+        let visibility =
-            &["wxid_spam".to_string()],
+            VisibilityIndex::build(&["wxid_spam".to_string()], &[], &ContactResolver::empty());
            &[],
            &ContactResolver::empty(),
        );
        let ev = wx_monitor::SessionEvent {
            username: "group@chatroom".to_string(),
            sort_timestamp: 1,
@@ -448,7 +457,8 @@ mod tests {
            last_msg_sender: Some("wxid_spam".to_string()),
            last_sender_display_name: Some("Spammer".to_string()),
        };
-        let mut enriched = crate::schema::enrich_session_event(ev, "wxid_me", &ContactResolver::empty());
+        let mut enriched =
            crate::schema::enrich_session_event(ev, "wxid_me", &ContactResolver::empty());
        project_session_sender(&mut enriched, &visibility);
        assert_eq!(enriched.session.summary, "[消息已隐藏]");
@@ -47,6 +47,7 @@ mod tests {
                    last_sender_display_name: None,
                },
                display_name: "wxid_friend".to_string(),
                avatar_url: None,
                direction: None,
                detected_at: None,
            },
@@ -70,6 +71,7 @@ mod tests {
                    last_sender_display_name: None,
                },
                display_name: "wxid_friend".to_string(),
                avatar_url: None,
                direction: None,
                detected_at: Some(2),
            },
@@ -8,20 +8,18 @@ use axum::http::StatusCode;
 use axum::response::sse::{Event, KeepAlive, Sse};
 use axum::response::IntoResponse;
 use axum::Json;
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 use serde_json::json;
 use tokio_stream::wrappers::BroadcastStream;
 use tokio_stream::StreamExt;
 use crate::cmd::server::types::{RuntimeAccountState, ServerHealthPayload};
-use crate::output::JsonEnvelope;
+use crate::output::{JsonEnvelope, PagingMeta, StatsMeta};
 use crate::schema::{
    enrich_message, enrich_message_as_hit, enrich_native_fts_hit, enrich_session,
    project_message_items,
 };
-use crate::visibility_projection::{
+use crate::visibility_projection::{project_contacts_envelope, project_sessions_envelope_enriched};
    project_contacts_envelope, project_sessions_envelope_enriched,
 };
 use super::error::ServeError;
 use super::event::SseEvent;
@@ -92,6 +90,68 @@ mod tests {
            ]))
        );
    }
    fn timeline_params(since: Option<i64>, until: Option<i64>) -> TimelineParams {
        TimelineParams {
            since,
            until,
            limit: 20,
            offset: 0,
            msg_type: None,
            order: "asc".to_string(),
            show_hidden: None,
        }
    }
    #[test]
    fn timeline_requires_a_bounded_time_range() {
        assert!(timeline_bounds(&timeline_params(None, Some(20))).is_err());
        assert!(timeline_bounds(&timeline_params(Some(10), None)).is_err());
        assert!(timeline_bounds(&timeline_params(Some(20), Some(10))).is_err());
        match timeline_bounds(&timeline_params(Some(10), Some(20))) {
            Ok(bounds) => assert_eq!(bounds, (10, 20)),
            Err(_) => panic!("valid timeline bounds should be accepted"),
        }
    }
    fn timeline_message(create_time: i64) -> TimelineMessage {
        TimelineMessage {
            sort_seq: create_time,
            server_id: create_time,
            msg_type: 1,
            sub_type: 0,
            sender: "wxid_other".to_string(),
            talker: "wxid_other".to_string(),
            talker_display_name: "Other".to_string(),
            create_time,
            status: 0,
            sender_display_name: "Other".to_string(),
            direction: wx_context::Direction::detect("wxid_other", "wxid_me"),
            snippet: create_time.to_string(),
        }
    }
    #[test]
    fn timeline_candidate_trimming_keeps_requested_edge() {
        let source = [5, 1, 3, 2, 4]
            .into_iter()
            .map(timeline_message)
            .collect::<Vec<_>>();
        let mut asc = source.clone();
        trim_timeline_candidates(&mut asc, wx_db::SortOrder::Asc, 2, false);
        assert_eq!(
            asc.iter().map(|item| item.create_time).collect::<Vec<_>>(),
            vec![1, 2]
        );
        let mut desc = source;
        trim_timeline_candidates(&mut desc, wx_db::SortOrder::Desc, 2, false);
        assert_eq!(
            desc.iter().map(|item| item.create_time).collect::<Vec<_>>(),
            vec![5, 4]
        );
    }
 }
 #[derive(Deserialize)]
@@ -221,8 +281,7 @@ pub async fn handler_contacts(
            .query_contacts(&query)
            .map_err(|e| ServeError::Db(e.to_string()))?;
-        let envelope =
+        let envelope = JsonEnvelope::from_query_result(result, wx_db::MAX_QUERY_LIMIT, 0, |c| c);
            JsonEnvelope::from_query_result(result, wx_db::MAX_QUERY_LIMIT, 0, |c| c);
        Ok::<_, ServeError>(project_contacts_envelope(
            envelope.items,
            &visibility,
@@ -379,9 +438,7 @@ pub async fn handler_messages(
        // When limit pushdown was used (non-anchor), total_rows only reflects the
        // scanned window. Use a lightweight COUNT(*) query for accurate DB-level total.
        if !has_anchor {
-            let mt_filter = msg_type
+            let mt_filter = msg_type.as_ref().and_then(|s| wx_db::parse_msg_type(s));
                .as_ref()
                .and_then(|s| wx_db::parse_msg_type(s));
            let db_total = guard.count_messages(
                &talker,
                since.unwrap_or(0),
@@ -405,6 +462,219 @@ pub async fn handler_messages(
    Ok(Json(result))
 }
 // ---------------------------------------------------------------------------
 // Timeline — messages across every conversation in one bounded query
 // ---------------------------------------------------------------------------
 #[derive(Deserialize)]
 pub struct TimelineParams {
    pub since: Option<i64>,
    pub until: Option<i64>,
    #[serde(default = "default_limit")]
    pub limit: usize,
    #[serde(default)]
    pub offset: usize,
    #[serde(rename = "type")]
    pub msg_type: Option<String>,
    #[serde(default = "default_order")]
    pub order: String,
    pub show_hidden: Option<String>,
 }
 #[derive(Clone, Debug, Serialize)]
 pub struct TimelineMessage {
    pub sort_seq: i64,
    pub server_id: i64,
    pub msg_type: u32,
    pub sub_type: u32,
    pub sender: String,
    pub talker: String,
    pub talker_display_name: String,
    pub create_time: i64,
    pub status: i32,
    pub sender_display_name: String,
    pub direction: wx_context::Direction,
    pub snippet: String,
 }
 impl TimelineMessage {
    fn from_enriched(message: crate::schema::EnrichedMessage, talker_display_name: String) -> Self {
        let crate::schema::EnrichedMessage {
            message,
            sender_display_name,
            direction,
            snippet,
        } = message;
        Self {
            sort_seq: message.sort_seq,
            server_id: message.server_id,
            msg_type: message.msg_type,
            sub_type: message.sub_type,
            sender: message.sender,
            talker: message.talker,
            talker_display_name,
            create_time: message.create_time,
            status: message.status,
            sender_display_name,
            direction,
            snippet,
        }
    }
 }
 fn sort_timeline_messages(messages: &mut [TimelineMessage], order: wx_db::SortOrder) {
    match order {
        wx_db::SortOrder::Asc => {
            messages.sort_unstable_by_key(|item| (item.create_time, item.sort_seq, item.server_id))
        }
        wx_db::SortOrder::Desc => messages.sort_unstable_by(|a, b| {
            (b.create_time, b.sort_seq, b.server_id).cmp(&(a.create_time, a.sort_seq, a.server_id))
        }),
    }
 }
 fn trim_timeline_candidates(
    messages: &mut Vec<TimelineMessage>,
    order: wx_db::SortOrder,
    keep_limit: usize,
    force: bool,
 ) {
    if force || messages.len() > keep_limit.saturating_mul(2) {
        sort_timeline_messages(messages, order);
        messages.truncate(keep_limit);
    }
 }
 fn timeline_bounds(params: &TimelineParams) -> Result<(i64, i64), ServeError> {
    let since = params
        .since
        .ok_or_else(|| ServeError::InvalidParam("missing required parameter: since".into()))?;
    let until = params
        .until
        .ok_or_else(|| ServeError::InvalidParam("missing required parameter: until".into()))?;
    if since > until {
        return Err(ServeError::InvalidParam(
            "since must be less than or equal to until".into(),
        ));
    }
    Ok((since, until))
 }
 /// Read a time-bounded timeline across all conversations in one server request.
 ///
 /// This is intentionally implemented inside the warm server process. Agent memory jobs and
 /// archive tools no longer need to launch one CLI process and make one HTTP round-trip for every
 /// active conversation.
 pub async fn handler_timeline(
    State(state): State<Arc<AppState>>,
    Query(params): Query<TimelineParams>,
 ) -> Result<impl IntoResponse, ServeError> {
    let (since, until) = timeline_bounds(&params)?;
    let db = Arc::clone(&state.db);
    let resolver = Arc::clone(&state.resolver);
    let visibility = Arc::clone(&state.visibility);
    let self_wxid = state.self_wxid.clone();
    let limit = wx_db::effective_limit(params.limit);
    let offset = params.offset;
    let keep_limit = offset.saturating_add(limit);
    let order = parse_order(&params.order);
    let msg_type = params.msg_type.as_deref().and_then(wx_db::parse_msg_type);
    let show_hidden = matches!(params.show_hidden.as_deref(), Some("1") | Some("true"));
    let result = tokio::task::spawn_blocking(move || {
        let guard = db.lock().map_err(|e| ServeError::Internal(e.to_string()))?;
        let sessions = guard
            .query_sessions(
                &wx_db::SessionQuery::new()
                    .limit(wx_db::MAX_QUERY_LIMIT)
                    .offset(0),
            )
            .map_err(|e| ServeError::Db(e.to_string()))?;
        let mut messages = Vec::new();
        let mut total = 0usize;
        let mut scanned = 0usize;
        let mut skipped = sessions.stats.skipped;
        let mut shard_warnings = Vec::new();
        for session in sessions.items {
            let talker = session.username;
            if !show_hidden && visibility.is_hidden_talker(&talker) {
                continue;
            }
            let talker_display_name = resolver.display_with_id(&talker);
            let mut talker_offset = 0usize;
            loop {
                let mut query = wx_db::MessageQuery::for_talker(&talker)
                    .since(since)
                    .until(until)
                    .limit(wx_db::MAX_QUERY_LIMIT)
                    .offset(talker_offset)
                    .order(order);
                if let Some(mt) = msg_type {
                    query = query.msg_type(mt);
                }
                let page = guard
                    .query_messages(&query)
                    .map_err(|e| ServeError::Db(e.to_string()))?;
                let returned = page.items.len();
                scanned = scanned.saturating_add(page.stats.total_rows);
                skipped = skipped.saturating_add(page.stats.skipped);
                shard_warnings.extend(page.shard_warnings);
                let enriched = page
                    .items
                    .into_iter()
                    .map(|message| enrich_message(message, &self_wxid, &resolver))
                    .collect();
                let projected = project_message_items(enriched, &talker, &visibility, show_hidden);
                total = total.saturating_add(projected.len());
                messages.extend(projected.into_iter().map(|message| {
                    TimelineMessage::from_enriched(message, talker_display_name.clone())
                }));
                // Retain only the global candidates needed for this page. The common first-page
                // path now stays close to 2×limit instead of holding the entire history in memory.
                trim_timeline_candidates(&mut messages, order, keep_limit, false);
                if returned < wx_db::MAX_QUERY_LIMIT {
                    break;
                }
                talker_offset = talker_offset.saturating_add(returned);
            }
        }
        trim_timeline_candidates(&mut messages, order, keep_limit, true);
        let start = offset.min(total);
        let items: Vec<_> = messages.into_iter().skip(start).take(limit).collect();
        let returned = items.len();
        Ok::<_, ServeError>(JsonEnvelope {
            items,
            paging: PagingMeta {
                limit,
                offset,
                returned,
                has_more: start + returned < total,
                total,
            },
            stats: StatsMeta {
                scanned,
                skipped,
                elapsed_ms: None,
                shard_warnings,
            },
        })
    })
    .await
    .map_err(|e| ServeError::Internal(e.to_string()))??;
    Ok(Json(result))
 }
 // ---------------------------------------------------------------------------
 // Search
 // ---------------------------------------------------------------------------
@@ -447,7 +717,9 @@ pub async fn handler_search(
                .map_err(|e: std::sync::PoisonError<_>| ServeError::Internal(e.to_string()))?;
            // Lazy-init name2id cache with proper error propagation.
            let name2id = {
-                let mut cache_guard = state_arc.name2id_cache.lock()
+                let mut cache_guard = state_arc
                    .name2id_cache
                    .lock()
                    .map_err(|e: std::sync::PoisonError<_>| ServeError::Internal(e.to_string()))?;
                match cache_guard.as_ref() {
                    Some(map) => map.clone(),
@@ -524,9 +796,7 @@ pub async fn handler_search(
            let first_attempt = guard
                .pool()
                .and_then(|pool| pool.fts_conn())
-                .map(|fts_conn| {
+                .map(|fts_conn| wx_db::native_fts::search_message_fts(fts_conn, &q, limit, offset));
                    wx_db::native_fts::search_message_fts(fts_conn, &q, limit, offset)
                });
            match first_attempt {
                Some(Ok(r)) => Some(r),
@@ -539,8 +809,8 @@ pub async fn handler_search(
                            guard
                                .pool()
                                .and_then(|pool| pool.fts_conn())
-                                .and_then(
+                                .and_then(|fts_conn| {
-                                    |fts_conn| match wx_db::native_fts::search_message_fts(
+                                    match wx_db::native_fts::search_message_fts(
                                        fts_conn, &q, limit, offset,
                                    ) {
                                        Ok(r) => Some(r),
@@ -551,8 +821,8 @@ pub async fn handler_search(
                                            );
                                            None
                                        }
-                                    },
+                                    }
-                                )
+                                })
                        }
                        Err(reopen_err) => {
                            eprintln!(
@@ -8,13 +8,11 @@ use axum::http::HeaderValue;
 use axum::response::{IntoResponse, Response};
 use tower::ServiceExt;
 use tower_http::services::ServeFile;
-use wx_db::{
+use wx_db::{open_readonly_connection, Message, MessageContent, MessageQuery, SortOrder, WechatDb};
    open_readonly_connection, Message, MessageContent, MessageQuery, SortOrder, WechatDb,
 };
 use crate::util::{format_month, sanitize_filename};
 use super::error::ServeError;
 use super::state::{AppState, CachedVoicePayload};
 use crate::util::{format_month, sanitize_filename};
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub enum MediaFormat {
@@ -44,6 +42,7 @@ enum MediaPayload {
    InlineBytes {
        bytes: Vec<u8>,
        content_type: &'static str,
        quality: Option<&'static str>,
    },
    ServePath {
        path: PathBuf,
@@ -58,11 +57,17 @@ impl MediaPayload {
            Self::InlineBytes {
                bytes,
                content_type,
                quality,
            } => {
                let mut response = bytes.into_response();
                response
                    .headers_mut()
                    .insert(CONTENT_TYPE, HeaderValue::from_static(content_type));
                if let Some(quality) = quality {
                    response
                        .headers_mut()
                        .insert("x-wechat-media-quality", HeaderValue::from_static(quality));
                }
                Ok(response)
            }
            Self::ServePath {
@@ -147,8 +152,9 @@ async fn resolve_media(
            ))),
            MessageContent::Voice => {
                let db_paths = {
-                    let mut cache_guard = state_for_cache.media_db_paths.lock()
+                    let mut cache_guard = state_for_cache.media_db_paths.lock().map_err(
-                        .map_err(|e: std::sync::PoisonError<_>| ServeError::Internal(e.to_string()))?;
+                        |e: std::sync::PoisonError<_>| ServeError::Internal(e.to_string()),
                    )?;
                    match cache_guard.as_ref() {
                        Some(paths) => paths.clone(),
                        None => {
@@ -243,6 +249,14 @@ fn resolve_image(
    let dat_path = lookup.recommended.ok_or_else(|| {
        ServeError::NotFound(format!("no candidate image file found for md5={md5}"))
    })?;
    let quality = if dat_path
        .file_name()
        .is_some_and(|name| name.to_string_lossy().ends_with("_t.dat"))
    {
        "thumbnail"
    } else {
        "full"
    };
    let data = std::fs::read(&dat_path)
        .map_err(|e| ServeError::Internal(format!("failed to read {}: {e}", dat_path.display())))?;
    let decoded = wx_media::decrypt_dat(&data, &dat_decrypt)
@@ -260,12 +274,14 @@ fn resolve_image(
        return Ok(MediaPayload::InlineBytes {
            bytes: transcoded.data,
            content_type: image_content_type(transcoded.ext),
            quality: Some(quality),
        });
    }
    Ok(MediaPayload::InlineBytes {
        bytes: decoded.data,
        content_type: image_content_type(&decoded.ext),
        quality: Some(quality),
    })
 }
@@ -289,6 +305,7 @@ fn resolve_voice(
            return Ok(MediaPayload::InlineBytes {
                bytes: cached.bytes.clone(),
                content_type: cached.content_type,
                quality: None,
            });
        }
    }
@@ -297,7 +314,7 @@ fn resolve_voice(
    let mut first_db_error: Option<String> = None;
    for db_path in db_paths {
-        let conn = match open_readonly_connection(&db_path, raw_key.as_ref()) {
+        let conn = match open_readonly_connection(db_path, raw_key.as_ref()) {
            Ok(conn) => conn,
            Err(err) => {
                if first_db_error.is_none() {
@@ -332,6 +349,7 @@ fn resolve_voice(
                return Ok(MediaPayload::InlineBytes {
                    bytes: result.data,
                    content_type: result.mime,
                    quality: None,
                });
            }
            Err(wx_media::MediaError::LookupMiss(_))
@@ -280,8 +280,12 @@ pub async fn cmd_serve(
        hardlink_db_conn,
        raw_key: acct.raw_key,
        dat_decrypt,
-        voice_cache: Arc::new(std::sync::Mutex::new(LruCache::new(NonZeroUsize::new(256).unwrap()))),
+        voice_cache: Arc::new(std::sync::Mutex::new(LruCache::new(
-        image_xor_cache: Arc::new(std::sync::Mutex::new(LruCache::new(NonZeroUsize::new(1024).unwrap()))),
+            NonZeroUsize::new(256).unwrap(),
        ))),
        image_xor_cache: Arc::new(std::sync::Mutex::new(LruCache::new(
            NonZeroUsize::new(1024).unwrap(),
        ))),
        name2id_cache: Arc::new(std::sync::Mutex::new(None)),
        media_db_paths: Arc::new(std::sync::Mutex::new(None)),
    });
@@ -313,6 +317,7 @@ pub async fn cmd_serve(
    eprintln!("    GET /api/v1/sessions");
    eprintln!("    GET /api/v1/contacts");
    eprintln!("    GET /api/v1/messages?contact=<name_or_wxid>");
    eprintln!("    GET /api/v1/timeline?since=<unix>&until=<unix>");
    eprintln!("    GET /api/v1/media?server_id=<id>&talker=<wxid>[&format=ogg|mp3]");
    eprintln!("    GET /api/v1/search?q=<keyword>");
    eprintln!("  Auth: {auth_status}");
@@ -11,6 +11,8 @@ use wx_context::{
 };
 use wx_db::WechatDb;
 type Name2IdCache = Arc<std::sync::Mutex<Option<HashMap<i64, String>>>>;
 /// Signal sent to the refresh task.
 pub enum RefreshTrigger {
    Refresh,
@@ -36,7 +38,7 @@ pub struct RefreshTask {
    /// Path to FTS DB for reopening.
    fts_path: Option<PathBuf>,
    /// Cache of name2id mapping — cleared when FTS is reopened.
-    name2id_cache: Option<Arc<std::sync::Mutex<Option<HashMap<i64, String>>>>>,
+    name2id_cache: Option<Name2IdCache>,
    /// Cache of media DB paths — cleared on every refresh.
    media_db_paths: Option<Arc<std::sync::Mutex<Option<Vec<PathBuf>>>>>,
    /// Cached hardlink.db connection — cleared on refresh so it is reopened lazily.
@@ -79,7 +81,7 @@ impl RefreshTask {
    /// Set the caches that should be invalidated on refresh.
    pub fn with_caches(
        mut self,
-        name2id_cache: Option<Arc<std::sync::Mutex<Option<HashMap<i64, String>>>>>,
+        name2id_cache: Option<Name2IdCache>,
        media_db_paths: Option<Arc<std::sync::Mutex<Option<Vec<PathBuf>>>>>,
        hardlink_db_conn: Option<Arc<std::sync::Mutex<Option<Connection>>>>,
    ) -> Self {
@@ -15,6 +15,7 @@ pub fn build_router(state: Arc<AppState>) -> Router {
        .route("/api/v1/sessions", get(handlers::handler_sessions))
        .route("/api/v1/contacts", get(handlers::handler_contacts))
        .route("/api/v1/messages", get(handlers::handler_messages))
        .route("/api/v1/timeline", get(handlers::handler_timeline))
        .route("/api/v1/media", get(handlers::handler_media))
        .route("/api/v1/search", get(handlers::handler_search))
        .route("/api/v1/events", get(handlers::handler_sse))
@@ -20,7 +20,9 @@ use crate::OutputFormat;
 const START_TIMEOUT: Duration = Duration::from_secs(10);
 const STOP_TIMEOUT: Duration = Duration::from_secs(5);
-fn resolve_app_paths(runtime_root: Option<PathBuf>) -> Result<AppPaths, Box<dyn std::error::Error>> {
+fn resolve_app_paths(
    runtime_root: Option<PathBuf>,
 ) -> Result<AppPaths, Box<dyn std::error::Error>> {
    match runtime_root {
        Some(root) => Ok(AppPaths::with_runtime_root(root)?),
        None => Ok(AppPaths::new()?),
@@ -120,9 +122,8 @@ pub async fn cmd_server_stop(args: ServerStopArgs) -> Result<(), Box<dyn std::er
 pub async fn cmd_server_restart(args: ServerRestartArgs) -> Result<(), Box<dyn std::error::Error>> {
    let ap = resolve_app_paths(args.runtime_root.clone())?;
-    let config = load_launch_config(&ap)?.ok_or(
+    let config = load_launch_config(&ap)?
-        "no persisted server launch configuration found; run `wx-cli server run` first",
+        .ok_or("no persisted server launch configuration found; run `wx-cli server run` first")?;
    )?;
    let stop_args = ServerStopArgs {
        runtime_root: args.runtime_root.clone(),
@@ -286,9 +287,7 @@ fn spawn_worker(
        command.arg("--runtime-root").arg(root);
    }
-    command
+    command.arg("--worker-id").arg(worker_id);
        .arg("--worker-id")
        .arg(worker_id);
    if let Some(key) = &config.key {
        command.arg("--key").arg(key);
@@ -6,7 +6,9 @@ use super::contacts::build_visibility;
 use super::thin_client::{ThinClientCliArgs, ThinClientOptions};
 use crate::output::JsonEnvelope;
 use crate::schema::{enrich_session, EnrichedSession};
-use crate::util::{effective_limit_all, open_db_core, print_cache_stats, print_detection_note, try_remote_or_local};
+use crate::util::{
    effective_limit_all, open_db_core, print_cache_stats, print_detection_note, try_remote_or_local,
 };
 use crate::visibility_projection::project_sessions_envelope_enriched;
 use crate::{OutputFormat, SortOrderArg};
@@ -65,6 +65,7 @@ fn format_watch_line(
 }
 #[cfg(test)]
 #[allow(clippy::items_after_test_module)]
 mod tests {
    use super::*;
@@ -197,15 +198,20 @@ mod tests {
    #[test]
    fn watch_text_hidden_sender_shows_placeholder() {
        use crate::schema::project_session_sender;
-        let visibility = VisibilityIndex::build(
+        let visibility =
-            &["wxid_spam".to_string()], &[], &ContactResolver::empty(),
+            VisibilityIndex::build(&["wxid_spam".to_string()], &[], &ContactResolver::empty());
        );
        let mut enriched = make_enriched_session("group@chatroom", "spam msg", Some("wxid_spam"));
        project_session_sender(&mut enriched, &visibility);
        let line = format_watch_line_from_enriched(&enriched, &ContactResolver::empty(), "wxid_me");
-        assert!(line.contains("[消息已隐藏]"), "should show placeholder: {line}");
+        assert!(
-        assert!(!line.contains("wxid_spam"), "should not leak sender wxid: {line}");
+            line.contains("[消息已隐藏]"),
            "should show placeholder: {line}"
        );
        assert!(
            !line.contains("wxid_spam"),
            "should not leak sender wxid: {line}"
        );
    }
    #[test]
@@ -281,6 +287,7 @@ fn should_emit_event(
    show_hidden || !visibility.is_hidden_talker(&event.username)
 }
 #[allow(clippy::too_many_arguments)]
 pub async fn cmd_watch(
    key_hex: Option<String>,
    data_dir: Option<PathBuf>,
@@ -17,6 +17,8 @@ pub struct EnrichedSession {
    pub session: Session,
    pub display_name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub avatar_url: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub direction: Option<Direction>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub detected_at: Option<i64>,
@@ -61,10 +63,12 @@ pub fn enrich_session(
    detected_at: Option<i64>,
 ) -> EnrichedSession {
    let display_name = resolver.display_with_id(&session.username);
    let avatar_url = resolver.avatar_url(&session.username).map(str::to_string);
    let direction = derive_session_direction(session.last_msg_sender.as_deref(), self_wxid);
    EnrichedSession {
        session,
        display_name,
        avatar_url,
        direction,
        detected_at,
    }
@@ -76,6 +80,7 @@ pub fn enrich_session_event(
    resolver: &ContactResolver,
 ) -> EnrichedSession {
    let display_name = resolver.display_with_id(&ev.username);
    let avatar_url = resolver.avatar_url(&ev.username).map(str::to_string);
    let direction = derive_session_direction(ev.last_msg_sender.as_deref(), self_wxid);
    let session = Session {
        username: ev.username,
@@ -88,6 +93,7 @@ pub fn enrich_session_event(
    EnrichedSession {
        session,
        display_name,
        avatar_url,
        direction,
        detected_at: Some(ev.detected_at),
    }
@@ -540,7 +546,11 @@ mod tests {
        }
    }
-    fn make_enriched(sender: &str, talker: &str, content: wx_db::MessageContent) -> EnrichedMessage {
+    fn make_enriched(
        sender: &str,
        talker: &str,
        content: wx_db::MessageContent,
    ) -> EnrichedMessage {
        let msg = make_message(sender, talker, content);
        let snippet = format_content(&msg);
        EnrichedMessage {
@@ -562,21 +572,33 @@ mod tests {
    #[test]
    fn project_message_item_non_group_does_not_filter() {
        let vis = vis_with_hidden_persons(&["wxid_spam"]);
-        let msg = make_enriched("wxid_spam", "wxid_spam", wx_db::MessageContent::Text("hi".into()));
+        let msg = make_enriched(
            "wxid_spam",
            "wxid_spam",
            wx_db::MessageContent::Text("hi".into()),
        );
        assert!(project_message_item(msg, "wxid_spam", &vis).is_some());
    }
    #[test]
    fn project_message_item_group_hidden_sender_filtered() {
        let vis = vis_with_hidden_persons(&["wxid_spam"]);
-        let msg = make_enriched("wxid_spam", "group@chatroom", wx_db::MessageContent::Text("spam".into()));
+        let msg = make_enriched(
            "wxid_spam",
            "group@chatroom",
            wx_db::MessageContent::Text("spam".into()),
        );
        assert!(project_message_item(msg, "group@chatroom", &vis).is_none());
    }
    #[test]
    fn project_message_item_group_visible_sender_kept() {
        let vis = vis_with_hidden_persons(&["wxid_spam"]);
-        let msg = make_enriched("wxid_normal", "group@chatroom", wx_db::MessageContent::Text("hi".into()));
+        let msg = make_enriched(
            "wxid_normal",
            "group@chatroom",
            wx_db::MessageContent::Text("hi".into()),
        );
        assert!(project_message_item(msg, "group@chatroom", &vis).is_some());
    }
@@ -679,8 +701,16 @@ mod tests {
    fn project_message_items_show_hidden_bypasses() {
        let vis = vis_with_hidden_persons(&["wxid_spam"]);
        let items = vec![
-            make_enriched("wxid_spam", "group@chatroom", wx_db::MessageContent::Text("spam".into())),
+            make_enriched(
-            make_enriched("wxid_normal", "group@chatroom", wx_db::MessageContent::Text("hi".into())),
+                "wxid_spam",
                "group@chatroom",
                wx_db::MessageContent::Text("spam".into()),
            ),
            make_enriched(
                "wxid_normal",
                "group@chatroom",
                wx_db::MessageContent::Text("hi".into()),
            ),
        ];
        let result = project_message_items(items, "group@chatroom", &vis, true);
        assert_eq!(result.len(), 2);
@@ -690,8 +720,16 @@ mod tests {
    fn project_message_items_filters_hidden_sender() {
        let vis = vis_with_hidden_persons(&["wxid_spam"]);
        let items = vec![
-            make_enriched("wxid_spam", "group@chatroom", wx_db::MessageContent::Text("spam".into())),
+            make_enriched(
-            make_enriched("wxid_normal", "group@chatroom", wx_db::MessageContent::Text("hi".into())),
+                "wxid_spam",
                "group@chatroom",
                wx_db::MessageContent::Text("spam".into()),
            ),
            make_enriched(
                "wxid_normal",
                "group@chatroom",
                wx_db::MessageContent::Text("hi".into()),
            ),
        ];
        let result = project_message_items(items, "group@chatroom", &vis, false);
        assert_eq!(result.len(), 1);
@@ -711,6 +749,7 @@ mod tests {
                last_sender_display_name: None,
            },
            display_name: "Spam".to_string(),
            avatar_url: None,
            direction: Some(Direction::Incoming),
            detected_at: None,
        };
@@ -732,6 +771,7 @@ mod tests {
                last_sender_display_name: Some("Spammer".to_string()),
            },
            display_name: "Group".to_string(),
            avatar_url: None,
            direction: Some(Direction::Incoming),
            detected_at: None,
        };
@@ -755,11 +795,15 @@ mod tests {
                last_sender_display_name: Some("Normal".to_string()),
            },
            display_name: "Group".to_string(),
            avatar_url: None,
            direction: Some(Direction::Incoming),
            detected_at: None,
        };
        project_session_sender(&mut session, &vis);
        assert_eq!(session.session.summary, "normal message");
-        assert_eq!(session.session.last_msg_sender.as_deref(), Some("wxid_normal"));
+        assert_eq!(
            session.session.last_msg_sender.as_deref(),
            Some("wxid_normal")
        );
    }
 }
@@ -3,6 +3,12 @@ use std::path::PathBuf;
 use crate::cmd::thin_client::{ThinClient, ThinClientError, ThinClientOptions};
 use wx_context::{AccountContext, DecryptRequest, DecryptStats, PersistentCache};
 type OpenDbAllResult = (
    wx_db::WechatDb,
    Option<PersistentCache>,
    Option<DecryptStats>,
 );
 /// Open a WechatDb: direct encrypted open if raw_key available, else decrypt+cache (core only).
 pub fn open_db_core(
    acct: &AccountContext,
@@ -27,14 +33,7 @@ pub fn open_db_core(
 pub fn open_db_all(
    acct: &AccountContext,
    progress: impl Fn(wx_context::DecryptProgress) + Send + Sync,
-) -> Result<
+) -> Result<OpenDbAllResult, Box<dyn std::error::Error>> {
    (
        wx_db::WechatDb,
        Option<PersistentCache>,
        Option<DecryptStats>,
    ),
    Box<dyn std::error::Error>,
 > {
    if acct.raw_key.is_some() {
        eprintln!("Direct encrypted open (SQLCipher)");
        let db = wx_context::open_encrypted_db(acct)?;
@@ -249,14 +248,8 @@ mod tests {
    #[test]
    fn effective_limit_all_true_returns_max() {
-        assert_eq!(
+        assert_eq!(effective_limit_all(true, 0), wx_db::MAX_QUERY_LIMIT);
-            effective_limit_all(true, 0),
+        assert_eq!(effective_limit_all(true, 50), wx_db::MAX_QUERY_LIMIT);
            wx_db::MAX_QUERY_LIMIT
        );
        assert_eq!(
            effective_limit_all(true, 50),
            wx_db::MAX_QUERY_LIMIT
        );
    }
    #[test]
@@ -95,9 +95,15 @@ fn ignore_tags_hide_matching_contact_at_both_talker_and_sender_level() {
            "json",
        ],
    );
-    let items = group_messages["items"].as_array().expect("query items array");
+    let items = group_messages["items"]
        .as_array()
        .expect("query items array");
    // The only group message is from wxid_hidden_tagged; it should be filtered out
-    assert_eq!(items.len(), 0, "tagged contact's group messages should be sender-level filtered: {group_messages}");
+    assert_eq!(
        items.len(),
        0,
        "tagged contact's group messages should be sender-level filtered: {group_messages}"
    );
    // Session should show placeholder for group where last sender is tagged
    let sessions = run_json(
@@ -112,9 +118,7 @@ fn ignore_tags_hide_matching_contact_at_both_talker_and_sender_level() {
            "json",
        ],
    );
-    let items = sessions["items"]
+    let items = sessions["items"].as_array().expect("sessions items array");
        .as_array()
        .expect("sessions items array");
    let group_session = items
        .iter()
        .find(|item| item["username"].as_str() == Some(TALKER_GROUP));
@@ -331,16 +335,8 @@ fn create_encrypted_contact_db(path: &Path, raw_key: &[u8; 32]) {
            )
            .expect("insert bob");
-            let tagged_extra = encode_extra_buffer_for_test(
+            let tagged_extra =
-                None,
+                encode_extra_buffer_for_test(None, None, None, None, None, None, None, Some("1"));
                None,
                None,
                None,
                None,
                None,
                None,
                Some("1"),
            );
            conn.execute(
                "INSERT INTO contact (username, nick_name, extra_buffer) VALUES (?1, ?2, ?3)",
                params![TALKER_TAGGED, "Sensitive Person", tagged_extra],
@@ -451,7 +447,10 @@ fn create_encrypted_message_db(path: &Path, raw_key: &[u8; 32]) {
            group = TABLE_GROUP,
        ),
        |conn| {
-            conn.execute("INSERT INTO Timestamp VALUES (?1)", params![1_700_000_000_i64])
+            conn.execute(
                "INSERT INTO Timestamp VALUES (?1)",
                params![1_700_000_000_i64],
            )
            .expect("insert timestamp");
            conn.execute(
                "INSERT INTO Name2Id VALUES (?1, ?2)",
@@ -729,7 +728,10 @@ fn create_sender_account(root: &Path) {
            group = TABLE_GROUP_SENDER,
        ),
        |conn| {
-            conn.execute("INSERT INTO Timestamp VALUES (?1)", params![1_700_000_000_i64])
+            conn.execute(
                "INSERT INTO Timestamp VALUES (?1)",
                params![1_700_000_000_i64],
            )
            .expect("insert timestamp");
            conn.execute(
                "INSERT INTO Name2Id VALUES (?1, ?2)",
@@ -754,8 +756,15 @@ fn create_sender_account(root: &Path) {
                    table = TABLE_ALICE
                ),
                params![
-                    100_i64, 3001_i64, 1_i64, 1_i64, 1_700_000_301_i64,
+                    100_i64,
-                    b"private hello" as &[u8], None::<Vec<u8>>, 0_i32, None::<i32>,
+                    3001_i64,
                    1_i64,
                    1_i64,
                    1_700_000_301_i64,
                    b"private hello" as &[u8],
                    None::<Vec<u8>>,
                    0_i32,
                    None::<i32>,
                ],
            )
            .expect("insert alice private message");
@@ -767,8 +776,15 @@ fn create_sender_account(root: &Path) {
                    table = TABLE_GROUP_SENDER
                ),
                params![
-                    200_i64, 4001_i64, 1_i64, 1_i64, 1_700_000_101_i64,
+                    200_i64,
-                    b"alice says hello in group" as &[u8], None::<Vec<u8>>, 0_i32, None::<i32>,
+                    4001_i64,
                    1_i64,
                    1_i64,
                    1_700_000_101_i64,
                    b"alice says hello in group" as &[u8],
                    None::<Vec<u8>>,
                    0_i32,
                    None::<i32>,
                ],
            )
            .expect("insert alice group message");
@@ -780,8 +796,15 @@ fn create_sender_account(root: &Path) {
                    table = TABLE_GROUP_SENDER
                ),
                params![
-                    210_i64, 4002_i64, 1_i64, 5_i64, 1_700_000_102_i64,
+                    210_i64,
-                    b"spam content" as &[u8], None::<Vec<u8>>, 0_i32, None::<i32>,
+                    4002_i64,
                    1_i64,
                    5_i64,
                    1_700_000_102_i64,
                    b"spam content" as &[u8],
                    None::<Vec<u8>>,
                    0_i32,
                    None::<i32>,
                ],
            )
            .expect("insert spam group message");
@@ -795,10 +818,15 @@ fn create_sender_account(root: &Path) {
                    table = TABLE_GROUP_SENDER
                ),
                params![
-                    220_i64, 4003_i64,
+                    220_i64,
                    4003_i64,
                    quote_local_type,
-                    1_i64, 1_700_000_103_i64,
+                    1_i64,
-                    quote_xml.as_bytes(), None::<Vec<u8>>, 0_i32, None::<i32>,
+                    1_700_000_103_i64,
                    quote_xml.as_bytes(),
                    None::<Vec<u8>>,
                    0_i32,
                    None::<i32>,
                ],
            )
            .expect("insert quote message");
@@ -814,22 +842,38 @@ fn sender_hiding_filters_hidden_sender_messages_in_group() {
    let result = run_json(
        fixture.path(),
        &[
-            "query", TALKER_GROUP,
+            "query",
-            "--data-dir", senders_dir.as_str(),
+            TALKER_GROUP,
-            "--key", TEST_KEY_HEX,
+            "--data-dir",
-            "--format", "json",
+            senders_dir.as_str(),
            "--key",
            TEST_KEY_HEX,
            "--format",
            "json",
        ],
    );
    let items = result["items"].as_array().expect("query items array");
    // spam message (server_id=4002) should be filtered out
-    let senders: Vec<&str> = items.iter().map(|i| i["sender"].as_str().unwrap()).collect();
+    let senders: Vec<&str> = items
-    assert!(!senders.contains(&TALKER_SPAM), "hidden sender message should be filtered: {result}");
+        .iter()
-    assert!(senders.contains(&TALKER_ALICE), "visible sender should remain: {result}");
+        .map(|i| i["sender"].as_str().unwrap())
        .collect();
    assert!(
        !senders.contains(&TALKER_SPAM),
        "hidden sender message should be filtered: {result}"
    );
    assert!(
        senders.contains(&TALKER_ALICE),
        "visible sender should remain: {result}"
    );
    // paging.total should NOT change (DB-level count)
    // paging.returned should reflect filtered items
-    assert_eq!(result["paging"]["returned"].as_u64().unwrap(), items.len() as u64);
+    assert_eq!(
        result["paging"]["returned"].as_u64().unwrap(),
        items.len() as u64
    );
 }
 #[test]
@@ -841,14 +885,22 @@ fn sender_hiding_does_not_affect_private_chat() {
    let result = run_json(
        fixture.path(),
        &[
-            "query", TALKER_ALICE,
+            "query",
-            "--data-dir", senders_dir.as_str(),
+            TALKER_ALICE,
-            "--key", TEST_KEY_HEX,
+            "--data-dir",
-            "--format", "json",
+            senders_dir.as_str(),
            "--key",
            TEST_KEY_HEX,
            "--format",
            "json",
        ],
    );
    let items = result["items"].as_array().expect("query items array");
-    assert_eq!(items.len(), 1, "private chat should not be filtered: {result}");
+    assert_eq!(
        items.len(),
        1,
        "private chat should not be filtered: {result}"
    );
 }
 #[test]
@@ -859,27 +911,51 @@ fn sender_hiding_redacts_quote_referring_hidden_sender() {
    let result = run_json(
        fixture.path(),
        &[
-            "query", TALKER_GROUP,
+            "query",
-            "--data-dir", senders_dir.as_str(),
+            TALKER_GROUP,
-            "--key", TEST_KEY_HEX,
+            "--data-dir",
-            "--format", "json",
+            senders_dir.as_str(),
            "--key",
            TEST_KEY_HEX,
            "--format",
            "json",
        ],
    );
    let items = result["items"].as_array().expect("query items array");
    // Find the quote message (server_id=4003)
    let quote = items.iter().find(|i| i["server_id"].as_i64() == Some(4003));
-    assert!(quote.is_some(), "quote message should be present (alice's reply): items={:?}", items.iter().map(|i| i["server_id"].as_i64()).collect::<Vec<_>>());
+    assert!(
        quote.is_some(),
        "quote message should be present (alice's reply): items={:?}",
        items
            .iter()
            .map(|i| i["server_id"].as_i64())
            .collect::<Vec<_>>()
    );
    let quote = quote.unwrap();
    // refer_sender and refer_content should be null (redacted)
    let q = &quote["content"]["Quote"];
-    assert!(q["refer_sender"].is_null(), "refer_sender should be redacted: {quote}");
+    assert!(
-    assert!(q["refer_content"].is_null(), "refer_content should be redacted: {quote}");
+        q["refer_sender"].is_null(),
        "refer_sender should be redacted: {quote}"
    );
    assert!(
        q["refer_content"].is_null(),
        "refer_content should be redacted: {quote}"
    );
    // reply_text should be preserved
-    assert!(q["reply_text"].as_str().unwrap().contains("my reply"), "reply_text should be preserved: {quote}");
+    assert!(
        q["reply_text"].as_str().unwrap().contains("my reply"),
        "reply_text should be preserved: {quote}"
    );
    // raw_xml should be cleared
-    assert_eq!(q["raw_xml"].as_str(), Some(""), "raw_xml should be empty: {quote}");
+    assert_eq!(
        q["raw_xml"].as_str(),
        Some(""),
        "raw_xml should be empty: {quote}"
    );
 }
 #[test]
@@ -890,19 +966,33 @@ fn sender_hiding_show_hidden_restores_all_messages_and_quotes() {
    let result = run_json(
        fixture.path(),
        &[
-            "query", TALKER_GROUP,
+            "query",
-            "--data-dir", senders_dir.as_str(),
+            TALKER_GROUP,
-            "--key", TEST_KEY_HEX,
+            "--data-dir",
            senders_dir.as_str(),
            "--key",
            TEST_KEY_HEX,
            "--show-hidden",
-            "--format", "json",
+            "--format",
            "json",
        ],
    );
    let items = result["items"].as_array().expect("query items array");
-    assert_eq!(items.len(), 3, "show_hidden should restore all 3 messages: {result}");
+    assert_eq!(
        items.len(),
        3,
        "show_hidden should restore all 3 messages: {result}"
    );
    // Quote should have refer_sender intact
-    let quote = items.iter().find(|i| i["server_id"].as_i64() == Some(4003)).unwrap();
+    let quote = items
-    assert!(!quote["content"]["Quote"]["refer_sender"].is_null(), "refer_sender should be intact with show_hidden: {quote}");
+        .iter()
        .find(|i| i["server_id"].as_i64() == Some(4003))
        .unwrap();
    assert!(
        !quote["content"]["Quote"]["refer_sender"].is_null(),
        "refer_sender should be intact with show_hidden: {quote}"
    );
 }
 #[test]
@@ -914,22 +1004,37 @@ fn sender_hiding_session_placeholder_when_last_sender_hidden() {
        fixture.path(),
        &[
            "sessions",
-            "--data-dir", senders_dir.as_str(),
+            "--data-dir",
-            "--key", TEST_KEY_HEX,
+            senders_dir.as_str(),
-            "--format", "json",
+            "--key",
            TEST_KEY_HEX,
            "--format",
            "json",
        ],
    );
    let items = sessions["items"].as_array().expect("sessions items array");
-    let group_session = items.iter().find(|i| i["username"].as_str() == Some(TALKER_GROUP));
+    let group_session = items
-    assert!(group_session.is_some(), "group session should be visible: {sessions}");
+        .iter()
        .find(|i| i["username"].as_str() == Some(TALKER_GROUP));
    assert!(
        group_session.is_some(),
        "group session should be visible: {sessions}"
    );
    let group_session = group_session.unwrap();
    // Summary should be placeholder, sender fields should be null
-    assert_eq!(group_session["summary"].as_str(), Some("[消息已隐藏]"),
+    assert_eq!(
-        "summary should be placeholder: {group_session}");
+        group_session["summary"].as_str(),
-    assert!(group_session["last_msg_sender"].is_null(),
+        Some("[消息已隐藏]"),
-        "last_msg_sender should be null: {group_session}");
+        "summary should be placeholder: {group_session}"
-    assert!(group_session["direction"].is_null(),
+    );
-        "direction should be null: {group_session}");
+    assert!(
        group_session["last_msg_sender"].is_null(),
        "last_msg_sender should be null: {group_session}"
    );
    assert!(
        group_session["direction"].is_null(),
        "direction should be null: {group_session}"
    );
 }
@@ -4,6 +4,7 @@ use std::io::{Read, Write};
 use std::net::{TcpListener, TcpStream};
 use std::path::Path;
 use std::process::{Child, Command, Stdio};
 use std::sync::Mutex;
 use std::thread;
 use std::time::{Duration, Instant};
@@ -18,6 +19,7 @@ const MSG_TABLE: &str = "Msg_29a6db07e8bbdb53f5d54cc3c309f3f1";
 const GROUP_TALKER: &str = "test@chatroom";
 const GROUP_MSG_TABLE: &str = "Msg_1d282e28b02b5c9f9522f855de32f9a8";
 const HIDDEN_SENDER: &str = "wxid_spam";
 static SERVER_START_LOCK: Mutex<()> = Mutex::new(());
 fn bin() -> &'static str {
    env!("CARGO_BIN_EXE_wx-cli")
@@ -98,8 +100,10 @@ fn serve_media_visible_sender_in_group_with_hidden_persons_not_visibility_blocke
        let body = String::from_utf8_lossy(&response.body);
        // The media endpoint was reached (not blocked by visibility) but the asset
        // isn't on disk. Acceptable.
-        assert!(!body.contains("message not found"),
+        assert!(
-            "visible sender should NOT get visibility 404: {body}");
+            !body.contains("message not found"),
            "visible sender should NOT get visibility 404: {body}"
        );
    }
    // If 200, even better — means asset resolution succeeded
 }
@@ -148,9 +152,22 @@ fn serve_media_dispatch_image_returns_png_bytes() {
    );
    assert_eq!(response.status_code, 200, "{response:#?}");
    assert_eq!(response.header("content-type"), Some("image/png"));
    assert_eq!(response.header("x-wechat-media-quality"), Some("full"));
    assert_eq!(&response.body[..8], b"\x89PNG\r\n\x1a\n");
 }
 #[test]
 fn serve_media_thumbnail_only_image_reports_quality() {
    let server = spawn_test_server();
    let response = http_get(
        &server.base_url,
        "/api/v1/media?server_id=3009&talker=wxid_alice",
    );
    assert_eq!(response.status_code, 200, "{response:#?}");
    assert_eq!(response.header("content-type"), Some("image/png"));
    assert_eq!(response.header("x-wechat-media-quality"), Some("thumbnail"));
 }
 #[test]
 fn serve_media_wxgf_embedded_png_returns_png_without_ffmpeg() {
    let server = spawn_test_server_with_env(&[("FFMPEG_PATH", "/definitely-missing-ffmpeg")]);
@@ -317,16 +334,17 @@ fn spawn_test_server_with_env(envs: &[(&str, &str)]) -> TestServer {
    spawn_test_server_with_setup(envs, &[])
 }
-fn spawn_test_server_with_setup(
+fn spawn_test_server_with_setup(envs: &[(&str, &str)], hidden_contacts: &[&str]) -> TestServer {
    envs: &[(&str, &str)],
    hidden_contacts: &[&str],
 ) -> TestServer {
    let fixture = create_fixture();
    if !hidden_contacts.is_empty() {
        write_settings(fixture.path(), hidden_contacts);
    }
    let account_dir = fixture.path().join(TEST_ACCOUNT_ID);
    let runtime_root = fixture.path().join("runtime");
    // Keep ephemeral-port selection and worker binding atomic across parallel tests.
    let _start_guard = SERVER_START_LOCK
        .lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner());
    let port = find_open_port();
    let mut command = Command::new(bin());
    command
@@ -713,6 +731,27 @@ fn create_encrypted_message_db(path: &Path, raw_key: &[u8; 32]) {
            )
            .expect("insert image ok message");
            let image_thumb_only_info =
                encode_packed_info_for_test(Some("md5_image_thumb_only"), None);
            conn.execute(
                &format!(
                    "INSERT INTO [{table}] VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)",
                    table = MSG_TABLE
                ),
                params![
                    301_i64,
                    3009_i64,
                    3_i64,
                    1_i64,
                    1_709_251_200_i64,
                    Vec::<u8>::new(),
                    image_thumb_only_info,
                    0_i32,
                    None::<i32>,
                ],
            )
            .expect("insert thumbnail-only image message");
            let image_wxgf_png_info = encode_packed_info_for_test(Some("md5_image_wxgf_png"), None);
            conn.execute(
                &format!(
@@ -986,6 +1025,8 @@ fn create_image_fixture(attach_dir: &Path) {
    let encrypted = xor_bytes(&png, xor_key);
    fs::write(month_dir.join("md5_image_ok_t.dat"), &encrypted).expect("write thumb dat");
    fs::write(month_dir.join("md5_image_ok.dat"), &encrypted).expect("write image dat");
    fs::write(month_dir.join("md5_image_thumb_only_t.dat"), &encrypted)
        .expect("write thumbnail-only dat");
    let wxgf_png = sample_wxgf_with_embedded_png();
    let wxgf_png_encrypted = xor_bytes(&wxgf_png, xor_key);
@@ -773,10 +773,7 @@ mod tests {
                &tmp.path().join("cache").join("test.db"),
            )
            .unwrap_err();
-        assert!(matches!(
+        assert!(matches!(err, wx_decrypt::DecryptError::NoMatchingEncKey));
            err,
            wx_decrypt::DecryptError::NoMatchingEncKey
        ));
    }
    #[test]
@@ -15,6 +15,7 @@ struct ResolvedContact {
    signature: Option<String>,
    region: Option<String>,
    labels: Vec<String>,
    avatar_url: Option<String>,
 }
 pub struct ContactResolver {
@@ -56,6 +57,7 @@ impl ContactResolver {
                        signature: c.signature,
                        region: c.region,
                        labels: c.labels,
                        avatar_url: c.avatar_url,
                    },
                );
            }
@@ -92,6 +94,13 @@ impl ContactResolver {
            .unwrap_or(&[])
    }
    /// Resolve a wxid to its preferred avatar URL.
    pub fn avatar_url(&self, wxid: &str) -> Option<&str> {
        self.contacts
            .get(wxid)
            .and_then(|contact| contact.avatar_url.as_deref())
    }
    /// Iterate all contacts with their wxid and labels.
    /// Used by VisibilityIndex to expand ignore_tags.
    pub fn all_labels(&self) -> impl Iterator<Item = (&String, &[String])> {
@@ -200,6 +209,7 @@ mod tests {
                        signature: None,
                        region: None,
                        labels: Vec::new(),
                        avatar_url: None,
                    },
                )
            })
@@ -235,6 +245,7 @@ mod tests {
                        signature: None,
                        region: None,
                        labels: labels.iter().map(|s| s.to_string()).collect(),
                        avatar_url: None,
                    },
                )
            })
@@ -77,8 +77,7 @@ impl VisibilityIndex {
    ///
    /// Hidden talkers OR hidden senders in visible groups cannot access media.
    pub fn allows_media_for_sender(&self, talker: &str, sender: &str) -> bool {
-        !self.hidden_persons.contains(talker)
+        !self.hidden_persons.contains(talker) && !self.is_hidden_sender_in_group(talker, sender)
            && !self.is_hidden_sender_in_group(talker, sender)
    }
 }
@@ -230,10 +229,7 @@ mod tests {
    #[test]
    fn allows_media_for_sender_covers_both_levels() {
        let idx = VisibilityIndex {
-            hidden_persons: vec![
+            hidden_persons: vec!["hidden_group@chatroom".to_string(), "wxid_spam".to_string()]
                "hidden_group@chatroom".to_string(),
                "wxid_spam".to_string(),
            ]
                .into_iter()
                .collect(),
        };
@@ -43,16 +43,19 @@ impl WechatDb {
        limit: usize,
        label_map: &HashMap<String, String>,
    ) -> Result<QueryResult<Contact>, DbError> {
        let avatar_expr = self.contact_avatar_select_expr()?;
        let total_rows: usize =
            self.contact_conn
                .query_row("SELECT COUNT(*) FROM contact", [], |row| {
                    row.get::<_, i64>(0)
                })? as usize;
-        let mut stmt = self.contact_conn.prepare(
+        let sql = format!(
-            "SELECT username, alias, remark, nick_name, description, extra_buffer \
+            "SELECT username, alias, remark, nick_name, description, extra_buffer, \
-             FROM contact ORDER BY username ASC LIMIT ?1 OFFSET ?2",
+             {avatar_expr} AS avatar_url \
-        )?;
+             FROM contact ORDER BY username ASC LIMIT ?1 OFFSET ?2"
        );
        let mut stmt = self.contact_conn.prepare(&sql)?;
        let rows = stmt.query_map(
            [
                Value::Integer(limit as i64),
@@ -81,6 +84,7 @@ impl WechatDb {
        label_map: &HashMap<String, String>,
    ) -> Result<QueryResult<Contact>, DbError> {
        let kw_lower = query.keyword.as_ref().unwrap().to_lowercase();
        let avatar_expr = self.contact_avatar_select_expr()?;
        let total_rows: usize =
            self.contact_conn
@@ -88,10 +92,12 @@ impl WechatDb {
                    row.get::<_, i64>(0)
                })? as usize;
-        let mut stmt = self.contact_conn.prepare(
+        let sql = format!(
-            "SELECT username, alias, remark, nick_name, description, extra_buffer \
+            "SELECT username, alias, remark, nick_name, description, extra_buffer, \
-             FROM contact ORDER BY username ASC",
+             {avatar_expr} AS avatar_url \
-        )?;
+             FROM contact ORDER BY username ASC"
        );
        let mut stmt = self.contact_conn.prepare(&sql)?;
        let rows = stmt.query_map([], |row| self.map_contact_row(row, label_map))?;
        let all_contacts: Vec<Contact> = rows.filter_map(|r| r.ok()).collect();
@@ -126,6 +132,10 @@ impl WechatDb {
        let nick_name: String = row.get::<_, String>(3).unwrap_or_default();
        let memo: Option<String> = row.get::<_, Option<String>>(4).unwrap_or(None);
        let extra_buffer: Vec<u8> = row.get::<_, Vec<u8>>(5).unwrap_or_default();
        let avatar_url: Option<String> = row
            .get::<_, Option<String>>(6)
            .unwrap_or(None)
            .filter(|value| !value.is_empty());
        let extra = contact_proto::decode_extra_buffer(&extra_buffer);
@@ -147,6 +157,22 @@ impl WechatDb {
            source_scene: extra.source_scene,
            phone: extra.phone,
            labels,
            avatar_url,
        })
    }
    /// Build a compatible avatar expression for WeChat database variants.
    /// Older fixtures and database versions may not contain either column.
    fn contact_avatar_select_expr(&self) -> Result<&'static str, DbError> {
        let has_small =
            decode::check_column_exists(&self.contact_conn, "contact", "small_head_url")?;
        let has_big = decode::check_column_exists(&self.contact_conn, "contact", "big_head_url")?;
        Ok(match (has_small, has_big) {
            (true, true) => "COALESCE(NULLIF(small_head_url, ''), NULLIF(big_head_url, ''))",
            (true, false) => "NULLIF(small_head_url, '')",
            (false, true) => "NULLIF(big_head_url, '')",
            (false, false) => "NULL",
        })
    }
@@ -302,11 +302,8 @@ mod tests {
    #[test]
    fn non_group_returns_fallback_unchanged() {
-        let (sender, content) = parse_group_sender(
+        let (sender, content) =
-            false,
+            parse_group_sender(false, "hello world".to_string(), "fallback".to_string());
            "hello world".to_string(),
            "fallback".to_string(),
        );
        assert_eq!(sender, "fallback");
        assert_eq!(content, "hello world");
    }
@@ -335,22 +332,16 @@ mod tests {
    #[test]
    fn group_empty_content_after_separator() {
-        let (sender, content) = parse_group_sender(
+        let (sender, content) =
-            true,
+            parse_group_sender(true, "wxid_abc:\n".to_string(), "fallback".to_string());
            "wxid_abc:\n".to_string(),
            "fallback".to_string(),
        );
        assert_eq!(sender, "wxid_abc");
        assert_eq!(content, "");
    }
    #[test]
    fn group_only_colon_before_newline() {
-        let (sender, content) = parse_group_sender(
+        let (sender, content) =
-            true,
+            parse_group_sender(true, ":\nsome content".to_string(), "fallback".to_string());
            ":\nsome content".to_string(),
            "fallback".to_string(),
        );
        assert_eq!(sender, "");
        assert_eq!(content, "some content");
    }
@@ -6,7 +6,9 @@ use rusqlite::types::ValueRef;
 use rusqlite::Connection;
 use serde::Serialize;
-use crate::decode::{check_column_exists, decode_content, msg_table_name, parse_content, parse_group_sender};
+use crate::decode::{
    check_column_exists, decode_content, msg_table_name, parse_content, parse_group_sender,
 };
 use crate::error::DbError;
 use crate::model::{split_local_type, MessageContent};
 use crate::open::WechatDb;
@@ -414,8 +416,7 @@ impl WechatDb {
        )?;
        for shard in &self.shards {
-            let shard_conn =
+            let shard_conn = WechatDb::open_shard_with_key(shard, self.sqlcipher_key.as_ref())?;
                WechatDb::open_shard_with_key(shard, self.sqlcipher_key.as_ref())?;
            // List Msg_* tables in this shard
            let mut table_stmt = shard_conn.prepare(
@@ -574,7 +575,8 @@ impl WechatDb {
        let decoded_text = decode_content(&raw_content, wcdb_ct)?;
        // Group sender parsing
-        let (sender, content_text) = parse_group_sender(is_group, decoded_text, sender_from_name2id);
+        let (sender, content_text) =
            parse_group_sender(is_group, decoded_text, sender_from_name2id);
        let (msg_type, sub_type) = split_local_type(local_type as i64);
@@ -323,9 +323,11 @@ impl WechatDb {
        msg_type_filter: Option<u32>,
    ) -> usize {
        let result = if let Some(mt) = msg_type_filter {
-            conn.query_row(sql, [start_time, end_time, mt as i64], |row: &rusqlite::Row<'_>| {
+            conn.query_row(
-                row.get::<_, i64>(0)
+                sql,
-            })
+                [start_time, end_time, mt as i64],
                |row: &rusqlite::Row<'_>| row.get::<_, i64>(0),
            )
        } else {
            conn.query_row(sql, [start_time, end_time], |row: &rusqlite::Row<'_>| {
                row.get::<_, i64>(0)
@@ -380,6 +380,9 @@ pub struct Contact {
    pub phone: Option<String>,
    /// Resolved label names from extra_buffer + contact_label table.
    pub labels: Vec<String>,
    /// Preferred avatar URL from `small_head_url`, falling back to `big_head_url`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub avatar_url: Option<String>,
 }
 /// A WeChat chatroom (group chat) entry with its member list.
@@ -530,10 +530,7 @@ mod tests {
    #[test]
    fn extract_quote_fromusr_normal() {
        let xml = r#"<msg><appmsg><title>reply</title><refermsg><fromusr>wxid_alice</fromusr><content>hi</content></refermsg></appmsg></msg>"#;
-        assert_eq!(
+        assert_eq!(extract_quote_fromusr(xml), Some("wxid_alice".to_string()));
            extract_quote_fromusr(xml),
            Some("wxid_alice".to_string())
        );
    }
    #[test]
@@ -552,19 +549,13 @@ mod tests {
    fn extract_quote_fromusr_prefers_chatusr_in_group() {
        // In group chats, <fromusr> is the chatroom ID, <chatusr> is the actual sender
        let xml = r#"<msg><appmsg><title>reply</title><refermsg><fromusr>group@chatroom</fromusr><chatusr>wxid_sender</chatusr><displayname>Sender</displayname><content>hi</content></refermsg></appmsg></msg>"#;
-        assert_eq!(
+        assert_eq!(extract_quote_fromusr(xml), Some("wxid_sender".to_string()));
            extract_quote_fromusr(xml),
            Some("wxid_sender".to_string())
        );
    }
    #[test]
    fn extract_quote_fromusr_falls_back_to_fromusr_without_chatusr() {
        // In private chats, only <fromusr> exists (no <chatusr>)
        let xml = r#"<msg><appmsg><title>reply</title><refermsg><fromusr>wxid_bob</fromusr><displayname>Bob</displayname><content>hi</content></refermsg></appmsg></msg>"#;
-        assert_eq!(
+        assert_eq!(extract_quote_fromusr(xml), Some("wxid_bob".to_string()));
            extract_quote_fromusr(xml),
            Some("wxid_bob".to_string())
        );
    }
 }
@@ -282,6 +282,55 @@ fn contacts_sessions_query_contacts_limit() {
    assert_eq!(result.items.len(), 1);
 }
 #[test]
 fn contacts_sessions_query_contacts_avatar_url() {
    let dir = create_fixture();
    let contact_path = dir.path().join("contact").join("contact.db");
    let conn = Connection::open(contact_path).unwrap();
    conn.execute_batch(
        "ALTER TABLE contact ADD COLUMN small_head_url TEXT;
         ALTER TABLE contact ADD COLUMN big_head_url TEXT;",
    )
    .unwrap();
    conn.execute(
        "UPDATE contact SET small_head_url = ?1, big_head_url = ?2 WHERE username = ?3",
        params![
            "https://avatar.example/alice-small.jpg",
            "https://avatar.example/alice-big.jpg",
            "wxid_alice"
        ],
    )
    .unwrap();
    conn.execute(
        "UPDATE contact SET big_head_url = ?1 WHERE username = ?2",
        params!["https://avatar.example/bob-big.jpg", "wxid_bob"],
    )
    .unwrap();
    drop(conn);
    let db = WechatDb::open(dir.path()).unwrap();
    let result = db.query_contacts(&ContactQuery::new()).unwrap();
    let alice = result
        .items
        .iter()
        .find(|contact| contact.user_name == "wxid_alice")
        .unwrap();
    let bob = result
        .items
        .iter()
        .find(|contact| contact.user_name == "wxid_bob")
        .unwrap();
    assert_eq!(
        alice.avatar_url.as_deref(),
        Some("https://avatar.example/alice-small.jpg")
    );
    assert_eq!(
        bob.avatar_url.as_deref(),
        Some("https://avatar.example/bob-big.jpg")
    );
 }
 // ---- sessions tests ----
 #[test]
@@ -20,7 +20,9 @@ pub enum KeychainError {
    #[error("WeChat is not running")]
    WeChatNotRunning,
-    #[error("WeChat version {version} is not supported for key extraction (requires 4.1.7.x or 4.1.8.x)")]
+    #[error(
        "WeChat version {version} is not supported for key extraction (requires 4.1.7 or newer)"
    )]
    UnsupportedVersion { version: String },
    #[error("could not detect WeChat account directory")]
@@ -17,11 +17,11 @@ pub use process::config_dir;
 pub use process::detect_active_account;
 pub use process::{
    ensure_supported_wechat_version, extract_base_wxid, find_account_dirs, find_account_dirs_under,
-    find_wechat_pid, is_xwechat_files_root, AccountDirInfo, ActiveAccount,
+    find_wechat_pid, is_xwechat_files_root, AccountDirInfo, ActiveAccount, DetectionSource,
-    DetectionSource, SUPPORTED_VERSION,
+    SUPPORTED_VERSION,
 };
 pub use wx_decrypt::read_db_salt;
 pub use store::{AccountKey, EncKeyEntry, KeyStore};
 pub use wx_decrypt::read_db_salt;
 use std::process::Command;
@@ -46,7 +46,11 @@ pub async fn capture_key(
    // Pre-read salts from all accounts. Skip unreadable DBs.
    let account_salts: Vec<([u8; 16], &AccountDirInfo)> = accounts
        .iter()
-        .filter_map(|a| wx_decrypt::read_db_salt(&a.message_db_path).ok().map(|salt| (salt, a)))
+        .filter_map(|a| {
            wx_decrypt::read_db_salt(&a.message_db_path)
                .ok()
                .map(|salt| (salt, a))
        })
        .collect();
    if account_salts.is_empty() {
@@ -3,17 +3,30 @@ use std::process::Command;
 use crate::error::KeychainError;
-pub const SUPPORTED_VERSION: &str = "4.1.8.21";
+pub const SUPPORTED_VERSION: &str = "4.1.7+";
-/// Version prefixes accepted for LLDB key extraction.
+/// Minimum version accepted for key extraction.
-/// Encryption params (PBKDF2-HMAC-SHA512, 256K iterations) are identical across these versions.
+/// Encryption params (PBKDF2-HMAC-SHA512, 256K iterations) are identical from this version onward.
-const EXTRACTION_VERSION_PREFIXES: &[&str] = &["4.1.7", "4.1.8"];
+const MIN_EXTRACTION_VERSION: (u64, u64, u64) = (4, 1, 7);
 /// Check whether a version string is compatible with our LLDB key extraction.
 fn is_extraction_compatible(version: &str) -> bool {
-    EXTRACTION_VERSION_PREFIXES
+    let mut components = version.split('.');
-        .iter()
+    let Some(major) = components.next().and_then(|value| value.parse().ok()) else {
-        .any(|prefix| version == *prefix || version.starts_with(&format!("{prefix}.")))
+        return false;
    };
    let Some(minor) = components.next().and_then(|value| value.parse().ok()) else {
        return false;
    };
    let Some(patch) = components.next().and_then(|value| value.parse().ok()) else {
        return false;
    };
    if components.any(|value| value.is_empty() || value.parse::<u64>().is_err()) {
        return false;
    }
    (major, minor, patch) >= MIN_EXTRACTION_VERSION
 }
 #[derive(Debug, Clone)]
@@ -138,16 +151,16 @@ fn get_wechat_version() -> Result<String, KeychainError> {
 /// Shared config directory resolved by `AppPaths`.
 pub fn config_dir() -> Result<PathBuf, KeychainError> {
-    let ap = wx_paths::AppPaths::new()
+    let ap = wx_paths::AppPaths::new().map_err(|e| KeychainError::Other(e.to_string()))?;
        .map_err(|e| KeychainError::Other(e.to_string()))?;
    Ok(ap.config_dir())
 }
 /// Default xwechat_files base path.
 fn default_xwechat_files_base() -> Result<PathBuf, KeychainError> {
-    let ap = wx_paths::AppPaths::new()
+    let ap = wx_paths::AppPaths::new().map_err(|e| KeychainError::Other(e.to_string()))?;
-        .map_err(|e| KeychainError::Other(e.to_string()))?;
+    Ok(ap
-    Ok(ap.home().join("Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files"))
+        .home()
        .join("Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files"))
 }
 /// Detect account directories from the filesystem (without WeChat running).
@@ -350,11 +363,32 @@ fn tiebreak_by_wal_mtime<'a>(accounts: &[&'a AccountDirInfo]) -> Option<&'a Acco
    best
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn test_extraction_version_accepts_4_1_7_and_newer() {
        for version in [
            "4.1.7", "4.1.7.31", "4.1.8", "4.1.9", "4.1.13", "4.2.0", "5.0.0",
        ] {
            assert!(
                is_extraction_compatible(version),
                "expected {version} to be supported"
            );
        }
    }
    #[test]
    fn test_extraction_version_rejects_older_and_invalid_versions() {
        for version in ["4.1.6.99", "4.0.99", "3.9.9", "4.1", "4.1.beta", ""] {
            assert!(
                !is_extraction_compatible(version),
                "expected {version:?} to be rejected"
            );
        }
    }
    #[test]
    fn test_extract_base_wxid_with_suffix() {
        assert_eq!(
@@ -57,15 +57,13 @@ pub struct KeyStore {
 impl KeyStore {
    /// Default path: `<config_dir>/keys.toml`
    pub fn default_path() -> Result<PathBuf, KeychainError> {
-        let ap = wx_paths::AppPaths::new()
+        let ap = wx_paths::AppPaths::new().map_err(|e| KeychainError::Other(e.to_string()))?;
            .map_err(|e| KeychainError::Other(e.to_string()))?;
        Ok(ap.keys_file())
    }
    /// Load from the default path, creating an empty store if the file doesn't exist.
    pub fn load_default() -> Result<Self, KeychainError> {
-        let ap = wx_paths::AppPaths::new()
+        let ap = wx_paths::AppPaths::new().map_err(|e| KeychainError::Other(e.to_string()))?;
            .map_err(|e| KeychainError::Other(e.to_string()))?;
        ap.migrate_config()
            .map_err(|e| KeychainError::Other(format!("config migration failed: {}", e)))?;
        let path = ap.keys_file();
@@ -354,7 +352,6 @@ impl KeyStore {
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -199,8 +199,8 @@ fn aes_ecb_decrypt(ciphertext: &[u8], key: &[u8; 16]) -> Result<Vec<u8>, MediaEr
    let cipher = Aes128::new(key.into());
    let mut decrypted = ciphertext.to_vec();
-    for chunk in decrypted.chunks_exact_mut(16) {
+    for chunk in decrypted.as_chunks_mut::<16>().0 {
-        cipher.decrypt_block(chunk.try_into().expect("chunk length mismatch"));
+        cipher.decrypt_block(chunk.into());
    }
    // PKCS7 unpadding
@@ -58,7 +58,11 @@ pub fn reset_ffmpeg_cache() {
    FFPROBE_CACHED.store(false, Ordering::Release);
 }
-fn run_command_with_piped_input(bin: String, input: &[u8], args: &[&str]) -> Result<Output, MediaError> {
+fn run_command_with_piped_input(
    bin: String,
    input: &[u8],
    args: &[&str],
 ) -> Result<Output, MediaError> {
    let mut child = Command::new(&bin)
        .args(args)
        .stdin(Stdio::piped())
@@ -76,7 +80,9 @@ fn run_command_with_piped_input(bin: String, input: &[u8], args: &[&str]) -> Res
            })
        });
-        let output = child.wait_with_output().map_err(|e| MediaError::FfmpegFailed {
+        let output = child
            .wait_with_output()
            .map_err(|e| MediaError::FfmpegFailed {
                status: -1,
                stderr: e.to_string(),
            })?;
@@ -22,7 +22,7 @@ pub fn query_hardlink_with_conn(
    media_type: &str,
    key: &str,
 ) -> Result<Vec<HardlinkEntry>, MediaError> {
-    let table = resolve_table(&conn, media_type)?;
+    let table = resolve_table(conn, media_type)?;
    let query = format!(
        "SELECT f.md5, f.file_name, f.file_size, f.modify_time,
@@ -37,9 +37,7 @@ fn extract_wxid_from_data_dir(data_dir: &Path) -> Result<String, MediaError> {
    Ok(data_dir.parent().map_or_else(
        || extract_wxid(dir_name),
-        |root| {
+        |root| wx_keychain::process::extract_base_wxid_for_account_dir_under_root(root, dir_name),
            wx_keychain::process::extract_base_wxid_for_account_dir_under_root(root, dir_name)
        },
    ))
 }
@@ -85,7 +85,9 @@ pub use audio_transcode::{transcode_silk_to_mp3, transcode_silk_to_ogg_opus};
 pub use dat::{decrypt_dat, detect_dat_format, detect_image_type, detect_xor_key};
 pub use error::MediaError;
 pub use fallback::{find_file_by_name, find_video_by_md5};
-pub use ffmpeg::{ffmpeg_available, ffprobe_available, reset_ffmpeg_cache, run_ffmpeg, run_ffprobe};
+pub use ffmpeg::{
    ffmpeg_available, ffprobe_available, reset_ffmpeg_cache, run_ffmpeg, run_ffprobe,
 };
 pub use hardlink::{query_hardlink, query_hardlink_with_conn};
 pub use image_resolver::{resolve_image, resolve_image_by_md5};
 pub use image_transcode::transcode_wxgf;
@@ -97,7 +99,9 @@ pub use types::{
    MediaLookupResult, TranscodeAudioResult, TranscodeImageResult, VoiceBlob,
 };
 pub use video_decrypt::{decrypt_video, decrypt_video_with_keystream};
-pub use voice::{extract_voice, extract_voice_with_conn, extract_voice_with_conn_hint, find_media_dbs};
+pub use voice::{
    extract_voice, extract_voice_with_conn, extract_voice_with_conn_hint, find_media_dbs,
 };
 pub use wxgf::{parse_wxgf, WxgfContent};
 /// Compute MD5 hash of bytes, returning the `md5::Digest` (displays as hex).
@@ -12,7 +12,12 @@ fn sample_silk() -> Vec<u8> {
 #[cfg(feature = "audio")]
 fn long_sample_silk() -> Vec<u8> {
-    silk_rs::encode_silk(vec![0_u8; silent_pcm_frame().len() * 250], 24_000, 24_000, true)
+    silk_rs::encode_silk(
        vec![0_u8; silent_pcm_frame().len() * 250],
        24_000,
        24_000,
        true,
    )
    .unwrap()
 }
@@ -15,21 +15,21 @@ fn make_xor_dat(key: u8) -> Vec<u8> {
 /// Header: 07 08 V1 08 07 (6B) + aes_size LE (4B) + xor_size LE (4B) + 0x01 (1B) = 15B
 /// Then AES-ECB encrypted payload with fixed key, then raw, then XOR tail.
 fn make_v1_dat() -> Vec<u8> {
-    use aes::cipher::{BlockCipherEncrypt, KeyInit};
+    use aes::cipher::{Array, BlockCipherEncrypt, KeyInit};
    use aes::Aes128;
    let key = b"cfcd208495d565ef"; // md5("0")[:16]
    let cipher = Aes128::new(key.into());
    // Plaintext: JPEG header (16 bytes = 1 AES block) with PKCS7 padding
-    let mut block1 = [
+    let mut block1 = Array::from([
        0xFFu8, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00,
        0x01,
-    ];
+    ]);
-    let mut block2 = [16u8; 16]; // full PKCS7 padding block
+    let mut block2 = Array::from([16u8; 16]); // full PKCS7 padding block
-    cipher.encrypt_block(aes::cipher::Array::from_mut_slice(&mut block1));
+    cipher.encrypt_block(&mut block1);
-    cipher.encrypt_block(aes::cipher::Array::from_mut_slice(&mut block2));
+    cipher.encrypt_block(&mut block2);
    let aes_size: u32 = 16; // original plaintext size
    let xor_size: u32 = 0;
@@ -46,20 +46,20 @@ fn make_v1_dat() -> Vec<u8> {
 /// Build a V2-encrypted `.dat` file with known AES key and XOR tail.
 fn make_v2_dat(aes_key: &[u8; 16], xor_key: u8) -> Vec<u8> {
-    use aes::cipher::{BlockCipherEncrypt, KeyInit};
+    use aes::cipher::{Array, BlockCipherEncrypt, KeyInit};
    use aes::Aes128;
    let cipher = Aes128::new(aes_key.into());
    // Plaintext: PNG header (16 bytes = 1 block)
-    let mut block1 = [
+    let mut block1 = Array::from([
        0x89u8, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44,
        0x52,
-    ];
+    ]);
-    let mut block2 = [16u8; 16]; // PKCS7 padding block
+    let mut block2 = Array::from([16u8; 16]); // PKCS7 padding block
-    cipher.encrypt_block(aes::cipher::Array::from_mut_slice(&mut block1));
+    cipher.encrypt_block(&mut block1);
-    cipher.encrypt_block(aes::cipher::Array::from_mut_slice(&mut block2));
+    cipher.encrypt_block(&mut block2);
    let aes_size: u32 = 16;
    // Tail: 4 bytes XOR-encrypted
@@ -184,10 +184,7 @@ fn voice_query_with_conn_returns_stable_not_found_errors() {
 fn voice_query_with_conn_hint_returns_chat_name_id_from_indexed_lookup() {
    let tmp = TempDir::new().unwrap();
    let db_path = tmp.path().join("media.db");
-    create_indexed_media_db(
+    create_indexed_media_db(&db_path, &[(55, 1000, 1, "srv_hint_1", b"hinted_blob")]);
        &db_path,
        &[(55, 1000, 1, "srv_hint_1", b"hinted_blob")],
    );
    let conn = rusqlite::Connection::open(&db_path).unwrap();
    let blob = wx_media::extract_voice_with_conn_hint(&conn, "srv_hint_1", Some(55)).unwrap();
@@ -118,11 +118,7 @@ impl DecryptCache {
        wx_decrypt::dispatch_decrypt_db(src, dst, &self.key_material, self.params)
    }
-    fn do_decrypt_wal(
+    fn do_decrypt_wal(&self, wal: &Path, dst: &Path) -> Result<usize, wx_decrypt::DecryptError> {
        &self,
        wal: &Path,
        dst: &Path,
    ) -> Result<usize, wx_decrypt::DecryptError> {
        wx_decrypt::dispatch_decrypt_wal(wal, dst, &self.key_material, self.params)
    }
 }
@@ -217,10 +217,7 @@ async fn monitor_detects_session_change() {
    // Should be an Updated event for wxid_bob (the new session)
    assert_eq!(event.username, "wxid_bob");
-    assert!(matches!(
+    assert!(matches!(event.kind, wx_monitor::SessionEventKind::Updated));
        event.kind,
        wx_monitor::SessionEventKind::Updated
    ));
    // Stop monitor and assert clean exit
    monitor.stop();
@@ -211,7 +211,9 @@ impl AppPaths {
    /// `<temp_root>/lldb/wechat_lldb_output.txt`
    pub fn lldb_output_file() -> PathBuf {
-        Self::temp_root().join("lldb").join("wechat_lldb_output.txt")
+        Self::temp_root()
            .join("lldb")
            .join("wechat_lldb_output.txt")
    }
    /// `<temp_root>/nickname/<pid>_<nanos>.db`
@@ -242,13 +244,21 @@ impl AppPaths {
    /// Current platform identifier.
    pub fn platform() -> &'static str {
        #[cfg(target_os = "macos")]
-        { "macos" }
+        {
            "macos"
        }
        #[cfg(target_os = "linux")]
-        { "linux" }
+        {
            "linux"
        }
        #[cfg(target_os = "windows")]
-        { "windows" }
+        {
            "windows"
        }
        #[cfg(not(any(target_os = "macos", target_os = "linux", target_os = "windows")))]
-        { "unknown" }
+        {
            "unknown"
        }
    }
    /// Build a summary of all paths.
@@ -359,21 +369,21 @@ mod tests {
    #[test]
    fn server_lock_file_under_server_state() {
        let ap = AppPaths::new().unwrap();
-        assert!(ap.server_lock_file().starts_with(&ap.server_state_dir()));
+        assert!(ap.server_lock_file().starts_with(ap.server_state_dir()));
        assert!(ap.server_lock_file().ends_with("manager.lock"));
    }
    #[test]
    fn server_config_file_under_server_state() {
        let ap = AppPaths::new().unwrap();
-        assert!(ap.server_config_file().starts_with(&ap.server_state_dir()));
+        assert!(ap.server_config_file().starts_with(ap.server_state_dir()));
        assert!(ap.server_config_file().ends_with("config.json"));
    }
    #[test]
    fn server_state_file_under_server_state() {
        let ap = AppPaths::new().unwrap();
-        assert!(ap.server_state_file().starts_with(&ap.server_state_dir()));
+        assert!(ap.server_state_file().starts_with(ap.server_state_dir()));
        assert!(ap.server_state_file().ends_with("state.json"));
    }
@@ -442,7 +452,10 @@ mod tests {
            let ap = AppPaths::new().unwrap();
            let config = ap.config_dir();
            assert!(
-                config.to_str().unwrap().contains("Application Support/wx-cli/config"),
+                config
                    .to_str()
                    .unwrap()
                    .contains("Application Support/wx-cli/config"),
                "macOS config should be under Application Support: {:?}",
                config
            );
@@ -464,7 +477,10 @@ mod tests {
            let ap = AppPaths::new().unwrap();
            let state = ap.state_root();
            assert!(
-                state.to_str().unwrap().contains("Application Support/wx-cli/state"),
+                state
                    .to_str()
                    .unwrap()
                    .contains("Application Support/wx-cli/state"),
                "macOS state should be under Application Support: {:?}",
                state
            );
@@ -120,8 +120,14 @@ mod tests {
        }
        // New files exist
-        assert_eq!(fs::read_to_string(new_config.join("keys.toml")).unwrap(), "test-keys");
+        assert_eq!(
-        assert_eq!(fs::read_to_string(new_config.join("settings.toml")).unwrap(), "test-settings");
+            fs::read_to_string(new_config.join("keys.toml")).unwrap(),
            "test-keys"
        );
        assert_eq!(
            fs::read_to_string(new_config.join("settings.toml")).unwrap(),
            "test-settings"
        );
        // Old files deleted
        assert!(!old_config.join("keys.toml").exists());
@@ -153,7 +159,10 @@ mod tests {
        }
        // New file unchanged
-        assert_eq!(fs::read_to_string(new_config.join("keys.toml")).unwrap(), "new-keys");
+        assert_eq!(
            fs::read_to_string(new_config.join("keys.toml")).unwrap(),
            "new-keys"
        );
        // Old file still exists (wasn't migrated because dst exists)
        assert!(old_config.join("keys.toml").exists());
    }
@@ -26,9 +26,7 @@ impl PlatformBaseDirs {
            let config_root = dirs::config_dir()
                .ok_or(PathsError::NoConfig)?
                .join("wx-cli");
-            let cache_root = dirs::cache_dir()
+            let cache_root = dirs::cache_dir().ok_or(PathsError::NoCache)?.join("wx-cli");
                .ok_or(PathsError::NoCache)?
                .join("wx-cli");
            let state_root = dirs::state_dir()
                .or_else(dirs::data_local_dir)
                .or_else(dirs::data_dir)
@@ -48,9 +46,7 @@ impl PlatformBaseDirs {
            let config_root = dirs::config_dir()
                .ok_or(PathsError::NoConfig)?
                .join("wx-cli");
-            let cache_root = dirs::cache_dir()
+            let cache_root = dirs::cache_dir().ok_or(PathsError::NoCache)?.join("wx-cli");
                .ok_or(PathsError::NoCache)?
                .join("wx-cli");
            let local_data = dirs::data_local_dir()
                .or_else(dirs::data_dir)
                .ok_or(PathsError::NoState)?
@@ -71,9 +67,7 @@ impl PlatformBaseDirs {
            let config_root = dirs::config_dir()
                .ok_or(PathsError::NoConfig)?
                .join("wx-cli");
-            let cache_root = dirs::cache_dir()
+            let cache_root = dirs::cache_dir().ok_or(PathsError::NoCache)?.join("wx-cli");
                .ok_or(PathsError::NoCache)?
                .join("wx-cli");
            let state_root = dirs::state_dir()
                .or_else(dirs::data_local_dir)
                .or_else(dirs::data_dir)
Author	SHA1	Message	Date
pandorafuture	2abe708f55	chore: keep clippy green on stable Rust	2026-08-26 06:36:06 +00:00
pandorafuture	6c7fdda7db	fix: accept WeChat 4.1.7 and newer	2026-08-26 06:20:16 +00:00
pandorafuture	7bed9e767a	feat: expose avatars and image quality metadata	2026-07-22 11:20:16 +08:00
pandorafuture	7a8f881d33	chore: prepare v0.7.3 release	2026-07-10 23:09:55 +08:00
pandorafuture	c8f90385a3	chore: restore fmt and clippy CI checks	2026-07-10 19:29:29 +08:00
pandorafuture	4ffd4355e0	docs: explain wx-cli as the WeChat agent layer	2026-07-10 19:23:37 +08:00
pandorafuture	ef6d1ca655	perf: add cross-conversation timeline endpoint	2026-07-10 19:23:37 +08:00