📱 WeChat OCR Agent / 微信未读消息监控助手

基于 PaddleOCR 的微信Mac客户端未读消息监控工具 - 自动截图并识别未读消息，支持层次化结构解析。

⚠️ 声明：本项目仅供学习研究使用，禁止用于任何商业用途。

功能特性 / Features

🔍 核心功能

• 定时监控 - 定期截图微信窗口，自动识别未读消息
• 层次化识别 - Layout → Section → Item 三层结构解析
• 结构化输出 - 提取联系人、未读数量、消息预览
• 智能过滤 - 自动排除公共服务类推广消息
• Agent 联动 - 结果可投喂给其他 Agent（自动回复、消息汇总等）

📊 识别能力

• 联系人名称提取
• 未读消息数量检测（红色气泡识别）
• 消息预览文本 OCR
• 时间戳识别
• 群聊/私聊区分

使用场景 / Use Cases

场景 A：OpenClaw Agent 后台监控

作为 OpenClaw 的后台监控任务，定期检查微信未读消息：

/agent wechat-ocr-agent 每隔 30s 自动检查微信未读消息

会在桌面创建一个wechat_screenshots 目录用于存放截图

联动示例：

如果未读消息里涉及旅游咨询询价，可以告诉 openclaw 将文本发送给 <other-process agent> 处理。

场景 B：独立工具使用

作为独立 Python 工具，手动调用进行 OCR 识别。

使用示例 / Usage Examples

层次化识别（推荐）

python scripts/hierarchical_recognition.py <截图路径>

输入： 微信聊天列表截图.png

输出：

{
  "unread_count": 3,
  "messages": [
    {
      "contact": "臭宝",
      "timestamp": "21:43",
      "preview": "好的，明天见！",
      "unread": 1
    },
    {
      "contact": "工作群",
      "timestamp": "20:15",
      "unread": 3,
      "is_group": true
    }
  ]
}

未读消息检测

python scripts/detect_unread.py <截图路径>

快速检测未读消息数量，不提取详细内容。

红色气泡扫描

python scripts/scan_red_bubbles.py <截图路径>

专门扫描红色未读气泡标记，适用于高对比度场景。

技术实现 / Technical Implementation

核心算法 / Core Algorithm

层次化识别流程：

1. Layout 层：定位微信窗口（通过搜索框特征）
2. Section 层：定位消息列表区域
3. Item 层：识别每个消息条目（联系人 + 未读标记）

未读消息检测逻辑

截图 → OCR 识别 → 定位联系人列表 → 检测红色气泡/未读标记 → 提取信息

核心脚本 / Core Scripts

1. scripts/hierarchical_recognition.py - 层次化识别主脚本

   • 三层结构解析
   • 结构化数据输出
   • 支持自定义截图路径

2. scripts/detect_unread.py - 未读消息检测

   • 快速检测未读数量
   • 轻量级识别

3. scripts/scan_red_bubbles.py - 红色气泡扫描

   • 基于颜色特征检测
   • 适用于高对比度场景

依赖 / Dependencies

Python 环境

paddlepaddle
paddleocr
Pillow
numpy

安装方式

# 方式 1：使用 requirements.txt
pip install -r requirements.txt

# 方式 2：手动安装
pip install paddlepaddle paddleocr Pillow numpy

系统要求

• 操作系统: macOS（已测试）
• Python: 3.8+
• 内存: 建议 4GB+（PaddleOCR 模型加载）

⚠️ Windows 未测试，不保证兼容性

运行方式 / How to Run

作为 OpenClaw Agent

# 安装到 OpenClaw workspace
cd ~/.openclaw/workspace
git clone https://github.com/54853315/openclaw-wechat-ocr-agent.git wechat-followup
cd wechat-followup
pip install -r requirements.txt
# 添加 Agent
openclaw agents add wechat-followup --workspace ~/openclaw/workspace/wechat-followup
openclaw gateway restart

独立运行

# 克隆仓库
git clone https://github.com/54853315/openclaw-wechat-ocr-agent.git
cd openclaw-wechat-ocr-agent
pip install -r requirements.txt

# 运行识别
python scripts/hierarchical_recognition.py screenshot.png

输出格式 / Output Format

JSON 输出

{
  "unread_count": 3,
  "messages": [
    {
      "contact": "联系人名称",
      "timestamp": "HH:mm",
      "preview": "消息预览内容",
      "unread": 1,
      "is_group": false
    }
  ]
}

字段说明

字段	类型	说明
contact	string	联系人/群聊名称
timestamp	string	消息时间（HH:mm 格式）
preview	string	消息预览文本
unread	integer	未读消息数量
is_group	boolean	是否为群聊

错误处理 / Error Handling

情况	处理方式
未检测到微信窗口	返回错误提示，建议检查截图
OCR 识别失败	重试 1 次，失败则返回空结果
截图格式不支持	提示支持的格式（PNG, JPG）
微信 UI 更新	可能需要调整识别规则

注意事项 / Notes

1. 系统兼容性 - 仅在 macOS 下测试，Windows 未测试
2. 微信版本 - 微信 UI 更新后可能需要调整识别规则
3. 窗口状态 - 建议保持微信窗口可见状态
4. 隐私保护 - 请勿用于侵犯隐私的场景
5. 性能消耗 - PaddleOCR 模型加载需要一定内存

扩展计划 / Roadmap

• 支持 Windows 系统
• 自动截图功能（无需手动截图）
• 更多消息字段提取（头像、置顶标记等）
• 实时监听模式（无需定时截图）
• 支持企业微信识别

---

免责声明 / Disclaimer

1. 本项目仅供学习研究使用，禁止用于任何商业用途
2. 仅在 macOS 下测试，Windows 未测试，不保证兼容性
3. 微信 UI 更新后可能需要调整识别规则
4. 建议保持微信窗口可见状态
5. 请勿用于侵犯隐私的场景

---

版本 / Version: 1.0.0
作者 / Author: K K (@GuGuaGuGuaX)
许可证 / License: MIT