From ec4c2c2f7b5314d4d45968805126f581da7db3d7 Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Tue, 6 Jan 2026 18:05:05 -0500 Subject: [PATCH] docs: update documentation for CCS v7.14.x with quota management --- docs/code-standards.md | 2 +- docs/codebase-summary.md | 11 ++++--- docs/project-overview-pdr.md | 26 ++++++++++++++-- docs/project-roadmap.md | 7 +++-- docs/system-architecture.md | 59 +++++++++++++++++++++++++++++++++--- docs/websearch.md | 2 ++ 6 files changed, 93 insertions(+), 14 deletions(-) diff --git a/docs/code-standards.md b/docs/code-standards.md index b4389cbc..64cca0e8 100644 --- a/docs/code-standards.md +++ b/docs/code-standards.md @@ -1,6 +1,6 @@ # CCS Code Standards -Last Updated: 2025-12-21 +Last Updated: 2026-01-06 Code standards, modularization patterns, and conventions for the CCS codebase. diff --git a/docs/codebase-summary.md b/docs/codebase-summary.md index f8b4ad44..67479076 100644 --- a/docs/codebase-summary.md +++ b/docs/codebase-summary.md @@ -1,8 +1,8 @@ # CCS Codebase Summary -Last Updated: 2025-12-22 +Last Updated: 2026-01-06 -Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, and v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers. +Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, and v7.14 Hybrid Quota Management. ## Repository Structure @@ -71,6 +71,8 @@ src/ │ ├── cliproxy-executor.ts # Main executor (666 lines) │ ├── config-generator.ts # Config file generation (531 lines) │ ├── account-manager.ts # Account management (509 lines) +│ ├── quota-manager.ts # Hybrid quota management (NEW v7.14) +│ ├── quota-fetcher.ts # Provider quota API integration (NEW v7.14) │ ├── platform-detector.ts # OS/arch detection │ ├── binary-manager.ts # Binary download/update │ ├── auth-handler.ts # Authentication handling @@ -79,8 +81,8 @@ src/ │ ├── service-manager.ts # Background service │ ├── proxy-detector.ts # Running proxy detection │ ├── startup-lock.ts # Race condition prevention -│ ├── remote-proxy-client.ts # Remote proxy health checks (NEW v7.1) -│ ├── proxy-config-resolver.ts # CLI/env/config merging (NEW v7.1) +│ ├── remote-proxy-client.ts # Remote proxy health checks (v7.1) +│ ├── proxy-config-resolver.ts # CLI/env/config merging (v7.1) │ ├── types.ts # ResolvedProxyConfig for local/remote modes │ └── [more files...] │ @@ -164,6 +166,7 @@ src/ | Auth | `auth/`, `cliproxy/auth/` | Authentication across providers | | Config | `config/`, `types/` | Configuration & type definitions | | Providers | `cliproxy/`, `copilot/`, `glmt/` | Provider integrations (7 CLIProxy providers: gemini, codex, agy, qwen, iflow, kiro, ghcp) | +| Quota | `cliproxy/quota-*.ts`, `account-manager.ts` | Hybrid quota management (v7.14) | | Remote Proxy | `cliproxy/remote-*.ts`, `proxy-config-resolver.ts` | Remote CLIProxy support (v7.1) | | Services | `web-server/`, `api/` | HTTP server, API services | | Utilities | `utils/`, `management/` | Helpers, diagnostics | diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md index f1f7db05..361bed83 100644 --- a/docs/project-overview-pdr.md +++ b/docs/project-overview-pdr.md @@ -1,6 +1,6 @@ # CCS Product Development Requirements (PDR) -Last Updated: 2025-12-22 +Last Updated: 2026-01-06 ## Product Overview @@ -8,9 +8,9 @@ Last Updated: 2025-12-22 **Tagline**: The universal AI profile manager for Claude Code -**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances. +**Description**: CLI wrapper enabling seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, OpenRouter, Qwen, Kimi, DeepSeek) with a React-based dashboard for configuration management. Supports both local and remote CLIProxyAPI instances with hybrid quota management. -**Current Version**: v7.2.x (Kiro + GitHub Copilot OAuth providers) +**Current Version**: v7.14.x (Hybrid Quota Management + Pause/Resume) --- @@ -98,6 +98,14 @@ CCS provides: - Protocol-based default ports (443 for HTTPS, 8317 for HTTP) - Dashboard UI for remote server configuration and testing +### FR-009: Quota Management (v7.14) +- Pause/resume individual accounts via `ccs cliproxy pause/resume ` +- Check quota status via `ccs cliproxy status [account]` +- Auto-failover when account exhausted +- Tier detection: free/paid/unknown +- Pre-flight quota checks before session start +- Dashboard UI with pause/resume toggles and tier badges + --- ## Non-Functional Requirements @@ -216,6 +224,13 @@ CCS provides: - [x] Authorization Code flow for Kiro (port 9876) - [x] Device Code flow for ghcp (no local port needed) +### v7.14 Release (Complete) +- [x] Hybrid quota management with auto-failover +- [x] `ccs cliproxy pause/resume/status` commands +- [x] API tier detection (free/paid/unknown) +- [x] Dashboard pause/resume toggles and tier badges +- [x] Pre-flight quota checks before session start + ### v8.0 Release (Planned - Q1 2026) - [ ] Multiple CLIProxyAPI instances (load balancing, failover) - [ ] Native git worktree support @@ -239,6 +254,11 @@ CCS provides: - AWS Kiro (Authorization Code OAuth) - Z.AI GLM API - OpenRouter API +- Moonshot Kimi API +- DeepSeek API +- Alibaba Qwen API +- Minimax API +- Azure Foundry API ### Third-Party Libraries - Express.js (web server) diff --git a/docs/project-roadmap.md b/docs/project-roadmap.md index 832a16a3..089907f2 100644 --- a/docs/project-roadmap.md +++ b/docs/project-roadmap.md @@ -1,6 +1,6 @@ # CCS Project Roadmap -Last Updated: 2025-12-22 +Last Updated: 2026-01-06 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans. @@ -23,6 +23,7 @@ All major modularization work is complete. The codebase evolved from monolithic | 9 | Test Infrastructure | 99 UI tests + 539 CLI tests, 90% coverage | | 10 | Remote CLIProxy | `proxy-config-resolver.ts`, `remote-proxy-client.ts` | | 11 | Kiro + ghcp Providers | OAuth support via CLIProxyAPIPlus (v7.2) | +| 12 | Hybrid Quota Management | `quota-manager.ts`, `quota-fetcher.ts` (v7.14) | **Metrics Achieved**: - Files >500 lines: 12 -> 5 (-58%) @@ -153,6 +154,7 @@ worktrees: - **#158**: Fix AGY OAuth flow - **#157**: ~~Add Kiro auth support from CLIProxyAPIPlus~~ **COMPLETE** (v7.2) - GitHub Copilot (ghcp) Device Code flow **COMPLETE** (v7.2) +- Hybrid quota management **COMPLETE** (v7.14) --- @@ -163,9 +165,10 @@ worktrees: | Modularization (Phases 1-9) | COMPLETE | - | | Remote CLIProxy Support (#142) | COMPLETE | v7.1 | | Kiro + GitHub Copilot OAuth (#157) | COMPLETE | v7.2 | +| Hybrid Quota Management | COMPLETE | v7.14 | | Critical Bug Fixes (#158, #155, #124) | PLANNED | Q1 2026 | | Multiple CLIProxyAPI Instances | PLANNED | Q1 2026 | -| Git Worktree Support | PLANNED | Q1 2026 | +| Git Worktree Support | PLANNED | Q2 2026 | | Enhanced Model Support | PLANNED | Q2 2026 | --- diff --git a/docs/system-architecture.md b/docs/system-architecture.md index 32d1e091..ac8f2daa 100644 --- a/docs/system-architecture.md +++ b/docs/system-architecture.md @@ -1,6 +1,6 @@ # CCS System Architecture -Last Updated: 2025-12-22 +Last Updated: 2026-01-06 High-level architecture documentation for the CCS (Claude Code Switch) system. @@ -8,12 +8,12 @@ High-level architecture documentation for the CCS (Claude Code Switch) system. ## System Overview -CCS is a CLI wrapper that enables seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, Kiro, GitHub Copilot). It consists of two main components: +CCS is a CLI wrapper that enables seamless switching between multiple Claude accounts and alternative AI providers (GLM, Gemini, Codex, Kiro, GitHub Copilot, OpenRouter, Qwen, Kimi, DeepSeek). It consists of two main components: 1. **CLI Application** (`src/`) - Node.js TypeScript CLI 2. **Dashboard UI** (`ui/`) - React web application served by Express -CCS v7.2 adds Kiro (AWS) and GitHub Copilot (ghcp) OAuth providers via CLIProxyAPIPlus. +CCS v7.14 adds Hybrid Quota Management with pause/resume/status commands and auto-failover. ``` +===========================================================================+ @@ -131,7 +131,9 @@ CCS v7.2 adds Kiro (AWS) and GitHub Copilot (ghcp) OAuth providers via CLIProxyA | cliproxy-executor| | copilot-package- | | glmt-proxy | | config-generator | | manager | | delta-accumulator| | account-manager | | [copilot logic] | | pipeline/ | - | auth/ | +------------------+ +------------------+ + | quota-manager | +------------------+ +------------------+ + | quota-fetcher | + | auth/ | | binary/ | | services/ | +------------------+ @@ -424,6 +426,55 @@ CCS v7.2 adds Kiro (AWS) and GitHub Copilot (ghcp) OAuth providers via CLIProxyA CCS_PROXY_FALLBACK_ENABLED Enable fallback (true/false) ``` +### Quota Management Flow (v7.14) + +``` ++===========================================================================+ +| Quota Management Architecture | ++===========================================================================+ + + Pre-Flight Check (before session start) + | + v + +------------------+ + | quota-manager.ts | Hybrid quota management + +------------------+ + | + +---> Get all active accounts for provider + | + +---> For each account: + | | + | v + | +------------------+ + | | quota-fetcher.ts | Provider-specific API calls + | +------------------+ + | | + | +---> Check isPaused flag --> Skip if paused + | | + | +---> Fetch quota from provider API + | | - Gemini: /models endpoint + | | - Codex: /api/v1/account + | | - Kiro: /api/usage + | | + | +---> Detect tier (free/paid/unknown) + | | + | +---> Check exhaustion status + | + +---> Select best account (not paused, not exhausted) + | + +---> Auto-failover to next account if current exhausted + + CLI Commands: + ccs cliproxy pause --> Set isPaused=true in account-manager + ccs cliproxy resume --> Set isPaused=false + ccs cliproxy status [account] --> Display quota + tier info + + Dashboard UI: + - Pause/Resume toggle per account + - Tier badge (free/paid/unknown) + - Quota usage display +``` + --- ## Configuration Architecture diff --git a/docs/websearch.md b/docs/websearch.md index 184588df..c7f92b58 100644 --- a/docs/websearch.md +++ b/docs/websearch.md @@ -1,5 +1,7 @@ # WebSearch Configuration Guide +Last Updated: 2026-01-06 + CCS provides automatic web search capability for all profiles, including third-party providers that cannot access Anthropic's native WebSearch API. ## How WebSearch Works