docs: 更新文档

2026-08-17 03:27:00 +08:00 · 2026-08-08 14:54:54 +08:00
parent cd2c3cfaee
commit f2c58f39b0
23 changed files with 713 additions and 182 deletions
@@ -16,7 +16,7 @@

 1. 进入“设置 → AI 模型”，添加一个 Provider，填写服务地址、模型和认证信息，然后测试连接。
 2. 打开“问问微信”。
-3. 根据问题选择时间范围和会话范围；范围越明确，答案越容易核对。
+3. 选择所有聊天、群聊、单聊或当前会话，并选择今天、近 7 天、近 30 天或不限时间；范围越明确，答案越容易核对。
 4. 输入问题并开始分析。

 如果知识库尚未建立，页面会提示你建立或同步；你也可以先直接使用当前可用的搜索路径。
@@ -58,3 +58,4 @@

 本地解析、索引和候选消息查找在本机完成。只有完成 AI 任务所需的用户问题、受控检索上下文和最终用于总结的来源内容，才可能发送到你配置的 Provider；具体边界见[数据、隐私与安全](./privacy.md)。

+使用远程 Provider 时，当前界面会在本次请求发出前显示接收方和发送范围，等待你确认。当前实现最多发送 8 条最终来源，不会发送完整微信数据库、数据库密钥、绝对文件路径或内部会话/消息引用 ID；这次确认不会自动授权之后的其他请求。
@@ -25,6 +25,14 @@

 不要把“消息类型已读取”理解成“所有媒体都一定能解码”。遇到图片或视频空白时，请先检查[媒体与导出排查](./troubleshooting.md#媒体显示或导出异常)。

+如果文字正常但图片无法打开，进入“设置 → 图片解密”查看当前状态。可以尝试自动获取，也可以在已经知道正确密钥时手动配置；原文件已经被微信清理时，仅配置密钥也无法恢复图片。
+
+## 可选保留撤回消息
+
+“设置 → 防撤回”提供一个默认关闭的可选功能。开启后，应用会尽量保留之后捕获到的撤回消息，并在气泡旁标记“消息已撤回”。它不能找回开启前已经消失或应用未捕获到的内容，也可能增加加载开销。
+
+该功能与普通只读浏览的数据边界不同。开启前请阅读[防撤回](./recall-protection.md)。
+
 ## 保护自己不被误导

 档案中的原始消息是核对 AI 结果的最终依据。看到 AI 的总结、日报或来源时，建议：
@@ -47,4 +55,3 @@
 ### 想跨多个会话查找

 使用“问问微信”，并在问题中写清时间范围、人物或群聊范围。需要更稳定的跨会话查找时，先建立[本地知识库](./knowledge.md)。
-
@@ -1,34 +1,39 @@
-# 导出聊天和报告
+# 导出聊天档案

 导出适合把微信里的重要讨论保存成可阅读、可分享或可继续处理的文件。

 ## 支持的格式

- **HTML**：适合完整阅读，可包含媒体和头像；
- **Markdown**：适合笔记、版本管理和再次编辑；
- **CSV**：适合表格分析；
- **JSON**：适合程序处理和数据归档。
+| 格式     | 适合什么任务             | 当前边界                                                   |
+| -------- | ------------------------ | ---------------------------------------------------------- |
+| HTML     | 完整阅读和长期归档       | 可包含媒体、头像和可选语音转写；支持多会话、增量合并和 ZIP |
+| Markdown | 笔记、版本管理和再次编辑 | 主要保留文本内容，不复制 HTML 资源文件                     |
+| CSV      | 表格分析                 | 主要保留文本内容，不复制 HTML 资源文件                     |
+| JSON     | 程序处理和数据归档       | 主要保留文本内容，不复制 HTML 资源文件                     |
+
+ZIP 是 HTML 资源包的压缩选项，不是第五种内容格式。

 ## 导出步骤

-1. 打开“导出”。
-2. 选择一个或多个联系人/群聊。
-3. 选择时间范围和消息类型。
-4. 按需要打开媒体、头像、原图/缩略图、语音转写和保留缺失资源等选项。
-5. 设置文件名，必要时选择 ZIP，然后开始导出。
+可以打开一级导航“导出”，也可以在“档案”的聊天顶部点击“导出”并选择时间范围。
+
+1. 选择一个或多个联系人/群聊。
+2. 选择时间范围和消息类型。
+3. 选择格式；只有 HTML 可以配置媒体资源、语音转写和 ZIP。
+4. 按需要设置头像、原图/缩略图和缺失资源处理。
+5. 设置文件名并开始导出。
 6. 在导出任务中心查看读取、解析、媒体处理、转写、写入和压缩进度；完成后打开文件位置。

 ## 多会话和增量导出

-HTML 支持把最多五个会话合并到一个档案中。再次使用相同名称导出时，可以把新消息增量合并到已有档案；这不会删除之前已导出的消息。
+HTML 支持把最多五个会话合并到一个档案中；选择多个会话后，其他格式会不可用。再次使用相同名称导出 HTML 时，可以把新消息增量合并到已有档案；这不会删除之前已导出的消息。

 ## 媒体怎么处理

 原图、缩略图、缺失资源和头像都可能影响导出大小与可读性。想要小文件时关闭媒体或选择缩略图；想要长期保存时，确认原始媒体目录仍可访问，并考虑 ZIP 归档。

-语音转写是可选步骤。只有已经成功转写的语音才会写入导出内容，导出不会替你自动补齐失败的识别。
+HTML 导出可以选择在任务中执行本地语音转写，并把成功结果显示在语音气泡下方。语音模型不可用或识别失败时，导出不会把失败内容当成已转写文本。

 ## 导出和原始数据的关系

 导出是复制/整理结果，不会修改微信原始数据库。删除导出文件也不会影响应用内聊天记录或本地知识库。
-
@@ -44,6 +44,8 @@ macOS 如果提示无法验证开发者，请按系统提示允许打开。自

 如果联系人列表为空，先检查是否连到了正确账号和数据目录，再重新加载会话。

+文字消息正常但图片打不开时，不代表数据库连接失败。打开“设置 → 图片解密”查看状态并尝试自动获取；图片原文件缺失、权限不足或密钥不匹配时，部分图片仍可能无法显示。
+
 ## 5. 完成你的第一个任务

 ### 只是想找一句话
@@ -52,7 +54,7 @@ macOS 如果提示无法验证开发者，请按系统提示允许打开。自

 ### 想找一个模糊的结论

-进入“问问微信”，直接描述问题，例如：
+先在“设置 → AI 模型”添加并测试一个 Provider，再进入“问问微信”描述问题，例如：

 - “上个月技术群讨论过哪些发布问题？”
 - “张三之前发过的项目地址在哪里？”
@@ -74,11 +76,13 @@ macOS 如果提示无法验证开发者，请按系统提示允许打开。自
 - [生成群聊日报或总结](./report.md)
 - [转写微信语音](./voice.md)
 - [导出聊天档案](./export.md)
- [连接外部 Agent 或微信机器人](../agent/overview.md)
+- [可选开启防撤回](./recall-protection.md)
+- [在微信里向 WechatExplorer 提问](../agent/agent-hub.md)
+- [让外部 Agent 查询微信历史](../agent/overview.md)

-## 7. 想让微信机器人参与实时对话
+## 7. 想直接在微信里提问

-如果你希望直接在微信里向本机助手提问，而不是在外部 Agent 中查询，请使用 Agent Hub：
+如果你希望直接在微信里向 WechatExplorer 提问，而不是另外配置 Codex 等外部 Agent，请使用 Agent Hub：

 1. 先完成上面的微信数据库连接，并确认“档案”里能看到聊天。
 2. 打开应用主导航中的“Agent”；页面标题为“Agent Hub”。
@@ -94,6 +98,8 @@ macOS 如果提示无法验证开发者，请按系统提示允许打开。自

 机器人会把处理结果回复给发消息的人。联系人聊天总结、群聊总结和需要理解自然语言的请求依赖“设置 → AI 模型”中已经配置好的 AI 服务。当前实时入口主要处理文字消息；它不是支持任意图片、语音、文件理解、群发或定时任务的通用机器人。机器人账号扫码登录与读取你微信数据库是两条独立流程，都需要分别确认账号和权限。

+Agent Hub 是普通用户可以直接使用的入口，不需要安装 Reader Skill 或配置 API Token。Reader Skill 和 API 只用于让外部 Agent 主动查询历史微信。
+
 ## 8. 需要配置 AI 吗？

 不一定。浏览聊天、普通关键词搜索、建立本地知识库和导出不要求在线 AI 服务。
@@ -106,6 +112,7 @@ macOS 如果提示无法验证开发者，请按系统提示允许打开。自
 - 离线语音转写使用本地模型；它与在线 AI 请求是两条不同的数据路径。
 - 你主动开始并确认 AI 问答或日报后，完成任务所需的受控上下文才可能发送给你选择的 AI 服务；打开应用不会自动上传全部聊天。
 - 应用内 Local HTTP API 默认只监听 `127.0.0.1:6131`，受保护接口需要 Token。
+- 防撤回默认关闭；首次开启会为微信消息数据库增加本地撤回日志/监听结构，详细边界见[防撤回](./recall-protection.md)。

 完整边界见[数据、隐私与安全](./privacy.md)。

@@ -14,6 +14,8 @@ WechatExplorer 的核心路径是本地优先，但“本地优先”不等于

 应用不会因为你打开 WechatExplorer 就自动把整份微信数据库上传。

+防撤回默认关闭，并且和上面的普通读取路径不同。用户第一次明确开启时，当前实现会在微信消息数据库中安装本地撤回日志/监听结构，同时在 WechatExplorer 用户数据目录保存必要的恢复记录。关闭开关不等于移除已经安装的结构或清空既有记录；当前 UI 没有对应的清理入口。详见[防撤回](./recall-protection.md)。
+
 ## 什么时候会请求外部服务

 当你主动使用 AI Search、群聊日报或图片理解，并配置了远程 Provider 时，完成任务所需的内容可能发送给该 Provider。当前设置页给出的边界是：
@@ -56,3 +58,4 @@ Token 由应用生成，使用 Electron `safeStorage` 加密保存在本机 `loc
 - 对需要外发的 AI 功能逐项确认 Provider；
 - 定期在“设置 → 缓存与清理”清理不再需要的检索、导出和索引缓存；
 - 在共享电脑上退出应用并保护系统账户。
+- 在开启防撤回前确认你接受其数据库写入、性能和清理边界，并先用微信官方方式备份重要数据。
@@ -0,0 +1,37 @@
+# 防撤回
+
+防撤回是一个默认关闭的可选功能。开启后，WechatExplorer 会尽量保留它能够捕获到的撤回消息，并在聊天气泡旁标记“消息已撤回”。
+
+它适合希望在本机档案中保留后续聊天上下文的用户，但不能保证找回每一条撤回消息。
+
+## 如何开启
+
+1. 先连接微信数据库，并确认“档案”可以正常读取聊天。
+2. 打开“设置 → 防撤回”。
+3. 阅读性能和数据提示后，开启“防撤回”。
+4. 保持 WechatExplorer 与当前微信数据连接；之后捕获到的撤回消息会尽量保留并标记。
+
+防撤回不是第一次使用的必要步骤。只想浏览、搜索、提问或导出时，可以保持关闭。
+
+## 当前能做什么
+
+- 监听应用能够识别到的后续撤回变化；
+- 在本地保留必要的消息和撤回关系；
+- 将已识别的原消息与撤回状态一起显示在档案中；
+- 按微信账号隔离 WechatExplorer 保存的恢复记录。
+
+## 当前限制
+
+- 不能恢复开启前已经撤回、且应用从未保存到的消息；
+- WechatExplorer 未运行、数据库未连接或没有捕获到撤回变化时，消息可能无法保留；
+- 微信版本、消息表结构和数据库事件变化都可能让部分消息无法恢复或正确匹配；
+- 开启后需要为消息表增加监听，聊天很多或磁盘较慢时可能影响加载性能；
+- “消息已撤回”只说明应用识别到了撤回关系，不保证恢复内容完整。
+
+## 数据写入与关闭边界
+
+普通浏览、搜索和 Knowledge 不会修改微信原始聊天数据库；防撤回是一个例外。用户第一次明确开启时，当前实现会在微信消息数据库中安装用于记录撤回的本地日志/监听结构，并在 WechatExplorer 的用户数据目录保存必要的本地恢复记录。
+
+关闭设置中的开关，不等同于删除已经安装的日志结构或清空此前保存的恢复记录。当前版本没有在 UI 中提供“移除防撤回日志结构”或“清空防撤回记录”的独立操作。对数据库写入、磁盘占用或完全回滚有要求时，应在开启前先确认这一边界，并使用微信官方方式备份重要数据。
+
+完整的数据边界见[数据、隐私与安全](./privacy.md)。
@@ -13,12 +13,13 @@

 ## 生成步骤

-1. 打开“日报”。
-2. 选择一个群聊。当前日报入口只支持群聊，不支持单聊。
-3. 选择时间范围：今天、昨天或近 7 天。
-4. 按需要选择参与总结的消息类型，先从文字开始最容易核对。
-5. 选择报告模板/内容模式并开始生成。
-6. 等待“整理输入 → AI 生成 → HTML/PNG 导出”完成。
+你可以从两个入口开始：打开一级导航“日报”后新建报告，或者在“档案”中选中一个群聊并点击“生成 AI 日报”。
+
+1. 选择一个群聊。当前日报入口只支持群聊，不支持单聊。
+2. 选择时间范围：今天、昨天或近 7 天。
+3. 按需要选择参与总结的消息类型，先从文字开始最容易核对。
+4. 选择报告模板/内容模式并开始生成。
+5. 等待“整理输入 → AI 生成 → HTML/PNG 导出”完成。

 报告可能包含主题、重要消息、问答、资源、待办、未解决事项、关键词、活跃统计，以及可用媒体的精选内容。具体展示内容会随消息类型、资源可用性和模型能力变化。

@@ -39,4 +40,3 @@
 - 群太活跃时分成“今天”和“近 7 天”两次生成；
 - 看到待办和结论后回到原消息核对上下文；
 - AI Provider 不可用时先检查模型配置和网络/本地服务状态。
-
@@ -44,6 +44,8 @@ AI Search 失败时可能仍保留部分来源；不要把部分结果当成完

 原图/缩略图目录缺失、权限不足或微信资源已被清理都会导致图片、视频或语音不可用。导出时可以切换缩略图、关闭媒体或保留缺失项，先确认文本档案是否正常。

+文字正常但图片打不开时，进入“设置 → 图片解密”查看状态并尝试自动获取。密钥正确也不能恢复已经被微信清理的原图文件。
+
 ## 日报生成失败

 日报只支持群聊。确认已选择群聊、时间范围内确实有消息、Provider 可用，并尝试先只选择文字消息。图片理解失败不会自动变成图片内容；报告可能跳过图片精选但仍生成文字日报。
@@ -60,3 +62,18 @@ AI Search 失败时可能仍保留部分来源；不要把部分结果当成完

 详细步骤见[Agent 接入概览](../agent/overview.md)和[API 安全](../agent/api-security.md)。

+## 微信机器人无法连接或不回复
+
+Agent Hub 和外部 Agent 是两条路径。机器人异常时依次确认：
+
+1. “Agent”页面中的 Agent Hub、微信连接器和数据库状态是否正常；
+2. 二维码是否过期，手机是否已经确认登录；
+3. 是否由另一个微信账号向已登录的机器人账号发送文字；
+4. 请求是否属于当前支持的最近会话、联系人聊天、近 7 天联系人总结、群聊总结或群成员发言总结；
+5. 需要总结或自然语言理解时，AI Provider 是否可用。
+
+当前机器人不支持群发、定时任务或与文字同等的图片、语音、文件和视频理解。详细边界见[Agent Hub](../agent/agent-hub.md)。
+
+## 防撤回没有保留消息
+
+防撤回只能尽量保留开启后且应用成功捕获到的撤回变化。确认开启时数据库已经连接、WechatExplorer 在撤回发生时保持运行，并检查聊天加载是否明显变慢。开启前已经消失、应用未捕获或微信结构无法识别的消息不能保证恢复；详见[防撤回](./recall-protection.md)。