Files

liuwei a559dcaaf0 说明书上传

2025-03-13 16:47:16 +08:00

22 KiB

Raw Blame History

WeChatRobot 项目需求规格说明书

文档信息

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

1. 项目概述

1.1 项目背景

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

1.2 项目目标

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

1.3 适用范围

本系统适用于以下场景：

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

2. 系统架构

2.1 总体架构

WeChatRobot 采用模块化设计，主要由以下几个部分组成：

核心引擎：负责与微信客户端交互，处理消息收发
功能模块：提供各种具体功能的实现
数据存储：管理系统数据和状态
管理界面：提供配置和监控功能

系统架构图如下：

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

2.2 核心组件

主程序模块
- 负责系统初始化和启动
- 协调各功能模块的工作
- 处理系统级事件
机器人核心
- 与微信客户端交互
- 消息分发与处理
- 命令解析与执行
功能模块
- AI 对话模块：集成多种 AI 模型
- 群聊管理模块：处理群成员变动、自动欢迎等
- 游戏任务模块：实现百科问答游戏
- 积分系统模块：管理用户积分和交易
- 签到模块：实现每日签到功能
- 消息总结模块：自动总结群聊内容
数据存储层
- MySQL 数据库：存储持久化数据
- Redis 缓存：存储临时数据和状态
Web 界面
- 基于 Flask 的管理界面
- 提供配置和监控功能

2.3 技术栈

编程语言
- Python 3.x
框架与库
- wcferry：微信客户端接口
- Flask：Web 框架
- MySQL Connector：数据库连接
- Redis：缓存服务
- Requests：HTTP 客户端
- Schedule：定时任务
- Pandas：数据处理
- Jupyter Client：代码执行
AI 接口
- OpenAI API
- 豆包 API (Doubao)
- TigerBot API
- 智谱 API (ZhipuAI)
- Google Generative AI
前端技术
- 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 消息处理

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

详细需求：

消息接收
- 接收文本消息、图片消息、视频消息、语音消息等多种类型
- 支持群聊和私聊消息的区分处理
消息存储
- 将消息存储到数据库中，包含以下信息：
  - 消息ID
  - 群ID（如适用）
  - 发送者ID
  - 消息内容
  - 消息类型
  - 时间戳
  - 附件URL（如适用）
  - 消息XML（如适用）
  - 缩略图（如适用）
消息过滤
- 过滤无效或垃圾消息
- 支持关键词过滤
- 支持特定消息类型的过滤
消息响应
- 根据预设规则自动响应特定消息
- 支持命令触发的响应
- 支持AI模型生成的智能响应

3.1.2 群聊管理

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

详细需求：

成员变动监控
- 检测群成员加入和退出事件
- 记录成员变动历史
- 提供成员变动通知
自动欢迎
- 当新成员加入群聊时，自动发送欢迎消息
- 支持自定义欢迎消息模板
- 支持群组特定的欢迎设置
群聊邀请管理
- 支持通过命令添加群聊
- 管理群聊邀请关系
- 提供群聊列表查询功能
群成员信息管理
- 缓存群成员信息
- 提供群成员信息查询功能
- 支持群成员昵称与ID的映射

3.1.3 AI 对话

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

详细需求：

多模型支持
- 支持豆包(Doubao)模型
- 支持TigerBot模型
- 支持ChatGLM模型
- 支持OpenAI模型
- 支持其他可扩展的AI模型
上下文对话
- 维护对话历史
- 支持上下文相关的回复
- 限制对话历史长度，避免token过多
自定义系统提示词
- 支持为不同AI模型设置系统提示词
- 支持根据不同场景切换提示词
对话统计
- 记录token使用情况
- 提供对话性能统计
- 支持对话质量评估

3.2 特色功能

3.2.1 群聊总结

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

详细需求：

内容总结
- 定期（如每日）总结群聊内容
- 提取关键话题和重要信息
- 生成结构化的总结报告
话题识别
- 自动识别群聊中的热门话题
- 对话题进行分类和评分
- 提供话题参与度分析
成员活跃度分析
- 识别最活跃的群成员
- 统计成员发言频率和质量
- 生成"今日MVP"等趣味性内容
总结展示
- 以轻松幽默的风格展示总结
- 融入网络流行语和Emoji
- 提供数据概览、话题概览、贡献者识别等内容

3.2.2 游戏任务系统

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

详细需求：

任务管理
- 支持随机分配任务
- 维护任务状态（待完成、已完成）
- 提供任务查询功能
答案验证
- 验证用户提交的答案
- 支持部分正确的评分
- 提供答案反馈和提示
积分系统
- 根据答案正确性奖励积分
- 支持积分扣除（如答错扣分）
- 维护用户积分余额
排行榜
- 提供群内用户积分排行
- 支持定期（如每周）排行榜更新
- 展示排行榜前N名用户

3.2.3 积分交易系统

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

详细需求：

积分转账
- 支持用户间积分转移
- 验证转账合法性（如余额检查）
- 记录转账历史
积分查询
- 提供用户积分余额查询
- 支持积分历史记录查询
- 展示积分来源和去向
积分奖惩
- 支持管理员奖励或扣除用户积分
- 提供积分奖惩理由记录
- 支持批量积分操作

3.2.4 签到系统

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

详细需求：

每日签到
- 支持用户每日签到
- 限制每日签到次数（每人每天一次）
- 自动重置每日签到计数
签到奖励
- 签到成功后给予积分奖励
- 支持连续签到额外奖励
- 支持特殊日期（如节假日）额外奖励
签到统计
- 记录用户签到历史
- 统计连续签到天数
- 提供签到排行榜
时区支持
- 根据配置的时区判断日期变更
- 支持不同地区用户的签到需求

3.2.5 定时提醒

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

详细需求：

工作报告提醒
- 支持日报、周报、月报提醒
- 自动识别工作日和非工作日
- 在适当时间发送提醒消息
自定义提醒
- 支持用户设置自定义提醒
- 提供提醒时间和内容的配置
- 支持重复提醒设置
节假日识别
- 集成中国节假日日历
- 在节假日发送特定消息
- 支持节假日前的工作安排提醒

3.3 管理功能

3.3.1 Web 管理界面

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

详细需求：

消息管理
- 查看历史消息记录
- 支持消息搜索和过滤
- 提供消息统计和分析
群组配置
- 管理群组列表
- 配置群组特定的功能设置
- 监控群组活跃度
功能开关
- 提供全局功能开关
- 支持群组级别的功能开关
- 记录功能状态变更历史
系统监控
- 监控系统运行状态
- 提供资源使用情况统计
- 支持异常情况告警

3.3.2 权限管理

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

详细需求：

权限级别
- 系统管理员：拥有所有权限
- 群组管理员：拥有特定群组的管理权限
- 普通用户：拥有基本功能使用权限
功能权限
- 控制特定功能的使用权限
- 支持按群组设置功能权限
- 提供权限变更审计
用户管理
- 管理用户账号和权限
- 支持用户封禁和解封
- 记录用户操作日志

4. 命令系统

4.1 通用命令

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

详细需求：

帮助命令
- /help：显示帮助信息
- /menu：显示功能菜单
功能开关命令
- 启用/禁用特定功能的命令
- 查询功能状态的命令
系统信息命令
- 查询系统状态
- 查询版本信息

4.2 游戏任务命令

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

详细命令列表：

/s：加入游戏（可选）
- 功能：显式加入游戏系统
- 响应：确认加入的消息
/ts：查看活跃任务
- 功能：显示当前活跃的任务列表
- 响应：活跃任务的详细信息
/l：列出未完成任务
- 功能：显示所有未完成的任务
- 响应：未完成任务的列表
/a [任务ID] [答案]：提交答案
- 功能：提交特定任务的答案
- 参数：任务ID和答案内容
- 响应：答案验证结果和积分变更
/r：查看排行榜
- 功能：显示积分排行榜
- 响应：排行榜信息
/ag：手动添加群聊（可选）
- 功能：将当前群聊添加到游戏系统
- 响应：添加结果确认
/t：获取新任务
- 功能：获取一个随机任务
- 响应：新任务的详细信息
- 限制：仅在特定时间段（9:00-22:59）可用

4.3 积分交易命令

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

详细命令列表：

积分转账积分数 @用户：转账积分
- 功能：将指定数量的积分转给目标用户
- 参数：积分数量和目标用户
- 响应：转账结果确认
命令别名：
- 积分交易
- 积分赠送
- 积分转移
- 转账积分
- 赠送积分
- 转移积分
- 送积分
- 积分送人
- 送人积分
- 积分赠予
- 赠予

4.4 管理命令

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

详细命令列表：

群组管理命令
- 添加/删除群组
- 配置群组特定设置
功能配置命令
- 启用/禁用特定功能
- 配置功能参数
用户管理命令
- 添加/删除用户
- 设置用户权限

5. 数据模型

5.1 数据库设计

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

主要数据表：

消息表（messages）
- 字段：
  - id：消息ID
  - group_id：群ID
  - timestamp：时间戳
  - sender：发送者ID
  - content：消息内容
  - message_type：消息类型
  - attachment_url：附件URL
  - message_id：微信消息ID
  - message_xml：消息XML
  - message_thumb：消息缩略图
用户表（t_encyclopedia_players）
- 字段：
  - player_id：用户ID
  - group_id：群ID
  - player_name：用户名称
  - points：积分
  - join_time：加入时间
任务表（t_encyclopedia_active_tasks）
- 字段：
  - active_task_id：任务ID
  - group_id：群ID
  - question：问题
  - answer：答案
  - score：分数
  - holder_id：持有者ID
  - status：状态（pending/completed）
任务历史表（t_encyclopedia_task_history）
- 字段：
  - id：记录ID
  - group_id：群ID
  - active_task_id：任务ID
  - player_id：用户ID
  - answer：提交的答案
  - is_correct：是否正确
  - points_earned：获得的积分
签到表
- 字段：
  - id：记录ID
  - user_id：用户ID
  - group_id：群ID
  - sign_time：签到时间
  - continuous_days：连续签到天数

5.2 缓存设计

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

主要缓存数据：

群成员信息
- 键格式：group:group_members:{group_id}
- 值类型：哈希表（wxid -> nickname）
- 用途：缓存群成员信息，避免频繁查询
群成员数量
- 键格式：group:group_member_count:{group_id}
- 值类型：字符串（数字）
- 用途：记录群成员数量
签到记录
- 键格式：group:sign_in:{group_id}:{user_id}
- 值类型：字符串（时间戳）
- 用途：记录用户签到状态
最后总结时间
- 键格式：{group_id}:summary_time
- 值类型：字符串（时间戳）
- 用途：记录群聊最后总结的时间
对话历史
- 内存缓存（非Redis）
- 结构：字典（wxid -> 消息列表）
- 用途：维护AI对话的上下文

6. 非功能需求

6.1 性能需求

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

详细需求：

响应时间
- 普通命令响应时间不超过1秒
- AI生成内容响应时间不超过10秒
- 数据库查询响应时间不超过2秒
并发处理
- 支持多个群组同时活跃
- 支持多用户并发请求
- 避免资源竞争和死锁
资源使用
- CPU使用率平均不超过50%
- 内存使用合理，避免内存泄漏
- 数据库连接池管理，避免连接耗尽

6.2 安全需求

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

详细需求：

数据安全
- 敏感配置信息加密存储
- API密钥安全管理
- 数据库访问权限控制
用户隐私
- 遵循最小权限原则收集用户信息
- 不存储不必要的敏感信息
- 提供隐私政策说明
防滥用措施
- 命令频率限制
- 异常行为检测
- 防止恶意使用系统资源

6.3 可扩展性

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

详细需求：

模块化设计
- 功能模块之间低耦合
- 提供清晰的接口定义
- 支持插件式扩展
配置灵活性
- 支持通过配置文件调整系统行为
- 避免硬编码配置项
- 支持运行时配置更新
AI模型扩展
- 支持新AI模型的便捷接入
- 统一的AI接口抽象
- 模型切换不影响系统稳定性

6.4 可靠性

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

详细需求：

错误处理
- 全面的异常捕获和处理
- 避免单点故障导致系统崩溃
- 提供友好的错误提示
日志系统
- 详细的操作日志记录
- 错误日志分级管理
- 支持日志查询和分析
自动恢复
- 系统异常时自动重试
- 关键服务自动重启
- 数据一致性保障

7. 部署要求

7.1 环境依赖

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

详细需求：

操作系统
- Windows 10/11（推荐）
- 支持其他操作系统（可选）
Python环境
- Python 3.8+
- 虚拟环境管理（推荐）
数据库环境
- MySQL 5.7+
- Redis 5.0+
网络环境
- 稳定的互联网连接
- 支持HTTPS请求

7.2 第三方服务

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

详细需求：

AI服务
- 豆包API访问权限
- TigerBot API访问权限
- OpenAI API访问权限（可选）
- 其他AI服务提供商的API
微信接口
- wcferry库及其依赖
- 微信PC客户端
其他服务
- 中国节假日数据服务
- 时区服务

7.3 部署流程

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

详细需求：

环境准备
- 安装 Python 3.8+
- 安装 MySQL 和 Redis
- 配置虚拟环境
代码部署
- 克隆或下载代码仓库
- 安装依赖包：pip install -r requirements.txt
- 配置系统参数
数据库初始化
- 创建 MySQL 数据库和表结构
- 初始化 Redis 缓存
- 导入基础数据（如有）
配置文件设置
- 复制 config.yaml.template 为 config.yaml
- 设置 AI 模型 API 密钥
- 配置数据库连接参数
- 设置其他系统参数
启动系统
- 启动微信客户端
- 运行主程序：python main.py
- 验证系统功能

8. 未来扩展计划

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

详细计划：

功能扩展
- 更多游戏类型支持
- 语音识别和处理
- 图像识别和处理
- 多语言支持
性能优化
- 消息处理流程优化
- 数据库查询优化
- 缓存策略改进
用户体验提升
- 移动端管理界面
- 更丰富的数据可视化
- 个性化配置选项
AI能力增强
- 更多AI模型集成
- 多模态内容生成
- 自定义模型训练
生态系统建设
- 插件系统
- 开发者文档
- 社区贡献机制

9. 附录

9.1 术语表

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

9.2 参考文档

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

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

22 KiB Raw Blame History Unescape Escape

WeChatRobot 项目需求规格说明书

文档信息

目录

1. 项目概述

1.1 项目背景

1.2 项目目标

1.3 适用范围

2. 系统架构

2.1 总体架构

2.2 核心组件

2.3 技术栈

2.4 系统依赖

3. 功能需求

3.1 基础功能

3.1.1 消息处理

3.1.2 群聊管理

3.1.3 AI 对话

3.2 特色功能

3.2.1 群聊总结

3.2.2 游戏任务系统

3.2.3 积分交易系统

3.2.4 签到系统

3.2.5 定时提醒

3.3 管理功能

3.3.1 Web 管理界面

3.3.2 权限管理

4. 命令系统

4.1 通用命令

4.2 游戏任务命令

4.3 积分交易命令

4.4 管理命令

5. 数据模型

5.1 数据库设计

5.2 缓存设计

6. 非功能需求

6.1 性能需求

6.2 安全需求

6.3 可扩展性

6.4 可靠性

7. 部署要求

7.1 环境依赖

7.2 第三方服务

7.3 部署流程

8. 未来扩展计划

9. 附录

9.1 术语表

9.2 参考文档

22 KiB

Raw Blame History