ds2api/docs/CONTRIBUTING.md

贡献指南

语言 / Language: 中文 | English

感谢你对 DS2API 的关注与贡献！

开发环境设置

前置要求

• Go 1.26+
• Node.js 20.19+ 或 22.12+（WebUI 开发时）
• npm（随 Node.js 提供）

后端开发

# 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://127.0.0.1:5001
# 实际绑定 0.0.0.0:5001，可通过局域网 IP 访问

前端开发（WebUI）

# 1. 进入 WebUI 目录
cd webui

# 2. 安装依赖
npm install

# 3. 启动开发服务器（热更新）
npm run dev
# 默认监听 http://localhost:5173，自动代理 API 到后端
# 当前未配置 host: 0.0.0.0，因此默认不对局域网开放

WebUI 技术栈：

• React + Vite
• Tailwind CSS
• 中英文语言包：webui/src/locales/zh.json / en.json

Docker 开发环境

docker-compose -f docker-compose.dev.yml up

代码规范

语言	规范
Go	提交前运行 ./scripts/lint.sh（包含 gofmt+golangci-lint）并确保 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 会自动处理。 但如果你本地想验证 static/admin/ 产物，还是可以手动运行 ./scripts/build-webui.sh。

WebUI 构建

手动构建 WebUI 到 static/admin/：

./scripts/build-webui.sh

运行测试

# Go + Node 单元测试（推荐）
./tests/scripts/run-unit-all.sh

# 端到端全链路测试（真实账号）
./tests/scripts/run-live.sh

项目结构

ds2api/
├── app/                     # 统一 HTTP Handler 装配（本地 + Serverless）
├── 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/              # Go 版本兼容与回归测试辅助
│   ├── config/              # 配置加载、校验与热更新
│   ├── deepseek/            # DeepSeek 客户端、PoW 逻辑
│   ├── js/                  # Node 运行时流式/兼容逻辑
│   ├── devcapture/          # 开发抓包
│   ├── format/              # 输出格式化
│   ├── prompt/              # Prompt 构建
│   ├── server/              # HTTP 路由（chi router）
│   ├── sse/                 # SSE 解析工具
│   ├── stream/              # 统一流式消费引擎
│   ├── testsuite/           # 测试集框架与场景编排
│   ├── translatorcliproxy/  # CLIProxy 桥接与流式写入
│   ├── util/                # 通用工具
│   ├── version/             # 版本解析与比较
│   └── webui/               # WebUI 静态托管
├── webui/                   # React WebUI 源码
│   └── src/
│       ├── app/             # 路由、鉴权、配置状态
│       ├── features/        # 业务功能模块
│       ├── components/      # 通用组件
│       └── locales/         # 语言包
├── scripts/                 # 构建与测试脚本
├── tests/
│   ├── compat/              # 兼容夹具与期望输出
│   ├── node/                # Node 侧单元测试
│   └── scripts/             # 测试脚本入口（unit/e2e）
├── plans/                   # 计划、门禁和手工烟测记录
├── static/admin/            # WebUI 构建产物（不提交）
├── Dockerfile               # 多阶段构建
├── docker-compose.yml       # 生产环境
├── docker-compose.dev.yml   # 开发环境
└── vercel.json              # Vercel 配置

问题反馈

请使用 GitHub Issues 并附上：

• 复现步骤
• 相关日志输出
• 运行环境信息（OS、Go 版本、部署方式）