AI-Proxy-Worker/docs/Contributing.md

贡献指南

🌍 Language / 语言

🇺🇸 English | 🇨🇳 中文

感谢你对 AI Proxy Worker 项目的关注！本指南将帮助你了解如何参与项目开发。

🚀 快速开始

前置要求

• Node.js 18+ 和 npm
• Git
• Cloudflare 账户（用于测试）
• JavaScript 和 Cloudflare Workers 基础知识

开发环境设置

# 克隆仓库
git clone https://github.com/qinfuyao/AI-Proxy-Worker.git
cd ai-proxy-worker

# 安装依赖
npm install -g wrangler

# 登录 Cloudflare
wrangler login

# 设置开发环境
cp wrangler.toml.example wrangler.toml
# 编辑 wrangler.toml 配置你的设置

🔧 开发流程

1. Fork 和 Clone

# 在 GitHub 上 Fork 仓库，然后克隆你的 fork
git clone https://github.com/qinfuyao/AI-Proxy-Worker.git
cd ai-proxy-worker

# 添加上游远程仓库
git remote add upstream https://github.com/original-owner/ai-proxy-worker.git

2. 创建功能分支

# 创建并切换到新分支
git checkout -b feature/your-feature-name

# 或者修复 bug
git checkout -b fix/bug-description

3. 本地开发

# 启动本地开发服务器
wrangler dev

# 测试你的更改
curl -X POST http://localhost:8787/chat \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "测试"}]}'

4. 测试

# 运行测试（如果可用）
npm test

# 手动测试清单：
# - 基本聊天功能
# - 流式响应
# - 错误处理
# - 身份验证

5. 提交和推送

# 添加更改
git add .

# 使用描述性消息提交
git commit -m "feat: 添加新 AI 模型支持"

# 推送到你的 fork
git push origin feature/your-feature-name

6. 创建 Pull Request

1. 在 GitHub 上访问你的 fork
2. 点击 "New Pull Request"
3. 填写 PR 模板
4. 等待审查

📝 代码规范

JavaScript 风格

• 使用现代 ES6+ 特性
• 保持一致的缩进（2个空格）
• 使用有意义的变量名
• 为复杂逻辑添加注释

// 好的示例
const handleChatRequest = async (request, env) => {
  const { messages, model } = await request.json();
  
  // 验证必需字段
  if (!messages || !Array.isArray(messages)) {
    throw new Error('消息必须是数组格式');
  }
  
  return await processChat(messages, model, env);
};

// 避免这样写
const h = async (r, e) => {
  const d = await r.json();
  return await p(d.m, d.mod, e);
};

错误处理

始终提供有意义的错误消息：

// 好的示例
if (!env.DEEPSEEK_API_KEY) {
  return new Response(JSON.stringify({
    error: 'configuration_error',
    message: '需要设置 DEEPSEEK_API_KEY 环境变量',
    timestamp: new Date().toISOString()
  }), {
    status: 500,
    headers: { 'Content-Type': 'application/json' }
  });
}

安全最佳实践

• 永远不要记录敏感信息（API 密钥、用户数据）
• 验证所有输入参数
• 使用适当的 HTTP 状态码
• 在适当的地方实施速率限制

🐛 Bug 报告

报告前检查

1. 检查现有 issues
2. 使用最新版本测试
3. 能够一致地重现问题

Bug 报告模板

**Bug 描述**
清楚地描述 bug 是什么。

**重现步骤**
1. 使用配置 X 部署 worker
2. 发送载荷 Y 的请求
3. 观察到错误 Z

**预期行为**
应该发生什么。

**环境信息**
- Cloudflare Workers 版本
- 使用的浏览器/客户端
- 任何相关配置

**附加上下文**
日志、截图或其他有用信息。

💡 功能请求

功能请求模板

**功能描述**
清楚地描述你希望看到的功能。

**使用场景**
解释为什么这个功能有用。

**建议实现**
如果你对如何实现有想法。

**考虑的替代方案**
你考虑过的其他解决方案。

📖 文档

写作指南

• 使用清晰、简洁的语言
• 提供实用示例
• 包含中英文版本
• 测试所有代码示例

文档结构

docs/
├── Installation.md/en.md     # 安装指南
├── Configuration.md/en.md    # 配置选项
├── API-Reference.md/en.md    # API 文档
├── Examples.md/en.md         # 使用示例
├── Troubleshooting.md/en.md  # 常见问题
└── Contributing.md/en.md     # 本文件

🔄 发布流程

版本编号

我们遵循 语义化版本：

• 主版本.次版本.修订版本
• 主版本：不兼容的 API 修改
• 次版本：向下兼容的功能性新增
• 修订版本：向下兼容的问题修正

发布清单

• 更新 wrangler.toml 中的版本
• 更新 CHANGELOG.md
• 测试所有功能
• 更新文档
• 创建发布说明
• 标记发布

🏆 致谢

贡献者

所有贡献者将在以下地方得到认可：

• README.md 贡献者部分
• 发布说明
• GitHub 贡献者页面

贡献类型

• 🐛 Bug 修复
• ✨ 新功能
• 📝 文档
• 🎨 UI/UX 改进
• 🔧 基础设施
• 🌍 翻译

❓ 获取帮助

社区支持

• 💡 Discussions - 一般问题
• 📋 Issues - Bug 报告和功能请求
• [Discord/Slack] - 实时聊天（如果可用）

代码审查流程

1. 所有 PR 需要至少一次审查
2. 维护者将在 48 小时内审查
3. 及时处理反馈
4. 合并前压缩提交

📋 贡献清单

提交 PR 前，确保：

• 代码遵循项目风格指南
• 所有测试通过
• 如需要已更新文档
• 提交消息具有描述性
• PR 描述解释了更改
• 代码中没有敏感信息
• 功能在生产环境中正常工作

---

感谢你为 AI Proxy Worker 做出贡献！ 🎉

你的贡献让这个项目对每个人都更好。