docs: 添加项目 README
包含功能介绍、技术栈、目录结构、快速开始、环境变量配置、工作原理说明。 🤖 Generated with [Qoder][https://qoder.com]
This commit is contained in:
figmar
177
README.md
Normal file
177
README.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# 识流 AI 助手
|
||||
|
||||
基于截图 + OCR 的微信自动回复机器人，支持关键词规则匹配和 AI 智能回复。
|
||||
|
||||
> **仅支持 Windows**，需要桌面端微信同时运行。
|
||||
|
||||
---
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **自动监听未读消息**：通过截图 + OCR 识别微信会话列表中的未读消息
|
||||
- **关键词规则回复**：支持「包含匹配」和「精确匹配」两种规则类型
|
||||
- **AI 智能回复**：支持接入 OpenAI / DeepSeek / Dify，无规则命中时自动调用 AI 回复
|
||||
- **消息记录**：所有收发消息入库存储，支持查询历史记录
|
||||
- **管理界面**：内置 Web 控制台，可管理规则、查看消息、查看运行日志
|
||||
- **可视化日志**：结构化日志系统，支持按模块、级别、关键词筛选
|
||||
|
||||
---
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层次 | 技术 |
|
||||
|------|------|
|
||||
| 桌面 GUI | PySide6 (Qt6) + QWebEngineView |
|
||||
| 后端服务 | Python / Flask |
|
||||
| 前端界面 | Vue 3 + Vite |
|
||||
| 数据库 | SQLite（本地存储） |
|
||||
| OCR 引擎 | RapidOCR + ONNX Runtime（PP-OCRv4） |
|
||||
| AI 接入 | OpenAI / DeepSeek / Dify（可配置） |
|
||||
| 桌面打包 | Tauri（备选方案） |
|
||||
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
├── main.py # 桌面 GUI 启动入口
|
||||
├── backend_main.py # Flask 后端启动入口
|
||||
├── requirements.txt # Python 依赖
|
||||
├── app/
|
||||
│ ├── application/ # 应用层：配置、Bot 控制器
|
||||
│ ├── infrastructure/
|
||||
│ │ ├── backend.py # Flask 服务启动
|
||||
│ │ ├── router/ # API 路由（rules / messages / bot）
|
||||
│ │ ├── service/
|
||||
│ │ │ ├── backend/ # AI 调用、数据库、配置读取
|
||||
│ │ │ ├── wechat/ # 截图、OCR、会话分析、聊天快照
|
||||
│ │ │ └── logging/ # 结构化日志服务
|
||||
│ │ └── wechat_multi_chat_bot.py # Bot 主循环
|
||||
│ ├── presentation/ # GUI 主窗口、加载窗口
|
||||
│ └── resources/
|
||||
│ └── ocr_models/ # OCR 模型文件（需单独下载）
|
||||
├── frontend/
|
||||
│ ├── src/ # Vue 3 前端源码
|
||||
│ └── dist/ # 构建产物（随代码附带）
|
||||
├── vendor/
|
||||
│ └── paddleocr/ # PaddleOCR 模型（需单独下载）
|
||||
└── legacy/ # 旧版 PHP 实现（已弃用，仅供参考）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
- Windows 10 / 11（64位）
|
||||
- Python 3.11+
|
||||
- 桌面端微信（已登录）
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
# 创建虚拟环境
|
||||
python -m venv .venv
|
||||
.venv\Scripts\activate
|
||||
|
||||
# 安装依赖
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 配置环境变量
|
||||
|
||||
在项目根目录创建 `.env` 文件：
|
||||
|
||||
```env
|
||||
# 服务地址（默认即可）
|
||||
APP_HOST=127.0.0.1
|
||||
APP_PORT=5000
|
||||
|
||||
# AI 提供商：openai / deepseek / dify / mock
|
||||
AI_PROVIDER=deepseek
|
||||
|
||||
# DeepSeek
|
||||
DEEPSEEK_API_KEY=your_api_key
|
||||
DEEPSEEK_API_BASE=https://api.deepseek.com/v1
|
||||
DEEPSEEK_MODEL=deepseek-chat
|
||||
|
||||
# OpenAI（使用 openai 时填写）
|
||||
# OPENAI_API_KEY=your_api_key
|
||||
# OPENAI_API_BASE=https://api.openai.com/v1
|
||||
# OPENAI_MODEL=gpt-4o-mini
|
||||
|
||||
# Dify（使用 dify 时填写）
|
||||
# DIFY_API_KEY=your_api_key
|
||||
# DIFY_API_BASE=https://api.dify.ai/v1
|
||||
# DIFY_USER=user
|
||||
|
||||
# 微信窗口位置（可根据实际屏幕分辨率调整）
|
||||
WECHAT_WINDOW_TARGET_WIDTH=1080
|
||||
WECHAT_WINDOW_TARGET_HEIGHT=820
|
||||
WECHAT_WINDOW_TARGET_LEFT=120
|
||||
WECHAT_WINDOW_TARGET_TOP=80
|
||||
```
|
||||
|
||||
### 下载 OCR 模型
|
||||
|
||||
OCR 模型文件体积较大，不纳入版本控制，需手动放置：
|
||||
|
||||
```
|
||||
app/resources/ocr_models/
|
||||
├── ch_PP-OCRv4_det.onnx # 文字检测模型
|
||||
├── ch_PP-OCRv4_rec.onnx # 文字识别模型
|
||||
└── ch_ppocr_mobile_v2.0_cls.onnx # 方向分类模型
|
||||
```
|
||||
|
||||
可从 [PaddleOCR 官方](https://github.com/PaddlePaddle/PaddleOCR) 或项目发布页下载。
|
||||
|
||||
### 启动应用
|
||||
|
||||
```bash
|
||||
# 启动桌面 GUI（自动拉起后端服务）
|
||||
python main.py
|
||||
|
||||
# 或单独启动后端服务
|
||||
python backend_main.py
|
||||
```
|
||||
|
||||
启动后浏览器访问 `http://127.0.0.1:5000` 可打开管理控制台。
|
||||
|
||||
---
|
||||
|
||||
## 管理控制台
|
||||
|
||||
| 页面 | 功能 |
|
||||
|------|------|
|
||||
| **控制面板** | 启动/停止监听、开关自动回复、开关全自动 AI 回复 |
|
||||
| **回复规则** | 新增/编辑/删除关键词规则，支持包含/精确两种匹配 |
|
||||
| **消息记录** | 查看所有收发消息，含 OCR 置信度、回复策略等信息 |
|
||||
| **运行日志** | 查看结构化运行日志，支持按模块和级别过滤 |
|
||||
|
||||
---
|
||||
|
||||
## 工作原理
|
||||
|
||||
```
|
||||
Bot 主循环
|
||||
↓ 每隔 3 秒
|
||||
截图微信会话列表 → OCR 识别 → 找到未读会话
|
||||
↓ 点击会话
|
||||
截图聊天区域 → 提取最新一条消息文本（对方发送）
|
||||
↓ POST /api/messages/receive
|
||||
关键词规则匹配
|
||||
├─ 命中 → 直接回复规则内容
|
||||
└─ 未命中 + 全自动开启 → 调用 AI 生成回复
|
||||
↓ should_reply = true
|
||||
pyautogui 模拟输入 → 剪贴板粘贴 → 回车发送
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 运行期间请勿手动操作微信窗口，避免与 Bot 产生冲突
|
||||
- 建议在专用电脑或虚拟机上运行，避免影响日常使用
|
||||
- 数据库文件存储在 `%LOCALAPPDATA%\AiShiliu\ai_shiliu.sqlite3`
|
||||
- `AI_PROVIDER=mock` 可用于本地测试，不调用真实 AI 接口
|
||||
Reference in New Issue
Block a user