感谢你对 MiniAgent 项目的关注！我们欢迎各种形式的贡献，包括但不限于：
- 🐛 报告 Bug
- 💡 提出新功能建议
- 📝 改进文档
- 🔧 提交代码修复
- 🧪 编写测试用例
- 📚 翻译文档
参与此项目即表示你同意遵守我们的行为准则。我们致力于为所有人提供友好、安全和包容的环境。
- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心
-
Fork 仓库
# 在 GitHub 上 fork 项目仓库 -
克隆你的 fork
git clone https://github.com/your-username/mini-agent.git cd mini-agent -
安装依赖
pip install -r requirements_mini.txt
-
设置上游仓库
git remote add upstream https://github.com/original-owner/mini-agent.git
-
运行测试
python test_mini.py
在报告 Bug 之前，请：
- 搜索现有 Issues - 确保问题尚未被报告
- 使用最新版本 - 确认问题在最新版本中仍然存在
- 提供详细信息 - 包含复现步骤、环境信息等
## Bug 描述
简洁清晰地描述这个 bug
## 复现步骤
1. 进入 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误
## 期望行为
清晰简洁地描述你期望发生什么
## 实际行为
清晰简洁地描述实际发生了什么
## 环境信息
- 操作系统: [例如 iOS]
- Python 版本: [例如 3.9]
- 项目版本: [例如 1.0.0]
## 附加信息
添加任何其他关于问题的上下文信息、截图等我们欢迎新功能建议！请：
- 搜索现有 Issues - 确保功能尚未被请求
- 详细描述 - 解释为什么需要这个功能
- 提供用例 - 描述具体的使用场景
## 功能描述
简洁清晰地描述你想要的功能
## 问题背景
这个功能请求是否与某个问题相关？请描述
## 解决方案
清晰简洁地描述你想要实现的解决方案
## 替代方案
清晰简洁地描述你考虑过的任何替代解决方案或功能
## 附加信息
添加任何其他关于功能请求的上下文信息或截图-
创建分支
git checkout -b feature/your-feature-name
-
进行更改
- 编写代码
- 添加/更新测试
- 更新文档
-
运行测试
python test_mini.py
-
提交更改
git add . git commit -m "feat: add your feature description"
-
推送到你的 fork
git push origin feature/your-feature-name
-
创建 Pull Request
- 修复现有功能中的错误
- 改进错误处理
- 性能优化
- 添加新的工具类
- 扩展现有功能
- 改进用户体验
- 修正文档错误
- 添加使用示例
- 改进代码注释
- 添加单元测试
- 改进测试覆盖率
- 添加集成测试
我们遵循 PEP 8 标准，建议使用以下工具：
# 代码格式化
pip install black
black .
# 代码检查
pip install flake8
flake8 .
# 类型检查
pip install mypy
mypy .- 类型提示 - 为函数参数和返回值添加类型提示
- 文档字符串 - 为类和函数添加清晰的文档字符串
- 错误处理 - 适当的异常处理和错误信息
- 测试覆盖 - 为新功能编写测试用例
from typing import Optional, Dict, Any
from pydantic import BaseModel
class ExampleTool(BaseTool):
"""示例工具类
这是一个工具类的示例，展示了标准的代码风格。
Attributes:
name: 工具名称
description: 工具描述
"""
name: str = "example_tool"
description: str = "这是一个示例工具"
async def execute(self, param: str, **kwargs) -> ToolResult:
"""执行工具逻辑
Args:
param: 输入参数
**kwargs: 额外参数
Returns:
ToolResult: 执行结果
Raises:
ValueError: 当参数无效时抛出
"""
try:
# 实现逻辑
result = self._process_param(param)
return ToolResult(success=True, output=result)
except Exception as e:
return ToolResult(success=False, error=str(e))
def _process_param(self, param: str) -> str:
"""处理参数的私有方法"""
if not param:
raise ValueError("参数不能为空")
return param.upper()我们使用 Conventional Commits 规范：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
feat: 新功能fix: Bug 修复docs: 文档更新style: 代码格式修改refactor: 代码重构test: 测试相关chore: 构建过程或辅助工具的变动
feat(tools): add web scraping tool
fix(agent): resolve memory leak in conversation history
docs(readme): update installation instructions
test(tools): add unit tests for file editor在提交 PR 之前，请确保：
- 代码遵循项目的代码规范
- 所有测试都通过
- 添加了必要的测试用例
- 更新了相关文档
- 提交消息符合规范
- PR 描述清晰明了
## 变更描述
简洁清晰地描述这个 PR 的变更内容
## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重大变更
- [ ] 文档更新
## 测试
- [ ] 通过现有测试
- [ ] 添加新测试
- [ ] 手动测试完成
## 检查清单
- [ ] 代码遵循项目规范
- [ ] 自我审查了代码
- [ ] 代码有适当的注释
- [ ] 更新了相关文档
- [ ] 变更不会产生新的警告- 自动检查 - CI 会自动运行测试和代码检查
- 代码审查 - 维护者会审查你的代码
- 反馈处理 - 根据反馈进行必要的修改
- 合并 - 审查通过后会被合并到主分支
mini_agent/
├── mini_agent/ # 核心模块
│ ├── __init__.py # 模块导出
│ ├── agent.py # 代理核心
│ ├── llm.py # LLM 接口
│ ├── schema.py # 数据结构
│ └── tools.py # 工具系统
├── examples.py # 使用示例
├── test_mini.py # 测试文件
└── main_mini.py # 主程序
- Agent - 智能代理的核心类
- Tool - 工具的抽象基类
- Memory - 对话记忆管理
- LLM - 语言模型接口
- 继承
BaseTool类 - 实现
execute方法 - 定义工具的 schema
- 添加测试用例
- 更新文档
- 在
agent.py中进行修改 - 确保向后兼容性
- 添加相应测试
- 更新示例代码
如果你有任何问题，可以：
- 查看文档 - 检查现有文档是否有答案
- 搜索 Issues - 查看是否有类似问题
- 创建 Issue - 描述你的问题
- 参与讨论 - 在 GitHub Discussions 中参与讨论
感谢所有为 MiniAgent 项目做出贡献的开发者！
记住：每一个贡献都很重要，无论大小！ 🌟