|
1 | | -# CLIPROXYAPIPLUS KNOWLEDGE BASE |
| 1 | +# AGENTS.md |
2 | 2 |
|
3 | | -**Generated:** 2026-05-18 |
4 | | -**Commit:** f7c2ff45 |
5 | | -**Branch:** main |
6 | | -**Latest Tag:** v7.1.7-3 |
| 3 | +Go 1.26+ proxy server providing OpenAI/Gemini/Claude/Codex compatible APIs with OAuth and round-robin load balancing. |
7 | 4 |
|
8 | | -## OVERVIEW |
9 | | - |
10 | | -Go 1.26 AI proxy server. Combines CLI auth flows, OpenAI-compatible API serving, provider executors, protocol translators, runtime model registry, management API, and public SDK. |
11 | | - |
12 | | -## STRUCTURE |
13 | | - |
14 | | -```text |
15 | | -CLIProxyAPIPlus/ |
16 | | -├── cmd/server/main.go # binary entry: flags, login flows, service boot |
17 | | -├── internal/ # private server implementation |
18 | | -├── sdk/ # embeddable public API |
19 | | -├── auths/ # default auth-file directory |
20 | | -├── test/ # cross-package integration/sentinel tests |
21 | | -├── management.html # embedded Management Center bundle |
22 | | -└── config.example.yaml # config surface reference |
23 | | -``` |
24 | | - |
25 | | -## WHERE TO LOOK |
26 | | - |
27 | | -| Task | Location | Notes | |
28 | | -|------|----------|-------| |
29 | | -| Server boot / flags | `cmd/server/main.go` | `--config`, `--tui`, login flags, local-model mode. | |
30 | | -| Management routes | `internal/api/` | Gin server + `/v0/management/*`. Ollama and IP blacklist routes included. | |
31 | | -| Provider auth | `internal/auth/` | OAuth/token storage per provider. | |
32 | | -| Upstream execution | `internal/runtime/executor/` | HTTP/WebSocket calls after translation. 503 fallback handling. | |
33 | | -| Protocol translation | `internal/translator/` | source/target registration and JSON/SSE transforms. | |
34 | | -| Model catalog/routing | `internal/registry/` | static fallback, dynamic discovery, provider scoping. Ollama alias resolution. | |
35 | | -| Config/auth synthesis | `internal/config/`, `internal/watcher/` | YAML fields, hot reload, config-backed auths. | |
36 | | -| SDK embedding | `sdk/cliproxy/` | Builder and service lifecycle. | |
37 | | - |
38 | | -## RECENT CHANGES (v7.1.7-3) |
39 | | - |
40 | | -- **Ollama provider support**: Alias resolution fix in conductor switch statements; management routes for Ollama config. |
41 | | -- **503 fallback handling**: Added 503 to `shouldPreserveAttemptBudgetForStatus` for proper fallback behavior. |
42 | | -- **IP blacklist feature**: New management routes and runtime enforcement for blocking scanner probes and malicious IPs. |
43 | | -- **Scanner probe blocking**: Integrated IP blacklist into request validation pipeline. |
44 | | - |
45 | | -## COMMANDS |
| 5 | +## Repository |
| 6 | +- GitHub: https://github.com/router-for-me/CLIProxyAPI |
46 | 7 |
|
| 8 | +## Commands |
47 | 9 | ```bash |
48 | | -go build ./cmd/server |
49 | | -go run ./cmd/server --config config.yaml |
50 | | -go test ./... |
51 | | -goreleaser build --snapshot --clean |
52 | | -``` |
53 | | - |
54 | | -## CONVENTIONS |
55 | | - |
56 | | -- YAML keys are kebab-case; Go fields stay CamelCase. |
57 | | -- Provider additions usually touch config, watcher/synthesizer, registry/model discovery, executor, management API, and Center UI. |
58 | | -- Executor logs for upstream failures must include masked request and response context when diagnosing 4xx/5xx. |
59 | | -- `management.html` is served by Plus; local UI edits need Center build output copied back. |
60 | | -- Tag versioning: append `-2`, `-3`, ... to upstream base version (e.g., `v7.1.7-3` after `v7.1.7-2`). |
61 | | - |
62 | | -## ANTI-PATTERNS |
63 | | - |
64 | | -- Do not use `http.DefaultClient`; use configured clients/proxy-aware helpers. |
65 | | -- Do not log Authorization, cookies, refresh tokens, API keys, or raw auth files. |
66 | | -- Do not terminate handlers with `panic` or `log.Fatal`. |
67 | | -- Do not scatter model allowlists in handlers/executors; centralize via registry/config paths. |
68 | | - |
69 | | -## SUB-DOCUMENTS |
70 | | - |
71 | | -```text |
72 | | -internal/AGENTS.md |
73 | | -sdk/AGENTS.md |
| 10 | +gofmt -w . # Format (required after Go changes) |
| 11 | +go build -o cli-proxy-api ./cmd/server # Build |
| 12 | +go run ./cmd/server # Run dev server |
| 13 | +go test ./... # Run all tests |
| 14 | +go test -v -run TestName ./path/to/pkg # Run single test |
| 15 | +go build -o test-output ./cmd/server && rm test-output # Verify compile (REQUIRED after changes) |
74 | 16 | ``` |
| 17 | +- Common flags: `--config <path>`, `--tui`, `--standalone`, `--local-model`, `--no-browser`, `--oauth-callback-port <port>` |
| 18 | + |
| 19 | +## Config |
| 20 | +- Default config: `config.yaml` (template: `config.example.yaml`) |
| 21 | +- `.env` is auto-loaded from the working directory |
| 22 | +- Auth material defaults under `auths/` |
| 23 | +- Storage backends: file-based default; optional Postgres/git/object store (`PGSTORE_*`, `GITSTORE_*`, `OBJECTSTORE_*`) |
| 24 | + |
| 25 | +## Architecture |
| 26 | +- `cmd/server/` — Server entrypoint |
| 27 | +- `internal/api/` — Gin HTTP API (routes, middleware, modules) |
| 28 | +- `internal/api/modules/amp/` — Amp integration (Amp-style routes + reverse proxy) |
| 29 | +- `internal/thinking/` — Main thinking/reasoning pipeline. `ApplyThinking()` (apply.go) parses suffixes (`suffix.go`, suffix overrides body), normalizes config to canonical `ThinkingConfig` (`types.go`), normalizes and validates centrally (`validate.go`/`convert.go`), then applies provider-specific output via `ProviderApplier`. Do not break this "canonical representation → per-provider translation" architecture. |
| 30 | +- `internal/runtime/executor/` — Per-provider runtime executors (incl. Codex WebSocket) |
| 31 | +- `internal/translator/` — Provider protocol translators (and shared `common`) |
| 32 | +- `internal/registry/` — Model registry + remote updater (`StartModelsUpdater`); `--local-model` disables remote updates |
| 33 | +- `internal/store/` — Storage implementations and secret resolution |
| 34 | +- `internal/managementasset/` — Config snapshots and management assets |
| 35 | +- `internal/cache/` — Request signature caching |
| 36 | +- `internal/watcher/` — Config hot-reload and watchers |
| 37 | +- `internal/wsrelay/` — WebSocket relay sessions |
| 38 | +- `internal/usage/` — Usage and token accounting |
| 39 | +- `internal/tui/` — Bubbletea terminal UI (`--tui`, `--standalone`) |
| 40 | +- `sdk/cliproxy/` — Embeddable SDK entry (service/builder/watchers/pipeline) |
| 41 | +- `test/` — Cross-module integration tests |
| 42 | + |
| 43 | +## Code Conventions |
| 44 | +- Keep changes small and simple (KISS) |
| 45 | +- Comments in English only |
| 46 | +- If editing code that already contains non-English comments, translate them to English (don’t add new non-English comments) |
| 47 | +- For user-visible strings, keep the existing language used in that file/area |
| 48 | +- New Markdown docs should be in English unless the file is explicitly language-specific (e.g. `README_CN.md`) |
| 49 | +- As a rule, do not make standalone changes to `internal/translator/`. You may modify it only as part of broader changes elsewhere. |
| 50 | +- If a task requires changing only `internal/translator/`, run `gh repo view --json viewerPermission -q .viewerPermission` to confirm you have `WRITE`, `MAINTAIN`, or `ADMIN`. If you do, you may proceed; otherwise, file a GitHub issue including the goal, rationale, and the intended implementation code, then stop further work. |
| 51 | +- `internal/runtime/executor/` should contain executors and their unit tests only. Place any helper/supporting files under `internal/runtime/executor/helps/`. |
| 52 | +- Follow `gofmt`; keep imports goimports-style; wrap errors with context where helpful |
| 53 | +- Do not use `log.Fatal`/`log.Fatalf` (terminates the process); prefer returning errors and logging via logrus |
| 54 | +- Shadowed variables: use method suffix (`errStart := server.Start()`) |
| 55 | +- Wrap defer errors: `defer func() { if err := f.Close(); err != nil { log.Errorf(...) } }()` |
| 56 | +- Use logrus structured logging; avoid leaking secrets/tokens in logs |
| 57 | +- Avoid panics in HTTP handlers; prefer logged errors and meaningful HTTP status codes |
| 58 | +- Timeouts are allowed only during credential acquisition; after an upstream connection is established, do not set timeouts for any subsequent network behavior. Intentional exceptions that must remain allowed are the Codex websocket liveness deadlines in `internal/runtime/executor/codex_websockets_executor.go`, the wsrelay session deadlines in `internal/wsrelay/session.go`, the management APICall timeout in `internal/api/handlers/management/api_tools.go`, and the `cmd/fetch_antigravity_models` utility timeouts |
0 commit comments