ds2api/docs/CONTRIBUTING.en.md

Contributing Guide

Language: 中文 | English

Thanks for your interest in contributing to DS2API!

Development Setup

Prerequisites

• Go 1.26+
• Node.js 20.19+ or 22.12+ (for WebUI development)
• npm (bundled with Node.js)

Backend Development

# 1. Clone
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# 2. Configure
cp config.example.json config.json
# Edit config.json with test accounts

# 3. Run backend
go run ./cmd/ds2api
# Local access: http://127.0.0.1:5001
# Actual bind: 0.0.0.0:5001, so LAN access is available via your private IP

Frontend Development (WebUI)

# 1. Navigate to WebUI directory
cd webui

# 2. Install dependencies
npm install

# 3. Start dev server (hot reload)
npm run dev
# Default: http://localhost:5173, auto-proxies API to backend
# host: 0.0.0.0 is not configured, so LAN access is not enabled by default

WebUI tech stack:

• React + Vite
• Tailwind CSS
• Bilingual language packs: webui/src/locales/zh.json / en.json

Docker Development

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

Code Standards

Language	Standards
Go	Run ./scripts/lint.sh (gofmt + golangci-lint) and ensure go test ./... passes before committing
JavaScript/React	Follow existing project style (functional components)
Commit messages	Use semantic prefixes: feat:, fix:, docs:, refactor:, style:, perf:, chore:

Submitting a PR

1. Fork the repo
2. Create a branch (e.g. feature/xxx or fix/xxx)
3. Commit changes
4. Push your branch
5. Open a Pull Request

💡 If you modify files under webui/, no manual build is needed — CI handles it automatically. If you want to verify the generated static/admin/ assets locally, you can still run ./scripts/build-webui.sh.

Build WebUI

Manually build WebUI to static/admin/:

./scripts/build-webui.sh

Running Tests

# Go + Node unit tests (recommended)
./tests/scripts/run-unit-all.sh

# End-to-end live tests (real accounts)
./tests/scripts/run-live.sh

Project Structure

ds2api/
├── app/                     # Shared HTTP handler assembly (local + serverless)
├── cmd/
│   ├── ds2api/              # Local/container entrypoint
│   └── ds2api-tests/        # End-to-end testsuite entrypoint
├── api/
│   ├── index.go             # Vercel Serverless Go entry
│   ├── chat-stream.js       # Vercel Node.js stream relay
│   └── (rewrite targets in vercel.json)
├── internal/
│   ├── account/             # Account pool and concurrency queue
│   ├── adapter/
│   │   ├── openai/          # OpenAI adapter
│   │   ├── claude/          # Claude adapter
│   │   └── gemini/          # Gemini adapter
│   ├── admin/               # Admin API handlers
│   ├── auth/                # Auth and JWT
│   ├── claudeconv/          # Claude message conversion
│   ├── compat/              # Go-version compatibility and regression helpers
│   ├── config/              # Config loading, validation, and hot-reload
│   ├── deepseek/            # DeepSeek client, PoW logic
│   ├── js/                  # Node runtime stream/compat logic
│   ├── devcapture/          # Dev packet capture
│   ├── format/              # Output formatting
│   ├── prompt/              # Prompt building
│   ├── server/              # HTTP routing (chi router)
│   ├── sse/                 # SSE parsing utilities
│   ├── stream/              # Unified stream consumption engine
│   ├── testsuite/           # Testsuite framework and scenario orchestration
│   ├── translatorcliproxy/  # CLIProxy bridge and stream writer
│   ├── util/                # Common utilities
│   ├── version/             # Version parsing and comparison
│   └── webui/               # WebUI static hosting
├── webui/                   # React WebUI source
│   └── src/
│       ├── app/             # Routing, auth, config state
│       ├── features/        # Feature modules
│       ├── components/      # Shared components
│       └── locales/         # Language packs
├── scripts/                 # Build and test scripts
├── tests/
│   ├── compat/              # Compatibility fixtures and expected outputs
│   ├── node/                # Node-side unit tests
│   └── scripts/             # Test script entrypoints (unit/e2e)
├── plans/                   # Plans, gates, and manual smoke-test records
├── static/admin/            # WebUI build output (not committed)
├── Dockerfile               # Multi-stage build
├── docker-compose.yml       # Production
├── docker-compose.dev.yml   # Development
└── vercel.json              # Vercel config

Reporting Issues

Please use GitHub Issues and include:

• Steps to reproduce
• Relevant log output
• Environment info (OS, Go version, deployment method)