mirror of
https://github.com/CJackHwang/ds2api.git
synced 2026-05-05 00:45:29 +08:00
146 lines
4.1 KiB
Markdown
146 lines
4.1 KiB
Markdown
# 贡献指南
|
||
|
||
语言 / Language: [中文](CONTRIBUTING.md) | [English](CONTRIBUTING.en.md)
|
||
|
||
感谢你对 DS2API 的关注与贡献！
|
||
|
||
## 开发环境设置
|
||
|
||
### 前置要求
|
||
|
||
- Go 1.24+
|
||
- Node.js 20+（WebUI 开发时）
|
||
- npm（随 Node.js 提供）
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
# 1. 克隆仓库
|
||
git clone https://github.com/CJackHwang/ds2api.git
|
||
cd ds2api
|
||
|
||
# 2. 配置
|
||
cp config.example.json config.json
|
||
# 编辑 config.json，填入测试账号
|
||
|
||
# 3. 启动后端
|
||
go run ./cmd/ds2api
|
||
# 默认监听 http://localhost:5001
|
||
```
|
||
|
||
### 前端开发（WebUI）
|
||
|
||
```bash
|
||
# 1. 进入 WebUI 目录
|
||
cd webui
|
||
|
||
# 2. 安装依赖
|
||
npm install
|
||
|
||
# 3. 启动开发服务器（热更新）
|
||
npm run dev
|
||
# 默认监听 http://localhost:5173，自动代理 API 到后端
|
||
```
|
||
|
||
WebUI 技术栈：
|
||
- React + Vite
|
||
- Tailwind CSS
|
||
- 中英文语言包：`webui/src/locales/zh.json` / `en.json`
|
||
|
||
### Docker 开发环境
|
||
|
||
```bash
|
||
docker-compose -f docker-compose.dev.yml up
|
||
```
|
||
|
||
## 代码规范
|
||
|
||
| 语言 | 规范 |
|
||
| --- | --- |
|
||
| **Go** | 提交前运行 `gofmt`，确保 `go test ./...` 通过 |
|
||
| **JavaScript/React** | 保持现有代码风格（函数组件） |
|
||
| **提交信息** | 使用语义化前缀：`feat:`、`fix:`、`docs:`、`refactor:`、`style:`、`perf:`、`chore:` |
|
||
|
||
## 提交 PR
|
||
|
||
1. Fork 仓库
|
||
2. 创建分支（如 `feature/xxx` 或 `fix/xxx`）
|
||
3. 提交更改
|
||
4. 推送分支
|
||
5. 发起 Pull Request
|
||
|
||
> 💡 如果修改了 `webui/` 目录下的文件，无需手动构建——CI 会自动处理。
|
||
|
||
## WebUI 构建
|
||
|
||
手动构建 WebUI 到 `static/admin/`：
|
||
|
||
```bash
|
||
./scripts/build-webui.sh
|
||
```
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
# Go + Node 单元测试（推荐）
|
||
./tests/scripts/run-unit-all.sh
|
||
|
||
# 端到端全链路测试（真实账号）
|
||
./tests/scripts/run-live.sh
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
ds2api/
|
||
├── cmd/
|
||
│ ├── ds2api/ # 本地/容器启动入口
|
||
│ └── ds2api-tests/ # 端到端测试集入口
|
||
├── api/
|
||
│ ├── index.go # Vercel Serverless Go 入口
|
||
│ ├── chat-stream.js # Vercel Node.js 流式转发
|
||
│ └── (rewrite targets in vercel.json)
|
||
├── internal/
|
||
│ ├── account/ # 账号池与并发队列
|
||
│ ├── adapter/
|
||
│ │ ├── openai/ # OpenAI 兼容适配器
|
||
│ │ ├── claude/ # Claude 兼容适配器
|
||
│ │ └── gemini/ # Gemini 兼容适配器
|
||
│ ├── admin/ # Admin API handlers
|
||
│ ├── auth/ # 鉴权与 JWT
|
||
│ ├── claudeconv/ # Claude 消息格式转换
|
||
│ ├── compat/ # 兼容性辅助
|
||
│ ├── config/ # 配置加载与热更新
|
||
│ ├── deepseek/ # DeepSeek 客户端、PoW WASM
|
||
│ ├── js/ # Node 运行时流式/兼容逻辑
|
||
│ ├── devcapture/ # 开发抓包
|
||
│ ├── format/ # 输出格式化
|
||
│ ├── prompt/ # Prompt 构建
|
||
│ ├── server/ # HTTP 路由（chi router）
|
||
│ ├── sse/ # SSE 解析工具
|
||
│ ├── stream/ # 统一流式消费引擎
|
||
│ ├── testsuite/ # 测试集核心逻辑
|
||
│ ├── util/ # 通用工具
|
||
│ └── webui/ # WebUI 静态托管
|
||
├── webui/ # React WebUI 源码
|
||
│ └── src/
|
||
│ ├── app/ # 路由、鉴权、配置状态
|
||
│ ├── features/ # 业务功能模块
|
||
│ ├── components/ # 通用组件
|
||
│ └── locales/ # 语言包
|
||
├── scripts/ # 构建与测试脚本
|
||
├── static/admin/ # WebUI 构建产物（不提交）
|
||
├── Dockerfile # 多阶段构建
|
||
├── docker-compose.yml # 生产环境
|
||
├── docker-compose.dev.yml # 开发环境
|
||
└── vercel.json # Vercel 配置
|
||
```
|
||
|
||
## 问题反馈
|
||
|
||
请使用 [GitHub Issues](https://github.com/CJackHwang/ds2api/issues) 并附上：
|
||
|
||
- 复现步骤
|
||
- 相关日志输出
|
||
- 运行环境信息（OS、Go 版本、部署方式）
|