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

# 文字交流模式说明

## 概述

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

## 功能特性

### 1. 智能对话引导
- 用户通过WebSocket发送 `TEXT` 类型的消息
- AI Agent 基于人生阶段（童年、教育、事业、家庭、信念）智能引导
- Agent 可能返回 1-3 条连续消息，像微信聊天一样自然
- 所有对话记录保存到数据库

### 2. 回忆录增量生成
- **实时处理**：每条用户消息都会触发后台异步分析
- **智能分类**：自动识别内容所属的人生阶段
- **增量写入**：新内容追加到对应章节，不覆盖已有内容
- **创意标题**：自动生成富有文学性的章节标题

### 3. 共享状态管理
- 对话 Agent 和回忆录 Agent 共享状态
- 状态包含：当前阶段、已完成阶段、各阶段已收集的信息片段
- 对话 Agent 根据状态智能选择下一个问题方向

### 4. 用户认证
- 所有操作需要用户登录
- 使用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": "听起来很有趣！能告诉我更多关于你在北京的生活吗？",
    "index": 0,
    "total": 1
  },
  "timestamp": "2024-01-15T10:30:05.000Z"
}
```

**多消息支持**：Agent 可能返回多条消息（最多3条），通过 `index` 和 `total` 字段标识：
- `index`: 当前消息序号（从0开始）
- `total`: 本次回复的总消息数

示例（Agent 返回2条消息）：
```json
// 第1条
{"type": "agent_response", "data": {"text": "那个小院子听起来很温馨。", "index": 0, "total": 2}}
// 第2条（约0.5秒后）
{"type": "agent_response", "data": {"text": "奶奶给你讲的故事里，有没有哪个让你印象特别深刻？", "index": 1, "total": 2}}
```

#### 对话结束确认
```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}

# 仅查看未读章节
GET /api/chapters?is_new=true
Authorization: Bearer {access_token}
```

### 7. 查看回忆录状态
```bash
GET /api/memoir-state
Authorization: Bearer {access_token}

# 返回示例
{
  "stage_order": ["childhood", "education", "career", "family", "belief"],
  "current_stage": "childhood",
  "covered_stages": [],
  "slots": {
    "childhood": {
      "place": {"snippet": "在南方一个小镇长大"},
      "people": {"snippet": "跟奶奶关系很好"},
      ...
    }
  }
}
```

### 8. 获取下一个问题方向
```bash
GET /api/memoir-state/next-question
Authorization: Bearer {access_token}

# 返回当前阶段和尚未覆盖的话题
{
  "current_stage": "childhood",
  "empty_slots": ["daily_life", "turning_event"],
  "covered_stages": []
}
```

### 9. 标记回忆录已读
```bash
POST /api/memoir-state/mark-read
Authorization: Bearer {access_token}
```

## 已移除的功能

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

## 保留的功能

- ✅ 文字消息处理（`TEXT`）
- ✅ Agent 多消息回应（`AGENT_RESPONSE`，支持连续 1-3 条）
- ✅ 智能对话阶段引导
- ✅ 回忆录增量生成（实时后台处理）
- ✅ 共享状态管理（回忆录状态 API）
- ✅ 用户认证
- ✅ 对话管理

## 注意事项

1. **WebSocket 连接必须提供 token**：`ws://.../ws/conversation/{id}?token={access_token}`
2. **所有对话记录都会保存**：用于后续章节整理
3. **章节增量生成**：每条消息都会触发后台异步分析，不必等对话结束
4. **章节按类别自动分类**：系统会根据内容自动判断章节类别
5. **多消息处理**：Agent 可能返回多条消息，客户端应根据 `index` 和 `total` 字段正确处理