---
name: wechat
description: 在本地查询、导出微信 4.1+ 聊天记录为 AI 可读文本 —— 支持双人会话、群聊、以及按消息量排名的重要联系人扫描。当用户想导出、搜索或分析自己的微信聊天记录，或为其他 skill（前任.skill / 同事.skill 等）准备聊天记录原材料时使用。
---

# 微信聊天记录导出

在本地把微信 4.1+ 的聊天记录构建为可查询、可导出的 AI 可读文本。所有操作在本机运行，数据不离机。

所有功能都是密封二进制的子命令（`preflight` / `setup` / `find_*` / `export_*`）。操作参考见 `reference/db-schema.md`。

## 前置检查（每次会话第一步）

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:CLAUDE_PLUGIN_ROOT\bootstrap.ps1" -Preflight
```

它先确保插件目录里有 `_common.exe`（首次使用会从 GitHub Release 下载约 7 MB 并校验 SHA-256，
可能要几十秒），再运行 `preflight`。下载失败时它会打印原因（通常是连不上 github.com），转述给用户。
之后本会话里的其他命令直接调用 `& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" <命令>`。

> **本 skill 的每一条命令都是 PowerShell。** 全新的工作目录默认不带 PowerShell 执行权限，
> 第一条命令就会被权限提示拦住。这时**不要**改用 Bash 重写（`&` 调用与 `$env:` 语法在 Bash 下
> 不成立），也不要放弃，而是用自然语言告诉用户：
>
> > 这个插件的命令都要用 PowerShell 跑。请在弹出的权限提示里选「允许」——
> > 如果有「始终允许 / 不再询问」，选它就不会再被打断。也可以用 `/permissions` 管理。
>
> 得到许可后从 `preflight` 重新开始。

记住结尾打印的 `BUILT_DB_DIR=` / `ARTIFACTS_DIR=`，下文的 `<BUILT_DB_DIR>` / `<ARTIFACTS_DIR>` 都用它。
然后**只看 `NEXT_STEP=`**：

| `NEXT_STEP` | 做什么 |
|---|---|
| `ready` | 数据已就绪，按下方「按意图选择流程」继续 |
| `setup` | 进入 Step 0 |
| `wait` | 上一次的准备窗口还开着：请用户在那个窗口里完成（或关掉它），再重跑 `preflight` |
| `reinstall` | 插件文件缺失（多半被杀毒软件删了）：请用户在杀毒软件里放行后重新安装插件 |

`SETUP_STATUS=` 若是 `interrupted` / `cancelled` / `failed:*`，preflight 会打印原因，转述给用户即可。

### Step 0：准备数据（`setup`）

一条命令完成全部准备：它会弹出**一个**管理员窗口，在里面按需抓取方案清单（`make_json`），
再构建数据库（`make_db`），并**等窗口跑完才返回**。

先用自然语言告诉用户（`SOLUTION=missing` 时用第一段，`present` 时用第二段）：

> 接下来会弹出 Windows 的管理员权限提示，请点「是」。窗口打开后，请切到微信，**逐个点开聊天
> （新的旧的都点）、通讯录、收藏、朋友圈，并搜索一次**；等窗口里「已捕获」的计数不再增长，
> 回到那个窗口按 **Enter**。之后数据库会自动构建，窗口会自己关掉。

> 接下来会弹出 Windows 的管理员权限提示，请点「是」。这次只需要重建数据库，窗口会自己跑完。

然后用 PowerShell 工具**后台运行**（`run_in_background`，它会一直等到窗口结束）：

```powershell
& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" setup
```

结束时会通知你。看最后一行 `SETUP_RESULT=`：

| `SETUP_RESULT` | 含义 / 处理 |
|---|---|
| `done` | 完成。重跑 `preflight`，应为 `NEXT_STEP=ready` |
| `cancelled` | 用户在 UAC 提示里点了「否」。问一下是否要再试 |
| `interrupted` | 窗口在完成前被关掉。问清楚后再试 |
| `failed:make_json` / `failed:make_db` | 报错留在那个窗口里，请用户把窗口内容告诉你 |
| `error` | 命令本身打印了原因（如微信没在运行、已有窗口在跑），照着转述 |

- 想拿到**最新消息**：再跑一次 `setup` 即可（已有方案清单时只重建数据库）。
- 新消息库没有方案（preflight 里出现 0 张表、或微信更新后建库失败）：用 `setup --refresh` 重新抓取方案清单。
- **不要**在当前会话里直接运行 `make_json` / `make_db`：它们需要管理员权限，在非终端环境下输出会被完全缓冲，看起来就是卡死。一律走 `setup`。

> Windows Defender 等杀毒软件可能报警，需要用户手动放行。

## 按意图选择流程

| 用户想要… | 用哪个流程 |
|---|---|
| 导出 / 搜索与某个人的双人聊天 | **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 — 运行导出命令

**直接运行 `find_private` 打印的那条导出命令**（可执行文件路径、参数、重定向都已拼好），
需要时在重定向前追加时间范围参数。它的形如：

```powershell
& <插件目录>\_common.exe export_private `
  --db <各库路径…> --table <Msg_...> --sender-map '<ARTIFACTS_DIR>\sender_map_<名字>.json' `
  > '<ARTIFACTS_DIR>\chat_<名字>.txt' 2> '<ARTIFACTS_DIR>\chat_<名字>.err.txt'
```

stdout 与 stderr **分别**落盘，内容不进上下文。**不要改成 `2>&1`**：Windows PowerShell 5.1 会把
原生程序的 stderr 包装成 `NativeCommandError` 写进聊天文件开头，让导出结果看起来像报错。

时间范围（默认全量）：`--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 天）

直接运行 `find_chatroom` 打印的导出命令即可，形如：

```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> "<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> "<ARTIFACTS_DIR>\contacts.err.txt"
```

`--threshold N`（最低消息数，默认 50）｜ `--include-chatrooms`（同时列出群聊）。

---

## 硬性规则

- `export_*` 的输出**必须**重定向到文件：`> "<ARTIFACTS_DIR>\xxx.txt" 2> "<ARTIFACTS_DIR>\xxx.err.txt"`，
  禁止裸跑让内容进上下文。**不要用 `2>&1`**，它会把 PowerShell 的 `NativeCommandError` 噪声写进聊天文件。
- `find_*` 的输出可以正常读取、展示给用户。
- 准备 / 更新数据一律用 `setup`（后台运行），禁止在当前会话里直接运行 `make_json` / `make_db`。
- 每次会话先跑 `bootstrap.ps1 -Preflight`；之后统一用 `& "$env:CLAUDE_PLUGIN_ROOT\_common.exe" <命令>` 调用。
  `_core.exe` 由 `setup` 在需要时自动下载并内部使用，不要直接调。
- 不要手写相对 `output\` 路径；路径优先取 `preflight` / `find_*` 打印出的绝对路径，`find_*` 打印的导出命令可以原样运行。
- 时区默认 GMT+8，`--tz` 调整。