Skip to content

AGENTS.md

Latest commit

 

History

History
123 lines (100 loc) · 7.11 KB

AGENTS.md

File metadata and controls

123 lines (100 loc) · 7.11 KB

PROJECT KNOWLEDGE BASE

Generated: 2026-05-29 Commit: daf31abc Branch: main

OVERVIEW

CLI Proxy monorepo: Go proxy server (CLIProxyAPIPlus), React Management Center (Cli-Proxy-API-Management-Center), and usage keeper (cpa-usage-keeper). Root tracks nested projects as gitlinks without .gitmodules. Dashboard (CLIProxyAPI-Dashboard) was intentionally removed from this hierarchy.

STRUCTURE

cli-proxy/
├── CLIProxyAPIPlus/                  # Go proxy, OAuth/auth, executors, translators, SDK
├── Cli-Proxy-API-Management-Center/  # React 19 + Vite management UI; builds management.html
└── cpa-usage-keeper/                 # Go usage tracking service

WHERE TO LOOK

Task Location Notes
Proxy boot flags / server mode CLIProxyAPIPlus/cmd/server/main.go Single binary entry point.
Provider auth/execution CLIProxyAPIPlus/internal/auth/, CLIProxyAPIPlus/internal/runtime/executor/ Auth and executor responsibilities stay separate.
Protocol conversion CLIProxyAPIPlus/internal/translator/ Transform only; no network calls.
Management API backend CLIProxyAPIPlus/internal/api/handlers/management/ Frontend contract lives in Center src/services/api/.
Management UI routes Cli-Proxy-API-Management-Center/src/router/MainRoutes.tsx, src/pages/ HashRouter paths under management.html#/*.
Management UI API calls Cli-Proxy-API-Management-Center/src/services/api/ Browser components do not call endpoints directly.
Usage tracking cpa-usage-keeper/internal/poller/, cpa-usage-keeper/internal/service/ Redis queue polling + SQLite persistence.

CODE MAP

Symbol / Entry Type Location Role
main Go entry CLIProxyAPIPlus/cmd/server/main.go CLI flags, login flows, proxy service boot.
Service Go struct CLIProxyAPIPlus/sdk/cliproxy/service.go Runtime wiring: auth updates, executors, registry, server lifecycle.
AiProvidersPage React page Cli-Proxy-API-Management-Center/src/pages/AiProvidersPage.tsx Provider list and enable/delete orchestration.
MainRoutes React router Cli-Proxy-API-Management-Center/src/router/MainRoutes.tsx All management hash routes.

CROSS-PROJECT CONVENTIONS

  • Backend logs must mask tokens, cookies, API keys, and auth headers; use existing masking utilities first.
  • Translators are pure format conversion. Do not add HTTP calls, credential selection, or upstream execution there.
  • Management UI state changes go through Zustand actions; components must not mutate store state directly.
  • Management UI HTTP calls go through src/services/api/; no raw component-level /v0/management/* calls.
  • management.html changes require rebuilding Center and copying the single-file bundle into CLIProxyAPIPlus/management.html when embedding locally.

ANTI-PATTERNS

  • Do not reintroduce Trae-specific provider flows; Trae support is intentionally removed.
  • Do not put private endpoints in user-visible placeholders, fixtures, bundles, or reachable git history.
  • Do not use as any, @ts-ignore, empty catch blocks, or test deletion to hide failures.
  • Do not commit root gitlinks before committing nested repo changes they point to.

COMMANDS

# CLIProxyAPIPlus
cd CLIProxyAPIPlus
go build ./cmd/server
go test ./...

# Management Center
cd Cli-Proxy-API-Management-Center
npm run type-check
npm run build

# Usage Keeper
cd cpa-usage-keeper
go build ./cmd/server
go test ./...

ACTIVE SUB-DOCUMENTS

CLIProxyAPIPlus/AGENTS.md
CLIProxyAPIPlus/internal/AGENTS.md
CLIProxyAPIPlus/internal/api/AGENTS.md
CLIProxyAPIPlus/internal/api/handlers/management/AGENTS.md
CLIProxyAPIPlus/internal/auth/kiro/AGENTS.md
CLIProxyAPIPlus/internal/config/AGENTS.md
CLIProxyAPIPlus/internal/registry/AGENTS.md
CLIProxyAPIPlus/internal/runtime/executor/AGENTS.md
CLIProxyAPIPlus/internal/translator/AGENTS.md
CLIProxyAPIPlus/internal/util/AGENTS.md
CLIProxyAPIPlus/sdk/AGENTS.md
CLIProxyAPIPlus/sdk/cliproxy/AGENTS.md
CLIProxyAPIPlus/sdk/cliproxy/auth/AGENTS.md
Cli-Proxy-API-Management-Center/AGENTS.md
Cli-Proxy-API-Management-Center/src/components/providers/AGENTS.md
Cli-Proxy-API-Management-Center/src/components/ui/AGENTS.md
Cli-Proxy-API-Management-Center/src/pages/AGENTS.md
Cli-Proxy-API-Management-Center/src/services/api/AGENTS.md
Cli-Proxy-API-Management-Center/src/stores/AGENTS.md
cpa-usage-keeper/AGENTS.md

NOTES

  • Root git status is the source of truth for nested project pointers; .gitmodules is absent.
  • Search tools may miss nested gitlink files from root. Re-run file discovery inside nested repos when editing subproject AGENTS.md.
  • Do not create release tags from the repository root. Create tags only inside the relevant subdirectory repository.
  • Tag versioning workflow: 1) git fetch --tags upstream to fetch upstream latest tags. 2) git ls-remote --tags upstream | grep -E 'refs/tags/v[0-9]' | sed 's|.*refs/tags/||' | sort -V | tail -10 to identify the latest upstream base version. 3) Use that base version with a sequence suffix: v<upstream_base>-<sequence>. Sequence starts at 1 for each new base.
  • For follow-up releases on the same base version, increment the suffix (e.g., v7.1.22-1 → v7.1.22-2).
  • When upstream releases a new base version (e.g., v7.1.22), create a new tag starting at suffix -1 (e.g., v7.1.22-1) even if the previous base had higher suffixes.
  • Only propose a new base tag when the user explicitly wants a new release line or that repository's recent tag history clearly starts a new base series.
  • Always verify upstream latest tags before tagging. The repo AGENTS.md Latest tags line may be stale; run the fetch command above to get the actual latest.
  • Upstream merges: always check server.go for duplicate route registration after merging.
  • Re-tagging: delete GitHub release assets first, then re-run goreleaser (otherwise 422 already_exists).
  • Every push requires a version bump. When pushing code changes to any subdirectory repository, increment the tag suffix and create a new tag. No code should remain untagged on origin.
  • Latest tags: CLIProxyAPIPlus: v7.1.28-1, Cli-Proxy-API-Management-Center: v1.14.0-9, cpa-usage-keeper: v1.8.6-1. Re-check before tagging.

RECENT CHANGES

  • CLIProxyAPIPlus v7.1.28-1: Token usage logging, gpt-5.5 restore for codex free tier.
  • CLIProxyAPIPlus v7.1.27-1: Mistral base_url /v1 suffix stripping fix.
  • CLIProxyAPIPlus v7.1.25-2: Mistral standalone provider, management API key CRUD, TTFT tracking, service tier usage, cache token reporting.
  • CLIProxyAPIPlus v7.1.23-8: CommandCode null content block fix (400 BAD_REQUEST on tool-heavy conversations).
  • Management Center v1.14.0-9: UI updates through v1.14.0-4 (priority column, CommandCode provider integration).
  • cpa-usage-keeper v1.8.6-1: Usage keeper updates.
  • Previous: CommandCode synthesizer/diff/SDK/watcher integration, upstream merges (v7.1.24 TTFT, helps migration, claudeCredsForAuthLookup restoration), CommandCode management API handler, config API key, model registration. See git log for full history.