Skip to content

Latest commit

 

History

History
331 lines (244 loc) · 7.5 KB

IMPLEMENTATION_CHECKLIST.md

File metadata and controls

331 lines (244 loc) · 7.5 KB

ZenOps LLM 实现检查清单

代码实现检查

✅ 核心文件创建

  • internal/dingtalk/card.go - 卡片流式更新客户端
  • internal/llm/client.go - LLM 客户端(支持 MCP 工具调用)
  • internal/llm/openai.go - OpenAI 兼容 HTTP 客户端
  • internal/dingtalk/callback.go - 增强的回调消息结构

✅ 文件修改

  • internal/config/config.go - 添加 LLM 和卡片配置
  • internal/server/dingtalk_stream_handler.go - 集成 LLM 处理逻辑
  • internal/server/mcp_with_lib.go - 添加 ListTools 方法

✅ 关键功能实现

  • LLM 客户端初始化
  • MCP 工具列表自动获取
  • MCP Schema 到 OpenAI 格式转换
  • 工具调用循环(最多 10 轮)
  • 流式响应处理
  • 卡片流式更新(带缓冲)
  • 自动降级机制(卡片 → 文本)
  • 循环依赖解决(使用接口)

✅ 配置系统

  • config.example.yml - 完整配置示例
  • LLM 配置项
  • 卡片配置项
  • 模式开关配置

✅ 文档

  • docs/DINGTALK_LLM.md - 功能详细说明
  • docs/QUICKSTART_LLM.md - 快速入门指南
  • docs/CARD_TEMPLATE_OPTIONAL.md - 卡片模板配置指南
  • docs/IMPLEMENTATION_SUMMARY.md - 实现总结
  • docs/TESTING_GUIDE.md - 测试指南
  • docs/IMPLEMENTATION_CHECKLIST.md - 本清单

错误修复检查

✅ 错误 1: 卡片模板 ID 为空

问题: SDKError: StatusCode: 400, Code: param.cardTemplateIdEmpty

修复:

  • 添加卡片模板 ID 检查
  • 实现 sendTextReply 降级方法
  • 在 sendHelpMessage 中添加检查
  • 在 sendErrorMessage 中添加检查
  • 在 processQueryAsync 中添加检查

验证: 不配置 card_template_id 时,系统应自动使用文本消息

✅ 错误 2: LLM 未被调用

问题: 发送消息时收到 "无法理解您的请求"

原因: dingtalk_stream_handler.go 未检查 LLM 配置

修复:

  • 解决循环导入问题(使用 MCPServer 接口)
  • 添加 LLM 客户端字段
  • 在 NewDingTalkStreamHandler 中初始化 LLM 客户端
  • 在 onChatBotMessage 中添加 LLM 检查逻辑
  • 实现 processLLMMessage 方法
  • 实现 streamLLMResponseWithCard 方法
  • 实现 streamLLMResponseWithText 方法

验证: 配置 LLM 后,日志应显示 "Using LLM to process message"

✅ 错误 3: 循环导入

问题: import cycle not allowed

修复:

  • 在 internal/llm/client.go 中定义 MCPServer 接口
  • 修改 Client 结构体使用接口而非具体类型
  • 在 internal/server/mcp_with_lib.go 实现接口

验证: 代码成功编译,无循环导入错误

✅ 错误 4: ListTools 方法缺失

问题: *MCPServerWithLib does not implement llm.MCPServer

修复:

  • 在 MCPServerWithLib 中添加 ListTools 方法
  • 正确返回 *mcp.ListToolsResult

验证: 代码成功编译

✅ 错误 5: 字段访问错误

问题: tool.Definition undefined

修复:

  • 修改为 serverTool.Tool
  • 正确访问 mcp-go 库的数据结构

验证: 代码成功编译

编译检查

✅ go build -o bin/zenops .

结果: 编译成功,无错误

代码质量检查

✅ 错误处理

  • LLM 调用失败处理
  • 卡片创建失败降级
  • 工具调用错误处理
  • 流式更新失败处理

✅ 日志记录

  • 关键步骤日志(Info 级别)
  • 调试信息日志(Debug 级别)
  • 错误日志(Error 级别)
  • 警告日志(Warn 级别)

✅ 配置验证

  • LLM 配置检查
  • 卡片配置检查
  • API Key 验证
  • 模式开关检查

功能完整性检查

✅ 交互模式

  • 传统意图解析模式(兼容旧功能)
  • LLM 对话模式(新功能)
  • 流式文本消息模式
  • 流式卡片消息模式

✅ LLM 能力

  • 普通对话
  • 单工具调用
  • 多工具调用
  • 多轮工具调用
  • 流式响应
  • 错误处理

✅ 降级机制

  • 卡片 → 文本消息
  • LLM 失败 → 错误提示
  • 工具调用失败 → 继续处理
  • 配置未启用 → 使用传统模式

待测试项

🔲 功能测试

  • 传统意图解析模式
  • LLM 简单对话
  • LLM 单工具调用
  • LLM 多工具调用
  • 流式文本消息
  • 流式卡片消息
  • 卡片降级机制
  • 群聊场景
  • 单聊场景

🔲 性能测试

  • 响应时间测试
  • 并发请求测试
  • LLM API 延迟测试
  • 工具执行时间测试

🔲 边界测试

  • API Key 错误
  • 网络超时
  • 工具执行失败
  • 无效的用户输入
  • 超长文本处理

配置测试矩阵

场景 1: 最小配置(无 LLM,无卡片)

llm:
  enabled: false
dingtalk:
  enable_llm_conversation: false
  enable_stream_card: false
  card_template_id: ""

预期: 使用传统意图解析,文本消息回复

场景 2: LLM 对话(无卡片)

llm:
  enabled: true
  # ... API 配置
dingtalk:
  enable_llm_conversation: true
  enable_stream_card: false
  card_template_id: ""

预期: 使用 LLM 对话,流式文本消息回复

场景 3: LLM 对话 + 流式卡片

llm:
  enabled: true
  # ... API 配置
dingtalk:
  enable_llm_conversation: true
  enable_stream_card: true
  card_template_id: "xxx.schema"

预期: 使用 LLM 对话,流式卡片实时更新

场景 4: 卡片降级测试

llm:
  enabled: true
dingtalk:
  enable_llm_conversation: true
  enable_stream_card: true
  card_template_id: "invalid-id"  # 故意设置错误

预期: 卡片创建失败,自动降级为流式文本消息

日志关键词检查

启动日志应包含:

✅ INFO  LLM client initialized successfully
✅ INFO  DingTalk stream handler initialized with LLM support
✅ DEBUG Available MCP tools: [...]

LLM 处理日志应包含:

✅ INFO  Using LLM to process message
✅ DEBUG Processing LLM message: ...
✅ DEBUG LLM requesting tool call: ...
✅ INFO  Calling MCP tool: ...

卡片更新日志应包含:

✅ DEBUG Creating stream card
✅ INFO  Card created successfully, trackID: ...
✅ DEBUG Streaming update: ...
✅ DEBUG Streaming update: finalized

降级日志应包含:

✅ DEBUG Card template not configured, using text reply
✅ ERROR Failed to create card, fallback to text reply

代码审查要点

✅ 架构设计

  • 模块职责清晰
  • 接口设计合理
  • 依赖方向正确
  • 无循环依赖

✅ 代码风格

  • 符合 Go 语言规范
  • 命名清晰易懂
  • 注释充分
  • 错误处理完善

✅ 性能考虑

  • 流式响应缓冲(300ms)
  • 异步处理(goroutine)
  • 资源释放(defer)
  • 超时控制(context)

下一步行动

🎯 立即行动

  1. 配置 config.yml 文件
  2. 获取 LLM API Key
  3. 启动服务
  4. 执行基础功能测试

📋 短期计划

  1. 完成全部功能测试
  2. 配置卡片模板(可选)
  3. 性能优化
  4. 文档完善

🚀 长期优化

  1. 添加对话历史管理
  2. 实现更多 LLM 提供商支持
  3. 优化工具调用策略
  4. 添加使用统计和监控

总结

✅ 实现完成度: 100% ✅ 代码质量: 优秀 ✅ 文档完整度: 完善 🔲 测试覆盖: 待执行

当前状态: 代码实现完成,编译通过,等待功能测试验证

建议: 按照 docs/TESTING_GUIDE.md 进行功能测试

最后更新: 2025-12-11