wechat_msg_crawler/CLAUDE.md

wechat-cli 项目

项目概述

基于本地微信数据库的 CLI 查询工具，支持会话、消息、联系人、群成员等查询。AI-first 设计，输出结构化 JSON。

技术栈

• Python 3.10+, Click, pycryptodome, zstandard
• SQLCipher 4 解密（AES-256-CBC）
• npm 分发 + PyInstaller 打包

目录结构

• wechat_cli/ — 主 CLI 包（commands/, core/, keys/, output/）
• skills/ — Claude Code skills（export-chat, tencent-cos-upload）
• collector/ — 群聊消息自动采集器
• collect_chats.py — 采集器入口脚本
• npm/ — npm 分发包

群聊采集器（collector/）

自动采集微信群聊消息的子系统：

• collector/config.py — 配置管理（MySQL、COS、扫描策略、回溯补录）
• collector/storage.py — MySQL 存储层（wechat_group_message 表）
• collector/wechat_adapter.py — 封装 wechat_cli.core 的适配层，包含 XML 元信息提取
• collector/scanner.py — 优先级队列扫描调度 + COS 媒体上传
• collector/backfill.py — 媒体回溯补录（watchdog 实时监听 + 定时兜底扫描）

关键约定

• wechat-cli 是只读工具，不修改微信数据
• 群聊通过 @chatroom 后缀识别
• 消息可跨多个 message_N.db 文件
• DBCache 使用 mtime 机制缓存解密副本到 /tmp/wechat_cli_cache/
• 采集器独立维护状态，不干扰 ~/.wechat-cli/last_check.json
• 非文本消息（文件/视频/链接等）从 XML 中提取元信息存入 content 字段，不依赖本地文件下载
• 群聊消息 content_raw 格式为 wxid:\n<xml>，解析 XML 时需先剥离发送者前缀
• 聊天记录合并转发（app_type=19）解析 recorditem XML，格式化为多行纯文本
• 引用/回复消息（app_type=57）提取 refermsg 中的 svrid 建立消息关联，content 格式化为 "正文\n ↳ 回复 发送者: 被引用内容"
• 数据库通过 svr_msg_id（微信 server_id）和 refer_msg_svrid（refermsg/svrid）实现引用消息的关联查询
• 采集器扫描策略: hot=15s, warm=30s, cold 退避至 120s（backoff 1.2），保证 ≤2min 入库
• 媒体文件只采集原始可读文件，不做 .dat 解密
  • 图片: 从 temp/RWTemp/YYYY-MM/{md5}.ext 获取（微信查看图片后自动生成）
  • 文件: 从 msg/file/YYYY-MM/filename 获取
  • 视频: 从 msg/video/YYYY-MM/{rawmd5}.mp4 获取
• 图片消息 content 格式为 [图片] {md5}，md5 是图片原始内容的 hash（来自消息 XML 的 md5 属性）
• 重要: RWTemp 中的图片文件名是派生 hash，与消息 XML 中的 md5/aeskey 等属性均不对应。匹配图片必须通过 hashlib.md5(文件内容) 计算后与 XML md5 属性比对，不能用文件名匹配
• 回溯补录: watchdog 监听 temp/RWTemp + msg/file + msg/video 目录 + 每 10 分钟定时扫描 media_url=NULL 记录（7天内）
• 默认日志级别 DEBUG，可通过配置文件 ~/.wechat-cli/collect-chats/config.json 修改