docs: 更新文档

2026-08-17 11:37:06 +08:00 · 2026-08-08 14:54:54 +08:00
parent cd2c3cfaee
commit f2c58f39b0
23 changed files with 713 additions and 182 deletions
@@ -13,7 +13,9 @@ WechatExplorer 的文档按“你想完成什么”组织，而不是按源码
 - [建立本地知识库](./user-guide/knowledge.md)
 - [生成群聊日报和总结](./user-guide/report.md)
 - [语音转文字](./user-guide/voice.md)
- [导出聊天和报告](./user-guide/export.md)
+- [导出聊天档案](./user-guide/export.md)
+- [防撤回](./user-guide/recall-protection.md)
+- [在微信里向 WechatExplorer 提问](./agent/agent-hub.md)
 - [数据、隐私与安全](./user-guide/privacy.md)
 - [常见问题与排查](./user-guide/troubleshooting.md)

@@ -22,14 +24,20 @@ WechatExplorer 的文档按“你想完成什么”组织，而不是按源码
 - [如何核对 AI 的回答来源](./concepts/answer-sources.md)：用用户语言解释依据、来源标记和查找过程。
 - [从微信数据到回答、日报和导出](./concepts/how-it-works.md)：了解哪些步骤在本机完成，哪些步骤可能调用 Provider。

-## 如果你想连接 Agent
+## 微信机器人和外部 Agent

-WechatExplorer 有两种不同的 Agent 使用方式，请先按你的目标选择：
+WechatExplorer 有两种不同的接入方式。微信机器人是普通用户可以直接使用的产品能力；Reader Skill 和 Local HTTP API 面向已经在使用 Codex、Claude Code、OpenClaw 等外部 Agent 的用户。

-| 你想做什么 | 应该看哪里 |
-| --- | --- |
+| 你想做什么                                                            | 应该看哪里                                                                 |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| 在微信里给机器人发消息，让本机读取数据、生成总结并回复                | [Agent Hub](./agent/agent-hub.md)                                          |
 | 在 Codex、Claude Code、OpenClaw 等外部 Agent 中主动查询过去的微信数据 | [Reader Skill](./agent/reader-skill.md) + [Local HTTP API](./agent/api.md) |
-| 在微信里给机器人发消息，让本机读取数据、生成总结并回复 | [Agent Hub](./agent/agent-hub.md) |
+
+### 在微信里提问
+
+打开应用一级导航中的“Agent”，进入“Agent Hub”后扫码登录微信机器人。机器人收到文字消息后，可以查询最近会话、读取联系人聊天、生成群聊总结图片或总结群成员发言，并把结果回复给发消息的人。它需要本地微信数据库已经连接；依赖 AI 的任务还需要配置 AI 服务。
+
+- [Agent Hub](./agent/agent-hub.md)：连接机器人、查看运行状态和了解实时交互边界。

 ### 让外部 Agent 查询历史微信

@@ -43,12 +51,6 @@ WechatExplorer 有两种不同的 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)
@@ -1,6 +1,8 @@
-# Agent Hub：让微信机器人参与实时工作
+# 在微信里向 WechatExplorer 提问（Agent Hub）

-Agent Hub 是 WechatExplorer 内置的实时微信交互入口。你先在应用中扫码登录一个微信机器人账号，之后向这个机器人发送文字；本机 Agent Hub 会接收消息、读取已经连接的微信数据，必要时调用已配置的 AI，再把结果回复给发消息的人。
+Agent Hub 是 WechatExplorer 内置的微信机器人入口，也是应用一级导航中的“Agent”页面。你先扫码登录一个微信机器人账号，再用微信账号向机器人发送文字；本机 Agent Hub 会接收消息、读取已经连接的微信数据，必要时调用已配置的 AI，再把结果回复给发送者。
+
+普通用户不需要安装 Reader Skill，也不需要配置 API Token。先连接微信数据库，再扫码登录机器人即可开始；需要总结或自然语言理解的任务还要配置 AI Provider。

 它和 Reader Skill 是两条不同的路径：

@@ -15,7 +17,7 @@ Agent Hub 是 WechatExplorer 内置的实时微信交互入口。你先在应用

 连接 Agent Hub 后，可以在微信中询问：

- “最近 5 条消息是谁？”
+- “最近 5 个会话”；
 - “帮我看看最近跟某人聊了些什么。”
 - “生成产品交流群今天的群聊总结图片。”

@@ -38,7 +40,7 @@ Agent Hub 是 WechatExplorer 内置的实时微信交互入口。你先在应用
 2. 确认 Hub 显示“运行中”，数据库状态为“可查询”。
 3. 点击“扫码登录微信机器人”。
 4. 用微信扫描二维码；如果页面显示“已扫码，等待手机确认”，在手机上确认。
-5. 状态变为“在线”后，从该机器人账号发送测试问题。
+5. 状态变为“在线”后，用另一个微信账号向机器人发送测试问题。

 可以重新扫码登录或断开连接。登录凭证失效时，需要重新扫码。

@@ -1,47 +1,52 @@
-# 连接 Agent：你能用它做什么
+# 在微信机器人或外部 Agent 中使用 WechatExplorer

-WechatExplorer 的 Agent 能力分成“查询过去的数据”和“处理实时微信消息”两条路径。先按你想完成的任务选择，不需要先学习内部模块名称。
+WechatExplorer 提供两条不同路径。先按你实际想做的事选择，不需要先理解 Agent、Skill 或 API 等术语。

-## 两种不同的使用方式
+| 你想做什么                                           | 使用方式                      | 需要什么                                                  |
+| ---------------------------------------------------- | ----------------------------- | --------------------------------------------------------- |
+| 直接在微信里发文字，让本机查询聊天并回复             | 微信机器人（Agent Hub）       | 在应用“Agent”页面扫码登录机器人；部分任务需要 AI Provider |
+| 在 Codex、Claude Code、OpenClaw 等工具里查询微信历史 | Reader Skill + Local HTTP API | 安装 Skill，并配置本机 API Token                          |

-### 让外部 Agent 查询历史微信
+## 直接在微信里提问

-连接 Reader Skill 后，你可以在本机的 Codex、Claude Code、OpenClaw 或其他 Agent 中询问自己的微信历史，例如：
+打开应用一级导航中的“Agent”，进入“Agent Hub”，扫码登录一个微信机器人账号。之后用另一个微信账号向机器人发送文字，它会调用 WechatExplorer 的本机数据，必要时使用已配置的 AI，再把结果回复给发送者。
+
+可以先尝试：
+
+- “最近 5 个会话”；
+- “帮我看看最近跟张三聊了些什么”；
+- “生成产品交流群今天的群聊总结图片”。
+
+这条路径不要求安装 Reader Skill，也不要求用户配置 API Token。它主要处理文字请求，不支持群发、定时任务或与文字同等的任意媒体理解。
+
+连接步骤、当前任务清单和安全边界见[Agent Hub](./agent-hub.md)。
+
+## 在外部 Agent 中查询历史微信
+
+Reader Skill 是给外部 Agent 的操作说明。安装后，Codex、Claude Code、OpenClaw 或其他本地 Agent 可以通过 WechatExplorer Local HTTP API 按需读取联系人、群聊、最近会话、指定时间范围的聊天和群成员信息。
+
+典型问题包括：

 - “总结今天技术交流群讨论的内容。”
 - “帮我找上个月讨论过的项目地址。”
 - “过去一周有没有人提到退款？”

-Agent 会按需读取 WechatExplorer 提供的联系人、群聊和聊天记录；它不会直接打开微信数据库文件。
+外部 Agent 不会直接打开微信数据库文件，但它能取得本机 API 返回的聊天内容。Agent 是否继续把结果发送给云端模型，取决于 Agent 自己的模型和工具配置。

-| 方式 | 适合谁 | 作用 | 是否需要外部 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 的安装路径
+## 外部 Agent 的安装步骤

 1. 启动 WechatExplorer 并完成微信数据库连接。
-2. 打开“API Center”，确认本地 API、数据库和 Reader Skill 都显示可用。
-3. 在 API Center 选择目标 Agent（Codex、Claude Code、OpenClaw 或其他 Agent），点击“复制安装指令”。
-4. 在 Agent 自己的本地 Skill/配置目录执行或粘贴指令。
+2. 打开一级导航“API”（页面为“API Center”），确认本地 API、数据库和 Reader Skill 都可用。
+3. 选择目标 Agent，点击“复制安装指令”。
+4. 在 Agent 自己的 Skill/配置目录执行或粘贴指令。
 5. 在 API Center 复制当前 Token，并在 Agent 运行环境中设置 `WECHATEXPLORER_API_TOKEN`。
-6. 先让 Agent 调用 health，再尝试查询联系人或最近会话。
+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)。
+- Agent Hub：微信机器人收到实时文字后处理并回复；
+- Reader Skill/API：外部 Agent 主动查询历史数据；
+- `127.0.0.1:6131` 是 Local HTTP API，不是 MCP Server；
+- Local HTTP API 当前没有对外提供实时入站消息订阅。
@@ -10,9 +10,15 @@ flowchart LR
  D --> E[筛选相关消息]
  E --> F[用户配置的 AI Provider]
  F --> G[回答与可核对来源]
-  B --> H[日报与导出]
-  B --> I[Local HTTP API]
-  I --> J[外部 Agent]
+  B --> H[聊天导出]
+  B --> I[整理日报输入]
+  I --> F
+  F --> J[本地保存 HTML 与 PNG]
+  B --> K[Local HTTP API]
+  K --> L[外部 Agent]
+  M[微信机器人消息] --> N[Agent Hub]
+  N --> B
+  N --> F
 ```

 ## 哪些步骤在本机
@@ -21,24 +27,25 @@ flowchart LR
 - 聊天档案浏览和普通搜索；
 - Knowledge 索引与增量同步；
 - 离线语音转写；
- 报告、导出文件和本地历史记录。
+- 聊天导出文件、日报 HTML/PNG 和本地历史记录的保存。

 ## 哪些步骤可能调用外部服务

 当你主动使用 AI Search、群聊日报或图片理解时，应用会把完成任务所需的受控问题和上下文发送给你配置的 Provider。它不会因为打开软件就自动上传完整数据库。

+Agent Hub 收到微信机器人的文字后，也可能为了理解请求或生成总结调用已配置的 Provider。Reader Skill 调用的是本机 API；外部 Agent 是否把读取结果继续交给云端模型，取决于外部 Agent 自己的配置。
+
 如果 Provider 是 Ollama 等本机服务，请把它视为本机的另一个进程；如果是云服务，数据处理和留存规则由该服务商决定。

 ## 产品名词和用户任务的对应关系

-| 用户想做什么 | 产品中可能看到的名称 |
-| --- | --- |
-| 让 AI 找相关聊天 | AI Search、Retrieval |
-| 让答案能回到原消息 | Evidence、Citation |
-| 查看 AI 查找过程 | Search Trace |
-| 让跨会话查找更稳定 | Knowledge、FTS 索引 |
-| 让外部 Agent 读取聊天 | Reader Skill、Local HTTP API |
-| 让微信机器人调用本机能力 | Agent Hub |
+| 用户想做什么             | 产品中可能看到的名称         |
+| ------------------------ | ---------------------------- |
+| 让 AI 找相关聊天         | AI Search、Retrieval         |
+| 让答案能回到原消息       | Evidence、Citation           |
+| 查看 AI 查找过程         | Search Trace                 |
+| 让跨会话查找更稳定       | Knowledge、FTS 索引          |
+| 让外部 Agent 读取聊天    | Reader Skill、Local HTTP API |
+| 让微信机器人调用本机能力 | Agent Hub                    |

 先按任务使用，再在需要排查或开发集成时阅读术语。
-
@@ -32,16 +32,17 @@ pnpm test:e2e:build

 ## 代码变更对应文档

-| 代码区域 | 需要同步检查的文档 |
-| --- | --- |
-| `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` |
+| 代码区域                                                  | 需要同步检查的文档                                         |
+| --------------------------------------------------------- | ---------------------------------------------------------- |
+| `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/main/services/recall-archive-service.ts`、防撤回设置 | `user-guide/recall-protection.md`、`user-guide/privacy.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`          |

 ## 文档检查

@@ -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)。