docs: restructure user manual for i18n and add EN/JA translations

Reorganize docs/user-manual/ from flat structure to language subdirectories (zh/, en/, ja/) with shared assets/. Move existing Chinese docs into zh/, fix image paths, add multilingual navigation README, and translate all 23 markdown files (~4500 lines each) to English and Japanese.
2026-04-26 12:22:43 +08:00 · 2026-03-03 08:40:52 +08:00
parent ce9c23833a
commit bbed2a1fe1
70 changed files with 8916 additions and 124 deletions
--- a/docs/user-manual/en/4-proxy/4.1-service.md
+++ b/docs/user-manual/en/4-proxy/4.1-service.md
@@ -0,0 +1,222 @@
+# 4.1 Proxy Service
+
+## Overview
+
+The proxy service starts a local HTTP proxy through which all API requests are forwarded.
+
+**Primary uses**:
+- Record request logs
+- Track API usage
+- Support failover
+- Centrally manage requests from multiple applications
+
+## Start the Proxy
+
+### Option 1: Main Interface Toggle
+
+Click the **Proxy Toggle** button at the top of the main interface.
+
+Toggle states:
+- White: Proxy not running
+- Green: Proxy running
+
+![image-20260108011353927](../../assets/image-20260108011353927.png)
+
+### Option 2: Settings Page
+
+1. Open "Settings > Advanced > Proxy Service"
+2. Click the toggle in the top-right corner
+
+![image-20260108011338922](../../assets/image-20260108011338922.png)
+
+## Proxy Configuration
+
+### Basic Configuration
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Listen Address | IP address the proxy binds to | `127.0.0.1` |
+| Listen Port | Port the proxy listens on | `15721` |
+| Enable Logging | Whether to record request logs | Enabled |
+
+### Modify Configuration
+
+1. **Stop the proxy service** (must stop first)
+2. Modify the listen address or port
+3. Click "Save"
+4. Restart the proxy
+
+> Modifying address/port requires stopping the proxy service first
+
+### Listen Address Options
+
+| Address | Description |
+|---------|-------------|
+| `127.0.0.1` | Only accessible from local machine (recommended) |
+| `0.0.0.0` | Allow LAN access |
+
+## Running Status
+
+When the proxy is running, the panel displays the following information:
+
+### Service Address
+
+```
+http://127.0.0.1:15721
+```
+
+Click the "Copy" button to copy the address.
+
+### Current Providers
+
+Displays the currently used provider for each app:
+
+```
+Claude: PackyCode
+Codex: AIGoCode
+Gemini: Google Official
+```
+
+### Statistics
+
+| Metric | Description |
+|--------|-------------|
+| Active Connections | Number of requests currently being processed |
+| Total Requests | Total number of requests since startup |
+| Success Rate | Percentage of successful requests (>90% green, <=90% yellow) |
+| Uptime | How long the proxy has been running |
+
+### Failover Queue
+
+The proxy panel displays the failover queue by app type:
+
+```
+Claude
+├── 1. PackyCode      [Currently Using] ●
+├── 2. AIGoCode                          ●
+└── 3. Backup Provider                   ○
+
+Codex
+├── 1. AIGoCode       [Currently Using] ●
+└── 2. Backup Provider                   ●
+```
+
+Queue details:
+- Numbers indicate priority order
+- "Currently Using" label indicates the active provider
+- Health badges show provider status:
+  - Green: Healthy (0 consecutive failures)
+  - Yellow: Degraded (1-2 consecutive failures)
+  - Red: Unhealthy (3+ consecutive failures)
+
+## How It Works
+
+### Request Flow
+
+```mermaid
+sequenceDiagram
+    participant CLI as CLI Tool (Claude)
+    participant Proxy as Local Proxy (CC Switch)
+    participant API as API Provider (Anthropic)
+    participant DB as Data Store (Logger)
+
+    CLI->>Proxy: Send API request
+    Proxy->>DB: Record request log / track usage
+    Proxy->>API: Forward request
+    API-->>Proxy: Return response
+    Proxy-->>CLI: Return response
+```
+
+### Configuration Changes
+
+After starting the proxy and enabling app takeover, CC Switch modifies app configurations:
+
+**Claude**:
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
+  }
+}
+```
+
+**Codex**:
+```toml
+base_url = "http://127.0.0.1:15721/v1"
+```
+
+**Gemini**:
+```
+GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
+```
+
+## Stop the Proxy
+
+### Option 1: Main Interface Toggle
+
+Click the proxy toggle button to turn it off.
+
+### Option 2: Settings Page
+
+Turn off the toggle in the proxy service panel.
+
+### Post-stop Processing
+
+When stopping the proxy, CC Switch will:
+
+1. Restore app configurations to their original state
+2. Save request logs
+3. Close all connections
+
+## Log Recording
+
+### Enable Logging
+
+Enable the "Enable Logging" toggle in the proxy panel.
+
+### Log Contents
+
+Each request record includes:
+
+| Field | Description |
+|-------|-------------|
+| Time | Request time |
+| App | Claude / Codex / Gemini |
+| Provider | Provider used |
+| Model | Requested model |
+| Tokens | Input/output token count |
+| Latency | Request duration |
+| Status | Success/failure |
+
+### View Logs
+
+View request logs in the "Settings > Usage" tab.
+
+## FAQ
+
+### Port Already in Use
+
+Error message: `Address already in use`
+
+Solution:
+1. Change the port (e.g., to 5001)
+2. Or close the program occupying the port
+
+### Proxy Fails to Start
+
+Check:
+- Is the port occupied
+- Are there sufficient permissions
+- Is the firewall blocking it
+
+### Request Timeout
+
+Possible causes:
+- Network issues
+- Provider server issues
+- Incorrect proxy configuration
+
+Solutions:
+- Check network connection
+- Try accessing the provider API directly
+- Check provider configuration