SuperAPI AI Directory

yichen-wechat-local-vault

General & other

View repository

Updated 10-16 02:36

About this skill

WeChat Local Parsing Vault

The positioning of this skill is "WeChat local digital asset vault + local query and analysis console". By default it only reads the local machine's databases and local processes, and does not click the WeChat interface; unless the user explicitly allows it, it does not operate the WeChat UI. By default it only handles the official first WeChat container com.tencent.xinWeChat, and does not handle dual-instance/second WeChat containers.

This version absorbs the advantages of two types of external tools:

  • WeChat CLI style: unified command entry point, JSON default output, recent sessions, history, global search, contact details, group members, statistics, export, favorites, unread, and incremental new messages.
  • Baoyu group chat summary workflow: archiving by group, continuing from the last summary, summary material packages, group member profile directories, history indexes, image description extension points, and the safe habit of "for large batches, write files first and then analyze".

Privacy boundaries

  • Do not output keys, full salt, wxid, or raw chat database content in replies or logs, unless the user explicitly asks for it to be displayed.
  • Keys, configuration, plaintext databases, manifests, incremental state, and export directories are all managed by local configuration files; skill documentation must not contain real absolute paths, wxid, contacts, or chat content from any personal machine.
  • It is recommended to put keys and plaintext databases in the local private application data directory, and put readable reports in a user-chosen export directory; paths can be described with placeholders or configuration fields.
  • Do not copy plaintext databases into the project workspace, desktop, cloud drive directories, or chat replies; the workspace should only contain export reports explicitly requested by the user.

First determine the data source

  • Current Mac account / local machine chat / incremental refresh: follow the Mac workflow below and the existing vault_cli.py commands.
  • Windows offline plaintext snapshot provided by the user: read Windows snapshot mode, use vault_cli.py snapshot --snapshot <目录> .... First validate, then chats select the exact chat_id, and finally query or export. No separate Windows Skill installation is required.
  • Windows mode only supports validate、chats、history、search and Markdown export; it does not support key extraction, decryption, incremental refresh, or parsing of Moments/favorites body content. If the snapshot is missing, the schema is incompatible, or there are WAL/SHM files, stop and explain the gap; do not attempt the Mac workflow or automatically fill in the snapshot.
  • The snapshot source system is determined by the information provided by the user, not by guessing based on whether the current system is Mac or Windows. Authorized Windows plaintext snapshots can be analyzed on a Mac, but real Windows WeChat version compatibility remains experimental.

Mac mode: automatic mode selection

Select the minimum necessary action based on the user's instructions:

  1. If the user says "using it for the first time, cannot decrypt, key is gone, decrypt everything, full rebuild": follow the full route.
  2. If the user says "continue, update it, incremental, recent, today, new messages": follow the incremental route.
  3. If the user names a contact/group chat/session ID: export only that one session; if necessary, first incrementally decrypt the message database.
  4. User gives a time range: export or analyze only within that time range.
  5. User asks about Moments/Favorites: only read the corresponding decrypted database; if the key is missing, capture it again.
  6. When the user explicitly says "group chat summary, group chat highlights, daily report, retrospective, continue from last time", prioritize using vault_cli.py digest-source to generate the material package, then write the briefing based on the materials; do not explain the entire skill as a summarization tool.
  7. When the user requests not to operate the WeChat interface, only use --match-only, saved keys, decrypted databases, or local database files; do not launch Computer Use.

Unified query entry point

For daily queries, prioritize using scripts/vault_cli.py. Mac commands only read the decrypted vault; Windows snapshots use the snapshot subcommand, see Windows snapshot mode. The query entry point does not capture keys and does not touch the WeChat UI.

python3 {{SKILL_DIR}}/scripts/vault_cli.py status --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py sessions --limit 20 --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py unread --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py new-messages --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py contacts --query "关键词" --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py members "群名" --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py history "联系人或群名" --start-time "2026-05-01" --end-time "2026-05-14" --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py search "关键词" --chat "群名" --type link --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py stats "群名" --start-time "2026-05-01" --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py export "群名" --format markdown --output ./chat.md
python3 {{SKILL_DIR}}/scripts/vault_cli.py favorites --type article --query "关键词" --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py moments --name "联系人" --start "2026-05-01" --format text

Message type filtering supports:text、image、voice、video、sticker、location、link、file、call、system。

Group chat summary material package

When the user wants "group chat highlights, daily report, summarize the group chat, see what this group has been talking about recently, continue from last time":

python3 {{SKILL_DIR}}/scripts/vault_cli.py digest-source "群名" --start "2026-05-01" --end "2026-05-14" --format text
python3 {{SKILL_DIR}}/scripts/vault_cli.py digest-source "群名" --since-last --data-root ~/Documents/wechat-digests --format text

Output will land in {data_root}/{group_id}-{group_name}/sources/, and create:

  • profiles/: standard version group member profiles.
  • profiles-roast/: sharp-tongued version profiles, must be kept separate from the standard version.
  • imgs/: image description extension point, format is {message_id}.txt, one line describes one image.
  • sources/*.json: machine-readable message materials, speaking statistics, and path information.
  • sources/*.md: a material draft for human reading and writing.

The material package does not automatically update history.json. Only after the final summary is written and confirmed should the summary history be updated, to avoid half-finished work polluting the "continue from last time" anchor.

Common commands

View which databases exist on this machine, without launching WeChat:

python3 {{SKILL_DIR}}/scripts/extract_keys.py --list-dbs

Match keys using existing capture logs, without launching WeChat:

python3 {{SKILL_DIR}}/scripts/extract_keys.py --match-only --targets all --reuse-log

First full key capture. Use only when new keys need to be captured; do not touch the second WeChat:

python3 {{SKILL_DIR}}/scripts/extract_keys.py --targets all --duration 240

Full decryption to the private vault:

python3 {{SKILL_DIR}}/scripts/decrypt_all_dbs.py --mode full

Daily incremental refresh. Only skip unchanged databases, do not reprocess all content:

python3 {{SKILL_DIR}}/scripts/decrypt_all_dbs.py --mode incremental

Export the complete chat with a contact:

python3 {{SKILL_DIR}}/scripts/export_chat.py --contact "联系人备注" --mode full

Export new chats with a contact:

python3 {{SKILL_DIR}}/scripts/export_chat.py --contact "联系人备注" --mode incremental

Export by exact conversation ID and time range:

python3 {{SKILL_DIR}}/scripts/export_chat.py --chat-id "contact_username" --since "2025-01-01"

Old scripts can still be used for narrow tasks; if the user has not specified otherwise, prioritize using vault_cli.py。

Mac mode: workflow

Full route

Used for initial setup, changing devices, key changes after WeChat upgrades, and when the user explicitly requests a full rebuild.

  1. First run extract_keys.py --list-dbs to view local databases, without displaying sensitive salt.
  2. If ~/.config/wechat-keys.json already has a key, first use --match-only --targets all --reuse-log to try reusing it.
  3. Only run key capture when reuse fails or critical databases are missing.
  4. Run decrypt_all_dbs.py --mode full, plaintext databases are written to the private vault.
  5. Read the manifest to confirm the number of decrypted items and failed items.

Incremental route

Used for daily updates, continuing previous work, and analyzing only recent new content.

  1. Run decrypt_all_dbs.py --mode incremental。
  2. If the target is a contact/group chat, run export_chat.py --mode incremental。
  3. If there are no new messages, directly tell the user there is no new content.
  4. Incremental state is only written to the vault's state directory, not into the skill documentation.

Specified conversation analysis

Used for "analyze my chat with so-and-so", "export this session ID", "help me write the next reply".

  1. If the user provides a remark/nickname, use export_chat.py --contact。
  2. If the user provides a WeChat userName or session ID, use export_chat.py --chat-id。
  3. After exporting, read the report and analyze the relationship, tone, risks, and next-step talking points according to the user's goal.
  4. Do not display all original text by default; only provide the full timeline or report path when the user asks to "analyze carefully".

Moments/Favorites parsing

Prefer using the already decrypted sns/sns.db、favorite/favorite.db、message_resource.db. When the key is missing, only supplement the relevant database, do not scrape everything. Output to the user-configured export directory.

Group chat highlights/daily report route

  1. First run incremental decryption to ensure the plaintext vault is up to date.
  2. Use vault_cli.py contacts or sessions to parse the group name and confirm the unique group chat.
  3. Use digest-source to generate a material package by time range; for large groups or long time ranges, write to a file first, do not stuff hundreds or thousands of raw messages directly into the conversation.
  4. Read sources/*.md and the necessary sources/*.json, first outline the topic skeleton, then write the body.
  5. Prefer the following output structure: title, message statistics, speaker ranking, opening overview, group member profiles, categorized body, pending issues, fixed ending.
  6. When a sharp-tongued version is needed, it can be written separately based on the same material, but it must not make personal attacks, infer health/family/identity attributes, or use timestamps to infer sleep schedule or location.
  7. Image content is invisible by default; only if imgs/{message_id}.txt exists, use the descriptions in it for the summary. Otherwise only write "the image content is invisible; based on context, infer that a discussion around an image happened here", do not fabricate the picture.
  8. After the summary is confirmed, then update the history.json and history-digests.jsonlin the group directory; the user's request to "continue from last time" depends on these files.

Output principles

  • In replies, prioritize conclusions, file paths, and next-step suggestions; put the full original text in a Markdown file.
  • When private chats are involved, a small amount of necessary original text may be quoted; avoid pasting the entire database content into the chat.
  • Clearly distinguish "decrypted plaintext database", "readable export report", and "key configuration".
  • Whenever decryption is completed, state the save location and whether it contains plaintext privacy.

Existing scripts

  • scripts/snapshot_reader.py: Windows offline plaintext snapshot verification, query, and export backend.

  • scripts/wechat_schema.py: Message table names and field alias mappings shared by both backends.

  • scripts/vault_cli.py: Unified local query entry point; absorbs the common command forms of WeChat CLI, and adds Moments and summary material packages.

  • scripts/extract_keys.py: Local key capture, reuse, and matching.

  • scripts/decrypt_all_dbs.py: Full/incremental decryption, writes to the private vault, and generates a manifest.

  • scripts/export_chat.py: Export full/incremental chat records by contact, group chat, or session ID.

  • scripts/list_contacts.py: List contacts and group chats.

  • scripts/wechat_digest.py: Daily summary script, used only when the user explicitly requests a summary.

  • scripts/search_sns.py: Moments search helper.

Query freshness and account isolation

When a task depends on the latest messages, first verify the snapshot time of the corresponding account and perform an incremental refresh within the authorized scope; do not substitute old messages of the same type for the target. Multi-account installation must explicitly configure the default account, and the second account is selected only as specified by the user; the account number is not equal to the dual-instance container number. Each account has independent configuration, keys, snapshots, incremental state, and export directories, and the global configuration must not be temporarily overridden to switch accounts. The Windows snapshot route does not trigger a Mac refresh.