# 🤝 贡献指南

> **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) 搭建本地开发环境。

---

> 再次感谢您的贡献！🎉