ss

2026-01-22 09:59:02 +08:00
parent 47dac9f33b
commit f7702f4e72
18 changed files with 8012 additions and 104 deletions
--- a/聊天智能体示例说明.md
+++ b/聊天智能体示例说明.md
@@ -0,0 +1,337 @@
+# 智能聊天Agent完整示例说明
+
+## 📋 概述
+
+这是一个完整的聊天智能体示例，展示了如何使用平台的核心能力构建一个功能完善的聊天助手。该示例包含了记忆管理、意图识别、多分支路由、上下文传递等核心功能。
+
+## 🎯 功能特性
+
+### ✅ 核心能力展示
+
+1. **记忆管理**
+   - 使用缓存节点存储对话历史
+   - 支持用户画像和上下文信息
+   - 自动更新记忆内容
+
+2. **意图识别**
+   - 使用LLM节点分析用户意图
+   - 识别情感状态
+   - 提取关键词和话题
+
+3. **多分支路由**
+   - 使用Switch节点根据意图分发
+   - 支持6种不同场景的处理分支
+   - 默认分支处理未知意图
+
+4. **上下文传递**
+   - 使用Transform节点合并数据
+   - 保持对话历史的连贯性
+   - 支持多轮对话
+
+5. **个性化回复**
+   - 根据不同意图生成针对性回复
+   - 考虑用户情感状态
+   - 保持对话风格一致
+
+## 🔄 工作流结构
+
+```
+开始节点
+  ↓
+查询记忆（Cache节点）
+  ↓
+合并上下文（Transform节点）
+  ↓
+意图理解（LLM节点）
+  ↓
+意图路由（Switch节点）
+  ├─→ 问候处理（greeting）
+  ├─→ 问题回答（question）
+  ├─→ 情感回应（emotion）
+  ├─→ 请求处理（request）
+  ├─→ 告别回复（goodbye）
+  └─→ 通用回复（default）
+  ↓
+合并回复（Merge节点）
+  ↓
+更新记忆（Cache节点）
+  ↓
+格式化回复（LLM节点）
+  ↓
+结束节点
+```
+
+## 📊 节点详细说明
+
+### 1. 开始节点（start-1）
+- **功能**: 接收用户输入
+- **输入格式**: JSON格式，包含 `query` 字段
+- **输出**: 将用户输入传递给后续节点
+
+### 2. 查询记忆节点（cache-query）
+- **类型**: Cache节点
+- **操作**: `get` - 获取用户记忆
+- **Key**: `user_memory_{user_id}`
+- **默认值**: 空记忆结构
+- **功能**: 从缓存中读取用户的对话历史和画像信息
+
+### 3. 合并上下文节点（transform-merge）
+- **类型**: Transform节点
+- **模式**: `merge` - 合并模式
+- **功能**: 将用户输入、记忆数据、时间戳合并为完整上下文
+
+### 4. 意图理解节点（llm-intent）
+- **类型**: LLM节点
+- **模型**: DeepSeek Chat
+- **功能**: 
+  - 分析用户输入
+  - 识别意图类型（greeting/question/emotion/request/goodbye/other）
+  - 识别情感状态（positive/neutral/negative）
+  - 提取关键词和话题
+- **输出格式**: JSON
+  ```json
+  {
+    "intent": "意图类型",
+    "emotion": "情感状态",
+    "keywords": ["关键词"],
+    "topic": "话题主题",
+    "needs_response": true
+  }
+  ```
+
+### 5. 意图路由节点（switch-intent）
+- **类型**: Switch节点
+- **功能**: 根据意图类型路由到不同的处理分支
+- **分支**:
+  - `greeting` → 问候处理
+  - `question` → 问题回答
+  - `emotion` → 情感回应
+  - `request` → 请求处理
+  - `goodbye` → 告别回复
+  - `default` → 通用回复
+
+### 6. 各分支处理节点（llm-*）
+- **类型**: LLM节点
+- **功能**: 根据不同意图生成针对性的回复
+- **特点**:
+  - 问候分支：友好、亲切
+  - 问题分支：准确、详细
+  - 情感分支：共情、温暖
+  - 请求分支：专业、清晰
+  - 告别分支：温暖、期待
+  - 通用分支：自然、连贯
+
+### 7. 合并回复节点（merge-response）
+- **类型**: Merge节点
+- **模式**: `merge_first` - 合并第一个结果
+- **功能**: 将各分支的回复结果合并
+
+### 8. 更新记忆节点（cache-update）
+- **类型**: Cache节点
+- **操作**: `set` - 设置记忆
+- **功能**: 
+  - 将本次对话添加到历史记录
+  - 更新用户画像（如需要）
+  - 保存上下文信息
+- **TTL**: 86400秒（24小时）
+
+### 9. 格式化回复节点（llm-format）
+- **类型**: LLM节点
+- **功能**: 对最终回复进行格式化和优化
+- **输出**: 自然、流畅的文本回复
+
+### 10. 结束节点（end-1）
+- **功能**: 返回最终回复
+- **输出格式**: 纯文本
+
+## 🚀 使用方法
+
+### 方法一：使用生成脚本（推荐）
+
+```bash
+cd backend/scripts
+python3 generate_chat_agent.py
+```
+
+脚本会自动创建Agent，包含完整的工作流配置。
+
+### 方法二：手动创建
+
+1. **进入Agent管理页面**
+   - 点击"创建Agent"按钮
+   - 填写名称和描述
+
+2. **进入工作流编辑器**
+   - 点击"设计"按钮
+   - 使用节点工具箱添加节点
+   - 按照工作流结构连接节点
+
+3. **配置节点**
+   - **LLM节点**: 配置API密钥、模型、Prompt
+   - **Cache节点**: 配置缓存Key和操作
+   - **Switch节点**: 配置路由规则
+   - **Transform节点**: 配置数据映射
+
+4. **测试Agent**
+   - 点击"测试"按钮
+   - 输入测试消息
+   - 查看执行结果
+
+5. **发布Agent**
+   - 点击"发布"按钮
+   - Agent状态变为"已发布"
+   - 可以开始使用
+
+## 📝 配置要点
+
+### 1. LLM节点配置
+
+- **Provider**: 选择AI模型提供商（如DeepSeek、OpenAI）
+- **Model**: 选择具体模型（如deepseek-chat、gpt-3.5-turbo）
+- **Temperature**: 
+  - 意图识别：0.3（需要准确性）
+  - 情感回应：0.8（需要创造性）
+  - 问题回答：0.5（平衡准确性和灵活性）
+- **Max Tokens**: 根据回复长度需求设置
+- **Prompt**: 明确角色、任务、输出格式要求
+
+### 2. Cache节点配置
+
+- **Operation**: 
+  - `get`: 查询记忆
+  - `set`: 更新记忆
+- **Key**: 使用用户ID确保记忆隔离
+- **TTL**: 设置合适的过期时间（如24小时）
+
+### 3. Switch节点配置
+
+- **Field**: 指定用于路由的字段（如`intent`）
+- **Cases**: 配置各分支的路由规则
+- **Default**: 配置默认分支
+
+### 4. Transform节点配置
+
+- **Mode**: 选择合并模式（`merge`）
+- **Mapping**: 配置数据映射规则
+- **变量引用**: 使用`{{variable}}`引用上游数据
+
+## 🎨 自定义扩展
+
+### 1. 添加新的意图分支
+
+1. 在Switch节点中添加新的case
+2. 创建对应的LLM处理节点
+3. 连接Switch节点和处理节点
+4. 连接处理节点到Merge节点
+
+### 2. 增强记忆功能
+
+- 添加用户画像更新逻辑
+- 实现长期记忆和短期记忆分离
+- 添加记忆检索和总结功能
+
+### 3. 添加外部工具
+
+- 集成知识库查询
+- 添加天气、新闻等外部API
+- 实现文件处理功能
+
+### 4. 优化回复质量
+
+- 添加回复质量评估节点
+- 实现多候选回复生成和选择
+- 添加回复风格控制
+
+## 🔍 测试示例
+
+### 测试用例1：问候
+```
+输入: "你好"
+预期: 友好的问候回复
+```
+
+### 测试用例2：问题
+```
+输入: "今天天气怎么样？"
+预期: 尝试回答问题或说明无法获取天气信息
+```
+
+### 测试用例3：情感表达
+```
+输入: "我今天心情不太好"
+预期: 共情、安慰的回复
+```
+
+### 测试用例4：请求
+```
+输入: "帮我写一首诗"
+预期: 生成诗歌或说明能力范围
+```
+
+### 测试用例5：告别
+```
+输入: "再见"
+预期: 温暖的告别回复
+```
+
+## ⚠️ 注意事项
+
+1. **API密钥配置**
+   - 确保所有LLM节点都配置了有效的API密钥
+   - 检查API配额和限制
+
+2. **记忆管理**
+   - Cache节点使用内存缓存，重启后会丢失
+   - 生产环境建议使用Redis等持久化缓存
+
+3. **性能优化**
+   - 减少不必要的LLM调用
+   - 优化Prompt长度
+   - 合理设置Token限制
+
+4. **错误处理**
+   - 添加错误处理节点
+   - 配置重试机制
+   - 提供友好的错误提示
+
+## 📚 相关文档
+
+- [创建Agent经验总结](./创建Agent经验.md)
+- [工作流节点类型说明](./可新增节点类型建议.md)
+- [Agent使用说明](./Agent使用说明.md)
+
+## 🎯 适用场景
+
+- ✅ 情感陪聊助手
+- ✅ 客服机器人
+- ✅ 智能问答系统
+- ✅ 对话式AI应用
+- ✅ 个性化聊天助手
+
+## 💡 最佳实践
+
+1. **Prompt设计**
+   - 明确角色定位
+   - 明确输出格式
+   - 提供示例和上下文
+
+2. **工作流设计**
+   - 保持流程清晰
+   - 合理使用分支
+   - 避免过度复杂
+
+3. **记忆管理**
+   - 定期清理过期记忆
+   - 控制记忆大小
+   - 保护用户隐私
+
+4. **测试验证**
+   - 覆盖各种场景
+   - 测试边界情况
+   - 验证回复质量
+
+---
+
+**创建时间**: 2024年
+**版本**: 1.0
+**作者**: AI Agent Platform