Skip to content

GreenBubbles for Windows v0.2.1

Latest

Choose a tag to compare

@seaneer seaneer released this 19 Nov 11:30

GreenBubbles for Windows v0.2.1

只读读取本机 Windows 微信 4.x 聊天记录,并提供 CLI、HTTP Connector、MCP server、归档导出与加密快照。数据库解密、查询、归档全部在本机完成,不上传聊天内容或密钥。

适用环境

  • Windows 10 / 11 x64
  • 微信 4.x(实测 4.1.11.24)
  • 便携包自带 Python 3.12,无需安装 Python、pip 或 Visual Studio
  • 通常不需要管理员权限;若微信以管理员身份运行,读取其内存也需要提权

快速开始

  1. 解压 greenbubbles-win-0.2.1-portable.zip 到任意目录。
  2. 登录并保持微信运行。
  3. 在解压目录执行:
.\greenbubbles.cmd source status
.\greenbubbles.cmd chats --limit 20
.\greenbubbles.cmd messages list --conversation <id或备注> --since 2026-11-01 --limit 100
  1. 常驻 HTTP / MCP:
.\start-connector-local.cmd

默认只绑定 127.0.0.1:8787,令牌在 state\token.txt。跨机访问请用 SSH 隧道,不要把端口直接暴露到公网。

文档与启动脚本修正(2026-11-20)

  • README 补齐 Windows OpenSSH Server 前置、-N -L、user@ip 与 token 取用步骤。
  • SERVICE 补 InstallPending 回退、隧道空响应和连接器消失的排查。
  • 中文 README 同步后台启动与跨机隧道步骤。
  • 连接器 PID 校验命令行,避免 PID 复用误杀无关进程。
  • README 首页架构图改为本地 PNG;中英文 README 同步补齐上游对比、查询契约、性能、项目结构、贡献者与 Roadmap。
  • Contributors 增加豆包工作官方链接;便携包同时包含中英文 README。

本次修复(GB-001~GB-008)

  • 图片 .dat 尾钥自适应:不再写死 XOR 0x37,按 0x1c/0x37 与结构校验选择正确密钥。
  • 无效图片不再返回 200:HTTP 返回 422 mediaValidationFailed,有效响应带 X-Media-Valid、X-Media-Format、X-Media-Decrypt。
  • wxgf 明确为 HEVC 容器,连接器只做密钥校验与解码验证;不再声称可直接转码。
  • /api/v1/source 同时返回顶层 conversations 与 readiness.conversations。
  • 消息列表默认附带 media 摘要,media=0 可关闭;图片解析按文件身份缓存。
  • sanitize=1 递归移除 sender、conversationId、id,并返回 sanitizedOutput 警告。
  • 历史报告中误判的截断图片已重新解密复核,45/45 通过,并发布更正说明。

性能参考(本机、缓存已预热)

操作 首次 常驻/预热后
进程启动 1.3–1.5 s 常驻
source status 1.27 s 0.17 s
793 条消息翻页(8 页) 11.65 s 0.43 s
单会话搜索 1.49 s —
全库搜索(已建索引) 2.07 s 0.78 s
全库搜索(实时,未建索引) 48–65 s —
全库索引构建 74–100 s —
回归套件(67 例) 135 s —

性能随账号规模、磁盘与是否已建索引变化,以上仅为参考,不是承诺。

已知限制

  • 只支持 Windows 微信 4.x;macOS 请用上游 GreenBubbles。
  • 需要本机微信已登录;密钥捕获依赖读取 Weixin.exe 内存。
  • wxgf 目前只做密钥校验与 HEVC 解码验证,不自动转 PNG 预览。
  • 便携包未做代码签名,首次运行可能出现 SmartScreen 提示。
  • 不提供 GUI;交互入口为 CLI、HTTP 与 MCP。

校验

Get-FileHash .\greenbubbles-win-0.2.1-portable.zip -Algorithm SHA256

SHA-256:4DFC27104A06D0B66BF2771F2A26DF58DBB643A854F48C8E557A7BCE46FAF608

许可与归属

  • 上游:GreenBubbles(MIT,Copyright © 2026 Bojie Li)。
  • Windows 实现:seaneer(https://github.com/seaneer)与豆包工作,MIT。
  • 本项目与腾讯无关联,也未获腾讯官方授权;仅用于读取本机已登录账号的本地数据,分发与使用前请自行评估腾讯用户协议和当地法律。

验证记录

  • CI(Python 3.10 / 3.12 / 便携包):run 44693543824,全部 success
  • Release build(v0.2.1 tag):run 44693544162,success
  • 公开树已移除内部审核材料与本机修复记录;便携包已按单提交重建并替换资产,包内不含逆向研究文档。
  • 资产 SHA-256 4dfc27104a06d0b66bf2771f2a26df58dbb643a854f48c8e557a7bce46faf608