diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dc7a8d8
--- /dev/null
+++ b/README.md
@@ -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 接口