SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsyichen-wechat-local-vault

yichen-wechat-local-vault

General & other

View repository

Updated 10-16 00:22

About this skill

WeChat Local Parsing Vault

This skill is positioned as a "WeChat local digital asset vault + local query and analysis console." By default, it only reads the local database and local processes, and does not click the WeChat interface; unless the user explicitly permits it, it does not operate the WeChat UI. By default, it only handles the first official 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: archive by group, continue from the last summary, summary material package, group member profile directory, history index, image description extension points, and the safe habit of "for large batches, write files first, then analyze."

Privacy boundaries

  • Do not output keys, full salts, wxids, or raw chat database contents in replies or logs, unless the user explicitly requests display.
  • Keys, configuration, plaintext databases, manifests, incremental states, and export directories are all managed by local configuration files; skill documentation must not include real absolute paths, wxids, contacts, or chat contents from any personal machine.
  • It is recommended to put keys and plaintext databases in a local private application data directory, and put readable reports in a user-selected export directory; paths only need to be described with placeholders or configuration fields.
  • Do not copy plaintext databases to the project workspace, desktop, cloud storage directories, or chat replies; the workspace should only contain export reports explicitly requested by the user.

First determine the data source

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

Mac mode: automatic mode selection

Choose the minimum necessary action based on the user's instruction:

  1. If the user says "first time using it, can't unlock it, the 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 perform incremental decryption of 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 already-decrypted database; if the key is missing, then supplement by capturing it.
  6. When the user explicitly says "group chat summary, group chat highlights, daily report, review, continue from last time", prioritize using vault_cli.py digest-source to generate a material pack, 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, already-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 already-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 pack

When the user wants "group chat highlights, daily report, summarize the group chat, see what this group has been chatting 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/: snarky version profiles, must be 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, speech statistics, and path information.
  • sources/*.md: a material draft for manual reading and writing.

The material pack 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 products 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 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 first-time configuration, changing devices, key changes after a WeChat upgrade, or 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 attempt reuse.
  3. Only when reuse fails or key databases are missing, run key capture.
  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 recently added 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 written only 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 what to reply next".

  1. If the user gives a remark/nickname, use export_chat.py --contact。
  2. If the user gives 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 scripts according to the user's goal.
  4. Do not display the full original text by default; only provide the complete 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 do a full crawl. Output to the export directory configured by the user.

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 pack 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. Output structure preferably adopts: title, message statistics, speaker ranking, opening overview, member profiles, categorized body, unresolved 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 description in it for the summary. Otherwise you can only write "the image content is invisible; based on context, infer that a discussion around an image happened here", do not fabricate the scene.
  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 quoted is enough; avoid pasting the entire database content into the chat.
  • Clearly distinguish "decrypted plaintext database", "readable export report", and "key configuration".
  • Each time 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 highlight material packs.

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

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

  • scripts/export_chat.py: Export complete/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 assistance.

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. For multi-account installations, the default account must be explicitly configured, 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 is configured independently, with its own keys, snapshots, incremental state, and export directory, without temporarily overriding the global configuration to switch accounts. The Windows snapshot route does not trigger a Mac refresh.