open-source/WechatExplorer
1
0
Fork 0
mirror of https://wget.la/https://github.com/Wxw-Gu/WechatExplorer synced 2026-10-03 18:33:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 整理文档

Browse Source
This commit is contained in:
Wxw-Gu
2026-09-04 17:52:49 +08:00
parent 454f449c41
commit f28480ffbe
6 changed files with 174 additions and 376 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+59 -333
View File
@@ -4,12 +4,9 @@
<img src="./build/icon.png" width="120" alt="TraceMemo Logo" />
</p>
<h2 align="center">把微信聊过的事，找回来、问清楚、留下来</h2>
<h2 align="center">把微信里的信息，记住、理解、监控，并在需要时行动</h2>
<p align="center">
本地优先的微信聊天记录工作台：查看、搜索、提问、总结和导出<br />
查看聊天 · 找回信息 · AI 问答 · 微信群聊总结 · 语音转写 · 导出 · 微信机器人 · Agent 接入
</p>
<p align="center">本地优先的微信数据、AI 分析与自动化工作台</p>
<p align="center">
<img src="https://img.shields.io/github/stars/Wxw-Gu/TraceMemo?style=for-the-badge" alt="GitHub stars" />
@@ -23,6 +20,8 @@
<a href="./docs/user-guide/getting-started.md"><b>第一次使用</b></a>
·
<a href="./docs/README.md"><b>完整文档</b></a>
·
<a href="./docs/concepts/how-it-works.md"><b>TraceMemo 如何工作</b></a>
</p>
<p align="center">
@@ -34,49 +33,22 @@
</p>
---
## TraceMemo 是什么
## TraceMemo（迹忆）是什么
TraceMemo（迹忆）原名 **WechatExplorer** 是一款本地优先的微信数据、AI 分析与自动化工作台，把聊天变成可浏览、可搜索、可理解、可追溯的信息。
TraceMemo（迹忆）是一款**本地优先、可追溯的 AI 微信知识与分析工作台**。
先用档案找原话，再按需要使用 AI Search、日报、监控或 Agent。普通浏览、搜索和导出不需要 AI。
TraceMemo 原名 **WechatExplorer**，是一次从“微信聊天记录探索工具”向“可追溯的本地 AI 知识工作台”演进后的正式品牌升级。
## 核心能力
它可以帮你浏览、搜索和整理微信历史，也可以让 AI 帮你找回聊过的内容，并回到原始消息核对答案。
你可以直接浏览聊天，也可以用自然语言提问：
> “上个月我们讨论过哪些发布问题？”
>
> “张三之前发过的项目地址在哪里？”
>
> “技术交流群今天有哪些结论和待办？”
它和普通聊天记录查看器最大的不同，是 AI 不只是告诉你答案，还会告诉你答案来自哪里。
你可以看到答案参考了哪些内容、来自哪个会话和时间，再回到原始消息确认它有没有理解错。
TraceMemo 不提供任何微信聊天数据，也不鼓励收集、上传、出售、共享或未经授权处理他人的聊天记录。使用 TraceMemo 时，请确保你对所处理的数据具有合法的访问和使用权限，并自行承担相应的数据安全与合规责任。
---
## 为什么叫 TraceMemo（迹忆）
<details>
`Trace` 代表聊天记录留下的痕迹、可以追溯的信息来源、AI 搜索过程，以及从结果回到原始聊天上下文并核对证据的能力。
`Memo` 代表记忆、知识沉淀和长期保存：让聊天中产生的信息逐渐形成个人知识。
“迹忆”可以理解为“留下痕迹的记忆”。
TraceMemo 不是单纯查看微信聊天记录的工具，而是希望让聊天中产生的信息留下痕迹，并能够被再次找到、理解、验证和沉淀。
> **品牌说明**
>
> TraceMemo（迹忆）原名 WechatExplorer。WechatExplorer 最初是一个用于查看和探索微信聊天记录的工具。随着本地搜索、AI 问答、来源追溯、知识库、日报、语音转写和 Agent 能力逐渐形成，项目已经从单纯的聊天记录查看器发展为本地 AI 知识与分析工作台，因此在 v2.2.0 正式更名为 TraceMemo（迹忆）。
</details>
---
- 💬 **聊天档案与搜索**：浏览会话，按关键词或身份信息查找。
- 🔍 **AI Search / 问问微信**：用自然语言找回模糊记忆，并查看来源。
- 🧠 **本地知识库**：建立索引，提升跨会话查询稳定性。
- 📊 **群聊日报**：生成今日、昨日或近 7 天的群聊总结。
- 👀 **群成员变化监控**：记录指定群聊的退群动态。
- 🔊 **文字转语音**：生成语音，试听后发送到选定会话。
- 🤖 **Agent Hub**：在微信里调用本机 TraceMemo。
- 🔌 **外部 Agent / Local HTTP API**：让外部 Agent 查询本机微信历史。
## 项目缘起
@@ -88,11 +60,12 @@ TraceMemo 最早叫 **WechatExplorer**。
第一个版本完成后，项目搁置了一段时间。后来重新捡起来，我还是想继续做群聊日报，但微信已经更新到 4.x，原来的微信 3.0 数据解析方案不再适用。
为了支持微信 4.x，我开始重新研究数据访问。这部分工作得到了 **WeFlow** 很大的帮助。TraceMemo 目前的微信 4.x 数据连接能力，参考并使用了 **WeFlow 历史版本中的相关实现和思路**，包括数据库密钥获取、图片解密等底层能力。
为了支持微信 4.x，我开始重新研究数据访问。这部分工作最初得到了 **WeFlow** 很大的帮助。早期 TraceMemo 曾参考 WeFlow 历史版本中的实现和思路，借此解决了数据库消息、密钥获取等微信 4.x 数据访问问题。
> **没有 WeFlow，就没有今天的 TraceMemo。**
随着项目继续发展，我逐步把这部分底层能力从原有实现中抽离，并重新实现了一套独立的数据访问兼容层。目前会继续保持与 WeFlow 历史接口和行为的兼容，以减少上层业务迁移成本。
也就是说，**WeFlow 是 TraceMemo 进入微信 数据访问领域的重要起点。没有 WeFlow，就没有今天的 TraceMemo。**
WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继续做后面的事情：让聊天记录可以被搜索、理解和总结，也让 AI 给出的答案能够回到原始消息核对。
在此基础上，项目陆续加入了：
@@ -105,12 +78,15 @@ WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继
- Reader Skill
- Agent 接入
- 多种聊天记录导出能力
- 退群监控
- 文字转语音
- 持续监控自动化能力
群聊日报后来被一些人看到，项目也开始有了 Star、Fork、使用反馈和功能建议。说实话，我一开始没想到，这个原本只给自己用的小工具，会得到这么多人的关注。
这些关注和反馈让我决定认真把项目继续做下去。WechatExplorer 就这样一步一步变成了今天的 **TraceMemo（迹忆）**。
感谢 WeFlow，也感谢每一位使用、关注和反馈过 TraceMemo 的人。
感谢每一位使用、关注和反馈过的人。
</details>
@@ -124,298 +100,45 @@ WeFlow 帮我跨过了微信 4.x 数据访问这道门槛，我才有机会继
## 从你的任务开始
| 我现在想做什么 | 在应用里打开 | 需要准备什么 |
| ----------------------------------------- | ------------------------------------------------------------------- | ------------------------------------ |
| 找一句记得原文或关键词的聊天 | [档案](./docs/user-guide/chat-archive.md) | 连接微信数据，不需要 AI |
| 找一件记得大意、但不知道在哪聊过的事 | [问问微信](./docs/user-guide/ai-search.md) | 配置 AI 服务，并选择会话和时间范围 |
| 让长期、跨群聊查找更稳定 | [问问微信 → 本地知识库](./docs/user-guide/knowledge.md) | 主动建立本地索引；不会自动创建 |
| 快速了解一个群今日、昨日或近 7 天聊了什么 | [日报](./docs/user-guide/report.md) | 选择群聊并配置 AI 服务 |
| 把群聊日报生成微信分享卡片（实验性） | [微信分享卡片](./docs/deployment/experimental-wechat-share-card.md) | 自备 Cloudflare、域名和微信测试号 |
| 把微信语音变成可搜索的文字 | [设置 → 语音转文字](./docs/user-guide/voice.md) | 准备本地语音模型 |
| 把聊天保存成 HTML、Markdown、CSV 或 JSON | [导出](./docs/user-guide/export.md) | 选择聊天、时间和格式，不需要 AI |
| 尽量保留之后捕获到的撤回消息 | [设置 → 防撤回](./docs/user-guide/recall-protection.md) | 默认关闭；开启前先了解写入和性能边界 |
| 直接在微信里向 TraceMemo 提问 | [微信机器人](./docs/agent/agent-hub.md) | 扫码连接机器人；总结类任务需要 AI |
| 让 Codex 等外部 Agent 查询微信历史 | [外部 Agent](./docs/agent/overview.md) | 安装 Reader Skill 并配置本机 Token |
---
## 最核心的三个能力
### 生成群聊日报
选择群聊和时间范围后，可以让 AI 把聊天整理成报告，并保存为 HTML 与 PNG 长图。
报告包含：
- 热点
- 重要消息
- 资源
- 问答
- 待办
- 未解决事项
- 活跃统计
- 图片精选
具体内容取决于消息、媒体是否可读以及模型能力。
详细说明：[生成群聊日报](./docs/user-guide/report.md)
</details>
### AI 帮你找回聊过的内容
打开“问问微信”，选择搜索范围和时间，然后像提问一样描述你想找的内容。
TraceMemo 会先在本机查找候选消息，再把整理后的少量来源交给你配置的 AI 模型生成回答。
你可以查看答案参考了哪些聊天、来自哪个人和时间，并从来源标记跳回原始消息核对；“查看检索详情”还会展示本次查找经历了哪些阶段。
<p align="center">
<img src="./public/问一问.png" alt="问问微信与聊天来源" />
</p>
详细说明：[使用 AI 查找聊天信息](./docs/user-guide/ai-search.md)
### 直接在微信里问你的历史聊天
打开应用中的“Agent”入口（页面标题为“Agent Hub”，对应微信机器人功能），扫码连接一个微信机器人账号。
例如，你可以直接给机器人发送：
- “最近 5 个会话”
- “张三最近和我聊了什么”
- “总结今天的技术交流群”
TraceMemo 会在本机读取已连接的聊天数据并把结果回复到微信。
这个入口不要求另外安装 Codex、Claude Code 等外部 Agent。
当前主要处理文字消息，不支持群发、定时任务或通用自主操作微信；总结和自然语言理解需要先配置 AI 服务。
详细步骤和能力边界见[在微信里向 TraceMemo 提问](./docs/agent/agent-hub.md)。
---
## 其他能力
### 本地知识库
<details>
“问问微信”里的“本地知识库”会为当前微信账号建立一份留在本机的可检索资料。
它把聊天文本、附件信息和已有语音转写整理起来，让跨会话、跨时间查找更稳定。
它只在用户主动建立后工作，可以同步、查看占用并清理；清理不会删除微信原始数据库。
详细说明：[本地知识库](./docs/user-guide/knowledge.md)
</details>
### 实验性：生成微信分享卡片
<details>
TraceMemo 可以把群聊日报长图上传到你自己部署的 Cloudflare Worker 和 R2，并生成可在微信中分享的临时网页、二维码及卡片信息。
该功能需要自备 Cloudflare 账号、域名和微信测试号，目前不属于开箱即用的稳定功能。
<p align="center">
<img src="./public/微信卡片分享.png" alt="微信卡片分享效果示例" />
</p>
详细说明：[实验性微信分享卡片](./docs/deployment/experimental-wechat-share-card.md)。
不熟悉命令行的用户，可以把[自动部署 Skill](./docs/skill/setup-wechat-share-card/SKILL.md)直接交给 Codex 或 Claude Code。
</details>
### 转写微信语音
<details>
TraceMemo 支持在本机转写单条或批量微信语音，结果可以参与本地知识库检索和 HTML 导出。
转写本身不要求把语音文件发送给在线 AI；随后用于 AI 问答或日报时，文字会按对应功能的规则处理。
详细说明：[语音转文字](./docs/user-guide/voice.md)
</details>
### 导出长期可用的聊天档案
<details>
支持 HTML、CSV、JSON 和 Markdown。
HTML 可携带媒体、头像和可选语音转写，支持最多五个会话合并，也可以压缩为 ZIP；增量合并、媒体资源和 ZIP 只适用于 HTML，其他格式主要保留文本内容。
详细说明：[导出聊天](./docs/user-guide/export.md)
</details>
### 在外部 Agent 中查询微信历史
<details>
通过 Reader Skill 和本机 Local HTTP API，Codex、Claude Code、OpenClaw 等外部 Agent 可以按需查询联系人、群聊和聊天记录。
这和微信机器人是两条不同路径：
- **微信机器人**：收到消息后在微信中回复。
- **外部 Agent**：主动查询历史。
安装和技术说明请看[Agent 接入概览](./docs/agent/overview.md)与[Local HTTP API](./docs/agent/api.md)。
</details>
---
## 它如何工作
```mermaid
flowchart LR
A[本机微信数据] --> B[TraceMemo 读取与解析]
B --> C[聊天档案]
B --> D[本地知识库与搜索]
D --> E[筛选相关聊天来源]
E --> F[用户配置的 AI 模型]
F --> G[带来源的回答]
B --> H[整理日报输入]
H --> F
B --> I[聊天导出]
B --> J[Local HTTP API]
J --> K[外部 Agent]
L[微信机器人消息] --> M[Agent Hub]
M --> B
M --> F
```
- 微信数据库读取、聊天解析、知识库索引和离线语音识别在本机完成。
- 普通浏览、普通搜索和导出不要求配置 AI 服务。
- 使用“问问微信”、群聊日报或图片理解等 AI 功能时，完成任务所需的内容可能发送到你选择的模型服务；具体发送范围和确认方式以对应功能页面为准。
- “问问微信”会先在本机缩小范围，不会默认把整个微信数据库作为一次模型请求发送。
完整边界见：[数据、隐私与安全](./docs/user-guide/privacy.md)
---
## 支持平台与安装包
| 平台 | 处理器架构 | Releases 安装包 |
| ------- | ------------------------------ | --------------- |
| Windows | x64 | `-setup.exe` |
| macOS | Apple Silicon（M 系列、arm64） | `.dmg` |
当前版本不支持 Intel 芯片的 Mac。
当前代码面向微信 4.x 数据结构。实际连接结果仍会受到微信客户端版本、账号数据状态和系统权限影响；macOS 首次连接可能需要按页面提示完成额外授权。
---
| 想做什么 | 使用入口 |
| --- | --- |
| 找记得原文或关键词的消息 | 档案搜索 |
| 找记得大意、但不知道在哪聊过的内容 | AI Search / 问问微信 |
| 长期跨群查询历史 | 本地知识库 |
| 了解一个群今天或近 7 天聊了什么 | 群聊日报 |
| 持续关注群成员退出 | 退群监控 |
| 按计划生成并发送群聊日报 | 定时日报 |
| 把文字生成微信语音 | 文字转语音 |
| 在微信里向本机 TraceMemo 提问 | Agent Hub |
| 让 Codex 等工具查询微信历史 | Reader Skill / Local HTTP API |
| 把聊天保存成文件 | 导出 |
## 快速开始
1. 从 [GitHub Releases](https://github.com/Wxw-Gu/TraceMemo/releases) 下载安装包。
2. 启动 TraceMemo，按照“第一次使用”页面选择微信数据目录。
3. 第一次使用请先点击“开始连接”，按页面提示准备连接组件并获取数据库密钥；只有已经有密钥的高级用户才需要“手动连接”。
4. 连接成功后打开“档案”，确认联系人和聊天消息已经出现。
5. 先在“档案”里搜索一句你记得的原话；这一步不需要 AI。
6. 需要 AI 问答或日报时，在“设置 → AI 模型”添加并测试 AI 服务，再打开“问问微信”或“日报”。
7. 想直接在微信里提问时，打开“Agent”扫码连接微信机器人；想让 Codex 等外部 Agent 查询时，再进入“API”。
1. 从 [GitHub Releases](https://github.com/Wxw-Gu/TraceMemo/releases) 下载对应平台的安装包。
2. 启动应用，按“第一次使用”页面选择微信数据目录并完成连接。
3. 打开“档案”，确认联系人和消息已加载后开始搜索。
4. 需要 AI 时，在“设置 → AI 模型”添加并测试 Provider。
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)。
从 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 等本地服务和自定义接口；具体服务商的配置、计费和数据规则由服务商决定。
使用本地服务可以减少数据离开电脑的路径，但本地服务的日志和配置仍由你自己负责。
开发者和 Agent 用户可以从[Agent 接入概览](./docs/agent/overview.md)开始，再按需要查看[Local HTTP API](./docs/agent/api.md)与[API 安全](./docs/agent/api-security.md)。
---
详细步骤见[第一次使用 TraceMemo](./docs/user-guide/getting-started.md)。
## 文档
- [文档首页](./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/deployment/experimental-wechat-share-card.md)
- [微信分享卡片自动部署 Skill](./docs/skill/setup-wechat-share-card/SKILL.md)
- [语音转文字](./docs/user-guide/voice.md)
- [导出聊天](./docs/user-guide/export.md)
- [防撤回](./docs/user-guide/recall-protection.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)
- [用户指南](./docs/README.md#用户指南)
- [AI / Knowledge](./docs/README.md#ai-与知识库)
- [Monitor / Automation](./docs/README.md#日报与自动化)
- [Agent / API](./docs/README.md#agent--api)
- [开发文档](./docs/development/overview.md)
- [隐私与安全](./docs/user-guide/privacy.md)
---
完整目录由[文档首页](./docs/README.md)维护。
## 本地开发
## 支持平台
需要 Node.js、pnpm 7+、对应平台的 Electron/native 构建环境，以及 Go（用于微信连接器）。
```bash
pnpm install
pnpm dev
```
常用检查：
```bash
pnpm typecheck
pnpm test:unit
pnpm test:component
pnpm test:integration
pnpm test:e2e:build
```
完整说明：[开发、测试与构建](./docs/development/overview.md)
---
## 支持与反馈
遇到问题时，先查看[常见问题与排查](./docs/user-guide/troubleshooting.md)。
提交 Issue 时请提供：
- 操作系统
- 微信版本
- TraceMemo 版本
- 复现步骤
- 已遮挡敏感信息的截图
请仅处理你有权访问的数据，并遵守适用的法律法规、组织政策和微信使用规则。
数据库读取、解密、自动化和机器人能力都可能受平台版本与账号环境影响。
---
## 许可说明
TraceMemo 当前暂未提供独立的项目 `LICENSE` 文件。
TraceMemo 允许个人使用、学习、修改、二次开发和 Fork，也欢迎基于项目进行非商业用途的再开发和分享。
**但未经项目维护者书面许可，禁止将 TraceMemo 本身或基于 TraceMemo 的衍生版本用于商业用途，包括但不限于商业软件、付费服务、商业产品、SaaS 服务或其他直接或间接的商业活动。**
仓库中的第三方组件以及参考项目均遵循各自适用的许可证和使用条款。TraceMemo 对第三方项目的参考、使用或集成，并不意味着这些第三方项目的代码或许可证发生变化。涉及第三方代码的部分，请以对应项目的许可证和授权范围为准。
---
| 平台 | 架构 | 安装包 |
| --- | --- | --- |
| Windows | x64 | `-setup.exe` |
| macOS | Apple Silicon（M 系列、arm64） | `.dmg` |
## 致谢
@@ -423,18 +146,21 @@ TraceMemo 的诞生离不开开源社区中许多优秀项目的工作。
### 特别感谢 WeFlow
TraceMemo 在支持微信 4.x 时，参考并使用了 **[WeFlow](https://github.com/hicccc77/WeFlow)** 历史版本中的相关实现和思路，包括数据库密钥获取、图片解密等底层能力。
TraceMemo 在早期适配微信 4.x 时，曾参考 **[WeFlow](https://github.com/hicccc77/WeFlow)** 历史版本中的相关实现和思路，包括数据库访问、密钥获取等底层能力。
特别感谢作者 **hicccc77** 的理解和包容。项目与 WeFlow 的具体关系见[项目缘起](#项目缘起)。
特别感谢作者 **[hicccc77](https://github.com/hicccc77)**。项目与 WeFlow 的具体关系见[项目缘起](#项目缘起)。
### 其他参考项目
- **[WechatMessageExplorer](https://github.com/svcvit/WechatMessageExplorer)**
- 提供了数据库解析相关思路。
- 提供了数据解析相关思路。
- **[chatlog](https://github.com/sjzar/chatlog)**
- 提供了数据处理方面的参考。
- **[wechat_chatter](https://github.com/yincongcyincong/wechat_chatter)**
- 提供了发送方面的参考。
感谢所有开源作者，也感谢所有帮助 TraceMemo 发现问题、提出建议和持续使用它的人。
---
docs/README.md
+45 -42
View File
@@ -1,64 +1,67 @@
# TraceMemo 文档
TraceMemo 的文档按“你想完成什么”组织，而不是按源码模块组织。
文档按产品任务和使用场景组织。需要集成或开发时，再看 Agent、概念和开发文档。
## 从这里开始
## 档案与搜索
- [第一次使用](./user-guide/getting-started.md)：安装、连接微信、完成第一次搜索和提问。
- [查看和搜索聊天](./user-guide/chat-archive.md)：找原话、回看上下文、处理媒体。
- [用 AI 查找聊天信息](./user-guide/ai-search.md)：理解普通搜索和 AI Search 的区别，并核对答案来源。
- [第一次使用](./user-guide/getting-started.md)：安装、连接微信并完成第一次搜索。
- [聊天档案与搜索](./user-guide/chat-archive.md)：浏览联系人和群聊，按关键词、备注、昵称、微信号或 wxid 查找消息；也包含档案中的文字转语音入口。
## 你可以完成的任务
## AI 与知识库
- [建立本地知识库](./user-guide/knowledge.md)
- [生成群聊日报和总结](./user-guide/report.md)
- [实验性：自托管微信分享卡片](./deployment/experimental-wechat-share-card.md)
- [交给 Agent 自动部署微信分享卡片](./skill/setup-wechat-share-card/SKILL.md)
- [语音转文字](./user-guide/voice.md)
- [导出聊天档案](./user-guide/export.md)
- [防撤回](./user-guide/recall-protection.md)
- [在微信里向 TraceMemo 提问](./agent/agent-hub.md)
- [数据、隐私与安全](./user-guide/privacy.md)
- [常见问题与排查](./user-guide/troubleshooting.md)
- [AI Search / 问问微信](./user-guide/ai-search.md)：用自然语言找回记得大意、但不知道在哪个会话里的内容，并查看 Evidence、Citation 和 Search Trace。
- [本地知识库](./user-guide/knowledge.md)：主动建立本地索引，提升跨会话、跨时间查询的稳定性。
- [如何核对 AI 的回答来源](./concepts/answer-sources.md)：从来源回到原始消息，检查上下文和覆盖范围。
- [从微信数据到回答、日报和导出](./concepts/how-it-works.md)：了解哪些步骤在本机完成，哪些 AI 功能可能调用 Provider。
## 如果你想了解 AI 为什么这样回答
## 日报与自动化
- [如何核对 AI 的回答来源](./concepts/answer-sources.md)：用用户语言解释依据、来源标记和查找过程。
- [从微信数据到回答、日报和导出](./concepts/how-it-works.md)：了解哪些步骤在本机完成，哪些步骤可能调用 Provider。
- [群聊日报](./user-guide/report.md)：手动生成今日、昨日或近 7 天的群聊报告，也可以创建定时日报。
- 定时日报会依次生成报告、保存 Report History，再按当前微信发送能力尝试通知；发送失败时可复用已有 PNG 重试。
- 自动发送和监控动作通过统一执行边界，并保留执行记录；简要说明见[产品工作方式](./concepts/how-it-works.md#动作执行与审计)。
## 微信机器人和外部 Agent
## Monitor
TraceMemo 有两种不同的接入方式。微信机器人是普通用户可以直接使用的产品能力；Reader Skill 和 Local HTTP API 面向已经在使用 Codex、Claude Code、OpenClaw 等外部 Agent 的用户。
退群监控会比较当前成员与上一份有效快照，记录成员退出事件。它支持多群、Last Good Snapshot 和事件历史；监控关闭期间的变化不会在重新开启后补报。工作方式见[产品工作方式](./concepts/how-it-works.md#退群监控)。
| 你想做什么 | 应该看哪里 |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 在微信里给机器人发消息，让本机读取数据、生成总结并回复 | [Agent Hub](./agent/agent-hub.md) |
| 在 Codex、Claude Code、OpenClaw 等外部 Agent 中主动查询过去的微信数据 | [Reader Skill](./agent/reader-skill.md) + [Local HTTP API](./agent/api.md) |
## 语音能力
### 在微信里提问
- [语音转文字](./user-guide/voice.md)：在本机转写微信语音，结果可用于搜索、Knowledge 和导出。
- [聊天档案与搜索](./user-guide/chat-archive.md#文字转语音)：把文字生成微信语音，试听后发送到当前联系人或群聊。
打开应用一级导航中的“Agent”，进入“Agent Hub”后扫码登录微信机器人。机器人收到文字消息后，可以查询最近会话、读取联系人聊天、生成群聊总结图片或总结群成员发言，并把结果回复给发消息的人。它需要本地微信数据库已经连接；依赖 AI 的任务还需要配置 AI 服务。
## Agent / API
- [Agent Hub](./agent/agent-hub.md)：连接机器人、查看运行状态和了解实时交互边界。
Agent Hub 让微信机器人调用本机 TraceMemo；Reader Skill / Local HTTP API 让外部 Agent 主动查询历史数据。
### 让外部 Agent 查询历史微信
- [Agent 接入概览](./agent/overview.md)
- [Agent Hub](./agent/agent-hub.md)
- [Reader Skill](./agent/reader-skill.md)
- [Local HTTP API](./agent/api.md)
- [API 安全](./agent/api-security.md)
连接 Reader Skill 后，你可以询问：
## 导出与隐私
> “总结今天技术交流群讨论了什么。”
> “过去一周有没有人提到这个项目？”
- [导出聊天](./user-guide/export.md)：导出 HTML、Markdown、CSV 或 JSON 档案。
- [数据、隐私与安全](./user-guide/privacy.md)：本地处理、Provider、媒体和 Token 的数据边界。
- [常见问题与排查](./user-guide/troubleshooting.md)：按安装、连接、AI、媒体和 Agent 现象排查。
- [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、轮换和边界。
## 开发文档
## 开发与平台
- [macOS 数据访问说明](./platform/macos.md)
- [开发、测试与构建](./development/overview.md)
- [本地启动排障](./development/local-startup-troubleshooting.md)
- [v2.2.0 正式品牌身份与安全升级迁移](./agent/release-notes-v2.2.0.md)
- [v2.1.9 API 鉴权迁移说明](./agent/release-notes-v2.1.9.md)
- [macOS 数据访问说明](./platform/macos.md)
- [关闭 SIP 教程](./mac-disable-sip.md)
当前工作区版本：**2.2.0**。文档只描述当前代码已经实现的能力；版本兼容性、AI Provider 行为和媒体读取结果可能随系统、微信客户端和服务商变化。
## 实验性功能与第三方
- [实验性：自托管微信分享卡片](./deployment/experimental-wechat-share-card.md)
- [微信分享卡片自动部署 Skill](./skill/setup-wechat-share-card/SKILL.md)
- [TraceMemo Reader Skill 文件](./skill/tracememo-reader/SKILL.md)
- [第三方组件说明](./third-party/wechat-chatter/NOTICE.md)
## 版本说明
- [v2.2.0 品牌与安全迁移](./agent/release-notes-v2.2.0.md)
- [v2.1.9 API 鉴权迁移](./agent/release-notes-v2.1.9.md)
文档按当前 develop 已实现的能力维护，不在首页固定写死版本号。版本兼容性、AI Provider 行为和媒体读取结果可能随系统、微信客户端和服务商变化。
docs/concepts/how-it-works.md
+37
View File
@@ -19,8 +19,45 @@ flowchart LR
M[微信机器人消息] --> N[Agent Hub]
N --> B
N --> F
B --> O[Monitor / Snapshot]
O --> P[Proposed Action]
F --> P
P --> Q[Policy]
Q --> R[Action Gateway]
R --> S[Personal WeChat Send Capability]
S --> T[Action Audit / Logs]
```
## Remember → Understand → Monitor → Act
TraceMemo 的工作方式可以概括为：
```text
Remember → Understand → Monitor → Act
```
先读取和整理微信信息，再由 AI、Knowledge 或日报帮助理解；Monitor 负责发现成员变化，明确的业务动作再进入执行边界。回答和动作结果都应能回到来源或记录核对。
## 退群监控
退群监控使用成员快照判断变化：
```text
Current Membership → Snapshot Diff → Member Event
```
上一份有效快照（Last Good Snapshot）不会被不完整读取覆盖，因此重启后仍可继续监控通知。
## 动作执行与审计
自动发送和监控动作经过统一边界：
```text
Feature → Policy → Gateway → Capability → Execution → Audit
```
Policy blocked 表示策略不允许，Capability unavailable 表示当前发送能力不可用，Send failed 表示已经尝试但执行失败。Action Audit / Logs 会保留执行结果；定时日报即使发送失败，也会保留已生成的报告记录。
## 哪些步骤在本机
- 微信数据库读取与解析；
docs/user-guide/chat-archive.md
+19 -1
View File
@@ -4,7 +4,7 @@
## 选择要看的会话
左侧会话列表可以浏览联系人、群聊、折叠群聊和公众号等已读取到的会话。选中会话后，右侧显示消息时间线；滚动到较早位置可以继续加载历史。
左侧会话列表可以浏览已读取到的联系人、群聊和公众号。选中会话后，右侧显示消息时间线；滚动到较早位置可以继续加载历史。
如果你从 AI 回答的来源进入档案，应用会自动切换到对应会话并尽量定位到消息时间。
@@ -19,6 +19,22 @@
关键词搜索速度快、结果直观，但它不会理解“意思相近但没有相同词”的问题。
## 怎么找到联系人
档案搜索会综合多个身份字段匹配联系人或群聊，包括：
- 通讯录备注（remark）；
- 微信昵称；
- 当前微信号；
- wxid；
- 拼音全拼和拼音首字母。
因此可以直接输入备注、昵称、微信号或拼音查找。搜索联系人和搜索消息是两步：先确认目标会话，再在会话内查关键词；记得大意但不知道原话时，改用[AI Search](./ai-search.md)。
## 文字转语音
在档案中选择当前联系人或群聊，输入文字后生成语音，试听确认后发送。这个入口只处理明确的文字转语音动作，不是任意文本、图片或本地语音文件发送器。
## 消息和媒体
根据微信数据中实际可用的资源，档案可以展示文本、图片、视频、语音、文件、链接、引用、小程序、表情和系统消息等类型。媒体是否能显示，取决于本机原始资源是否仍然存在、权限是否完整以及当前微信版本的存储方式。
@@ -27,6 +43,8 @@
如果文字正常但图片无法打开，进入“设置 → 图片解密”查看当前状态。可以尝试自动获取，也可以在已经知道正确密钥时手动配置；原文件已经被微信清理时，仅配置密钥也无法恢复图片。
联系人和群聊列表会尽量显示头像、备注和昵称。头像或资料缺失时不影响消息读取；这通常表示本机没有对应资源，或微信没有返回完整资料。
## 可选保留撤回消息
“设置 → 防撤回”提供一个默认关闭的可选功能。开启后，应用会尽量保留之后捕获到的撤回消息，并在气泡旁标记“消息已撤回”。它不能找回开启前已经消失或应用未捕获到的内容，也可能增加加载开销。
docs/user-guide/monitor-automation.md
+2
View File
@@ -0,0 +1,2 @@
# monitor-automation
docs/user-guide/report.md
+12
View File
@@ -33,6 +33,18 @@
生成成功后会保存本地 HTML 与 PNG，并出现在日报历史中。你可以复制图片、打开文件位置或重新生成。删除历史日报只删除本地生成的报告文件，不会影响微信聊天数据库。
## 定时日报
在“日报 → 定时日报”中可以创建每天运行的任务。选择群聊、执行时间、日报范围、消息类型和模板后，TraceMemo 会按计划执行：
```text
定时触发 → 读取群聊 → 生成报告 → 保存 Report History → 尝试发送
```
生成和发送是两个阶段。当前微信发送能力不可用、未绑定或发送失败时，报告仍会保存，PNG 和执行记录也会保留；这类结果会显示为“已生成，但未发送”或“已生成，发送失败”。
执行记录支持查看已生成的日报。对“等待发送”或“发送失败”的记录，可以直接重试发送，重试会复用已经生成的 PNG，不会重新调用 AI 生成整份报告；完整执行状态和发送边界见[如何把聊天变成可用的信息](../concepts/how-it-works.md#动作执行与审计)。
## 让报告更可靠
- 先选正确的群和时间范围；