# 第一次使用 TraceMemo
如果你刚下载 TraceMemo，只需要完成一条主线：
> 安装应用 → 连接微信数据 → 确认聊天已加载 → 搜索或提问。
这篇文档不要求你先学习内部术语；先把第一个问题问出来，之后再按需要深入了解产品名称和进阶功能。
## 1. 开始前准备
TraceMemo 需要读取微信本地数据库。首次使用前，请确认已安装受支持的微信客户端，并按照连接页面完成数据库密钥获取。
| 系统 | 微信客户端 | 首次连接说明 |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| macOS | **微信 4.1.13 系列**（推荐 [4.1.13.8](https://github.com/zsbai/wechat-versions/releases/tag/4.1.13.8)）
备选 [4.1.8.100](https://github.com/zsbai/wechat-versions/releases/tag/4.1.8.100) | 支持 Apple Silicon（M 系列）和 Intel Mac 自动获取数据库密钥。首次连接时，请按照 TraceMemo 页面提示完成系统授权及微信登录操作。 |
| Windows | **微信 4.x**（推荐 [4.1.9.57](https://github.com/iibob/wechat-win-archive/releases/tag/v4.1.9.57)） | 支持自动获取数据库密钥。首次使用时请确认微信数据目录正确，无需处理 macOS 的 SIP 设置。 |
### macOS 用户
TraceMemo 已支持两种 Mac 架构：
- **Apple Silicon（M1 / M2 / M3 / M4 等）**
- **Intel Mac（x64）**
两种架构均支持自动获取微信数据库密钥，TraceMemo 会根据当前 Mac 自动选择对应的连接方式。
Apple Silicon 和 Intel 均已适配微信 macOS `4.1.13` 系列。首次获取密钥时，请让微信停留在登录页面，并按照 TraceMemo 中显示的步骤操作。
> 不同 Mac 架构的连接流程可能略有区别，请始终以应用内「第一次使用」页面显示的提示为准。
### 关于微信版本
- 上表中的版本是当前 TraceMemo 已适配或推荐使用的版本，并不代表只有这些版本可以运行。
- TraceMemo 必须取得当前微信账号对应的数据库密钥，才能读取聊天记录。
- 你需要有权访问要读取的微信账号和聊天数据。
- 如果要使用 AI 问答、群聊日报或图片理解，还需要在应用中配置一个 AI 服务。
当前代码按微信 4.x 数据结构处理。不同微信客户端版本、系统权限和数据迁移状态可能影响自动连接；遇到问题时请查看[常见问题与排查](./troubleshooting.md)。
## 2. 安装并启动
安装包统一从 [GitHub Releases](https://github.com/Wxw-Gu/TraceMemo/releases) 下载。
### Windows
1. 从 Releases 下载 Windows x64 的 `tracememo-<版本号>-setup.exe` 安装包。
2. 双击安装包，按向导完成安装。
3. 启动 TraceMemo。
4. 如果安装完成后软件无法启动，请安装 Microsoft Visual C++ x64 运行库：[vc_redist.x64.exe](https://aka.ms/vc14/vc_redist.x64.exe)，安装完成后重新启动 TraceMemo。
### macOS
1. 从 Releases 下载与你 Mac 处理器架构匹配的 `.dmg`：
- Apple Silicon（M 系列、`arm64`）：`tracememo-<版本号>-arm64.dmg`
- Intel（`x64`）：`tracememo-<版本号>-x64.dmg`
2. 打开 DMG，将 TraceMemo 拖入“应用程序”文件夹。
3. 如果系统提示“无法打开，因为开发者无法验证”，前往“系统设置 → 隐私与安全性”，点击“仍要打开”。
4. 如果系统提示应用已损坏，可在终端执行：
```bash
xattr -cr "/Applications/TraceMemo.app"
```
5. 先让微信停在**未登录窗口**（如果微信已经登录，请退出当前账号，**只关闭窗口不算**），再启动 TraceMemo。
- 连接时会按提示自动获取数据库密钥；应用会根据当前架构进入对应流程，按连接页面显示的授权要求操作即可。
- **等第五步 明确提示可以登录后，再回到微信点击登录。** 在此之前不要先点登录，否则这次密钥获取会失败，需要重新开始。
- 只有页面明确提示时才按[关闭 SIP 教程](../mac-disable-sip.md)处理。关闭 SIP 会降低系统安全性，完成密钥配置后应重新开启。
> **注意事项：取密钥时提示监听超时（`CAPTURE_TIMEOUT`，或相关失败）**
>
> 这说明「先让微信停在未登录窗口」这一步操作有误——常见原因是微信当时已经登录，或者还没等连接页面提示就先点了登录
>
> 请先退出微信账号、回到**未登录窗口**，然后按上面的第 5 步**重新来一遍**（等连接页面明确提示可以登录后，再回到微信点击登录）。
更完整的权限和安全边界见 [macOS 数据访问说明](../platform/macos.md)。
## 3. 让应用读取微信数据
首次启动会自动进入“第一次使用”页面。页面会根据当前系统显示连接方式和注意事项：
通常按下面三步操作即可：
1. **确认微信数据目录**：自动识别不准确时，打开微信设置中的缓存/存储管理，复制实际路径并在页面中修改。
2. **让微信停在登录页面**：如果微信已经登录，先退出当前微信账号，不只是关闭微信窗口。
3. **点击“开始连接”并按提示获取密钥**：软件准备好连接组件后会提示你登录微信；回到微信完成登录，再等待数据库、账号和联系人检查完成。
只有已经通过其他方式取得当前账号数据库密钥的高级用户，才需要选择“手动连接”。Windows 不需要关闭 SIP；macOS 是否需要额外授权或处理 SIP，以当前连接页面提示为准。
连接页面会显示微信状态、数据库状态和诊断结果。连接失败时先不要反复删除数据，优先查看[连接问题排查](./troubleshooting.md#连接微信失败)。
## 4. 确认第一次连接成功
连接成功后会进入“档案”页面。你可以用下面三个信号确认已经准备好：
- 左侧出现联系人或群聊列表；
- 选中一个会话后，右侧能看到历史消息；
- 搜索框可以在当前会话中定位文字。
如果联系人列表为空，先检查是否连到了正确账号和数据目录，再重新加载会话。
文字消息正常但图片打不开时，不代表数据库连接失败。打开“设置 → 图片解密”查看状态并尝试自动获取；图片原文件缺失、权限不足或密钥不匹配时，部分图片仍可能无法显示。
## 5. 完成你的第一个任务
### 只是想找一句话
进入“档案”，选择联系人或群聊，在会话内搜索关键词。适合你记得原话、姓名、链接或大致关键词的情况。
### 想找一个模糊的结论
先在“设置 → AI 模型”添加并测试一个 Provider，再进入“问问微信”描述问题，例如：
- “上个月技术群讨论过哪些发布问题？”
- “张三之前发过的项目地址在哪里？”
- “过去一周有没有人提到退款？”
这就是 AI Search：它会先帮你从本机聊天中找出相关内容，再让你配置的模型组织答案。你不需要知道关键词在哪，但问题越具体，结果越容易核对。
### 想让 AI 的答案可核对
回答生成后，打开来源或检索详情，查看它参考的聊天内容、会话、时间和原始消息。你可以从来源直接跳回“档案”检查上下文。
产品把这些来源信息分别称为 Evidence、Citation 和 Search Trace；普通使用时只需要记住“答案可以回到原消息核对”即可。详见[如何核对 AI 的回答来源](../concepts/answer-sources.md)。
## 6. 接下来可以做什么
- [查看和搜索聊天](./chat-archive.md)
- [使用 AI 查找聊天信息](./ai-search.md)
- [建立本地知识库，让后续查找更稳定](./knowledge.md)
- [生成群聊日报或总结](./report.md)
- [转写微信语音](./voice.md)
- [导出聊天档案](./export.md)
- [在微信里向 TraceMemo 提问](../agent/agent-hub.md)
- [让外部 Agent 查询微信历史](../agent/overview.md)
## 7. 想直接在微信里提问
如果你希望直接在微信里向 TraceMemo 提问，而不是另外配置 Codex 等外部 Agent，请使用 Agent Hub：
1. 先完成上面的微信数据库连接，并确认“档案”里能看到聊天。
2. 打开应用主导航中的“Agent”；页面标题为“Agent Hub”。
3. 确认 Agent Hub 显示“运行中”，数据 API/数据库状态可以查询。
4. 点击“扫码登录微信机器人”，用微信扫描二维码，并在手机上确认登录。
5. 状态变为“在线”后，向这个机器人发送文字消息。
可以先试试这些真实支持的请求：
- “最近 5 个会话”；
- “帮我看看最近跟张三聊了些什么”；
- “生成产品交流群今天的群聊总结图片”。
机器人会把处理结果回复给发消息的人。联系人聊天总结、群聊总结和需要理解自然语言的请求依赖“设置 → AI 模型”中已经配置好的 AI 服务。当前实时入口主要处理文字消息；它不是支持任意图片、语音、文件理解、群发或定时任务的通用机器人。机器人账号扫码登录与读取你微信数据库是两条独立流程，都需要分别确认账号和权限。
Agent Hub 是普通用户可以直接使用的入口，不需要安装 Reader Skill 或配置 API Token。Reader Skill 和 API 只用于让外部 Agent 主动查询历史微信。
## 8. 需要配置 AI 吗？
不一定。浏览聊天、普通关键词搜索、建立本地知识库和导出不要求在线 AI 服务。
使用“问问微信”、群聊日报或图片理解时，需要在“设置 → AI 模型”中添加并测试 AI 服务。你主动开始并确认远程 AI 功能后，完成任务所需的内容才可能发送给该服务；计费、留存和地区规则由对应服务商决定。
## 9. 数据和隐私的最低须知
- 微信数据库、聊天解析和本地索引默认留在本机。
- 离线语音转写使用本地模型；它与在线 AI 请求是两条不同的数据路径。
- 你主动开始并确认 AI 问答或日报后，完成任务所需的受控上下文才可能发送给你选择的 AI 服务；打开应用不会自动上传全部聊天。
- 应用内 Local HTTP API 默认只监听 `127.0.0.1:6131`，受保护接口需要 Token。
完整边界见[数据、隐私与安全](./privacy.md)。
## 10. 如果你卡住了
按现象进入[常见问题与排查](./troubleshooting.md)：连接失败、聊天为空、AI 没有结果、语音模型不可用、导出失败和 Agent 无法访问分别有不同处理方式。