docs: 更新 README，包含 MCP 接入指南
Sileya
parent
558b105cbc
commit
7896fbd1aa
157
README.md
157
README.md
|
|
@ -4,87 +4,147 @@
|
|||
识别潜在的心理问题（如霸凌、抑郁情绪、焦虑、家庭矛盾等），
|
||||
为家长提供早期预警。
|
||||
|
||||
## 项目状态
|
||||
|
||||
⚠️ **开发中** — 当前为最小可行性版本（MVP）
|
||||
|
||||
已实现：
|
||||
- ✅ 心理筛查核心模块
|
||||
- ✅ MiniMax API 集成
|
||||
- ✅ MCP 工具（FastMCP stdio）
|
||||
- ✅ 单元测试 + 集成测试
|
||||
- ✅ 测试语料库
|
||||
|
||||
待实现：
|
||||
- ⏳ 接入 xiaozhi-esp32-server MCP 接入点
|
||||
- ⏳ 案例库（召回 / 上传 / 咨询师终端）
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
child-psycho-companion/
|
||||
├── src/
|
||||
│ └── psycho_screener/ # 核心筛查模块
|
||||
│ ├── __init__.py
|
||||
│ └── screener.py # 筛查器实现
|
||||
├── tests/
|
||||
├── src/psycho_screener/
|
||||
│ ├── __init__.py
|
||||
│ ├── conftest.py
|
||||
│ └── test_screener.py # 单元测试
|
||||
├── .env.example # 环境变量模板
|
||||
├── pyproject.toml
|
||||
│ ├── 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
|
||||
```
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
cd child-psycho-companion
|
||||
pip install -e .
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### 2. 配置 API Key
|
||||
### 配置
|
||||
|
||||
```bash
|
||||
export MINIMAX_API_KEY=your-api-key-here
|
||||
```
|
||||
|
||||
### 3. 使用示例
|
||||
### 筛查器直接调用
|
||||
|
||||
```python
|
||||
from psycho_screener import PsychoScreener
|
||||
|
||||
screener = PsychoScreener(api_key="your-api-key")
|
||||
screener = PsychoScreener(api_key="your-key")
|
||||
|
||||
# 对儿童对话进行筛查
|
||||
context = """
|
||||
孩子：今天在学校，小明又打我了，我好害怕。
|
||||
孩子：他说如果我告诉老师就会打我。
|
||||
"""
|
||||
result = screener.screen(context)
|
||||
# 简单文本
|
||||
result = screener.screen("孩子说：今天小明又打我了...")
|
||||
|
||||
# 构建注入前缀
|
||||
if result.detected:
|
||||
print(f"检测到问题：{result.summary}")
|
||||
prefix = screener.build_response_prefix(result)
|
||||
print(f"响应前缀：{prefix}")
|
||||
print(prefix) # 【已发现特定心理问题】类别：bullying...
|
||||
```
|
||||
|
||||
### 4. 运行测试
|
||||
### 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
|
||||
# 安装测试依赖
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# 运行单元测试（Mock 模式，不调用真实 API）
|
||||
# 单元测试（Mock，不调用 API）
|
||||
pytest tests/test_screener.py -v -m unit
|
||||
|
||||
# 运行集成测试（需要真实 API key）
|
||||
# 集成测试（真实 API，需要 MINIMAX_API_KEY）
|
||||
export MINIMAX_API_KEY=your-key
|
||||
pytest tests/test_screener.py -v -m integration
|
||||
pytest tests/ -v
|
||||
|
||||
# MCP 工具测试
|
||||
pytest tests/test_mcp_tool.py -v
|
||||
```
|
||||
|
||||
## 核心流程
|
||||
|
||||
```
|
||||
儿童语音 → 小智AI (STT) → 对话上下文
|
||||
↓
|
||||
心理筛查器 (MiniMax API)
|
||||
↓
|
||||
ScreeningResult {detected, category, severity}
|
||||
↓
|
||||
┌───────────┴───────────┐
|
||||
detected=True detected=False
|
||||
↓ ↓
|
||||
注入前缀标记 原样返回
|
||||
"已发现特定心理问题：..."
|
||||
```
|
||||
---
|
||||
|
||||
## 检测类别
|
||||
|
||||
|
|
@ -99,9 +159,10 @@ pytest tests/test_screener.py -v -m integration
|
|||
| social_isolation | 社交孤立 | medium-high |
|
||||
| other | 其他心理需求 | - |
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- [ ] 接入 xinnan-tech/xiaozhi-esp32-server MCP 接入点
|
||||
- [ ] 构建案例库系统
|
||||
- [ ] 开发咨询师终端
|
||||
- [ ] 家长端报告界面
|
||||
1. 在真实 xiaozhi 环境中验证 MCP 工具接入
|
||||
2. 构建案例库：召回 / 上传 / 咨询师终端
|
||||
3. 家长端报告界面
|
||||
|
|
|
|||
Loading…
Reference in New Issue