wechat · diff
git:20260828.9ff09d4 to git:20260829.8a7daa5
84 added, 22 removed. Audit A to A.
---
name: wechat
description: 在本地查询、导出微信 4.1+ 聊天记录为 AI 可读文本 —— 支持双人会话、群聊、以及按消息量排名的重要联系人扫描。当用户想导出、搜索或分析自己的微信聊天记录，或为其他 skill（前任.skill / 同事.skill 等）准备聊天记录原材料时使用。
---
# 微信聊天记录导出
在本地把微信 4.1+ 的聊天记录构建为可查询、可导出的 AI 可读文本。所有操作在本机运行，数据不离机。
所有功能都是密封二进制的子命令（`preflight` / `find_*` / `export_*` / `make_json` / `make_db`）。操作参考见 `reference/db-schema.md`。
## 前置检查（每次会话第一步）
```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" preflight
```
- 结尾打印 `READY` 和 `BUILT_DB_DIR=<路径>`：记住该路径，下文所有 `<BUILT_DB_DIR>` 都用它。
- 同时打印 `ARTIFACTS_DIR=<路径>`：记住该路径，下文所有 `<ARTIFACTS_DIR>` 都用它。
- - 同时打印 `BUILD_DB_CMD=<命令>`：Step 0 直接用它，路径/环境变量都已拼好。
- - 结尾打印 `NOT READY`：按脚本逐条提示处理（缺依赖 / 缺构建核心 / 需构建数据库），处理完重跑。
+ - 同时打印 `BUILD_DB_CMD=<命令>`：`make_db` 的命令内容，路径已拼好。**但不要直接跑**，见 Step 0b。
+ - 结尾打印 `NOT READY`：先确认 `<CORE_HOME>\solution.json` 是否存在 —— preflight **不检查**这个文件，
+ 直接跑 `BUILD_DB_CMD` 会以 `[ERROR] 方案文件不存在` 失败。不存在 → Step 0a；存在 → Step 0b。
+ 其余提示（缺依赖 / 缺构建核心）按脚本逐条处理，处理完重跑。
- ### Step 0：构建数据库 / 更新数据
+ ### Step 0：准备数据
- 首次必做；之后每次想拿到最新消息也要重跑。微信保持登录，**以管理员权限**运行 preflight 打印的 `BUILD_DB_CMD`。不要手写环境变量格式，直接复制 preflight 的输出。
+ 两个子步骤，**都需要管理员权限**，而且**都必须用下面的「提权新窗口」方式启动**：
- > 首次使用且无方案文件时，先生成方案清单。**微信必须已登录运行**，且以**管理员权限**执行：
- > ```powershell
- > $env:WECHAT_CORE_HOME = "<CORE_HOME>"
- > & "$env:CLAUDE_PLUGIN_ROOT\_core.exe" make_json
- > ```
- > 运行后**在微信里逐个点开聊天（新旧都开）、联系人、收藏、朋友圈并搜索**——每个库的
- > 数据准备只会在相关内容被打开时逐步覆盖，浏览得越全，抓到的库越全。它会实时打印 `[SOLUTION] <库名>`，
- > 覆盖够了或 180 秒后自动写出 `solution.json`（落在 `<CORE_HOME>`）。
- > `<CORE_HOME>` 用 preflight 打印的 `CORE_HOME=` 值；`solution.json` 与 `built_db/` 都落在这里。
- > Windows Defender 可能对 `make_json` 报警，需手动放行。
+ - `make_json` —— 生成方案清单 `solution.json`（首次、或方案失效时才需要）
+ - `make_db` —— 构建 / 更新数据库（首次必做；之后每次想拿到最新消息都要重跑）
+ 其余子命令（`preflight` / `find_*` / `export_*`）**都不需要**管理员权限，正常运行即可。
+
+ #### 为什么必须开新窗口
+
+ 不要在当前会话里直接跑 `make_json` / `make_db`：
+
+ - 两者都需要管理员权限，当前会话通常没有；
+ - 它们的输出在非终端环境下会被**完全缓冲**，你一个字节都读不到，看起来就是卡死；
+ - `make_json` **不会自己结束**，必须由用户在窗口里按 `Ctrl+C` 才写出 `solution.json`。
+
+ 正确做法：弹一个提权 PowerShell 窗口，用户点一下「是」，然后在那个窗口里看进度、自己按 `Ctrl+C`。
+
+ #### Step 0a —— 生成方案清单（`solution.json` 不存在时）
+
+ **微信必须已登录运行。** 先用自然语言告诉用户「接下来会弹出一个 UAC 提权提示，请点『是』」，再执行：
+
+ ```powershell
+ $inner = @'
+ $env:WECHAT_CORE_HOME='<CORE_HOME>'
+ & '<PLUGIN_ROOT>\_core.exe' make_json
+ '@
+ Start-Process powershell -Verb RunAs -ArgumentList '-NoExit','-NoProfile','-Command',$inner
+ ```
+
+ `<CORE_HOME>` / `<PLUGIN_ROOT>` 必须替换成 preflight 打印的**绝对路径**。新窗口不继承当前会话的
+ 环境变量，`$env:CLAUDE_PLUGIN_ROOT` 在里面是空的，**不要**照抄变量引用。
+
+ `Start-Process` 会立刻返回，这**不代表成功**。接着告诉用户：
+
+ > 弹出的窗口里会不断打印 `[SOLUTION] <库名>` 和 `已捕获 N/27`。请现在到微信里**逐个点开聊天
+ > （新旧都开）、通讯录、收藏、朋友圈，并用一次搜索** —— 每个库只有在相关内容被打开时才会被抓到。
+ > 等计数不再增长（至少要出现 `contact\contact.db` 和 `message\message_*.db`），
+ > 在那个窗口里按 **Ctrl+C**，就会写出 `solution.json`。
+
+ 然后**等用户确认已按下 Ctrl+C**，再检查文件确实生成：
+
+ ```powershell
+ Test-Path '<CORE_HOME>\solution.json'
+ ```
+
+ 若为 `False`：用户可能点了 UAC 的「否」，或还没按 Ctrl+C。问清楚再处理，不要盲目重跑。
+
+ #### Step 0b —— 构建 / 更新数据库
+
+ 同样开提权窗口（内容即 preflight 打印的 `BUILD_DB_CMD`）：
+
+ ```powershell
+ $inner = @'
+ $env:WECHAT_CORE_HOME='<CORE_HOME>'
+ & '<PLUGIN_ROOT>\_common.exe' make_db
+ '@
+ Start-Process powershell -Verb RunAs -ArgumentList '-NoExit','-NoProfile','-Command',$inner
+ ```
+
+ `make_db` 会自己跑完，**不需要** Ctrl+C。跑完后重跑 `preflight`，应打印 `READY`。
+
+ > Windows Defender 等杀毒软件可能对 `make_json` / `make_db` 报警，需要用户手动放行。
+
## 按意图选择流程
| 用户想要… | 用哪个流程 |
|---|---|
| 导出 / 搜索与某个人的双人聊天 | **A. 双人会话** |
| 导出 / 总结某个群 | **B. 群聊** |
| 知道"和谁聊得最多" / 重要联系人排名 | **C. 联系人扫描** |
导出结果若要做成规避微信折叠的中文总结，接着用 `wechat-summary` skill。
---
## A. 双人会话
### A1 — 查找联系人 + 生成 sender_map
```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" find_private <关键词> --built-db-dir "<BUILT_DB_DIR>"
```
输出：wxid、消息表名、各库消息量与日期范围、sender_map 推断结果（含采样消息），以及一条即用的 `export_private` 命令。
### A2 — 与用户核对 sender_map
find_private 会为每个库打印推断出的「用户 / 对方」及其样本消息。**用自然语言和用户确认**，例如：
> 我从消息内容推断：`my_id=2`（样本「晚点到」「在开会」）是你，`other_id=7`（样本「好的」「路上注意」）是对方。对吗？
- 用户确认 → 进入 A3。
- 用户说反了 → 编辑对应的 `<ARTIFACTS_DIR>\sender_map_<名字>.json`，把该库条目的 `my_id` 与 `other_id` 对调，再进入 A3。
### A3 — 运行导出命令
- stdout + stderr 必须一起重定向到文件，**绝不能让内容进入上下文窗口**：
+ stdout 与 stderr 必须**分别**重定向到文件，**绝不能让内容进入上下文窗口**：
```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" export_private `
--db <各库路径…> --table <Msg_...> --sender-map "<ARTIFACTS_DIR>\sender_map_<名字>.json" `
- > "<ARTIFACTS_DIR>\chat_<名字>.txt" 2>&1
+ > "<ARTIFACTS_DIR>\chat_<名字>.txt" 2> "<ARTIFACTS_DIR>\chat_<名字>.err.txt"
```
- 优先直接复制 `find_private` 打印的完整导出命令；其中已带绝对路径。
+ **不要用 `2>&1`。** Windows PowerShell 5.1 会把原生程序的 stderr 包装成 `NativeCommandError`
+ 错误记录写进聊天文件开头（`At line:1 char:1` / `+ CategoryInfo …`），让导出结果看起来像报错。
+ 分开重定向即可保持聊天文件干净，stderr 同样不进上下文。
+ > `find_private` 会打印一条「导出命令」：**参数部分可以复制，但开头的可执行文件路径不能用** ——
+ > 它指向 Nuitka onefile 的临时解包目录（`…\Temp\onefile_*\python.exe`），进程一退出就被删除，
+ > 照抄必定失败。开头一律换成 `& "$env:CLAUDE_PLUGIN_ROOT\_common.exe"`。
+
时间范围（默认全量）：`--days N` ｜ `--since YYYY-MM-DD` ｜ `--since … --until YYYY-MM-DD`。其中 `--until` **包含当天**。
---
## B. 群聊
群聊导出会自动处理发送者映射；少数无法识别的发送者会显示为 `【?】`。
### B1 — 查找群
```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" find_chatroom <关键词> --built-db-dir "<BUILT_DB_DIR>"
```
### B2 — 运行导出命令（默认最近 1 天）
```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" export_chatroom `
--db <单个库路径> --table <Msg_...> `
--contact-db "<BUILT_DB_DIR>\contact\contact.db" `
--id-map "<ARTIFACTS_DIR>\id_map_<群名>.json" `
- > "<ARTIFACTS_DIR>\chat_<群名>.txt" 2>&1
+ > "<ARTIFACTS_DIR>\chat_<群名>.txt" 2> "<ARTIFACTS_DIR>\chat_<群名>.err.txt"
```
范围：`--days N` ｜ `--since` ｜ `--until`。其中 `--until` **包含当天**。`--contact-db` 存在时自动生成 / 更新 id_map，后续导出可省略该参数。
---
## C. 联系人扫描
```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" find_contact <关键词> --built-db-dir "<BUILT_DB_DIR>"
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" export_contacts `
--contact-db "<BUILT_DB_DIR>\contact\contact.db" `
--msg-dbs "<BUILT_DB_DIR>\message\message_*.db" `
- > "<ARTIFACTS_DIR>\contacts.txt" 2>&1
+ > "<ARTIFACTS_DIR>\contacts.txt" 2> "<ARTIFACTS_DIR>\contacts.err.txt"
```
`--threshold N`（最低消息数，默认 50）｜ `--include-chatrooms`（同时列出群聊）。
---
## 硬性规则
- - `export_*` 的输出**必须** `> "<ARTIFACTS_DIR>\xxx.txt" 2>&1`，禁止裸跑让内容进上下文。
+ - `export_*` 的输出**必须**重定向到文件：`> "<ARTIFACTS_DIR>\xxx.txt" 2> "<ARTIFACTS_DIR>\xxx.err.txt"`，
+ 禁止裸跑让内容进上下文。**不要用 `2>&1`**，它会把 PowerShell 的 `NativeCommandError` 噪声写进聊天文件。
- `find_*` 的输出可以正常读取、展示给用户。
- - 所有子命令用 `& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" <命令>` 调用。
- - 不要手写相对 `output\` 路径；优先直接复制 `preflight` / `find_*` 打印出的完整命令。
+ - `make_json` / `make_db` 必须用 Step 0 的提权新窗口启动，禁止在当前会话里直接运行（会因缺权限、输出缓冲、无法发送 Ctrl+C 而表现为静默卡死）。
+ - 子命令分布在两个二进制：`preflight` / `find_*` / `export_*` / `make_db` 在 `_common.exe`，**`make_json` 在 `_core.exe`**。当前会话里统一用 `& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" <命令>` 调用。
+ - 不要手写相对 `output\` 路径；路径优先取 `preflight` / `find_*` 打印出的绝对路径。
+ 但 `find_*` 打印的导出命令，**开头那段 `…\Temp\onefile_*\python.exe` 是失效路径**，
+ 必须换成 `& "$env:CLAUDE_PLUGIN_ROOT\_common.exe"`。
- 时区默认 GMT+8，`--tz` 调整。