wechat_msg_crawler/project.md

wechat-cli 项目规划

项目目标

构建基于微信本地数据库的 AI-first CLI 工具生态，支持消息查询、数据导出、自动化采集。

当前版本

v0.2.4

已完成功能

核心 CLI（wechat_cli/）

• 密钥提取（macOS/Linux/Windows 进程内存扫描）
• 会话列表、消息历史、全局搜索
• 联系人查询、群成员列表
• 聊天统计、收藏夹查询
• 未读消息、增量消息检测
• 导出聊天记录（Markdown/TXT）
• 媒体文件路径解析（--media 标志）

Skills

• export-chat — 单个聊天完整导出（消息+视频+音频+文件）
• tencent-cos-upload — 腾讯云 COS 文件上传工具

群聊消息采集器（collector/）— 2026-04-13 新增

• 自动发现所有群聊（定期扫描 session.db）
• 增量消息采集（基于 create_time 水位线）
• MySQL 持久化（wechat_group_message 表）
• 媒体文件上传腾讯 COS（只采集原始可读文件，不做 .dat 解密）
  • 图片: temp/RWTemp/YYYY-MM/{md5}.ext（查看后自动生成）
  • 文件/视频/音频: msg/file/YYYY-MM/filename
• 自适应扫描频率（hot/warm/cold 三级，优先级队列调度）
• 白名单/黑名单过滤（支持正则）
• 守护模式 + 一次性扫描模式
• 非文本消息元信息提取（文件名/大小/视频时长等，不依赖本地下载）
• 详细扫描日志（每条消息类型/发送者/媒体状态）
• 聊天记录合并转发解析（app_type=19 → 多行纯文本）
• 引用/回复消息关联（app_type=57 → svr_msg_id + refer_msg_svrid，支持消息间关联查询）
• 扫描频率优化（hot=15s, warm=30s, cold≤120s，保证 ≤2min 入库）
• 默认 DEBUG 日志级别
• 媒体回溯补录（watchdog 监听 RWTemp + msg/file + 10min 定时兜底扫描，补录 7 天内记录）

待规划功能

• 采集数据 Web 查询界面
• 消息内容分析/统计 dashboard

技术约束

• macOS 需要 Full Disk Access 权限
• 微信版本 ≤ 4.1.8.100
• 图片原文件需用户在微信中查看后才会出现在 temp/RWTemp 目录