175 lines
3.8 KiB
Markdown
175 lines
3.8 KiB
Markdown
|
# 🤝 贡献指南
|
|||
|
|
|
|||
|
|
> **Contributing Guide**
|
|||
|
|
|
|||
|
|
感谢您对天工智能体平台的兴趣！我们欢迎所有形式的贡献——代码、文档、Bug 反馈、功能建议等。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、行为准则
|
|||
|
|
|
|||
|
|
请保持友善和尊重的沟通氛围。我们致力于为所有贡献者提供一个开放、包容的环境。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、如何贡献
|
|||
|
|
|
|||
|
|
### 🐛 报告 Bug
|
|||
|
|
|
|||
|
|
1. 前往 **[Issues](#)** 页面
|
|||
|
|
2. 搜索是否已有相同问题报告
|
|||
|
|
3. 创建新 Issue，使用 Bug 报告模板
|
|||
|
|
4. 请包含以下信息：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
**标题**: [Bug] 简短描述问题
|
|||
|
|
|
|||
|
|
**描述**:
|
|||
|
|
- 预期行为：
|
|||
|
|
- 实际行为：
|
|||
|
|
- 复现步骤：
|
|||
|
|
1. ...
|
|||
|
|
2. ...
|
|||
|
|
- 环境信息：
|
|||
|
|
- 浏览器/版本：
|
|||
|
|
- 操作系统：
|
|||
|
|
- API 版本：
|
|||
|
|
- 截图/日志：
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### ✨ 功能建议
|
|||
|
|
|
|||
|
|
1. 前往 **[Discussions](#)** 或 **Issues**
|
|||
|
|
2. 使用功能建议模板
|
|||
|
|
3. 清晰地描述你想要的功能及其使用场景
|
|||
|
|
|
|||
|
|
### 💻 提交代码
|
|||
|
|
|
|||
|
|
#### 第一步：Fork & Clone
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# Fork 项目到你的 GitHub 账号
|
|||
|
|
# 然后 Clone 你的 Fork
|
|||
|
|
git clone https://github.com/<your-username>/aiagent.git
|
|||
|
|
cd aiagent
|
|||
|
|
|
|||
|
|
# 添加 upstream 远程仓库
|
|||
|
|
git remote add upstream https://github.com/original/aiagent.git
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 第二步：创建分支
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 从最新的 main 分支创建功能分支
|
|||
|
|
git checkout main
|
|||
|
|
git pull upstream main
|
|||
|
|
git checkout -b feat/your-feature-name
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
分支命名规范：
|
|||
|
|
|
|||
|
|
| 分支类型 | 命名格式 | 示例 |
|
|||
|
|
|:---------|:---------|:------|
|
|||
|
|
| 新功能 | `feat/<描述>` | `feat/add-voice-input` |
|
|||
|
|
| Bug 修复 | `fix/<描述>` | `fix/token-refresh-bug` |
|
|||
|
|
| 文档 | `docs/<描述>` | `docs/update-api-ref` |
|
|||
|
|
| 重构 | `refactor/<描述>` | `refactor/user-module` |
|
|||
|
|
|
|||
|
|
#### 第三步：开发
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 确保你的代码
|
|||
|
|
# 1. 通过所有 lint 检查
|
|||
|
|
cd frontend && pnpm lint
|
|||
|
|
|
|||
|
|
cd backend && flake8 app/
|
|||
|
|
|
|||
|
|
# 2. 通过所有测试
|
|||
|
|
cd frontend && pnpm test
|
|||
|
|
cd backend && pytest
|
|||
|
|
|
|||
|
|
# 3. 遵循代码规范（详见开发指南）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 第四步：提交 & 推送
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 使用 Conventional Commits 规范
|
|||
|
|
git add .
|
|||
|
|
git commit -m "feat(agent): 新增智能体知识库关联功能"
|
|||
|
|
|
|||
|
|
# 推送到你的 Fork
|
|||
|
|
git push origin feat/your-feature-name
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 第五步：发起 Pull Request
|
|||
|
|
|
|||
|
|
1. 前往原始仓库的 **Pull Requests** 页面
|
|||
|
|
2. 点击 **New Pull Request**
|
|||
|
|
3. 选择你的分支 → 目标分支 (`main`)
|
|||
|
|
4. 填写 PR 模板：
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
## 描述
|
|||
|
|
简要描述本次变更内容
|
|||
|
|
|
|||
|
|
## 关联 Issue
|
|||
|
|
Closes #123
|
|||
|
|
|
|||
|
|
## 变更类型
|
|||
|
|
- [ ] 新功能 (feat)
|
|||
|
|
- [ ] Bug 修复 (fix)
|
|||
|
|
- [ ] 文档更新 (docs)
|
|||
|
|
- [ ] 代码重构 (refactor)
|
|||
|
|
- [ ] 测试 (test)
|
|||
|
|
- [ ] 构建/工具链 (chore)
|
|||
|
|
|
|||
|
|
## 自测清单
|
|||
|
|
- [ ] 代码已 lint 通过
|
|||
|
|
- [ ] 测试已通过
|
|||
|
|
- [ ] 本地运行验证通过
|
|||
|
|
- [ ] 文档已更新（如需要）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、Code Review 流程
|
|||
|
|
|
|||
|
|
| 阶段 | 说明 |
|
|||
|
|
|:-----|:------|
|
|||
|
|
| 1️⃣ 提交 PR | PR 状态变为 `Open` |
|
|||
|
|
| 2️⃣ CI 检查 | 自动运行 Lint + 测试 |
|
|||
|
|
| 3️⃣ Review 分配 | 维护者分配 Reviewer |
|
|||
|
|
| 4️⃣ 代码审查 | Reviewer 逐行审查，提出修改建议 |
|
|||
|
|
| 5️⃣ 修改 | 提交者根据反馈修改代码 |
|
|||
|
|
| 6️⃣ 批准合并 | Review 通过后，由维护者合并到 `main` |
|
|||
|
|
|
|||
|
|
### Review 关注点
|
|||
|
|
|
|||
|
|
- 代码正确性：功能是否符合预期
|
|||
|
|
- 代码风格：是否遵循项目规范
|
|||
|
|
- 性能影响：是否有明显性能问题
|
|||
|
|
- 安全漏洞：是否存在 SQL 注入 / XSS / 越权等隐患
|
|||
|
|
- 测试覆盖：是否包含必要的测试用例
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、文档贡献
|
|||
|
|
|
|||
|
|
文档和代码同等重要！如果你发现文档有误或缺失，欢迎贡献：
|
|||
|
|
|
|||
|
|
- **API 文档**：位于 `docs/api-reference.md`
|
|||
|
|
- **架构文档**：位于 `docs/architecture.md`
|
|||
|
|
- **使用指南**：位于 `docs/quickstart.md`
|
|||
|
|
- **代码注释**：修改代码时保持注释同步更新
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、开发环境
|
|||
|
|
|
|||
|
|
请参考 [开发指南](./development-guide.md) 搭建本地开发环境。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
> 再次感谢您的贡献！🎉
|