diff --git a/README.md b/README.md index 6097231..2c4a2fd 100644 --- a/README.md +++ b/README.md @@ -1,145 +1,310 @@ # WechatExplorer -macOS / Windows 微信聊天记录查看与 AI 分析工具。 -是一个基于 Electron + React + TypeScript 开发的本地微信聊天记录查看与分析工具。它支持查看解密后的微信数据库内容，提供 AI 智能检索、群聊总结和多格式聊天记录导出功能。 +

+ WechatExplorer Logo +

-## 项目说明 +

让 AI 读懂你的微信

-本项目的目标，是在自己的电脑上实现“本地查看微信聊天记录 + 一键生成群聊总结”的实用能力。 +

+ 本地优先的 AI 微信助手
+ 聊天记录查看 · AI 问问微信 · 群聊日报 · Agent · 本地 API +

-在微信 4.0 数据库解析、解密思路上，项目参考了 [WeFlow](https://github.com/hicccc77/WeFlow) 等开源项目的实现方式；此项目围绕我自己的使用场景做的定制化工具，重点放在本地聊天记录查看、群聊总结和个人工作流集成上。 +

+ GitHub stars + GitHub downloads + Latest release +

-> macOS 支持相对稳定；Windows 已初步支持 但因聊天记录大/机械硬盘等问题 会有所卡顿，仍在持续兼容不同微信版本与本地目录结构。 +

+ 📦 下载最新版 + · + 🚀 第一次使用 + · + 📖 使用说明 +

-## ✨ 功能特性 +> ⭐ 如果这个项目帮助到了你，欢迎点一个 Star，支持项目持续更新。 -- **聊天记录查看**: 浏览微信好友和群聊的聊天记录，支持头像显示。 -- **AI 智能检索**: 支持全局搜索、指定会话搜索和自然语言提问，帮助快速定位聊天主题与相关证据。 -- **消息防撤回**: 可在设置中开启，归档并高亮查看对方已撤回消息。 -- **AI 智能总结**: 支持多模型服务配置（DeepSeek/GPT-4o/Claude/Moonshot），一键总结群聊精华内容，生成话题报告。 -- **群聊日报生成**: 支持围绕群聊内容生成日报，通常会覆盖以下模块中的部分或全部内容： - - **今日讨论热点**: 梳理群内主要话题，支持热度标签。 - - **一句话速览**: 首屏突出今日核心结论与待跟进事项。 - - **实用信息与资源**: 提取分享的链接、资源等信息。 - - **重要消息汇总**: 标记并展示重要消息，带发送者头像。 - - **有趣对话或金句**: 收录群内的精彩对话。 - - **问题与解答**: 整理群内的问答内容。 - - **尚未解决 / 今日剧情线**: 更适合工作群和项目群的回顾与跟进。 - - **今日群相册 / 语音时长榜 / 临时群友称号**: 让图片、语音和氛围型内容也能参与日报。 - - **群内数据可视化**: 消息热度条形图、话唠榜 TOP5、活跃时间线。 - - **词云/关键词**: 可视化展示群聊关键词。 -- **图片生成**: 将 AI 总结的内容生成精美图片，方便分享。 -- **数据导出**: 支持将聊天记录导出为 HTML、CSV、JSON 和 Markdown，支持按时间范围导出并打开文件所在文件夹。 -- **诊断日志**: 可在设置的高级选项中控制诊断日志，方便排查运行异常。 -- **安全隐私**: 所有数据仅在本地处理，AI 功能需自行配置 API Key。 +

+ WechatExplorer AI 微信助手界面 +

-## 📸 预览 +> 像问 ChatGPT 一样，直接询问你的微信聊天记录。 -### 日报模板 +WechatExplorer 是一个基于 Electron + React + TypeScript 开发的本地优先 AI 微信助手。它不只是查看聊天记录，而是把聊天内容变成可以搜索、总结、分析和交给 Agent 使用的信息。 + +**支持：** + +微信聊天记录查看、AI 微信助手、AI 群聊日报、MCP、Agent、本地 API + +## ✨ 为什么选择 WechatExplorer？ + +- ✅ **像 ChatGPT 一样搜索整个微信**：用自然语言提问，快速找到聊天上下文。 +- ✅ **AI 自动生成群聊日报**：自动整理热点、资源、问答和待跟进事项。 +- ✅ **Agent 可直接读取微信聊天**：支持 Codex、Claude Code、MCP 等 AI 工作流。 +- ✅ **本地数据库优先**：聊天数据默认保存在本机，不会自动上传。 +- ✅ **支持微信 3.x / 4.x**：不同微信版本提供对应版本支持。 +- ✅ **多格式导出**：支持 HTML、Markdown、CSV 和 JSON。 + +## 🚀 第一次使用 + +软件已经内置完整的新手引导，通常按下面三步即可开始： + +```text +下载软件 + ↓ +连接微信 + ↓ +开始问你的微信 +``` + +首次启动会自动进入「第一次使用」页面。连接成功后，软件会显示「开始探索你的微信」；进入主界面后，还可以随时点击左下角「新手引导」重新查看。 + +## 📸 功能预览 + +### AI 群聊日报
点击查看完整日报模板
- 完整日报模板 + 完整群聊日报模板
-### AI 群聊日报界面 +### AI 问问微信 -AI 群聊日报页面 +AI 问问微信页面 -### 检索界面 +### 本地 API 与 Agent -检索页面 +本地 API 与 Agent 页面 -### 本地 API 与 Reader Skill +## 🎯 它能帮你做什么 -本地 API 与 Reader Skill 页面 +### 🤖 AI 问问微信 -## [点击这里下载](https://github.com/Wxw-Gu/WechatExplorer/releases) +直接向自己的微信提问： -## 📖 使用方法 +> “去年我和老板聊过哪些关于涨薪的事情？” +> +> “技术群这周讨论了哪些问题？” +> +> “帮我找到张三发过的项目地址。” -安装、获取数据库密钥、连接微信数据及常见问题，请查看： +### 📰 AI 群聊日报 -### [👉 WechatExplorer 完整使用教程](./docs/user-guide/getting-started.md) +选择一个群聊和时间范围，自动生成： -教程包含 macOS 与 Windows 的分步截图，以及数据目录、SIP、图片解密密钥和自动获取失败的排查方法。 +- ✅ 今日热点 +- ✅ 一句话总结 +- ✅ 资源汇总 +- ✅ 问答整理 +- ✅ 活跃榜 +- ✅ 词云与关键词 -> 微信 4.0+ 在 macOS / Windows 上已支持部分能力，目前仍在持续适配。如需其他成熟方案，也可参考 [WeFlow](https://github.com/hicccc77/WeFlow) 和 [Chatlog](https://github.com/sjzar/chatlog)。 +
+ 展开查看日报的完整模块 -## 🛠️ 开发配置（可选） +- **今日讨论热点**：梳理群内主要话题，支持热度标签。 +- **一句话速览**：首屏突出今日核心结论与待跟进事项。 +- **实用信息与资源**：提取分享的链接、资源等信息。 +- **重要消息汇总**：标记并展示重要消息，带发送者头像。 +- **有趣对话或金句**：收录群内的精彩对话。 +- **问题与解答**：整理群内的问答内容。 +- **尚未解决 / 今日剧情线**：适合工作群和项目群的回顾与跟进。 +- **今日群相册 / 语音时长榜 / 临时群友称号**：让图片、语音和氛围型内容也能参与日报。 +- **群内数据可视化**：消息热度条形图、话唠榜 TOP5、活跃时间线。 +- **词云 / 关键词**：可视化展示群聊关键词。 +
-本地开发需要 Node.js（推荐 v16+）和 pnpm 7。 +支持导出 HTML 与 PNG，也支持图片理解和图片生成。 -### 环境变量 +### 📂 查看聊天 -可选配置项，可在 `.env` 文件中设置；本地开发时运行 `pnpm dev` 会在 `.env` 不存在时自动从 `.env.example` 复制一份。成品用户也可以直接在软件“设置”里填写或自动获取图片解密密钥。 +浏览微信好友和群聊的聊天记录，支持查看： -| 变量名 | 说明 | 示例 | -| ----------------------- | --------------------------- | --------------------------- | -| `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` | 过滤的消息类型 | `分享消息,图片,表情包,视频` | +- 文本 +- 图片 +- 视频 +- 语音 +- 文件 -## 🤖 AI 集成（本地 HTTP API） +同时支持头像显示、全局搜索、指定会话搜索、消息防撤回和上下文定位。 -WechatExplorer 内置了一个本地 HTTP API 服务，默认监听 `127.0.0.1:6131`（纯本地，无鉴权），让你能够从 **Claude Desktop / Claude Code / Codex / curl / 任何脚本** 读取已经解锁的微信聊天记录。 +### 📤 导出聊天 + +支持按会话和时间范围导出聊天记录为 HTML、CSV、JSON 或 Markdown，并可以打开文件所在文件夹。 + +### 🤖 Agent + +通过本地 HTTP API 和内置 Reader Skill，让 Codex、Claude Code 等 Agent 在本机服务运行并获得授权后读取、总结聊天数据。 + +## 🚀 规划与未来（Roadmap） + +WechatExplorer 仍在持续演进，未来会围绕 **AI 大模型 + 微信 + Agent** 持续完善能力。 + +下面是正在设计或计划中的部分功能（不代表发布时间）。 + +
+ 点击展开未来规划 + +### 🚧 人物镜像（Persona） + +根据长期聊天记录生成每个人的沟通画像： + +- 兴趣标签 +- 常聊话题 +- 表达风格 +- 个性化沟通参考 + +### 🚧 AI 长期记忆 + +让 AI 持续理解你的聊天历史，在不同时间跨度内建立上下文，支持长期事项追踪和连续对话。 + +### 🚧 微信卡片分享 + +将 AI 日报生成可点击的微信卡片消息，而不仅仅是图片，方便在群聊中传播与查看。 + +

+ 微信卡片分享示例 +

+ +### 🚧 退群自动监控 + +自动记录群聊成员变动： + +- 谁加入群聊 +- 谁退出群聊 +- 变动发生的时间 +- 群成员变动记录 + +

+ 退群自动监控示例 +

+ +### 💡 更多 AI 能力 + +包括会议纪要、聊天知识库、长期事项追踪、个人成长分析等更多探索。 + +WechatExplorer 希望不仅仅是一个聊天记录查看工具，更希望成为一个能够理解、整理和协助管理微信信息的 AI 工作平台。 + +如果你有好的想法，欢迎提交 Issue 或 Pull Request，一起把它做得更好。 + +
+ +## ⚙️ 快速开始 + +### 下载并安装 + +从 [GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) 下载对应系统的安装包： + +- Windows：下载 `-setup.exe` 并按安装向导完成安装。 +- macOS：下载 `.dmg`，将 WechatExplorer 拖入“应用程序”。首次打开若被系统拦截，请在“系统设置 → 隐私与安全性”中允许打开。 + +### 连接微信 + +按照软件内置的「第一次使用」引导完成连接： + +1. 确认微信数据目录。 +2. 让微信停在登录页面。 +3. 点击“开始获取”，按提示完成连接。 + +Windows 已完整支持，不需要关闭 SIP。macOS 首次自动获取数据库密钥前，需要关闭 SIP 并完成系统授权。 + +### 配置 AI + +进入「设置 → AI 模型」，添加模型服务商并填写 API Key，保存并测试成功后即可使用「问问微信」和「日报」。支持： + +- OpenAI +- DeepSeek +- Claude +- Moonshot +- OpenAI 兼容接口 + +### 下一步 + +| 你想做什么 | 从哪里开始 | +| ----------------- | ---------------------------------------------------------------- | +| 重新查看连接步骤 | 点击左下角「新手引导」 | +| 直接向微信提问 | 打开「问问微信」 | +| 生成群聊日报 | 打开「日报」 | +| 浏览聊天记录 | 打开「档案」 | +| 导出聊天记录 | 打开「导出」 | +| 让 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 -API 服务在 WechatExplorer 启动时自动启用，**不需要任何配置**。只需要： - -1. 安装并启动 WechatExplorer -2. 完成首次密钥配置（主窗口第一步），解锁 WCDB 数据库 -3. API 即在 `http://127.0.0.1:6131` 可用 +1. 安装并启动 WechatExplorer。 +2. 完成首次密钥配置，解锁 WCDB 数据库。 +3. 在 `http://127.0.0.1:6131` 使用本地 API。 ### 7×24 提供 API（菜单栏常驻模式） -默认情况下，关闭主窗口时 macOS 会让 app 继续运行，但 Windows / Linux 会退出。如果希望主窗口关闭后 API 服务仍可用，启用菜单栏模式： +默认情况下，关闭主窗口时 macOS 会让 app 继续运行，但 Windows / Linux 会退出。如果希望主窗口关闭后 API 服务仍可用，可以启用菜单栏模式： ```bash -# 任选一种方式 WXE_TRAY=1 open /Applications/WechatExplorer.app /Applications/WechatExplorer.app/Contents/MacOS/WechatExplorer --tray ``` 启用后： -- macOS dock 图标自动隐藏 -- 菜单栏出现 WechatExplorer 图标（可点击重新打开主窗口、查看 API 状态） -- 主窗口关闭后 API 服务继续运行 +- macOS Dock 图标自动隐藏。 +- 菜单栏出现 WechatExplorer 图标，可重新打开主窗口、查看 API 状态。 +- 主窗口关闭后 API 服务继续运行。 ### API 端点一览 | 端点 | 说明 | | ------------------------------------------------ | --------------------------------------- | | `GET /api/v1/health` | 健康检查 | -| `GET /api/v1/current_time` | 获取当前本地时间（用于"今天/昨天"换算） | +| `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 | +| `GET /api/v1/resolve?q=群昵称` | 把昵称、wxid 或 md5 解析成 md5 | -详细参数、返回结构、时间格式见 [`docs/skill/wechatexplorer-reader/SKILL.md`](./docs/skill/wechatexplorer-reader/SKILL.md)。 +详细参数、返回结构和时间格式见 [Reader Skill 文档](./docs/skill/wechatexplorer-reader/SKILL.md)。 ### 安装 Reader Skill，让 Agent 读取和总结群聊 -WechatExplorer 已内置 **Reader Skill**，无需手动复制仓库中的 `SKILL.md`： +WechatExplorer 已内置 Reader Skill，无需手动复制仓库中的 `SKILL.md`： 1. 启动 WechatExplorer，并确认数据库已连接、本地 API 已运行。 -2. 打开应用内的 **API** 页面。 -3. 在“快速接入”中选择 **Codex** 或 **Claude Code**。 -4. 点击复制安装指令，将指令粘贴给对应的 Agent 执行。 +2. 打开应用内的「API」页面。 +3. 在“快速接入”中选择 Codex 或 Claude Code。 +4. 点击复制安装指令，将指令粘贴给对应 Agent 执行。 5. 安装完成后，可以直接向 Agent 提问： > “今天技术交流群聊了什么？” -Reader Skill 会自动获取本机时间、定位目标群聊、读取所需聊天记录，并结合上下文生成总结。详细接口说明仍可查看 [`docs/skill/wechatexplorer-reader/SKILL.md`](./docs/skill/wechatexplorer-reader/SKILL.md)。 +Reader Skill 会自动获取本机时间、定位目标群聊、读取所需聊天记录，并结合上下文生成总结。 ### curl 调试示例（可选） @@ -149,7 +314,7 @@ Reader Skill 会自动获取本机时间、定位目标群聊、读取所需聊 # 健康检查 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)" @@ -159,11 +324,73 @@ curl -G "http://127.0.0.1:6131/api/v1/resolve" \ --data-urlencode "q=摸鱼交流群" ``` +
+ +## 🛠️ 开发配置（可选） + +
+ 展开开发配置、环境变量和构建命令 + +本地开发需要 Node.js（建议当前 LTS）和 pnpm 7+： + +```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 安装包 +``` + +
+ +## ❓ FAQ + +
+ 展开常见问题 + +### 我已经连接成功，怎么重新查看教程？ + +点击左下角「新手引导」。首次连接流程、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 @@ -173,14 +400,41 @@ curl -G "http://127.0.0.1:6131/api/v1/resolve" \ -## 🔗 参考致谢 +## 致谢 -- [WechatMessageExplorer](https://github.com/svcvit/WechatMessageExplorer) -- [WeFlow](https://github.com/hicccc77/WeFlow) -- [chatlog](https://github.com/sjzar/chatlog) +
+ 展开致谢与参考项目 -## 📱 交流与反馈 +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 交流二维码 + WechatExplorer 交流与售后群二维码

diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md index 9d85b04..9f6edca 100644 --- a/docs/user-guide/getting-started.md +++ b/docs/user-guide/getting-started.md @@ -1,121 +1,248 @@ -# WechatExplorer 使用教程 +# WechatExplorer：第一次使用与问题排查 -本文介绍如何安装 WechatExplorer、自动获取微信数据库密钥，并完成首次连接。 +这份说明解决三件事：第一次连接微信、连接成功后如何开始使用，以及遇到问题时如何自助排查。 -## 1. 使用前准备 +如果你已经进入软件，忘记了连接步骤，可以直接点击左下角「新手引导」，重新查看首次连接流程、AI 配置入口和群聊日报入口。 -### 支持的版本 +## 你现在要做什么 -| 系统 | 已测试的微信版本 | 说明 | +- [我第一次使用，想连接微信](#第一次连接微信) +- [我已经连接成功，下一步做什么](#连接成功后做什么) +- [我想重新查看引导](#重新查看新手引导) +- [我想配置 AI](#配置-ai) +- [我遇到问题](#遇到问题) +- [我想让 Agent 读取微信](#接入-api-reader-skill-或-agent) + +## 开始前确认 + +| 系统 | 已测试的微信版本 | 需要注意 | | --- | --- | --- | -| macOS | `4.1.8.100` | 支持相对稳定；自动获取密钥前需要关闭 SIP | -| Windows | `4.1.9.57` | 已初步支持；不同安装路径和数据目录可能仍需手动调整 | +| macOS | `4.1.8.100` | 自动获取数据库密钥前需要关闭 SIP 并完成授权 | +| Windows | `4.1.9.57` | 已完整支持；首次使用时请确认微信数据目录 | -- macOS 微信下载：[wechat-versions v4.1.8.100](https://github.com/zsbai/wechat-versions/releases/tag/4.1.8.100) -- Windows 微信下载：[wechat-win-archive v4.1.9.57](https://github.com/iibob/wechat-win-archive/releases#release-v4.1.9.57) -- WechatExplorer 下载：[GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) +- WechatExplorer 当前面向微信 4.0 数据结构。 +- Windows 不需要关闭 SIP。 +- macOS 首次自动获取数据库密钥需要按页面提示完成系统授权。 +- WechatExplorer 必须取得当前微信账号对应的数据库密钥才能读取聊天记录。 +- 请只处理你有权访问的微信数据。 -> [!IMPORTANT] -> WechatExplorer 必须取得本机微信数据库密钥才能读取聊天记录。请仅处理你有权访问的数据。 +下载入口：[GitHub Releases](https://github.com/Wxw-Gu/WechatExplorer/releases) -### macOS：关闭 SIP +## 第一次连接微信 -macOS 自动获取密钥前需要关闭 SIP，具体操作见 [macOS 关闭 SIP 教程](../mac-disable-sip.md)。 +### 1. 安装 WechatExplorer -关闭 SIP 会降低系统安全性。建议了解风险后再操作，并在不再需要自动获取密钥时重新开启。 +#### Windows -## 2. 安装 WechatExplorer +1. 从 Releases 下载 Windows `-setup.exe` 安装包。 +2. 双击安装包，按向导完成安装。 +3. 启动 WechatExplorer。 -### macOS +#### macOS 1. 从 Releases 下载 `.dmg` 文件。 2. 打开 DMG，将 WechatExplorer 拖入“应用程序”文件夹。 -3. 如果系统提示“无法打开，因为开发者无法验证”，请前往“系统设置 → 隐私与安全性”，点击“仍要打开”。 -4. 如果系统提示应用已损坏，在终端执行： +3. 如果系统提示“无法打开，因为开发者无法验证”，前往“系统设置 → 隐私与安全性”，点击“仍要打开”。 +4. 如果系统提示应用已损坏，可在终端执行： ```bash xattr -cr "/Applications/WechatExplorer.app" ``` -### Windows +5. 如果这是第一次在 macOS 上自动获取数据库密钥，先完成 [关闭 SIP 教程](../mac-disable-sip.md)。关闭 SIP 会降低系统安全性，完成密钥配置后建议重新开启。 -1. 从 Releases 下载 `-setup.exe` 安装包。 -2. 双击安装，并按安装向导完成操作。 +### 2. 按软件内引导连接微信 -## 3. 自动获取密钥 +首次启动会自动进入「第一次使用」页面。页面会根据当前系统显示连接方式和注意事项： -### 第一步：确认微信数据目录 +

+ 第一次使用连接页面 +

-启动 WechatExplorer 后，先检查页面中的“存储路径”是否正确。 +通常按下面三步操作即可： -![确认微信数据目录](./images/initial-setup.png) +1. **确认微信数据目录**：自动识别不准确时，在页面中修改存储路径。 +2. **让微信停在登录页面**：如果微信已经登录，先退出微信登录，不只是关闭窗口。 +3. **点击开始获取**：软件会尝试获取数据库密钥。按提示可以登录后，再回到微信完成登录。 -Windows 当前不会扫描二级目录。如果没有正确识别微信数据，请进入“设置”，手动选择微信数据所在目录。 +Windows 已完整支持，不需要关闭 SIP。macOS 首次获取密钥前，需要按页面提示完成授权并关闭 SIP。 -![Windows 自定义数据目录](./images/windows-data-path.png) +### 3. 连接成功 -### 第二步：让微信停留在登录页面 +连接成功后，软件会进入聊天档案，并显示「开始探索你的微信」引导： -如果微信已经登录，请先退出登录；然后重新打开微信，让它停留在未登录页面，暂时不要点击登录。 +

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

-![微信未登录页面](./images/wechat-login-window.png) +这里推荐先体验「AI 群聊日报」，也可以直接查看聊天、问问微信或配置 AI 模型。 -### 第三步：开始获取密钥 +## 连接成功后做什么 -返回 WechatExplorer，点击“自动获取密钥”。 +### AI 问问微信 -- **Windows**：看到“Hook 注入成功”后，返回微信完成登录。 -- **macOS**：系统会弹出授权提示，请输入当前 macOS 用户密码并完成授权，然后返回微信完成登录。 +打开「问问微信」，用自然语言向自己的微信提问，例如： -![macOS 授权页面](./images/macos-authorization.png) +- “技术群这周讨论了哪些问题？” +- “帮我找到张三发过的项目地址。” +- “去年我和老板聊过哪些关于涨薪的事情？” -> 点击“自动获取密钥”前，微信必须停留在登录页面。WechatExplorer 提示可以登录后，再回到微信完成登录。 +如果还没有配置 AI，点击「设置 → AI 模型」添加模型服务商并测试连接。 -### 第四步：完成连接 +### AI 群聊日报 -如果系统环境和微信版本符合要求，WechatExplorer 会自动填写数据库密钥并连接数据库。连接成功后即可查看、搜索和导出聊天记录，也可以配置 AI 服务生成群聊总结。 +1. 打开「日报」。 +2. 选择一个群聊和时间范围。 +3. 按需要选择日报内容和模板。 +4. 开始生成，完成后查看或导出 HTML 与 PNG。 -![密钥获取完成](./images/setup-complete.png) +日报会整理讨论摘要、关键主题、重要消息、资源、问题和待跟进事项，并保留证据来源。 -## 4. 图片解密密钥 +### 查看聊天 -微信 4.0 及以上版本的图片通常以 `.dat` 文件存储，显示图片还需要： +1. 打开「档案」。 +2. 选择好友或群聊。 +3. 浏览历史消息，也可以按关键词定位会话。 + +### 导出聊天 + +打开「导出」，选择联系人或群聊、时间范围和格式。支持 HTML、CSV、JSON 和 Markdown。 + +## 重新查看新手引导 + +连接成功后，首次弹窗关闭不会影响功能使用。需要重新查看时，点击主界面左下角的「新手引导」： + +

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

+ +新手引导会再次展示： + +- 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 的设置中导出后填写。文字聊天记录不受图片密钥影响。 -1. 使用首次连接页面的“自动获取密钥”。 -2. 在“设置 → 图片解密密钥”中自动获取或手动填写。 -3. 从 WeFlow 或 Chatlog 的设置中导出后手动填写。 +### 我已经连接成功，怎么重新查看教程？ -数据库连接成功但图片无法显示时，请优先检查这两项密钥。 +点击左下角「新手引导」。 -## 5. 常见问题 +首次连接流程、AI 配置入口、群聊日报、问问微信和完整教程都会再次展示。 -### 自动获取密钥失败 +## 接入 API、Reader Skill 或 Agent -请依次确认： +这是高级使用路径，请先完成数据库连接并熟悉「问问微信、日报、档案、导出」的基础流程。 -1. 微信版本是否与上方已测试版本一致。 -2. 点击“自动获取密钥”时，微信是否停留在未登录页面。 -3. 微信数据目录是否正确；Windows 用户尤其需要检查是否多选或少选了一层目录。 -4. macOS 是否已按教程关闭 SIP，并完成系统授权。 -5. 微信和 WechatExplorer 是否都保持运行。 +### Reader Skill -仍然失败时，可以切换到“手动输入”，粘贴从其他兼容工具中取得的数据库密钥。 +1. 打开应用的「API」页面。 +2. 确认本地 API 已运行；如果已停止，点击“启动服务”。 +3. 在“快速接入”中选择 Codex 或 Claude Code。 +4. 复制安装指令，粘贴给对应 Agent 执行。 +5. 安装完成后，让 Agent 读取和总结本地聊天。 -### Windows 使用时卡顿 +本地 API 默认地址为 `http://127.0.0.1:6131`，默认仅监听本机且无鉴权。详细端点和参数见 [Reader Skill 文档](../skill/wechatexplorer-reader/SKILL.md)。 -Windows 支持仍处于初步阶段，不同微信版本、安装路径、数据目录和权限环境可能存在差异。建议优先使用上方已测试的微信版本。 +### Agent Hub -### 数据会上传吗？ +应用内的「Agent」页面用于管理 WechatExplorer 的 Agent 连接与运行状态，属于高级功能。 -聊天数据库在本机读取和处理。只有使用 AI 总结功能时，相关聊天内容才会按你配置的模型服务发送；是否启用以及使用哪个服务由你决定。 +## 数据与隐私 -## 6. 下一步 +- WechatExplorer 只读取你有权访问的本机微信数据。 +- 不使用 AI 时，应用不会因为读取聊天记录而自动上传聊天内容。 +- 使用 AI 问问微信、日报或图片理解时，相关内容会发送到你配置的模型服务。 +- 本地 API 默认监听 `127.0.0.1`，且无鉴权。不要将它暴露在不可信的局域网环境中。 -- 在应用“设置”中填写兼容 OpenAI API 的模型服务和 API Key，使用 AI 总结功能。 -- 在应用的 **API** 页面安装 Reader Skill，让 Codex 或 Claude Code 读取和总结本地群聊。 -- 本地 API 的端点和调试方法见项目 [README](../../README.md#ai-集成本地-http-api)。 +## 仍然无法解决？ + +请先完成上面的自助排查，再进入交流/售后群。提问时一次性提供： + +1. 操作系统和版本。 +2. 微信版本。 +3. WechatExplorer 版本。 +4. 当前处于哪一步，以及完整错误信息。 +5. 必要截图；请遮挡账号、数据库密钥、API Key 和其他敏感信息。 + +交流二维码位于项目 [README](../../README.md) 文末。 diff --git a/public/first-use-welcome.png b/public/first-use-welcome.png new file mode 100644 index 0000000..738031b Binary files /dev/null and b/public/first-use-welcome.png differ diff --git a/public/setup-page.png b/public/setup-page.png new file mode 100644 index 0000000..741f844 Binary files /dev/null and b/public/setup-page.png differ diff --git a/public/二维码.jpg b/public/二维码.jpg index 7d6527c..04ab618 100644 Binary files a/public/二维码.jpg and b/public/二维码.jpg differ diff --git a/public/微信卡片分享.png b/public/微信卡片分享.png new file mode 100644 index 0000000..7724d5c Binary files /dev/null and b/public/微信卡片分享.png differ diff --git a/public/退群监控.png b/public/退群监控.png new file mode 100644 index 0000000..d56b478 Binary files /dev/null and b/public/退群监控.png differ diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx index 0444b8c..2aa7772 100644 --- a/src/renderer/src/App.tsx +++ b/src/renderer/src/App.tsx @@ -20,6 +20,7 @@ import { AiModelConfig, useGroupReportGeneration } from './hooks/useGroupReportG import { SummaryDateRange, SummaryMessageType } from './utils/group-report' import { Contact, Message } from '../../shared/types' import { DatabaseConnectionMode, DatabaseConnectionPage } from './components/DatabaseConnectionPage' +import { FirstUseWelcome } from './components/FirstUseWelcome' import { ExportWorkspace } from './components/export/ExportWorkspace' import { AISearchWorkspace } from './components/search/AISearchWorkspace' import type { ExportJobProgress, ExportRequest, ExportTaskRecord } from '../../shared/export' @@ -39,7 +40,8 @@ interface SelfInfo { accountRoot: string } -const MAC_KEY_FAQ_URL = 'https://github.com/hicccc77/WeFlow/blob/main/docs/MAC-KEY-FAQ.md' +const MAC_KEY_FAQ_URL = 'https://github.com/Wxw-Gu/WechatExplorer/blob/main/docs/mac-disable-sip.md' +const FIRST_USE_WELCOME_SEEN_KEY = 'wxe_first_use_welcome_seen' const MESSAGE_MONITOR_DEBOUNCE_MS = 8000 const INITIAL_MESSAGE_COUNT = 20 const MESSAGE_PAGE_SIZE = 100 @@ -256,6 +258,7 @@ function App(): React.ReactElement { const [bootState, setBootState] = useState<'loading' | 'connecting' | 'login'>('loading') const [autoConnectSource, setAutoConnectSource] = useState<'env' | 'saved' | null>(null) const [startupProgress, setStartupProgress] = useState(null) + const [showFirstUseWelcome, setShowFirstUseWelcome] = useState(false) const [appearanceSettings, setAppearanceSettings] = React.useState<{ theme: 'system' | 'light' | 'dark' compactMode: boolean @@ -728,6 +731,7 @@ function App(): React.ReactElement { }) setIsDatabaseConnected(true) setBootState('login') + maybeShowFirstUseWelcome() window.setTimeout(() => { setStartupProgress(null) }, 500) @@ -1222,6 +1226,45 @@ function App(): React.ReactElement { setActivePage('settings') } + const dismissFirstUseWelcome = (): void => { + try { + localStorage.setItem(FIRST_USE_WELCOME_SEEN_KEY, '1') + } catch { + // The welcome prompt is optional and should not interrupt normal use. + } + setShowFirstUseWelcome(false) + } + + const maybeShowFirstUseWelcome = (): void => { + try { + if (localStorage.getItem(FIRST_USE_WELCOME_SEEN_KEY) === '1') return + } catch { + // If localStorage is unavailable, still show the one-time prompt for this session. + } + setShowFirstUseWelcome(true) + } + + const openFirstUseSearch = (): void => { + dismissFirstUseWelcome() + setActivePage('search') + } + + const openFirstUseReport = (): void => { + dismissFirstUseWelcome() + setReportWorkspaceView('configure') + setSelectedReportId(null) + setActivePage('report') + } + + const openFirstUseAISettings = (): void => { + dismissFirstUseWelcome() + openModelSettings() + } + + const openFirstUseGuide = (): void => { + setShowFirstUseWelcome(true) + } + const openReport = (reportId: string): void => { setSelectedReportId(reportId) setReportWorkspaceView('result') @@ -1651,10 +1694,19 @@ function App(): React.ReactElement { dbReady={isDatabaseConnected} onPageChange={handlePageChange} onOpenSettings={openSettings} + onOpenGuide={openFirstUseGuide} appearanceTheme={appearanceSettings.theme} compactMode={appearanceSettings.compactMode} > {reportNotice &&
{reportNotice}
} + {showFirstUseWelcome && ( + + )} {renderCurrentWorkspace()} ) diff --git a/src/renderer/src/components/DatabaseConnectionPage.tsx b/src/renderer/src/components/DatabaseConnectionPage.tsx index 032e75c..f94699c 100644 --- a/src/renderer/src/components/DatabaseConnectionPage.tsx +++ b/src/renderer/src/components/DatabaseConnectionPage.tsx @@ -1,5 +1,8 @@ import React from 'react' +const GUIDE_URL = + 'https://github.com/Wxw-Gu/WechatExplorer/blob/main/docs/user-guide/getting-started.md' + export type DatabaseConnectionMode = 'automatic' | 'manual' export type DatabaseConnectionStatusKind = 'normal' | 'success' | 'error' @@ -116,9 +119,9 @@ export function DatabaseConnectionPage({

WechatExplorer

-

你的本地微信聊天档案

+

让 AI 读懂你的微信

- 连接本机微信数据库，开始检索、整理和分析聊天记录。 + 连接成功后，你可以搜索聊天记录、生成群聊日报，并按需使用 AI 分析。

@@ -131,7 +134,7 @@ export function DatabaseConnectionPage({
- 不会上传 + AI 按需启用
@@ -140,6 +143,42 @@ export function DatabaseConnectionPage({
+
+

第一次使用

+

开始连接微信

+

跟着下面 3 步操作，通常几分钟即可完成连接。

+
    +
  1. + 1 +
    + 确认微信数据目录 + 没有自动找到时，可在设置中手动选择 +
    +
    2. +
  2. + 2 +
    + 让微信停在登录页面 + 不要在获取密钥前完成登录 +
    +
    3. +
  3. + 3 +
    + 点击自动获取密钥 + 提示可以登录后，再回到微信完成登录 +
    +
    4. +
+ + 查看 5 分钟上手教程 → + +
@@ -219,20 +258,31 @@ export function DatabaseConnectionPage({ onClick={onAutoGetKey} disabled={isFetching} > - {isFetching - ? '正在获取密钥…' - : statusKind === 'error' - ? '重新检测' - : '自动获取密钥'} + {isFetching ? '正在获取密钥…' : statusKind === 'error' ? '重新检测' : '开始获取'} - {showMacKeyFaq && ( +

+ {isMac ? ( + <> + macOS 首次获取密钥需要关闭 SIP。{' '} + + 查看说明 + + + ) : ( + 'Windows 已完整支持，不需要关闭 SIP。' + )} +

+ {showMacKeyFaq && isMac && ( - 查看详情 · 连接帮助 + 获取失败？查看连接排查 )}
) : (
+

+ 仅适用于已经通过其他方式获得当前微信账号数据库密钥的高级用户。第一次使用请返回“开始连接”。 +

diff --git a/src/renderer/src/components/FirstUseWelcome.tsx b/src/renderer/src/components/FirstUseWelcome.tsx new file mode 100644 index 0000000..f55a5f8 --- /dev/null +++ b/src/renderer/src/components/FirstUseWelcome.tsx @@ -0,0 +1,78 @@ +import React from 'react' + +interface FirstUseWelcomeProps { + onDismiss: () => void + onOpenSearch: () => void + onOpenReport: () => void + onOpenAISettings: () => void +} + +const GUIDE_URL = + 'https://github.com/Wxw-Gu/WechatExplorer/blob/main/docs/user-guide/getting-started.md' + +export function FirstUseWelcome({ + onDismiss, + onOpenSearch, + onOpenReport, + onOpenAISettings +}: FirstUseWelcomeProps): React.ReactElement { + return ( +
+
+ + +

微信已连接

+

开始探索你的微信

+

+ 最关键的一步已经完成。现在，让 AI 帮你看看最近的聊天都发生了什么。 +

+ + + +
+ + +
+ +
+ 还没有配置 AI？ + + + 查看完整使用教程 + +
+
+
+ ) +} diff --git a/src/renderer/src/components/layout/AppShell.tsx b/src/renderer/src/components/layout/AppShell.tsx index 8261722..46fddc0 100644 --- a/src/renderer/src/components/layout/AppShell.tsx +++ b/src/renderer/src/components/layout/AppShell.tsx @@ -17,6 +17,7 @@ interface AppShellProps { dbReady: boolean onPageChange: (page: AppPage) => void onOpenSettings: () => void + onOpenGuide: () => void appearanceTheme?: 'system' | 'light' | 'dark' compactMode?: boolean children: React.ReactNode @@ -36,6 +37,7 @@ export function AppShell({ dbReady, onPageChange, onOpenSettings, + onOpenGuide, appearanceTheme = 'system', compactMode = false, children @@ -47,6 +49,19 @@ export function AppShell({