open-source/WechatExplorer
1
0
Fork 0
mirror of https://wget.la/https://github.com/Wxw-Gu/WechatExplorer synced 2026-08-17 03:27:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 更新文档

Browse Source
This commit is contained in:
Wxw-Gu
2026-08-07 22:52:56 +08:00
parent a73af3b5ad
commit cd2c3cfaee
24 changed files with 1175 additions and 992 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+58
View File
@@ -0,0 +1,58 @@
# WechatExplorer 文档
WechatExplorer 的文档按“你想完成什么”组织，而不是按源码模块组织。
## 从这里开始
- [第一次使用](./user-guide/getting-started.md)：安装、连接微信、完成第一次搜索和提问。
- [查看和搜索聊天](./user-guide/chat-archive.md)：找原话、回看上下文、处理媒体。
- [用 AI 查找聊天信息](./user-guide/ai-search.md)：理解普通搜索和 AI Search 的区别，并核对答案来源。
## 你可以完成的任务
- [建立本地知识库](./user-guide/knowledge.md)
- [生成群聊日报和总结](./user-guide/report.md)
- [语音转文字](./user-guide/voice.md)
- [导出聊天和报告](./user-guide/export.md)
- [数据、隐私与安全](./user-guide/privacy.md)
- [常见问题与排查](./user-guide/troubleshooting.md)
## 如果你想了解 AI 为什么这样回答
- [如何核对 AI 的回答来源](./concepts/answer-sources.md)：用用户语言解释依据、来源标记和查找过程。
- [从微信数据到回答、日报和导出](./concepts/how-it-works.md)：了解哪些步骤在本机完成，哪些步骤可能调用 Provider。
## 如果你想连接 Agent
WechatExplorer 有两种不同的 Agent 使用方式，请先按你的目标选择：
| 你想做什么 | 应该看哪里 |
| --- | --- |
| 在 Codex、Claude Code、OpenClaw 等外部 Agent 中主动查询过去的微信数据 | [Reader Skill](./agent/reader-skill.md) + [Local HTTP API](./agent/api.md) |
| 在微信里给机器人发消息，让本机读取数据、生成总结并回复 | [Agent Hub](./agent/agent-hub.md) |
### 让外部 Agent 查询历史微信
连接 Reader Skill 后，你可以询问：
> “总结今天技术交流群讨论了什么。”
> “过去一周有没有人提到这个项目？”
- [Agent 接入概览](./agent/overview.md)：先选择适合你的接入方式。
- [Reader Skill](./agent/reader-skill.md)：安装并让外部 Agent 按需读取聊天。
- [Local HTTP API](./agent/api.md)：完整端点和请求示例。
- [API 安全](./agent/api-security.md)：Bearer Token、CORS、轮换和边界。
### 让微信机器人参与实时工作
打开应用主导航中的“Agent”，进入“Agent Hub”后扫码登录微信机器人。机器人收到文字消息后，可以查询最近会话、读取联系人聊天、生成群聊总结图片或总结群成员发言，并把结果回复给发消息的人。它需要本地微信数据库已经连接；依赖 AI 的任务还需要配置 AI 服务。
- [Agent Hub](./agent/agent-hub.md)：连接机器人、查看运行状态和了解实时交互边界。
## 开发与平台
- [macOS 数据访问说明](./platform/macos.md)
- [开发、测试与构建](./development/overview.md)
- [v2.1.9 API 鉴权迁移说明](./agent/release-notes-v2.1.9.md)
当前工作区版本：**2.1.9**。文档只描述当前代码已经实现的能力；版本兼容性、AI Provider 行为和媒体读取结果可能随系统、微信客户端和服务商变化。
docs/agent/agent-hub.md
+67
View File
@@ -0,0 +1,67 @@
# Agent Hub：让微信机器人参与实时工作
Agent Hub 是 WechatExplorer 内置的实时微信交互入口。你先在应用中扫码登录一个微信机器人账号，之后向这个机器人发送文字；本机 Agent Hub 会接收消息、读取已经连接的微信数据，必要时调用已配置的 AI，再把结果回复给发消息的人。
它和 Reader Skill 是两条不同的路径：
- Reader Skill / Local HTTP API：外部 Agent 主动查询历史微信数据；
- Agent Hub / 微信机器人：机器人收到实时消息后处理并回复。
## 连接器和 Agent Hub 是什么关系
你不需要单独部署这些组件。扫码后，后台的微信连接器负责登录机器人、保持连接、接收微信消息和发送回复；Agent Hub 负责判断消息要做什么、查询 WechatExplorer 本地数据、调用 AI 并组织结果。可以把它理解为：连接器负责“和微信通信”，Hub 负责“处理任务”。
## 你能做什么
连接 Agent Hub 后，可以在微信中询问：
- “最近 5 条消息是谁？”
- “帮我看看最近跟某人聊了些什么。”
- “生成产品交流群今天的群聊总结图片。”
当前已实现的实时任务包括：
- 查看最近会话（数量限制为 1–20）；
- 查询你和某位联系人的近期聊天；
- 用已配置的 AI 总结你和某位联系人近 7 天的聊天；
- 生成今天、昨天或近 7 天的群聊总结图片；
- 总结指定群成员在群里的近期发言；
- 对不需要读取聊天的普通文字请求返回简短 AI 回复。
任务完成后，回复会发送回触发这次请求的微信用户。群聊总结会先发送进度提示，完成后发送图片。
这些任务会在后台查询联系人、群聊和聊天记录，但当前机器人没有单独的“列出所有联系人”或“列出所有群聊”命令；需要完整浏览或按条件查询时，请使用档案页面或 Reader Skill / Local HTTP API。
## 连接步骤
1. 打开应用主导航中的“Agent”；页面标题为“Agent Hub”。
2. 确认 Hub 显示“运行中”，数据库状态为“可查询”。
3. 点击“扫码登录微信机器人”。
4. 用微信扫描二维码；如果页面显示“已扫码，等待手机确认”，在手机上确认。
5. 状态变为“在线”后，从该机器人账号发送测试问题。
可以重新扫码登录或断开连接。登录凭证失效时，需要重新扫码。
## 运行日志
Agent Hub 页面会记录系统、Agent Hub 和微信连接器日志。日志支持筛选、复制和清空，并会隐藏 Token 和二维码数据，不记录微信密码。
## 需要满足的条件
- WechatExplorer 的微信数据库已经连接，并且数据 API 可以查询；
- 依赖总结或自然语言理解的任务，需要在“设置 → AI 模型”配置可用的 AI 服务；
- WechatExplorer 和 Agent Hub 需要保持运行，机器人才能接收和回复消息。
## 安全与边界
- Hub 使用本机通信，不把数据库直接暴露到公网；
- 机器人账号和个人微信账号是不同的登录边界，请确认你连接的是正确账号；
- 机器人回复会发送给当前发消息的人；开发者 API 另有受保护的测试发送入口，使用前必须确认接收者；
- Hub 生成群聊总结时仍可能调用你配置的 AI Provider；
- 当前实时自然语言入口主要处理文字消息。底层连接器可以接收图片、语音、文件和视频，但 Agent Hub 尚未为这些媒体提供同等的实时意图处理；
- 当前没有实现群发、广播、定时任务或通用自主操作微信；
- 本页面的“Agent Hub 状态”可以通过 Local HTTP API 查询，但不要把它误认为外部 Agent 的实时消息订阅接口或 MCP Server。
## 无法连接时
先检查 Hub、连接器和数据库三项状态，再查看日志。二维码过期、连接器不存在、凭证失效和数据 API 未就绪分别需要重新扫码、修复安装、重新登录或先完成微信数据库连接。
docs/agent/api-security.md
+47 -9
View File
@@ -1,12 +1,50 @@
# Local API Security
# Local HTTP API 安全
WechatExplorer 的安全模型是：本机回环地址 + 高熵 Bearer Token。
## 当前安全边界
- Token 使用密码学安全随机源生成，并由 Electron safeStorage 加密保存。
- 应用升级或首次启动时自动、幂等生成；应用重启后保持不变。
- API Center 可以显示、复制或重新生成 Token。重新生成后旧 Token 立即失效。
- `/api/v1/health` 公开且不返回聊天内容、数据库路径、Token 或 Provider 信息。
- 其他 endpoint 缺少或使用错误 Token 时返回 `401 Unauthorized`。
- CORS 仅允许精确的 localhost、127.0.0.1 和 ::1 HTTP Origin；无 Origin 的 curl、Node 和本地 Agent 请求正常工作。
WechatExplorer 的本地 API 默认监听 `127.0.0.1:6131`。它面向同一台电脑上的 API Center、Reader Skill、CLI 和 Agent，不是公网网关，也不是带用户账户和细粒度权限 Scope 的服务。
本地 API 不应暴露到公网或不受信任网络。Bearer Token 提供本机 API 访问保护，但不是公网网关、用户账户系统或完整权限 Scope 系统。
## Bearer Token
- `/api/v1/health` 是公开健康检查；
- 其他所有端点都要求 `Authorization: Bearer <TOKEN>`；
- Token 由应用生成，使用 32 个随机字节编码；
- Token 由 Electron `safeStorage` 加密保存在用户数据目录的 `local-api-token.bin`；
- 文件权限设置为 `0600`；
- 在“API Center”中可以显示、复制和重新生成；
- 重新生成后旧 Token 立即失效。
应用不会自动把 Token 写入 Codex、Claude Code、OpenClaw 或其他 Agent 配置。请把它放进 Agent 自己的本地 secret/environment，例如：
```bash
export WECHATEXPLORER_API_TOKEN="<TOKEN>"
```
## CORS 与 Origin
带浏览器 `Origin` 的请求只允许精确的 HTTP loopback Origin：
- `http://localhost` 及其端口；
- `http://127.0.0.1` 及其端口；
- `http://[::1]` 及其端口。
不带 `Origin` 的 curl、Node、本地脚本和 Agent 请求不受浏览器 CORS 规则限制，但仍必须携带 Token（health 除外）。
## 不要做的事
- 不要把 Token 放入 URL query、日志、截图、公开 Skill 或 Git；
- 不要把服务反向代理到公网；
- 不要把“health 能访问”误认为数据端点无需授权；
- 不要把 Bearer Token 当成跨用户权限系统；当前服务没有细粒度 Scope；
- 不要在共享机器上让不可信进程继承 Token 环境变量。
## Token 不可用时
如果系统安全存储不可用，API Token 会无法生成或读取，本地 API 会安全停用。先修复系统钥匙串/凭据服务，再回到 API Center 重试。不要手动编辑 `local-api-token.bin`。
## 相关文档
- [Agent 接入概览](./overview.md)
- [Reader Skill](./reader-skill.md)
- [数据、隐私与安全](../user-guide/privacy.md)
- [v2.1.9 鉴权迁移说明](./release-notes-v2.1.9.md)
docs/agent/api.md
+86 -8
View File
@@ -1,16 +1,94 @@
# WechatExplorer Local HTTP API
WechatExplorer v2.1.9 默认在 `127.0.0.1:6131` 提供 Local HTTP API。
本文面向需要自己写集成的开发者。普通用户请先阅读[Agent 接入概览](./overview.md)。
- `GET /api/v1/health` 无需鉴权。
- 其他数据和 Agent endpoint 需要 `Authorization: Bearer <TOKEN>`。
- Token 从 WechatExplorer → API Center → API Token 获取。
- Token 不得放入 URL、仓库或共享配置。
## 基本信息
- 默认地址：`http://127.0.0.1:6131`
- API 前缀：`/api/v1`
- 默认只监听 loopback；不要把它当作公网服务。
- `/api/v1/health` 无需 Token；其他端点需要 `Authorization: Bearer <TOKEN>`。
- 请求体使用 JSON；响应为 JSON。
## 最小请求
```bash
export WECHATEXPLORER_API_TOKEN="<YOUR_API_TOKEN>"
# 健康检查
curl http://127.0.0.1:6131/api/v1/health
# 读取数据
export WECHATEXPLORER_API_TOKEN="<从 API Center 复制的 Token>"
curl -H "Authorization: Bearer $WECHATEXPLORER_API_TOKEN" \
http://127.0.0.1:6131/api/v1/recent_chat
"http://127.0.0.1:6131/api/v1/recent_chat?limit=20"
```
完整 endpoint 与使用流程见 [Reader Skill](../skill/wechatexplorer-reader/SKILL.md)，安全边界见 [API Security](./api-security.md)。
不要把 Token 放入 URL、Skill 文件、仓库或命令历史可被共享的脚本中。
## 端点
| 方法 | 路径 | 作用 | 参数/请求体 |
| --- | --- | --- | --- |
| GET | `/api/v1/health` | 服务与数据库健康状态 | 无 |
| GET | `/api/v1/current_time` | 本机时间、时区和 Unix 时间戳 | 无 |
| GET | `/api/v1/contact` | 联系人和群聊列表 | `filter`、`type=user\|group` |
| GET | `/api/v1/chatroom` | 群聊列表 | `keyword` |
| GET | `/api/v1/recent_chat` | 最近会话 | `limit`，默认 50 |
| GET | `/api/v1/chatlog` | 指定会话的聊天记录 | 必填 `talker`；可选 `time` 或 `startTime`/`endTime` |
| GET | `/api/v1/group_snapshot` | 群成员快照 | 必填 `md5` |
| GET | `/api/v1/resolve` | 将昵称、wxid 或 md5 解析为会话 | 必填 `q` |
| POST | `/api/v1/report` | 将结构化日报渲染为 HTML 与 PNG | `GroupReportExportRequest` JSON |
| GET | `/api/v1/agent/status` | Agent Hub、连接器和数据库状态 | 无 |
| POST | `/api/v1/agent/group-report` | 读取群聊并生成总结图片 | `{ "group": "群名或标识", "range": "today\|yesterday\|7days" }` |
| POST | `/api/v1/agent/send` | 通过已连接机器人测试发送文字或本地图片 | `{ "to": "接收者", "text": "...", "media_url": "..." }` |
### 这些端点与实时机器人有什么关系
- `/api/v1/agent/status` 只用于查询 Agent Hub、微信连接器和数据库状态；
- `/api/v1/agent/group-report` 由外部 Agent 或脚本主动请求生成群聊总结图片；
- `/api/v1/agent/send` 是受 Bearer Token 保护的开发者/测试发送入口，用于通过已经连接的机器人发送文字或本地图片；它不是任意群发能力，也不是实时消息订阅接口；
- 当前 API 没有对外暴露实时入站 webhook。微信消息由应用内部的 Agent Hub 和微信连接器接收、处理和回复。
## 时间查询
`chatlog` 的 `time` 支持：
- `YYYY-MM-DD`：当天；
- `YYYY-MM-DD~YYYY-MM-DD`：日期闭区间；
- `YYYY-MM-DD/HH:mm`：从该分钟开始的 60 秒；
- 也可以使用 Unix 秒级 `startTime` 和 `endTime`。
时间按运行 WechatExplorer 的本机时区解析。用户说“今天”“昨天”时，先调用 `current_time`，再根据返回的 `localDate` 计算日期，避免使用 Agent 自己的时区。
## 常用工作流
### 查找并读取一个会话
```bash
BASE="http://127.0.0.1:6131/api/v1"
AUTH="Authorization: Bearer $WECHATEXPLORER_API_TOKEN"
curl -H "$AUTH" "$BASE/resolve?q=技术交流群"
curl -H "$AUTH" "$BASE/chatlog?talker=技术交流群&time=2026-08-07"
```
当标识不确定时，先用 `resolve` 或 `contact`，再调用 `chatlog`。对重要问题，先宽范围定位，再针对关键时间点读取前后文，不要只凭一次粗查回答。
### 生成群聊总结图片
优先使用 `/api/v1/agent/group-report`，因为它会读取指定群聊并按 `today`、`yesterday` 或 `7days` 生成总结。`/api/v1/report` 是更底层的渲染接口，要求调用方已经准备好 `report` 和 `metadata` 结构；完整 TypeScript 类型以 `src/shared/group-report.ts` 为准。
## 响应与错误
- `200`：请求成功；
- `401`：缺少、错误或已失效的 Bearer Token；
- `400`：参数或 JSON 请求体无效；
- `403`：浏览器 Origin 不在允许的 loopback 列表；
- `404`：端点、会话或群聊不存在；
- `503`：数据库或 Agent Hub 尚未就绪；
- `500`：服务端处理或报告渲染失败。
成功响应会返回端点对应的 JSON 对象，例如 `chatlog` 包含 `contact`、`query`、`count` 和 `messages`，`contact` 返回 `count` 与 `contacts`。
## 与 MCP 的关系
当前实现没有把 `6131` 暴露为 MCP Server。需要在 Agent 中使用时，请安装随应用提供的 Reader Skill，并让 Skill 通过普通 HTTP 请求调用本 API。
docs/agent/overview.md
+47
View File
@@ -0,0 +1,47 @@
# 连接 Agent：你能用它做什么
WechatExplorer 的 Agent 能力分成“查询过去的数据”和“处理实时微信消息”两条路径。先按你想完成的任务选择，不需要先学习内部模块名称。
## 两种不同的使用方式
### 让外部 Agent 查询历史微信
连接 Reader Skill 后，你可以在本机的 Codex、Claude Code、OpenClaw 或其他 Agent 中询问自己的微信历史，例如：
- “总结今天技术交流群讨论的内容。”
- “帮我找上个月讨论过的项目地址。”
- “过去一周有没有人提到退款？”
Agent 会按需读取 WechatExplorer 提供的联系人、群聊和聊天记录；它不会直接打开微信数据库文件。
| 方式 | 适合谁 | 作用 | 是否需要外部 Agent 配置 |
| --- | --- | --- | --- |
| Reader Skill + Local HTTP API | 想在 Codex/Claude Code/OpenClaw 中查微信的人 | Agent 通过本机 HTTP 请求读取聊天 | 是，需要安装 Skill 和 Token |
| Agent Hub | 想从微信机器人账号发消息、让本机处理并回复的人 | 微信连接器把消息送到本机 Hub，Hub 调用数据和 AI | 不使用外部 Reader Skill，但需要扫码连接机器人 |
这两条路径不要混写：Reader Skill/API 是外部 Agent 主动读取历史；Agent Hub 是机器人收到实时消息后处理并回复。`127.0.0.1:6131` 是 Local HTTP API，不是 MCP Server。
## 外部 Agent 的安装路径
1. 启动 WechatExplorer 并完成微信数据库连接。
2. 打开“API Center”，确认本地 API、数据库和 Reader Skill 都显示可用。
3. 在 API Center 选择目标 Agent（Codex、Claude Code、OpenClaw 或其他 Agent），点击“复制安装指令”。
4. 在 Agent 自己的本地 Skill/配置目录执行或粘贴指令。
5. 在 API Center 复制当前 Token，并在 Agent 运行环境中设置 `WECHATEXPLORER_API_TOKEN`。
6. 先让 Agent 调用 health，再尝试查询联系人或最近会话。
详细说明：[Reader Skill](./reader-skill.md)、[Local HTTP API](./api.md)、[API 安全](./api-security.md)。
## Agent 能看到什么
外部 Agent 通过 API 按需读取联系人、群聊、最近会话、指定时间范围聊天和群成员快照，也可以请求生成群聊总结图片。API 本身不提供任意文件系统浏览，也不会把完整数据库自动上传到网络。
Agent 是否把读取结果再次交给云端模型，取决于 Agent 的模型配置和它如何处理工具结果。使用前请检查 Agent 自己的隐私设置。
## 什么时候用 Agent Hub
如果你希望直接在微信里问“最近 5 条消息是谁？”或“生成产品交流群今天的群聊总结图片”，打开应用主导航中的“Agent”，进入“Agent Hub”，扫码登录一个微信机器人账号。机器人收到文字后，会调用本地数据和已配置的 AI，再把结果回复给发消息的人。
当前实时入口支持最近会话、联系人近期聊天、联系人近 7 天总结、群聊总结图片、群成员发言总结和有限的普通自然语言回复。它不等于通用聊天机器人，也不提供群发、定时或任意媒体理解。
详细流程见[Agent Hub](./agent-hub.md)。
docs/agent/reader-skill.md
+57 -8
View File
@@ -1,11 +1,60 @@
# Reader Skill Authentication
# Reader Skill：让外部 Agent 读取微信
WechatExplorer Reader 是 Local HTTP API Skill，不是 MCP Server。
## 先理解它能做什么
1. 打开 WechatExplorer → API Center。
2. 确认 API 和数据库已就绪。
3. 在 API Token 区域复制 Token。
4. 将它保存到 Agent 自己的本地环境配置：`WECHATEXPLORER_API_TOKEN=<YOUR_API_TOKEN>`。
5. 安装 Reader Skill，并让所有数据请求携带 `Authorization: Bearer $WECHATEXPLORER_API_TOKEN`。
Reader Skill 是一份给 Agent 的操作说明。安装后，Codex、Claude Code、OpenClaw 或其他本地 Agent 可以按需调用 WechatExplorer，读取联系人、群聊、最近会话、指定时间的聊天和群成员信息。
Codex、Claude Code、OpenClaw 和其他 Agent 均使用相同的 HTTP Bearer Token 模型。WechatExplorer 不会自动把 Token 写入任何 Agent 配置。
它使用的是 WechatExplorer Local HTTP API，不是 MCP Server。
Reader Skill 只负责“外部 Agent 主动查询历史微信数据”。它不负责二维码登录、监听微信实时消息、接收机器人消息或管理 Agent Hub。想让机器人收到微信消息后处理并回复，请阅读[Agent Hub](./agent-hub.md)。
## 推荐安装流程
1. 启动 WechatExplorer 并完成数据库连接。
2. 打开“API Center”，确认 API 服务和数据库状态正常。
3. 在 Reader Skill 区域选择目标 Agent，点击“复制安装指令”。
4. 把指令粘贴到对应 Agent 的 Skill/配置目录；应用会根据本机路径生成适合 Codex、Claude Code、OpenClaw 或通用 Agent 的说明。
5. 在 API Center 复制 Token，在 Agent 自己的本地环境设置：
```bash
export WECHATEXPLORER_API_TOKEN="<YOUR_API_TOKEN>"
```
6. 先执行 health 检查，再读取数据端点。
WechatExplorer 不会自动把 Token 写进 Agent 配置。重新生成 Token 后，必须同步更新 Agent 环境。
## Agent 的读取顺序
当用户使用“今天”“昨天”“本周”等相对时间时：
1. 调用 `/api/v1/current_time` 获取本机时区和日期；
2. 将相对时间换算为 `chatlog` 支持的 `time` 或时间戳；
3. 调用 `/api/v1/resolve`、`contact` 或 `chatroom` 确认会话；
4. 调用 `/api/v1/chatlog` 读取目标范围；
5. 对重要结论再读取关键消息前后文，不要只凭一次粗查。
## 最小请求
```bash
curl http://127.0.0.1:6131/api/v1/health
curl -H "Authorization: Bearer $WECHATEXPLORER_API_TOKEN" \
"http://127.0.0.1:6131/api/v1/recent_chat?limit=20"
```
## 当前能力范围
Reader Skill 可以指导 Agent 使用：
- 联系人、群聊、最近会话和会话解析；
- 指定会话、日期或时间戳范围的聊天记录；
- 群成员快照；
- 结构化日报渲染和按群聊生成总结图片；
- Agent Hub 状态检查与已连接机器人发送测试。这里的发送接口是开发者/测试用途，不是实时机器人入口，也不会让 Reader Skill 自动监听微信消息。
端点、参数、错误码和鉴权细节以[Local HTTP API](./api.md)为准。Skill 文件保持短小，避免在多个文档中复制会变化的完整响应 schema。
## 隐私边界
Reader Skill 本身不会把聊天数据自动上传到其他服务器；它只是让 Agent 调用本机 API。Agent 读取结果是否继续发送给云端模型，取决于 Agent 自己的模型和工具配置。请同时阅读[数据、隐私与安全](../user-guide/privacy.md)。
docs/agent/release-notes-v2.1.9.md
+9 -8
View File
@@ -1,11 +1,12 @@
# WechatExplorer v2.1.9 API Authentication
# WechatExplorer 2.1.9：Local HTTP API 鉴权迁移
v2.1.9 为 Local HTTP API 增加 Bearer Token 鉴权。这是有意的 breaking change。
2.1.9 为 Local HTTP API 增加 Bearer Token 鉴权。这是一次有意的兼容性变化：除健康检查外，数据接口不再接受裸请求。
- v2.1.8：`GET /api/v1/contact` 可能直接返回数据。
- v2.1.9：相同请求必须携带 `Authorization: Bearer <TOKEN>`，否则返回 `401`。
- `GET /api/v1/health` 保持公开。
- 老用户升级后会自动生成并安全保存 Token，不改变原有 apiEnabled、host 或 port 设置。
- Token 可在 WechatExplorer → API Center 中显示、复制和重新生成。
- 历史版本中，`GET /api/v1/contact` 等数据请求可能直接返回内容；
- 2.1.9 中，相同请求必须携带 `Authorization: Bearer <TOKEN>`，否则返回 `401`；
- `GET /api/v1/health` 保持公开；
- 升级后应用会生成并安全保存 Token，原有 API 启用状态、监听地址和端口设置保持不变；
- Token 可在 WechatExplorer → API Center 中显示、复制和重新生成；
- Reader Skill、Codex、Claude Code、OpenClaw 和其他本地 Agent 需要在自己的环境中设置 `WECHATEXPLORER_API_TOKEN`。
Reader Skill 和本地 Agent 需要使用 `WECHATEXPLORER_API_TOKEN` 更新本机配置。
如果旧 Agent 无法访问，请先从 API Center 复制当前 Token，再确认每个非 health 请求都带有 Bearer header。完整规则见[API 安全](./api-security.md)。
docs/concepts/answer-sources.md
+41
View File
@@ -0,0 +1,41 @@
# 如何核对 AI 的回答来源
## 先记住一件事
AI 回答后，你可以继续查看它参考了哪些聊天内容、这些内容来自哪个会话和时间，并跳回原始消息检查上下文。
这让 WechatExplorer 和只给一段摘要的聊天机器人不同：答案不是终点，来源也应该能被你检查。
## 三类来源信息
在产品界面和检索详情中，你可能看到这些名称：
- **Evidence**：AI 回答所依据的原始聊天片段。
- **Citation**：回答中某个结论对应的来源标记。
- **Search Trace**：本次查找经历了哪些阶段、每一步用了多久、覆盖是否完整。
普通用户不需要记住英文名。判断一个回答是否可信时，按“来源 → 原消息 → 上下文”检查即可。
## 推荐的核对顺序
1. 先看回答是否明确区分事实、推断和不确定信息；
2. 打开来源，检查发送者、会话和时间；
3. 跳回档案，查看消息前后文，确认是否存在引用、转发或后续修正；
4. 检查提示中是否有未转写语音、缺失媒体或只覆盖部分范围；
5. 对重要决定、金额、日期和责任人，不要只依据 AI 摘要。
## 为什么来源可能不完整
来源覆盖受时间范围、会话范围、索引状态和可读媒体影响。例如：
- Knowledge 正在同步时，新的分析会被暂停；
- 语音没有转写时，AI 可能只能看到消息类型；
- 图片无法读取或未启用图片理解时，AI 不应声称知道图片内容；
- 你只选择了一个群，答案不会自动代表所有聊天。
看到“可能遗漏”或“部分覆盖”时，扩大范围、先完成同步或检查原始媒体后再问。
## 这不是事实保证
Evidence 和 Citation 能告诉你“模型看到了什么”，不能保证模型没有误读。最终判断仍应回到原始消息，尤其是涉及隐私、法律、财务、医疗或工作决策时。
docs/concepts/how-it-works.md
+44
View File
@@ -0,0 +1,44 @@
# WechatExplorer 如何把聊天变成可用的信息
你可以把一次任务想成下面这条路径：
```mermaid
flowchart LR
A[本机微信数据] --> B[读取与解析]
B --> C[聊天档案与普通搜索]
B --> D[本地知识索引]
D --> E[筛选相关消息]
E --> F[用户配置的 AI Provider]
F --> G[回答与可核对来源]
B --> H[日报与导出]
B --> I[Local HTTP API]
I --> J[外部 Agent]
```
## 哪些步骤在本机
- 微信数据库读取与解析；
- 聊天档案浏览和普通搜索；
- Knowledge 索引与增量同步；
- 离线语音转写；
- 报告、导出文件和本地历史记录。
## 哪些步骤可能调用外部服务
当你主动使用 AI Search、群聊日报或图片理解时，应用会把完成任务所需的受控问题和上下文发送给你配置的 Provider。它不会因为打开软件就自动上传完整数据库。
如果 Provider 是 Ollama 等本机服务，请把它视为本机的另一个进程；如果是云服务，数据处理和留存规则由该服务商决定。
## 产品名词和用户任务的对应关系
| 用户想做什么 | 产品中可能看到的名称 |
| --- | --- |
| 让 AI 找相关聊天 | AI Search、Retrieval |
| 让答案能回到原消息 | Evidence、Citation |
| 查看 AI 查找过程 | Search Trace |
| 让跨会话查找更稳定 | Knowledge、FTS 索引 |
| 让外部 Agent 读取聊天 | Reader Skill、Local HTTP API |
| 让微信机器人调用本机能力 | Agent Hub |
先按任务使用，再在需要排查或开发集成时阅读术语。
docs/development/overview.md
+55
View File
@@ -0,0 +1,55 @@
# 开发、测试与构建
本文面向希望参与 WechatExplorer 开发、验证文档或维护集成的贡献者。普通用户请从[第一次使用](../user-guide/getting-started.md)开始。
## 技术基线
- Electron + React + TypeScript；
- pnpm 7+；
- Go（构建微信连接器）；
- 平台对应的 Electron/native 构建环境。
产品文档的事实来源优先级是：当前源码 → 当前 UI/Renderer → 测试 → package/config → README/docs → 历史资料。功能、API、版本、隐私和兼容性变更时，不要只改 README。
## 本地开发
```bash
pnpm install
pnpm dev
```
常用检查：
```bash
pnpm typecheck
pnpm test:unit
pnpm test:component
pnpm test:integration
pnpm test:e2e:build
```
完整测试入口 `pnpm test` 还会运行 Skill 安装指令、微信连接器、构建和 Playwright 测试；需要对应平台环境。
## 代码变更对应文档
| 代码区域 | 需要同步检查的文档 |
| --- | --- |
| `src/shared/ai-search.ts`、AI Search pipeline | `user-guide/ai-search.md`、`concepts/answer-sources.md` |
| `src/shared/knowledge.ts`、`src/main/knowledge/` | `user-guide/knowledge.md`、`concepts/how-it-works.md` |
| `src/shared/voice-recognition.ts` | `user-guide/voice.md` |
| `src/shared/group-report.ts`、报告 UI | `user-guide/report.md`、API/Agent 文档 |
| `src/shared/export.ts`、导出服务/UI | `user-guide/export.md` |
| `src/shared/local-api-test.ts`、`src/main/http-server.ts` | `agent/api.md`、`api-security.md`、打包 Skill |
| Agent Hub service/UI | `agent/agent-hub.md`、`user-guide/privacy.md` |
| 设置导航、连接页面 | `user-guide/getting-started.md`、`docs/README.md` |
## 文档检查
提交文档变更前至少执行：
```bash
git diff --check
rg -n "v2\.1\.7|TraceMemo|迹忆|mcpServers|无鉴权" README.md docs --glob '*.md' --glob '!DOCUMENTATION_AUDIT.md' --glob '!development/overview.md'
```
历史迁移说明可以出现旧版本号；正式使用指南不要把过时版本写成当前版本。负向澄清“6131 不是 MCP Server”可以保留，以防用户照抄错误配置。
docs/mac-disable-sip.md
+3 -45
View File
@@ -1,47 +1,5 @@
# macOS 关闭 SIP 教程
# macOS 数据访问说明（兼容入口）
SIP（System Integrity Protection，系统完整性保护）是 macOS 的系统安全机制。关闭 SIP 会降低系统安全性，只建议在确实需要读取或调试本地微信数据时临时关闭；操作完成后，建议重新开启。
完整内容已移到[macOS 数据访问与系统权限](./platform/macos.md)。
## 准备
- 一台 Mac 电脑，Intel 芯片和 Apple Silicon 芯片均可。
- 需要进入 macOS 恢复模式。
- 请先保存正在编辑的文件，并预留一次重启时间。
## 关闭 SIP
### Intel Mac
1. 关机。
2. 按下开机键后，立刻按住 `Command + R`。
3. 保持按住，直到进入 macOS 恢复模式。
### Apple Silicon Mac（M1/M2/M3/M4）
1. 关机。
2. 长按开机键不放。
3. 直到出现启动选项界面后松开。
4. 选择“选项”，进入 macOS 恢复模式。
### 在恢复模式中执行命令
1. 进入恢复模式后，点击顶部菜单栏的 **Utilities（实用工具）**。
2. 选择 **Terminal（终端）**。
3. 在终端中输入：
```bash
csrutil disable
```
4. 按回车执行。
5. 看到关闭成功提示后，重启电脑。
## 重新开启 SIP
如果后续不再需要关闭 SIP，建议重新进入恢复模式，在终端中执行：
```bash
csrutil enable
```
然后重启电脑。
保留此文件是为了兼容应用内已经发布的帮助链接。请不要把“关闭 SIP”当作默认安装步骤；只有当当前连接页面明确要求时才处理，并在完成后恢复系统安全设置。
docs/platform/macos.md
+27
View File
@@ -0,0 +1,27 @@
# macOS 数据访问与系统权限
## 你什么时候会看到这些提示
WechatExplorer 需要读取微信本地数据。macOS 会根据系统版本、微信状态和安全设置，要求应用完成授权；自动获取数据库密钥时，页面可能提示暂时调整系统安全设置。
## 推荐步骤
1. 先启动 WechatExplorer，阅读连接页面显示的当前前置条件。
2. 确认微信数据目录指向当前账号。
3. 只在页面明确要求时处理系统授权或 SIP；按页面提示完成密钥获取后，恢复你平时使用的安全设置。
4. 返回应用重新检测账号、数据库和图片资源状态。
不要直接复制网上针对其他微信版本的命令。系统授权失败时，记录 macOS 版本、微信版本和页面错误，再按[排障文档](../user-guide/troubleshooting.md#连接微信失败)处理。
## SIP 风险
关闭 System Integrity Protection 会降低 macOS 对系统文件和进程的保护。它不是日常使用 WechatExplorer 的功能开关，也不应长期保持关闭。只有在你理解风险、确认页面要求且完成必要操作时才处理；完成后按 Apple 官方方式重新启用。
## 应用无法打开
如果 macOS 阻止未验证的应用，使用系统“隐私与安全性”中的“仍要打开”选项。不要为了绕过提示下载来历不明的补丁或替换应用文件。
## Intel 与 Apple Silicon
从 Releases 选择与 Mac 处理器匹配的构建。不同架构、微信版本和系统授权状态可能导致连接结果不同；文档不对所有组合做兼容性保证。
docs/skill/wechatexplorer-reader/SKILL.md
+44 -352
View File
@@ -1,372 +1,64 @@
---
name: wechatexplorer-reader
description: 通过本地 HTTP API 读取 WechatExplorer 解锁后的微信聊天数据(本地服务由 WechatExplorer.app 提供)。当用户提到微信聊天记录、群消息、看看群里说了什么、查一下微信、分析微信对话、总结群聊等场景时,使用此技能。注意:此技能的数据源是用户本机 WechatExplorer app。
description: 通过 WechatExplorer 本地 HTTP API 按需读取用户有权访问的微信聊天数据。当用户要求查看微信消息、查找联系人或群聊、总结聊天、生成群聊总结时使用。此 Skill 由本机 WechatExplorer 提供数据，不是 MCP Server。
---
# WechatExplorer Reader
通过本地 HTTP API(`http://127.0.0.1:6131`)读取 WechatExplorer 已经解锁的微信数据库内容。
你是一个通过本机 WechatExplorer 读取微信历史的 Agent。先确认用户已经在 WechatExplorer 中完成数据库连接，再按需调用 API；不要假设数据库已就绪，也不要声称读取了没有调用过的消息。
## 数据源
## 连接信息
- **本服务由 WechatExplorer.app 提供**,数据完全在本地处理,不会上传任何服务器
- 用户必须在 WechatExplorer 主窗口完成**首次密钥配置**(解锁 WCDB 数据库)
- 默认监听 `127.0.0.1:6131`,仅本机可访问
- 除 health 外的 API 均要求 Bearer Token。Token 获取路径:WeChatExplorer → API Center → API Token → 显示/复制 Token
- Base URL 默认是 `http://127.0.0.1:6131/api/v1`。
- `GET /health` 不需要 Token。
- 其他端点必须带 `Authorization: Bearer $WECHATEXPLORER_API_TOKEN`。
- Token 由用户在 WechatExplorer → API Center 显示/复制，并放在 Agent 自己的本地环境中。
- 不要把 Token 放到 URL、回答、日志、Skill 文件或仓库。
- 6131 是普通 Local HTTP API，不是 MCP Server；不要生成 `mcpServers` 配置。
## 前置条件
## 每次任务前
1. **安装并启动 WechatExplorer.app**(从项目 release 页面下载)
2. **首次启动时完成密钥配置**:在主界面第一步输入微信数据库密钥(64 位 hex),完成 WCDB 初始化
3. **如需 7×24 提供 API**:用 `WXE_TRAY=1` 或 `--tray` 参数启动 app,启用菜单栏常驻模式(主窗口关闭后服务仍在)
1. 调用 `/health`，确认服务和数据库状态。
2. 用户说“今天”“昨天”“本周”等相对时间时，先调用 `/current_time`，按返回的本机时区换算日期。
3. 用 `/resolve`、`/contact` 或 `/chatroom` 确认会话标识。
4. 用 `/chatlog` 读取最小必要的时间范围。
5. 对重要结论读取关键消息前后文；不要只凭一次宽范围粗查回答。
## Authentication
## 端点速查
WechatExplorer Reader 使用的是 **WechatExplorer Local HTTP API**,不是 MCP Server。
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/health` | 健康和数据库状态 |
| GET | `/current_time` | 本机时间与时区 |
| GET | `/contact` | 联系人/群聊列表；可传 `filter`、`type` |
| GET | `/chatroom` | 群聊列表；可传 `keyword` |
| GET | `/recent_chat` | 最近会话；可传 `limit` |
| GET | `/chatlog` | 会话消息；必填 `talker`，可传 `time` 或时间戳范围 |
| GET | `/group_snapshot` | 群成员快照；必填 `md5` |
| GET | `/resolve` | 昵称、wxid、md5 解析；必填 `q` |
| POST | `/report` | 将已有日报结构渲染为 HTML/PNG |
| GET | `/agent/status` | Agent Hub、连接器和数据库状态 |
| POST | `/agent/group-report` | 按群和 `today`/`yesterday`/`7days` 生成总结图片 |
| POST | `/agent/send` | 已连接机器人发送测试 |
1. 在 WechatExplorer 中打开 **API Center**。
2. 在 **API Token** 区域点击“复制 Token”。
3. 把 Token 保存到 Agent 自己的本地环境配置中:
## 时间与上下文规则
```bash
export WECHATEXPLORER_API_TOKEN="<YOUR_API_TOKEN>"
```
`/chatlog` 的 `time` 支持 `YYYY-MM-DD`、日期闭区间和分钟范围；也可以使用 Unix 秒级 `startTime`/`endTime`。时间按 WechatExplorer 所在机器的本机时区解释。
health 可以不带 Token:
当用户问“某个话题是谁说的、后来结论是什么”时，先定位会话和时间，再读取关键消息前后文。回答时区分：
```bash
curl http://127.0.0.1:6131/api/v1/health
```
- 原消息明确写出的内容；
- 根据多条消息整理出的总结；
- 没有来源支持的推断。
除 health 外,所有请求必须使用标准 Bearer header:
## 隐私和安全
```bash
curl -H "Authorization: Bearer $WECHATEXPLORER_API_TOKEN" \
http://127.0.0.1:6131/api/v1/recent_chat
```
只读取用户请求所需的会话和时间范围。不要把完整聊天数据库、密钥或 Token 暴露给用户。Reader API 本身不自动把聊天转发到外部服务器，但当前 Agent 可能会把工具结果交给其配置的模型；如有疑问，提醒用户检查 Agent 的数据策略。
本文件后续写出的所有 `GET` / `POST` 数据请求都默认包含上述 Authorization header。禁止把 Token 放入 URL query、路径、Skill 文件或仓库。
## 常见错误
## API 列表
GET 用于读取数据,`POST /api/v1/report` 用于生成群日报(HTML + 长图)。所有端点返回 JSON。
| 端点 | 用途 | 关键参数 |
| ---------------------------- | ------------------------------------- | ----------------------------------------------------------------- |
| `GET /api/v1/health` | 健康检查 + 是否已初始化 | — |
| `GET /api/v1/current_time` | 获取当前本地时间(用于"今天/昨天"换算) | — |
| `GET /api/v1/contact` | 联系人 / 群聊列表 | `filter`(昵称模糊)、`type`(`user` \| `group`) |
| `GET /api/v1/chatroom` | 群聊列表(等同 contact?type=group) | `keyword` |
| `GET /api/v1/recent_chat` | 最近会话 | `limit`(默认 50) |
| `GET /api/v1/chatlog` | 聊天记录 | `talker`、`time` 或 `startTime`/`endTime` |
| `GET /api/v1/group_snapshot` | 群成员快照 | `md5` |
| `GET /api/v1/resolve` | 把昵称/wxid/md5 解析成 md5 | `q` |
| `POST /api/v1/report` | 生成群聊日报 HTML + 长图 PNG | JSON body(见下文,推荐传 `metadata.talker` 让服务端自动反推真头像) |
### `talker` 参数可接受的值
`chatlog` 和 `recent_chat` 的 `talker` / 列表项 ID 支持以下三种形式,服务端会按 `nickname → wxid → md5` 顺序匹配:
1. **群昵称 / 好友备注**(模糊匹配,如 `技术交流`、`摸鱼群`)
2. **微信 wxid**(如 `wxid_abc123`、`gh_xxxxx@chatroom`)
3. **会话 md5**(如 `49023470180@chatroom` 的 md5 哈希,可在 `contact` 接口里看到)
不确定时先调 `GET /api/v1/resolve?q=<输入>` 校验,返回 `{ md5, m_nsUsrName, m_nsNickName, type, ... }`。
### `chatroom` 与 `contact?type=group` 字段一致性
`/chatroom` 和 `/contact?type=group` 返回的是**同一个集合**(都是 `listContacts().filter(type==='group')`),字段也完全一致:
```json
{
"m_nsUsrName": "49023470180@chatroom", // wxid, 用作 chatlog 的 talker
"m_nsNickName": { "buffer": "...", "type": "Buffer" }, // nickname 原 buffer
"type": "group",
"md5": "..."
}
```
需要 `displayName` 时从 `m_nsNickName` 里解析;需要拉消息就传 `m_nsUsrName` 当 talker。
## 时间范围格式(`time` 参数)
支持以下格式:
| 输入 | 含义 |
| ----------------------------------- | ---------------------------- |
| `2026-07-03` | 单日 00:00:00 ~ 23:59:59 |
| `2026-07-01~2026-07-03` | 日期范围(闭区间) |
| `2026-07-03/14:30` | 单分钟(从 14:30:00 起 60 秒) |
| `2026-07-03/14:30~2026-07-03/15:30` | 精确到分钟的范围 |
也可以直接传 unix 秒级时间戳作为 `startTime` 和 `endTime`。
### "今天 / 昨天 / 本周" 的时区语义
所有 `time` / `startTime` / `endTime` 都按**用户本机时区**解析(由 `current_time` 里的 `timezone` 字段给出,典型为 `Asia/Shanghai`)。含义如下:
- "今天 2026-07-03" → 本机 2026-07-03 00:00:00 ~ 23:59:59(北京时间 24 小时),**不是** UTC 当天
- "昨天" → 本机昨天 0 点 ~ 23:59:59
- "本周" → 本周一 0 点 ~ 当前时刻(按本机时区所在周的周一)
跨时区时(如用户在国外):仍以本机时区为准,需要按 UTC 处理时显式传 unix 时间戳。
## 时间预检工作流(Time-Aware Workflow)
**重要**:只要用户请求中包含"今天"、"昨天"、"本周"、"刚才"等相对时间概念,**禁止**直接生成日期字符串。
**步骤 1**:先调用 `current_time` 工具获取本地 RFC3339 时间。
**步骤 2**:根据返回的时间计算对应的 `time` 参数。
**步骤 3**:用计算后的参数调 `chatlog`。
示例:
- 用户: "今天 摸鱼交流群 聊了啥?"
- AI: 先 `GET /api/v1/current_time` → 得到 `2026-07-03T14:30:00+08:00` → 计算 `time=2026-07-03` → `GET /api/v1/chatlog?talker=摸鱼交流群&time=2026-07-03`
## 多步上下文检索(强制)
当查询特定话题或特定发送者发言时,**必须**按以下流程操作:
1. **初步定位**:用 `contact` 或 `chatroom` 端点确定群聊 md5 / wxid
2. **粗查**:用 `chatlog` + 较宽时间范围找到相关消息时间点
3. **精查**:对每个关键时间点分别查前后 15-30 分钟(不带任何 keyword 过滤),用完整上下文分析
**禁止**:仅凭一次粗查结果直接回答用户。
## 生成群日报(POST /api/v1/report)
当用户希望输出**可视化群日报**(长图 PNG + HTML 邮件版)时,用这个端点。WechatExplorer 内置 `mobile_daily_report.html` 模板,渲染后会同时落盘 `htmlPath` 和 `pngPath`,并返回 `imageDataUrl` 可直接预览。
### 请求体(`GroupReportExportRequest`)
```json
{
"report": {
"overview": "一句话总览,20-80 字",
"topics": [
{
"title": "话题标题",
"timeRange": "10:00-12:30",
"heat": "高", // "高" | "中" | "低"
"participants": ["张三", "李四"],
"summary": "本话题讨论了什么",
"conclusion": "可选,达成的结论",
"keywords": ["关键词1", "关键词2"]
}
],
"resources": [{ "title": "链接/文件标题", "description": "为什么重要", "sender": "张三" }],
"importantMessages": [
{ "sender": "张三", "time": "10:23", "content": "原消息文本", "note": "为什么重要" }
],
"quotes": [
{
"messages": [
{ "sender": "李四", "content": "原话1" },
{ "sender": "王五", "content": "原话2" }
],
"note": "为什么这些话值得引用"
}
],
"qa": [{ "question": "Q", "answer": "A", "answerer": "解答人(可选)" }],
"unresolved": [
{
"question": "待跟进问题",
"owner": "相关人(可选)",
"status": "待跟进",
"note": "为什么还没结束"
}
],
"storylines": [
{
"title": "剧情线",
"stages": [{ "time": "10:12", "event": "提出问题" }],
"result": "可选结果"
}
],
"reversals": [
{ "topic": "某话题", "initialView": "最初判断", "finalView": "最终判断", "note": "可选说明" }
],
"participantChains": [
{ "topic": "某话题", "chain": ["A 提出", "B 补充", "C 收尾"], "note": "可选说明" }
],
"analytics": {
"topicHeat": [{ "topic": "话题1", "score": 9.5 }],
"activeTimeline": "10:00-12:00 为最活跃时段",
"topSpeakers": [{ "name": "张三", "count": 58 }],
"voiceLeaderboard": [{ "sender": "张三", "count": 3, "durationSec": 97 }]
},
"keywords": ["高频词1", "高频词2"],
"hero": {
"headline": "一句抓重点的日报标题",
"summary": "一句概览",
"keyTakeaway": "最重要结论",
"pendingNote": "待跟进事项"
}
},
"metadata": {
"groupName": "技术交流",
"reportDate": "2026-07-03",
"dateRange": "2026-07-03 全天",
"messageCount": 1234,
"activeUsers": 56,
"timeSpan": "00:00-23:59",
"generatedAt": "2026-07-03 22:00",
"recordNote": "本日报由 WechatExplorer 自动生成",
"footerNote": "底部附加说明",
"heroParticipants": ["张三", "李四"],
"avatars": {},
"talker": "技术交流",
"timeRange": "2026-07-03"
}
}
```
### 响应(`GroupReportExportResult`)
```json
{
"success": true,
"htmlPath": "/Users/.../Desktop/技术交流_日报_2026-07-03.html",
"pngPath": "/Users/.../Desktop/技术交流_日报_2026-07-03.png",
"imageDataUrl": "data:image/png;base64,iVBORw0K..."
}
```
成功返回 200;失败返回 500 + `{ success: false, error: "..." }`。HTML 和 PNG 用 `mobile_daily_report.html` 模板渲染,长图宽度自适应移动端预览。
### 典型工作流
1. 调 `current_time` + `chatlog` 拉取当天/目标时间段消息
2. LLM 总结生成 `report` + `metadata`(直接走 AI 总结即可,无需自己造数据)
3. POST 到 `/api/v1/report` 拿到 `htmlPath` / `pngPath`,把文件路径告诉用户即可在 Finder 打开
4. **不要**自己拼 HTML/PNG,模板已内置,只需组织好 report/metadata 字段
### 必填字段与隐式约束(踩坑提示)
`metadata` 的以下字段**必填**,缺一返回 500:
- `groupName`、`reportDate`、`dateRange`、`generatedAt`
- `heroParticipants`:数组,模板会把每个名字当 key 去 `metadata.avatars[name]` 取头像图
- `avatars`:对象,**每个 `heroParticipants` 里的名字都必须有这个 key**(没有就传 `""`,**不要省略整段**),否则模板渲染会抛 `Cannot read properties of undefined (reading '<名字>')` 报 500
`report` 的以下字段**必须存在**(空就传 `[]`,**不能省略**),否则模板遍历时会抛 `Cannot read properties of undefined (reading 'map')` 报 500:
- `report.topics`(至少 1 个,完全没话题就改用纯文本总结,不要硬生成空日报)
- `report.resources`
- `report.importantMessages`
- `report.quotes`
- `report.qa`
- `report.analytics.topicHeat`
- `report.analytics.topSpeakers`(至少 1 个)
- `report.keywords`
最小安全示例:
```json
{
"report": {
"overview": "...",
"topics": [],
"resources": [],
"importantMessages": [],
"quotes": [],
"qa": [],
"analytics": { "topicHeat": [], "activeTimeline": "", "topSpeakers": [] },
"keywords": []
},
"metadata": {
"groupName": "技术交流",
"reportDate": "2026-07-07",
"dateRange": "2026-07-07 全天",
"heroParticipants": ["张三", "李四"],
"avatars": { "张三": "", "李四": "" }
}
}
```
`report.importantMessages[].time` 用 `HH:mm` 格式(不要 ISO 时间戳);`report.analytics.topicHeat[].score` 数字 0-10。
### 4 个数字格子的内容必须紧凑(避免塌陷)
模板顶部的 4 个统计格(`消息数 / 活跃人数 / 时间跨度 / 主要话题`)宽度均分,内容过长会被截断或换行:
| 字段 | 推荐格式 | 反例(会撑爆格子) |
| ------------------------ | --------------------------------------------------- | -------------------------------------- |
| `metadata.messageCount` | 纯数字 `"1234"` | `"约 1.2k 条"` |
| `metadata.activeUsers` | 纯数字 `"56"` | `"大约 50 多人"` |
| `metadata.timeSpan` | **持续时长紧凑半角** `"1 h"` / `"30 min"` / `"2 d"` | `"1 小时"` / `"7 小时"` / `"1天3小时"` |
| `metadata.topicCount` 等 | 数字 / 短中文 | 长句子 |
`timeSpan` 是**首条到末条消息的持续时长**,不是时间区间。**单位用半角空格分隔**:
- `< 1 h` → `"30 min"`
- `1~24 h` → `"1 h"` / `"7 h"`(整数,向上取整)
- `> 24 h` → `"2 d"`(整数,向上取整)
**首末条消息的具体时间点**:`dateRange` 字段会显示完整日期 + 起止时间(无长度限制),模板里 dateRange 是 hero 区的副标题,跟 stat 格子分开。
**区间叙事**(如"主要集中在上午 10 点-12 点")放 `report.analytics.activeTimeline`,那是模板里单独一段的描述,不被 stat 格子限制。
**不传 timeSpan**:服务端会用空字符串渲染(stat 格会空),subagent 应当总是算好时长填进来,或者 renderer 端会自动算(见 renderer 源码)。
### 头像:服务端自动反推(推荐)
**v1.4 起无需手动拼 `avatars` 字典**。在 `metadata` 里加 `talker`(群昵称/wxid/md5 都行),服务端会用 `getGroupSnapshot` 拉全量群成员,按 `nickname → avatar` 自动反推填进 `metadata.avatars`。LLM 总结里出现的 `heroParticipants` / `topics[].participants` / `topSpeakers[].name` 等所有名字都会被覆盖。
**优先级**:客户端传的 `avatars[name]`(非空字符串) > 服务端反推 > 占位 SVG(姓名首字母 + 随机色块)。
**回退**:不传 `talker` 时按 `metadata.avatars` 字典取;还取不到则生成 SVG 占位(`fallbackAvatar`),**不会变空白方块**(v1.4 修了 data URL 正则,SVG 占位能正常嵌入)。
**手动覆盖**:仍可传 `avatars` 字典强制使用自定义头像,例如 `{"张三": "data:image/jpeg;base64,..."}`。
**P2 风险**:群里有两人同名(如"杨伟")时,服务端只取首条;客户端可手动覆盖。
## 隐私安全原则
1. **最小化原则**:只返回用户明确请求的内容,不过度展开无关聊天
2. **本地处理**:所有数据来自用户本机,API 不缓存、不转发
3. **摘要优先**:对于大量聊天记录,先提供摘要而非完整 dump
4. **用户确认**:涉及敏感内容时,先展示摘要,让用户决定是否继续深入
## 典型工作流示例
**示例 1:今日群聊总结(纯文本)**
1. `GET /api/v1/current_time` → 获取今天日期
2. `GET /api/v1/chatroom?keyword=技术交流` → 找到目标群 md5
3. `GET /api/v1/chatlog?talker=技术交流&time=2026-07-03` → 拉取今天的聊天
4. AI 用 LLM 生成总结报告(话题 TOP N、最活跃发言者等)
**示例 2:搜索特定消息上下文**
1. `GET /api/v1/chatlog?talker=摸鱼群&time=2026-07-01~2026-07-03` → 粗查近 3 天
2. 在返回的消息中定位关键词出现的时间点 T1, T2, ...
3. 对每个 Ti 分别查 `chatlog?talker=摸鱼群&time=Ti-15min~Ti+15min`,分析上下文
**示例 3:群日报(可视化长图)**
1. `GET /api/v1/chatlog?talker=技术交流&time=2026-07-03` → 拉今天聊天
2. LLM 按上方 `GroupDailyReport` schema 总结出 `report` + `metadata`
3. `POST /api/v1/report` body = 上述 JSON → 拿到 `htmlPath` / `pngPath` / `imageDataUrl`
4. 把 `imageDataUrl` 给用户预览,把 `pngPath` 路径告诉用户用 Finder 打开
## 错误处理
- `401 unauthorized` → Token 缺失、格式错误、已被重新生成或配置不正确;请回到 API Center 复制当前 Token
- `503` → WechatExplorer 未初始化(密钥未配置),提示用户在主窗口完成配置
- `404 talker not found` → talker 不存在,先调 `contact` 或 `resolve` 确认 md5/wxid
- `400 missing required parameter` → 检查必填参数(talker / md5 / q)
- `200` 但 `result.warnings: ['enrich skipped: talker "X" not found']` → `/report` 的 `metadata.talker` 解析失败,头像走 SVG fallback(不阻断生成)
- `200` 但 `result.warnings: ['enriched N member avatars from snapshot (M members)']` → enrich 成功(诊断用)
- `400 请求体为空 / 需包含 report 和 metadata` → 调用 `/report` 时 body 必须是非空 JSON,且有这两个顶层字段
- `500 success=false` → 模板渲染失败,通常因 `report` 字段缺失或 `metadata.groupName/reportDate` 为空,检查后重试
## 配置 Codex / Claude Code / OpenClaw
- **Codex**:安装本 Skill,并在启动 Codex 的本地 shell 或项目私有环境中设置 `WECHATEXPLORER_API_TOKEN`。
- **Claude Code**:安装本 Skill,并在启动 Claude Code 的本地 shell 或私有环境配置中设置 `WECHATEXPLORER_API_TOKEN`。
- **OpenClaw**:安装本 Skill,把 `WECHATEXPLORER_API_TOKEN` 放入 OpenClaw 自己的本地 secret / environment 配置。
- **其他 Agent**:确保执行 HTTP 请求的本地进程能读取 `WECHATEXPLORER_API_TOKEN`。
不要把 `http://127.0.0.1:6131` 配置成 `mcpServers.url`;6131 提供的是 Local HTTP API,不是 MCP Server。
- `401`：Token 缺失、错误或被轮换；请用户回 API Center 复制最新 Token。
- `403`：浏览器 Origin 不在 loopback 允许列表；CLI/Agent 通常不带 Origin。
- `404`：先用 `/resolve` 确认会话标识。
- `503`：用户还没有完成数据库连接或对应服务未就绪。
- 空结果：缩小/扩大时间范围，确认账号和会话，再检查媒体或语音是否可读。
docs/user-guide/ai-search.md
+60
View File
@@ -0,0 +1,60 @@
# 用 AI 查找你以前聊过的信息
## AI Search 是什么
你可以把它理解成“会帮你翻聊天记录的 AI”。
普通搜索需要你猜关键词；AI Search 更适合这些问题：
- “我们上个月为什么决定延期？”
- “谁提过这个项目，后来结论是什么？”
- “过去一周有哪些待跟进事项？”
它会先在本机查找相关聊天，再把受控范围内的内容交给你选择的 AI Provider 生成回答。它不是凭空记忆，也不是把整库聊天一次性上传。
## 第一次使用
1. 进入“设置 → AI 模型”，添加一个 Provider，填写服务地址、模型和认证信息，然后测试连接。
2. 打开“问问微信”。
3. 根据问题选择时间范围和会话范围；范围越明确，答案越容易核对。
4. 输入问题并开始分析。
如果知识库尚未建立，页面会提示你建立或同步；你也可以先直接使用当前可用的搜索路径。
## 怎么提问更容易得到好结果
把“谁、什么时候、在哪个群、想找什么结果”写出来。例如：
> “在产品交流群里，查找 2026 年 7 月讨论发布延期的消息，列出结论和待办。”
尽量避免只写“总结一下”。如果你只记得模糊含义，也可以先提问，再根据来源缩小范围继续追问。
## AI 回答后先看什么
不要只看结论。回答区域通常还会展示：
- 参考了哪些聊天内容；
- 来源来自哪个会话、发送者和时间；
- 哪一段回答对应哪条来源；
- 本次查找经过了哪些阶段、耗时和覆盖情况；
- 是否存在未转写语音、媒体不可用或结果不完整的提示。
你可以点击来源回到档案中的原始消息。产品内部将这些信息称为 Evidence、Citation 和 Search Trace，用户可以把它们理解为“依据、来源标记和查找过程”。详见[如何核对 AI 的回答来源](../concepts/answer-sources.md)。
## 什么时候不要直接相信答案
- 来源很少，或时间范围与问题不一致；
- 回答提到了来源中没有的细节；
- 关键内容来自未转写语音、无法读取的图片或转发消息；
- 页面提示只覆盖了部分聊天。
这些情况下，打开原消息，扩大或缩小范围，再重新提问。必要时把问题改成“只列出原文明确说过的内容”。
## 取消、失败和降级
分析过程中可以取消当前任务。检索或模型请求失败时，页面可能保留已找到的来源或切换到备用路径；这不代表一定得到了完整答案。请查看提示、检索详情和[排障文档](./troubleshooting.md#ai-没有结果或回答失败)。
## 数据会发到哪里
本地解析、索引和候选消息查找在本机完成。只有完成 AI 任务所需的用户问题、受控检索上下文和最终用于总结的来源内容，才可能发送到你配置的 Provider；具体边界见[数据、隐私与安全](./privacy.md)。
docs/user-guide/chat-archive.md
+50
View File
@@ -0,0 +1,50 @@
# 查看和搜索聊天
“档案”是你直接阅读微信历史的地方。适合查原文、回看上下文、确认 AI 来源，也适合在你已经知道关键词时快速定位。
## 选择要看的会话
左侧会话列表可以浏览联系人、群聊、折叠群聊和公众号等已读取到的会话。选中会话后，右侧显示消息时间线；滚动到较早位置可以继续加载历史。
如果你从 AI 回答的来源进入档案，应用会自动切换到对应会话并尽量定位到消息时间。
## 普通关键词搜索什么时候最好用
当你记得以下任意信息时，优先使用档案搜索：
- 一段原话或关键词；
- 人名、群名、项目名；
- 链接、文件名或订单号；
- 大致知道在哪个联系人或群里。
关键词搜索速度快、结果直观，但它不会理解“意思相近但没有相同词”的问题。
## 消息和媒体
根据微信数据中实际可用的资源，档案可以展示文本、图片、视频、语音、文件、链接、引用、小程序、表情和系统消息等类型。媒体是否能显示，取决于本机原始资源是否仍然存在、权限是否完整以及当前微信版本的存储方式。
不要把“消息类型已读取”理解成“所有媒体都一定能解码”。遇到图片或视频空白时，请先检查[媒体与导出排查](./troubleshooting.md#媒体显示或导出异常)。
## 保护自己不被误导
档案中的原始消息是核对 AI 结果的最终依据。看到 AI 的总结、日报或来源时，建议：
1. 打开来源对应的会话；
2. 查看消息前后几条上下文；
3. 注意消息时间、发送者和是否存在转发/引用；
4. 对未转写的语音、无法读取的图片保持不确定判断。
## 常见问题
### 会话列表为空
确认数据库连接成功、连接的是正确微信账号，并重新加载数据。若仍为空，查看[连接微信失败](./troubleshooting.md#连接微信失败)。
### 搜索不到明明存在的消息
先缩小到正确会话，再尝试更短的关键词或原文片段。对于“以前讨论过什么”这类语义问题，改用[AI Search](./ai-search.md)。
### 想跨多个会话查找
使用“问问微信”，并在问题中写清时间范围、人物或群聊范围。需要更稳定的跨会话查找时，先建立[本地知识库](./knowledge.md)。
docs/user-guide/export.md
+34
View File
@@ -0,0 +1,34 @@
# 导出聊天和报告
导出适合把微信里的重要讨论保存成可阅读、可分享或可继续处理的文件。
## 支持的格式
- **HTML**：适合完整阅读，可包含媒体和头像；
- **Markdown**：适合笔记、版本管理和再次编辑；
- **CSV**：适合表格分析；
- **JSON**：适合程序处理和数据归档。
## 导出步骤
1. 打开“导出”。
2. 选择一个或多个联系人/群聊。
3. 选择时间范围和消息类型。
4. 按需要打开媒体、头像、原图/缩略图、语音转写和保留缺失资源等选项。
5. 设置文件名，必要时选择 ZIP，然后开始导出。
6. 在导出任务中心查看读取、解析、媒体处理、转写、写入和压缩进度；完成后打开文件位置。
## 多会话和增量导出
HTML 支持把最多五个会话合并到一个档案中。再次使用相同名称导出时，可以把新消息增量合并到已有档案；这不会删除之前已导出的消息。
## 媒体怎么处理
原图、缩略图、缺失资源和头像都可能影响导出大小与可读性。想要小文件时关闭媒体或选择缩略图；想要长期保存时，确认原始媒体目录仍可访问，并考虑 ZIP 归档。
语音转写是可选步骤。只有已经成功转写的语音才会写入导出内容，导出不会替你自动补齐失败的识别。
## 导出和原始数据的关系
导出是复制/整理结果，不会修改微信原始数据库。删除导出文件也不会影响应用内聊天记录或本地知识库。
docs/user-guide/getting-started.md
+71 -207
View File
@@ -1,250 +1,114 @@
# WechatExplorer：第一次使用与问题排查
# 第一次使用 WechatExplorer
这份说明解决三件事：第一次连接微信、连接成功后如何开始使用，以及遇到问题时如何自助排查。
如果你刚下载 WechatExplorer，只需要完成一条主线：
如果你已经进入软件，忘记了连接步骤，可以直接点击左下角「新手引导」，重新查看首次连接流程、AI 配置入口和群聊日报入口。
> 安装应用 → 连接微信数据 → 确认聊天已加载 → 搜索或提问。
## 你现在要做什么
这篇文档不要求你先学习内部术语；先把第一个问题问出来，之后再按需要深入了解产品名称和进阶功能。
- [我第一次使用，想连接微信](#第一次连接微信)
- [我已经连接成功，下一步做什么](#连接成功后做什么)
- [我想重新查看引导](#重新查看新手引导)
- [我想配置 AI](#配置-ai)
- [我遇到问题](#遇到问题)
- [我想让 Agent 读取微信](#接入-api-reader-skill-或-agent)
## 1. 开始前准备
> 正常覆盖安装只会替换应用程序文件，WechatExplorer / 迹忆不会主动删除或修改微信原始聊天记录。应用缓存和本地设置可能随版本升级发生变化。系统故障、磁盘异常、误操作和微信自身迁移不受本应用控制，因此升级前仍建议使用微信官方迁移或备份功能备份重要聊天记录，不要将唯一副本保存在单一设备。
- 一台 macOS 或 Windows 电脑。
- 已安装并使用过微信桌面客户端。
- 你有权访问要读取的微信账号和聊天数据。
- 如果要使用 AI 问答、群聊日报或图片理解，还需要在应用中配置一个 AI 服务。
## 开始前确认
当前代码按微信 4.x 数据结构处理。不同微信客户端版本、系统权限和数据迁移状态可能影响自动连接；遇到问题时请查看[常见问题与排查](./troubleshooting.md)。
| 系统 | 已测试的微信客户端 | 需要注意 |
| ------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| macOS | [微信 macOS `4.1.8.100`](https://github.com/zsbai/wechat-versions/releases/tag/4.1.8.100) | 自动获取数据库密钥前需要关闭 SIP 并完成授权 |
| Windows | [微信 Windows `4.1.9.57`](https://github.com/iibob/wechat-win-archive/releases#release-v4.1.9.57) | 已完整支持；首次使用时请确认微信数据目录 |
## 2. 安装并启动
- WechatExplorer 当前面向微信 4.0 数据结构。
- Windows 不需要关闭 SIP。
- macOS 首次自动获取数据库密钥需要按页面提示完成系统授权。
- WechatExplorer 必须取得当前微信账号对应的数据库密钥才能读取聊天记录。
- 请只处理你有权访问的微信数据。
1. 从 [GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) 下载对应系统的安装包。
2. Windows 使用 `-setup.exe` 安装；macOS 打开 `.dmg` 并将应用拖入“应用程序”。
3. 启动 WechatExplorer，进入“第一次使用”页面。
WechatExplorer / 迹忆应用安装包：[GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases)。Windows 选择 `-setup.exe`，macOS 按处理器架构选择对应 `.dmg`。微信客户端请使用上方“已测试的微信客户端”链接。
macOS 如果提示无法验证开发者，请按系统提示允许打开。自动获取数据库密钥需要额外系统授权时，先阅读[macOS 数据访问说明](../platform/macos.md)。不要在不理解风险的情况下长期关闭系统安全保护。
## 第一次连接微信
## 3. 让应用读取微信数据
### 1. 安装 WechatExplorer
第一次打开时，应用会引导你完成数据库连接。核心是两件事：找到当前微信数据目录，并取得对应账号的数据库密钥。
#### Windows
1. 在连接页面确认微信数据目录。自动识别不准确时，打开微信设置中的缓存/存储管理，复制实际路径后粘贴到页面。
2. 第一次使用先点击“开始连接”，按页面提示准备连接组件和获取密钥；只有已经通过其他方式拿到密钥的高级用户才选择“手动连接”。
3. 如果自动获取要求微信处于特定登录状态，请按页面提示完成登录、授权或重新检测；不要只关闭微信窗口就认为已经退出。
4. 点击开始连接，等待数据库、账号和联系人检查完成。
1. 从 Releases 下载 Windows `-setup.exe` 安装包。
2. 双击安装包，按向导完成安装。
3. 启动 WechatExplorer。
连接页面会显示微信状态、数据库状态和诊断结果。连接失败时先不要反复删除数据，优先查看[连接问题排查](./troubleshooting.md#连接微信失败)。
#### macOS
## 4. 确认第一次连接成功
1. 从 Releases 下载 `.dmg` 文件。
2. 打开 DMG，将 WechatExplorer 拖入“应用程序”文件夹。
3. 如果系统提示“无法打开，因为开发者无法验证”，前往“系统设置 → 隐私与安全性”，点击“仍要打开”。
4. 如果系统提示应用已损坏，可在终端执行：
连接成功后会进入“档案”页面。你可以用下面三个信号确认已经准备好：
```bash
xattr -cr "/Applications/WechatExplorer.app"
```
- 左侧出现联系人或群聊列表；
- 选中一个会话后，右侧能看到历史消息；
- 搜索框可以在当前会话中定位文字。
5. 如果这是第一次在 macOS 上自动获取数据库密钥，先完成 [关闭 SIP 教程](../mac-disable-sip.md)。关闭 SIP 会降低系统安全性，完成密钥配置后建议重新开启。
如果联系人列表为空，先检查是否连到了正确账号和数据目录，再重新加载会话。
### 2. 按软件内引导连接微信
## 5. 完成你的第一个任务
首次启动会自动进入「第一次使用」页面。页面会根据当前系统显示连接方式和注意事项：
### 只是想找一句话
<p align="center">
<img src="../../public/setup-page.png" alt="第一次使用连接页面" width="820" />
</p>
进入“档案”，选择联系人或群聊，在会话内搜索关键词。适合你记得原话、姓名、链接或大致关键词的情况。
通常按下面三步操作即可：
### 想找一个模糊的结论
1. **确认微信数据目录**：自动识别不准确时，在页面中修改存储路径。
2. **让微信停在登录页面**：如果微信已经登录，先退出微信登录，不只是关闭窗口。
3. **点击开始获取**：软件会尝试获取数据库密钥。按提示可以登录后，再回到微信完成登录。
进入“问问微信”，直接描述问题，例如：
Windows 已完整支持，不需要关闭 SIP。macOS 首次获取密钥前，需要按页面提示完成授权并关闭 SIP。
- “上个月技术群讨论过哪些发布问题？”
- “张三之前发过的项目地址在哪里？”
- “过去一周有没有人提到退款？”
### 3. 连接成功
这就是 AI Search：它会先帮你从本机聊天中找出相关内容，再让你配置的模型组织答案。你不需要知道关键词在哪，但问题越具体，结果越容易核对。
连接成功后，软件会进入聊天档案，并显示「开始探索你的微信」引导：
### 想让 AI 的答案可核对
<p align="center">
<img src="../../public/first-use-welcome.png" alt="连接成功后的新手引导" width="760" />
</p>
回答生成后，打开来源或检索详情，查看它参考的聊天内容、会话、时间和原始消息。你可以从来源直接跳回“档案”检查上下文。
这里推荐先体验「AI 群聊日报」，也可以直接查看聊天、问问微信或配置 AI 模型。
产品把这些来源信息分别称为 Evidence、Citation 和 Search Trace；普通使用时只需要记住“答案可以回到原消息核对”即可。详见[如何核对 AI 的回答来源](../concepts/answer-sources.md)。
## 连接成功后做什么
## 6. 接下来可以做什么
### AI 问问微信
- [查看和搜索聊天](./chat-archive.md)
- [使用 AI 查找聊天信息](./ai-search.md)
- [建立本地知识库，让后续查找更稳定](./knowledge.md)
- [生成群聊日报或总结](./report.md)
- [转写微信语音](./voice.md)
- [导出聊天档案](./export.md)
- [连接外部 Agent 或微信机器人](../agent/overview.md)
打开「问问微信」，用自然语言向自己的微信提问，例如：
## 7. 想让微信机器人参与实时对话
- “技术群这周讨论了哪些问题？”
- “帮我找到张三发过的项目地址。”
- “去年我和老板聊过哪些关于涨薪的事情？”
如果你希望直接在微信里向本机助手提问，而不是在外部 Agent 中查询，请使用 Agent Hub：
如果还没有配置 AI，点击「设置 → AI 模型」添加模型服务商并测试连接。
1. 先完成上面的微信数据库连接，并确认“档案”里能看到聊天。
2. 打开应用主导航中的“Agent”；页面标题为“Agent Hub”。
3. 确认 Agent Hub 显示“运行中”，数据 API/数据库状态可以查询。
4. 点击“扫码登录微信机器人”，用微信扫描二维码，并在手机上确认登录。
5. 状态变为“在线”后，向这个机器人发送文字消息。
### AI 群聊日报
可以先试试这些真实支持的请求：
1. 打开「日报」。
2. 选择一个群聊和时间范围。
3. 按需要选择日报内容和模板。
4. 开始生成，完成后查看或导出 HTML 与 PNG。
- “最近 5 个会话”；
- “帮我看看最近跟张三聊了些什么”；
- “生成产品交流群今天的群聊总结图片”。
日报会整理讨论摘要、关键主题、重要消息、资源、问题和待跟进事项，并保留证据来源。
机器人会把处理结果回复给发消息的人。联系人聊天总结、群聊总结和需要理解自然语言的请求依赖“设置 → AI 模型”中已经配置好的 AI 服务。当前实时入口主要处理文字消息；它不是支持任意图片、语音、文件理解、群发或定时任务的通用机器人。机器人账号扫码登录与读取你微信数据库是两条独立流程，都需要分别确认账号和权限。
### 查看聊天
## 8. 需要配置 AI 吗？
1. 打开「档案」。
2. 选择好友或群聊。
3. 浏览历史消息，也可以按关键词定位会话。
不一定。浏览聊天、普通关键词搜索、建立本地知识库和导出不要求在线 AI 服务。
### 导出聊天
使用“问问微信”、群聊日报或图片理解时，需要在“设置 → AI 模型”中添加并测试 AI 服务。你主动开始并确认远程 AI 功能后，完成任务所需的内容才可能发送给该服务；计费、留存和地区规则由对应服务商决定。
打开「导出」，选择联系人或群聊、时间范围和格式。支持 HTML、CSV、JSON 和 Markdown。
## 9. 数据和隐私的最低须知
## 重新查看新手引导
- 微信数据库、聊天解析和本地索引默认留在本机。
- 离线语音转写使用本地模型；它与在线 AI 请求是两条不同的数据路径。
- 你主动开始并确认 AI 问答或日报后，完成任务所需的受控上下文才可能发送给你选择的 AI 服务；打开应用不会自动上传全部聊天。
- 应用内 Local HTTP API 默认只监听 `127.0.0.1:6131`，受保护接口需要 Token。
连接成功后，首次弹窗关闭不会影响功能使用。需要重新查看时，点击主界面左下角的「新手引导」：
完整边界见[数据、隐私与安全](./privacy.md)。
<p align="center">
<img src="../../public/guide-entry.png" alt="主界面左下角新手引导入口" width="760" />
</p>
## 10. 如果你卡住了
新手引导会再次展示：
- AI 群聊日报入口。
- 查看聊天记录入口。
- 问问微信入口。
- AI 模型配置入口。
- 完整使用教程入口。
## 配置 AI
WechatExplorer 支持 OpenAI 兼容接口，也提供 DeepSeek、OpenAI、Claude、Moonshot 等常用配置方式。
1. 进入「设置 → AI 模型」。
2. 添加模型服务商并填写 API Key。
3. 确认 Base URL 和模型名称正确。
4. 保存并测试连接。
5. 返回「问问微信」或「日报」重试。
AI 功能使用你配置的模型服务。相关聊天内容会按请求发送给该服务；是否启用以及使用哪一个服务由你决定。
## 遇到问题
先判断你遇到的现象，再按对应路径处理。
| 现象 | 优先检查 |
| --------------------------------- | -------------------------------------------------------- |
| 软件打不开 | macOS 安全提示或应用损坏处理；Windows 重新运行安装包 |
| 找不到微信数据 | 在首次连接页面或设置中确认数据目录，Windows 检查目录层级 |
| 获取不到数据库密钥 | 微信是否停留在登录页面、微信和应用是否同时运行 |
| 数据库连接失败 | 当前账号是否匹配、微信版本是否兼容、数据库目录是否正确 |
| 已连接但图片不显示 | 配置图片 XOR Key 和 AES Key |
| AI 问问微信或日报不可用 | 在「设置 → AI 模型」配置并测试模型服务 |
| API、Reader Skill 或 Agent 不可用 | 先连接数据库，再确认 API 服务状态和对应配置 |
### 软件打不开
#### macOS
- 出现“无法打开，因为开发者无法验证”：前往“系统设置 → 隐私与安全性”，点击“仍要打开”。
- 出现“应用已损坏”：确认应用位于“应用程序”目录，再执行：
```bash
xattr -cr "/Applications/WechatExplorer.app"
```
#### Windows
确认下载的是 Releases 中的 `-setup.exe` 安装包，并按安装向导完成安装。Windows 不需要关闭 SIP。
### 找不到微信数据
在首次连接页面确认“存储路径”。如果没有自动识别：
1. 打开「设置」。
2. 手动选择微信数据所在目录。
3. 返回连接页面，重新测试连接。
Windows 当前不会扫描二级目录，请确认目录没有多选或少选一层目录。
### 获取不到数据库密钥
按顺序检查：
1. 微信版本是否与上方已测试版本一致。
2. 点击“开始获取”时，微信是否停留在未登录页面。
3. 微信和 WechatExplorer 是否都保持运行。
4. 微信数据目录是否准确。
5. macOS 是否已关闭 SIP 并完成系统授权。
仍然失败时，可以在连接页面切换为“高级用户：已有数据库密钥？手动连接”，粘贴从其他兼容工具中取得的数据库密钥。手动输入的密钥必须与当前微信账号匹配。
### 数据库连接失败或账号不匹配
数据库密钥与微信账号绑定。请确认：
- 当前微信登录的是获取密钥时对应的账号。
- WechatExplorer 选择的是该账号的数据目录。
- 没有把其他账号或旧数据目录的密钥粘贴进来。
### 已连接但图片无法显示
微信 4.0 的图片通常以 `.dat` 文件存储。显示图片还需要：
- **XOR Key**：单字节十六进制值，例如 `0x40`。
- **AES Key**：用于 AES-128-ECB 解密的 16 字符字符串。
进入「设置 → 图片解密密钥」，选择自动获取或手动填写。也可以从 WeFlow 或 Chatlog 的设置中导出后填写。文字聊天记录不受图片密钥影响。
### 我已经连接成功，怎么重新查看教程？
点击左下角「新手引导」。
首次连接流程、AI 配置入口、群聊日报、问问微信和完整教程都会再次展示。
## 接入 API、Reader Skill 或 Agent
这是高级使用路径，请先完成数据库连接并熟悉「问问微信、日报、档案、导出」的基础流程。
### Reader Skill
1. 打开应用的「API」页面。
2. 确认本地 API 已运行；如果已停止，点击“启动服务”。
3. 在“快速接入”中选择 Codex 或 Claude Code。
4. 复制安装指令，粘贴给对应 Agent 执行。
5. 安装完成后，让 Agent 读取和总结本地聊天。
本地 API 默认地址为 `http://127.0.0.1:6131`，默认仅监听本机。除 health 外的数据接口需要 Bearer Token；Token 可在 API Center 中显示或复制。详细端点和参数见 [Reader Skill 文档](../skill/wechatexplorer-reader/SKILL.md)。
### Agent Hub
应用内的「Agent」页面用于管理 WechatExplorer 的 Agent 连接与运行状态，属于高级功能。
## 数据与隐私
- WechatExplorer 只读取你有权访问的本机微信数据。
- 不使用 AI 时，应用不会因为读取聊天记录而自动上传聊天内容。
- 使用 AI 问问微信、日报或图片理解时，相关内容会发送到你配置的模型服务。
- 本地 API 默认监听 `127.0.0.1`，并要求 Bearer Token。它仍面向个人本机使用，不建议暴露到公网或不受信任网络。
## 仍然无法解决？
请先完成上面的自助排查，再进入交流/售后群。提问时一次性提供：
1. 操作系统和版本。
2. 微信版本。
3. WechatExplorer 版本。
4. 当前处于哪一步，以及完整错误信息。
5. 必要截图；请遮挡账号、数据库密钥、API Key 和其他敏感信息。
交流二维码位于项目 [README](../../README.md) 文末。
按现象进入[常见问题与排查](./troubleshooting.md)：连接失败、聊天为空、AI 没有结果、语音模型不可用、导出失败和 Agent 无法访问分别有不同处理方式。
docs/user-guide/knowledge.md
+38
View File
@@ -0,0 +1,38 @@
# 把聊天变成更容易再次找到的本地资料
## 你为什么需要 Knowledge
如果你经常查同一批工作群、项目讨论或长期联系人，只靠每次临时翻聊天会越来越慢。Knowledge 会在本机建立一份可重复查找的索引，让“以前聊过什么”这类问题更容易跨会话、跨时间找到相关内容。
它不是另一个聊天窗口，也不会替你修改微信原始数据库；它是 WechatExplorer 为当前账号维护的本地加速资料。
## 建立和同步
Knowledge 不会在第一次连接后自动悄悄建立。进入“问问微信”后，在“本地知识库”区域点击：
- **建立本地知识库**：第一次读取当前账号的可检索聊天；
- **同步最新记录**：已有索引时，只补充新增或变化的内容。
同步会在后台运行，完成后页面显示已索引消息、知识片段和磁盘占用。同步期间暂不能开始新的 AI 分析；同步异常时，旧索引仍可能可以继续使用。
## 账号隔离
每个微信账号使用独立的本地索引。切换账号时，应用不会把一个账号的索引混入另一个账号的搜索结果。
## 什么时候值得建立
- 你要跨多个群查过去几个月的内容；
- 你反复查同一个项目、客户或主题；
- 你希望 AI 先从更稳定的本地资料中找来源；
- 你想减少每次搜索都重新读取大量原始记录的等待。
只偶尔查一条原话时，直接使用档案搜索通常更快。
## 清理和重建
在“设置 → 缓存与清理”中可以清理本地知识库索引、检索记录和导出任务缓存。清理索引不会删除微信原始聊天记录或数据库密钥；之后可以回到“问问微信”重新建立。
## 产品术语（可选）
源码和日志中可能出现 SQLite、FTS、Chunk、索引等词。它们描述的是本地存储和检索实现，不是你开始使用 WechatExplorer 的前置知识。
docs/user-guide/privacy.md
+58
View File
@@ -0,0 +1,58 @@
# 数据、隐私与安全
WechatExplorer 的核心路径是本地优先，但“本地优先”不等于所有功能都完全离线。是否有数据离开电脑，取决于你是否启用了对应的 AI、Agent 或机器人能力。
## 默认留在本机的内容
以下处理由应用在本机完成：
- 读取和解析微信数据库；
- 聊天档案浏览和普通关键词搜索；
- 本地 Knowledge 索引及其账号隔离；
- 离线语音转写；
- 导出文件生成和本地日报历史。
应用不会因为你打开 WechatExplorer 就自动把整份微信数据库上传。
## 什么时候会请求外部服务
当你主动使用 AI Search、群聊日报或图片理解，并配置了远程 Provider 时，完成任务所需的内容可能发送给该 Provider。当前设置页给出的边界是：
- 当前用户问题；
- 受控检索所需的有限上下文；
- 最终用于总结的 Evidence。
不会发送完整微信数据库、全量聊天记录、未选中的聊天范围、数据库密钥、内部索引结构或内部会话/消息引用 ID。Provider 的日志、保留、计费和跨境规则不由 WechatExplorer 控制，请查看你所选服务商的政策。
Ollama 等本机 Provider 可以把模型请求留在本机，但本机服务的日志和配置仍由你负责。
## 语音和媒体
离线语音转写在本机进行。图片理解属于 AI 功能：只有你主动启用并使用相关报告/分析路径时，图片才可能按该 Provider 的请求规则被处理。无法读取的媒体不会被自动“猜出来”。
## Local HTTP API
- 默认监听地址为 `127.0.0.1:6131`，不是公网服务；
- `/api/v1/health` 为公开健康检查；
- 其他端点需要 `Authorization: Bearer <TOKEN>`；
- 浏览器 CORS 只允许 HTTP 的 `localhost`、`127.0.0.1` 和 `[::1]` Origin；
- 不带 Origin 的本地 CLI/Agent 请求可以使用 Token 访问；
- API 不适合直接转发到公网或绑定到不受信任的网络接口。
Token 由应用生成，使用 Electron `safeStorage` 加密保存在本机 `local-api-token.bin`，文件权限为仅当前用户可读写。你可以在“API Center”中显示、复制或重新生成 Token；重新生成会立即使旧 Token 失效。具体配置见[API 安全](../agent/api-security.md)。
## Agent 访问时发生什么
外部 Agent 通过 Reader Skill 调用本机 API，按需读取联系人、会话或时间范围内的聊天；它不会因此获得数据库文件路径或任意文件系统权限。Agent 是否把读取结果再次发送给模型，取决于 Agent 本身及其配置。
应用内 Agent Hub 是另一条路径：微信机器人通过本机 Hub 调用 WechatExplorer，并且可能使用已配置的 AI 来理解问题。请把机器人账号、发送权限和日志视为独立的安全边界。
机器人收到的文字会先进入本机 Agent Hub；如果任务需要总结或自然语言理解，受控上下文可能发送给你配置的 AI Provider。机器人账号扫码登录、个人微信数据库连接和外部 Agent/API Token 是不同的边界，使用前请分别确认账号与权限。
## 你可以主动做的事
- 不要把 API Token 放进 Git、截图、URL 或公开 Skill 文件；
- 只连接你有权访问的微信数据；
- 对需要外发的 AI 功能逐项确认 Provider；
- 定期在“设置 → 缓存与清理”清理不再需要的检索、导出和索引缓存；
- 在共享电脑上退出应用并保护系统账户。
docs/user-guide/report.md
+42
View File
@@ -0,0 +1,42 @@
# 生成群聊日报和总结
如果你每天在多个群里聊天，晚上不想重新翻几十个群，可以让 WechatExplorer 根据一个群的聊天内容整理出一份可阅读、可保存的报告。
## 报告适合做什么
典型场景包括：
- 整理今天工作群的讨论重点；
- 回顾昨天错过的决定和资源；
- 汇总近 7 天的项目进展、待办和未解决问题；
- 把群里的图片、语音统计和重要消息放进一张长图或 HTML 页面。
## 生成步骤
1. 打开“日报”。
2. 选择一个群聊。当前日报入口只支持群聊，不支持单聊。
3. 选择时间范围：今天、昨天或近 7 天。
4. 按需要选择参与总结的消息类型，先从文字开始最容易核对。
5. 选择报告模板/内容模式并开始生成。
6. 等待“整理输入 → AI 生成 → HTML/PNG 导出”完成。
报告可能包含主题、重要消息、问答、资源、待办、未解决事项、关键词、活跃统计，以及可用媒体的精选内容。具体展示内容会随消息类型、资源可用性和模型能力变化。
## 如何检查报告
报告中的重点结论会关联来源消息。对于重要决定、金额、时间和责任人，打开对应原消息核对，不要把 AI 生成的摘要当成新的事实来源。
图片无法读取时，报告可能只保留消息类型和上下文；模型未通过图片理解验证时，图片精选会被跳过。语音在日报中可参与数量和活跃度统计，但不要把统计当成语音内容已经被完整转写。
## 保存、查看和删除
生成成功后会保存本地 HTML 与 PNG，并出现在日报历史中。你可以复制图片、打开文件位置或重新生成。删除历史日报只删除本地生成的报告文件，不会影响微信聊天数据库。
## 让报告更可靠
- 先选正确的群和时间范围；
- 不确定时先只选择文字消息；
- 群太活跃时分成“今天”和“近 7 天”两次生成；
- 看到待办和结论后回到原消息核对上下文；
- AI Provider 不可用时先检查模型配置和网络/本地服务状态。
docs/user-guide/troubleshooting.md
+62
View File
@@ -0,0 +1,62 @@
# 常见问题与排查
先按现象定位，不要为了“重置”而直接删除微信数据库或整个应用目录。
## 连接微信失败
依次检查：
1. 数据目录是否指向当前登录账号，而不是旧备份或迁移前目录；
2. 微信版本是否属于当前代码面向的 4.x 数据结构；
3. 微信是否处于页面要求的登录/退出状态；
4. macOS 是否完成页面要求的授权；
5. 连接页面的诊断项是否明确指出密钥、账号或数据库问题。
重新输入密钥或断开连接不会删除微信原始数据库。macOS 的 SIP 和授权说明见[平台说明](../platform/macos.md)。
## 连接成功但没有联系人或消息
确认账号身份和数据目录匹配。返回“设置 → 账号与数据库”查看数据库连接状态，重新加载会话后再试。若仍为空，记录系统、微信版本和错误提示后提交 Issue。
## AI 没有结果或回答失败
- 先在“设置 → AI 模型”测试 Provider；
- 检查问题的时间范围和会话范围是否过窄；
- 确认 Knowledge 没有正在同步；
- 打开检索详情，查看是本地查找为空、Provider 失败还是来源被过滤；
- 把问题改成要求“只根据来源原文回答”。
AI Search 失败时可能仍保留部分来源；不要把部分结果当成完整覆盖。
## AI 答案看起来不对
打开来源和原始消息，检查发送者、时间和上下文。若来源不支持结论，扩大或缩小范围后重问。涉及未转写语音、缺失图片、转发和引用时，优先以原消息为准。
## Knowledge 一直在同步
首次建立或增量同步会在后台运行。查看“已索引消息、知识片段、磁盘占用”和同步详情；同步期间暂不能开始新的 AI 分析。若出现错误，旧索引可能仍可用，重启应用或在“缓存与清理”清理后重新建立。
## 语音转写失败
检查本地模型是否已准备、磁盘空间是否足够、单条语音是否仍有原始资源。批量任务可能部分成功；先处理失败项，不必重复转写已缓存内容。
## 媒体显示或导出异常
原图/缩略图目录缺失、权限不足或微信资源已被清理都会导致图片、视频或语音不可用。导出时可以切换缩略图、关闭媒体或保留缺失项，先确认文本档案是否正常。
## 日报生成失败
日报只支持群聊。确认已选择群聊、时间范围内确实有消息、Provider 可用，并尝试先只选择文字消息。图片理解失败不会自动变成图片内容；报告可能跳过图片精选但仍生成文字日报。
## Agent 无法读取
确认：
1. WechatExplorer 正在运行且 API Center 显示本地服务在线；
2. Agent 使用的是当前 Reader Skill，而不是旧的 MCP 配置；
3. 请求地址为 `http://127.0.0.1:6131`；
4. 非 health 请求带有最新 `Authorization: Bearer <TOKEN>`；
5. Token 重新生成后，Agent 配置已同步更新。
详细步骤见[Agent 接入概览](../agent/overview.md)和[API 安全](../agent/api-security.md)。
docs/user-guide/voice.md
+37
View File
@@ -0,0 +1,37 @@
# 语音转文字
WechatExplorer 可以把微信语音转换成可搜索的文字，适合你不想逐条播放、希望把语音内容带入后续查找或导出的场景。
## 使用前准备
1. 打开“设置 → 语音识别”。
2. 按页面提示准备或下载本地语音模型。
3. 等待模型状态显示可用。
语音识别使用本地 SenseVoice/sherpa-onnx 运行时。首次准备模型可能需要下载文件和占用额外磁盘空间；模型文件可以从设置中删除，之后需要重新准备。
## 转写单条语音
在聊天档案中找到语音消息，点击转写入口。完成后，转写文本会与该消息关联，并可用于后续查看或检索。失败时查看消息提示和模型状态。
## 批量转写
在语音设置中选择联系人或群聊，再选择范围：
- 最近 30 天；
- 当前年份；
- 选择的历史范围。
开始前页面会显示语音条数、已缓存数量、待处理数量和预计耗时。批量任务支持进度、取消、缓存复用，并可能以“部分失败”结束；部分失败时可以根据列表重新处理未成功内容。
## 和 AI、知识库、导出的关系
- 本地转写结果可以参与本地知识库检索；
- 导出时可选择是否包含已有语音转写；
- AI Search 可能提示某些语音尚未转写，这意味着答案覆盖不完整；
- 群聊日报默认会统计语音数量和时长，但不等于已经理解了每条语音的具体内容。
## 隐私提示
离线转写本身在本机完成。若你主动把转写结果用于 AI Search、日报或其他 AI 功能，受控文本可能按对应功能的规则发送给你配置的 Provider；详见[数据、隐私与安全](./privacy.md)。