6.3 KiB
6.3 KiB
贡献指南
感谢你对 DeepAudit 的关注！我们热烈欢迎所有形式的贡献，无论是提交 Issue、创建 PR，还是改进文档。
目录
行为准则
请在参与项目时保持友善和尊重。我们致力于为每个人提供一个开放、包容的环境。
如何贡献
报告 Bug
- 先搜索 Issues 确认问题未被报告
- 创建新 Issue，使用 Bug 报告模板
- 提供详细信息：
- 操作系统和版本
- 部署方式（Docker/本地）
- 复现步骤
- 错误日志或截图
- 期望行为 vs 实际行为
提出新功能
- 先搜索 Issues 确认功能未被提出
- 创建新 Issue，描述：
- 功能需求背景
- 期望的实现方式
- 可能的替代方案
改进文档
文档改进同样重要！你可以：
- 修复文档中的错误
- 补充缺失的说明
- 改进文档结构
- 添加使用示例
贡献代码
- Fork 本项目
- 创建功能分支
- 编写代码和测试
- 提交 Pull Request
开发环境搭建
环境要求
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | 18+ | 前端运行环境 |
| Python | 3.13+ | 后端运行环境 |
| PostgreSQL | 15+ | 数据库 |
| pnpm | 8+ | 推荐的前端包管理器 |
| uv | 最新版 | 推荐的 Python 包管理器 |
数据库准备
# 使用 Docker 启动 PostgreSQL（推荐）
docker run -d \
--name deepaudit-db \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=deepaudit \
-p 5432:5432 \
postgres:15-alpine
后端启动
# 1. 进入后端目录
cd backend
# 2. 创建虚拟环境
uv venv
source .venv/bin/activate # Linux/macOS
# 或 .venv\Scripts\activate # Windows
# 3. 安装依赖
uv pip install -e .
# 4. 配置环境变量
cp env.example .env
# 编辑 .env 文件，配置数据库和 LLM 参数
# 5. 初始化数据库
alembic upgrade head
# 6. 启动后端服务
uvicorn app.main:app --reload --port 8000
前端启动
# 1. 进入前端目录
cd frontend
# 2. 安装依赖
pnpm install
# 3. 配置环境变量（可选）
cp .env.example .env
# 4. 启动开发服务器
pnpm dev
代码规范
后端 (Python)
- 使用 Python 3.11+ 类型注解
- 遵循 PEP 8 代码风格
- 使用 Ruff 进行代码格式化和检查
- 使用 mypy 进行类型检查
# 代码格式化
ruff format app
# 代码检查
ruff check app
# 类型检查
mypy app
前端 (TypeScript/React)
- 使用 TypeScript 严格模式
- 遵循 React 最佳实践
- 使用 Biome 进行代码格式化和检查
# 代码检查
pnpm lint
# 类型检查
pnpm type-check
# 代码格式化
pnpm format
通用规范
- 变量和函数使用有意义的命名
- 添加必要的注释，特别是复杂逻辑
- 保持函数简短，单一职责
- 避免硬编码，使用配置或常量
提交规范
我们使用 Conventional Commits 规范。
提交格式
<type>(<scope>): <subject>
<body>
<footer>
Type 类型
| Type | 说明 |
|---|---|
feat |
新功能 |
fix |
Bug 修复 |
docs |
文档更新 |
style |
代码格式（不影响功能） |
refactor |
代码重构 |
perf |
性能优化 |
test |
测试相关 |
chore |
构建/工具相关 |
ci |
CI/CD 相关 |
示例
# 新功能
git commit -m "feat(llm): add support for DeepSeek API"
# Bug 修复
git commit -m "fix(scan): handle empty file content"
# 文档更新
git commit -m "docs: update deployment guide"
# 代码重构
git commit -m "refactor(api): simplify error handling"
Pull Request 流程
1. Fork 和克隆
# Fork 项目到你的 GitHub 账号
# 然后克隆到本地
git clone https://github.com/YOUR_USERNAME/DeepAudit.git
cd DeepAudit
# 添加上游仓库
git remote add upstream https://github.com/lintsinghua/DeepAudit.git
2. 创建分支
# 同步上游代码
git fetch upstream
git checkout main
git merge upstream/main
# 创建功能分支
git checkout -b feature/your-feature-name
3. 开发和测试
# 编写代码...
# 确保代码通过检查
cd frontend && pnpm lint && pnpm type-check
cd backend && ruff check app && mypy app
# 提交代码
git add .
git commit -m "feat: your feature description"
4. 推送和创建 PR
# 推送到你的 Fork
git push origin feature/your-feature-name
然后在 GitHub 上创建 Pull Request：
- 填写 PR 标题（遵循提交规范）
- 描述改动内容和原因
- 关联相关 Issue（如有）
- 等待 Review
5. 代码审查
- 回应 Review 意见
- 根据反馈修改代码
- 保持 PR 更新（rebase 上游代码）
项目结构
DeepAudit/
├── backend/ # 后端 (FastAPI)
│ ├── app/
│ │ ├── api/ # API 路由
│ │ ├── core/ # 核心配置
│ │ ├── db/ # 数据库
│ │ ├── models/ # 数据模型
│ │ ├── schemas/ # Pydantic 模式
│ │ └── services/ # 业务逻辑
│ │ └── llm/ # LLM 适配器
│ ├── alembic/ # 数据库迁移
│ └── pyproject.toml
├── frontend/ # 前端 (React + TypeScript)
│ ├── src/
│ │ ├── app/ # 应用配置
│ │ ├── components/ # UI 组件
│ │ ├── features/ # 功能模块
│ │ ├── pages/ # 页面组件
│ │ └── shared/ # 共享工具
│ └── package.json
├── docs/ # 文档
├── docker-compose.yml # Docker 编排
└── README.md
贡献者
感谢所有贡献者的付出！
问题反馈
如有问题，请通过以下方式联系：