child-psycho-companion/README.md

# 儿童心理陪伴玩偶

基于小智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. 家长端报告界面