024 Agent 1342a4c6

Agent 开发指南

本文档记录 SimpleLLMFunc 框架的开发经验和流程原则。

开发环境准备

1. 环境同步

进入项目目录后，首先同步依赖环境。

2. 运行测试

使用 pytest 运行相关测试文件。

3. 运行示例

使用 python 直接运行示例文件。

开发流程

步骤 1: 理解需求并阅读现有代码

关键原则：

• 先阅读 README 和文档了解框架设计理念
• 使用搜索工具查找关键代码模式
• 使用 glob 工具查找相关文件
• 阅读核心文件的实现，理解现有架构

搜索模式：

• 搜索事件流相关代码
• 搜索工具执行相关代码
• 搜索装饰器相关代码

步骤 2: 设计方案

根据需求设计：

• 新增/修改哪些文件
• 新增哪些类型/函数
• 保持向前向后兼容性

步骤 3: 单元测试先行

原则：先写测试，验证核心逻辑

• 创建测试文件
• 测试事件发射器的核心功能
• 验证事件类型定义

步骤 4: 实现功能

按依赖顺序实现：

1. 类型定义
2. 核心类
3. 执行逻辑修改
4. 导出更新

步骤 5: 运行测试验证

运行单元测试确保核心逻辑正确。

步骤 6: 创建示例并运行

创建实际使用示例，验证完整流程。

步骤 7: 提交代码

使用有意义的提交信息，描述做了什么修改。

调试技巧

1. 添加临时日志输出

当功能不工作时，在关键位置添加调试输出，观察变量值和执行路径。

2. 追踪问题根源

本例中的排查思路：

• 现象：自定义事件未显示
• 第一个怀疑点：event_emitter 是否正确传递
• 第二个怀疑点：工具函数参数检查方式是否正确
• 解决思路：从 Tool 对象获取 parameters 列表

3. 使用 .env 控制日志级别

设置 LOG_LEVEL=WARNING 减少无关日志干扰。

测试驱动开发 (TDD) 实践

1. 红灯-绿灯-重构循环

1. 红灯: 写一个会失败的测试
2. 绿灯: 写最少的代码让测试通过
3. 重构: 重构代码，测试仍然通过

2. 测试分层

• 单元测试: 测试独立组件（事件发射器、事件类型）
• 集成测试: 通过示例验证完整流程

3. 测试原则

• 每个新功能应该有对应的单元测试
• 测试应该覆盖核心逻辑边界情况

关键代码位置

常见问题排查

问题: 自定义事件不显示

排查方向：

1. 检查 event_emitter 是否为 None
2. 检查工具函数签名参数检查方式
3. 检查 Tool 对象的 parameters 列表
4. 检查事件是否正确放入队列

问题: poetry 环境问题

尝试重新同步依赖。

Git 工作流

1. 从 dev 创建功能分支
2. 开发并提交，提交信息使用英文
3. 推送到远程

经验总结

1. 先读文档和代码: 理解框架设计后再动手
2. 单元测试验证核心逻辑: 独立测试新功能
3. 示例验证完整流程: 端到端测试
4. 调试时加日志: 逐步追踪问题
5. 保持提交小而专注: 每次提交只做一件事