docs: 更新文档

docs/user-guide/ai-search.md

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

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

@@ -0,0 +1,34 @@
+# 导出聊天和报告
+
+导出适合把微信里的重要讨论保存成可阅读、可分享或可继续处理的文件。
+
+## 支持的格式
+
+- **HTML**：适合完整阅读，可包含媒体和头像；
+- **Markdown**：适合笔记、版本管理和再次编辑；
+- **CSV**：适合表格分析；
+- **JSON**：适合程序处理和数据归档。
+
+## 导出步骤
+
+1. 打开“导出”。
+2. 选择一个或多个联系人/群聊。
+3. 选择时间范围和消息类型。
+4. 按需要打开媒体、头像、原图/缩略图、语音转写和保留缺失资源等选项。
+5. 设置文件名，必要时选择 ZIP，然后开始导出。
+6. 在导出任务中心查看读取、解析、媒体处理、转写、写入和压缩进度；完成后打开文件位置。
+
+## 多会话和增量导出
+
+HTML 支持把最多五个会话合并到一个档案中。再次使用相同名称导出时，可以把新消息增量合并到已有档案；这不会删除之前已导出的消息。
+
+## 媒体怎么处理
+
+原图、缩略图、缺失资源和头像都可能影响导出大小与可读性。想要小文件时关闭媒体或选择缩略图；想要长期保存时，确认原始媒体目录仍可访问，并考虑 ZIP 归档。
+
+语音转写是可选步骤。只有已经成功转写的语音才会写入导出内容，导出不会替你自动补齐失败的识别。
+
+## 导出和原始数据的关系
+
+导出是复制/整理结果，不会修改微信原始数据库。删除导出文件也不会影响应用内聊天记录或本地知识库。
+

docs/user-guide/getting-started.md

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

@@ -0,0 +1,38 @@
+# 把聊天变成更容易再次找到的本地资料
+
+## 你为什么需要 Knowledge
+
+如果你经常查同一批工作群、项目讨论或长期联系人，只靠每次临时翻聊天会越来越慢。Knowledge 会在本机建立一份可重复查找的索引，让“以前聊过什么”这类问题更容易跨会话、跨时间找到相关内容。
+
+它不是另一个聊天窗口，也不会替你修改微信原始数据库；它是 WechatExplorer 为当前账号维护的本地加速资料。
+
+## 建立和同步
+
+Knowledge 不会在第一次连接后自动悄悄建立。进入“问问微信”后，在“本地知识库”区域点击：
+
+- **建立本地知识库**：第一次读取当前账号的可检索聊天；
+- **同步最新记录**：已有索引时，只补充新增或变化的内容。
+
+同步会在后台运行，完成后页面显示已索引消息、知识片段和磁盘占用。同步期间暂不能开始新的 AI 分析；同步异常时，旧索引仍可能可以继续使用。
+
+## 账号隔离
+
+每个微信账号使用独立的本地索引。切换账号时，应用不会把一个账号的索引混入另一个账号的搜索结果。
+
+## 什么时候值得建立
+
+- 你要跨多个群查过去几个月的内容；
+- 你反复查同一个项目、客户或主题；
+- 你希望 AI 先从更稳定的本地资料中找来源；
+- 你想减少每次搜索都重新读取大量原始记录的等待。
+
+只偶尔查一条原话时，直接使用档案搜索通常更快。
+
+## 清理和重建
+
+在“设置 → 缓存与清理”中可以清理本地知识库索引、检索记录和导出任务缓存。清理索引不会删除微信原始聊天记录或数据库密钥；之后可以回到“问问微信”重新建立。
+
+## 产品术语（可选）
+
+源码和日志中可能出现 SQLite、FTS、Chunk、索引等词。它们描述的是本地存储和检索实现，不是你开始使用 WechatExplorer 的前置知识。
+

docs/user-guide/privacy.md

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

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

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

@@ -0,0 +1,37 @@
+# 语音转文字
+
+WechatExplorer 可以把微信语音转换成可搜索的文字，适合你不想逐条播放、希望把语音内容带入后续查找或导出的场景。
+
+## 使用前准备
+
+1. 打开“设置 → 语音识别”。
+2. 按页面提示准备或下载本地语音模型。
+3. 等待模型状态显示可用。
+
+语音识别使用本地 SenseVoice/sherpa-onnx 运行时。首次准备模型可能需要下载文件和占用额外磁盘空间；模型文件可以从设置中删除，之后需要重新准备。
+
+## 转写单条语音
+
+在聊天档案中找到语音消息，点击转写入口。完成后，转写文本会与该消息关联，并可用于后续查看或检索。失败时查看消息提示和模型状态。
+
+## 批量转写
+
+在语音设置中选择联系人或群聊，再选择范围：
+
+- 最近 30 天；
+- 当前年份；
+- 选择的历史范围。
+
+开始前页面会显示语音条数、已缓存数量、待处理数量和预计耗时。批量任务支持进度、取消、缓存复用，并可能以“部分失败”结束；部分失败时可以根据列表重新处理未成功内容。
+
+## 和 AI、知识库、导出的关系
+
+- 本地转写结果可以参与本地知识库检索；
+- 导出时可选择是否包含已有语音转写；
+- AI Search 可能提示某些语音尚未转写，这意味着答案覆盖不完整；
+- 群聊日报默认会统计语音数量和时长，但不等于已经理解了每条语音的具体内容。
+
+## 隐私提示
+
+离线转写本身在本机完成。若你主动把转写结果用于 AI Search、日报或其他 AI 功能，受控文本可能按对应功能的规则发送给你配置的 Provider；详见[数据、隐私与安全](./privacy.md)。
+