# WeChatRobot 项目需求规格说明书

## 文档信息

| 文档名称 | WeChatRobot 项目需求规格说明书 |
| :------ | :--------------------------- |
| 版本号   | V1.0                        |
| 状态     | 初稿                        |
| 创建日期 | 2024年5月                   |

## 目录

1. [项目概述](#1-项目概述)
   1. [项目背景](#11-项目背景)
   2. [项目目标](#12-项目目标)
   3. [适用范围](#13-适用范围)

2. [系统架构](#2-系统架构)
   1. [总体架构](#21-总体架构)
   2. [核心组件](#22-核心组件)
   3. [技术栈](#23-技术栈)
   4. [系统依赖](#24-系统依赖)

3. [功能需求](#3-功能需求)
   1. [基础功能](#31-基础功能)
   2. [特色功能](#32-特色功能)
   3. [管理功能](#33-管理功能)

4. [命令系统](#4-命令系统)
   1. [通用命令](#41-通用命令)
   2. [游戏任务命令](#42-游戏任务命令)
   3. [积分交易命令](#43-积分交易命令)
   4. [管理命令](#44-管理命令)

5. [数据模型](#5-数据模型)
   1. [数据库设计](#51-数据库设计)
   2. [缓存设计](#52-缓存设计)

6. [非功能需求](#6-非功能需求)
   1. [性能需求](#61-性能需求)
   2. [安全需求](#62-安全需求)
   3. [可扩展性](#63-可扩展性)
   4. [可靠性](#64-可靠性)

7. [部署要求](#7-部署要求)
   1. [环境依赖](#71-环境依赖)
   2. [第三方服务](#72-第三方服务)
   3. [部署流程](#73-部署流程)

8. [未来扩展计划](#8-未来扩展计划)

9. [附录](#9-附录)
   1. [术语表](#91-术语表)
   2. [参考文档](#92-参考文档)

## 1. 项目概述

### 1.1 项目背景

随着微信在社交和工作场景中的广泛应用，用户对于微信自动化管理、智能回复、群聊管理等需求日益增长。WeChatRobot 项目旨在满足这些需求，提供一个功能丰富、易于扩展的微信机器人解决方案，帮助用户提高沟通效率、增强群聊体验、实现自动化管理。

### 1.2 项目目标

1. 开发一个基于 Python 的微信机器人系统，实现微信消息的自动化处理
2. 提供丰富的功能模块，包括但不限于：AI 对话、群聊管理、游戏任务、积分系统等
3. 支持多种 AI 模型接入，提供智能对话能力
4. 实现群聊内容的自动化总结和分析
5. 提供用户友好的管理界面，便于配置和监控
6. 设计可扩展的架构，便于后续功能扩展

### 1.3 适用范围

本系统适用于以下场景：
- 个人用户：提升微信使用体验，自动化处理日常消息
- 群组管理员：辅助管理微信群，提高群聊活跃度
- 企业用户：用于客户服务、内部沟通自动化等场景
- 开发者：作为微信自动化的基础框架，进行二次开发

## 2. 系统架构

### 2.1 总体架构

WeChatRobot 采用模块化设计，主要由以下几个部分组成：
- 核心引擎：负责与微信客户端交互，处理消息收发
- 功能模块：提供各种具体功能的实现
- 数据存储：管理系统数据和状态
- 管理界面：提供配置和监控功能

系统架构图如下：

```
+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
|  微信客户端       |<--->|  WeChatRobot     |<--->|  数据存储        |
|  (wcferry)       |     |  核心引擎         |     |  (MySQL/Redis)   |
|                  |     |                  |     |                  |
+------------------+     +--------+---------+     +------------------+
                                  |
                                  |
                         +--------v---------+
                         |                  |
                         |  功能模块         |
                         |                  |
                         +--------+---------+
                                  |
                                  |
                         +--------v---------+
                         |                  |
                         |  Web管理界面      |
                         |  (Flask)         |
                         |                  |
                         +------------------+
```

### 2.2 核心组件

1. **主程序模块**
   - 负责系统初始化和启动
   - 协调各功能模块的工作
   - 处理系统级事件

2. **机器人核心**
   - 与微信客户端交互
   - 消息分发与处理
   - 命令解析与执行

3. **功能模块**
   - AI 对话模块：集成多种 AI 模型
   - 群聊管理模块：处理群成员变动、自动欢迎等
   - 游戏任务模块：实现百科问答游戏
   - 积分系统模块：管理用户积分和交易
   - 签到模块：实现每日签到功能
   - 消息总结模块：自动总结群聊内容

4. **数据存储层**
   - MySQL 数据库：存储持久化数据
   - Redis 缓存：存储临时数据和状态

5. **Web 界面**
   - 基于 Flask 的管理界面
   - 提供配置和监控功能

### 2.3 技术栈

1. **编程语言**
   - Python 3.x

2. **框架与库**
   - wcferry：微信客户端接口
   - Flask：Web 框架
   - MySQL Connector：数据库连接
   - Redis：缓存服务
   - Requests：HTTP 客户端
   - Schedule：定时任务
   - Pandas：数据处理
   - Jupyter Client：代码执行

3. **AI 接口**
   - OpenAI API
   - 豆包 API (Doubao)
   - TigerBot API
   - 智谱 API (ZhipuAI)
   - Google Generative AI

4. **前端技术**
   - HTML/CSS/JavaScript
   - Bootstrap（可选）

### 2.4 系统依赖

详细的系统依赖列表（基于 requirements.txt）：

- chinese_calendar~=1.10.0：中国节假日判断
- lxml~=5.3.0：XML 处理
- openai>1.0.0：OpenAI API 接口
- pandas~=2.2.3：数据处理
- pyyaml~=6.0.2：YAML 配置文件处理
- requests~=2.32.3：HTTP 请求
- schedule~=1.2.2：定时任务
- wcferry==39.2.*：微信客户端接口
- redis~=5.2.1：Redis 缓存
- PyMySQL~=1.1.1：MySQL 数据库连接
- Flask~=3.1.0：Web 框架
- mysql-connector-python~=9.2.0：MySQL 连接器
- pytz~=2025.1：时区处理
- 其他辅助库（详见 requirements.txt）

## 3. 功能需求

### 3.1 基础功能

#### 3.1.1 消息处理

**功能描述**：
系统能够接收、处理和响应各类微信消息，包括个人消息和群聊消息。

**详细需求**：
1. **消息接收**
   - 接收文本消息、图片消息、视频消息、语音消息等多种类型
   - 支持群聊和私聊消息的区分处理

2. **消息存储**
   - 将消息存储到数据库中，包含以下信息：
     - 消息ID
     - 群ID（如适用）
     - 发送者ID
     - 消息内容
     - 消息类型
     - 时间戳
     - 附件URL（如适用）
     - 消息XML（如适用）
     - 缩略图（如适用）

3. **消息过滤**
   - 过滤无效或垃圾消息
   - 支持关键词过滤
   - 支持特定消息类型的过滤

4. **消息响应**
   - 根据预设规则自动响应特定消息
   - 支持命令触发的响应
   - 支持AI模型生成的智能响应

#### 3.1.2 群聊管理

**功能描述**：
系统能够监控和管理微信群聊，包括成员变动、自动欢迎等功能。

**详细需求**：
1. **成员变动监控**
   - 检测群成员加入和退出事件
   - 记录成员变动历史
   - 提供成员变动通知

2. **自动欢迎**
   - 当新成员加入群聊时，自动发送欢迎消息
   - 支持自定义欢迎消息模板
   - 支持群组特定的欢迎设置

3. **群聊邀请管理**
   - 支持通过命令添加群聊
   - 管理群聊邀请关系
   - 提供群聊列表查询功能

4. **群成员信息管理**
   - 缓存群成员信息
   - 提供群成员信息查询功能
   - 支持群成员昵称与ID的映射

#### 3.1.3 AI 对话

**功能描述**：
系统集成多种AI模型，提供智能对话能力。

**详细需求**：
1. **多模型支持**
   - 支持豆包(Doubao)模型
   - 支持TigerBot模型
   - 支持ChatGLM模型
   - 支持OpenAI模型
   - 支持其他可扩展的AI模型

2. **上下文对话**
   - 维护对话历史
   - 支持上下文相关的回复
   - 限制对话历史长度，避免token过多

3. **自定义系统提示词**
   - 支持为不同AI模型设置系统提示词
   - 支持根据不同场景切换提示词

4. **对话统计**
   - 记录token使用情况
   - 提供对话性能统计
   - 支持对话质量评估

### 3.2 特色功能

#### 3.2.1 群聊总结

**功能描述**：
系统能够自动总结群聊内容，识别热门话题和活跃成员。

**详细需求**：
1. **内容总结**
   - 定期（如每日）总结群聊内容
   - 提取关键话题和重要信息
   - 生成结构化的总结报告

2. **话题识别**
   - 自动识别群聊中的热门话题
   - 对话题进行分类和评分
   - 提供话题参与度分析

3. **成员活跃度分析**
   - 识别最活跃的群成员
   - 统计成员发言频率和质量
   - 生成"今日MVP"等趣味性内容

4. **总结展示**
   - 以轻松幽默的风格展示总结
   - 融入网络流行语和Emoji
   - 提供数据概览、话题概览、贡献者识别等内容

#### 3.2.2 游戏任务系统

**功能描述**：
系统提供百科问答游戏功能，支持任务分配、答案验证和积分奖励。

**详细需求**：
1. **任务管理**
   - 支持随机分配任务
   - 维护任务状态（待完成、已完成）
   - 提供任务查询功能

2. **答案验证**
   - 验证用户提交的答案
   - 支持部分正确的评分
   - 提供答案反馈和提示

3. **积分系统**
   - 根据答案正确性奖励积分
   - 支持积分扣除（如答错扣分）
   - 维护用户积分余额

4. **排行榜**
   - 提供群内用户积分排行
   - 支持定期（如每周）排行榜更新
   - 展示排行榜前N名用户

#### 3.2.3 积分交易系统

**功能描述**：
系统支持用户间的积分转账和交易功能。

**详细需求**：
1. **积分转账**
   - 支持用户间积分转移
   - 验证转账合法性（如余额检查）
   - 记录转账历史

2. **积分查询**
   - 提供用户积分余额查询
   - 支持积分历史记录查询
   - 展示积分来源和去向

3. **积分奖惩**
   - 支持管理员奖励或扣除用户积分
   - 提供积分奖惩理由记录
   - 支持批量积分操作

#### 3.2.4 签到系统

**功能描述**：
系统提供每日签到功能，支持签到统计和奖励机制。

**详细需求**：
1. **每日签到**
   - 支持用户每日签到
   - 限制每日签到次数（每人每天一次）
   - 自动重置每日签到计数

2. **签到奖励**
   - 签到成功后给予积分奖励
   - 支持连续签到额外奖励
   - 支持特殊日期（如节假日）额外奖励

3. **签到统计**
   - 记录用户签到历史
   - 统计连续签到天数
   - 提供签到排行榜

4. **时区支持**
   - 根据配置的时区判断日期变更
   - 支持不同地区用户的签到需求

#### 3.2.5 定时提醒

**功能描述**：
系统能够根据预设规则发送定时提醒消息。

**详细需求**：
1. **工作报告提醒**
   - 支持日报、周报、月报提醒
   - 自动识别工作日和非工作日
   - 在适当时间发送提醒消息

2. **自定义提醒**
   - 支持用户设置自定义提醒
   - 提供提醒时间和内容的配置
   - 支持重复提醒设置

3. **节假日识别**
   - 集成中国节假日日历
   - 在节假日发送特定消息
   - 支持节假日前的工作安排提醒

### 3.3 管理功能

#### 3.3.1 Web 管理界面

**功能描述**：
系统提供基于 Web 的管理界面，便于配置和监控。

**详细需求**：
1. **消息管理**
   - 查看历史消息记录
   - 支持消息搜索和过滤
   - 提供消息统计和分析

2. **群组配置**
   - 管理群组列表
   - 配置群组特定的功能设置
   - 监控群组活跃度

3. **功能开关**
   - 提供全局功能开关
   - 支持群组级别的功能开关
   - 记录功能状态变更历史

4. **系统监控**
   - 监控系统运行状态
   - 提供资源使用情况统计
   - 支持异常情况告警

#### 3.3.2 权限管理

**功能描述**：
系统提供多级权限管理，控制不同用户对功能的访问权限。

**详细需求**：
1. **权限级别**
   - 系统管理员：拥有所有权限
   - 群组管理员：拥有特定群组的管理权限
   - 普通用户：拥有基本功能使用权限

2. **功能权限**
   - 控制特定功能的使用权限
   - 支持按群组设置功能权限
   - 提供权限变更审计

3. **用户管理**
   - 管理用户账号和权限
   - 支持用户封禁和解封
   - 记录用户操作日志

## 4. 命令系统

### 4.1 通用命令

**功能描述**：
系统提供一系列通用命令，用于基本功能的触发和控制。

**详细需求**：
1. **帮助命令**
   - `/help`：显示帮助信息
   - `/menu`：显示功能菜单

2. **功能开关命令**
   - 启用/禁用特定功能的命令
   - 查询功能状态的命令

3. **系统信息命令**
   - 查询系统状态
   - 查询版本信息

### 4.2 游戏任务命令

**功能描述**：
系统提供一系列命令，用于游戏任务系统的操作。

**详细命令列表**：
1. `/s`：加入游戏（可选）
   - 功能：显式加入游戏系统
   - 响应：确认加入的消息

2. `/ts`：查看活跃任务
   - 功能：显示当前活跃的任务列表
   - 响应：活跃任务的详细信息

3. `/l`：列出未完成任务
   - 功能：显示所有未完成的任务
   - 响应：未完成任务的列表

4. `/a [任务ID] [答案]`：提交答案
   - 功能：提交特定任务的答案
   - 参数：任务ID和答案内容
   - 响应：答案验证结果和积分变更

5. `/r`：查看排行榜
   - 功能：显示积分排行榜
   - 响应：排行榜信息

6. `/ag`：手动添加群聊（可选）
   - 功能：将当前群聊添加到游戏系统
   - 响应：添加结果确认

7. `/t`：获取新任务
   - 功能：获取一个随机任务
   - 响应：新任务的详细信息
   - 限制：仅在特定时间段（9:00-22:59）可用

### 4.3 积分交易命令

**功能描述**：
系统提供积分交易相关的命令，支持用户间的积分转移。

**详细命令列表**：
1. `积分转账 积分数 @用户`：转账积分
   - 功能：将指定数量的积分转给目标用户
   - 参数：积分数量和目标用户
   - 响应：转账结果确认

2. 命令别名：
   - `积分交易`
   - `积分赠送`
   - `积分转移`
   - `转账积分`
   - `赠送积分`
   - `转移积分`
   - `送积分`
   - `积分送人`
   - `送人积分`
   - `积分赠予`
   - `赠予`

### 4.4 管理命令

**功能描述**：
系统提供一系列管理命令，用于系统配置和管理。

**详细命令列表**：
1. **群组管理命令**
   - 添加/删除群组
   - 配置群组特定设置

2. **功能配置命令**
   - 启用/禁用特定功能
   - 配置功能参数

3. **用户管理命令**
   - 添加/删除用户
   - 设置用户权限

## 5. 数据模型

### 5.1 数据库设计

**功能描述**：
系统使用 MySQL 数据库存储持久化数据。

**主要数据表**：
1. **消息表（messages）**
   - 字段：
     - id：消息ID
     - group_id：群ID
     - timestamp：时间戳
     - sender：发送者ID
     - content：消息内容
     - message_type：消息类型
     - attachment_url：附件URL
     - message_id：微信消息ID
     - message_xml：消息XML
     - message_thumb：消息缩略图

2. **用户表（t_encyclopedia_players）**
   - 字段：
     - player_id：用户ID
     - group_id：群ID
     - player_name：用户名称
     - points：积分
     - join_time：加入时间

3. **任务表（t_encyclopedia_active_tasks）**
   - 字段：
     - active_task_id：任务ID
     - group_id：群ID
     - question：问题
     - answer：答案
     - score：分数
     - holder_id：持有者ID
     - status：状态（pending/completed）

4. **任务历史表（t_encyclopedia_task_history）**
   - 字段：
     - id：记录ID
     - group_id：群ID
     - active_task_id：任务ID
     - player_id：用户ID
     - answer：提交的答案
     - is_correct：是否正确
     - points_earned：获得的积分

5. **签到表**
   - 字段：
     - id：记录ID
     - user_id：用户ID
     - group_id：群ID
     - sign_time：签到时间
     - continuous_days：连续签到天数

### 5.2 缓存设计

**功能描述**：
系统使用 Redis 缓存存储临时数据和状态。

**主要缓存数据**：
1. **群成员信息**
   - 键格式：`group:group_members:{group_id}`
   - 值类型：哈希表（wxid -> nickname）
   - 用途：缓存群成员信息，避免频繁查询

2. **群成员数量**
   - 键格式：`group:group_member_count:{group_id}`
   - 值类型：字符串（数字）
   - 用途：记录群成员数量

3. **签到记录**
   - 键格式：`group:sign_in:{group_id}:{user_id}`
   - 值类型：字符串（时间戳）
   - 用途：记录用户签到状态

4. **最后总结时间**
   - 键格式：`{group_id}:summary_time`
   - 值类型：字符串（时间戳）
   - 用途：记录群聊最后总结的时间

5. **对话历史**
   - 内存缓存（非Redis）
   - 结构：字典（wxid -> 消息列表）
   - 用途：维护AI对话的上下文

## 6. 非功能需求

### 6.1 性能需求

**功能描述**：
系统需要满足一定的性能要求，确保良好的用户体验。

**详细需求**：
1. **响应时间**
   - 普通命令响应时间不超过1秒
   - AI生成内容响应时间不超过10秒
   - 数据库查询响应时间不超过2秒

2. **并发处理**
   - 支持多个群组同时活跃
   - 支持多用户并发请求
   - 避免资源竞争和死锁

3. **资源使用**
   - CPU使用率平均不超过50%
   - 内存使用合理，避免内存泄漏
   - 数据库连接池管理，避免连接耗尽

### 6.2 安全需求

**功能描述**：
系统需要确保数据安全和用户隐私保护。

**详细需求**：
1. **数据安全**
   - 敏感配置信息加密存储
   - API密钥安全管理
   - 数据库访问权限控制

2. **用户隐私**
   - 遵循最小权限原则收集用户信息
   - 不存储不必要的敏感信息
   - 提供隐私政策说明

3. **防滥用措施**
   - 命令频率限制
   - 异常行为检测
   - 防止恶意使用系统资源

### 6.3 可扩展性

**功能描述**：
系统设计需要考虑未来的扩展需求。

**详细需求**：
1. **模块化设计**
   - 功能模块之间低耦合
   - 提供清晰的接口定义
   - 支持插件式扩展

2. **配置灵活性**
   - 支持通过配置文件调整系统行为
   - 避免硬编码配置项
   - 支持运行时配置更新

3. **AI模型扩展**
   - 支持新AI模型的便捷接入
   - 统一的AI接口抽象
   - 模型切换不影响系统稳定性

### 6.4 可靠性

**功能描述**：
系统需要具备良好的可靠性和稳定性。

**详细需求**：
1. **错误处理**
   - 全面的异常捕获和处理
   - 避免单点故障导致系统崩溃
   - 提供友好的错误提示

2. **日志系统**
   - 详细的操作日志记录
   - 错误日志分级管理
   - 支持日志查询和分析

3. **自动恢复**
   - 系统异常时自动重试
   - 关键服务自动重启
   - 数据一致性保障

## 7. 部署要求

### 7.1 环境依赖

**功能描述**：
系统运行需要特定的环境依赖。

**详细需求**：
1. **操作系统**
   - Windows 10/11（推荐）
   - 支持其他操作系统（可选）

2. **Python环境**
   - Python 3.8+
   - 虚拟环境管理（推荐）

3. **数据库环境**
   - MySQL 5.7+
   - Redis 5.0+

4. **网络环境**
   - 稳定的互联网连接
   - 支持HTTPS请求

### 7.2 第三方服务

**功能描述**：
系统依赖一些第三方服务和API。

**详细需求**：
1. **AI服务**
   - 豆包API访问权限
   - TigerBot API访问权限
   - OpenAI API访问权限（可选）
   - 其他AI服务提供商的API

2. **微信接口**
   - wcferry库及其依赖
   - 微信PC客户端

3. **其他服务**
   - 中国节假日数据服务
   - 时区服务

### 7.3 部署流程

**功能描述**：
系统部署需要遵循特定的流程。

**详细需求**：
1. **环境准备**
   - 安装 Python 3.8+
   - 安装 MySQL 和 Redis
   - 配置虚拟环境

2. **代码部署**
   - 克隆或下载代码仓库
   - 安装依赖包：`pip install -r requirements.txt`
   - 配置系统参数

3. **数据库初始化**
   - 创建 MySQL 数据库和表结构
   - 初始化 Redis 缓存
   - 导入基础数据（如有）

4. **配置文件设置**
   - 复制 `config.yaml.template` 为 `config.yaml`
   - 设置 AI 模型 API 密钥
   - 配置数据库连接参数
   - 设置其他系统参数

5. **启动系统**
   - 启动微信客户端
   - 运行主程序：`python main.py`
   - 验证系统功能

## 8. 未来扩展计划

**功能描述**：
系统计划在未来版本中实现的功能和改进。

**详细计划**：
1. **功能扩展**
   - 更多游戏类型支持
   - 语音识别和处理
   - 图像识别和处理
   - 多语言支持

2. **性能优化**
   - 消息处理流程优化
   - 数据库查询优化
   - 缓存策略改进

3. **用户体验提升**
   - 移动端管理界面
   - 更丰富的数据可视化
   - 个性化配置选项

4. **AI能力增强**
   - 更多AI模型集成
   - 多模态内容生成
   - 自定义模型训练

5. **生态系统建设**
   - 插件系统
   - 开发者文档
   - 社区贡献机制

## 9. 附录

### 9.1 术语表

| 术语 | 描述 |
| ---- | ---- |
| wcferry | 微信客户端接口库，用于与微信进行交互 |
| AI模型 | 人工智能模型，如豆包、TigerBot等，用于生成智能回复 |
| 积分系统 | 用户在系统中获取和使用的虚拟货币系统 |
| 任务系统 | 百科问答游戏的核心功能模块 |
| Redis | 内存数据库，用于缓存临时数据 |
| MySQL | 关系型数据库，用于存储持久化数据 |
| Flask | Python Web框架，用于构建管理界面 |
| Token | AI模型处理文本的计量单位 |

### 9.2 参考文档

1. Python 官方文档：https://docs.python.org/
2. Flask 文档：https://flask.palletsprojects.com/
3. MySQL 文档：https://dev.mysql.com/doc/
4. Redis 文档：https://redis.io/documentation
5. wcferry 文档：参考项目GitHub页面
6. 各AI模型API文档：参考各服务提供商官方文档

---

本文档详细描述了 WeChatRobot 项目的需求规格，为开发团队提供了明确的开发指导。随着项目的进展，本文档可能会进行更新和补充。