release

.env.example

@@ -18,6 +18,10 @@ APP_PORT=23000
 APP_URL=                                   # 应用访问地址（留空自动检测，生产环境建议显式配置）
                                            # 示例：https://your-domain.com 或 http://192.168.1.100:23000
 
+# API 测试配置
+# API 测试请求超时时间（毫秒），范围 5000-120000。未设置时默认 15000。
+API_TEST_TIMEOUT_MS=15000
+
 # Cookie 安全策略
 # 功能说明：控制是否强制 HTTPS Cookie（设置 cookie 的 secure 属性）
 # - true (默认)：仅允许 HTTPS 传输 Cookie，浏览器会自动放行 localhost 的 HTTP

AGENTS.md

@@ -1,44 +1,157 @@
-# Repository Guidelines
+# CLAUDE.md
 
-## Project Structure & Module Organization
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-- `src/app` holds Next.js routes and API handlers; UI primitives live in `src/components`.
-- Shared server logic sits in `src/actions`, `src/lib`, and `src/repository`.
-- Drizzle migrations and schema snapshots live under `drizzle/` with settings in `drizzle.config.ts`.
-- Static assets stay in `public/`; deployment helpers live in `deploy/`, `docker-compose.yaml`, and the `Makefile`.
-- Docker volumes write into `data/`; treat it as runtime-only.
+## Project Overview
 
-## Build, Test, and Development Commands
+Claude Code Hub is an AI API proxy platform built with Next.js 15 + Hono + PostgreSQL + Redis. It provides multi-provider management, intelligent load balancing, real-time monitoring, and OpenAPI documentation for Claude/OpenAI compatible APIs.
 
-- `bun run dev` — starts Next.js (port 13500) with Turbo for local work.
-- `bun run build` / `bun run start` — compiles the standalone production bundle and serves it.
-- `bun run lint`, `bun run typecheck`, `bun run format:check` — run ESLint 9, TypeScript `--noEmit`, and Prettier verification; treat failures as blockers.
-- `bun run db:generate`, `bun run db:migrate`, `bun run db:push`, `bun run db:studio` — Drizzle Kit for schema evolution.
-- `docker compose up -d` — spins up the full stack (app, Postgres, Redis) for parity testing.
+## Development Commands
 
-## Coding Style & Naming Conventions
+```bash
+# Install dependencies
+bun install
 
-- 2-space indentation, trailing commas, and single quotes follow Prettier and `eslint.config.mjs`.
-- React components use PascalCase (`UsageChart.tsx`); hooks and utilities stay camelCase; route folders remain kebab-case.
-- Prefer `async/await`, keep server actions inside `src/actions`, and co-locate Tailwind classes with the JSX they style.
-- Run `bun run format` before submitting wide-ranging edits.
+# Development server (port 13500 with Turbo)
+bun run dev
 
-## Testing Guidelines
+# Build for production
+bun run build
 
-- Today we rely on `bun run lint` and `bun run typecheck` plus manual checks through `/admin`.
-- Smoke API changes with `curl -H "Authorization: Bearer <ADMIN_TOKEN>" http://localhost:13500/api/providers`.
-- New automated tests should follow `*.spec.ts` naming, live next to the feature, and wire into `package.json` scripts.
-- Note any seed data or feature flags in the PR description so reviewers can reproduce your scenario.
+# Type checking
+bun run typecheck
 
-## Commit & Pull Request Guidelines
+# Linting
+bun run lint
 
-- Follow Conventional commits (`fix:`, `chore:`, `feat:`) as seen in `git log`; keep subjects under 72 characters.
-- Body text should note user impact plus migration or environment changes.
-- PRs must include a short summary, screenshots or JSON samples for UI/API updates, links to issues, and migration callouts.
-- Rebase onto `main`, run `bun run lint && bun run typecheck`, and flag anything that blocks deploy parity.
+# Format code
+bun run format
 
-## Security & Configuration Tips
+# Database commands
+bun run db:generate    # Generate Drizzle migrations
+bun run db:migrate     # Run migrations
+bun run db:push        # Push schema changes
+bun run db:studio      # Open Drizzle Studio
+```
 
-- Start from `.env.example`, rotate `ADMIN_TOKEN` before sharing previews, and scope provider keys to least privilege.
-- Keep Redis, Postgres, and upstream tokens in secrets management—never in Git commits.
-- Prefer `bun run dev` with mock providers when debugging rather than production credentials.
+### Local Development with Docker
+
+```bash
+cd dev
+make dev      # Start PostgreSQL + Redis + bun dev
+make db       # Start only database and Redis
+make migrate  # Run database migrations
+make clean    # Clean all resources
+```
+
+## Architecture
+
+### Request Flow
+
+```
+Client Request → Next.js API Route (/v1)
+    → ProxySession (context creation)
+    → GuardPipeline (auth → version → session → sensitive → rateLimit → provider)
+    → ProxyForwarder (request forwarding with format conversion)
+    → ResponseHandler (streaming/non-streaming response)
+```
+
+### Key Directories
+
+- `src/app/v1/_lib/` - Proxy core: handlers, guards, converters, forwarders
+- `src/actions/` - Server Actions (business logic, exposed via OpenAPI)
+- `src/repository/` - Database queries (Drizzle ORM)
+- `src/lib/` - Shared utilities: rate-limit, circuit-breaker, session, logger
+- `src/drizzle/` - Database schema and migrations
+- `src/app/api/actions/` - OpenAPI documentation generation
+
+### Provider Types
+
+The system supports multiple provider types via `providerType` field:
+
+- `claude` - Anthropic API (standard)
+- `claude-auth` - Claude relay services (Bearer auth only)
+- `codex` - Codex CLI (Response API)
+- `gemini-cli` - Gemini CLI
+- `openai-compatible` - OpenAI Compatible APIs
+
+### Format Converters
+
+Located in `src/app/v1/_lib/converters/`, these handle bidirectional conversion between:
+
+- Claude Messages API
+- OpenAI Chat Completions API
+- Codex Response API
+- Gemini CLI format
+
+### Guard Pipeline
+
+The `GuardPipelineBuilder` in `src/app/v1/_lib/proxy/guard-pipeline.ts` orchestrates request processing:
+
+1. `auth` - API key validation
+2. `version` - Client version check
+3. `probe` - Handle probe requests
+4. `session` - Session management (5-min context caching)
+5. `sensitive` - Content filtering
+6. `rateLimit` - Multi-dimensional rate limiting (RPM, USD limits)
+7. `provider` - Provider selection (weight + priority + circuit breaker)
+8. `messageContext` - Request logging
+
+### Database Schema
+
+Core tables in `src/drizzle/schema.ts`:
+
+- `users` - User accounts with quota limits
+- `keys` - API keys with per-key limits
+- `providers` - Upstream provider configurations
+- `messageRequest` - Request logs with token/cost tracking
+- `modelPrices` - Model pricing data (LiteLLM sync)
+- `errorRules` - Error classification rules
+- `sensitiveWords` - Content filtering rules
+
+### OpenAPI Documentation
+
+Server Actions are automatically exposed as REST endpoints via `src/app/api/actions/[...route]/route.ts`:
+
+- Swagger UI: `/api/actions/docs`
+- Scalar UI: `/api/actions/scalar`
+- OpenAPI JSON: `/api/actions/openapi.json`
+
+## Configuration
+
+Key environment variables (see `.env.example`):
+
+- `ADMIN_TOKEN` - Admin login token (required)
+- `DSN` - PostgreSQL connection string
+- `REDIS_URL` - Redis for rate limiting and sessions
+- `AUTO_MIGRATE` - Enable automatic DB migrations
+- `ENABLE_RATE_LIMIT` - Enable rate limiting features
+- `SESSION_TTL` - Session cache duration (default 300s)
+
+## Important Patterns
+
+### Path Alias
+
+All imports use `@/*` alias mapping to `./src/*`.
+
+### i18n
+
+Internationalization via `next-intl` with messages in `/messages/{locale}/`.
+
+### Rate Limiting
+
+Redis Lua scripts ensure atomic operations. Fail-open strategy when Redis unavailable.
+
+### Circuit Breaker
+
+Per-provider circuit breaker with configurable thresholds. States: CLOSED → OPEN → HALF_OPEN.
+
+### Session Stickiness
+
+5-minute session caching to maintain provider consistency within conversations.
+
+## PR Guidelines
+
+- All PRs must target `dev` branch (never `main` directly)
+- Run `bun run lint && bun run typecheck` before committing
+- Follow Conventional Commits format (feat/fix/chore/refactor/test)

CHANGELOG.md

@@ -8,12 +8,7 @@ All notable changes to this project will be documented in this file.
 
 - Add real-time monitoring big screen dashboard with live metrics, 24h trends, provider slots status, and activity stream (#184) @ding113
 - Add dark mode support with theme switcher in Dashboard and settings pages (#171) @ding113
-- Add dark mode support to provider quota management page (#170) @ding113
-
-### Changed
-
-- Merge dev to main with internationalization improvements (Japanese, Russian, Traditional Chinese) and UI enhancements for daily limit dialogs (#182) @ding113
-- Refactor provider quota management page from card layout to compact list layout with circular progress indicators, search, and sorting capabilities (#170) @ding113
+- Add MCP (Model Context Protocol) passthrough functionality to forward tool calls to third-party AI services (#193) @ding113
 
 ### Changed