From cd2c3cfaeef044786a185aaac289be520605cc8c Mon Sep 17 00:00:00 2001 From: Wxw-Gu Date: Fri, 7 Aug 2026 22:52:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 491 ++++++---------------- docs/README.md | 58 +++ docs/agent/agent-hub.md | 67 +++ docs/agent/api-security.md | 56 ++- docs/agent/api.md | 94 ++++- docs/agent/overview.md | 47 +++ docs/agent/reader-skill.md | 65 ++- docs/agent/release-notes-v2.1.9.md | 17 +- docs/concepts/answer-sources.md | 41 ++ docs/concepts/how-it-works.md | 44 ++ docs/development/overview.md | 55 +++ docs/mac-disable-sip.md | 48 +-- docs/platform/macos.md | 27 ++ docs/skill/wechatexplorer-reader/SKILL.md | 396 ++--------------- docs/user-guide/ai-search.md | 60 +++ docs/user-guide/chat-archive.md | 50 +++ docs/user-guide/export.md | 34 ++ docs/user-guide/getting-started.md | 278 ++++-------- docs/user-guide/knowledge.md | 38 ++ docs/user-guide/privacy.md | 58 +++ docs/user-guide/report.md | 42 ++ docs/user-guide/troubleshooting.md | 62 +++ docs/user-guide/voice.md | 37 ++ package.json | 2 +- 24 files changed, 1175 insertions(+), 992 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/agent/agent-hub.md create mode 100644 docs/agent/overview.md create mode 100644 docs/concepts/answer-sources.md create mode 100644 docs/concepts/how-it-works.md create mode 100644 docs/development/overview.md create mode 100644 docs/platform/macos.md create mode 100644 docs/user-guide/ai-search.md create mode 100644 docs/user-guide/chat-archive.md create mode 100644 docs/user-guide/export.md create mode 100644 docs/user-guide/knowledge.md create mode 100644 docs/user-guide/privacy.md create mode 100644 docs/user-guide/report.md create mode 100644 docs/user-guide/troubleshooting.md create mode 100644 docs/user-guide/voice.md diff --git a/README.md b/README.md index 06f7c60..714f7a5 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ WechatExplorer Logo

-

让 AI 读懂你的微信

+

把微信聊过的事，找回来、问清楚、留下来

- 本地优先的 AI 微信助手
- 聊天记录查看 · AI 问问微信 · 群聊日报 · Agent · 本地 API + 本地优先的微信聊天记录工作台：查看、搜索、提问、总结和导出
+ 查看聊天 · 找回信息 · AI 问答 · 群聊日报 · 语音转写 · 导出 · 实时微信交互

@@ -18,431 +18,214 @@

- 📦 下载最新版 + 下载 WechatExplorer · - 🚀 第一次使用 + 第一次使用 · - 📖 使用说明 + 完整文档

-> ⭐ 如果这个项目帮助到了你，欢迎点一个 Star，支持项目持续更新。 -

- WechatExplorer AI 微信助手界面 + WechatExplorer 主界面

-> 像问 ChatGPT 一样，直接询问你的微信聊天记录。 +## WechatExplorer 是什么 -WechatExplorer 是一个基于 Electron + React + TypeScript 开发的本地优先 AI 微信助手。它不只是查看聊天记录，而是把聊天内容变成可以搜索、总结、分析和交给 Agent 使用的信息。 +WechatExplorer 帮你在自己的电脑上读取和整理微信聊天记录。 -**支持：** +你可以直接浏览聊天，也可以用自然语言提问： -微信聊天记录查看、AI 微信助手、AI 群聊日报、MCP、Agent、本地 API +> “上个月我们讨论过哪些发布问题？” +> “张三之前发过的项目地址在哪里？” +> “技术交流群今天有哪些结论和待办？” -## ✨ 为什么选择 WechatExplorer？ +它和普通聊天记录查看器最大的不同，是 AI 回答可以回到原始聊天核对。你可以看到回答参考了哪些内容、来自哪个会话和时间，再回到消息上下文确认它有没有理解错。 -- ✅ **像 ChatGPT 一样搜索整个微信**：用自然语言提问，快速找到聊天上下文。 -- ✅ **AI 自动生成群聊日报**：自动整理热点、资源、问答和待跟进事项。 -- ✅ **Agent 可直接读取微信聊天**：支持 Codex、Claude Code、MCP 等 AI 工作流。 -- ✅ **本地数据库优先**：聊天数据默认保存在本机，不会自动上传。 -- ✅ **支持微信 3.x / 4.x**：不同微信版本提供对应版本支持。 -- ✅ **多格式导出**：支持 HTML、Markdown、CSV 和 JSON。 +## 你可以用它做什么 -## 🚀 第一次使用 +### 查看和搜索自己的微信记录 -软件已经内置完整的新手引导，通常按下面三步即可开始： +- 浏览联系人、群聊、折叠群聊和公众号消息。 +- 查看文本、图片、视频、语音、文件、链接、引用、小程序等内容。 +- 搜索会话或当前聊天中的关键词。 +- 从 AI 结果跳回对应聊天位置。 -```text -下载软件 - ↓ -连接微信 - ↓ -开始问你的微信 -``` +详细说明：[聊天档案与普通搜索](./docs/user-guide/chat-archive.md) -首次启动会自动进入「第一次使用」页面。连接成功后，软件会显示「开始探索你的微信」；进入主界面后，还可以随时点击左下角「新手引导」重新查看。 +### 直接向微信历史提问 -## 📸 功能预览 +打开“问问微信”，选择搜索范围和时间，然后像提问一样描述你想找的内容。 -### AI 群聊日报 - -
- 点击查看完整日报模板 -
- 完整群聊日报模板 -
- -### AI 问问微信 - -AI 问问微信页面 - -### 本地 API 与 Agent - -本地 API 与 Agent 页面 - -## 🎯 它能帮你做什么 - -### 🤖 AI 问问微信 - -直接向自己的微信提问： - -> “去年我和老板聊过哪些关于涨薪的事情？” -> -> “技术群这周讨论了哪些问题？” -> -> “帮我找到张三发过的项目地址。” - -### 📰 AI 群聊日报 - -选择一个群聊和时间范围，自动生成： - -- ✅ 今日热点 -- ✅ 一句话总结 -- ✅ 资源汇总 -- ✅ 问答整理 -- ✅ 活跃榜 -- ✅ 词云与关键词 - -
- 展开查看日报的完整模块 - -- **今日讨论热点**：梳理群内主要话题，支持热度标签。 -- **一句话速览**：首屏突出今日核心结论与待跟进事项。 -- **实用信息与资源**：提取分享的链接、资源等信息。 -- **重要消息汇总**：标记并展示重要消息，带发送者头像。 -- **有趣对话或金句**：收录群内的精彩对话。 -- **问题与解答**：整理群内的问答内容。 -- **尚未解决 / 今日剧情线**：适合工作群和项目群的回顾与跟进。 -- **今日群相册 / 语音时长榜 / 临时群友称号**：让图片、语音和氛围型内容也能参与日报。 -- **群内数据可视化**：消息热度条形图、话唠榜 TOP5、活跃时间线。 -- **词云 / 关键词**：可视化展示群聊关键词。 -
- -支持导出 HTML 与 PNG，也支持图片理解和图片生成。 - -### 📂 查看聊天 - -浏览微信好友和群聊的聊天记录，支持查看： - -- 文本 -- 图片 -- 视频 -- 语音 -- 文件 - -同时支持头像显示、全局搜索、指定会话搜索、消息防撤回和上下文定位。 - -### 📤 导出聊天 - -支持按会话和时间范围导出聊天记录为 HTML、CSV、JSON 或 Markdown，并可以打开文件所在文件夹。 - -### 🤖 Agent - -通过本地 HTTP API 和内置 Reader Skill，让 Codex、Claude Code 等 Agent 在本机服务运行并获得授权后读取、总结聊天数据。 - -## 🚀 规划与未来（Roadmap） - -WechatExplorer 仍在持续演进，未来会围绕 **AI 大模型 + 微信 + Agent** 持续完善能力。 - -下面是正在设计或计划中的部分功能（不代表发布时间）。 - -
- 点击展开未来规划 - -### 🚧 人物镜像（Persona） - -根据长期聊天记录生成每个人的沟通画像： - -- 兴趣标签 -- 常聊话题 -- 表达风格 -- 个性化沟通参考 - -### 🚧 AI 长期记忆 - -让 AI 持续理解你的聊天历史，在不同时间跨度内建立上下文，支持长期事项追踪和连续对话。 - -### 🚧 微信卡片分享 - -将 AI 日报生成可点击的微信卡片消息，而不仅仅是图片，方便在群聊中传播与查看。 +WechatExplorer 会先在本机查找候选消息，再把整理后的少量来源交给你配置的 AI 模型生成回答。回答中的来源标记可以定位到对应聊天证据；“查看检索详情”还会展示本次查找经历了哪些阶段。

- 微信卡片分享示例 + 问问微信与聊天来源

-### 🚧 退群自动监控 +详细说明：[使用 AI 查找聊天信息](./docs/user-guide/ai-search.md) -自动记录群聊成员变动： +### 让重要信息以后更容易找到 -- 谁加入群聊 -- 谁退出群聊 -- 变动发生的时间 -- 群成员变动记录 +“问问微信”里的“本地知识库”会为当前微信账号建立一份留在本机的可检索资料。它把聊天文本、附件信息和已有语音转写整理起来，让跨会话、跨时间查找更稳定。 + +- 用户主动点击后才会建立。 +- 支持同步最新记录。 +- 显示已索引消息、知识片段和磁盘占用。 +- 可以从设置中清理，清理不会删除微信原始数据库。 + +详细说明：[本地知识库](./docs/user-guide/knowledge.md) + +### 检查 AI 回答依据 + +AI 给出答案后，你可以继续确认： + +- 它参考了哪几条聊天内容； +- 来源属于哪个人、会话和时间； +- 回答中的来源编号对应哪条原始消息； +- 本次搜索经过了哪些步骤、用了多长时间； +- 当前结果是否只覆盖了部分聊天或遗漏了未转写语音。 + +想进一步了解来源标记和查找过程，阅读[如何核对 AI 的回答来源](./docs/concepts/answer-sources.md)。 + +### 生成群聊日报 + +选择群聊和时间范围后，可以让 AI 把聊天整理成热点、重要消息、资源、问答、待办、未解决事项、活跃统计和图片精选，并导出 HTML 与 PNG 长图。

- 退群自动监控示例 + 群聊日报示例

-### 💡 更多 AI 能力 +详细说明：[生成群聊日报](./docs/user-guide/report.md) -包括会议纪要、聊天知识库、长期事项追踪、个人成长分析等更多探索。 +### 转写微信语音 -WechatExplorer 希望不仅仅是一个聊天记录查看工具，更希望成为一个能够理解、整理和协助管理微信信息的 AI 工作平台。 +WechatExplorer 提供本地离线语音识别： -如果你有好的想法，欢迎提交 Issue 或 Pull Request，一起把它做得更好。 +- 在聊天气泡中转写单条语音； +- 按联系人或群聊批量转写； +- 转写结果可以参与本地知识库检索和 HTML 导出； +- 本地转写本身不需要把语音文件发送给在线 AI；如果你随后用转写结果进行 AI 问答或日报，文字会按对应功能的规则处理。 -
+详细说明：[语音转文字](./docs/user-guide/voice.md) -## ⚙️ 快速开始 +### 导出长期可用的聊天档案 -### 下载并安装 +支持 HTML、CSV、JSON 和 Markdown。HTML 可携带媒体、头像和可选语音转写，也可以压缩为 ZIP；再次使用同名档案导出时可以增量合并新消息。 -当前 WechatExplorer / 迹忆版本：`v2.1.7`。 +详细说明：[导出聊天](./docs/user-guide/export.md) -应用安装包：[WechatExplorer GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases)。Windows 选择 `-setup.exe`，macOS 按处理器架构选择对应 `.dmg`。 +### 如果你要让 Agent 读取微信数据 -| 系统 | 已测试的微信客户端 | -| ------- | ------------------------------------------------------------------------------------------------- | -| Windows | [微信 Windows `4.1.9.57`](https://github.com/iibob/wechat-win-archive/releases#release-v4.1.9.57) | -| macOS | [微信 macOS `4.1.8.100`](https://github.com/zsbai/wechat-versions/releases/tag/4.1.8.100) | +WechatExplorer 提供 Local HTTP API 和 Reader Skill。安装后，Codex、Claude Code、OpenClaw 等 Agent 可以在你的电脑上按需查询聊天： -微信客户端来自上表对应的第三方版本存档，请自行核对来源与文件完整性。 +> “总结今天技术交流群讨论了什么。” +> “过去一周有没有人提到某个项目？” -正常覆盖安装只会替换应用程序文件，WechatExplorer / 迹忆不会主动删除或修改微信原始聊天记录；但应用缓存和本地设置可能随版本升级变化。升级前仍建议使用微信官方迁移或备份功能备份重要记录，不要将唯一副本保存在单一设备。 +它提供的是随应用安装的 Reader Skill 和本机 Local HTTP API。连接后，Agent 可以按需查找联系人、群聊和聊天记录，再帮你做总结。安装和完整技术说明请看[Agent 接入概览](./docs/agent/overview.md)与[Local HTTP API](./docs/agent/api.md)。 -### 连接微信 +### 连接微信机器人，让 AI 参与实时微信工作 -按照软件内置的「第一次使用」引导完成连接： +除了读取过去的聊天，你还可以在应用里的“Agent”页面（页面标题为“Agent Hub”）扫码连接一个微信机器人账号。机器人收到你发来的文字后，会在本机调用 WechatExplorer 已连接的聊天数据，并把结果回复给发消息的人。 -1. 确认微信数据目录。 -2. 让微信停在登录页面。 -3. 点击“开始获取”，按提示完成连接。 +目前已经支持的实时任务包括： -Windows 已完整支持，不需要关闭 SIP。macOS 首次自动获取数据库密钥前，需要关闭 SIP 并完成系统授权。 +- 查看最近会话； +- 查询你和某位联系人的近期聊天； +- 用已配置的 AI 总结你和某位联系人近 7 天的聊天； +- 生成今天、昨天或近 7 天的群聊总结图片； +- 总结指定群成员在群里的近期发言； +- 对不需要读取聊天的普通文字请求给出简短 AI 回复。 -### 配置 AI +例如，你可以直接给机器人发“最近 5 个会话”，或“生成产品交流群今天的群聊总结图片”。需要读取历史数据时，WechatExplorer 必须已经连接微信数据库；需要总结或自然语言理解时，还要在“设置 → AI 模型”中配置可用的 AI 服务。 -进入「设置 → AI 模型」，添加模型服务商并填写 API Key，保存并测试成功后即可使用「问问微信」和「日报」。支持： +这条路径和上面的 Reader Skill / Local HTTP API 不同：Reader Skill/API 是外部 Agent 主动查询历史微信数据；Agent Hub 则是微信机器人收到实时消息后处理并回复。当前实时入口主要处理文字消息，不应把它理解成支持任意媒体理解、群发、定时任务或通用自主操作的机器人。 -- OpenAI -- DeepSeek -- Claude -- Moonshot -- OpenAI 兼容接口 +详细步骤和能力边界见[Agent Hub：从微信里向本机助手提问](./docs/agent/agent-hub.md)。 -### 下一步 +## 它如何工作 -| 你想做什么 | 从哪里开始 | -| ----------------- | ---------------------------------------------------------------- | -| 重新查看连接步骤 | 点击左下角「新手引导」 | -| 直接向微信提问 | 打开「问问微信」 | -| 生成群聊日报 | 打开「日报」 | -| 浏览聊天记录 | 打开「档案」 | -| 导出聊天记录 | 打开「导出」 | -| 让 Agent 读取微信 | [Reader Skill 文档](./docs/skill/wechatexplorer-reader/SKILL.md) | - -## 🖥️ 支持平台与微信版本 - -- **Windows**：已完整支持 Windows x64，不需要关闭 SIP。 -- **macOS**：支持 Intel 和 Apple Silicon；首次自动获取数据库密钥前，需要关闭 SIP 并完成系统授权。 -- **微信 3.0**：请使用 [v1.1.0 版本](https://github.com/Wxw-Gu/WechatExplorer/releases/tag/v1.1.0)。 -- **微信 4.0**：使用当前 Releases 中的最新版。 - -不同微信版本、账号和数据目录可能存在差异，遇到连接问题时请优先参考 [使用说明](./docs/user-guide/getting-started.md)。 - -## 🔒 隐私与权限 - -- WechatExplorer 只读取你有权访问的本机微信数据。 -- 不使用 AI 时，应用不会因为读取聊天记录而自动上传聊天内容。 -- 使用 AI 问问微信、日报或图片理解时，相关内容会发送到你配置的模型服务。 -- 本地 API 默认监听 `127.0.0.1`，无鉴权；请按可信网络范围配置。 -- 消息防撤回、图片解密和数据库密钥等能力都应只用于你有权访问的数据。 - -## 🔌 高级能力：本地 HTTP API 与 Agent - -
- 展开本地 HTTP API、Reader Skill 和 Agent 说明 - -WechatExplorer 内置一个本地 HTTP API 服务，默认监听 `127.0.0.1:6131`，纯本地、无鉴权。完成数据库连接后，API 会自动启用。 - -### 启用本地 API - -1. 安装并启动 WechatExplorer。 -2. 完成首次密钥配置，解锁 WCDB 数据库。 -3. 在 `http://127.0.0.1:6131` 使用本地 API。 - -### 7×24 提供 API（菜单栏常驻模式） - -默认情况下，关闭主窗口时 macOS 会让 app 继续运行，但 Windows / Linux 会退出。如果希望主窗口关闭后 API 服务仍可用，可以启用菜单栏模式： - -```bash -WXE_TRAY=1 open /Applications/WechatExplorer.app -/Applications/WechatExplorer.app/Contents/MacOS/WechatExplorer --tray +```mermaid +flowchart LR + A[本机微信数据] --> B[WechatExplorer 读取与解析] + B --> C[聊天档案] + B --> D[本地知识库与搜索] + D --> E[筛选相关聊天来源] + E --> F[用户配置的 AI 模型] + F --> G[带来源的回答] + E --> H[日报与导出] + B --> I[按需交给本地 Agent] ``` -启用后： +- 微信数据库读取、聊天解析、知识库索引和离线语音识别在本机完成。 +- 普通浏览、普通搜索和导出不要求配置 AI 服务。 +- 你主动使用并确认“问问微信”、群聊日报或图片理解时，完成任务所需的内容可能发送到你选择的模型服务。 +- “问问微信”会先在本机缩小范围，不会默认把整个微信数据库作为一次模型请求发送。 +完整边界见：[数据、隐私与安全](./docs/user-guide/privacy.md) -- macOS Dock 图标自动隐藏。 -- 菜单栏出现 WechatExplorer 图标，可重新打开主窗口、查看 API 状态。 -- 主窗口关闭后 API 服务继续运行。 +## 快速开始 -### API 端点一览 +1. 从 [GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) 下载安装包。 +2. 启动 WechatExplorer，按照“第一次使用”页面选择微信数据目录。 +3. 第一次使用请先点击“开始连接”，按页面提示准备连接组件并获取数据库密钥；只有已经有密钥的高级用户才需要“手动连接”。 +4. 连接成功后打开“档案”，确认联系人和聊天消息已经出现。 +5. 需要 AI 时，在“设置 → AI 模型”添加并测试 AI 服务。 +6. 打开“问问微信”，按需要建立本地知识库；如果正在同步，等待状态变为“已同步”后再开始第一个问题。 -| 端点 | 说明 | -| ------------------------------------------------ | --------------------------------------- | -| `GET /api/v1/health` | 健康检查 | -| `GET /api/v1/current_time` | 获取当前本地时间，用于“今天 / 昨天”换算 | -| `GET /api/v1/contact?filter=xxx` | 联系人 / 群聊列表 | -| `GET /api/v1/chatroom?keyword=xxx` | 搜索群聊 | -| `GET /api/v1/chatlog?talker=xxx&time=2026-07-03` | 聊天记录 | -| `GET /api/v1/group_snapshot?md5=xxx` | 群成员快照 | -| `GET /api/v1/resolve?q=群昵称` | 把昵称、wxid 或 md5 解析成 md5 | +当前代码面向微信 4.x 数据结构。Windows 发布构建为 x64；macOS 发布构建提供 Intel 和 Apple Silicon 版本。macOS 首次连接可能需要按页面提示完成系统授权；如果页面提示处理 SIP，请先阅读对应说明。具体步骤和限制见[第一次使用](./docs/user-guide/getting-started.md)。 -详细参数、返回结构和时间格式见 [Reader Skill 文档](./docs/skill/wechatexplorer-reader/SKILL.md)。 +完整步骤：[第一次使用 WechatExplorer](./docs/user-guide/getting-started.md) -### 安装 Reader Skill，让 Agent 读取和总结群聊 +## 配置 AI -WechatExplorer 已内置 Reader Skill，无需手动复制仓库中的 `SKILL.md`： +需要 AI 问答、群聊日报或图片理解时，在“设置 → AI 模型”添加并测试一个服务。应用支持云端服务、Ollama 等本地服务和自定义接口；具体服务商的配置、计费和数据规则由服务商决定。 -1. 启动 WechatExplorer，并确认数据库已连接、本地 API 已运行。 -2. 打开应用内的「API」页面。 -3. 在“快速接入”中选择 Codex 或 Claude Code。 -4. 点击复制安装指令，将指令粘贴给对应 Agent 执行。 -5. 安装完成后，可以直接向 Agent 提问： +使用本地服务可以减少数据离开电脑的路径，但本地服务的日志和配置仍由你自己负责。 -> “今天技术交流群聊了什么？” +开发者和 Agent 用户可以从[Agent 接入概览](./docs/agent/overview.md)开始，再按需要查看[Local HTTP API](./docs/agent/api.md)与[API 安全](./docs/agent/api-security.md)。 -Reader Skill 会自动获取本机时间、定位目标群聊、读取所需聊天记录，并结合上下文生成总结。 +## 文档 -### curl 调试示例（可选） +- [文档首页](./docs/README.md) +- [第一次使用](./docs/user-guide/getting-started.md) +- [聊天档案与搜索](./docs/user-guide/chat-archive.md) +- [AI 查找聊天信息](./docs/user-guide/ai-search.md) +- [本地知识库](./docs/user-guide/knowledge.md) +- [群聊日报](./docs/user-guide/report.md) +- [语音转文字](./docs/user-guide/voice.md) +- [导出聊天](./docs/user-guide/export.md) +- [数据、隐私与安全](./docs/user-guide/privacy.md) +- [Agent 接入](./docs/agent/overview.md) +- [微信机器人与 Agent Hub](./docs/agent/agent-hub.md) +- [Local HTTP API](./docs/agent/api.md) +- [开发与测试](./docs/development/overview.md) -不使用 Agent 时，也可以通过 `curl` 直接调试本地 HTTP API： +## 本地开发 -```bash -# 健康检查 -curl http://127.0.0.1:6131/api/v1/health - -# 今天“摸鱼交流群”的聊天记录 -curl -G "http://127.0.0.1:6131/api/v1/chatlog" \ - --data-urlencode "talker=摸鱼交流群" \ - --data-urlencode "time=$(date +%Y-%m-%d)" - -# 把群昵称解析成 md5 -curl -G "http://127.0.0.1:6131/api/v1/resolve" \ - --data-urlencode "q=摸鱼交流群" -``` - -
- -## 🛠️ 开发配置（可选） - -
- 展开开发配置、环境变量和构建命令 - -本地开发需要 Node.js（建议当前 LTS）和 pnpm 7+： +需要 Node.js、pnpm 7+、对应平台的 Electron/native 构建环境，以及 Go（用于微信连接器）。 ```bash pnpm install pnpm dev ``` -本地开发时运行 `pnpm dev` 会在 `.env` 不存在时自动从 `.env.example` 复制一份。成品用户不需要配置 `.env`，也可以直接在软件“设置”里填写 AI 和图片解密配置。 - -### 环境变量 - -| 变量名 | 说明 | 示例 | -| ----------------------- | ----------------------------- | --------------------------- | -| `VITE_DB_KEY` | 微信数据库密钥（32 字节 hex） | `YOUR_DB_KEY_HERE` | -| `VITE_IMAGE_XOR_KEY` | 图片解密 XOR 密钥（hex 格式） | `0x40` | -| `VITE_IMAGE_AES_KEY` | 图片解密 AES 密钥（16 字符） | `YOUR_AES_KEY_HERE` | -| `VITE_DEEPSEEK_API_KEY` | DeepSeek API Key | `sk-xxx` | -| `VITE_AI_BASE_URL` | AI API 地址 | `https://api.deepseek.com` | -| `VITE_AI_MODEL` | AI 模型 | `deepseek-chat` | -| `VITE_FILTER_MSG_TYPES` | 过滤的消息类型 | `分享消息,图片,表情包,视频` | - -常用命令： +常用检查： ```bash -pnpm typecheck # 类型检查 -pnpm lint # ESLint 检查 -pnpm build # 构建 -pnpm build:win # 构建 Windows x64 安装包 +pnpm typecheck +pnpm test:unit +pnpm test:component +pnpm test:integration +pnpm test:e2e:build ``` -
+完整说明：[开发、测试与构建](./docs/development/overview.md) -## ❓ FAQ +## 支持与反馈 -
- 展开常见问题 +遇到问题时，先查看[常见问题与排查](./docs/user-guide/troubleshooting.md)。提交 Issue 时请提供操作系统、微信版本、WechatExplorer 版本、复现步骤和已遮挡敏感信息的截图。 -### 我已经连接成功，怎么重新查看教程？ +请仅处理你有权访问的数据，并遵守适用的法律法规、组织政策和微信使用规则。数据库读取、解密、自动化和机器人能力都可能受平台版本与账号环境影响。 -点击左下角「新手引导」。首次连接流程、AI 配置入口、群聊日报、问问微信和完整教程都会再次展示。 +## 许可说明 -### 微信 3.0 应该下载哪个版本？ - -请使用 [v1.1.0 版本](https://github.com/Wxw-Gu/WechatExplorer/releases/tag/v1.1.0)。微信 4.0 用户使用当前 Releases 中的最新版。 - -### AI 问问微信或群聊日报不可用怎么办？ - -进入「设置 → AI 模型」，添加模型服务商并填写 API Key，确认 Base URL 和模型名称正确，然后保存并测试连接。 - -### 连接失败怎么办？ - -请先查看 [使用说明](./docs/user-guide/getting-started.md) 的“遇到问题”部分，重点确认微信数据目录、微信登录状态、微信版本和 macOS SIP 设置。 - -
- -## ⚠️ 免责声明 - -本项目仅供学习和研究使用。请勿用于非法用途。开发者不对使用本项目造成的任何后果负责。请遵守相关法律法规和微信使用协议，并仅处理你有权访问的数据。 - -## ⭐ Star History - - - - - - Star History Chart - - - -## 致谢 - -
- 展开致谢与参考项目 - -WechatExplorer 在开发过程中参考了多个优秀的开源项目，感谢这些项目作者的工作与分享。 - -特别感谢： - -- **[WechatMessageExplorer](https://github.com/svcvit/WechatMessageExplorer)** - - 提供了微信数据库解析相关思路。 -- **[WeFlow](https://github.com/hicccc77/WeFlow)** - - 参考了数据库密钥获取、图片解密等实现思路。 -- **[chatlog](https://github.com/sjzar/chatlog)** - - 提供了聊天记录导出与数据处理方面的参考。 - -在此基础上，WechatExplorer 进行了重新设计与实现，包括： - -- AI 问问微信 -- AI 群聊日报 -- 本地 HTTP API -- Reader Skill -- Agent Hub -- 新手引导 -- Electron + React 全新界面 -- 本地优先 AI 工作流 - -感谢所有开源作者。 - -
- -## 💬 交流与反馈 - -请先完成 [第一次使用与问题排查](./docs/user-guide/getting-started.md)，再查看问题排查和 FAQ。只有自助排查仍无法解决时，再扫码进入交流群。 - -

- WechatExplorer 交流与售后群二维码 -

+仓库中的第三方组件、模型和连接器遵循各自的许可证。当前仓库根目录未提供独立的项目 `LICENSE` 文件；贡献、复制或再分发前，请先向维护者确认 WechatExplorer 本身的许可范围。 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..98d090e --- /dev/null +++ b/docs/README.md @@ -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 行为和媒体读取结果可能随系统、微信客户端和服务商变化。 diff --git a/docs/agent/agent-hub.md b/docs/agent/agent-hub.md new file mode 100644 index 0000000..1c86a04 --- /dev/null +++ b/docs/agent/agent-hub.md @@ -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 未就绪分别需要重新扫码、修复安装、重新登录或先完成微信数据库连接。 diff --git a/docs/agent/api-security.md b/docs/agent/api-security.md index 06c976f..e93100d 100644 --- a/docs/agent/api-security.md +++ b/docs/agent/api-security.md @@ -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 由应用生成，使用 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="" +``` + +## 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) diff --git a/docs/agent/api.md b/docs/agent/api.md index ef0da0f..66f49fd 100644 --- a/docs/agent/api.md +++ b/docs/agent/api.md @@ -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 从 WechatExplorer → API Center → API Token 获取。 -- Token 不得放入 URL、仓库或共享配置。 +## 基本信息 + +- 默认地址：`http://127.0.0.1:6131` +- API 前缀：`/api/v1` +- 默认只监听 loopback；不要把它当作公网服务。 +- `/api/v1/health` 无需 Token；其他端点需要 `Authorization: Bearer `。 +- 请求体使用 JSON；响应为 JSON。 + +## 最小请求 ```bash -export WECHATEXPLORER_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。 diff --git a/docs/agent/overview.md b/docs/agent/overview.md new file mode 100644 index 0000000..915b267 --- /dev/null +++ b/docs/agent/overview.md @@ -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)。 diff --git a/docs/agent/reader-skill.md b/docs/agent/reader-skill.md index 7ad3a67..b290e4e 100644 --- a/docs/agent/reader-skill.md +++ b/docs/agent/reader-skill.md @@ -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=`。 -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="" + ``` + +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)。 diff --git a/docs/agent/release-notes-v2.1.9.md b/docs/agent/release-notes-v2.1.9.md index e2a2c7f..b1a456c 100644 --- a/docs/agent/release-notes-v2.1.9.md +++ b/docs/agent/release-notes-v2.1.9.md @@ -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 `，否则返回 `401`。 -- `GET /api/v1/health` 保持公开。 -- 老用户升级后会自动生成并安全保存 Token，不改变原有 apiEnabled、host 或 port 设置。 -- Token 可在 WechatExplorer → API Center 中显示、复制和重新生成。 +- 历史版本中，`GET /api/v1/contact` 等数据请求可能直接返回内容； +- 2.1.9 中，相同请求必须携带 `Authorization: Bearer `，否则返回 `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)。 diff --git a/docs/concepts/answer-sources.md b/docs/concepts/answer-sources.md new file mode 100644 index 0000000..ca6b602 --- /dev/null +++ b/docs/concepts/answer-sources.md @@ -0,0 +1,41 @@ +# 如何核对 AI 的回答来源 + +## 先记住一件事 + +AI 回答后，你可以继续查看它参考了哪些聊天内容、这些内容来自哪个会话和时间，并跳回原始消息检查上下文。 + +这让 WechatExplorer 和只给一段摘要的聊天机器人不同：答案不是终点，来源也应该能被你检查。 + +## 三类来源信息 + +在产品界面和检索详情中，你可能看到这些名称： + +- **Evidence**：AI 回答所依据的原始聊天片段。 +- **Citation**：回答中某个结论对应的来源标记。 +- **Search Trace**：本次查找经历了哪些阶段、每一步用了多久、覆盖是否完整。 + +普通用户不需要记住英文名。判断一个回答是否可信时，按“来源 → 原消息 → 上下文”检查即可。 + +## 推荐的核对顺序 + +1. 先看回答是否明确区分事实、推断和不确定信息； +2. 打开来源，检查发送者、会话和时间； +3. 跳回档案，查看消息前后文，确认是否存在引用、转发或后续修正； +4. 检查提示中是否有未转写语音、缺失媒体或只覆盖部分范围； +5. 对重要决定、金额、日期和责任人，不要只依据 AI 摘要。 + +## 为什么来源可能不完整 + +来源覆盖受时间范围、会话范围、索引状态和可读媒体影响。例如： + +- Knowledge 正在同步时，新的分析会被暂停； +- 语音没有转写时，AI 可能只能看到消息类型； +- 图片无法读取或未启用图片理解时，AI 不应声称知道图片内容； +- 你只选择了一个群，答案不会自动代表所有聊天。 + +看到“可能遗漏”或“部分覆盖”时，扩大范围、先完成同步或检查原始媒体后再问。 + +## 这不是事实保证 + +Evidence 和 Citation 能告诉你“模型看到了什么”，不能保证模型没有误读。最终判断仍应回到原始消息，尤其是涉及隐私、法律、财务、医疗或工作决策时。 + diff --git a/docs/concepts/how-it-works.md b/docs/concepts/how-it-works.md new file mode 100644 index 0000000..1f6d63e --- /dev/null +++ b/docs/concepts/how-it-works.md @@ -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 | + +先按任务使用，再在需要排查或开发集成时阅读术语。 + diff --git a/docs/development/overview.md b/docs/development/overview.md new file mode 100644 index 0000000..bb30742 --- /dev/null +++ b/docs/development/overview.md @@ -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”可以保留，以防用户照抄错误配置。 diff --git a/docs/mac-disable-sip.md b/docs/mac-disable-sip.md index bb95c75..aae6d55 100644 --- a/docs/mac-disable-sip.md +++ b/docs/mac-disable-sip.md @@ -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”当作默认安装步骤；只有当当前连接页面明确要求时才处理，并在完成后恢复系统安全设置。 diff --git a/docs/platform/macos.md b/docs/platform/macos.md new file mode 100644 index 0000000..f525775 --- /dev/null +++ b/docs/platform/macos.md @@ -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 处理器匹配的构建。不同架构、微信版本和系统授权状态可能导致连接结果不同；文档不对所有组合做兼容性保证。 + diff --git a/docs/skill/wechatexplorer-reader/SKILL.md b/docs/skill/wechatexplorer-reader/SKILL.md index ce8a461..f037728 100644 --- a/docs/skill/wechatexplorer-reader/SKILL.md +++ b/docs/skill/wechatexplorer-reader/SKILL.md @@ -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="" -``` +`/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`：用户还没有完成数据库连接或对应服务未就绪。 +- 空结果：缩小/扩大时间范围，确认账号和会话，再检查媒体或语音是否可读。 diff --git a/docs/user-guide/ai-search.md b/docs/user-guide/ai-search.md new file mode 100644 index 0000000..fec4b98 --- /dev/null +++ b/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)。 + diff --git a/docs/user-guide/chat-archive.md b/docs/user-guide/chat-archive.md new file mode 100644 index 0000000..d3334e8 --- /dev/null +++ b/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)。 + diff --git a/docs/user-guide/export.md b/docs/user-guide/export.md new file mode 100644 index 0000000..61952d6 --- /dev/null +++ b/docs/user-guide/export.md @@ -0,0 +1,34 @@ +# 导出聊天和报告 + +导出适合把微信里的重要讨论保存成可阅读、可分享或可继续处理的文件。 + +## 支持的格式 + +- **HTML**：适合完整阅读，可包含媒体和头像； +- **Markdown**：适合笔记、版本管理和再次编辑； +- **CSV**：适合表格分析； +- **JSON**：适合程序处理和数据归档。 + +## 导出步骤 + +1. 打开“导出”。 +2. 选择一个或多个联系人/群聊。 +3. 选择时间范围和消息类型。 +4. 按需要打开媒体、头像、原图/缩略图、语音转写和保留缺失资源等选项。 +5. 设置文件名，必要时选择 ZIP，然后开始导出。 +6. 在导出任务中心查看读取、解析、媒体处理、转写、写入和压缩进度；完成后打开文件位置。 + +## 多会话和增量导出 + +HTML 支持把最多五个会话合并到一个档案中。再次使用相同名称导出时，可以把新消息增量合并到已有档案；这不会删除之前已导出的消息。 + +## 媒体怎么处理 + +原图、缩略图、缺失资源和头像都可能影响导出大小与可读性。想要小文件时关闭媒体或选择缩略图；想要长期保存时，确认原始媒体目录仍可访问，并考虑 ZIP 归档。 + +语音转写是可选步骤。只有已经成功转写的语音才会写入导出内容，导出不会替你自动补齐失败的识别。 + +## 导出和原始数据的关系 + +导出是复制/整理结果，不会修改微信原始数据库。删除导出文件也不会影响应用内聊天记录或本地知识库。 + diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md index 9ebc694..1e02b6e 100644 --- a/docs/user-guide/getting-started.md +++ b/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. 完成你的第一个任务 -首次启动会自动进入「第一次使用」页面。页面会根据当前系统显示连接方式和注意事项： +### 只是想找一句话 -

- 第一次使用连接页面 -

+进入“档案”，选择联系人或群聊，在会话内搜索关键词。适合你记得原话、姓名、链接或大致关键词的情况。 -通常按下面三步操作即可： +### 想找一个模糊的结论 -1. **确认微信数据目录**：自动识别不准确时，在页面中修改存储路径。 -2. **让微信停在登录页面**：如果微信已经登录，先退出微信登录，不只是关闭窗口。 -3. **点击开始获取**：软件会尝试获取数据库密钥。按提示可以登录后，再回到微信完成登录。 +进入“问问微信”，直接描述问题，例如： -Windows 已完整支持，不需要关闭 SIP。macOS 首次获取密钥前，需要按页面提示完成授权并关闭 SIP。 +- “上个月技术群讨论过哪些发布问题？” +- “张三之前发过的项目地址在哪里？” +- “过去一周有没有人提到退款？” -### 3. 连接成功 +这就是 AI Search：它会先帮你从本机聊天中找出相关内容，再让你配置的模型组织答案。你不需要知道关键词在哪，但问题越具体，结果越容易核对。 -连接成功后，软件会进入聊天档案，并显示「开始探索你的微信」引导： +### 想让 AI 的答案可核对 -

- 连接成功后的新手引导 -

+回答生成后，打开来源或检索详情，查看它参考的聊天内容、会话、时间和原始消息。你可以从来源直接跳回“档案”检查上下文。 -这里推荐先体验「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)。 -

- 主界面左下角新手引导入口 -

+## 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 无法访问分别有不同处理方式。 diff --git a/docs/user-guide/knowledge.md b/docs/user-guide/knowledge.md new file mode 100644 index 0000000..0917109 --- /dev/null +++ b/docs/user-guide/knowledge.md @@ -0,0 +1,38 @@ +# 把聊天变成更容易再次找到的本地资料 + +## 你为什么需要 Knowledge + +如果你经常查同一批工作群、项目讨论或长期联系人，只靠每次临时翻聊天会越来越慢。Knowledge 会在本机建立一份可重复查找的索引，让“以前聊过什么”这类问题更容易跨会话、跨时间找到相关内容。 + +它不是另一个聊天窗口，也不会替你修改微信原始数据库；它是 WechatExplorer 为当前账号维护的本地加速资料。 + +## 建立和同步 + +Knowledge 不会在第一次连接后自动悄悄建立。进入“问问微信”后，在“本地知识库”区域点击： + +- **建立本地知识库**：第一次读取当前账号的可检索聊天； +- **同步最新记录**：已有索引时，只补充新增或变化的内容。 + +同步会在后台运行，完成后页面显示已索引消息、知识片段和磁盘占用。同步期间暂不能开始新的 AI 分析；同步异常时，旧索引仍可能可以继续使用。 + +## 账号隔离 + +每个微信账号使用独立的本地索引。切换账号时，应用不会把一个账号的索引混入另一个账号的搜索结果。 + +## 什么时候值得建立 + +- 你要跨多个群查过去几个月的内容； +- 你反复查同一个项目、客户或主题； +- 你希望 AI 先从更稳定的本地资料中找来源； +- 你想减少每次搜索都重新读取大量原始记录的等待。 + +只偶尔查一条原话时，直接使用档案搜索通常更快。 + +## 清理和重建 + +在“设置 → 缓存与清理”中可以清理本地知识库索引、检索记录和导出任务缓存。清理索引不会删除微信原始聊天记录或数据库密钥；之后可以回到“问问微信”重新建立。 + +## 产品术语（可选） + +源码和日志中可能出现 SQLite、FTS、Chunk、索引等词。它们描述的是本地存储和检索实现，不是你开始使用 WechatExplorer 的前置知识。 + diff --git a/docs/user-guide/privacy.md b/docs/user-guide/privacy.md new file mode 100644 index 0000000..6831380 --- /dev/null +++ b/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 `； +- 浏览器 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； +- 定期在“设置 → 缓存与清理”清理不再需要的检索、导出和索引缓存； +- 在共享电脑上退出应用并保护系统账户。 diff --git a/docs/user-guide/report.md b/docs/user-guide/report.md new file mode 100644 index 0000000..5f1a759 --- /dev/null +++ b/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 不可用时先检查模型配置和网络/本地服务状态。 + diff --git a/docs/user-guide/troubleshooting.md b/docs/user-guide/troubleshooting.md new file mode 100644 index 0000000..5c74d41 --- /dev/null +++ b/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 `； +5. Token 重新生成后，Agent 配置已同步更新。 + +详细步骤见[Agent 接入概览](../agent/overview.md)和[API 安全](../agent/api-security.md)。 + diff --git a/docs/user-guide/voice.md b/docs/user-guide/voice.md new file mode 100644 index 0000000..cc87855 --- /dev/null +++ b/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)。 + diff --git a/package.json b/package.json index 5ed3e2c..7219207 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "wechatexplorer", - "version": "2.1.8", + "version": "2.1.9", "packageManager": "pnpm@7.33.7", "description": "macOS / Windows 微信聊天记录查看与 AI 群聊总结助手", "keywords": [