Files

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL

2026-01-24 19:33:28 +08:00

8.9 KiB

Raw Blame History

陪练功能基础信息

一、功能概述

业务场景

考培练系统为轻医美连锁品牌提供AI陪练功能，通过模拟真实客户场景，让学员进行实战对话练习。

两种陪练入口

1. 陪练中心（直接模式）

URL: http://localhost:3001/trainee/ai-practice-center
流程: 选择预设场景 → 直接调用Coze开始陪练
场景来源: 数据库中的预设场景（practice_scenes表）

2. 课程中心（课程模式）

URL: http://localhost:3001/trainee/course-center
流程: 点击课程陪练 → Dify提取场景 → Coze开始陪练
场景来源: Dify根据课程内容动态生成

二、Coze配置信息

认证方式（更新于 2025-11-16）

系统使用 OAuth认证（JWT + 私钥签名），不再使用Personal Access Token (PAT)。

OAuth配置（后端环境变量）

# OAuth认证配置
COZE_OAUTH_CLIENT_ID=1114009328887
COZE_OAUTH_PUBLIC_KEY_ID=GGs9pw0BDHx2k9vGGehUyRgKV-PyUWLBncDs-YNNN_I
COZE_OAUTH_PRIVATE_KEY_PATH=/app/secrets/coze_private_key.pem
COZE_PRACTICE_BOT_ID=7560643598174683145

# API配置（关键：必须使用中国区）
COZE_API_BASE=https://api.coze.cn

私钥文件位置

宿主机: /root/aiedu/kaopeilian-backend/secrets/coze_private_key.pem
容器内: /app/secrets/coze_private_key.pem
权限: 600（仅所有者可读写）
Docker挂载: ./kaopeilian-backend/secrets:/app/secrets:ro（只读）

重要提示

⚠️ JWTAuth必须指定 base_url='https://api.coze.cn'，否则会使用国际版导致认证失败

官方资源

API文档: https://www.coze.cn/open/docs/developer_guides/chat_v3
OAuth文档: https://www.coze.cn/open/docs/developer_guides/oauth
Python SDK: https://github.com/coze-dev/coze-py
SDK版本: cozepy>=0.19.0

Bot信息

Bot ID: 7560643598174683145
应用ID: 1114009328887
功能: AI模拟客户陪练，支持多轮对话
特性: 实时流式响应，可自定义场景角色

三、Dify配置信息

API配置

DIFY_API_BASE = "http://dify.ireborn.com.cn/v1"
DIFY_PRACTICE_API_KEY = "app-rYP6LNM4iPmNjIHns12zFeJp"
DIFY_PRACTICE_WORKFLOW_ID = "待确认"  # 需要从Dify创建工作流后获取

调用示例

curl -X POST 'http://dify.ireborn.com.cn/v1/workflows/run' \
--header 'Authorization: Bearer app-rYP6LNM4iPmNjIHns12zFeJp' \
--header 'Content-Type: application/json' \
--data-raw '{
  "inputs": {
    "course_id": "5"
  },
  "response_mode": "streaming",
  "user": "kaopeilian"
}'

工作流说明

输入参数: course_id（课程ID）
响应模式: streaming（流式返回）
输出格式: JSON场景数据（包含name、description、background、ai_role、objectives等）

四、技术架构

核心技术栈

前端: Vue3 + Element Plus
后端: Python + FastAPI
数据库: MySQL 8.0（存储场景数据）
AI对话: Coze Bot（字节跳动）
场景提取: Dify工作流
通信协议: SSE (Server-Sent Events)

数据存储策略

场景数据: 存储在MySQL的practice_scenes表
对话历史: 由Coze平台管理，不存储在本地数据库

五、规划文档

已完成文档

✅ Coze-API文档.md - Coze API核心使用方法
✅ 陪练功能技术方案.md - 完整技术架构和实现方案
✅ 陪练功能API接口规范.md - 前后端API接口详细规范
✅ 陪练功能数据流程图.md - 数据流程和时序图
✅ 规范与约定-团队基线.md - 更新了陪练功能相关规范

文档位置

所有规划文档位于：考培练系统规划/全链路联调/Ai工作流/coze/

六、参考代码

可用参考代码位置

Coze Python SDK: 参考代码/coze-py-main/
- 示例代码：examples/chat_stream.py（流式对话）
- 示例代码：examples/chat_simple_audio.py（音频对话）
Coze后端参考: 参考代码/coze-chat-backend/
- main.py - FastAPI集成示例
- auth.py - Coze认证方式
- config.py - 配置管理
Coze前端参考: 参考代码/coze-chat-frontend/
- React + TypeScript实现
- SSE流式对话处理示例

已有页面

陪练中心页面: kaopeilian-frontend/src/views/trainee/ai-practice-center.vue（前端已实现）
场景管理页面: kaopeilian-frontend/src/views/manager/practice-scene-management.vue（前端已实现）
对话页面: 待开发（可参考Training模块）

核心参考代码（新发现）

Training模块: 参考代码/coze-chat-frontend/src/pages/Training/
- index.tsx - 主入口（20行）
- TextChat.tsx - 文本对话实现（68行）
- VoiceChat.tsx - 语音对话实现（225行）
- TrainingStore.ts - 核心状态管理（525行） ⭐ 重点参考

TrainingStore.ts核心功能：

✅ SSE流式对话处理（使用@ant-design/x的XStream）
✅ WebSocket语音对话（使用@coze/api/ws-tools）
✅ 消息列表管理（增量更新、删除、重新生成）
✅ 对话状态管理（6种状态：未连接、连接中、已连接、聆听、回复中、错误）
✅ 文件上传支持
✅ 错误处理和重试
✅ AbortController中断控制

七、开发路线图

第一阶段：数据库与基础API（2天）

创建practice_scenes表
插入初始场景数据
实现场景管理API（CRUD）

第二阶段：前端管理页面（2天）

场景管理页面开发
表单验证与提交
列表筛选与分页

第三阶段：Coze集成（3天）

Coze SDK集成
流式对话API实现
陪练对话页面开发

第四阶段：Dify集成（2天）

Dify场景提取API
课程中心集成

第五阶段：联调与优化（2天）

端到端测试
错误处理完善
性能优化

预计总工期: 11个工作日

八、关键技术点

⚠️ 场景提示词构建（核心差异）

与参考代码的关键不同：

参考代码：用户直接与Bot对话，无场景概念
考培练系统：首次消息必须包含完整场景设定

实现方式：

# 后端：首次消息时构建场景提示词
if is_first:
    scene_prompt = f"""
# 陪练场景设定

## 场景名称
{scene_name}

## 场景背景
{scene_background}

## AI角色要求
{scene_ai_role}

## 练习目标
{chr(10).join(f"{i+1}. {obj}" for i, obj in enumerate(scene_objectives))}

---

现在开始陪练对话。请严格按照上述设定扮演角色。

学员的第一句话：{user_message}
"""
    # 发送完整提示词给Coze
    Message.build_user_question_text(scene_prompt)
else:
    # 后续消息仅发送用户输入
    Message.build_user_question_text(user_message)

为什么这样设计：

让AI明确理解要扮演的角色
保持对话上下文（使用conversation_id）
后续消息无需重复场景信息
用户界面不显示场景设定文本

SSE流式通信

// 前端处理SSE事件
const response = await fetch('/api/v1/practice/start', {
  method: 'POST',
  body: JSON.stringify({
    scene_name: scene.name,
    scene_background: scene.background,
    scene_ai_role: scene.ai_role,
    scene_objectives: scene.objectives,
    user_message: userInput,
    is_first: true  // 标记首次消息
  })
})

const reader = response.body.getReader()
const decoder = new TextDecoder()

while (true) {
  const { value, done } = await reader.read()
  if (done) break
  
  const chunk = decoder.decode(value)
  // 解析 event: xxx\ndata: {...}\n\n 格式
}

Coze流式对话

# 后端调用Coze
from cozepy import Coze, TokenAuth, Message, ChatEventType

stream = coze.chat.stream(
    bot_id=COZE_PRACTICE_BOT_ID,
    user_id=user_id,
    additional_messages=[Message.build_user_question_text(message)],
    conversation_id=conversation_id  # 保持对话上下文
)

for event in stream:
    if event.event == ChatEventType.CONVERSATION_MESSAGE_DELTA:
        # 发送SSE增量事件
        yield f"event: message.delta\ndata: {json.dumps({'content': event.message.content})}\n\n"

九、注意事项

安全性

Token不要提交到版本控制
使用环境变量管理敏感配置
API调用添加速率限制

性能

SSE连接超时设置为180秒
数据库查询使用索引
前端消息列表使用虚拟滚动

用户体验

实现打字效果（message.delta）

如有技术问题，请参考：

Coze API文档：Coze-API文档.md
技术方案文档：陪练功能技术方案.md
API接口规范：陪练功能API接口规范.md
数据流程图：陪练功能数据流程图.md
OAuth认证规范：../../规范与约定-团队基线.md
完整迁移报告：/root/aiedu/OAUTH_MIGRATION_SUCCESS.md

文档版本: v2.0
最后更新: 2025-11-16
维护人: 考培练系统开发团队
重大更新: OAuth认证迁移完成

8.9 KiB Raw Blame History Unescape Escape