心灵伙伴项目文档
📋 项目概述
项目名称: 心灵伙伴 定位: AI驱动的心理健康智能助手系统 目标用户: 大学生群体 技术栈: Gradio | CAMEL-AI | MCP | Peewee ORM
核心特性
- 🤖 多智能体对话系统: 基于CAMEL-AI框架的角色扮演式心理咨询
- 😊 情绪识别与分析: 实时情绪检测、历史趋势分析、LLM增强分析
- 📊 心理评估系统: SAS焦虑自评量表，维度分析+趋势追踪
- 🧘 智能放松规划: 结合地理位置的个性化放松方案推荐
- 📖 情绪日记: 自动记录+AI综合分析
- 📈 数据统计可视化: 暖色系图表+Agent生成的温暖分析
- 👥 用户管理: 完整的认证、权限、管理员功能
🏗️ 系统架构
整体架构图
┌─────────────────────────────────────────────────────────┐
│ Gradio Web UI (app.py) │
│ ┌──────┬──────┬──────┬──────┬──────┬──────┬──────┐ │
│ │登录 │对话 │评估 │放松 │日记 │统计 │管理 │ │
│ └──────┴──────┴──────┴──────┴──────┴──────┴──────┘ │
└───────────────────────┬─────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────┐
│ 应用层 (api/apps/) │
│ ┌────────────┬────────────┬────────────┬────────────┐ │
│ │conversation│ emotion │ sas │ relaxation │ │
│ │_app.py │ _app.py │ _app.py │ _app.py │ │
│ ├────────────┼────────────┼────────────┼────────────┤ │
│ │statistics │ user │ admin │ │ │
│ │_app.py │ _app.py │ _app.py │ │ │
│ └────────────┴────────────┴────────────┴────────────┘ │
└───────────────────────┬─────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────┐
│ 服务层 (api/db/services/) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ UserService | EmotionService | ConversationSvc │ │
│ │ AssessmentService │ │
│ └─────────────────────────────────────────────────┘ │
└───────────────────────┬─────────────────────────────────┘
│
┌───────────────────────▼─────────────────────────────────┐
│ 数据层 (api/db/db_models.py) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ User | Emotion | Conversation | Assessment │ │
│ └─────────────────────────────────────────────────┘ │
│ SQLite (mindmate.db) │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ 外部集成 (api/tools/) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ web_search_tools.py - 智谱Z.AI语义搜索 │ │
│ │ mcp_search.py - 百度地图MCP工具集 │ │
│ │ amap_rest_tools.py - 高德地图REST API │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ AI引擎 (CAMEL-AI) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ ChatAgent | RolePlaying | Tools | ModelFactory │ │
│ └─────────────────────────────────────────────────┘ │
│ ↓ 调用 OpenAI Compatible API │
│ ┌─────────────────────────────────────────────────┐ │
│ │ DeepSeek-V3 / Qwen2.5 / 其他兼容模型 │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘技术栈详解
前端层
- Gradio 5.38.0: 快速构建Web UI，支持实时交互、文件上传、图表展示
- Matplotlib 3.10.3: 数据可视化（情绪分布、评估结果、对话趋势）
应用层
- CAMEL-AI 0.2.72: 多智能体框架
- ChatAgent: 单智能体对话，支持工具调用 - RolePlaying: 双智能体角色扮演（心理咨询师 ↔ 大学生） - ModelFactory: 统一模型接口管理
- 工具集成:
- 智谱Z.AI SDK: 语义搜索、案例检索 - 百度地图MCP: 地理编码、POI搜索、路径规划、天气查询 - 高德地图REST API: 备用地图服务
数据层
- Peewee 3.18.2: 轻量级ORM
- SQLite: 嵌入式数据库（生产环境可迁移至PostgreSQL/MySQL）
- 数据模型:
User # 用户表（username, password_hash, status, is_admin）
Emotion # 情绪记录（timestamp, emotions_json, user_input, user_id）
Conversation # 对话记录（timestamp, user_input, ai_response, user_id）
Assessment # 评估记录（timestamp, scores_json, total_score, result, user_id）安全与工具
- Cryptography 45.0.5: API密钥加密存储
- Loguru 0.7.3: 结构化日志
- Pytest 8.4.1: 单元测试框架
📦 项目结构
resonant-soul-main/
├── api/ # 后端核心代码
│ ├── apps/ # 应用模块
│ │ ├── admin_app.py # 管理员功能（用户管理）
│ │ ├── conversation_app.py # 对话引擎（ChatAgent + 工具调用）
│ │ ├── emotion_app.py # 情绪分析（关键词+LLM兜底+日记分析）
│ │ ├── relaxation_app.py # 放松规划（意图识别+地图工具）
│ │ ├── sas_app.py # SAS量表（反向计分+维度分析+LLM建议）
│ │ ├── statistics_app.py # 统计分析（Agent化+暖色图表）
│ │ └── user_app.py # 用户认证（登录/注册/密码修改）
│ ├── db/ # 数据库层
│ │ ├── db_models.py # ORM模型定义
│ │ ├── init_data.py # 初始化数据（管理员账号）
│ │ └── services/ # 数据服务层
│ │ ├── assessment_service.py # 评估CRUD+统计
│ │ ├── conversation_service.py # 对话CRUD+统计
│ │ ├── emotion_service.py # 情绪CRUD+统计
│ │ └── user_service.py # 用户CRUD+认证
│ ├── tools/ # 外部工具集成
│ │ ├── amap_rest_tools.py # 高德地图REST API
│ │ ├── mcp_search.py # 百度地图MCP工具（8个工具函数）
│ │ └── web_search_tools.py # 智谱Z.AI语义搜索
│ ├── utils/ # 工具函数
│ │ ├── file_utils.py # 文件操作
│ │ ├── log_utils.py # 日志配置
│ │ └── t_crypt.py # 加密解密
│ ├── constants.py # 常量定义
│ └── settings.py # 全局配置（模型初始化）
├── conf/ # 配置文件
│ └── service_conf.yaml # LLM配置、管理员账号
├── docker/ # Docker部署
│ └── entrypoint.sh # 容器启动脚本
├── logs/ # 日志目录
├── resources/ # 资源文件（截图）
├── test/ # 测试用例
│ └── test_emotion_app.py # 情绪分析单元测试
├── app.py # 主入口（Gradio界面）
├── Dockerfile # Docker镜像构建
├── pyproject.toml # 项目元数据+依赖
├── requirements.txt # pip依赖列表
├── uv.lock # uv依赖锁定
├── mindmate.db # SQLite数据库文件
└── README.md # 项目说明🎯 核心功能详解
1. 用户管理系统
1.1 用户认证
- 注册: SHA256密码哈希 + 唯一用户名校验
- 登录: 密码验证 + 状态检查（禁用用户拒绝登录）
- 会话管理: Gradio State存储当前用户（id, name, is_admin）
1.2 管理员功能
- 用户列表: 展示所有用户（ID、用户名、昵称、状态、注册时间）
- 用户操作:
- 启用/禁用用户（管理员账号不可禁用） - 删除用户（管理员账号不可删除）
- 权限控制:
is_admin=True用户可见管理员标签页
1.3 个人信息管理
- 查看用户名、昵称、注册时间
- 修改密码（≥8位，需确认）
代码位置: api/apps/user_app.py, api/apps/admin_app.py
2. 智能对话系统
2.1 对话流程
用户输入
↓
情绪分析（关键词匹配 + LLM兜底）
↓
保存情绪记录到数据库
↓
构造系统提示词（包含当前情绪）
↓
负面情绪？→ 调用 supportive_case_search_tool 检索资源
↓
创建 ChatAgent（注入历史对话+检索结果）
↓
调用 agent.step() 生成回复
↓
后处理（移除第三人称表述）
↓
保存对话记录 + 更新情绪图表2.2 情绪识别机制
两阶段识别:
- 关键词匹配（快速路径）:
emotions = {
'焦虑': ['焦虑', '紧张', '不安', '担心', '压力', '烦恼'],
'抑郁': ['抑郁', '难过', '消沉', '伤心', '悲伤', '失落'],
'愤怒': ['生气', '愤怒', '烦躁', '恼火', '不满', '讨厌'],
'积极': ['开心', '快乐', '高兴', '兴奋', '满足']
}- LLM语义分析（兜底）:
- 当关键词未匹配时，调用OpenAI Compatible API - 使用零温度、16 tokens限制，强制返回标准标签 - 异常时返回 ['平静']
2.3 工具调用
supportive_case_search_tool:
- 输入: 情绪标签、用户情境、媒体偏好（video/article/auto）
- 输出: 相关心理调适案例、成功故事、安慰资源（标题+URL+摘要）
- 实现: 智谱Z.AI SDK语义搜索
工具选择策略:
preferred = os.environ.get('SEARCH_PREFERRED', 'mcp').lower()
if preferred == 'sdk':
tools = get_tools() # 智谱SDK
else:
tools = mcp_tools if mcp_tools else get_tools() # 优先MCP2.4 对话记忆
- 使用
message_window_size=12保留最近12轮对话 - 登录时从数据库加载历史对话注入Agent记忆
- 支持连续上下文理解
代码位置: api/apps/conversation_app.py, api/apps/emotion_app.py
3. 心理评估系统（SAS量表）
3.1 量表设计
5题简化版SAS:
- 我感到比平常更加紧张和焦虑
- 我无缘无故地感到害怕
- 我容易心烦意乱或感到恐慌
- 我感到我的身体好像被分成几块
- 我感到一切都很好，不会发生什么不幸（反向题）
评分: 1=很少/没有, 2=有时, 3=经常, 4=总是如此
3.2 计分逻辑
# 反向计分（第5题）
reverse_indices = [5]
processed_scores = [5-score if idx in reverse_indices else score
for idx, score in enumerate(scores, 1)]
# 标准分计算
rough_score = sum(processed_scores)
standard_score = int(rough_score * 1.25)3.3 维度分析
dim_map = {
"紧张-焦虑": [1],
"恐惧-惊恐": [2, 3],
"躯体化/解离": [4],
"消极预期": [5], # 已反向处理
}- 计算每个维度的平均分（1-4）
- 等级划分: 低( Dict[str, Any]:
"""返回紧凑统计快照（纯文本/数字），供Agent分析""" return { "days": days, "total_emotions": {...}, "daily_emotions": {...}, "assessment_result_distribution": {...}, "conversations_total": 11, "conversations_daily_counts": {...}, }
**Agent系统提示词**:你是一位温暖、专业的心理支持助理。你可以调用工具获取用户最近统计信息， 请基于工具返回的快照，总结趋势、给出3-5条可执行建议，并以温柔口吻收尾。 避免医学诊断与药物建议，输出简洁 Markdown。
**用户消息示例**:请使用 stats_snapshot_tool(user_id=2, days=7) 获取数据后，再输出： 1) 情绪趋势（1-2句） 2) 关键观察（最多3点） 3) 温暖建议（3-5条，每条≤25字） 4) 鼓励收尾（1-2句）
**输出示例**:使用统计简析
- 最近7天主要情绪：焦虑
- 期间对话次数：11
温暖建议
- 记录每天一个小确幸，睡前复盘1分钟
- 进行3分钟呼吸放松，缓解紧张
- 找到一位可信任的朋友聊聊
- 安排一次短途散步，给自己放个小假
你已经很努力了，保持当下的节奏，我们一起慢慢变好。
**降级策略**: CHAT_MDL不可用时，使用规则生成（统计主情绪+通用建议）
**UI控件**:
- 滑块: 统计天数（3-30，默认7）
- 按钮: "刷新统计数据"
- 输出: 暖色系图表 + Agent生成的Markdown分析
**代码位置**: `api/apps/statistics_app.py`
---
## 🔧 配置与部署
### 1. 环境配置
#### 1.1 配置文件 (`conf/service_conf.yaml`)llm: model_type: 'deepseek-ai/DeepSeek-V3' # 或 'Qwen/Qwen2.5-7B-Instruct' model_url: 'https://api.siliconflow.cn/v1/' api_key: 'sk-your-api-key-here'
admin: username: 'admin' password: 'admin@123' name_nick: '系统管理员'
#### 1.2 环境变量（可选）搜索工具选择
export SEARCH_PREFERRED=mcp # 或 sdk
百度地图API密钥（用于MCP工具）
export BAIDU_MAPS_API_KEY=your_baidu_key
智谱API密钥（用于Z.AI搜索）
export ZHIPU_API_KEY=your_zhipu_key export ZAI_CHAT_MODEL=glm-4.6
### 2. 本地开发部署
#### 2.1 环境准备1. 安装UV包管理器
pip install uv set UV_INDEX=https://mirrors.aliyun.com/pypi/simple
2. 创建虚拟环境并安装依赖
uv sync --python 3.10 --all-extras
3. 激活虚拟环境
cd .venv/Scripts activate # Windows
source .venv/bin/activate # Linux/Mac
#### 2.2 启动项目python app.py
访问地址: http://127.0.0.1:7860
### 4. 魔搭创空间部署
#### 4.1 生成依赖文件uv pip compile pyproject.toml --all-extras -o requirements.txt
#### 4.2 上传代码
1. 将项目推送到魔搭Git仓库
2. 在"设置"中点击"上线发布"
#### 4.3 配置环境变量
在魔搭创空间设置中添加:
- `ZHIPU_API_KEY`
- `BAIDU_MAPS_API_KEY`
---
## 🔐 安全机制
### 1. 密码安全
- **哈希算法**: SHA256
- **存储**: 仅存储哈希值，不存储明文
- **验证**: 输入密码哈希后与数据库比对
### 2. API密钥加密from api.utils.t_crypt import encrypt_api_key, decrypt_api_key, generate_key
加密存储
key = generate_key() encrypted = encrypt_api_key(api_key, key)
使用时解密
api_key = decrypt_api_key(encrypted, key)
### 3. 权限控制
- **管理员保护**: 管理员账号不可被禁用/删除
- **状态检查**: 登录时验证用户状态（禁用用户拒绝登录）
- **会话隔离**: 每个用户只能访问自己的数据
### 4. 输入验证
- **密码强度**: 最少8位
- **用户名唯一性**: 注册时检查重复
- **SQL注入防护**: 使用ORM参数化查询
### 表结构详解
#### User表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| username | TEXT | 用户名（唯一） |
| name_nick | TEXT | 昵称 |
| password | TEXT | SHA256哈希 |
| status | BOOLEAN | 启用状态（True=启用） |
| is_admin | BOOLEAN | 管理员标识 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
#### Emotion表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| timestamp | DATETIME | 记录时间 |
| emotions | TEXT | JSON数组（["焦虑", "抑郁"]） |
| user_input | TEXT | 用户输入内容 |
| user_id | INTEGER | 外键→User.id |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
#### Conversation表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| timestamp | DATETIME | 对话时间 |
| user_input | TEXT | 用户输入 |
| ai_response | TEXT | AI回复 |
| user_id | INTEGER | 外键→User.id |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
#### Assessment表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| timestamp | DATETIME | 评估时间 |
| scores | TEXT | JSON数组（[1,2,3,4,1]） |
| total_score | INTEGER | SAS标准分 |
| result | TEXT | 评估结果文本 |
| user_id | INTEGER | 外键→User.id |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |
---
## 🧪 测试
### 单元测试运行所有测试
pytest
运行特定测试文件
pytest test/test_emotion_app.py -v
测试覆盖率
pytest --cov=api --cov-report=html
### 测试用例示例test/test_emotion_app.py
@pytest.mark.parametrize("text, expected_emotion", [ ("我今天很开心", ["积极"]), ("我感到很焦虑", ["焦虑"]), ("他非常愤怒", ["愤怒"]), ("她有点抑郁", ["抑郁"]), ]) def test_analyze_emotion_single_emotion(text, expected_emotion): """测试单个情绪识别""" assert analyze_emotion(text) == expected_emotion
---
## 🚀 性能优化
### 1. 数据库优化
- **索引**: 在 `user_id`, `timestamp` 字段添加索引
- **连接池**: 使用Peewee连接池（生产环境）
- **批量操作**: 使用 `bulk_create` 批量插入
### 2. 缓存策略
- **模型缓存**: `CHAT_MDL` 全局单例，避免重复初始化
- **工具缓存**: MCP工具客户端延迟初始化+全局复用
### 3. 异步优化（待实现）
- 使用 `asyncio` + `aiohttp` 异步调用外部API
- Gradio支持 `async def` 事件处理函数
### 4. 日志管理日志配置（api/utils/log_utils.py）
from loguru import logger
logger.add( "logs/resonant-soul.{time:YYYY-MM-DD}.log", rotation="00:00", # 每天午夜轮转 retention="30 days", # 保留30天 level="INFO" )
---
## 📈 监控与运维
### 1. 日志监控
- **位置**: `logs/resonant-soul.{date}.log`
- **级别**: INFO（正常操作）、WARNING（异常但可恢复）、ERROR（严重错误）
- **关键指标**:
- 用户登录/注册
- 对话生成耗时
- 工具调用失败率
- 数据库操作异常
### 2. 数据库备份定时备份SQLite
cp mindmate.db backups/mindmate_$(date +%Y%m%d_%H%M%S).db
保留最近30天备份
find backups/ -name "mindmate_*.db" -mtime +30 -delete
### 3. 健康检查添加健康检查端点（待实现）
@app.get("/health") def health_check(): return { "status": "healthy", "db_connected": check_db_connection(), "model_loaded": CHAT_MDL is not None, }
## 🛣️ 未来规划
### 短期目标（v0.2.0）
- [ ] 支持多模态输入（语音、图片）
- [ ] 添加情绪预警机制（连续负面情绪触发提醒）
- [ ] 实现对话导出功能（PDF/Word）
### 中期目标（v0.3.0）
- [ ] 多用户实时聊天室（同伴支持）
- [ ] 心理咨询师接入（人工干预）
- [ ] 移动端适配（响应式设计）
- [ ] 数据可视化大屏（管理员视角）
### 长期目标（v1.0.0）
- [ ] 迁移至PostgreSQL（支持高并发）
- [ ] 微服务架构拆分（对话/评估/统计独立服务）
- [ ] 集成更多AI能力（情绪识别模型微调、个性化推荐）
- [ ] 开放API接口（第三方集成）
---
### 技术文档
- [CAMEL-AI Documentation](https://docs.camel-ai.org/)
- [Gradio Documentation](https://www.gradio.app/docs/)
- [Peewee Documentation](http://docs.peewee-orm.com/en/latest/)
### 相关项目
- [Mental Health Chatbot](https://github.com/topics/mental-health-chatbot)
- [Psychological Assessment Tools](https://github.com/topics/psychological-assessment)
---
**最后更新**: 2025-10-25
**文档版本**: v1.0