mirror of
https://github.com/QuantumNous/new-api.git
synced 2026-03-30 08:56:02 +00:00
107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# AGENTS.md — Project Conventions for new-api
|
|
|
|
## Overview
|
|
|
|
This is an AI API gateway/proxy built with Go. It aggregates 40+ upstream AI providers (OpenAI, Claude, Gemini, Azure, AWS Bedrock, etc.) behind a unified API, with user management, billing, rate limiting, and an admin dashboard.
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Go 1.22+, Gin web framework, GORM v2 ORM
|
|
- **Frontend**: React 18, Vite, Semi Design UI (@douyinfe/semi-ui)
|
|
- **Databases**: SQLite, MySQL, PostgreSQL (all three must be supported)
|
|
- **Cache**: Redis (go-redis) + in-memory cache
|
|
- **Auth**: JWT, WebAuthn/Passkeys, OAuth (GitHub, Discord, OIDC, etc.)
|
|
- **Frontend package manager**: Bun (preferred over npm/yarn/pnpm)
|
|
|
|
## Architecture
|
|
|
|
Layered architecture: Router -> Controller -> Service -> Model
|
|
|
|
```
|
|
router/ — HTTP routing (API, relay, dashboard, web)
|
|
controller/ — Request handlers
|
|
service/ — Business logic
|
|
model/ — Data models and DB access (GORM)
|
|
relay/ — AI API relay/proxy with provider adapters
|
|
relay/channel/ — Provider-specific adapters (openai/, claude/, gemini/, aws/, etc.)
|
|
middleware/ — Auth, rate limiting, CORS, logging, distribution
|
|
setting/ — Configuration management (ratio, model, operation, system, performance)
|
|
common/ — Shared utilities (JSON, crypto, Redis, env, rate-limit, etc.)
|
|
dto/ — Data transfer objects (request/response structs)
|
|
constant/ — Constants (API types, channel types, context keys)
|
|
types/ — Type definitions (relay formats, file sources, errors)
|
|
i18n/ — Backend internationalization (go-i18n, en/zh)
|
|
oauth/ — OAuth provider implementations
|
|
pkg/ — Internal packages (cachex, ionet)
|
|
web/ — React frontend
|
|
web/src/i18n/ — Frontend internationalization (i18next, zh/en/fr/ru/ja/vi)
|
|
```
|
|
|
|
## Internationalization (i18n)
|
|
|
|
### Backend (`i18n/`)
|
|
- Library: `nicksnyder/go-i18n/v2`
|
|
- Languages: en, zh
|
|
|
|
### Frontend (`web/src/i18n/`)
|
|
- Library: `i18next` + `react-i18next` + `i18next-browser-languagedetector`
|
|
- Languages: zh (fallback), en, fr, ru, ja, vi
|
|
- Translation files: `web/src/i18n/locales/{lang}.json` — flat JSON, keys are Chinese source strings
|
|
- Usage: `useTranslation()` hook, call `t('中文key')` in components
|
|
- Semi UI locale synced via `SemiLocaleWrapper`
|
|
- CLI tools: `bun run i18n:extract`, `bun run i18n:sync`, `bun run i18n:lint`
|
|
|
|
## Rules
|
|
|
|
### Rule 1: JSON Package — Use `common/json.go`
|
|
|
|
All JSON marshal/unmarshal operations MUST use the wrapper functions in `common/json.go`:
|
|
|
|
- `common.Marshal(v any) ([]byte, error)`
|
|
- `common.Unmarshal(data []byte, v any) error`
|
|
- `common.UnmarshalJsonStr(data string, v any) error`
|
|
- `common.DecodeJson(reader io.Reader, v any) error`
|
|
- `common.GetJsonType(data json.RawMessage) string`
|
|
|
|
Do NOT directly import or call `encoding/json` in business code. These wrappers exist for consistency and future extensibility (e.g., swapping to a faster JSON library).
|
|
|
|
Note: `json.RawMessage`, `json.Number`, and other type definitions from `encoding/json` may still be referenced as types, but actual marshal/unmarshal calls must go through `common.*`.
|
|
|
|
### Rule 2: Database Compatibility — SQLite, MySQL >= 5.7.8, PostgreSQL >= 9.6
|
|
|
|
All database code MUST be fully compatible with all three databases simultaneously.
|
|
|
|
**Use GORM abstractions:**
|
|
- Prefer GORM methods (`Create`, `Find`, `Where`, `Updates`, etc.) over raw SQL.
|
|
- Let GORM handle primary key generation — do not use `AUTO_INCREMENT` or `SERIAL` directly.
|
|
|
|
**When raw SQL is unavoidable:**
|
|
- Column quoting differs: PostgreSQL uses `"column"`, MySQL/SQLite uses `` `column` ``.
|
|
- Use `commonGroupCol`, `commonKeyCol` variables from `model/main.go` for reserved-word columns like `group` and `key`.
|
|
- Boolean values differ: PostgreSQL uses `true`/`false`, MySQL/SQLite uses `1`/`0`. Use `commonTrueVal`/`commonFalseVal`.
|
|
- Use `common.UsingPostgreSQL`, `common.UsingSQLite`, `common.UsingMySQL` flags to branch DB-specific logic.
|
|
|
|
**Forbidden without cross-DB fallback:**
|
|
- MySQL-only functions (e.g., `GROUP_CONCAT` without PostgreSQL `STRING_AGG` equivalent)
|
|
- PostgreSQL-only operators (e.g., `@>`, `?`, `JSONB` operators)
|
|
- `ALTER COLUMN` in SQLite (unsupported — use column-add workaround)
|
|
- Database-specific column types without fallback — use `TEXT` instead of `JSONB` for JSON storage
|
|
|
|
**Migrations:**
|
|
- Ensure all migrations work on all three databases.
|
|
- For SQLite, use `ALTER TABLE ... ADD COLUMN` instead of `ALTER COLUMN` (see `model/main.go` for patterns).
|
|
|
|
### Rule 3: Frontend — Prefer Bun
|
|
|
|
Use `bun` as the preferred package manager and script runner for the frontend (`web/` directory):
|
|
- `bun install` for dependency installation
|
|
- `bun run dev` for development server
|
|
- `bun run build` for production build
|
|
- `bun run i18n:*` for i18n tooling
|
|
|
|
### Rule 4: New Channel StreamOptions Support
|
|
|
|
When implementing a new channel:
|
|
- Confirm whether the provider supports `StreamOptions`.
|
|
- If supported, add the channel to `streamSupportedChannels`.
|