恢复人脸识别功能。使用关闭功能进行隐藏

plugins/kid_photo_extractor/README.md

@@ -0,0 +1,327 @@
+# 需求分析与设计文档：群聊小朋友照片提取功能
+
+## 1. 需求概述
+
+开发一个基于 deepface 的人脸识别与分析功能，通过权限管理系统控制该功能在群聊中的启用状态。该功能可以自动识别群聊中分享的图片，提取包含小朋友人脸的照片，并按照人脸进行分类整理。
+
+## 2. 功能需求
+
+### 2.1 基本功能
+- 通过群权限管理系统控制功能的开启与关闭
+- 处理指定目录下的图片文件
+- 分析图片中的人脸，识别小朋友的人脸
+- 将包含小朋友人脸的图片进行分类存储
+- 支持通过指令触发人脸分组功能
+- 记录每个群的最后分析时间
+- 分析完成后输出详细的分析结果统计
+
+### 2.2 详细需求
+1. **权限管理**：
+   - 使用现有的 `GroupBotManager` 管理该功能的权限
+   - 通过指令启用/关闭该功能
+
+2. **图片处理**：
+   - 处理指定目录下的图片文件（不需要处理微信消息）
+   - 根据指令处理对应群聊的图片目录
+   - 支持常见图片格式（jpg, png, jpeg等）
+   - 图片预处理（调整大小、格式转换等）
+
+3. **人脸识别**：
+   - 识别图片中的所有人脸
+   - 判断人脸是否为小朋友（儿童）
+   - 提取小朋友人脸特征用于分组
+
+4. **照片分类**：
+   - 为每个识别出的小朋友创建独立文件夹
+   - 将包含同一小朋友的照片复制到对应文件夹
+   - 处理一张图片中多个小朋友的情况
+
+5. **指令控制**：
+   - 提供开始分析的指令
+   - 提供查看分析结果的指令
+   - 提供清理分析数据的指令
+   - 提供查询最后分析时间的指令
+
+6. **分析记录**：
+   - 记录每个群的最后分析时间
+   - 记录每次分析的统计结果（处理图片数、识别人脸数、分类结果等）
+   - 支持查询历史分析记录
+
+7. **结果输出**：
+   - 分析完成后自动输出详细的分析结果
+   - 包括处理图片总数、识别出的小朋友数量、每个小朋友的照片数量
+   - 提供分类后的文件夹路径信息
+
+## 3. 技术方案
+
+### 3.1 技术栈
+- **deepface**：用于人脸检测、年龄估计和人脸识别
+- **Python**：核心开发语言
+- **Redis**：存储权限配置和人脸特征数据
+- **OpenCV**：辅助图像处理
+
+### 3.2 系统架构
+
+```
++------------------+     +------------------+     +------------------+
+|                  |     |                  |     |                  |
+|  权限管理模块     |---->|  图片处理模块     |---->|  人脸识别模块     |
+|  (GroupBotManager)|     |  (ImageProcessor) |     |  (FaceAnalyzer)  |
+|                  |     |                  |     |                  |
++------------------+     +------------------+     +------------------+
+                                                          |
+                                                          v
++------------------+     +------------------+     +------------------+
+|                  |     |                  |     |                  |
+|  指令处理模块     |<----|  照片分类模块     |<----|  人脸分组模块     |
+|  (CommandHandler) |     |  (PhotoClassifier)|     |  (FaceGrouper)   |
+|                  |     |                  |     |                  |
++------------------+     +------------------+     +------------------+
+```
+
+### 3.3 模块设计
+
+#### 3.3.1 权限管理模块
+- 使用现有的 `GroupBotManager` 类
+- 添加 `KID_PHOTO_EXTRACT` 功能权限（已存在）
+- 提供权限检查方法
+
+#### 3.3.2 图片处理模块
+- 扫描指定目录下的图片
+- 图片预处理（调整大小、格式转换等）
+- 支持批量处理多张图片
+
+#### 3.3.3 人脸识别模块
+- 使用 deepface 进行人脸检测
+- 年龄估计，识别小朋友（例如年龄 < 14 岁）
+- 提取人脸特征向量
+
+#### 3.3.4 人脸分组模块
+- 基于人脸特征向量进行聚类
+- 为每个聚类分配唯一 ID
+- 维护人脸 ID 与照片的映射关系
+
+#### 3.3.5 照片分类模块
+- 创建分类目录结构
+- 将照片复制到对应的分类目录
+- 处理一张照片中多个小朋友的情况
+
+#### 3.3.6 指令处理模块
+- 解析用户指令
+- 触发相应的功能模块
+- 返回操作结果消息
+
+## 4. 数据结构设计
+
+### 4.1 Redis 数据结构
+
+1. **权限配置**：
+   ```
+   group:{group_id}:permissions
+   ```
+   - 哈希表，存储群组的功能权限配置
+   - 包含 KID_PHOTO_EXTRACT 的启用状态
+
+2. **人脸特征数据**：
+   ```
+   group:{group_id}:kid_faces
+   ```
+   - 哈希表，存储识别出的小朋友人脸特征
+   - 键为人脸 ID，值为特征向量的序列化数据
+
+3. **照片映射**：
+   ```
+   group:{group_id}:kid_photos:{face_id}
+   ```
+   - 集合，存储包含特定小朋友的照片路径
+
+4. **分析记录**：
+   ```
+   group:{group_id}:photo_analysis:last_time
+   ```
+   - 字符串，存储最后一次分析的时间戳
+
+5. **分析结果**：
+   ```
+   group:{group_id}:photo_analysis:results
+   ```
+   - 列表，存储历史分析结果的JSON数据
+   - 每次分析后将结果添加到列表头部
+
+### 4.2 文件目录结构
+
+```
+/群聊文件目录/
+  ├── 原始图片/  # 已下载好的图片目录
+  │   ├── image1.jpg
+  │   ├── image2.png
+  │   └── ...
+  └── kid_photos/  # 分析结果目录
+      ├── kid_1/
+      │   ├── photo1.jpg
+      │   └── photo2.jpg
+      ├── kid_2/
+      │   ├── photo1.jpg
+      │   └── photo3.jpg
+      └── analysis_report.json  # 分析报告文件
+```
+
+## 5. 接口设计
+
+### 5.1 插件接口
+
+```python
+class KidPhotoExtractor(PluginInterface):
+    def __init__(self, system_context):
+        super().__init__("kid_photo_extract", "小朋友照片提取", system_context)
+        self.face_analyzer = FaceAnalyzer()
+        self.photo_classifier = PhotoClassifier()
+        
+    def handle_command(self, command, message):
+        # 处理用户指令
+        pass
+        
+    def analyze_photos(self, group_id, source_dir):
+        # 分析指定目录下的照片
+        pass
+        
+    def generate_report(self, group_id, analysis_result):
+        # 生成分析报告
+        pass
+```
+
+### 5.2 指令接口
+
+1. **开始分析**：
+   ```
+   #开始分析照片 [可选:目录路径]
+   ```
+   - 触发对指定目录下图片的分析
+   - 如果不指定目录，则使用默认的群聊文件目录
+
+2. **查看结果**：
+   ```
+   #查看照片分析
+   ```
+   - 返回最近一次分析结果统计信息
+
+3. **清理数据**：
+   ```
+   #清理照片分析
+   ```
+   - 清理分析数据和分类目录
+
+4. **查询分析时间**：
+   ```
+   #照片分析时间
+   ```
+   - 返回最后一次分析的时间信息
+
+## 6. 实现流程
+
+### 6.1 权限管理流程
+
+1. 用户发送权限设置指令
+2. 系统验证用户权限
+3. 更新群组的 KID_PHOTO_EXTRACT 权限状态
+4. 返回设置结果
+
+### 6.2 照片分析流程
+
+1. 用户发送开始分析指令（可指定目录）
+2. 系统验证群组权限
+3. 扫描指定目录中的图片
+4. 对每张图片进行人脸检测
+5. 识别小朋友人脸并提取特征
+6. 对人脸特征进行聚类分组
+7. 创建分类目录结构
+8. 将照片复制到对应分类目录
+9. 生成分析报告并保存
+10. 记录分析时间和结果
+11. 返回分析完成消息和结果统计
+
+### 6.3 分析结果输出流程
+
+1. 分析完成后自动生成结果报告
+2. 报告包含以下内容：
+   - 分析时间
+   - 处理图片总数
+   - 识别出的小朋友总数
+   - 每个小朋友的照片数量
+   - 分类后的文件夹路径
+3. 将报告以文本形式发送到群聊
+4. 同时保存报告为JSON文件
+
+## 7. 安全与隐私考虑
+
+1. **数据安全**：
+   - 图片处理完成后及时清理临时文件
+   - 人脸特征数据加密存储
+
+2. **隐私保护**：
+   - 只在功能启用的群组中处理图片
+   - 提供清理数据的指令
+   - 不上传或分享用户照片到外部服务
+   - 分析结果仅在群内可见
+
+3. **权限控制**：
+   - 只有群管理员可以启用/关闭该功能
+   - 只有授权用户可以触发分析指令
+
+## 8. 性能优化
+
+1. **图片处理优化**：
+   - 限制处理图片的大小
+   - 使用多线程并行处理多张图片
+
+2. **人脸识别优化**：
+   - 缓存已识别的人脸特征
+   - 使用轻量级模型进行初步筛选
+
+3. **存储优化**：
+   - 定期清理长时间未访问的数据
+   - 对大量数据进行分片存储
+
+## 9. 开发计划
+
+### 9.1 阶段一：基础功能实现
+- 实现权限管理集成
+- 实现基本的人脸检测和年龄估计
+- 实现简单的照片分类功能
+
+### 9.2 阶段二：功能完善
+- 实现人脸聚类和分组
+- 优化小朋友识别准确率
+- 完善指令系统
+
+### 9.3 阶段三：性能优化与测试
+- 性能优化
+- 全面测试
+- 文档完善
+
+## 10. 测试计划
+
+### 10.1 单元测试
+- 测试人脸检测准确率
+- 测试年龄估计准确率
+- 测试人脸聚类效果
+
+### 10.2 集成测试
+- 测试与权限系统的集成
+- 测试与消息系统的集成
+- 测试与文件系统的集成
+
+### 10.3 性能测试
+- 测试大量图片处理性能
+- 测试多人脸图片处理性能
+- 测试系统资源占用情况
+
+## 11. 总结
+
+本功能通过 deepface 技术实现群聊中小朋友照片的自动识别与分类，帮助用户更好地管理和整理群聊中分享的照片。该功能与现有的权限管理系统无缝集成，用户可以通过简单的指令控制功能的启用和使用。
+
+实现该功能需要解决人脸检测、年龄估计、人脸聚类等技术挑战，同时需要考虑数据安全和隐私保护问题。通过分阶段开发和全面测试，确保功能的稳定性和可靠性。
+
+
+接下来的内容：
+1.需要支持人脸人工打标，打标之后，记录到数据库里面，作为分析的对比源头。