mcncarl · zhouzheseno-collab · Aug 18, 2026 · Aug 20, 2026 · Aug 20, 2026
diff --git a/.github/workflows/windows-wechat-vault.yml b/.github/workflows/windows-wechat-vault.yml
@@ -0,0 +1,46 @@
+name: Windows WeChat vault
+
+on:
+  push:
+    paths:
+      - 'yichen-wechat-windows-vault/**'
+      - '.github/workflows/windows-wechat-vault.yml'
+  pull_request:
+    paths:
+      - 'yichen-wechat-windows-vault/**'
+      - '.github/workflows/windows-wechat-vault.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: windows-wechat-vault-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: windows-2025
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.11'
+          cache: pip
+          cache-dependency-path: yichen-wechat-windows-vault/requirements-dev.txt
+
+      - name: Install pinned dependencies
+        run: python -m pip install --requirement yichen-wechat-windows-vault/requirements-dev.txt
+
+      - name: Run synthetic tests
+        run: python -m pytest yichen-wechat-windows-vault/tests -q
+
+      - name: Run dependency self-test
+        run: python yichen-wechat-windows-vault/scripts/self_test.py
+
+      - name: Verify environment
+        run: python -m pip check
diff --git a/README.md b/README.md
@@ -88,6 +88,15 @@ WeChat digital-asset assistant for macOS:
 - Requirements: macOS, WeChat Mac 4.x, Python 3.9+, `pycryptodome`, `zstandard`
 - See [yichen-wechat-local-vault/README.md](./yichen-wechat-local-vault/README.md) for full documentation
 
+### 4W) `yichen-wechat-windows-vault`
+Independent Windows counterpart to the Mac local-vault Skill:
+- Uses finite, exact-version key capture and page-HMAC-verified SQLCipher decryption
+- Supports sessions, contacts, members, history, search, statistics, exports, Favorites, Moments, and digest-source packs
+- Stores verified keys with Windows DPAPI and keeps all decrypted data in a private local vault
+- Requires an explicit database path and never changes Codex, Hermes, MCP, startup, or WeChat configuration
+- Requirements: Windows 10/11, WeChat 4.x with a supported profile, Python 3.11+, `frida`, `pycryptodome`, `zstandard`
+- See [yichen-wechat-windows-vault/README.md](./yichen-wechat-windows-vault/README.md) for full documentation
+
 ### 5–6) Social fetchers integrated into `yichen-content-archive`
 The former standalone Douyin and Xiaohongshu fetchers now have one source of truth:
 - `douyin_download.py` reads metadata or downloads a known Douyin video through Playwright interception
@@ -261,6 +270,12 @@ yichen-skills/
 │     ├─ list_contacts.py
 │     ├─ search_sns.py
 │     └─ wechat_digest.py
+├─ yichen-wechat-windows-vault/
+│  ├─ SKILL.md
+│  ├─ README.md
+│  ├─ references/
+│  ├─ scripts/
+│  └─ tests/
 ├─ yichen-mac-wechat-dual-open/
 │  ├─ SKILL.md
 │  ├─ scripts/
@@ -368,6 +383,7 @@ yichen-skills/
 - Dependencies:
   - X article drafts: `pip install playwright pycryptodome && python3 -m playwright install chromium`
   - WeChat local vault: `pip install pycryptodome zstandard`
+  - Windows WeChat vault: run `yichen-wechat-windows-vault/scripts/setup.ps1`
   - WeChat dual open: `pip install Pillow`
   - Content archive (Douyin): `pip install playwright requests && python3 -m playwright install chromium`
   - Content archive (Xiaohongshu): `pip install requests`
@@ -392,6 +408,7 @@ Keep directory names unchanged:
 - `yichen-summary`
 - `yichen-x-article-draft-uploader`
 - `yichen-wechat-local-vault`
+- `yichen-wechat-windows-vault`
 - `yichen-mac-wechat-dual-open`
 - `yichen-volc-asr`
 - `yichen-video-content`

diff --git a/README.zh.md b/README.zh.md
@@ -88,6 +88,15 @@ Mac 微信双开——无需第三方工具，一条命令搞定：
 - 依赖：macOS、微信 Mac 4.x、Python 3.9+、`pycryptodome`、`zstandard`
 - 详细文档见 [yichen-wechat-local-vault/README.md](./yichen-wechat-local-vault/README.md)
 
+### 4W) `yichen-wechat-windows-vault`
+Mac 本地 Vault Skill 的独立 Windows 对应实现：
+- 采用限时、精确版本密钥捕获和逐页 HMAC 验证的 SQLCipher 解密
+- 支持会话、联系人、群成员、历史、搜索、统计、导出、收藏、朋友圈和摘要素材包
+- 使用 Windows DPAPI 保存已验证密钥，明文数据只进入本机私有 Vault
+- 必须显式指定数据库路径，不修改 Codex、Hermes、MCP、启动项或微信配置
+- 依赖：Windows 10/11、受支持的微信 4.x、Python 3.11+、`frida`、`pycryptodome`、`zstandard`
+- 详细文档见 [yichen-wechat-windows-vault/README.md](./yichen-wechat-windows-vault/README.md)
+
 ### 5–6) 已融合进 `yichen-content-archive` 的社交平台抓取器
 原先独立的抖音和小红书抓取器现在只保留一个事实源：
 - `douyin_download.py` 通过 Playwright 拦截读取元数据或下载已知抖音视频
@@ -260,6 +269,12 @@ yichen-skills/
 │     ├─ list_contacts.py
 │     ├─ search_sns.py
 │     └─ wechat_digest.py
+├─ yichen-wechat-windows-vault/
+│  ├─ SKILL.md
+│  ├─ README.md
+│  ├─ references/
+│  ├─ scripts/
+│  └─ tests/
 ├─ yichen-mac-wechat-dual-open/
 │  ├─ SKILL.md
 │  ├─ scripts/
@@ -367,6 +382,7 @@ yichen-skills/
 - 依赖：
   - X 文章草稿：`pip install playwright pycryptodome && python3 -m playwright install chromium`
   - 微信本地解析：`pip install pycryptodome zstandard`
+  - Windows 微信本地 Vault：运行 `yichen-wechat-windows-vault/scripts/setup.ps1`
   - 微信双开：`pip install Pillow`
   - 内容归档（抖音）：`pip install playwright requests && python3 -m playwright install chromium`
   - 内容归档（小红书）：`pip install requests`
@@ -391,6 +407,7 @@ yichen-skills/
 - `yichen-summary`
 - `yichen-x-article-draft-uploader`
 - `yichen-wechat-local-vault`
+- `yichen-wechat-windows-vault`
 - `yichen-mac-wechat-dual-open`
 - `yichen-volc-asr`
 - `yichen-video-content`

diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
@@ -127,6 +127,22 @@ This repository references and adapts ideas/workflows from external projects.
   - The protocol and implementation in this repository have been adapted for this Skill family and are not represented as an official upstream release.
   - The upstream copyright and complete MIT license text are preserved in the local license copy above.
 
+## 11) Windows WeChat vault runtime and protocol references
+
+- Usage in this repo: `yichen-wechat-windows-vault`.
+- Runtime dependencies:
+  - Frida Python bindings 17.15.4, wxWindows Library Licence 3.1.
+  - PyCryptodome 3.23.0, BSD / public-domain components.
+  - python-zstandard 0.23.0, BSD-3-Clause.
+- Reference-only sources:
+  - SQLCipher official source and verification utility for public page-layout and HMAC behavior.
+  - OpenSSL 1.1.1 source for identification of the public `PKCS5_PBKDF2_HMAC` function structure.
+  - Frida official JavaScript API documentation for finite `Interceptor.attach` usage.
+- What was copied:
+  - No third-party source is vendored in this Skill.
+  - The Windows process adapter, exact-version profile, DPAPI store, page verifier, schema queries, and synthetic tests are independently implemented.
+- Full dependency links and scope notes are recorded in `yichen-wechat-windows-vault/THIRD_PARTY_NOTICES.md` and `PROVENANCE.md`.
+
 ## Notes
 
 - This repository maintains its own license (`LICENSE`) for original contributions. It is personal-learning and non-commercial only.

diff --git a/docs/superpowers/specs/2026-08-18-windows-wechat-vault-design.md b/docs/superpowers/specs/2026-08-18-windows-wechat-vault-design.md
@@ -0,0 +1,53 @@
+# Windows WeChat Vault Skill Design
+
+## Goal
+
+Publish the supplied Windows WeChat local-vault skill in `mcncarl/yichen-skills` without altering the maintained macOS vault or exposing personal data.
+
+## Scope
+
+- Add a new, self-contained `yichen-wechat-windows-vault/` skill directory from the supplied v0.3.0 archive.
+- Preserve the archive's Windows-only implementation, privacy rules, compatibility reference, MCP configuration, and self-test.
+- Add concise English and Chinese entries to the repository indexes so users can discover the Windows skill and its OS boundary.
+- Add the new directory to the README project trees and the documented stable directory-name lists.
+
+## Deliberate boundaries
+
+- Do not merge this implementation into `yichen-wechat-local-vault`; that directory is macOS-only and uses a different database format, key extraction flow, filesystem layout, and dependencies.
+- Do not change existing macOS behavior or installation guidance.
+- Do not include keys, live databases, decrypted exports, media caches, credentials, user paths, or chat content.
+- Do not claim support for an unlisted WeChat build; the bundled compatibility checks remain authoritative.
+
+## Layout
+
+```text
+yichen-wechat-windows-vault/
+├─ SKILL.md
+├─ README.md
+├─ agents/openai.yaml
+├─ references/
+│  ├─ compatibility.md
+│  └─ profile-fixtures.json
+└─ scripts/
+   ├─ setup.ps1
+   ├─ uninstall.ps1
+   ├─ capture_keys.py
+   ├─ decrypt_databases.py
+   ├─ refresh_vault.py
+   ├─ diagnose.py
+   ├─ self_test.py
+   ├─ vault_cli.py
+   ├─ vault_common.py
+   ├─ wechat_media.py
+   ├─ decode_silk.cjs
+   ├─ gateway_query.py
+   ├─ mcp_server.py
+   └─ requirements.txt
+```
+
+## Validation
+
+1. Check that the imported file set matches the archive and that no tracked file matches repository secret/database/media exclusions.
+2. Run Python syntax compilation for the bundled Windows scripts on the current host; this checks syntax only and does not attach to WeChat or read local user data.
+3. Run the archive's profile-fixture validation in an isolated import context; full `self_test.py` is intentionally not expected to pass on macOS because it validates Windows-only dependencies and paths.
+4. Review the final diff and README links before committing and opening the PR.
diff --git a/yichen-wechat-windows-vault/PROVENANCE.md b/yichen-wechat-windows-vault/PROVENANCE.md
@@ -0,0 +1,34 @@
+# Provenance
+
+## Relationship to the Mac Skill
+
+This Skill follows the existing `yichen-wechat-local-vault` user-facing concepts: local private vault, sessions, contacts, members, history, search, statistics, export, Favorites, Moments, and digest-source generation. That same-repository Skill was used as the functional and interface reference.
+
+The following Windows components were implemented independently for this contribution:
+
+- exact Windows PE fingerprint and prologue validation;
+- finite Frida attachment to one explicitly selected Weixin process;
+- derived-key candidate handling and page-HMAC verification;
+- Windows DPAPI key storage;
+- snapshot-based incremental decryption;
+- Windows WeChat 4.x contact, session, message-shard, Favorites, Moments, and resource-index adapters;
+- synthetic fixtures and automated tests.
+
+## Excluded sources
+
+No source code, implementation details, binary, package, fork, mirror, or generated output from wx-cli, wxcli, jackwener, or related projects was consulted, copied, adapted, or invoked. The implementation does not detect or import those packages at runtime.
+
+No code from the previously closed Windows v0.1/v0.3 contribution was reused. Existing private vault tooling was used only as a black-box source of schema availability and query-count comparisons; its source was not used to implement this Skill.
+
+## Independent compatibility derivation
+
+The supported Windows profile was derived from the user's installed `Weixin.dll` by:
+
+1. hashing the complete DLL;
+2. reading PE exception-function boundaries;
+3. locating an embedded OpenSSL source assertion reference for `crypto/evp/p5_crpt2.c`;
+4. identifying the adjacent x64 function by the documented `PKCS5_PBKDF2_HMAC` argument and loop structure;
+5. recording and checking the exact function prologue;
+6. accepting captured results only when the SQLCipher page HMAC validates against an explicit local database.
+
+Official OpenSSL, SQLCipher, and Frida documentation were used as protocol and API references. No third-party implementation was copied into the repository.
diff --git a/yichen-wechat-windows-vault/README.md b/yichen-wechat-windows-vault/README.md
@@ -0,0 +1,47 @@
+# Yichen WeChat Windows Vault
+
+An independent Windows implementation of the repository's WeChat local-vault experience. It supports finite, version-pinned key capture; verified SQLCipher decryption; incremental private-vault refresh; and read-only queries for sessions, contacts, group members, history, search, statistics, exports, Favorites, Moments, and message-resource metadata.
+
+## Requirements
+
+- Windows 10 or 11
+- Python 3.11+
+- Desktop WeChat 4.x with an exact supported profile
+- Data belonging to the current user, with explicit authorization
+
+## Install
+
+```powershell
+Set-Location yichen-wechat-windows-vault
+.\scripts\setup.ps1
+```
+
+This creates an isolated environment under `%LOCALAPPDATA%\yichen-wechat-windows-vault`. It does not modify Codex, Hermes, MCP, WeChat, logon tasks, or system configuration.
+
+## Diagnose, capture, and refresh
+
+Always provide the database root explicitly:
+
+```powershell
+$Python = Join-Path $env:LOCALAPPDATA "yichen-wechat-windows-vault\venv\Scripts\python.exe"
+& $Python .\scripts\diagnose.py --db-root "C:\explicit\path\to\db_storage"
+.\scripts\capture_keys_on_demand.ps1 -DbRoot "C:\explicit\path\to\db_storage" -Duration 20
+```
+
+Keep WeChat running and open the needed area during the finite capture window. If no new database derivation occurs, the command may correctly report zero captured candidates; retry during a normal WeChat restart or while opening a database-backed feature. Unknown DLL hashes fail closed.
+
+## Query
+
+```powershell
+$Root = Join-Path $env:LOCALAPPDATA "yichen-wechat-windows-vault\vault\decrypted"
+& $Python .\scripts\vault_cli.py --decrypted-root $Root sessions --limit 20
+& $Python .\scripts\vault_cli.py --decrypted-root $Root history "chat name" --limit 50
+& $Python .\scripts\vault_cli.py --decrypted-root $Root search "keyword" --start-time 2026-08-01
+& $Python .\scripts\vault_cli.py --decrypted-root $Root stats "chat name"
+```
+
+Run `vault_cli.py --help` and the subcommand help for all options. Exports must point to a deliberate private destination.
+
+## Scope
+
+The Windows implementation keeps the Mac Skill's command-level concepts and interaction model. Its Windows process integration, version profile, DPAPI storage, database refresh, schema adapters, and tests were implemented independently. See [PROVENANCE.md](PROVENANCE.md) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
diff --git a/yichen-wechat-windows-vault/SKILL.md b/yichen-wechat-windows-vault/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: yichen-wechat-windows-vault
+description: Capture, decrypt, refresh, and query the current user's authorized local Windows WeChat 4.x vault. Use for Windows chat sessions, contacts, group members, history, search, statistics, exports, Favorites, Moments, or digest-source requests; key capture is finite and version-pinned.
+---
+
+# Yichen WeChat Windows Vault
+
+Operate only on the current user's authorized Windows WeChat data. Treat the live database tree as read-only and keep keys, decrypted databases, state, and exports out of repositories.
+
+## Workflow
+
+1. Require an explicit `db_storage` path. Do not search Documents, Desktop, OneDrive, or other user folders.
+2. Run `scripts/diagnose.py --db-root <path>` before capture.
+3. Run `scripts/setup.ps1` once when the isolated runtime is missing. It does not edit Codex, Hermes, MCP, startup, or WeChat configuration.
+4. Use `scripts/capture_keys_on_demand.ps1 -DbRoot <path> -Duration 20` only with authorization to attach to the user's own Weixin process. Keep the window finite. The wrapper selects exactly one process that has `Weixin.dll` loaded.
+5. Stop when the DLL fingerprint or function prologue is unknown. Read [references/compatibility.md](references/compatibility.md) before adding a profile.
+6. Query only the private decrypted copy with `scripts/vault_cli.py --decrypted-root <path> <command>`.
+
+Use bounded limits and explicit dates for large searches. Prefer `digest-source` for a reusable group-chat material pack and `export` for a direct transcript. Use `resources` only for metadata; this Skill does not decode images or transcribe voice.
+
+## Commands
+
+- `status`, `sessions`, `unread`, `new-messages`
+- `contacts`, `members`
+- `history`, `search`, `stats`
+- `favorites`, `moments`, `resources`
+- `export`, `digest-source`
+
+## Invariants
+
+- Never print, return, commit, or upload captured keys.
+- Accept a captured candidate only after SQLCipher page-HMAC verification.
+- Store verified keys with Windows DPAPI for the current user.
+- Never modify a live WeChat database or control the WeChat process.
+- Never create persistent hooks, watchers, services, or scheduled tasks.
+- Do not claim capture success when the result reports zero verified databases.
+- Do not commit private vault files, real chat data, account identifiers, or absolute personal paths.
+
+Read [references/privacy.md](references/privacy.md) when handling real data or exports.
diff --git a/yichen-wechat-windows-vault/THIRD_PARTY_NOTICES.md b/yichen-wechat-windows-vault/THIRD_PARTY_NOTICES.md
@@ -0,0 +1,16 @@
+# Third-Party Notices
+
+Runtime dependencies are pinned in `requirements.txt` and installed into an isolated local environment.
+
+| Dependency | Version | Purpose | License / source |
+|---|---:|---|---|
+| Frida Python bindings | 17.15.4 | Finite local process instrumentation | wxWindows Library Licence 3.1; https://github.com/frida/frida |
+| PyCryptodome | 3.23.0 | AES-256-CBC operations | BSD / public-domain components; https://github.com/Legrandin/pycryptodome |
+| python-zstandard | 0.23.0 | WeChat compressed message decoding | BSD-3-Clause; https://github.com/indygreg/python-zstandard |
+| pytest | 8.4.1 | Development tests only | MIT; https://github.com/pytest-dev/pytest |
+
+Reference-only specifications and source navigation:
+
+- SQLCipher official source and verification utility (BSD-3-Clause) were consulted for page layout, HMAC salt masking, key derivation, and little-endian page numbering. No SQLCipher source is vendored.
+- OpenSSL 1.1.1 source was consulted to identify the public `PKCS5_PBKDF2_HMAC` function structure in a local binary. No OpenSSL source is vendored.
+- The same-repository Mac Skill was consulted only for the product interface and functional vocabulary under this repository's license.
diff --git a/yichen-wechat-windows-vault/agents/openai.yaml b/yichen-wechat-windows-vault/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Yichen WeChat Windows Vault"
+  short_description: "Windows WeChat local vault capture and analysis"
+  default_prompt: "Use $yichen-wechat-windows-vault to refresh and query my authorized local Windows WeChat vault."
diff --git a/yichen-wechat-windows-vault/references/compatibility.md b/yichen-wechat-windows-vault/references/compatibility.md
@@ -0,0 +1,22 @@
+# Windows compatibility profiles
+
+Key capture is supported only when every profile check succeeds.
+
+| WeChat version | Weixin.dll SHA-256 | PBKDF2 RVA | Required prologue |
+|---|---|---:|---|
+| 4.1.10.53 | `AB35CFBD7AA9514EC0530747CFC59CAE9DEB0DD46D953548D3CF01919C62A577` | `0x68831B0` | `40535556574154415541564157B898000000E82955F4FF482BE0488B052FD197` |
+
+The runtime table is `scripts/profiles.json`. The profile pins the complete DLL hash and the bytes at the target RVA. A matching version label alone is insufficient.
+
+## Adding a version
+
+Do not guess or copy an offset from another build. For each new DLL:
+
+1. record the complete SHA-256 and file version;
+2. independently identify the PBKDF2 function within that exact PE image;
+3. record at least 16 bytes of its prologue;
+4. validate captured 32-byte outputs against multiple encrypted database first-page HMACs;
+5. add a synthetic regression and document the derivation evidence;
+6. keep unknown builds fail-closed until review is complete.
+
+The current profile was derived independently from PE metadata, embedded OpenSSL source references, x64 calling convention, and the OpenSSL PBKDF2 control flow. It was not obtained from an older Windows implementation.