bacow/chatlog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
Shen Junzheng
2025-04-16 17:40:19 +08:00
parent 25d0b394e2
commit 07a15117f3
4 changed files with 477 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

237
README.md
View File

@@ -2,7 +2,7 @@
# Chatlog
![chatlog](https://socialify.git.ci/sjzar/chatlog/image?font=Rokkitt&name=1&pattern=Diagonal+Stripes&theme=Auto)
![chatlog](https://socialify.git.ci/sjzar/chatlog/image?font=Rokkitt&forks=1&issues=1&name=1&pattern=Diagonal+Stripes&stargazers=1&theme=Auto)
_聊天记录工具，帮助大家轻松使用自己的聊天数据_
@@ -13,7 +13,7 @@ _聊天记录工具，帮助大家轻松使用自己的聊天数据_
</div>
![chatlog](https://github.com/user-attachments/assets/746717b8-9b39-4a45-97f3-f0ae8fc5a344)
![chatlog](https://github.com/user-attachments/assets/e085d3a2-e009-4463-b2fd-8bd7df2b50c3)
## Feature
@@ -23,16 +23,35 @@ _聊天记录工具，帮助大家轻松使用自己的聊天数据_
- 提供 Terminal UI 界面 & 命令行工具
- 提供 HTTP API 服务，支持查询聊天记录、联系人、群聊、最近会话等信息
- 支持 MCP SSE 协议，可与支持 MCP 的 AI 助手无缝集成
- 支持多媒体消息，支持解密图片、语音
- 支持自动解密数据，简化使用流程
- 支持多账号管理，可在不同账号间切换
## TODO
- 支持多媒体数据
- 聊天数据全文索引
- 聊天数据统计 & Dashboard
## Quick Start
## Install
### 基本步骤
1. **安装 Chatlog**：[下载预编译版本](#下载预编译版本) 或 [使用 Go 安装](#从源码安装)
2. **运行程序**：执行 `chatlog` 启动 Terminal UI 界面
3. **解密数据**：选择 `解密数据` 菜单项
4. **开启 HTTP 服务**：选择 `开启 HTTP 服务` 菜单项
5. **访问数据**：通过 [HTTP API](#http-api) 或 [MCP 集成](#mcp-集成) 访问聊天记录
> 💡 **提示**：如果电脑端微信聊天记录不全，可以[从手机端迁移数据](#从手机迁移聊天记录)
### 常见问题快速解决
- **macOS 用户**：获取密钥前需[临时关闭 SIP](#macos-版本说明)
- **Windows 用户**：遇到界面显示问题请[使用 Windows Terminal](#windows-版本说明)
- **集成 AI 助手**：查看 [MCP 集成指南](#mcp-集成)
## 安装指南
### 从源码安装
@@ -44,150 +63,164 @@ go install github.com/sjzar/chatlog@latest
访问 [Releases](https://github.com/sjzar/chatlog/releases) 页面下载适合您系统的预编译版本。
## Quick Start
### 操作流程
1. 下载并安装微信客户端
2. 手机微信上操作 `我 - 设置 - 通用 - 聊天记录迁移与备份 - 迁移 - 迁移到电脑`，这一步的目的是将手机中的聊天记录传输到电脑上。可以放心操作，不会影响到手机上的聊天记录。
3. 下载 `chatlog` 预编译版本或从源码安装，推荐使用 go 进行安装。
4. 运行 `chatlog`，按照提示进行操作，解密数据并开启 HTTP 服务后，即可通过浏览器或 AI 助手访问聊天记录。
### macOS 版本提示
1. macOS 用户在获取密钥前，需要确认已经关闭 SIP 并安装 Xcode Command Line Tools。由于 macOS 的安全机制，在正常情况在无法读取微信进程的内存数据，所以需要临时关闭 SIP。关闭 SIP 的方法：
```shell
# 1. 进入恢复模式
Apple Intel Mac: 关机后，按住 Command + R 键开机，直到出现苹果标志和进度条。
Apple Silicon Mac: 关机后，按住开机键不松开，直到出现苹果标志和进度条。
# 2. 打开终端
选项 - 实用工具 - 终端
# 3. 关闭 SIP
输入以下命令关闭 SIP：
csrutil disable
# 4. 重启系统
```
2. 目前的 macOS 版本方案依赖 `lldb` 工具，所以需要安装 Xcode Command Line Tools。
```shell
# 在 terminal 执行以下命令安装 Xcode Command Line Tools：
xcode-select --install
```
3. 仅获取数据密钥步骤需要关闭 SIP；获取数据密钥后即可重新打开 SIP，不影响解密数据和 HTTP 服务的运行。
4. 如果是 Apple Silicon 芯片的 mac 用户，请检查 微信、chatlog、terminal 均不要运行在 Rosetta 模式下运行，否则可能无法获取密钥。
## 使用指南
### Terminal UI 模式
1. 启动程序：
最简单的使用方式是通过 Terminal UI 界面操作：
```bash
./chatlog
chatlog
```
2. 使用界面操作：
- 使用方向键导航菜单
- 按 `Enter` 选择菜单项
- 按 `Esc` 返回上一级菜单
- 按 `Ctrl+C` 退出程序
操作方法：
- 使用 `↑` `↓` 键选择菜单项
- 按 `Enter` 确认选择
- 按 `Esc` 返回上级菜单
- 按 `Ctrl+C` 退出程序
### 命令行模式
获取微信数据密钥：
对于熟悉命令行的用户，可以直接使用以下命令：
```bash
./chatlog key
# 获取微信数据密钥
chatlog key
# 解密数据库文件
chatlog decrypt
# 启动 HTTP 服务
chatlog server
```
解密数据库文件：
### 从手机迁移聊天记录
```bash
./chatlog decrypt
```
如果电脑端微信聊天记录不全，可以从手机端迁移数据：
1. 打开手机微信，进入 `我 - 设置 - 通用 - 聊天记录迁移与备份`
2. 选择 `迁移 - 迁移到电脑`，按照提示操作
3. 完成迁移后，重新运行 `chatlog` 获取密钥并解密数据
> 此操作不会影响手机上的聊天记录，只是将数据复制到电脑端
## 平台特定说明
### Windows 版本说明
如遇到界面显示异常（如花屏、乱码等），请使用 [Windows Terminal](https://github.com/microsoft/terminal) 运行程序
### macOS 版本说明
macOS 用户在获取密钥前需要临时关闭 SIP（系统完整性保护）：
1. **关闭 SIP**：
```shell
# 进入恢复模式
# Intel Mac: 重启时按住 Command + R
# Apple Silicon: 重启时长按电源键
# 在恢复模式中打开终端并执行
csrutil disable
# 重启系统
```
2. **安装必要工具**：
```shell
# 安装 Xcode Command Line Tools
xcode-select --install
```
3. **获取密钥后**：可以重新启用 SIP（`csrutil enable`），不影响后续使用
> Apple Silicon 用户注意：确保微信、chatlog 和终端都不在 Rosetta 模式下运行
## HTTP API
启动 HTTP 服务后，可以通过以下 API 访问数据：
启动 HTTP 服务后（默认地址 `http://127.0.0.1:5030`），可通过以下 API 访问数据：
### 聊天记录
### 聊天记录查询
```
GET /api/v1/chatlog?time=2023-01-01&talker=wxid_xxx&limit=100&offset=0&format=json
GET /api/v1/chatlog?time=2023-01-01&talker=wxid_xxx
```
参数说明：
- `time`: 时间范围，格式为 `YYYY-MM-DD` 或 `YYYY-MM-DD~YYYY-MM-DD`
- `talker`: 聊天对象的 ID，不知道 ID 的话也可以尝试备注名、昵称、群聊 ID等
- `limit`: 返回记录数量限制
- `offset`: 分页偏移量
- `format`: 输出格式，支持 `json`、`csv` 或纯文本
- `talker`: 聊天对象标识（支持 wxid、群聊 ID、备注名、昵称等）
- `limit`: 返回记录数量（默认 100）
- `offset`: 分页偏移量（默认 0）
- `format`: 输出格式，支持 `json`、`csv` 或纯文本（默认 纯文本）
### 联系人列表
### 其他 API 接口
```
GET /api/v1/contact
```
- **联系人列表**：`GET /api/v1/contact`
- **群聊列表**：`GET /api/v1/chatroom`
- **会话列表**：`GET /api/v1/session`
- **多媒体内容**：`GET /api/v1/media?msgid=xxx`
### 群聊列表
```
GET /api/v1/chatroom
```
## MCP 集成
### 会话列表
```
GET /api/v1/session
```
## MCP
支持 MCP SSE 协议，启动 HTTP 服务后，通过 SSE Endpoint 访问服务：
Chatlog 支持 MCP (Model Context Protocol) SSE 协议，可与支持 MCP 的 AI 助手无缝集成。
启动 HTTP 服务后，通过 SSE Endpoint 访问服务：
```
GET /sse
```
提供了 4 个 tool 用于与 AI 助手集成：
- `chatlog`: 查询聊天记录
- `query_contact`: 查询联系人
- `query_chat_room`: 查询群聊
- `query_recent_chat`: 查询最近会话
### 快速集成
### 示例
Chatlog 可以与多种支持 MCP 的 AI 助手集成，包括：
以 [ChatWise](https://chatwise.app/) 工具为例，在 `设置 - 工具` 下新建工具，类型为 `sse`，ID 为 `chatlog`，URL 为 `http://127.0.0.1:5030/sse`，勾选自动执行工具，即可使用。
- **ChatWise**: 直接支持 SSE，在工具设置中添加 `http://127.0.0.1:5030/sse`
- **Cherry Studio**: 直接支持 SSE，在 MCP 服务器设置中添加 `http://127.0.0.1:5030/sse`
部分 AI 聊天工具暂时不支持 MCP SSE 协议，可以通过 [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) 工具转发请求，以 [Claude Desktop](https://claude.ai/download) 为例，在安装好 `mcp-proxy` 后，将 `mcp-proxy` 配置到 `Claude Desktop` 的 `config.json` 文件中，即可使用：
对于不直接支持 SSE 的客户端，可以使用 [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) 工具转发请求：
```json
{
"mcpServers": {
"mcp-proxy": {
"command": "/Users/sarv/.local/bin/mcp-proxy",
"args": [
"http://localhost:5030/sse"
],
"env": {}
}
},
"globalShortcut": ""
}
```
- **Claude Desktop**: 通过 mcp-proxy 支持，需要配置 `claude_desktop_config.json`
- **Monica Code**: 通过 mcp-proxy 支持，需要配置 VSCode 插件设置
### 详细集成指南
查看 [MCP 集成指南](docs/mcp.md) 获取各平台的详细配置步骤和注意事项。
## Prompt 示例
为了帮助大家更好地利用 Chatlog 与 AI 助手，我们整理了一些 prompt 示例。希望这些 prompt 可以启发大家更有效地查询和分析聊天记录，获取更精准的信息。
查看 [Prompt 指南](docs/prompt.md) 获取详细示例。
同时欢迎大家分享使用经验和 prompt！如果您有好的 prompt 示例或使用技巧，请通过 [Discussions](https://github.com/sjzar/chatlog/discussions) 进行分享，共同进步。
## 免责声明
⚠️ **重要提示：使用本项目前，请务必阅读并理解完整的 [免责声明](./DISCLAIMER.md)。**
本项目仅供学习、研究和个人合法使用，禁止用于任何非法目的或未授权访问他人数据。下载、安装或使用本工具即表示您同意遵守免责声明中的所有条款，并自行承担使用过程中的全部风险和法律责任。
### 摘要（请阅读完整免责声明）
- 仅限处理您自己合法拥有的聊天数据或已获授权的数据
- 严禁用于未经授权获取、查看或分析他人聊天记录
- 开发者不对使用本工具可能导致的任何损失承担责任
- 使用第三方 LLM 服务时，您应遵守这些服务的使用条款和隐私政策
**本项目完全免费开源，任何以本项目名义收费的行为均与本项目无关。**
## License
`chatlog` 是在 Apache-2.0 许可下的开源软件。
本项目基于 [Apache-2.0 许可证](./LICENSE) 开源。
## 隐私政策
本项目不收集任何用户数据。所有数据处理均在用户本地设备上进行。使用第三方服务时，请参阅相应服务的隐私政策。
## Thanks
- [@0xlane](https://github.com/0xlane) 的 [wechat-dump-rs](https://github.com/0xlane/wechat-dump-rs) 项目
- [@xaoyaoo](https://github.com/xaoyaoo) 的 [PyWxDump](https://github.com/xaoyaoo/PyWxDump) 项目
- [@git-jiadong](https://github.com/git-jiadong) 的 [go-lame](https://github.com/git-jiadong/go-lame) 和 [go-silk](https://github.com/git-jiadong/go-silk) 项目
- [Anthropic](https://www.anthropic.com/) 的 [MCP]((https://github.com/modelcontextprotocol) ) 协议
- 各个 Go 开源库的贡献者们