wechatAI-Skill（微信本地数据只读助理）

Overview

This skill turns WorkBuddy into a read-only assistant for the user's own local WeChat data on a Windows machine running WeChat 4.x (Weixin.exe). It wraps wechat-cli (a local SQLCipher-decrypting CLI) plus a .dat image decoder, and provides a consistent four-dimension Markdown categorization workflow.

The skill is strictly read-only: it never sends, modifies, or deletes WeChat data, never connects to any network, and keeps decryption keys on the local machine.

When To Use

Trigger this skill when the user asks to:
- List or browse their WeChat recent sessions / conversations
- Pull and summarize chat history of a contact or group
- Search messages by keyword within a chat or across all chats
- Analyze group activity (top talkers, message-type mix, hourly peaks)
- View images sent in chats (decrypt .dat cache to JPG/PNG)
- Locate and extract PDF / Word attachments from chats
- Categorize/summarize messages into a reusable Markdown digest

Do not use this skill for: sending messages, auto-replying, controlling the WeChat UI, or any WeChat-bot behavior — those are out of scope and violate the platform ToS.

Locating the wechat-cli Environment

The wechat-cli install is a Python package run from a virtualenv. Resolve the environment in this order:

1. Environment variable WECHAT_CLI_HOME — a directory that contains .venv/ and wechat-cli-src/.
2. Default known install on this machine: D:\WorkBuddyLog\2026-10-15-08-28-38 (contains .venv/Scripts/python.exe and wechat-cli-src/).
3. Otherwise, perform a one-time setup by following references/setup.md.

Once resolved, every command is invoked as:

<HOME>/.venv/Scripts/python.exe -m wechat_cli.main <subcommand> [args]

(<HOME> = the resolved WECHAT_CLI_HOME.) The console script wechat_cli also exists in <HOME>/.venv/Scripts/.

Prerequisites (must hold before any read)

• Windows machine with WeChat 4.x installed and logged in and running (Weixin.exe process present). WeChat 3.x is incompatible.
• A successful init has been performed at least once (decryption keys persisted in ~/.wechat-cli/all_keys.json). History decrypts offline from cached keys; new messages require Weixin.exe to be running.
• The machine running the command is the same machine that runs WeChat (the tool reads the process memory for keys and the local DB).

If init has not been done, follow references/setup.md (the init step requires the user to be present and may need an elevated terminal).

Core Capabilities

Invoke the subcommands below. Add --format text for human-readable output, or parse the default JSON. Always run under the resolved venv.

1. List sessions

python -m wechat_cli.main sessions --limit 20 --format text

2. Read history

python -m wechat_cli.main history "群名或联系人" --limit 30 --format text
python -m wechat_cli.main history "群名" --limit 30 --format text --start-time "2026-10-01"
python -m wechat_cli.main history "群名" --type 图片 --limit 10 --media

--media prints the local cache path of images/files (paths only; decoding is a separate step — see below).

3. Keyword search

python -m wechat_cli.main search "关键词" --chat "会话名" --limit 30 --format text
python -m wechat_cli.main search "关键词" --format text

4. Activity statistics

python -m wechat_cli.main stats "群名" --format text
python -m wechat_cli.main stats "群名" --start-time "2026-10-08" --end-time "2026-10-15"

5. Export / contacts / members / favorites

python -m wechat_cli.main export "会话名"
python -m wechat_cli.main contacts --query "姓名"
python -m wechat_cli.main members "群名"
python -m wechat_cli.main favorites

Image / File Decoding Workflow

WeChat stores media in the local profile directory %APPDATA%/../Tencent/xwechat_files/<wxid>/msg/...:

• Images: cached as single-byte XOR-encrypted *.dat under msg/attach/<hash>/YYYY-MM/Img/. The standard --media path is unreliable (multiple messages may point to the same guessed file). To view them, run the bundled decoder on the .dat path:
  python <SKILL>/scripts/decrypt_wechat_dat.py "<path>.dat" <out_dir>
  The script auto-detects JPG/PNG/GIF/BMP by magic number. If an original _W.dat fails to decode (non-standard envelope in newer WeChat), fall back to its thumbnail ..._t_W.dat in the same folder, which usually decodes cleanly.
• PDF / Word attachments: stored unencrypted under msg/file/YYYY-MM/ with their original filenames. To open, copy the file out of that directory into the workspace and read it (use pdfplumber for PDF text, python-docx for .docx). Note all chats' files are mixed in this one folder — identify the right file by timestamp + filename.
• BMP outputs from the decoder: convert to PNG with Pillow if the viewer needs PNG (e.g. Image.open(...).save(...)).

<SKILL> = this skill's directory. The decoder script is in scripts/decrypt_wechat_dat.py.

Categorization Output Format

For any history pull, produce a Markdown digest using the four-dimension template below. Keep it copy-paste ready (it is designed to be pasted into any Markdown editor):

## 「群名/联系人」消息归类（时间范围）
**📌 核心话题**
- …

**✅ 关键决策 / 响应**
- …

**⏳ 待跟进**
- …

**🌟 精华（值得留存）**
- …

Adjust dimensions to the user's request (e.g. add a 费用/风险 column when relevant).

Security & Compliance

• Read only the user's own WeChat data. Never read others' chats or process third-party information without authorization.
• The decryption key file ~/.wechat-cli/all_keys.json is sensitive: never print it, never transmit it, never commit it to a repo.
• Every command invocation must be authorized by the user; do not auto-retry on failure.
• Export files only to the user's workspace and state the path first.
• Do not expose the key or database to any network service unless the user explicitly requests a local-only read-only web app and accepts the constraints (localhost binding, token auth, no public exposure).

Resources

• scripts/decrypt_wechat_dat.py — offline XOR .dat image decoder (JPG/PNG/GIF/BMP auto-detect).
• references/setup.md — one-time install + init + command quick reference (from source build on Windows).
• references/PROMPTS.md — ready-to-use prompt templates for the user and the agent, plus few-shot examples.