life-echo/api/docs/文字交流模式说明.md

# 文字交流模式说明

## 概述

当前系统已配置为**纯文字交流模式**，暂时不接通语音模块（ASR/TTS）。用户可以通过WebSocket发送文字消息与AI进行对话，系统会自动将对话记录整理成书的多个章节。

## 功能特性

### 1. 文字对话
- 用户通过WebSocket发送 `TEXT` 类型的消息
- AI Agent 生成文字回应
- 所有对话记录保存到数据库

### 2. 章节自动整理
- 对话结束后，系统自动调用 Memory Agent
- 将对话段落整理成结构化的章节
- 章节按类别分类（童年、教育、职业、家庭、信念、总结等）

### 3. 用户认证
- 所有操作需要用户登录
- 使用JWT访问令牌进行认证
- WebSocket连接需要传递token参数

## WebSocket 消息格式

### 客户端发送

#### 文字消息
```json
{
  "type": "text",
  "conversation_id": "conversation-id",
  "data": {
    "text": "我小时候住在北京"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

#### 结束对话
```json
{
  "type": "end_conversation",
  "conversation_id": "conversation-id"
}
```

### 服务端返回

#### 连接确认
```json
{
  "type": "connect",
  "conversation_id": "conversation-id",
  "data": {
    "status": "connected"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

#### Agent 回应
```json
{
  "type": "agent_response",
  "conversation_id": "conversation-id",
  "data": {
    "text": "听起来很有趣！能告诉我更多关于你在北京的生活吗？"
  },
  "timestamp": "2024-01-15T10:30:05.000Z"
}
```

#### 对话结束确认
```json
{
  "type": "end_conversation",
  "conversation_id": "conversation-id",
  "data": {
    "status": "ended"
  },
  "timestamp": "2024-01-15T10:35:00.000Z"
}
```

## 使用流程

### 1. 用户注册/登录
```bash
POST /api/auth/register
{
  "phone": "13800138000",
  "password": "password123",
  "nickname": "用户昵称"
}

# 返回 access_token 和 refresh_token
```

### 2. 创建对话
```bash
POST /api/conversations
Authorization: Bearer {access_token}

# 返回 conversation_id
```

### 3. 连接 WebSocket
```
ws://localhost:8000/ws/conversation/{conversation_id}?token={access_token}
```

### 4. 发送文字消息
发送 `TEXT` 类型消息，接收 `AGENT_RESPONSE` 回应

### 5. 结束对话
发送 `END_CONVERSATION` 消息，系统自动整理章节

### 6. 查看章节
```bash
GET /api/chapters
Authorization: Bearer {access_token}
```

## 已移除的功能

- ❌ 音频块处理（`AUDIO_CHUNK`）
- ❌ 语音转文字（ASR）
- ❌ 文字转语音（TTS）
- ❌ 转写结果消息（`TRANSCRIPT`）
- ❌ TTS音频消息（`TTS_AUDIO`）

## 保留的功能

- ✅ 文字消息处理（`TEXT`）
- ✅ Agent 文字回应（`AGENT_RESPONSE`）
- ✅ 对话阶段检测
- ✅ 章节自动整理
- ✅ 用户认证
- ✅ 对话管理

## 注意事项

1. **WebSocket 连接必须提供 token**：`ws://.../ws/conversation/{id}?token={access_token}`
2. **所有对话记录都会保存**：用于后续章节整理
3. **章节整理在对话结束时触发**：发送 `END_CONVERSATION` 消息
4. **章节按类别自动分类**：系统会根据内容自动判断章节类别