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. 测试原则

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

## 关键代码位置

| 功能 | 文件位置 |
|------|----------|
| 事件类型定义 | hooks/events.py |
| 事件发射器 | hooks/event_emitter.py |
| ReAct 循环 | base/ReAct.py |
| 工具执行 | base/tool_call/execution.py |
| Tool 装饰器 | tool/tool.py |
| 工具注册 | llm_decorator/utils/tools.py |

## 常见问题排查

### 问题: 自定义事件不显示

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

### 问题: poetry 环境问题

尝试重新同步依赖。

## Git 工作流

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

## 经验总结

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