tiennm99/ccs
1
0
Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-07-15 22:21:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update documentation for v7.1 remote CLIProxy feature

Browse Source 
- README: add remote CLIProxy section with CLI flags and quick setup
- code-standards: add Config Priority Pattern (CLI > ENV > config.yaml)
- codebase-summary: add new remote proxy files, update test counts (638)
- project-overview-pdr: add FR-008 requirement, v7.1 release section
- project-roadmap: add Phase 10 (Remote CLIProxy), mark #142 complete
- system-architecture: add Remote CLIProxy Flow diagram
This commit is contained in:
kaitranntt
2025-12-21 20:09:46 -05:00
parent 326e7592f2
commit ec7781bbc8
6 changed files with 161 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+31
View File
@@ -255,6 +255,37 @@ See [docs/websearch.md](./docs/websearch.md) for detailed configuration and trou
<br>
## Remote CLIProxy
CCS v7.x supports connecting to remote CLIProxyAPI instances, enabling:
- **Team sharing**: One CLIProxyAPI server for multiple developers
- **Cost optimization**: Centralized API key management
- **Network isolation**: Keep API credentials on a secure server
### Quick Setup
Configure via dashboard (**Settings > CLIProxy Server**) or CLI flags:
```bash
ccs gemini --proxy-host 192.168.1.100 --proxy-port 8317
ccs codex --proxy-host proxy.example.com --proxy-protocol https
```
### CLI Flags
| Flag | Description |
|------|-------------|
| `--proxy-host` | Remote proxy hostname or IP |
| `--proxy-port` | Remote proxy port (default: 8317 for HTTP, 443 for HTTPS) |
| `--proxy-protocol` | `http` or `https` (default: http) |
| `--proxy-auth-token` | Bearer token for authentication |
| `--local-proxy` | Force local mode, ignore remote config |
| `--remote-only` | Fail if remote unreachable (no fallback) |
See [Remote Proxy documentation](https://docs.ccs.kaitran.ca/features/remote-proxy) for detailed setup.
<br>
## Documentation
| Topic | Link |
docs/code-standards.md
+20
View File
@@ -580,6 +580,26 @@ interface Config { ... }
export interface Config { ... }
```
### 5. Config Priority Pattern
When resolving configuration from multiple sources, follow this priority order:
```typescript
// proxy-config-resolver.ts pattern
// Priority: CLI flags > Environment variables > config.yaml > defaults
const resolved = {
...DEFAULT_CONFIG, // 4. Defaults (lowest)
...yamlConfig, // 3. config.yaml
...envConfig, // 2. Environment variables
...cliFlags, // 1. CLI flags (highest)
};
```
This pattern is used in:
- `src/cliproxy/proxy-config-resolver.ts` - Remote proxy config
- `src/config/unified-config-loader.ts` - Main config loading
---
## Related Documentation
docs/codebase-summary.md
+12 -6
View File
@@ -2,7 +2,7 @@
Last Updated: 2025-12-21
Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure).
Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure) and v7.1 Remote CLIProxy feature.
## Repository Structure
@@ -79,6 +79,9 @@ 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)
│ ├── types.ts # ResolvedProxyConfig for local/remote modes
│ └── [more files...]
│
├── copilot/ # GitHub Copilot integration
@@ -161,6 +164,7 @@ src/
| Auth | `auth/`, `cliproxy/auth/` | Authentication across providers |
| Config | `config/`, `types/` | Configuration & type definitions |
| Providers | `cliproxy/`, `copilot/`, `glmt/` | Provider integrations |
| 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 |
@@ -462,12 +466,14 @@ tests/
| Metric | Value |
|--------|-------|
| Total Tests | 497 |
| Passing | 497 |
| Skipped | 2 |
| Failed | 0 |
| CLI Tests | 539 |
| UI Tests | 99 |
| Total Tests | 638 |
| Passing | 612 |
| Skipped | 6 |
| Failed | 0 (CLI), 26 (UI - jsdom setup) |
| Coverage Threshold | 90% |
| Test Files | 29 |
| Test Files | 38 |
---
docs/project-overview-pdr.md
+21 -4
View File
@@ -8,9 +8,9 @@ Last Updated: 2025-12-21
**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.
**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.
**Current Version**: v7.x (OpenRouter integration added)
**Current Version**: v7.1.x (Remote CLIProxy routing, OpenRouter integration)
---
@@ -90,6 +90,14 @@ CCS provides:
- Support Gemini CLI, OpenCode, Grok providers
- Graceful fallback chain
### FR-008: Remote CLIProxy Support
- Connect to remote CLIProxyAPI instances
- CLI flags for proxy configuration (--proxy-host, --proxy-port, etc.)
- Environment variable configuration (CCS_PROXY_HOST, etc.)
- Fallback to local proxy when remote unreachable
- Protocol-based default ports (443 for HTTPS, 8317 for HTTP)
- Dashboard UI for remote server configuration and testing
---
## Non-Functional Requirements
@@ -167,7 +175,7 @@ CCS provides:
| Startup time | < 100ms | Achieved |
| Dashboard load | < 2s | Achieved |
| Error rate | < 1% | Achieved |
| Test coverage | > 90% | 90% (497 tests) |
| Test coverage | > 90% | 90% (539 CLI + 99 UI tests) |
| File size compliance | 100% < 200 lines | 95% |
---
@@ -191,7 +199,16 @@ CCS provides:
- [x] Settings page modularization (20 files)
- [x] Analytics page modularization (8 files)
- [x] Auth monitor modularization (8 files)
- [x] Comprehensive test infrastructure (497 tests)
- [x] Comprehensive test infrastructure (539 CLI + 99 UI tests)
### v7.1 Release (Complete)
- [x] Remote CLIProxy routing support
- [x] CLI flags for remote proxy (--proxy-host, --proxy-port, etc.)
- [x] Environment variables for proxy config (CCS_PROXY_*)
- [x] Dashboard remote proxy configuration UI
- [x] Connection testing with latency display
- [x] Fallback to local when remote unreachable
- [x] Protocol-based default ports (HTTPS:443, HTTP:8317)
### v8.0 Release (Planned - Q1 2026)
- [ ] Multiple CLIProxyAPI instances (load balancing, failover)
docs/project-roadmap.md
+12 -9
View File
@@ -17,16 +17,18 @@ All major modularization work is complete. The codebase evolved from monolithic
| 3 | CLIProxy | `src/cliproxy/` with auth/, binary/, services/ subdirs |
| 4 | Utils/Errors | `src/utils/ui/`, `src/errors/`, `src/management/` |
| 5 | UI Components | 5 monster files split into modular dirs (54+ modules) |
| 6 | Settings Page | `pages/settings/` (1,781→20 files) |
| 7 | Analytics Page | `pages/analytics/` (420→8 files) |
| 8 | Auth Monitor | `monitoring/auth-monitor/` (465→8 files) |
| 9 | Test Infrastructure | 99 UI tests + 497 CLI tests, 90% coverage |
| 6 | Settings Page | `pages/settings/` (1,781->20 files) |
| 7 | Analytics Page | `pages/analytics/` (420->8 files) |
| 8 | Auth Monitor | `monitoring/auth-monitor/` (465->8 files) |
| 9 | Test Infrastructure | 99 UI tests + 539 CLI tests, 90% coverage |
| 10 | Remote CLIProxy | `proxy-config-resolver.ts`, `remote-proxy-client.ts` |
**Metrics Achieved**:
- Files >500 lines: 12 → 5 (-58%)
- UI files >200 lines: 28 → 8 (-71%)
- Barrel exports: 5 → 39 (+680%)
- Test coverage: 0% → 90%
- Files >500 lines: 12 -> 5 (-58%)
- UI files >200 lines: 28 -> 8 (-71%)
- Barrel exports: 5 -> 39 (+680%)
- Test coverage: 0% -> 90%
- Total tests: 638 (539 CLI + 99 UI)
---
@@ -59,7 +61,7 @@ All major modularization work is complete. The codebase evolved from monolithic
| Issue | Title | Type | Status |
|-------|-------|------|--------|
| #142 | Configure with available CLIProxyAPI | enhancement | **IN PROGRESS** |
| #142 | Configure with available CLIProxyAPI | enhancement | **COMPLETE** (v7.1) |
| #157 | Support for Kiro auth from CLIProxyAPIPlus | enhancement | - |
| #123 | Add More Models | enhancement | Ongoing |
| #114 | OpenCode Zen Free model + Auto Rotation API Key | enhancement | - |
@@ -157,6 +159,7 @@ worktrees:
| Milestone | Status | Target |
|-----------|--------|--------|
| Modularization (Phases 1-9) | COMPLETE | - |
| Remote CLIProxy Support (#142) | COMPLETE | v7.1 |
| Critical Bug Fixes (#158, #155, #124) | PLANNED | Q1 2026 |
| Multiple CLIProxyAPI Instances | PLANNED | Q1 2026 |
| Git Worktree Support | PLANNED | Q1 2026 |
docs/system-architecture.md
+65 -4
View File
@@ -13,6 +13,8 @@ CCS is a CLI wrapper that enables seamless switching between multiple Claude acc
1. **CLI Application** (`src/`) - Node.js TypeScript CLI
2. **Dashboard UI** (`ui/`) - React web application served by Express
CCS v7.1 adds support for both **local** and **remote** CLIProxyAPI instances.
```
+===========================================================================+
| CCS System |
@@ -30,10 +32,10 @@ CCS is a CLI wrapper that enables seamless switching between multiple Claude acc
| +------------------+ +-----------------+ | Gemini/etc) | |
| | +----------------+ |
| v |
| +-----------------+ |
| | CLIProxyAPI | |
| | (Binary) | |
| +-----------------+ |
| +---------------------+ |
| | CLIProxyAPI | |
| | (Local or Remote) | |
| +---------------------+ |
| |
+===========================================================================+
```
@@ -350,6 +352,65 @@ CCS is a CLI wrapper that enables seamless switching between multiple Claude acc
+------------------+
```
### Remote CLIProxy Flow (v7.1)
```
+===========================================================================+
| Remote CLIProxy Architecture |
+===========================================================================+
Config Resolution (proxy-config-resolver.ts)
|
+---> Priority: CLI flags > ENV vars > config.yaml > defaults
|
v
+------------------+
| ResolvedProxyConfig |
| mode: local|remote |
+------------------+
|
+---> [mode = local] ---> Spawn local CLIProxyAPI binary
| |
| v
| localhost:8317
|
+---> [mode = remote] ---> Connect to remote server
|
v
+------------------+
| Health Check | remote-proxy-client.ts
| /v1/models | 2s timeout
+------------------+
|
+---> [reachable] ---> Use remote
| |
| v
| protocol://host:port
|
+---> [unreachable] ---> Fallback decision
|
+-----------------------------+
|
+---> [fallbackEnabled] ---> Start local
|
+---> [remoteOnly] ---> Fail with error
CLI Flags:
--proxy-host <host> Remote hostname/IP
--proxy-port <port> Port (default: 8317 HTTP, 443 HTTPS)
--proxy-protocol <proto> http or https
--proxy-auth-token <token> Bearer authentication
--local-proxy Force local mode
--remote-only Fail if remote unreachable
Environment Variables:
CCS_PROXY_HOST Remote hostname
CCS_PROXY_PORT Remote port
CCS_PROXY_PROTOCOL Protocol (http/https)
CCS_PROXY_AUTH_TOKEN Auth token
CCS_PROXY_FALLBACK_ENABLED Enable fallback (true/false)
```
---
## Configuration Architecture