贡献指南

欢迎参与 Claude Code Hub 开源项目！本文档将帮助您了解如何按照项目规范提交高质量的 Pull Request（PR），成为社区贡献者的一员。

概述

Claude Code Hub 是一个面向团队的 AI API 代理平台，支持统一管理多家供应商、智能分流和现代化运维工具。我们欢迎各种形式的贡献：

• 报告 Bug 和提出功能建议
• 改进文档和翻译
• 提交代码修复和新功能
• 参与代码审查和讨论

行为准则

为了营造积极、包容的社区氛围，所有参与者需遵守以下行为准则（参考 Contributor Covenant 2.1）：

• 友好尊重：保持耐心和包容的沟通方式
• 尊重多元：尊重不同背景和观点的贡献者
• 基于事实：讨论以数据和事实为依据，避免人身攻击
• 建设性反馈：提出问题时同时思考可能的解决方案

开发环境搭建

环境要求

快速开始

1. 克隆仓库并安装依赖：

git clone https://github.com/ding113/claude-code-hub.git
cd claude-code-hub
bun install

2. 配置环境变量：

cp .env.example .env

编辑 .env 文件，至少需要配置：

# 后台登录令牌（开发环境可使用简单值）
ADMIN_TOKEN=dev-token-12345

# 数据库连接（本地开发）
DSN=postgres://postgres:postgres@localhost:5432/claude_code_hub

# Redis 连接（本地开发）
REDIS_URL=redis://localhost:6379

3. 启动开发服务器：

bun run dev

服务默认运行在 http://localhost:13500。

Docker 开发环境

如需完整的容器化开发体验，可使用 dev/ 目录中的工具：

cd dev
make dev      # 一键启动 PostgreSQL + Redis + 开发服务器
make db       # 仅启动数据库和 Redis
make logs     # 查看所有服务日志
make clean    # 清理环境

分支策略

项目采用双分支模型管理代码：

main (稳定版本) ← dev (开发分支) ← feature/* / fix/* (功能/修复分支)

分支说明

分支命名规范

代码规范

TypeScript 规范

项目使用 TypeScript 严格模式，遵循以下规范：

• 缩进：2 空格
• 引号：单引号
• 尾随逗号：强制使用
• 类型安全：避免使用 any，必要时添加注释说明

ESLint 配置

项目使用 Next.js 推荐的 ESLint 配置：

// eslint.config.mjs 核心配置
extends: ["next/core-web-vitals", "next/typescript", "prettier"]

运行检查：

bun run lint

Prettier 格式化

代码格式由 Prettier 统一管理：

# 检查格式
bun run format:check

# 自动修复格式
bun run format

代码风格要点

提交规范

Conventional Commits

所有提交消息必须遵循 Conventional Commits 规范：

<类型>: <简短描述>

[可选的详细说明]

[可选的关联 Issue]

提交类型

提交消息示例

良好的提交消息：

feat: add weighted load balancing for providers

- Implement weighted random selection algorithm
- Add priority-based failover logic
- Update provider configuration UI

Closes #123

应避免的提交消息：

# 太模糊
fix: bug fix

# 没有类型前缀
update code

# 混合多个变更
feat: add feature and fix bug and update docs

PR 流程

开发工作流

1. 同步最新代码：

git checkout dev
git pull origin dev

2. 创建功能分支：

git checkout -b feature/your-feature-name

3. 开发并提交：

# 进行开发...

# 运行检查
bun run lint
bun run typecheck
bun run format:check

# 提交变更
git add .
git commit -m "feat: add your feature description"

4. 推送并创建 PR：

git push origin feature/your-feature-name

然后在 GitHub 上创建指向 dev 分支的 Pull Request。

PR 检查清单

创建 PR 前，请确认以下事项：

• [ ] 目标分支：PR 的 base 分支是 dev
• [ ] CI 检查：所有状态检查已通过（Code Quality Check、Docker Build Test）
• [ ] 无冲突：与目标分支无合并冲突
• [ ] 关联 Issue：如有相关 Issue，请在 PR 中引用
• [ ] 变更说明：提供清晰的变更摘要和测试说明
• [ ] 截图/日志：UI 变更附上截图，逻辑变更附上测试日志

CI/CD 检查

每个 PR 会自动触发以下检查：

bun run typecheck        # 类型检查
bun run format:check     # 格式检查
docker compose build     # 构建测试（可选）

Review 流程

1. 等待审查：维护者会在 2 个工作日内进行 Review
2. 处理反馈：根据反馈修改后，直接推送到同一分支
3. 合并方式：采用 Squash and merge 保持干净的提交历史

PR 过期处理

如果 PR 长时间未合并导致与 dev 分支产生差异：

git fetch origin
git rebase origin/dev
git push --force-with-lease

Issue 报告

Bug 报告

提交 Bug 时，请包含以下信息：

1. 环境信息

   • 操作系统和版本
   • Docker/Node.js/Bun 版本
   • Claude Code Hub 版本

2. 复现步骤

   • 详细的操作步骤
   • 相关配置（脱敏后）

3. 预期结果 vs 实际结果

   • 您期望发生什么
   • 实际发生了什么

4. 日志和截图

   • 相关错误日志
   • 问题界面截图

功能请求

提交功能建议时，请说明：

• 使用场景：为什么需要这个功能
• 期望行为：功能应该如何工作
• 替代方案：是否考虑过其他解决方式

开发命令参考

常用命令

数据库命令

Docker 命令

# 构建镜像
docker compose build

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f app

# 停止服务
docker compose down

联系方式

感谢

感谢每一位为 Claude Code Hub 做出贡献的开发者！您的参与让这个项目变得更好。

无论是提交代码、报告 Bug、改进文档，还是参与讨论，每一份贡献都是宝贵的。