# Claude Code — 儿童心理陪伴玩偶项目

## 项目背景

基于小智 AI 生态的儿童心理陪伴玩偶项目。由客座教授（大头/胡老师）指导团队开发。
- 仓库：http://xmhome.ow-my.com:3000/sileya-ai/child-psycho-companion
- 技术栈：Python、MCP（Model Context Protocol）、MiniMax API、Docker

## 技术架构

### 核心模块
- `src/psycho_screener/screener.py` — 心理问题筛查（bullying/depression/anxiety 等7类）
- `src/psycho_screener/mcp_tool.py` — fastmcp 协议版本
- `src/psycho_screener/mcp_tool_native.py` — 原生 mcp SDK 版本

### 工具
- `mcp_simulator.py` — MCP 协议模拟器
- `xiaozhi_cli_client.py` — xiaozhi-esp32-server CLI 调试工具
- `test_xiaozhi_client.py` — pytest 测试套件

### 环境
- Docker 容器：xiaozhi-esp32-server（8000/8003）、mcp-endpoint-server（8004）
- Python 3.x + .venv 虚拟环境

---

## 当前状态（2026-04-06）

### 已解决的问题

#### 1. WebSocket 认证问题 ✅
- **问题**：服务端从 HTTP header 读 `device-id`，客户端从 URL query param 传
- **根因**：xiaozhi-server `connection.py` 第 227 行用 `self.headers.get("device-id")` 读 header，客户端用 `?device-id=xxx` query 参数
- **修复**：`xiaozhi_cli_client.py` 改用 `additional_headers={"Device-ID": DEVICE_ID, "Client-ID": DEVICE_ID}` 传递
- **状态**：已修复并验证，WebSocket 连接成功

#### 2. MCP Endpoint Token URL 编码 ✅
- **问题**：token 中的 `+` 在 URL 中被 FastAPI 解码为空格，导致 base64 解码失败
- **根因**：`api.minimaxi.com/v1` 返回 1008 policy violation
- **修复**：`.config.yaml` 中 token 的 `+` → `%2B`，`=` → `%3D`
- **状态**：已修复，`MCP接入点连接成功`

#### 3. MCP 工具注册 ✅ 不需要真机
- **澄清**：`psycho-screener` 是服务端 MCP，通过 stdio 子进程运行，不需要 ESP32 真机
- **状态**：`psycho_screen` 工具已在函数列表中注册

### 待解决问题

#### P0 — MiniMax LLM 401 错误（根因已定位）
- **现象**：xiaozhi-server LLM 调用返回 401 "令牌已过期或验证不正确"
- **根因**：配置被 xinnan-tech manager-api 远程覆盖
  - 本地 `.config.yaml` 配置了 MiniMax-M2.5
  - 但 `config_loader.py` 检测到 manager-api 配置后，调用 `get_server_config()` 从 xinnan-tech API 获取设备配置
  - API 返回的默认模型是 `glm-4-flash`，覆盖了本地配置
  - `glm-4-flash` 的 API key 与 MiniMax 不匹配，导致 401
- **解决方向**：升级到 xiaozhi-esp32-server 全模块安装（智控台），在智控台配置 MiniMax API Key
- **详见**：`STATUS.md`

#### P1 — `screen_from_messages()` 未实现
- `screener.py` 的消息格式接口未完成
- 需要从 messages 数组提取儿童对话

---

## 下一步计划

### 近期（升级智控台）
1. 将 xiaozhi-esp32-server 从最简化安装升级为全模块安装（智控台）
2. 在智控台配置 MiniMax LLM + TTS
3. 验证玩偶对话功能完整链路

### 中期（功能完善）
1. 实现 `screen_from_messages()` 方法
2. WebSocket 认证调试
3. 案例库设计

详见 `STATUS.md`

---

## 运行命令

```bash
# 激活虚拟环境
cd /Users/bigemon/WorkSpace/child-psycho-companion
source .venv/bin/activate

# 测试玩偶对话
python xiaozhi_cli_client.py "今天小朋友打我，我好害怕"

# Docker 容器状态
docker ps | grep xiaozhi

# 查看 xiaozhi-server 日志
docker logs xiaozhi-esp32-server 2>&1 | tail -20
```

## Git 操作

```bash
git add . && git commit -m "描述" && git push origin main
```