169 lines
4.0 KiB
Markdown
169 lines
4.0 KiB
Markdown
# 儿童心理陪伴玩偶
|
||
|
||
基于小智AI生态的儿童心理筛查插件，通过分析儿童与玩偶的对话内容，
|
||
识别潜在的心理问题（如霸凌、抑郁情绪、焦虑、家庭矛盾等），
|
||
为家长提供早期预警。
|
||
|
||
## 项目状态
|
||
|
||
⚠️ **开发中** — 当前为最小可行性版本（MVP）
|
||
|
||
已实现：
|
||
- ✅ 心理筛查核心模块
|
||
- ✅ MiniMax API 集成
|
||
- ✅ MCP 工具（FastMCP stdio）
|
||
- ✅ 单元测试 + 集成测试
|
||
- ✅ 测试语料库
|
||
|
||
待实现：
|
||
- ⏳ 接入 xiaozhi-esp32-server MCP 接入点
|
||
- ⏳ 案例库（召回 / 上传 / 咨询师终端）
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
child-psycho-companion/
|
||
├── src/psycho_screener/
|
||
│ ├── __init__.py
|
||
│ ├── screener.py # 核心筛查模块
|
||
│ └── mcp_tool.py # MCP 工具（FastMCP stdio）
|
||
├── tests/
|
||
│ ├── test_screener.py # 筛查器测试（15个）
|
||
│ └── test_mcp_tool.py # MCP工具测试（6个）
|
||
├── docs/
|
||
│ └── test_corpus.md # 虚构测试语料
|
||
├── mcp_config.json # mcp_pipe.py 桥接配置
|
||
├── .env.example # 环境变量模板
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
cd child-psycho-companion
|
||
pip install -e ".[dev]"
|
||
```
|
||
|
||
### 配置
|
||
|
||
```bash
|
||
export MINIMAX_API_KEY=your-api-key-here
|
||
```
|
||
|
||
### 筛查器直接调用
|
||
|
||
```python
|
||
from psycho_screener import PsychoScreener
|
||
|
||
screener = PsychoScreener(api_key="your-key")
|
||
|
||
# 简单文本
|
||
result = screener.screen("孩子说：今天小明又打我了...")
|
||
|
||
# 构建注入前缀
|
||
if result.detected:
|
||
prefix = screener.build_response_prefix(result)
|
||
print(prefix) # 【已发现特定心理问题】类别：bullying...
|
||
```
|
||
|
||
### MCP 工具调用
|
||
|
||
```python
|
||
from psycho_screener.mcp_tool import psycho_screen
|
||
|
||
messages = [
|
||
{"role": "system", "content": "你是一个小智AI玩偶..."},
|
||
{"role": "user", "content": "今天小朋友欺负我了"},
|
||
]
|
||
result = psycho_screen(messages, include_prefix=True)
|
||
```
|
||
|
||
---
|
||
|
||
## MCP 接入指南
|
||
|
||
### 接入架构
|
||
|
||
```
|
||
孩子语音 → 小智设备(ESP32)
|
||
↓
|
||
xiaozhi-esp32-server
|
||
↓
|
||
MCP Endpoint (ws://...)
|
||
↓
|
||
psycho-screener MCP 工具 ← 你在这里
|
||
```
|
||
|
||
### 部署步骤
|
||
|
||
**前置条件：** 已有运行中的 `xiaozhi-esp32-server` 并开启了 MCP 接入点。
|
||
|
||
1. **从 xiaozhi 智控台获取 MCP 接入点地址**
|
||
- 格式：`ws://<IP>:<PORT>/mcp_endpoint/mcp/?token=<xxx>`
|
||
|
||
2. **配置本工具**
|
||
```bash
|
||
export MCP_ENDPOINT="ws://192.168.1.25:8004/mcp_endpoint/mcp/?token=xxx"
|
||
export MINIMAX_API_KEY=your-key
|
||
```
|
||
|
||
3. **启动 MCP 桥接**
|
||
```bash
|
||
# 方式A：直接用 python mcp_pipe.py（需要克隆 mcp-calculator 仓库）
|
||
python mcp_pipe.py
|
||
|
||
# 方式B：自行运行 mcp_tool.py（需要 MCP_ENDPOINT 环境变量）
|
||
python -m psycho_screener.mcp_tool
|
||
```
|
||
|
||
4. **在 xiaozhi 智控台刷新 MCP 状态**
|
||
- 确认 `psycho_screen` 工具已注册
|
||
|
||
5. **提示词配置（重要）**
|
||
- 需要在 xiaozhi 的系统提示词中告知 LLM：
|
||
> "当孩子表达悲伤、害怕、被欺负、孤独等情绪时，
|
||
> 调用 psycho_screen 工具分析对话上下文"
|
||
|
||
---
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
# 单元测试（Mock，不调用 API）
|
||
pytest tests/test_screener.py -v -m unit
|
||
|
||
# 集成测试（真实 API，需要 MINIMAX_API_KEY）
|
||
export MINIMAX_API_KEY=your-key
|
||
pytest tests/ -v
|
||
|
||
# MCP 工具测试
|
||
pytest tests/test_mcp_tool.py -v
|
||
```
|
||
|
||
---
|
||
|
||
## 检测类别
|
||
|
||
| 类别 | 描述 | 严重程度 |
|
||
|------|------|---------|
|
||
| bullying | 霸凌/同伴冲突 | low-high |
|
||
| depression | 抑郁情绪 | medium-high |
|
||
| anxiety | 焦虑/恐惧 | low-medium |
|
||
| family_conflict | 家庭矛盾 | medium-high |
|
||
| self_esteem | 自卑/自我否定 | low-medium |
|
||
| trauma | 创伤事件 | medium-high |
|
||
| social_isolation | 社交孤立 | medium-high |
|
||
| other | 其他心理需求 | - |
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
1. 在真实 xiaozhi 环境中验证 MCP 工具接入
|
||
2. 构建案例库：召回 / 上传 / 咨询师终端
|
||
3. 家长端报告界面
|