From 46c9b98d7509167f02ef2709c979911416b9d152 Mon Sep 17 00:00:00 2001 From: Wxw-Gu Date: Thu, 13 Aug 2026 15:05:36 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0readme?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 279 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 206 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 719db03..d0cfc42 100644 --- a/README.md +++ b/README.md @@ -30,36 +30,91 @@

- TraceMemo 主界面 + TraceMemo 微信机器人

+--- + ## TraceMemo（迹忆）是什么 -TraceMemo（迹忆）是一款本地优先、可追溯的 AI 微信知识与分析工作台。 +TraceMemo（迹忆）是一款**本地优先、可追溯的 AI 微信知识与分析工作台**。 -TraceMemo（迹忆）原名 WechatExplorer，是一次从“微信聊天记录探索工具”向“可追溯的本地 AI 知识工作台”演进后的正式品牌升级。 - -## 为什么叫 TraceMemo（迹忆） - -`Trace` 代表聊天记录留下的痕迹、可以追溯的信息来源、AI 搜索过程，以及从结果回到原始聊天上下文并核对证据的能力。 - -`Memo` 代表记忆、知识沉淀和长期保存：让聊天中产生的信息逐渐形成个人知识。 - -“迹忆”可以理解为“留下痕迹的记忆”。TraceMemo 不是单纯查看微信聊天记录的工具，而是希望让聊天中产生的信息留下痕迹，并能够被再次找到、理解、验证和沉淀。 - -> **品牌说明** -> -> TraceMemo（迹忆）原名 WechatExplorer。WechatExplorer 最初是一个用于查看和探索微信聊天记录的工具。随着本地搜索、AI 问答、来源追溯、知识库、日报、语音转写和 Agent 能力逐渐形成，项目已经从单纯的聊天记录查看器发展为本地 AI 知识与分析工作台，因此在 v2.2.0 正式更名为 TraceMemo（迹忆）。 +TraceMemo 原名 **WechatExplorer**，是一次从“微信聊天记录探索工具”向“可追溯的本地 AI 知识工作台”演进后的正式品牌升级。 它可以帮你浏览、搜索和整理微信历史，也可以让 AI 帮你找回聊过的内容，并回到原始消息核对答案。 你可以直接浏览聊天，也可以用自然语言提问： > “上个月我们讨论过哪些发布问题？” +> > “张三之前发过的项目地址在哪里？” +> > “技术交流群今天有哪些结论和待办？” -它和普通聊天记录查看器最大的不同，是 AI 不只是告诉你答案，还会告诉你答案来自哪里。你可以看到答案参考了哪些内容、来自哪个会话和时间，再回到原始消息确认它有没有理解错。 +它和普通聊天记录查看器最大的不同，是 AI 不只是告诉你答案，还会告诉你答案来自哪里。 + +你可以看到答案参考了哪些内容、来自哪个会话和时间，再回到原始消息确认它有没有理解错。 + +TraceMemo 不提供任何微信聊天数据，也不鼓励收集、上传、出售、共享或未经授权处理他人的聊天记录。使用 TraceMemo 时，请确保你对所处理的数据具有合法的访问和使用权限，并自行承担相应的数据安全与合规责任。 + +--- + +## 为什么叫 TraceMemo（迹忆） + +
+`Trace` 代表聊天记录留下的痕迹、可以追溯的信息来源、AI 搜索过程，以及从结果回到原始聊天上下文并核对证据的能力。 + +`Memo` 代表记忆、知识沉淀和长期保存：让聊天中产生的信息逐渐形成个人知识。 + +“迹忆”可以理解为“留下痕迹的记忆”。 + +TraceMemo 不是单纯查看微信聊天记录的工具，而是希望让聊天中产生的信息留下痕迹，并能够被再次找到、理解、验证和沉淀。 + +> **品牌说明** +> +> TraceMemo（迹忆）原名 WechatExplorer。WechatExplorer 最初是一个用于查看和探索微信聊天记录的工具。随着本地搜索、AI 问答、来源追溯、知识库、日报、语音转写和 Agent 能力逐渐形成，项目已经从单纯的聊天记录查看器发展为本地 AI 知识与分析工作台，因此在 v2.2.0 正式更名为 TraceMemo（迹忆）。 + +
+ +--- + +## 项目缘起 + +
+ +TraceMemo 最早叫 **WechatExplorer**。 + +**2025 年 12 月**，我做出了第一个版本。当时功能很简单：解析微信 3.0 的聊天记录，再用 AI 生成群聊日报。最初只是给自己用，想把散落在微信里的信息重新找出来，也方便看看群里每天聊了什么。 + +第一个版本完成后，项目搁置了一段时间。后来重新捡起来，我还是想继续做群聊日报，但微信已经更新到 4.x，原来的微信 3.0 数据解析方案不再适用。 + +为了支持微信 4.x，我开始重新研究数据访问。这部分工作得到了 **WeFlow** 很大的帮助。TraceMemo 目前的微信 4.x 数据连接能力，参考并使用了 **WeFlow 历史版本中的相关实现和思路**，包括数据库密钥获取、图片解密等底层能力。 + +> **没有 WeFlow，就没有今天的 TraceMemo。** + +WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继续做后面的事情：让聊天记录可以被搜索、理解和总结，也让 AI 给出的答案能够回到原始消息核对。 + +在此基础上，项目陆续加入了： + +- 本地知识库 +- 消息来源追溯 +- 群聊日报 +- 语音消息也参与知识库等问答 +- 微信机器人 +- Local HTTP API +- Reader Skill +- Agent 接入 +- 多种聊天记录导出能力 + +群聊日报后来被一些人看到，项目也开始有了 Star、Fork、使用反馈和功能建议。说实话，我一开始没想到，这个原本只给自己用的小工具，会得到这么多人的关注。 + +这些关注和反馈让我决定认真把项目继续做下去。WechatExplorer 就这样一步一步变成了今天的 **TraceMemo（迹忆）**。 + +感谢 WeFlow，也感谢每一位使用、关注和反馈过 TraceMemo 的人。 + +
+ +--- ## 💬 交流与反馈 @@ -82,22 +137,37 @@ TraceMemo（迹忆）原名 WechatExplorer，是一次从“微信聊天记录 | 直接在微信里向 TraceMemo 提问 | [微信机器人](./docs/agent/agent-hub.md) | 扫码连接机器人；总结类任务需要 AI | | 让 Codex 等外部 Agent 查询微信历史 | [外部 Agent](./docs/agent/overview.md) | 安装 Reader Skill 并配置本机 Token | +--- + ## 最核心的三个能力 -### 浏览和搜索微信历史 +### 生成群聊日报 -- 浏览联系人、群聊、折叠群聊和公众号消息。 -- 查看文本、图片、视频、语音、文件、链接、引用、小程序等内容。 -- 搜索会话或当前聊天中的关键词。 -- 从 AI 结果跳回对应聊天位置。 +选择群聊和时间范围后，可以让 AI 把聊天整理成报告，并保存为 HTML 与 PNG 长图。 -详细说明：[聊天档案与普通搜索](./docs/user-guide/chat-archive.md) +报告包含： + +- 热点 +- 重要消息 +- 资源 +- 问答 +- 待办 +- 未解决事项 +- 活跃统计 +- 图片精选 + +具体内容取决于消息、媒体是否可读以及模型能力。 +详细说明：[生成群聊日报](./docs/user-guide/report.md) + + ### AI 帮你找回聊过的内容 打开“问问微信”，选择搜索范围和时间，然后像提问一样描述你想找的内容。 -TraceMemo 会先在本机查找候选消息，再把整理后的少量来源交给你配置的 AI 模型生成回答。你可以查看答案参考了哪些聊天、来自哪个人和时间，并从来源标记跳回原始消息核对；“查看检索详情”还会展示本次查找经历了哪些阶段。 +TraceMemo 会先在本机查找候选消息，再把整理后的少量来源交给你配置的 AI 模型生成回答。 + +你可以查看答案参考了哪些聊天、来自哪个人和时间，并从来源标记跳回原始消息核对；“查看检索详情”还会展示本次查找经历了哪些阶段。

问问微信与聊天来源 @@ -107,71 +177,94 @@ TraceMemo 会先在本机查找候选消息，再把整理后的少量来源交 ### 直接在微信里问你的历史聊天 -打开应用中的“Agent”入口（页面标题为“Agent Hub”，对应微信机器人功能），扫码连接一个微信机器人账号。例如，你可以直接给机器人发送“最近 5 个会话”“张三最近和我聊了什么”，或者让它生成指定群聊的总结图片。TraceMemo 会在本机读取已连接的聊天数据并把结果回复到微信。 +打开应用中的“Agent”入口（页面标题为“Agent Hub”，对应微信机器人功能），扫码连接一个微信机器人账号。 -这个入口不要求另外安装 Codex、Claude Code 等外部 Agent。当前主要处理文字消息，不支持群发、定时任务或通用自主操作微信；总结和自然语言理解需要先配置 AI 服务。 +例如，你可以直接给机器人发送： + +- “最近 5 个会话” +- “张三最近和我聊了什么” +- “总结今天的技术交流群” + +TraceMemo 会在本机读取已连接的聊天数据并把结果回复到微信。 + +这个入口不要求另外安装 Codex、Claude Code 等外部 Agent。 + +当前主要处理文字消息，不支持群发、定时任务或通用自主操作微信；总结和自然语言理解需要先配置 AI 服务。 详细步骤和能力边界见[在微信里向 TraceMemo 提问](./docs/agent/agent-hub.md)。 +--- + ## 其他能力 ### 本地知识库 -“问问微信”里的“本地知识库”会为当前微信账号建立一份留在本机的可检索资料。它把聊天文本、附件信息和已有语音转写整理起来，让跨会话、跨时间查找更稳定。 +

+“问问微信”里的“本地知识库”会为当前微信账号建立一份留在本机的可检索资料。 + +它把聊天文本、附件信息和已有语音转写整理起来，让跨会话、跨时间查找更稳定。 它只在用户主动建立后工作，可以同步、查看占用并清理；清理不会删除微信原始数据库。 详细说明：[本地知识库](./docs/user-guide/knowledge.md) -### 生成群聊日报 - -
-查看群聊日报示例、内容和导出方式 - -选择群聊和时间范围后，可以让 AI 把聊天整理成报告，并保存为 HTML 与 PNG 长图。报告可能包含热点、重要消息、资源、问答、待办、未解决事项、活跃统计和图片精选；具体内容取决于消息、媒体是否可读以及模型能力。 - -

- 群聊日报示例 -

- -详细说明：[生成群聊日报](./docs/user-guide/report.md) -
### 实验性：生成微信分享卡片 -TraceMemo 可以把群聊日报长图上传到你自己部署的 Cloudflare Worker 和 R2，并生成可在微信中分享的临时网页、二维码及卡片信息。该功能需要自备 Cloudflare 账号、域名和微信测试号，目前不属于开箱即用的稳定功能。 +
+TraceMemo 可以把群聊日报长图上传到你自己部署的 Cloudflare Worker 和 R2，并生成可在微信中分享的临时网页、二维码及卡片信息。 + +该功能需要自备 Cloudflare 账号、域名和微信测试号，目前不属于开箱即用的稳定功能。

微信卡片分享效果示例

-详细说明：[实验性微信分享卡片](./docs/deployment/experimental-wechat-share-card.md)。不熟悉命令行的用户，可以把 [自动部署 Skill](./docs/skill/setup-wechat-share-card/SKILL.md) 直接交给 Codex 或 Claude Code。 +详细说明：[实验性微信分享卡片](./docs/deployment/experimental-wechat-share-card.md)。 + +不熟悉命令行的用户，可以把[自动部署 Skill](./docs/skill/setup-wechat-share-card/SKILL.md)直接交给 Codex 或 Claude Code。 + +
### 转写微信语音 -TraceMemo 支持在本机转写单条或批量微信语音，结果可以参与本地知识库检索和 HTML 导出。转写本身不要求把语音文件发送给在线 AI；随后用于 AI 问答或日报时，文字会按对应功能的规则处理。 +
+TraceMemo 支持在本机转写单条或批量微信语音，结果可以参与本地知识库检索和 HTML 导出。 + +转写本身不要求把语音文件发送给在线 AI；随后用于 AI 问答或日报时，文字会按对应功能的规则处理。 详细说明：[语音转文字](./docs/user-guide/voice.md) -### 防撤回 - -可选开启后，TraceMemo 会尽量保留开启期间捕获到的撤回消息。该能力受微信版本和应用运行状态影响，不保证找回所有内容，也不能恢复开启前已经撤回的消息。 - -详细说明：[防撤回](./docs/user-guide/recall-protection.md) +
### 导出长期可用的聊天档案 -支持 HTML、CSV、JSON 和 Markdown。HTML 可携带媒体、头像和可选语音转写，支持最多五个会话合并，也可以压缩为 ZIP；增量合并、媒体资源和 ZIP 只适用于 HTML，其他格式主要保留文本内容。 +
+支持 HTML、CSV、JSON 和 Markdown。 + +HTML 可携带媒体、头像和可选语音转写，支持最多五个会话合并，也可以压缩为 ZIP；增量合并、媒体资源和 ZIP 只适用于 HTML，其他格式主要保留文本内容。 详细说明：[导出聊天](./docs/user-guide/export.md) +
+ ### 在外部 Agent 中查询微信历史 -通过 Reader Skill 和本机 Local HTTP API，Codex、Claude Code、OpenClaw 等外部 Agent 可以按需查询联系人、群聊和聊天记录。这和微信机器人是两条不同路径：微信机器人收到消息后在微信中回复；外部 Agent 则主动查询历史。 +
+通过 Reader Skill 和本机 Local HTTP API，Codex、Claude Code、OpenClaw 等外部 Agent 可以按需查询联系人、群聊和聊天记录。 + +这和微信机器人是两条不同路径： + +- **微信机器人**：收到消息后在微信中回复。 +- **外部 Agent**：主动查询历史。 安装和技术说明请看[Agent 接入概览](./docs/agent/overview.md)与[Local HTTP API](./docs/agent/api.md)。 +
+ +--- + ## 它如何工作 ```mermaid @@ -199,6 +292,8 @@ flowchart LR 完整边界见：[数据、隐私与安全](./docs/user-guide/privacy.md) +--- + ## 支持平台与安装包 | 平台 | 处理器架构 | Releases 安装包 | @@ -206,7 +301,11 @@ flowchart LR | Windows | x64 | `-setup.exe` | | macOS | Apple Silicon（M 系列、arm64） | `.dmg` | -当前版本不支持 Intel 芯片的 Mac。当前代码面向微信 4.x 数据结构。实际连接结果仍会受到微信客户端版本、账号数据状态和系统权限影响；macOS 首次连接可能需要按页面提示完成额外授权。 +当前版本不支持 Intel 芯片的 Mac。 + +当前代码面向微信 4.x 数据结构。实际连接结果仍会受到微信客户端版本、账号数据状态和系统权限影响；macOS 首次连接可能需要按页面提示完成额外授权。 + +--- ## 快速开始 @@ -218,22 +317,32 @@ flowchart LR 6. 需要 AI 问答或日报时，在“设置 → AI 模型”添加并测试 AI 服务，再打开“问问微信”或“日报”。 7. 想直接在微信里提问时，打开“Agent”扫码连接微信机器人；想让 Codex 等外部 Agent 查询时，再进入“API”。 -Windows 安装后无法启动时，请先安装 [Microsoft Visual C++ x64 运行库](https://aka.ms/vc14/vc_redist.x64.exe)。当前完整测试过的微信客户端为 Windows `4.1.9.57` 和 macOS `4.1.8.100`；下载地址与连接要求见[第一次使用](./docs/user-guide/getting-started.md)。 +Windows 安装后无法启动时，请先安装 [Microsoft Visual C++ x64 运行库](https://aka.ms/vc14/vc_redist.x64.exe)。 -从 WechatExplorer v2.1.9 升级时，TraceMemo v2.2.0 会在首次启动检测旧设置、Knowledge、Token、AI Provider 和 Agent 数据，并在用户确认后复制到新的 TraceMemo 数据目录。迁移不会覆盖已有 TraceMemo 数据，也不会删除旧目录；详情见 [v2.2.0 正式品牌身份与安全升级迁移](./docs/agent/release-notes-v2.2.0.md)。 +当前完整测试过的微信客户端为 Windows `4.1.9.57` 和 macOS `4.1.8.100`；下载地址与连接要求见[第一次使用](./docs/user-guide/getting-started.md)。 + +从 WechatExplorer v2.1.9 升级时，TraceMemo v2.2.0 会在首次启动检测旧设置、Knowledge、Token、AI Provider 和 Agent 数据，并在用户确认后复制到新的 TraceMemo 数据目录。 + +迁移不会覆盖已有 TraceMemo 数据，也不会删除旧目录；详情见 [v2.2.0 正式品牌身份与安全升级迁移](./docs/agent/release-notes-v2.2.0.md)。 如果 macOS 页面提示处理 SIP，请先阅读对应说明。具体步骤和限制见[第一次使用](./docs/user-guide/getting-started.md)。 完整步骤：[第一次使用 TraceMemo](./docs/user-guide/getting-started.md) +--- + ## 配置 AI -需要 AI 问答、群聊日报或图片理解时，在“设置 → AI 模型”添加并测试一个服务。应用支持云端服务、Ollama 等本地服务和自定义接口；具体服务商的配置、计费和数据规则由服务商决定。 +需要 AI 问答、群聊日报或图片理解时，在“设置 → AI 模型”添加并测试一个服务。 + +应用支持云端服务、Ollama 等本地服务和自定义接口；具体服务商的配置、计费和数据规则由服务商决定。 使用本地服务可以减少数据离开电脑的路径，但本地服务的日志和配置仍由你自己负责。 开发者和 Agent 用户可以从[Agent 接入概览](./docs/agent/overview.md)开始，再按需要查看[Local HTTP API](./docs/agent/api.md)与[API 安全](./docs/agent/api-security.md)。 +--- + ## 文档 - [文档首页](./docs/README.md) @@ -253,6 +362,8 @@ Windows 安装后无法启动时，请先安装 [Microsoft Visual C++ x64 运行 - [Local HTTP API](./docs/agent/api.md) - [开发与测试](./docs/development/overview.md) +--- + ## 本地开发 需要 Node.js、pnpm 7+、对应平台的 Electron/native 构建环境，以及 Go（用于微信连接器）。 @@ -274,40 +385,62 @@ pnpm test:e2e:build 完整说明：[开发、测试与构建](./docs/development/overview.md) +--- + ## 支持与反馈 -遇到问题时，先查看[常见问题与排查](./docs/user-guide/troubleshooting.md)。提交 Issue 时请提供操作系统、微信版本、TraceMemo 版本、复现步骤和已遮挡敏感信息的截图。 +遇到问题时，先查看[常见问题与排查](./docs/user-guide/troubleshooting.md)。 -请仅处理你有权访问的数据，并遵守适用的法律法规、组织政策和微信使用规则。数据库读取、解密、自动化和机器人能力都可能受平台版本与账号环境影响。 +提交 Issue 时请提供： + +- 操作系统 +- 微信版本 +- TraceMemo 版本 +- 复现步骤 +- 已遮挡敏感信息的截图 + +请仅处理你有权访问的数据，并遵守适用的法律法规、组织政策和微信使用规则。 + +数据库读取、解密、自动化和机器人能力都可能受平台版本与账号环境影响。 + +--- ## 许可说明 -仓库中的第三方组件、模型和连接器遵循各自的许可证。当前仓库根目录未提供独立的项目 `LICENSE` 文件；贡献、复制或再分发前，请先向维护者确认 TraceMemo 本身的许可范围。 +TraceMemo 当前暂未提供独立的项目 `LICENSE` 文件。 + +TraceMemo 允许个人使用、学习、修改、二次开发和 Fork，也欢迎基于项目进行非商业用途的再开发和分享。 + +**但未经项目维护者书面许可，禁止将 TraceMemo 本身或基于 TraceMemo 的衍生版本用于商业用途，包括但不限于商业软件、付费服务、商业产品、SaaS 服务或其他直接或间接的商业活动。** + +仓库中的第三方组件以及参考项目均遵循各自适用的许可证和使用条款。TraceMemo 对第三方项目的参考、使用或集成，并不意味着这些第三方项目的代码或许可证发生变化。涉及第三方代码的部分，请以对应项目的许可证和授权范围为准。 + +--- ## 致谢 - 展开致谢与参考项目 +TraceMemo 的诞生离不开开源社区中许多优秀项目的工作。 -TraceMemo 在开发过程中参考了多个优秀的开源项目，感谢这些项目作者的工作与分享。 +### 特别感谢 WeFlow -特别感谢： +TraceMemo 在支持微信 4.x 时，参考并使用了 **[WeFlow](https://github.com/hicccc77/WeFlow)** 历史版本中的相关实现和思路，包括数据库密钥获取、图片解密等底层能力。 + +特别感谢作者 **hicccc77** 的理解和包容。项目与 WeFlow 的具体关系见[项目缘起](#项目缘起)。 + +### 其他参考项目 - **[WechatMessageExplorer](https://github.com/svcvit/WechatMessageExplorer)** - - 提供了微信数据库解析相关思路。 -- **[WeFlow](https://github.com/hicccc77/WeFlow)** - - 参考了数据库密钥获取、图片解密等实现思路。 + - 提供了数据库解析相关思路。 + - **[chatlog](https://github.com/sjzar/chatlog)** - - 提供了聊天记录导出与数据处理方面的参考。 + - 提供了数据处理方面的参考。 -在此基础上，TraceMemo 进行了重新设计与实现，包括： +感谢所有开源作者，也感谢所有帮助 TraceMemo 发现问题、提出建议和持续使用它的人。 -- AI 问问微信 -- AI 群聊日报 -- 本地 HTTP API -- Reader Skill -- Agent Hub -- 新手引导 -- Electron + React 全新界面 -- 本地优先 AI 工作流 +--- -感谢所有开源作者。 +

+ TraceMemo（迹忆） +
+ 把微信聊过的事，找回来、问清楚、留下来。 +