Sweep开源贡献指南：与AI开发助手共成长

欢迎加入Sweep开源社区！作为一款AI驱动的开发助手，Sweep致力于自动化处理小型功能开发和bug修复。通过贡献代码、文档或创意，你将直接参与构建下一代开发者工具，与全球开发者共同塑造AI辅助编程的未来。

🚀 为什么选择贡献Sweep？

成长收益

• 实践前沿技术：深入AI代码生成、向量数据库、代码分析等领域的实际应用
• 提升工程能力：在真实项目中实践Python/TypeScript开发、CI/CD流程和测试驱动开发
• 构建专业影响力：优质贡献将展示在项目文档和社区渠道

社区影响力可视化

• 贡献者名单永久展示在项目主页
• 月度活跃贡献者将获得社区 spotlight 推广
• 重要功能贡献者受邀参与项目决策会议
• PR合并后自动生成贡献统计图表

💡 小贴士：首次贡献者可从"good first issue"标签开始，这些任务经过特别设计，适合新手入门。

🛠️ 准备工作：从零开始的开发环境

环境搭建三步曲

1. 获取代码

git clone https://gitcode.com/gh_mirrors/sw/sweep.git
cd sweep

2. 安装依赖

# 安装Python后端依赖
pip install -e .

# 安装前端依赖
cd docs && npm install && cd ..
cd sweep_chat && npm install && cd ..

3. 本地验证

# 启动服务
docker-compose up -d

# 运行测试
pytest tests/

技术栈概览

层次	核心技术	主要目录	功能说明
前端	React/Next.js	sweep_chat/	用户界面与交互逻辑
后端	Python/FastAPI	sweepai/	API服务与业务逻辑
AI层	向量数据库/代码分析	sweepai/core/	代码理解与生成

💡 小贴士：开发前建议先运行npm run dev(前端)和uvicorn sweepai.api:app --reload(后端)，验证基础环境是否正常工作。

🔄 贡献流程：发现→构建→验证→融合

graph TD
    A[发现机会] --> B[构建解决方案]
    B --> C[验证质量]
    C --> D[融合代码]
    D --> A

1. 发现机会

问题报告

• 搜索现有issue避免重复
• 使用模板填写：问题复现步骤、预期行为、实际结果、相关截图

功能建议

• 提出改进方案：代码生成准确性、PR预览组件优化等
• 参与社区讨论：分享你的创意和实现思路

2. 构建解决方案

分支管理

• 功能分支：feature/[issue-id]-brief-description
• Bug修复：fix/[issue-id]-bug-description

开发规范

• Python：遵循PEP8规范
• TypeScript：使用项目ESLint配置
• 提交信息格式：[类型]: 描述 #issue-id

3. 验证质量

必须执行的测试

# 单元测试
pytest tests/

# E2E测试
cd sweep_chat && npx cypress run && cd ..

# 代码风格检查
flake8 sweepai/

测试通过标准

• 所有测试通过率100%
• 新增功能需添加对应测试用例
• 代码覆盖率不低于80%

4. 融合代码

PR提交要点

• 关联issue：使用Fixes #123格式
• 变更说明：清晰描述实现的功能或修复
• 测试方法：说明如何验证修改

审查标准

• 代码符合项目架构
• 无性能退化
• 安全性检查：避免硬编码密钥

💡 小贴士：PR描述中添加[WIP]前缀表示"进行中"，完成后移除该前缀请求审查。

🌟 特色贡献方向

1. AI能力优化

• 改进代码生成逻辑：[sweepai/agents/complete_code.py]
• 优化提示词模板：[sweepai/core/prompts.py]
• 提升代码摘要算法：[sweepai/agents/summarize_file.py]

2. 前端交互增强

• 完善代码预览卡片：[docs/components/Cards.tsx]
• 优化加载状态动画：[sweep_chat/components/shared/PulsingLoader.tsx]
• 改进移动端响应式设计

3. 社区运营支持

• 编写使用教程：[docs/Recipes.md]
• 录制操作视频：[docs/pages/videos/]
• 翻译文档到其他语言
• 组织线上/线下工作坊

💡 小贴士：选择贡献方向时，优先考虑自己熟悉的技术领域，同时尝试挑战一个略微超出舒适区的任务。

📋 新手友好任务清单

• [ ] 修复文档中的错别字或格式问题
• [ ] 为现有功能添加单元测试
• [ ] 改进错误提示信息
• [ ] 优化组件注释
• [ ] 参与issue分类和标签整理

📈 贡献者成长路径

新手贡献者 → 活跃贡献者 → 核心贡献者 → 维护者
   ↓            ↓             ↓            ↓
修复小问题   独立功能开发   架构决策      项目方向

❓ 常见问题解答

如何处理大型重构需求？

目前Sweep不支持超过5个文件的大规模变更，建议拆分为多个小型PR逐步实现。每个PR专注于单一功能或修复，保持代码审查的高效性。

发现安全漏洞应该如何报告？

请直接发送邮件至项目维护邮箱，安全相关问题将优先处理。不要在公开issue中讨论敏感安全问题。

前端组件开发有设计规范吗？

参考现有UI组件和样式指南，保持设计一致性。新组件应包含单元测试和使用示例，确保可维护性。

🚀 开始你的贡献之旅

1. Star并Fork仓库
2. 浏览"good first issue"寻找合适任务
3. 创建第一个PR，标题格式：docs: add contribution guide examples #123

所有贡献都将被记录在贡献者名单中，期待你的加入，让我们共同打造更强大的AI开发助手！