012-kaopeilian/docs/规划/全链路联调/Ai工作流/coze

陪练功能开发文档

📚 文档导航

本目录包含考培练系统AI陪练功能的完整开发文档。

---

🎯 快速开始

新成员必读

1. ⚠️核心差异点速查.md（5分钟）- 与参考代码的关键不同
2. 基础信息.md（5分钟）- 功能概述和配置信息
3. README.md（本文档）- 文档导航

开发人员

后端开发：

1. Coze-API文档.md - Coze API使用指南
2. 陪练功能API接口规范.md - 14个API接口定义
3. 陪练分析报告-数据结构与Dify规范.md - Dify工作流规范

前端开发：

1. 参考代码分析-Training模块.md - React到Vue3迁移方案
2. 陪练功能API接口规范.md - 前端API调用
3. 陪练功能数据流程图.md - 数据流程

---

✅ 完成报告

已完成功能

1. ✅陪练中心入口开发完成报告.md - 预设场景陪练（文本模式）
2. ✅语音陪练功能完成报告.md - 语音对话功能
3. ✅课程中心陪练入口开发完成报告.md - 课程场景提取
4. ✅陪练分析报告功能完成报告.md - AI分析报告

---

📖 技术文档

核心技术文档

Coze集成：

• Coze-API文档.md - Coze WebSocket API完整使用指南
• ⚠️核心差异点速查.md - 场景提示词构建要点

API规范：

• 陪练功能API接口规范.md - 14个API接口详细定义
• 陪练分析报告-数据结构与Dify规范.md - Dify工作流输入输出

数据流程：

• 陪练功能数据流程图.md - 完整流程图和时序图
• 陪练功能技术方案.md - 技术架构和实现方案

参考代码：

• 参考代码分析-Training模块.md - React实现深度解析和Vue3迁移

基础信息：

• 基础信息.md - 功能概述、配置信息、参考代码位置

---

🎯 核心功能

1. 语音陪练对话

• 前端@coze/api直连wss://ws.coze.cn
• 实时语音识别和播放
• 双方字幕实时显示
• 语音/文本模式切换

技术：WsChatClient + Agora SDK

2. 对话历史保存

• 实时保存到MySQL（practice_dialogues表）
• 会话管理（practice_sessions表）
• 异步保存，不阻塞对话

3. AI分析报告

• Dify工作流生成分析
• 5个维度评分
• 6个能力评估
• 对话标注（亮点/金牌话术）
• 改进建议

Dify API Key：app-9MWaCEiRegpYGQLov4S9oQjh

4. 报告展示

• practice-report.vue页面
• 合并数据库对话+Dify标注
• 雷达图可视化
• 对话筛选功能

5. 陪练记录

• practice-records.vue页面
• 列表查询和筛选
• 统计数据展示

---

📊 数据库表

4张表

1. practice_scenes - 陪练场景（5个预设场景）
2. practice_sessions - 陪练会话（记录时长、轮次）
3. practice_dialogues - 对话记录（逐条保存）
4. practice_reports - 分析报告（JSON存储）

---

🔌 API接口

14个接口

场景管理（2个）：

• GET /practice/scenes
• GET /practice/scenes/{id}

对话管理（3个）：

• POST /practice/start（SSE）
• POST /practice/interrupt
• POST /practice/conversation/create

会话管理（7个）：

• POST /practice/sessions/create
• POST /practice/dialogues/save
• POST /practice/sessions/{id}/end
• POST /practice/sessions/{id}/analyze
• GET /practice/reports/{id}
• GET /practice/sessions/list
• GET /practice/stats

场景提取（1个）：

• POST /practice/extract-scene

---

⚠️ 关键要点

场景提示词（最重要）

考培练系统与参考代码的核心差异：

• 首次消息必须包含完整场景设定
• 使用Markdown格式组织
• 后续消息只发送用户输入
• 详见：⚠️核心差异点速查.md

Dify对话标注格式

{
  "dialogue_annotations": [
    {"sequence": 1, "tags": ["金牌话术"], "comment": "..."}
  ]
}

重要：

• 完整对话来自数据库
• Dify只返回标注（sequence+tags+comment）
• 后端自动合并

语音识别技巧

• server_vad模式
• 说完话保持静音500ms
• 环境必须安静

---

📝 开发状态

已完成（100%）

• ✅ 语音陪练对话
• ✅ 对话历史保存
• ✅ AI分析报告
• ✅ 报告页面展示
• ✅ 陪练记录管理

测试通过

• ✅ 语音连接和播放
• ✅ 用户语音识别
• ✅ 对话实时保存
• ✅ Dify分析报告生成
• ✅ 对话标注匹配
• ✅ 报告页面数据展示

---

🎓 核心经验

1. 前端直连Coze - 比后端中转简单高效
2. 使用官方SDK - @coze/api稳定可靠
3. 对话数据分离 - 数据库存完整对话，Dify只做标注
4. 异步保存策略 - 保存失败不影响对话继续
5. 合理的数据结构 - 两张表分离（会话+对话）便于查询

---

📞 技术支持

遇到问题时查阅：

1. 场景不生效 → 核心差异点速查.md
2. 语音无法识别 → Coze-API文档.md（VAD配置）
3. API对接问题 → 陪练功能API接口规范.md
4. Dify格式问题 → 陪练分析报告-数据结构与Dify规范.md

---

文档维护：考培练系统开发团队
最后更新：2025-10-13
版本：v2.0（完整版）