WeChat local history
Operate only on local WeChat data the user is authorized to access. Keep keys, decrypted databases, voice caches, and exports local. Never print a raw key or include one in chat, logs, commands, or reports.
Resolve the runtime
Use the directory containing this SKILL.md as SKILL_DIR; never assume a fixed installation path.
- macOS: prefer
$SKILL_DIR/.venv/bin/python, otherwise python3.
- Windows: prefer
$SKILL_DIR\.venv\Scripts\python.exe, otherwise python.
Before reading chat data, run the read-only diagnostic:
"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/common/doctor.py" --json
On Windows, use the equivalent venv Python path. Interpret fail as blocking and warn as optional/degraded:
key or database failure: read the matching platform reference below.mcp warning: use the CLI fallback now; run platform setup only when MCP registration is needed.voice-backend warning: ordinary export works; install the optional platform voice stack only for transcription.voice-model warning: ordinary export still works. Do not download the model without user approval.
Route the request
| Intent |
Preferred action |
| List chats or groups |
wechat_list_chats |
| Read one chat |
wechat_read_chat |
| Search all chats |
wechat_search_messages |
| Review recent activity |
wechat_recent_messages |
| Summarize recent chats and action items |
wechat_chat_summary |
| Review pats, recalls, group changes, payments, or calls |
wechat_system_events; filter with a stable code or Chinese label |
| Review shared music, videos, Channels, mini programs, files, or links |
Use normal read/search/summary tools; inspect the structured app object in CLI JSON when exact metadata matters |
| Statistics, media, or a received document |
CLI stats, media, or openfile |
| Export history or transcribe voice |
Read references/export-transcription.md |
| Missing chats, a missing shard, or a corrupted database |
Read references/db-repair.md |
| macOS setup, key failure, or WeChat update |
Read references/macos.md |
| Windows setup, key failure, or WeChat update |
Read references/windows.md |
MCP is a thin optional facade. If it is unavailable, use the same logic through scripts/common/query.py and request JSON:
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" list --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" read CONTACT -d 7 -n 50 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" search KEYWORD -d 30 -n 50 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" recent -d 3 -n 100 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" summary -d 3 --json
"$PYTHON" "$SKILL_DIR/scripts/common/query.py" events -e pat -d 30 -n 100 --json
[我] means the account owner; [对方] means the peer. If contact matching is ambiguous, show the candidates and ask the user to choose; do not guess. Keep time windows and limits proportional to the request, and do not dump full history unless explicitly requested.
Operational invariants
- Raw keys are 64 hexadecimal characters and are device-specific. macOS and Windows keys for the same account are not interchangeable.
- macOS queries encrypted databases in place through SQLCipher, always read-only.
- Windows first creates a local plaintext mirror under
decrypted/, then queries it read-only. Treat that mirror as sensitive.
- WeChat updates may invalidate extraction assumptions or require a new key. Run
doctor.py before repeating extraction.
- Voice transcription is offline after the model is cached. A first large-v3 download is about 3 GB and always requires user approval.
- Type-49 app messages are parsed locally. Preserve their structured
app metadata when answering questions about titles, creators, sources, URLs, files, mini programs, or Channels; unknown subtypes may still contain useful fields.
- Setup migrates only missing private files from legacy installs. Switching an existing user-skill link requires the explicit platform upgrade flag and leaves a recoverable backup.
- A damaged shard is quarantined into
<name>.db.factory/ and is usually recoverable page by page. Never repair a live database in place: rebuild into a copy, verify it, and back up before restoring anything.
1---2name: wechat-decrypt3description: Read, search, summarize, export, and transcribe a user's own local WeChat 4.x history on macOS or Windows; diagnose setup and re-extract the device key after a WeChat update. Use for WeChat messages, chats, contacts, and local archives. Do not use for remote accounts or devices the user is not authorized to access.4---56# WeChat local history78Operate only on local WeChat data the user is authorized to access. Keep keys, decrypted databases, voice caches, and exports local. Never print a raw key or include one in chat, logs, commands, or reports.910## Resolve the runtime1112Use the directory containing this `SKILL.md` as `SKILL_DIR`; never assume a fixed installation path.1314- macOS: prefer `$SKILL_DIR/.venv/bin/python`, otherwise `python3`.15- Windows: prefer `$SKILL_DIR\.venv\Scripts\python.exe`, otherwise `python`.1617Before reading chat data, run the read-only diagnostic:1819```bash20"$SKILL_DIR/.venv/bin/python" "$SKILL_DIR/scripts/common/doctor.py" --json21```2223On Windows, use the equivalent venv Python path. Interpret `fail` as blocking and `warn` as optional/degraded:2425- `key` or `database` failure: read the matching platform reference below.26- `mcp` warning: use the CLI fallback now; run platform setup only when MCP registration is needed.27- `voice-backend` warning: ordinary export works; install the optional platform voice stack only for transcription.28- `voice-model` warning: ordinary export still works. Do not download the model without user approval.2930## Route the request3132| Intent | Preferred action |33|---|---|34| List chats or groups | `wechat_list_chats` |35| Read one chat | `wechat_read_chat` |36| Search all chats | `wechat_search_messages` |37| Review recent activity | `wechat_recent_messages` |38| Summarize recent chats and action items | `wechat_chat_summary` |39| Review pats, recalls, group changes, payments, or calls | `wechat_system_events`; filter with a stable code or Chinese label |40| Review shared music, videos, Channels, mini programs, files, or links | Use normal read/search/summary tools; inspect the structured `app` object in CLI JSON when exact metadata matters |41| Statistics, media, or a received document | CLI `stats`, `media`, or `openfile` |42| Export history or transcribe voice | Read [references/export-transcription.md](references/export-transcription.md) |43| Missing chats, a missing shard, or a corrupted database | Read [references/db-repair.md](references/db-repair.md) |44| macOS setup, key failure, or WeChat update | Read [references/macos.md](references/macos.md) |45| Windows setup, key failure, or WeChat update | Read [references/windows.md](references/windows.md) |4647MCP is a thin optional facade. If it is unavailable, use the same logic through `scripts/common/query.py` and request JSON:4849```bash50"$PYTHON" "$SKILL_DIR/scripts/common/query.py" list --json51"$PYTHON" "$SKILL_DIR/scripts/common/query.py" read CONTACT -d 7 -n 50 --json52"$PYTHON" "$SKILL_DIR/scripts/common/query.py" search KEYWORD -d 30 -n 50 --json53"$PYTHON" "$SKILL_DIR/scripts/common/query.py" recent -d 3 -n 100 --json54"$PYTHON" "$SKILL_DIR/scripts/common/query.py" summary -d 3 --json55"$PYTHON" "$SKILL_DIR/scripts/common/query.py" events -e pat -d 30 -n 100 --json56```5758`[我]` means the account owner; `[对方]` means the peer. If contact matching is ambiguous, show the candidates and ask the user to choose; do not guess. Keep time windows and limits proportional to the request, and do not dump full history unless explicitly requested.5960## Operational invariants6162- Raw keys are 64 hexadecimal characters and are device-specific. macOS and Windows keys for the same account are not interchangeable.63- macOS queries encrypted databases in place through SQLCipher, always read-only.64- Windows first creates a local plaintext mirror under `decrypted/`, then queries it read-only. Treat that mirror as sensitive.65- WeChat updates may invalidate extraction assumptions or require a new key. Run `doctor.py` before repeating extraction.66- Voice transcription is offline after the model is cached. A first large-v3 download is about 3 GB and always requires user approval.67- Type-49 app messages are parsed locally. Preserve their structured `app` metadata when answering questions about titles, creators, sources, URLs, files, mini programs, or Channels; unknown subtypes may still contain useful fields.68- Setup migrates only missing private files from legacy installs. Switching an existing user-skill link requires the explicit platform upgrade flag and leaves a recoverable backup.69- A damaged shard is quarantined into `<name>.db.factory/` and is usually recoverable page by page. Never repair a live database in place: rebuild into a copy, verify it, and back up before restoring anything.
tzwkb