012-kaopeilian/docs/规划/全链路联调/Ai工作流/coze/⚠️核心差异点速查.md

⚠️ 核心差异点速查卡

考培练系统 vs 参考代码的关键不同

🎯 最重要的差异：场景提示词

参考代码（简单对话）

// 直接发送用户消息
await startChatStream({
  content: "你好",  // 仅用户输入
  bot_id: "7509379008556089379",
  user_id: "user_123"
})

考培练系统（场景驱动）

// 首次消息：场景信息 + 用户输入
await fetch('/api/v1/practice/start', {
  method: 'POST',
  body: JSON.stringify({
    // ⚠️ 完整场景信息
    scene_name: "初次电话拜访客户",
    scene_background: "你是一名销售专员...",
    scene_ai_role: "AI扮演一位忙碌的采购经理...",
    scene_objectives: ["学会专业开场白", "建立信任"],
    scene_keywords: ["开场白", "需求挖掘"],
    
    // 用户输入
    user_message: "您好，我是XX公司的销售顾问",
    
    // ⚠️ 首次标记
    is_first: true
  })
})

// 后续消息：仅用户输入
await fetch('/api/v1/practice/start', {
  method: 'POST',
  body: JSON.stringify({
    user_message: "我们提供轻医美整体解决方案",
    conversation_id: "conv_abc123",  // 保持上下文
    is_first: false  // 不再包含场景信息
  })
})

📝 后端场景提示词构建

标准模板（Python）

if request.is_first:
    scene_prompt = f"""
# 陪练场景设定

## 场景名称
{request.scene_name}

## 场景描述
{request.scene_description}

## 场景背景
{request.scene_background}

## AI角色要求
{request.scene_ai_role}

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

## 关键词
{', '.join(request.scene_keywords)}

---

现在开始陪练对话。请你严格按照上述场景设定扮演角色，与学员进行实战对话练习。
不要提及"场景设定"或"角色扮演"等元信息，直接进入角色开始对话。

学员的第一句话：{request.user_message}
"""
    # 发送给Coze
    stream = coze.chat.stream(
        bot_id=COZE_PRACTICE_BOT_ID,
        user_id=user_id,
        additional_messages=[Message.build_user_question_text(scene_prompt)]
    )
else:
    # 后续消息直接发送
    stream = coze.chat.stream(
        bot_id=COZE_PRACTICE_BOT_ID,
        user_id=user_id,
        additional_messages=[Message.build_user_question_text(request.user_message)],
        conversation_id=request.conversation_id  # 使用同一个对话ID
    )

🔄 完整对话流程对比

参考代码流程

用户输入 "你好"
  ↓
发送给Coze: "你好"
  ↓
AI回复: "你好，我是AI助手..."
  ↓
用户继续输入...

考培练系统流程

用户在场景确认页面点击"开始陪练"
  ↓
用户输入第一句话 "您好，我是XX公司的销售顾问"
  ↓
后端构建完整提示词:
  """
  # 陪练场景设定
  ## 场景名称: 初次电话拜访客户
  ## 场景背景: 你是一名销售专员...
  ## AI角色要求: AI扮演一位忙碌的采购经理...
  ## 练习目标:
  1. 学会专业的电话开场白
  2. 快速建立信任关系
  ---
  现在开始陪练。学员第一句话：您好，我是XX公司的销售顾问
  """
  ↓
发送给Coze: 完整提示词（Markdown格式）
  ↓
AI理解场景后回复: "喂？什么事？我现在很忙..."（扮演采购经理）
  ↓
用户继续输入 "我想占用您几分钟..."
  ↓
发送给Coze: "我想占用您几分钟..."（仅用户输入，不含场景）
  ↓
AI继续扮演角色回复...

💡 为什么这样设计？

1. AI角色一致性

• 问题：如果不传场景信息，AI可能无法理解要扮演什么角色
• 解决：首次消息包含完整场景设定，让AI明确角色

2. 对话上下文保持

• 机制：使用conversation_id续接对话
• 效果：后续消息AI会记住场景设定，无需重复发送

3. 性能优化

• 首次：发送完整提示词（~500字符）
• 后续：仅发送用户输入（~50字符）
• 节省：减少Token消耗，提升响应速度

4. 用户体验

• 界面显示：用户仅看到自己的输入，不看到场景设定文本
• 沉浸感：用户专注于对话，不被技术细节干扰

📋 实现检查清单

后端实现

• 判断is_first标记
• 构建Markdown格式场景提示词
• 拼接user_message
• 发送给Coze
• 保存conversation_id

前端实现

• 页面加载时获取场景信息
• 首次发送时携带完整场景参数
• 设置is_first=true
• 保存返回的conversation_id
• 后续消息仅发送user_message和conversation_id
• 设置is_first=false

测试验证

• 首次消息AI回复符合场景角色
• 后续消息AI持续扮演角色
• conversation_id正确续接
• 场景信息不显示在消息列表中

🚨 常见错误

❌ 错误1：每次都发送场景信息

# 错误示范
stream = coze.chat.stream(
    additional_messages=[Message.build_user_question_text(
        scene_prompt + user_message  # 每次都拼接，浪费Token
    )]
)

✅ 正确：仅首次发送

# 正确示范
if is_first:
    message_content = scene_prompt + user_message
else:
    message_content = user_message

stream = coze.chat.stream(
    additional_messages=[Message.build_user_question_text(message_content)],
    conversation_id=conversation_id  # 关键：保持上下文
)

❌ 错误2：不保存conversation_id

# 错误示范：每次创建新对话
stream = coze.chat.stream(
    bot_id=bot_id,
    user_id=user_id,
    additional_messages=[...]
    # 没有传conversation_id，AI会忘记场景
)

✅ 正确：保持对话连续性

# 正确示范
stream = coze.chat.stream(
    bot_id=bot_id,
    user_id=user_id,
    additional_messages=[...],
    conversation_id=saved_conversation_id  # 使用同一个ID
)

❌ 错误3：前端显示场景提示词

// 错误示范：用户看到场景设定文本
messageList.value.push({
  role: 'user',
  content: scenePrompt + userInput  // 显示完整提示词
})

✅ 正确：仅显示用户输入

// 正确示范：用户仅看到自己的输入
messageList.value.push({
  role: 'user',
  content: userInput  // 仅显示用户输入
})

// 后端负责拼接场景信息

📊 数据流示例

首次消息数据流

前端发送:
{
  scene_name: "初次电话拜访",
  scene_background: "...",
  scene_ai_role: "...",
  scene_objectives: [...],
  user_message: "您好",
  is_first: true
}
  ↓
后端构建:
"""
# 陪练场景设定
## 场景名称: 初次电话拜访
...
学员第一句话：您好
"""
  ↓
发送给Coze:
Message.build_user_question_text(完整提示词)
  ↓
前端显示:
用户: 您好
AI: 喂？什么事？

后续消息数据流

前端发送:
{
  user_message: "我想占用您几分钟",
  conversation_id: "conv_abc123",
  is_first: false
}
  ↓
后端直接发送:
Message.build_user_question_text("我想占用您几分钟")
  ↓
发送给Coze:
使用conversation_id, AI记住之前的场景
  ↓
前端显示:
用户: 我想占用您几分钟
AI: 好吧，说吧，你有什么产品？

🎓 学习建议

新手开发者

1. 先理解参考代码的基本对话流程
2. 再理解场景提示词的必要性
3. 对比两种实现方式的差异
4. 按照文档实现考培练版本

有经验开发者

1. 快速浏览参考代码结构
2. 重点关注场景提示词构建逻辑
3. 理解is_first标记的作用
4. 直接开始实现

📞 技术支持

遇到问题时查阅：

1. 场景不生效 → 检查is_first标记和提示词构建
2. AI忘记角色 → 检查conversation_id是否正确续接
3. Token消耗大 → 检查是否每次都发送场景信息
4. 前端显示问题 → 检查消息列表是否只显示user_message

---

版本：v1.0 更新：2025-10-13 维护：考培练系统开发团队

快速链接：

• 完整技术方案
• API接口规范
• 参考代码分析
• 开发任务清单