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-22 17:11:04 +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.2-takeover.md
+++ b/docs/user-manual/en/4-proxy/4.2-takeover.md
@@ -0,0 +1,195 @@
+# 4.2 App Takeover
+
+## Overview
+
+App takeover means letting CC Switch's proxy intercept and forward a specific application's API requests.
+
+When takeover is enabled:
+- The app's API requests are forwarded through the local proxy
+- Request logs and usage statistics can be recorded
+- Failover functionality becomes available
+
+## Prerequisites
+
+The proxy service must be started before using the app takeover feature.
+
+## Enable Takeover
+
+### Location
+
+Settings > Advanced > Proxy Service > App Takeover area
+
+### Steps
+
+1. Ensure the proxy service is started
+2. Find the "App Takeover" area
+3. Enable the toggle for the desired apps
+
+### Takeover Toggles
+
+| Toggle | Effect |
+|--------|--------|
+| Claude Takeover | Intercept Claude Code requests |
+| Codex Takeover | Intercept Codex requests |
+| Gemini Takeover | Intercept Gemini CLI requests |
+
+Multiple app takeovers can be enabled simultaneously.
+
+## How Takeover Works
+
+### Configuration Changes
+
+When takeover is enabled, CC Switch modifies the app's configuration file to point the API endpoint to the local proxy.
+
+**Claude configuration change**:
+
+```json
+// Before takeover
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
+  }
+}
+
+// After takeover
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:15721"
+  }
+}
+```
+
+**Codex configuration change**:
+
+```toml
+# Before takeover
+base_url = "https://api.openai.com/v1"
+
+# After takeover
+base_url = "http://127.0.0.1:15721/v1"
+```
+
+**Gemini configuration change**:
+
+```bash
+# Before takeover
+GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
+
+# After takeover
+GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
+```
+
+### Request Forwarding
+
+When the proxy receives a request:
+
+1. Identifies the request source (Claude/Codex/Gemini)
+2. Looks up the currently enabled provider for that app
+3. Forwards the request to the provider's actual endpoint
+4. Records the request log
+5. Returns the response to the app
+
+## Takeover Status Indicators
+
+### Main Interface Indicators
+
+When takeover is enabled, the main interface shows the following changes:
+
+- **Proxy logo color**: Changes from colorless to green
+- **Provider cards**: The currently active provider shows a green border
+
+### Provider Card States
+
+| State | Border Color | Description |
+|-------|--------------|-------------|
+| Currently Active | Blue | Provider in the config file (non-proxy mode) |
+| Proxy Active | Green | Provider actually used by the proxy |
+| Normal | Default | Unused provider |
+
+## Disable Takeover
+
+### Steps
+
+1. Turn off the corresponding app's takeover toggle in the proxy panel
+2. Or directly stop the proxy service
+
+### Configuration Restoration
+
+When disabling takeover, CC Switch will:
+
+1. Restore the app configuration to its pre-takeover state
+2. Save current request logs
+
+## Takeover and Provider Switching
+
+### Switching Providers in Takeover Mode
+
+When switching providers in takeover mode:
+
+1. Click the "Enable" button on a provider in the main interface
+2. The proxy immediately uses the new provider to forward requests
+3. **No need to restart the CLI tool**
+
+This is a major advantage of takeover mode: provider switching takes effect instantly.
+
+### Switching Without Takeover
+
+When switching providers without takeover:
+
+1. Configuration file is modified
+2. CLI tool must be restarted for changes to take effect
+
+## Multi-app Takeover
+
+Multiple apps can be taken over simultaneously, each managed independently:
+
+- Independent provider configurations
+- Independent failover queues
+- Independent request statistics
+
+## Use Cases
+
+### Scenario 1: Usage Monitoring
+
+Enable takeover + log recording to monitor API usage.
+
+### Scenario 2: Quick Switching
+
+With takeover enabled, switching providers does not require restarting CLI tools.
+
+### Scenario 3: Failover
+
+Enabling takeover is a prerequisite for using the failover feature.
+
+## Notes
+
+### Performance Impact
+
+The proxy adds minimal latency (typically < 10ms), negligible for most scenarios.
+
+### Network Requirements
+
+In takeover mode, CLI tools must be able to access the local proxy address.
+
+### Configuration Backup
+
+Before enabling takeover, CC Switch backs up the original configuration and restores it when disabled.
+
+## FAQ
+
+### Requests Fail After Takeover
+
+Check:
+- Is the proxy service running normally
+- Is the provider configuration correct
+- Is the network working properly
+
+### Configuration Not Restored After Disabling Takeover
+
+Possible causes:
+- Proxy exited abnormally
+- Configuration file was modified by another program
+
+Solutions:
+- Manually edit the provider and re-save
+- Or re-enable and then disable takeover