103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# 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
|
||
```
|