# chat

**Repository Path**: fakerlove/chat

## Basic Information

- **Project Name**: chat
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-21
- **Last Updated**: 2026-10-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 DeepSeek 与 Tulpa 技术的微信智能聊天与自动回复助手

本项目运行在 Windows 系统上，基于 Python 3.11 与 Conda 环境开发。项目实现了对微信指定联系人的实时消息免 Hook 读取、上下文结合、DeepSeek 大模型智能生成、系统托盘常驻以及自动/手动双模式秒级回复功能。

---

## 目录
1. [项目核心功能与亮点](#一项目核心功能与亮点)
2. [身份配置、密钥与回退机制（重要指引）](#二身份配置密钥与回退机制重要指引)
3. [参考开源项目 Tulpa 的实现原理深度剖析](#三参考开源项目-tulpa-的实现原理深度剖析)
4. [本项目的技术实现思路与架构](#四本项目的技术实现思路与架构)
5. [目录结构与模块说明](#五目录结构与模块说明)
6. [运行环境与使用说明](#六运行环境与使用说明)
7. [软件打包与发布指南](#七软件打包与发布指南)

---

## 一、项目核心功能与亮点

1. **专属身份背景与提示词智能生成**：
   - **预设虚拟身份**：默认预置一套虚拟身份 —— **小李**，男，23岁，大学本科（计算机专业），软件开发工程师，爱好打羽毛球、听音乐、看电影与数码科技。
   - **对方身份灵活切换**：支持自由指定回复对象角色（**朋友、女朋友/恋爱对象、同事、老师、妈妈/长辈、领导、相亲对象**或自定义身份）。
   - **提示词动态组装**：系统根据配置的本人背景、对方关系与当前语气，自动拼装生成高质量的 DeepSeek System Prompt。
2. **多风格语气策略与实时一键切换**：
   - 预设丰富语气：**智能综合**（情景自适应）、**暧昧甜蜜**（对象专属）、**开启话题**（主动破冰）、**换话题**（自然转移）、**结束话题**（礼貌收尾）、**幽默风趣**（接梗逗趣）、**关心体贴**（暖男陪伴）、**稳重礼貌**（同事/长辈/领导）、**撒娇卖萌**及**自定义指令**。
   - 悬浮卡片上直接集成语气下拉框与【🔄 换语气生成】按钮，随时随地按需切换不同风格候选。
3. **微信语音自动转写 (阿里云 DashScope Qwen-Audio ASR)**：
   - 对方发来语音消息时，系统自动提取微信本地 SILK 音频流并解码转换为标准 WAV 音频，调用阿里云 Qwen-Audio 语音转写大模型转换为文字，并结合上下文无缝回复。
   - 提供本地转写缓存机制，防止重复消耗 API 额度与产生延时。
4. **50 条多轮历史记录与视频消息智能识别**：
   - 上下文历史默认拉取 50 条（不足 50 条有多少取多少）。
   - **视频消息无感处理**：跳过视频底层文件解析，自动转换为 `[对方发送了一条视频]` 提示词，AI 会结合身份自然做出好奇询问、夸奖或稍后查看等真实回应。
5. **小图标设置面板与持久化存储**：
   - 点击右下角任务栏托盘小图标菜单，或点击右下角悬浮卡片右上角的小齿轮图标（`⚙️`），可随时弹出【个人身份与回复设置】窗口。
   - 支持自由编辑个人背景、对方好友、API Key、修改记录条数、预览生成的 System Prompt，并支持一键恢复默认虚拟身份配置。
6. **实时无感读取微信消息**：
   - 吸收 Tulpa 的底层数据库解密技术，直接免锁只读解密微信 4.x 本地加密数据库（`MSG0.db`、`session.db`、`contact.db` 等），不依赖破坏性 Hook，安全稳定。
   - 自动解压微信 4.x 最新的 `zstd` 压缩文本，保留完整对话记录。
7. **双模式自如切换**：
   - **✋ 手动模式（推荐）**：对方发来消息时，Windows 右下角优雅弹出悬浮回复卡片，提供 **3~5 个不同风格的高质量候选回复**，点击任一选项立即自动发送；也支持自定义修改后发送。
   - **🤖 自动模式**：对方发来消息后，大模型自动生成 **1~3 句** 拟真自然的短句，带有拟真打字间隔自动回复发送。
8. **Windows 系统托盘常驻与无干扰交互**：
   - 运行后在 Windows 任务栏右下角生成专属小图标（根据模式显示不同色彩与标识）。
   - 有新消息时通过 Windows 系统托盘气泡通知提醒。
   - 发送完成后自动恢复原先的工作窗口焦点，用户日常办公不被打扰。

---

## 二、身份配置、密钥与回退机制（重要指引）

为了保障您的个人隐私与 API 密钥安全，本项目全面解耦了身份配置与代码逻辑，并提供了多层次的配置与热更新回退机制：

### 1. 身份配置回退规则（核心三原则）
1. **未配置情况（默认使用虚拟身份）**：
   - 如果用户首次克隆或下载软件后**未配置**自己的身份信息（本地无 `config.json`），系统会自动使用默认的**虚拟身份（小李，23岁，软件开发工程师）**运行，开箱即用，无需繁琐设置。
2. **已配置情况（优先使用用户配置身份）**：
   - 用户可以参考根目录下的模板文件 `config.example.json` 与 `keys.example.json`，在本地创建 `config.json` 与 `keys.json` 文件，填入自己的真实身份背景（姓名、性别、年龄、学历、经历、爱好、微信好友及称呼），系统启动时将**优先读取并应用配置后的真实身份**。
3. **软件启动后用户修改（即时生效与持久化）**：
   - 软件运行过程中，用户点击右下角托盘图标菜单或悬浮卡片右上角小齿轮（`⚙️`）打开【设置面板】自由修改个人背景、对方信息、语气或 API Key。
   - 点击【保存并应用】后，系统会立即持久化保存至本地 `config.json`，并通过全局事件总线**实时热更新**生效，无需重启程序！
   - 点击【一键恢复默认虚拟身份】可随时重置回预设虚拟设定，且已配置好的 API Key 会被贴心保留。

### 2. API Key 与阿里云语音转写 Key 配置

本项目依赖两个主要云端 API 服务，您可以选择**文件配置**或**图形界面配置**：

| 服务名称 | 作用说明 | 获取渠道 | 配置字段 |
| :--- | :--- | :--- | :--- |
| **DeepSeek API Key** | 对话上下文理解与智能回复生成 | [DeepSeek 开放平台](https://platform.deepseek.com) | `chat_settings.api_key` 或 `keys.json` 的 `deepseek_api_key` |
| **阿里云 ASR API Key** | 微信语音消息自动转写文字 (Qwen-Audio) | [阿里云百炼 DashScope 控制台](https://dashscope.console.aliyun.com) | `asr_settings.api_key` 或 `keys.json` 的 `ali_asr_api_key` |

#### 配置方法 A：使用独立密钥文件 `keys.json`（推荐）
在项目根目录创建 `keys.json`（可参考 `keys.example.json`）：
```json
{
  "deepseek_api_key": "sk-your-deepseek-api-key",
  "ali_asr_api_key": "sk-your-ali-asr-api-key"
}
```

#### 配置方法 B：在 `config.json` 中配置
直接在本地 `config.json` 对应的 `chat_settings` 与 `asr_settings` 中填入：
```json
{
  "chat_settings": {
    "api_key": "sk-your-deepseek-api-key",
    "model": "deepseek-chat"
  },
  "asr_settings": {
    "enabled": true,
    "api_key": "sk-your-ali-asr-api-key",
    "model": "qwen-audio-3.0-asr-flash",
    "base_url": "https://maas.qianwenaiapi.com/api/v1"
  }
}
```

#### 配置方法 C：通过图形设置界面配置
启动程序后，右键托盘图标点击【⚙️ 个人身份与回复设置】，切换到【📜 聊天记录与高级】选项卡，在 **DeepSeek 大模型配置** 与 **阿里云语音转写配置** 输入框中填入您的 Key，点击【保存并应用配置】即可。

### 3. Git 忽略与隐私安全保护机制
本项目在根目录配备了严密的 `.gitignore` 规则：
- `config.json`（包含用户个人真实身份、工作单位、微信号等敏感配置）已加入忽略；
- `keys.json` 与 `*.local.json`（包含 API Key 与转写 Key）已加入忽略；
- `log/` 与 `*.log`、`voice_cache.json`（包含微信真实聊天记录与语音内容）已加入忽略。

**确保本地开箱直接使用，同时使用 Git 推送代码时绝对不会泄露个人隐私或 API 额度！**

---

## 三、参考开源项目 Tulpa 的实现原理深度剖析

我们在研读 [fumingyang2004/Tulpa](https://github.com/fumingyang2004/Tulpa) 的实现代码后，将其关于微信本地数据提取的核心思路总结如下：

### 1. 账号与数据目录自动探测
- **定位依据**：微信 4.x 将全局用户配置保存在 `%APPDATA%\Tencent\xwechat\config\*.ini`，并在注册表 `HKCU\Software\Tencent\Weixin` 记录数据路径。
- **目录规则**：用户数据库位于 `C:\Users\<User>\Documents\xwechat_files\<wxid_hash>\` 目录下。

### 2. 内存密钥只读提取（Memory Scanning）
- **核心机制**：微信启动登录后，WCDB 数据库引擎会在 `Weixin.exe` 进程内存中创建加密配置对象 `com.Tencent.WCDB.Config.Cipher`。
- **动态扫描**：Tulpa 借助 Windows API（`VirtualQueryEx`、`ReadProcessMemory`）扫描进程的可读写内存区域，定位带有特定的特征掩码（`CONFIG_XOR_MASK`）与 SQLCipher 4 密钥结构。
- **密钥验证**：提取出候选的 32 字节密钥后，使用 **PBKDF2-HMAC-SHA512**（256,000 次迭代，页面大小 4096 字节，Reserve 80 字节）解密数据库第一页并校验 HMAC。验证成功后缓存密钥，无需重复扫描。

### 3. WAL 增量合并与只读副本解密
- **实时性问题**：微信运行时新产生的聊天记录优先写入 `-wal`（预写日志文件），直接读取主库可能缺失最新消息。
- **页级缓存与合并**：Tulpa 实现了轻量级 WAL 帧解析（`_merge_wal`），监测 `MSG.db` 和 `MSG.db-wal` 的修改时间与尺寸变动，将 WAL 中的更新帧解密后应用到临时只读副本中，确保 100% 捕获最新收到的消息。

### 4. 微信 4.x zstandard 压缩正文解析
- 微信 4.x 为了节省空间，大量长文本和卡片内容采用 `zstd` 算法压缩存储，头部带有固定魔数 `0x28 0xb5 0x2f 0xfd`。
- Tulpa 集成 `zstandard` 库动态解压，防止聊天记录退化为 `[文本]` 占位符。

### 5. Tulpa 的局限与本项目的突破
- **Tulpa 原版局限**：Tulpa 定位为只读数据检索层与 MCP 服务，正如其 README 所述：“微信支持读取、回复草稿与复制，不能发送”。
- **本项目突破**：本项目完整继承了 Tulpa **免 Hook、安全高效的底层只读数据库解密与监听引擎**，同时在发送端创新性地结合了 **Windows 原生 UI 自动化与快捷键交互技术**，打通了“**读取 ➔ 理解 ➔ 生成 ➔ 发送**”的完整闭环！

---

## 四、本项目的技术实现思路与架构

```
┌──────────────────────────────────────────────────────────────────┐
│                          微信电脑版客户端                          │
└────────┬─────────────────────────────────────────────────▲───────┘
         │ 1. 内存提取密钥 / 解密 SQLite WAL                │ 5. 模拟粘贴并回车发送
         ▼                                                 │
┌──────────────────┐                              ┌────────┴─────────┐
│   wechat_db.py   │                              │ wechat_sender.py │
│ (微信4.x解密与监听)│                              │ (Win32发送与对齐) │
└────────┬─────────┘                              └────────▲─────────┘
         │ 2. 捕获监控目标新消息                            │ 4. 自动/手动回复触发
         ▼                                                 │
┌──────────────────┐       3. 请求大模型          ┌────────┴─────────┐
│     main.py      ├─────────────────────────────►│   tray_app.py    │
│    (主调度服务)   │                              │ (托盘与右下角卡片) │
└────────▲─────────┘                              └──────────────────┘
         │
         ▼ 3. 携带多轮对话上下文与角色设定
┌──────────────────┐
│deepseek_client.py│
│ (DeepSeek Chat)  │
└──────────────────┘
```

1. **后台消息监听器 (`wechat_db.py` & `main.py`)**：
   - 建立针对监控联系人的高精度水位线 `watermark = max(sort_seq)`。
   - 严格识别微信 4.x 消息方向（`origin_source == 1` 或 `status == 2` 为我方发言；`origin_source == 2` 为对方发言），彻底杜绝自己回复自己导致的自触发循环。
2. **AI 智能生成 (`deepseek_client.py`)**：
   - **手动模式**：向 DeepSeek API 提交历史记录，要求返回 3~5 个口语化、包含不同风格倾向（积极、幽默、客气、反问等）的纯文本候选数组。
   - **自动模式**：要求 DeepSeek 生成 1~3 句连贯真实的朋友式回复，以 JSON 格式输出。
3. **交互界面与系统托盘 (`tray_app.py`)**：
   - 基于 PyQt5 打造无边框现代圆角阴影悬浮卡片。
   - 手动模式下：在屏幕右下角弹出，展示对方发言及 3~5 个候选按钮，用户鼠标点击任意一项立即触发发送并自动收起。
   - 采用多线程异步发送机制，发送过程不阻塞 PyQt5 GUI 事件循环，避免 Windows 报“未响应”。
   - 托盘菜单支持随时切换“自动模式 / 手动模式”。
4. **安全无感发送 (`wechat_sender.py`)**：
   - 针对当前运行的微信 4.x 窗口（`Qt51514QWindowIcon`），使用 Windows API 安全置顶，支持窗口最小化或隐藏到托盘时自动唤醒还原（`SW_RESTORE`）并校验坐标防呆。
   - 快速切入指定好友聊天界面并聚焦输入框，注入文本后模拟发送。
   - 发送完成后自动切回用户之前操作的软件窗口，不影响日常办公。

---

## 五、目录结构与模块说明

```
chat/
│
├── main.py              # 主调度服务：集成监听、AI调度与托盘主事件循环
├── config_manager.py    # 配置中心：管理虚拟身份背景、对方角色、回复语气与 System Prompt 动态生成
├── settings_dialog.py   # 设置界面：可视化修改本人背景、对方身份、语气策略、Key与提示词预览
├── wechat_db.py         # 微信底层模块：内存解密、数据库读取、WAL合并、方向判定与消息解析
├── wechat_sender.py     # 微信发送模块：Win32 API窗口定位、最小化安全唤醒还原、文本注入与发送
├── deepseek_client.py   # DeepSeek 客户端：多轮上下文角色封装与候选/自动句子生成（支持动态语气与视频提示词）
├── ali_asr.py           # 阿里云语音转写模块：微信 SILK 音频提取、解码与 Qwen-Audio ASR 转写
├── tray_app.py          # 托盘与界面模块：系统托盘、气泡通知、快捷语气切换与设置图标入口
├── logger.py            # 全局统一日志模块：控制台实时输出与 log/wechat_reply.log 轮转记录
├── app.ico              # 应用程序图标文件
│
├── config.example.json  # 配置模板文件（内置小李虚拟身份配置，纳入 Git 管理）
├── keys.example.json    # 密钥模板文件（占位示例，纳入 Git 管理）
├── config.json          # [本地私有] 本地实际配置文件（含个人设定，已被 .gitignore 忽略）
├── keys.json            # [本地私有] 本地实际 API 密钥文件（已被 .gitignore 忽略）
│
├── script/              # 软件打包与构建脚本目录
│   ├── build_exe.py     # PyInstaller 自动打包 Python 主脚本
│   └── build.bat        # Windows 一键打包批处理脚本
├── build_exe.py         # 根目录打包快捷调用脚本
├── wechat_assistant.spec# PyInstaller 规格文件
│
├── log/                 # 运行与错误日志目录（自动忽略提交）
│   └── wechat_reply.log
├── start.bat            # Windows 一键启动脚本
├── .gitignore           # Git 忽略配置文件（全面保护隐私与密钥安全）
└── readme.md            # 项目完整文档与技术实现剖析
```

---

## 六、运行环境与使用说明

### 1. 运行环境配置
- **操作系统**：Windows 10 / Windows 11 (x64)
- **微信客户端**：已启动且已登录电脑版微信（支持微信 4.x 最新版本）
- **Python 环境**：Python 3.10+ / 3.11+
- **核心依赖库**：`PyQt5`、`cryptography`、`zstandard`、`requests`、`pywin32`、`pyperclip`、`pilk`

### 2. 启动方式
双击运行根目录下的 `start.bat`，或在命令行中运行：
```powershell
python main.py
```

### 3. 操作体验
1. 启动后，Windows 任务栏右下角托盘会出现绿色小图标。
2. 托盘弹出系统气泡：`微信智能助手已就绪`。
3. **当监控好友发来消息时**：
   - **手动模式**：屏幕右下角平滑弹出卡片，展示对方发的消息和 3~5 个生成的回复选项，点击任意选项即可秒级自动发回微信！
   - **自动模式**：右键点击托盘图标切换为【自动回复模式】，对方发来消息后，助手将在 1~2 秒内自动回复 1~3 句话。
4. 右键托盘图标可随时进行模式切换、手动触发测试、打开设置面板或退出程序。

---

## 七、软件打包与发布指南

项目所有打包构建相关的脚本均已归档于 `script/` 目录下：

### 1. 一键打包步骤
- **方式一（双击批处理）**：直接双击运行 `script\build.bat`。
- **方式二（命令行执行）**：
  ```cmd
  python script/build_exe.py
  ```

### 2. 打包构建产物
打包完成后，产物输出至根目录下的 `dist/` 文件夹：
- `dist/微信智能回复助手.exe`（中文名称可执行程序）
- `dist/wechat_assistant.exe`（英文名称可执行程序）
- `dist/config.example.json`（分发配置模板）
- `dist/keys.example.json`（分发密钥模板）

打包生成的程序为单文件绿色独立版本，无需在目标电脑上配置 Python 环境即可开箱运行。