From e7608ada4a0f3ad9e550bf3bab2eaf90f72477a6 Mon Sep 17 00:00:00 2001 From: musistudio Date: Thu, 1 Jan 2026 21:17:41 +0800 Subject: [PATCH] fix docs --- CLAUDE.md | 8 +- docs/docs/cli/commands/other.md | 101 +- docs/docs/cli/commands/preset.md | 254 ++++ docs/docs/cli/commands/statusline.md | 400 ++++++ docs/docs/cli/installation.md | 6 +- docs/docs/cli/intro.md | 34 +- docs/docs/cli/quick-start.md | 54 +- docs/docs/server/advanced/agents.md | 40 - docs/docs/server/advanced/presets.md | 490 +++++-- docs/docs/server/api/logs-api.md | 24 - docs/docs/server/api/overview.md | 41 - docs/i18n/en/code.json | 329 +++++ .../options.json | 14 + .../current.json | 90 ++ .../en/docusaurus-theme-classic/footer.json | 30 + .../en/docusaurus-theme-classic/navbar.json | 22 + .../advanced/custom-router.md | 0 .../advanced/preset-format.md | 18 +- .../advanced/presets.md | 673 +++++++++ .../cli/commands/preset.md | 254 ++++ .../cli/commands/statusline.md | 402 ++++++ .../cli/config/basic.md | 0 .../cli/config/project-level.md | 0 .../cli/intro.md | 5 +- .../cli/model.md | 0 .../cli/other-commands.md | 85 ++ .../cli/start.md | 0 .../cli/status.md | 0 .../config/basic.md | 0 .../config/providers.md | 0 .../config/routing.md | 0 .../config/transformers.md | 0 .../current.json | 78 ++ .../installation.md | 6 +- .../intro.md | 18 +- .../quick-start.md | 0 .../server/api/config-api.md | 0 .../server/api/logs-api.md | 24 - .../server/api/messages-api.md | 0 .../server/api/overview.md | 41 - .../server/deployment.md | 0 .../server/intro.md | 0 .../advanced/agents.md | 112 -- .../advanced/presets.md | 394 ------ .../cli/other-commands.md | 203 --- .../current/cli/commands/model.md | 127 ++ .../current/cli/commands/other.md | 84 ++ .../current/cli/commands/preset.md | 254 ++++ .../current/cli/commands/start.md | 82 ++ .../current/cli/commands/status.md | 63 + .../current/cli/commands/statusline.md | 401 ++++++ .../current/cli/config/basic.md | 208 +++ .../current/cli/config/project-level.md | 213 +++ .../current/cli/installation.md | 46 + .../current/cli/intro.md | 70 + .../current/cli/quick-start.md | 82 ++ .../current/server/advanced/custom-router.md | 148 ++ .../current/server/advanced/preset-format.md | 1197 +++++++++++++++++ .../current/server/advanced/presets.md | 672 +++++++++ .../current/server/api/config-api.md | 220 +++ .../current/server/api/logs-api.md | 166 +++ .../current/server/api/messages-api.md | 220 +++ .../current/server/api/overview.md | 88 ++ .../current/server/config/basic.md | 160 +++ .../current/server/config/providers.md | 212 +++ .../current/server/config/routing.md | 164 +++ .../current/server/config/transformers.md | 282 ++++ .../current/server/deployment.md | 182 +++ .../current/server/intro.md | 77 ++ .../docusaurus-theme-classic/footer.json | 2 +- docs/package.json | 1 + docs/sidebars.ts | 5 +- docs/src/css/custom.css | 113 ++ docs/src/pages/index.tsx | 4 +- docs/tailwind.config.js | 24 +- pnpm-lock.yaml | 22 + 76 files changed, 8652 insertions(+), 1187 deletions(-) create mode 100644 docs/docs/cli/commands/preset.md create mode 100644 docs/docs/cli/commands/statusline.md delete mode 100644 docs/docs/server/advanced/agents.md create mode 100644 docs/i18n/en/code.json create mode 100644 docs/i18n/en/docusaurus-plugin-content-blog/options.json create mode 100644 docs/i18n/en/docusaurus-plugin-content-docs/current.json create mode 100644 docs/i18n/en/docusaurus-theme-classic/footer.json create mode 100644 docs/i18n/en/docusaurus-theme-classic/navbar.json rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/advanced/custom-router.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/advanced/preset-format.md (98%) create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/presets.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/preset.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/statusline.md rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/cli/config/basic.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/cli/config/project-level.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/cli/intro.md (89%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/cli/model.md (100%) create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/other-commands.md rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/cli/start.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/cli/status.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/config/basic.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/config/providers.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/config/routing.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/config/transformers.md (100%) create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/current.json rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/installation.md (80%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/intro.md (74%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/quick-start.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/server/api/config-api.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/server/api/logs-api.md (86%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/server/api/messages-api.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/server/api/overview.md (74%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/server/deployment.md (100%) rename docs/i18n/zh-CN/{docusaurus-plugin-content-docs => docusaurus-plugin-content-docs.backup.20260101_205603}/server/intro.md (100%) delete mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/agents.md delete mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/presets.md delete mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/other-commands.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/model.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/other.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/preset.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/start.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/status.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/statusline.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/basic.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/project-level.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/installation.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/intro.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/quick-start.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/custom-router.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/preset-format.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/presets.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/config-api.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/logs-api.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/messages-api.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/overview.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/basic.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/providers.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/routing.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/transformers.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/deployment.md create mode 100644 docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/intro.md diff --git a/CLAUDE.md b/CLAUDE.md index d454b96..bc14ae4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,10 +6,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Claude Code Router is a tool that routes Claude Code requests to different LLM providers. It uses a Monorepo architecture with four main packages: -- **cli** (`@musistudio/claude-code-router-cli`): Command-line tool providing the `ccr` command -- **server** (`@musistudio/claude-code-router-server`): Core server handling API routing and transformations -- **shared** (`@musistudio/claude-code-router-shared`): Shared constants, utilities, and preset management -- **ui** (`@musistudio/claude-code-router-ui`): Web management interface (React + Vite) +- **cli** (`@musistudio/claude-code-router`): Command-line tool providing the `ccr` command +- **server** (`@CCR/server`): Core server handling API routing and transformations +- **shared** (`@CCR/shared`): Shared constants, utilities, and preset management +- **ui** (`@CCR/ui`): Web management interface (React + Vite) ## Build Commands diff --git a/docs/docs/cli/commands/other.md b/docs/docs/cli/commands/other.md index 884dc97..bbc5151 100644 --- a/docs/docs/cli/commands/other.md +++ b/docs/docs/cli/commands/other.md @@ -30,27 +30,6 @@ Execute a claude command through the router. ccr code [args...] ``` -## ccr activate - -Output shell environment variables for integration. - -```bash -ccr activate -``` - -Output: - -```bash -export ANTHROPIC_API_URL="http://localhost:8080/v1" -export ANTHROPIC_API_KEY="sk-xxxxx" -``` - -To use in your shell: - -```bash -eval "$(ccr activate)" -``` - ## ccr ui Open the Web UI in your browser. @@ -59,76 +38,14 @@ Open the Web UI in your browser. ccr ui ``` -## ccr statusline +## ccr activate -Integrated statusline (reads JSON from stdin). +Output shell environment variables for integration with external tools. ```bash -echo '{"status":"running"}' | ccr statusline +ccr activate ``` -## ccr config - -Configuration management commands. - -### Edit Configuration - -```bash -ccr config edit -``` - -Opens the configuration file in your default editor. - -### Validate Configuration - -```bash -ccr config validate -``` - -Validates the current configuration file. - -### Show Configuration - -```bash -ccr config show -``` - -Displays the current configuration (with sensitive values masked). - -## ccr preset - -Preset management commands. - -### List Presets - -```bash -ccr preset list -``` - -### Apply Preset - -```bash -ccr preset apply -``` - -### Save Preset - -```bash -ccr preset save -``` - -## ccr log - -View server logs. - -```bash -ccr log [options] -``` - -Options: -- `-f, --follow`: Follow log output (like `tail -f`) -- `-n `: Number of lines to show - ## Global Options These options can be used with any command: @@ -154,24 +71,12 @@ ccr stop ccr restart --config /path/to/config.json ``` -### View and set environment variables - -```bash -eval "$(ccr activate)" -``` - ### Open Web UI ```bash ccr ui ``` -### Follow logs - -```bash -ccr log -f -``` - ## Related Documentation - [Getting Started](/docs/intro) - Introduction to Claude Code Router diff --git a/docs/docs/cli/commands/preset.md b/docs/docs/cli/commands/preset.md new file mode 100644 index 0000000..663e160 --- /dev/null +++ b/docs/docs/cli/commands/preset.md @@ -0,0 +1,254 @@ +--- +sidebar_position: 5 +--- + +# ccr preset + +Manage presets - configuration templates that can be shared and reused. + +## Overview + +Presets allow you to: +- Save your current configuration as a reusable template +- Share configurations with others +- Install pre-configured setups from the community +- Switch between different configurations easily + +## Commands + +### export + +Export your current configuration as a preset. + +```bash +ccr preset export [options] +``` + +**Options:** +- `--output ` - Custom output directory path +- `--description ` - Preset description +- `--author ` - Preset author +- `--tags ` - Comma-separated keywords +- `--include-sensitive` - Include API keys and sensitive data (not recommended) + +**Example:** +```bash +ccr preset export my-config --description "My production setup" --author "Your Name" +``` + +**What happens:** +1. Reads current configuration from `~/.claude-code-router/config.json` +2. Prompts for description, author, and keywords (if not provided) +3. Sanitizes sensitive fields (API keys become placeholders) +4. Creates preset directory at `~/.claude-code-router/presets//` +5. Generates `manifest.json` with configuration and metadata + +### install + +Install a preset from a local directory. + +```bash +ccr preset install +``` + +**Sources:** +- Local directory path: `/path/to/preset-directory` +- Preset name (for reconfiguring an already installed preset): `preset-name` + +**Example:** +```bash +# Install from directory +ccr preset install ./my-preset + +# Reconfigure an installed preset +ccr preset install my-preset +``` + +**What happens:** +1. Reads `manifest.json` from the preset directory +2. Validates the preset structure +3. If the preset has a `schema`, prompts for required values (API keys, etc.) +4. Copies preset to `~/.claude-code-router/presets//` +5. Saves user inputs in `manifest.json` + +**Note:** URL installation is not currently supported. Download the preset directory first. + +### list + +List all installed presets. + +```bash +ccr preset list +``` + +**Example output:** +``` +Available presets: + +• my-config (v1.0.0) + My production setup + by Your Name + +• openai-setup + Basic OpenAI configuration +``` + +### info + +Show detailed information about a preset. + +```bash +ccr preset info +``` + +**Shows:** +- Version, description, author, keywords +- Configuration summary (Providers, Router rules) +- Required inputs (if any) + +**Example:** +```bash +ccr preset info my-config +``` + +### delete / rm / remove + +Delete an installed preset. + +```bash +ccr preset delete +ccr preset rm +ccr preset remove +``` + +**Example:** +```bash +ccr preset delete my-config +``` + +## Preset Structure + +A preset is a directory containing a `manifest.json` file: + +```json +{ + "name": "my-preset", + "version": "1.0.0", + "description": "My configuration", + "author": "Author Name", + "keywords": ["openai", "production"], + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "{{apiKey}}", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + + "Router": { + "default": "openai:gpt-4" + }, + + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "OpenAI API Key", + "prompt": "Enter your OpenAI API key" + } + ] +} +``` + +### Schema System + +The `schema` field defines inputs that users must provide during installation: + +**Field types:** +- `password` - Hidden input (for API keys) +- `input` - Text input +- `select` - Single selection from options +- `multiselect` - Multiple selection +- `confirm` - Yes/No confirmation +- `editor` - Multi-line text +- `number` - Numeric input + +**Dynamic options:** +```json +{ + "id": "provider", + "type": "select", + "label": "Select Provider", + "options": { + "type": "providers" + } +} +``` + +**Conditional fields:** +```json +{ + "id": "model", + "type": "select", + "label": "Select Model", + "when": { + "field": "provider", + "operator": "exists" + }, + "options": { + "type": "models", + "providerField": "#{selectedProvider}" + } +} +``` + +## Sharing Presets + +To share a preset: + +1. **Export your configuration:** + ```bash + ccr preset export my-preset + ``` + +2. **Share the directory:** + ```bash + ~/.claude-code-router/presets/my-preset/ + ``` + +3. **Distribution methods:** + - Upload to GitHub repository + - Create a GitHub Gist + - Share as a zip file + - Publish on npm (future feature) + +4. **Users install with:** + ```bash + ccr preset install /path/to/my-preset + ``` + +## Security + +### Automatic Sanitization + +By default, `export` sanitizes sensitive fields: +- Fields named `api_key`, `apikey`, `password`, `secret` are replaced with `{{fieldName}}` placeholders +- These placeholders become required inputs in the schema +- Users are prompted to provide their own values during installation + +### Include Sensitive Data + +To include actual values (not recommended): +```bash +ccr preset export my-preset --include-sensitive +``` + +**Warning:** Never share presets containing sensitive data! + +## Related Documentation + +- [Configuration Guide](/docs/cli/config/basic) - Basic configuration +- [Project-Level Configuration](/docs/cli/config/project-level) - Project-specific settings +- [Server: Presets](/docs/server/advanced/presets) - Advanced preset topics diff --git a/docs/docs/cli/commands/statusline.md b/docs/docs/cli/commands/statusline.md new file mode 100644 index 0000000..5c55d1e --- /dev/null +++ b/docs/docs/cli/commands/statusline.md @@ -0,0 +1,400 @@ +--- +sidebar_position: 5 +--- + +# ccr statusline + +Display a customizable status bar showing real-time information about your Claude Code session, including workspace, Git branch, model, token usage, and more. + +## Overview + +The `ccr statusline` command reads JSON data from stdin and renders a beautifully formatted status bar in your terminal. It's designed to integrate with Claude Code's hook system to display real-time session information. + +## Usage + +### Basic Usage + +```bash +ccr statusline +``` + +The command expects JSON data via stdin, typically piped from a Claude Code hook: + +```bash +echo '{"hook_event_name":"...","session_id":"...","..."}' | ccr statusline +``` + +### Hook Integration + +Configure in your Claude Code settings: + +```json +{ + "hooks": { + "postResponse": { + "command": "ccr statusline", + "input": "json" + } + } +} +``` + +## Available Themes + +### Default Theme + +A clean, minimal theme with Nerd Font icons and colored text: + +``` + 󰉋 my-project  main 󰚩 claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +### Powerline Theme + +A vim-powerline inspired style with colored backgrounds and arrow separators: + +``` + 󰉋 my-project  main 󰚩 claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +Activate by setting `currentStyle: "powerline"` in your config. + +### Simple Theme + +Fallback theme without icons for terminals that don't support Nerd Fonts: + +``` +my-project main claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +Automatically used when `USE_SIMPLE_ICONS=true` or on unsupported terminals. + +## Available Modules + +Status line modules display different types of information: + +| Module | Description | Variables | +|--------|-------------|-----------| +| **workDir** | Current working directory name | `{{workDirName}}` | +| **gitBranch** | Current Git branch | `{{gitBranch}}` | +| **model** | Model being used | `{{model}}` | +| **usage** | Token usage (input/output) | `{{inputTokens}}`, `{{outputTokens}}` | +| **context** | Context window usage | `{{contextPercent}}`, `{{contextWindowSize}}` | +| **speed** | Token processing speed | `{{tokenSpeed}}`, `{{isStreaming}}` | +| **cost** | API cost | `{{cost}}` | +| **duration** | Session duration | `{{duration}}` | +| **lines** | Code changes | `{{linesAdded}}`, `{{linesRemoved}}` | +| **script** | Custom script output | Dynamic | + +## Configuration + +Configure statusline in `~/.claude-code-router/config.json`: + +### Default Style Example + +```json +{ + "StatusLine": { + "currentStyle": "default", + "default": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "model", + "icon": "󰚩", + "text": "{{model}}", + "color": "bright_cyan" + }, + { + "type": "usage", + "icon": "↑", + "text": "{{inputTokens}}", + "color": "bright_green" + }, + { + "type": "usage", + "icon": "↓", + "text": "{{outputTokens}}", + "color": "bright_yellow" + } + ] + } + } +} +``` + +### Powerline Style Example + +```json +{ + "StatusLine": { + "currentStyle": "powerline", + "powerline": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "white", + "background": "bg_bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "white", + "background": "bg_bright_magenta" + } + ] + } + } +} +``` + +### Full Featured Example + +```json +{ + "StatusLine": { + "currentStyle": "default", + "default": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "model", + "icon": "󰚩", + "text": "{{model}}", + "color": "bright_cyan" + }, + { + "type": "context", + "icon": "🪟", + "text": "{{contextPercent}}% / {{contextWindowSize}}", + "color": "bright_green" + }, + { + "type": "speed", + "icon": "⚡", + "text": "{{tokenSpeed}} t/s {{isStreaming}}", + "color": "bright_yellow" + }, + { + "type": "cost", + "icon": "💰", + "text": "{{cost}}", + "color": "bright_magenta" + }, + { + "type": "duration", + "icon": "⏱️", + "text": "{{duration}}", + "color": "bright_white" + }, + { + "type": "lines", + "icon": "📝", + "text": "+{{linesAdded}}/-{{linesRemoved}}", + "color": "bright_cyan" + } + ] + } + } +} +``` + +## Custom Scripts + +You can create custom modules by executing scripts: + +```json +{ + "type": "script", + "icon": "🔧", + "scriptPath": "/path/to/script.js", + "options": { + "customOption": "value" + } +} +``` + +Script format (CommonJS): + +```javascript +// my-status-module.js +module.exports = function(variables, options) { + // Access variables like model, gitBranch, etc. + // Access options from configuration + return `Custom: ${variables.model}`; +}; + +// Or async +module.exports = async function(variables, options) { + const data = await fetchSomeData(); + return data; +}; +``` + +## Color Options + +### Standard Colors + +- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` +- `bright_black`, `bright_red`, `bright_green`, `bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white` + +### Background Colors + +Prefix with `bg_`: `bg_blue`, `bg_bright_red`, etc. + +### Hexadecimal Colors + +Use 24-bit TrueColor with hex codes: + +```json +{ + "color": "#FF5733", + "background": "bg_#1E90FF" +} +``` + +## Available Variables + +All variables are accessible in module text using `{{variableName}}`: + +| Variable | Description | Example | +|----------|-------------|---------| +| `{{workDirName}}` | Current directory name | `my-project` | +| `{{gitBranch}}` | Git branch name | `main` | +| `{{model}}` | Model name | `claude-3-5-sonnet-20241022` | +| `{{inputTokens}}` | Input tokens (formatted) | `12.3k` | +| `{{outputTokens}}` | Output tokens (formatted) | `5.2k` | +| `{{tokenSpeed}}` | Tokens per second | `45` | +| `{{isStreaming}}` | Streaming status | `streaming` or empty | +| `{{contextPercent}}` | Context usage percentage | `45` | +| `{{contextWindowSize}}` | Total context window | `200k` | +| `{{cost}}` | Total cost | `$0.15` | +| `{{duration}}` | Session duration | `2m34s` | +| `{{linesAdded}}` | Lines added | `150` | +| `{{linesRemoved}}` | Lines removed | `25` | +| `{{sessionId}}` | Session ID (first 8 chars) | `a1b2c3d4` | + +## Environment Variables + +Control behavior with environment variables: + +| Variable | Values | Description | +|----------|--------|-------------| +| `USE_SIMPLE_ICONS` | `true`/`false` | Force simple theme without icons | +| `NERD_FONT` | Any value | Auto-detect Nerd Font support | + +## Examples + +### Minimal Status Line + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "model", + "text": "{{model}}" + }, + { + "type": "usage", + "text": "↑{{inputTokens}} ↓{{outputTokens}}" + } + ] + } + } +} +``` + +Output: `claude-3-5-sonnet-20241022 ↑12.3k ↓5.2k` + +### Developer Productivity Focus + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "lines", + "icon": "📝", + "text": "+{{linesAdded}}/-{{linesRemoved}}", + "color": "bright_cyan" + }, + { + "type": "duration", + "icon": "⏱️", + "text": "{{duration}}", + "color": "bright_white" + } + ] + } + } +} +``` + +Output: ` feature/auth 📝 +150/-25 ⏱️ 2m34s` + +## Preset Integration + +Statusline themes can be included in presets. When you install a preset with statusline configuration, it will automatically apply when you activate that preset. + +See [Presets](/docs/server/advanced/presets) for more information. + +## Troubleshooting + +### Icons Not Displaying + +Set `USE_SIMPLE_ICONS=true` in your environment: + +```bash +export USE_SIMPLE_ICONS=true +``` + +### Colors Not Working + +Ensure your terminal supports TrueColor (24-bit color): + +```bash +export COLORTERM=truecolor +``` + +### Git Branch Not Showing + +Ensure you're in a Git repository and have the `git` command installed. + +## Related Commands + +- [ccr status](/docs/cli/commands/status) - Check server status +- [ccr preset](/docs/cli/commands/preset) - Manage presets with statusline themes diff --git a/docs/docs/cli/installation.md b/docs/docs/cli/installation.md index bf1100f..8e631ed 100644 --- a/docs/docs/cli/installation.md +++ b/docs/docs/cli/installation.md @@ -15,19 +15,19 @@ Install Claude Code Router globally using your preferred package manager. ## Install via npm ```bash -npm install -g @musistudio/claude-code-router-cli +npm install -g @musistudio/claude-code-router ``` ## Install via pnpm ```bash -pnpm add -g @musistudio/claude-code-router-cli +pnpm add -g @musistudio/claude-code-router ``` ## Install via Yarn ```bash -yarn global add @musistudio/claude-code-router-cli +yarn global add @musistudio/claude-code-router ``` ## Verify Installation diff --git a/docs/docs/cli/intro.md b/docs/docs/cli/intro.md index 87d83eb..78e41a1 100644 --- a/docs/docs/cli/intro.md +++ b/docs/docs/cli/intro.md @@ -16,18 +16,12 @@ Claude Code Router CLI (`ccr`) is a command-line tool for managing and controlli - **Code Execution**: Directly execute `claude` command - **Environment Integration**: Output environment variables for shell integration - **Web UI**: Open Web management interface -- **Status Bar**: Integration into editor status bar +- **Status Bar**: Display customizable session status with `ccr statusline` ## Installation ```bash -npm install -g @musistudio/claude-code-router-cli -``` - -Or using project alias: - -```bash -npm install -g claude-code-router +npm install -g @musistudio/claude-code-router ``` ## Basic Usage @@ -50,29 +44,6 @@ ccr status ccr stop ``` -### View Models - -```bash -ccr model -``` - -## Integration with Claude Code - -`ccr` integrates seamlessly with Claude Code to route requests to your chosen LLM provider. - -### Method 1: Set API Address - -```bash -export ANTHROPIC_BASE_URL="http://localhost:3456/v1" -export ANTHROPIC_API_KEY="your-api-key" -``` - -### Method 2: Use activate Command - -```bash -eval "$(ccr activate)" -``` - ## Configuration File `ccr` uses the same configuration file as Server: `~/.claude-code-router/config.json` @@ -84,4 +55,5 @@ Configure once, and both CLI and Server will use it. - [Installation Guide](/docs/cli/installation) - Detailed installation instructions - [Quick Start](/docs/cli/quick-start) - Get started in 5 minutes - [Command Reference](/docs/category/cli-commands) - Complete command list +- [Status Line](/docs/cli/commands/statusline) - Customize your status bar - [Configuration Guide](/docs/category/cli-config) - Configuration file details diff --git a/docs/docs/cli/quick-start.md b/docs/docs/cli/quick-start.md index 9458035..76ea0a0 100644 --- a/docs/docs/cli/quick-start.md +++ b/docs/docs/cli/quick-start.md @@ -14,66 +14,16 @@ ccr start The router will start on `http://localhost:8080` by default. -## 2. Configure Environment Variables - -Set the following environment variables in your shell: - -```bash -export ANTHROPIC_API_URL="http://localhost:8080/v1" -export ANTHROPIC_API_KEY="your-provider-api-key" -``` - -Or use the `ccr activate` command to get the environment variables: - -```bash -eval "$(ccr activate)" -``` - -## 3. Use Claude Code +## 2. Use Claude Code Now you can use Claude Code normally: ```bash -claude code +ccr code ``` Your requests will be routed through Claude Code Router to your configured provider. -## 4. Configure Providers (Optional) - -To configure multiple providers or custom routing, use: - -```bash -ccr model -``` - -This will open an interactive menu to select and configure models. - -Or edit the configuration file directly: - -```bash -# Open config in your default editor -ccr config edit -``` - -Example configuration (`~/.claude-code-router/config.json`): - -```json -{ - "Providers": [ - { - "NAME": "deepseek", - "HOST": "https://api.deepseek.com", - "APIKEY": "your-deepseek-api-key", - "MODELS": ["deepseek-chat", "deepseek-coder"] - } - ], - "Router": { - "default": "deepseek,deepseek-chat" - } -} -``` - ## What's Next? - [Basic Configuration](/docs/config/basic) - Learn about configuration options diff --git a/docs/docs/server/advanced/agents.md b/docs/docs/server/advanced/agents.md deleted file mode 100644 index 0746105..0000000 --- a/docs/docs/server/advanced/agents.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Agents - -Extend functionality with the agent system. - -## What are Agents? - -Agents are pluggable feature modules that can: -- Detect whether to handle a request -- Modify requests -- Provide custom tools - -## Built-in Agents - -### Image Agent - -Handles image-related tasks by detecting image URLs or file paths in requests. - -## Agent Configuration - -Agents are configured in the server configuration and automatically loaded. - -## Agent Tool Call Flow - -1. Detect and mark agents in `preHandler` hook -2. Add agent tools to the request -3. Intercept tool call events in `onSend` hook -4. Execute agent tool and initiate new LLM request -5. Stream results back - -## Creating Custom Agents - -Coming soon! Custom agent support is under development. - -## Next Steps - -- [Presets](/docs/advanced/presets) - Use predefined configurations diff --git a/docs/docs/server/advanced/presets.md b/docs/docs/server/advanced/presets.md index ce7cf77..5e448be 100644 --- a/docs/docs/server/advanced/presets.md +++ b/docs/docs/server/advanced/presets.md @@ -10,16 +10,129 @@ Use predefined configurations for quick setup. Presets are pre-configured settings that include provider configurations, routing rules, and transformers optimized for specific use cases. -## Dynamic Configuration System (v2.0+) +## Using Presets -CCR 2.0 introduces a powerful dynamic configuration system that supports: +### CLI Mode (Command Line) + +CLI mode is suitable for developers who prefer command-line operations. + +#### Installing Presets + +**Install from local directory:** + +```bash +ccr preset install /path/to/preset-directory +``` + +**Reconfigure an installed preset:** + +```bash +ccr preset install my-preset +``` + +:::note Note +CLI mode **does not support** installing presets directly from URLs. To install from GitHub, clone to local first or use Web UI. +::: + +#### Using Presets + +After installing a preset, you can use the preset name to start Claude Code: + +```bash +# Start with a specific preset +ccr my-preset "your prompt" + +# Background task with preset +ccr my-preset --background "your prompt" +``` + +The preset will: +- Automatically load pre-configured Providers +- Apply preset routing rules +- Use transformers configured in the preset + +#### List All Presets + +```bash +ccr preset list +``` + +This will display all installed presets with their names, versions, and descriptions. + +#### View Preset Information + +```bash +ccr preset info my-preset +``` + +#### Delete Preset + +```bash +ccr preset delete my-preset +``` + +### Web UI Mode + +Web UI provides a more friendly visual interface with additional installation methods. + +#### Access Web UI + +```bash +ccr ui +``` + +Then open `http://localhost:3000` in your browser. + +#### Install from GitHub Repository + +1. Click the "Preset Market" button +2. Select the preset you want to install from the list +3. Click the "Install" button + +Or manually enter a GitHub repository URL: + +``` +Format: https://github.com/username/repo +Example: https://github.com/example/ccr-presets +``` + +#### Reconfigure Preset + +1. Click the "View Details" icon next to the preset +2. Modify configuration items in the detail page +3. Click "Apply" to save configuration + +#### Manage Presets + +- **View**: Click the info icon on the right side of the preset +- **Delete**: Click the delete icon on the right side of the preset + +## Creating Custom Presets + +### Preset Directory Structure + +Presets are stored as directories with the following structure: + +``` +~/.claude-code-router/presets// +├── manifest.json # Required: Preset configuration file +├── transformers/ # Optional: Custom transformers +│ └── custom-transformer.js +├── scripts/ # Optional: Custom scripts +│ └── status.js +└── README.md # Optional: Documentation +``` + +### Dynamic Configuration System + +CCR introduces a powerful dynamic configuration system that supports: - **Multiple Input Types**: Selectors, multi-select, confirm boxes, text input, number input, etc. - **Conditional Logic**: Dynamically show/hide configuration fields based on user input - **Variable References**: Configuration fields can reference each other - **Dynamic Options**: Option lists can be dynamically generated from preset configuration or user input -### Schema Field Types +#### Schema Field Types | Type | Description | Example | |------|-------------|---------| @@ -31,7 +144,7 @@ CCR 2.0 introduces a powerful dynamic configuration system that supports: | `confirm` | Confirmation box | Use proxy | | `editor` | Multi-line text editor | Custom config | -### Condition Operators +#### Condition Operators | Operator | Description | Example | |----------|-------------|---------| @@ -42,9 +155,9 @@ CCR 2.0 introduces a powerful dynamic configuration system that supports: | `exists` | Field exists | `{"field": "apiKey", "operator": "exists"}` | | `gt/lt/gte/lte` | Greater/less than (or equal) | For number comparisons | -### Dynamic Options Types +#### Dynamic Options Types -#### static - Static Options +##### static - Static Options ```json "options": { "type": "static", @@ -55,7 +168,7 @@ CCR 2.0 introduces a powerful dynamic configuration system that supports: } ``` -#### providers - Extract from Providers Configuration +##### providers - Extract from Providers Configuration ```json "options": { "type": "providers" @@ -63,7 +176,7 @@ CCR 2.0 introduces a powerful dynamic configuration system that supports: ``` Automatically extracts names from the `Providers` array as options. -#### models - Extract from Specified Provider's Models +##### models - Extract from Specified Provider's Models ```json "options": { "type": "models", @@ -72,7 +185,7 @@ Automatically extracts names from the `Providers` array as options. ``` Dynamically displays models based on the user-selected provider. -### Template Variables +#### Template Variables Use `{{variableName}}` syntax to reference user input in the template: @@ -87,7 +200,7 @@ Use `{{variableName}}` syntax to reference user input in the template: } ``` -### Configuration Mappings +#### Configuration Mappings For complex configuration needs, use `configMappings` to precisely control value placement: @@ -109,7 +222,7 @@ For complex configuration needs, use `configMappings` to precisely control value ] ``` -### Complete Example +#### Complete Example ```json { @@ -220,123 +333,317 @@ For complex configuration needs, use `configMappings` to precisely control value } ``` -## Available Presets +### manifest.json Complete Field Reference -### Development +`manifest.json` is the core configuration file of a preset, using JSON5 format (comments supported). -Optimized for software development tasks: -- Fast response times -- Good for code generation -- Cost-effective +#### 1. Metadata Fields -### Research +These fields describe basic information about the preset: -Optimized for research and analysis: -- Long context support -- High-quality responses -- More capable models +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | ✓ | Preset name (unique identifier) | +| `version` | string | ✓ | Version number (follows semver) | +| `description` | string | - | Preset description | +| `author` | string | - | Author information | +| `homepage` | string | - | Project homepage URL | +| `repository` | string | - | Source repository URL | +| `license` | string | - | License type | +| `keywords` | string[] | - | Keyword tags | +| `ccrVersion` | string | - | Compatible CCR version | +| `source` | string | - | Preset source URL | +| `sourceType` | string | - | Source type (`local`/`gist`/`registry`) | +| `checksum` | string | - | Content checksum (SHA256) | -### Balanced +Example: -A balance between speed and quality: -- Good general-purpose performance -- Reasonable costs -- Wide model support - -## Using Presets - -Use the CLI to apply a preset: - -```bash -ccr preset apply development -``` - -List available presets: - -```bash -ccr preset list -``` - -## Creating Custom Presets - -### Using the Dynamic Configuration System - -Create a preset file with `schema` and `template`: - -```bash -# Create preset directory -mkdir -p ~/.claude-code-router/presets/my-preset - -# Create manifest.json -cat > ~/.claude-code-router/presets/my-preset/manifest.json << 'EOF' +```json { "name": "my-preset", "version": "1.0.0", "description": "My custom preset", + "author": "Your Name", + "homepage": "https://github.com/yourname/ccr-presets", + "repository": "https://github.com/yourname/ccr-presets.git", + "license": "MIT", + "keywords": ["openai", "production"], + "ccrVersion": "2.0.0" +} +``` + +#### 2. Configuration Fields + +These fields are directly merged into CCR's configuration. All fields supported in `config.json` can be used here: + +| Field | Type | Description | +|-------|------|-------------| +| `Providers` | array | Provider configuration array | +| `Router` | object | Routing configuration | +| `transformers` | array | Transformer configuration | +| `StatusLine` | object | Status bar configuration | + +Example: + +```json +{ + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + "PORT": 8080 +} +``` + +#### 3. Dynamic Configuration System Fields + +These fields are used to create interactive configuration templates: + +| Field | Type | Description | +|-------|------|-------------| +| `schema` | array | Configuration input form definition | +| `template` | object | Configuration template (with variable references) | +| `configMappings` | array | Configuration mapping rules | +| `userValues` | object | User-filled values (used at runtime) | +| `requiredInputs` | array | Required input list (auto-generated) | + +**Schema Field Types:** + +| Type | Description | Use Case | +|------|-------------|----------| +| `password` | Password input (hidden) | API Key | +| `input` | Single-line text input | URL | +| `number` | Number input | Port number | +| `select` | Single-select dropdown | Select Provider | +| `multiselect` | Multi-select | Enable features | +| `confirm` | Confirmation box | Enable/disable | +| `editor` | Multi-line text editor | Custom config | + +Dynamic configuration example: + +```json +{ "schema": [ { "id": "apiKey", "type": "password", "label": "API Key", + "prompt": "Enter your API Key", "required": true + }, + { + "id": "provider", + "type": "select", + "label": "Provider", + "options": { + "type": "static", + "options": [ + {"label": "OpenAI", "value": "openai"}, + {"label": "DeepSeek", "value": "deepseek"} + ] + }, + "defaultValue": "openai" } ], "template": { "Providers": [ { - "name": "my-provider", - "api_key": "{{apiKey}}" + "name": "#{provider}", + "api_key": "#{apiKey}" } ] } } +``` + +### Creating Preset Examples + +#### Example 1: Simple Preset (No Dynamic Configuration) + +```bash +# Create preset directory +mkdir -p ~/.claude-code-router/presets/simple-openai + +# Create manifest.json +cat > ~/.claude-code-router/presets/simple-openai/manifest.json << 'EOF' +{ + "name": "simple-openai", + "version": "1.0.0", + "description": "Simple OpenAI configuration", + "author": "Your Name", + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + + "requiredInputs": [ + { + "id": "Providers[0].api_key", + "prompt": "Enter OpenAI API Key", + "placeholder": "OPENAI_API_KEY" + } + ] +} EOF -# Apply preset (will prompt for API Key) -ccr my-preset +# Configure preset (input API Key) +ccr preset install simple-openai + +# Use preset +ccr simple-openai "your prompt" ``` -You can also save and reload your current configuration: +#### Example 2: Advanced Preset (Dynamic Configuration) ```bash -# Save current configuration as a preset -ccr preset save my-preset +# Create preset directory +mkdir -p ~/.claude-code-router/presets/advanced-config -# Load a saved preset -ccr preset apply my-preset +# Create manifest.json +cat > ~/.claude-code-router/presets/advanced-config/manifest.json << 'EOF' +{ + "name": "advanced-config", + "version": "1.0.0", + "description": "Advanced configuration with multi-provider support", + "author": "Your Name", + "keywords": ["openai", "deepseek", "multi-provider"], + + "schema": [ + { + "id": "provider", + "type": "select", + "label": "Select Provider", + "prompt": "Choose your primary LLM provider", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "Use OpenAI's GPT models" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "Use DeepSeek's cost-effective models" + } + ] + }, + "defaultValue": "openai", + "required": true + }, + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "Enter your API Key", + "placeholder": "sk-...", + "required": true + }, + { + "id": "enableProxy", + "type": "confirm", + "label": "Enable Proxy", + "prompt": "Access API through a proxy?", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "Proxy URL", + "prompt": "Enter proxy server address", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ], + + "template": { + "Providers": [ + { + "name": "#{provider}", + "api_base_url": "#{provider === 'openai' ? 'https://api.openai.com/v1' : 'https://api.deepseek.com'}", + "api_key": "#{apiKey}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + "Router": { + "default": "#{provider}/gpt-4o", + "background": "#{provider}/gpt-4o-mini" + } + }, + + "configMappings": [ + { + "target": "PROXY_URL", + "value": "#{proxyUrl}", + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ] +} +EOF + +# Configure preset (will prompt for input) +ccr preset install advanced-config + +# Use preset +ccr advanced-config "your prompt" ``` -## Preset Management +### Export Current Configuration as Preset -### List All Presets +If you have already configured CCR, you can export the current configuration: ```bash -ccr preset list +# Export current configuration +ccr preset export my-exported-preset ``` -Output example: +Export will automatically: +- Identify sensitive fields (like `api_key`) and replace with environment variable placeholders +- Generate `schema` for collecting user input +- Generate `template` and `configMappings` -``` -Available presets: - development - Development optimized configuration - research - Research optimized configuration - balanced - Balanced configuration - my-preset - Custom preset -``` - -### Apply a Preset +Optional flags: ```bash -ccr preset apply +ccr preset export my-exported-preset \ + --description "Exported configuration" \ + --author "Your Name" \ + --tags "production,openai" ``` -The server will automatically restart to load the new configuration. - -### Delete a Preset - -```bash -ccr preset delete -``` +:::tip Share Presets +Exported preset directories can be directly shared with others. Recipients can: +- **CLI Mode**: Place directory in `~/.claude-code-router/presets/`, then run `ccr preset install preset-name` +- **Web UI Mode**: Upload directory to GitHub, then install via repository URL +::: ## Preset File Location @@ -348,21 +655,6 @@ Presets are stored in: Each preset is a directory containing a `manifest.json` file. -## Exporting and Importing Presets - -### Export Current Configuration - -```bash -ccr config show > my-config.json -``` - -### Import Configuration - -```bash -ccr config edit -# Then paste the imported configuration -``` - ## Best Practices 1. **Use Dynamic Configuration**: Use the schema system for configuration items that require user input diff --git a/docs/docs/server/api/logs-api.md b/docs/docs/server/api/logs-api.md index 5ebffed..d5bfcde 100644 --- a/docs/docs/server/api/logs-api.md +++ b/docs/docs/server/api/logs-api.md @@ -168,27 +168,3 @@ Server logs use rotating-file-stream for automatic rotation: - **maxFiles**: 3 - Keep last 3 log files - **interval**: 1d - Rotate daily - **maxSize**: 50M - Maximum 50MB per file - -## Log Analysis - -### Analyze Logs with jq - -```bash -# View all error logs -curl "http://localhost:3456/api/logs" \ - -H "x-api-key: your-api-key" | \ - jq -r '.[] | fromjson | select(.level >= 40)' - -# Count requests -curl "http://localhost:3456/api/logs" \ - -H "x-api-key: your-api-key" | \ - jq -r '.[] | fromjson | .req.method' | \ - sort | uniq -c -``` - -### Real-time Log Monitoring - -```bash -# Get latest logs in real-time via API -watch -n 5 'curl -s "http://localhost:3456/api/logs" -H "x-api-key: your-api-key" | jq -r ".[-10:]"' -``` diff --git a/docs/docs/server/api/overview.md b/docs/docs/server/api/overview.md index 5875c56..42aad26 100644 --- a/docs/docs/server/api/overview.md +++ b/docs/docs/server/api/overview.md @@ -54,27 +54,6 @@ curl -H "x-api-key: your-api-key" http://localhost:3456/api/config | `/ui` | GET | Web management interface | | `/ui/` | GET | Web management interface (redirect) | -## Error Responses - -All APIs return a unified error format when errors occur: - -```json -{ - "error": { - "type": "invalid_request_error", - "message": "Error description" - } -} -``` - -Common HTTP status codes: - -- `200` - Success -- `400` - Invalid request parameters -- `401` - Unauthorized (invalid API Key) -- `404` - Resource not found -- `500` - Internal server error - ## Authentication ### API Key Authentication @@ -88,16 +67,6 @@ curl -X POST http://localhost:3456/v1/messages \ -d '...' ``` -### No Authentication Mode - -When no Providers are configured, the server listens on `0.0.0.0` without authentication: - -```json5 -{ - "Providers": [] -} -``` - ## Streaming Responses The Messages API supports streaming responses (Server-Sent Events): @@ -121,13 +90,3 @@ data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"} event: message_stop data: {"type":"message_stop"} ``` - -## Rate Limiting - -The server itself does not implement rate limiting. It's recommended to configure it through a reverse proxy (e.g., Nginx). - -## Version Management - -Current API version: `v1` - -All `/v1/*` endpoints maintain backward compatibility. diff --git a/docs/i18n/en/code.json b/docs/i18n/en/code.json new file mode 100644 index 0000000..ecd5d5f --- /dev/null +++ b/docs/i18n/en/code.json @@ -0,0 +1,329 @@ +{ + "theme.ErrorPageContent.title": { + "message": "This page crashed.", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "Scroll back to top", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "Archive", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "Archive", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "Blog list page navigation", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "Newer entries", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "Older entries", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "Blog post page navigation", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "Newer post", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "Older post", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.tags.tagsPageLink": { + "message": "View all tags", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel.mode.system": { + "message": "system mode", + "description": "The name for the system color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "light mode", + "description": "The name for the light color mode" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "dark mode", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel": { + "message": "Switch between dark and light mode (currently {mode})", + "description": "The ARIA label for the color mode toggle" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "Breadcrumbs", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription.plurals": { + "message": "1 item|{count} items", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "Docs pages", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "Previous", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "Next", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "One doc tagged|{count} docs tagged", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged} with \"{tagName}\"", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versionBadge.label": { + "message": "Version: {versionLabel}" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "This is unreleased documentation for {siteTitle} {versionLabel} version.", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "For up-to-date documentation, see the {latestVersionLink} ({versionLabel}).", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "latest version", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "Edit this page", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "Direct link to {heading}", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": " on {date}", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": " by {user}", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "Last updated{atDate}{byUser}", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.NotFound.title": { + "message": "Page Not Found", + "description": "The title of the 404 page" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "Versions", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.tags.tagsListLabel": { + "message": "Tags:", + "description": "The label alongside a tag list" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "Close", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.admonition.caution": { + "message": "caution", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "danger", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "info", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "note", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "tip", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "warning", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "Blog recent posts navigation", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "Expand sidebar category '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "Collapse sidebar category '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.IconExternalLink.ariaLabel": { + "message": "(opens in new tab)", + "description": "The ARIA label for the external link icon" + }, + "theme.NavBar.navAriaLabel": { + "message": "Main", + "description": "The ARIA label for the main navigation" + }, + "theme.NotFound.p1": { + "message": "We could not find what you were looking for.", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "Please contact the owner of the site that linked you to the original URL and let them know their link is broken.", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "Languages", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "On this page", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "Read more", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "Read more about {title}", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "One min read|{readingTime} min read", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.CodeBlock.copy": { + "message": "Copy", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.copied": { + "message": "Copied", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "Copy code to clipboard", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "Toggle word wrap", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.docs.breadcrumbs.home": { + "message": "Home page", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "Docs sidebar", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "Collapse sidebar", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "Collapse sidebar", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "Close navigation bar", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← Back to main menu", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "Toggle navigation bar", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.navbar.mobileDropdown.collapseButton.expandAriaLabel": { + "message": "Expand the dropdown", + "description": "The ARIA label of the button to expand the mobile dropdown navbar item" + }, + "theme.navbar.mobileDropdown.collapseButton.collapseAriaLabel": { + "message": "Collapse the dropdown", + "description": "The ARIA label of the button to collapse the mobile dropdown navbar item" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "Expand sidebar", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "Expand sidebar", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.blog.post.plurals": { + "message": "One post|{count} posts", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} tagged with \"{tagName}\"", + "description": "The title of the page for a blog tag" + }, + "theme.blog.author.pageTitle": { + "message": "{authorName} - {nPosts}", + "description": "The title of the page for a blog author" + }, + "theme.blog.authorsList.pageTitle": { + "message": "Authors", + "description": "The title of the authors page" + }, + "theme.blog.authorsList.viewAll": { + "message": "View all authors", + "description": "The label of the link targeting the blog authors page" + }, + "theme.blog.author.noPosts": { + "message": "This author has not written any posts yet.", + "description": "The text for authors with 0 blog post" + }, + "theme.contentVisibility.unlistedBanner.title": { + "message": "Unlisted page", + "description": "The unlisted content banner title" + }, + "theme.contentVisibility.unlistedBanner.message": { + "message": "This page is unlisted. Search engines will not index it, and only users having a direct link can access it.", + "description": "The unlisted content banner message" + }, + "theme.contentVisibility.draftBanner.title": { + "message": "Draft page", + "description": "The draft content banner title" + }, + "theme.contentVisibility.draftBanner.message": { + "message": "This page is a draft. It will only be visible in dev and be excluded from the production build.", + "description": "The draft content banner message" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "Try again", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "Skip to main content", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "Tags", + "description": "The title of the tag list page" + } +} diff --git a/docs/i18n/en/docusaurus-plugin-content-blog/options.json b/docs/i18n/en/docusaurus-plugin-content-blog/options.json new file mode 100644 index 0000000..9239ff7 --- /dev/null +++ b/docs/i18n/en/docusaurus-plugin-content-blog/options.json @@ -0,0 +1,14 @@ +{ + "title": { + "message": "Blog", + "description": "The title for the blog used in SEO" + }, + "description": { + "message": "Blog", + "description": "The description for the blog used in SEO" + }, + "sidebar.title": { + "message": "Recent posts", + "description": "The label for the left sidebar" + } +} diff --git a/docs/i18n/en/docusaurus-plugin-content-docs/current.json b/docs/i18n/en/docusaurus-plugin-content-docs/current.json new file mode 100644 index 0000000..919a535 --- /dev/null +++ b/docs/i18n/en/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,90 @@ +{ + "version.label": { + "message": "Next", + "description": "The label for version current" + }, + "sidebar.tutorialSidebar.category.Server": { + "message": "Server", + "description": "The label for category 'Server' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Server.link.generated-index.title": { + "message": "Claude Code Router Server", + "description": "The generated-index page title for category 'Server' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Server.link.generated-index.description": { + "message": "Deploy and manage Claude Code Router server", + "description": "The generated-index page description for category 'Server' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.API Reference": { + "message": "API Reference", + "description": "The label for category 'API Reference' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.API Reference.link.generated-index.title": { + "message": "API Reference", + "description": "The generated-index page title for category 'API Reference' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.API Reference.link.generated-index.description": { + "message": "Server API documentation", + "description": "The generated-index page description for category 'API Reference' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.server-configuration-category": { + "message": "Configuration", + "description": "The label for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.server-configuration-category.link.generated-index.title": { + "message": "Server Configuration", + "description": "The generated-index page title for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.server-configuration-category.link.generated-index.description": { + "message": "Server configuration guide", + "description": "The generated-index page description for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Advanced": { + "message": "Advanced", + "description": "The label for category 'Advanced' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Advanced.link.generated-index.title": { + "message": "Advanced Topics", + "description": "The generated-index page title for category 'Advanced' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Advanced.link.generated-index.description": { + "message": "Advanced features and customization", + "description": "The generated-index page description for category 'Advanced' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.CLI": { + "message": "CLI", + "description": "The label for category 'CLI' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.CLI.link.generated-index.title": { + "message": "Claude Code Router CLI", + "description": "The generated-index page title for category 'CLI' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.CLI.link.generated-index.description": { + "message": "Command-line tool usage guide", + "description": "The generated-index page description for category 'CLI' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Commands": { + "message": "Commands", + "description": "The label for category 'Commands' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Commands.link.generated-index.title": { + "message": "CLI Commands", + "description": "The generated-index page title for category 'Commands' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Commands.link.generated-index.description": { + "message": "Complete command reference", + "description": "The generated-index page description for category 'Commands' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.cli-configuration-category": { + "message": "Configuration", + "description": "The label for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.cli-configuration-category.link.generated-index.title": { + "message": "CLI Configuration", + "description": "The generated-index page title for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.cli-configuration-category.link.generated-index.description": { + "message": "CLI configuration guide", + "description": "The generated-index page description for category 'Configuration' in sidebar 'tutorialSidebar'" + } +} diff --git a/docs/i18n/en/docusaurus-theme-classic/footer.json b/docs/i18n/en/docusaurus-theme-classic/footer.json new file mode 100644 index 0000000..41fbf1e --- /dev/null +++ b/docs/i18n/en/docusaurus-theme-classic/footer.json @@ -0,0 +1,30 @@ +{ + "link.title.Docs": { + "message": "Docs", + "description": "The title of the footer links column with title=Docs in the footer" + }, + "link.title.Community": { + "message": "Community", + "description": "The title of the footer links column with title=Community in the footer" + }, + "link.title.More": { + "message": "More", + "description": "The title of the footer links column with title=More in the footer" + }, + "link.item.label.Tutorial": { + "message": "Tutorial", + "description": "The label of footer link with label=Tutorial linking to /docs/intro" + }, + "link.item.label.GitHub": { + "message": "GitHub", + "description": "The label of footer link with label=GitHub linking to https://github.com/musistudio/claude-code-router" + }, + "link.item.label.Blog": { + "message": "Blog", + "description": "The label of footer link with label=Blog linking to /blog" + }, + "copyright": { + "message": "Copyright © 2026 Claude Code Router. Built with Docusaurus.", + "description": "The footer copyright" + } +} diff --git a/docs/i18n/en/docusaurus-theme-classic/navbar.json b/docs/i18n/en/docusaurus-theme-classic/navbar.json new file mode 100644 index 0000000..547f110 --- /dev/null +++ b/docs/i18n/en/docusaurus-theme-classic/navbar.json @@ -0,0 +1,22 @@ +{ + "title": { + "message": "Claude Code Router", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "Claude Code Router Logo", + "description": "The alt text of navbar logo" + }, + "item.label.Documentation": { + "message": "Documentation", + "description": "Navbar item with label Documentation" + }, + "item.label.Blog": { + "message": "Blog", + "description": "Navbar item with label Blog" + }, + "item.label.GitHub": { + "message": "GitHub", + "description": "Navbar item with label GitHub" + } +} diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/custom-router.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/custom-router.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/custom-router.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/custom-router.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/preset-format.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/preset-format.md similarity index 98% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/preset-format.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/preset-format.md index e34304f..6b6a67e 100644 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/preset-format.md +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/preset-format.md @@ -1036,6 +1036,7 @@ ccr preset export my-preset ``` 可选项： + ```bash ccr preset export my-preset \ --description "我的预设" \ @@ -1043,16 +1044,29 @@ ccr preset export my-preset \ --tags "openai,production" ``` -### 导入预设 +### 安装预设 + +**CLI 方式：** ```bash # 从本地目录安装 ccr preset install /path/to/preset -# 从预设名称重新配置（已安装的） +# 重新配置已安装的预设 ccr preset install my-preset ``` +:::note 注意 +CLI 方式**不支持**从 URL 安装。如需从 GitHub 安装，请使用 Web UI 或先克隆到本地。 +::: + +**Web UI 方式：** + +1. 访问 Web UI：`ccr ui` +2. 点击"预设商城"按钮 +3. 选择预设或输入 GitHub 仓库 URL +4. 点击安装 + ### 管理预设 ```bash diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/presets.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/presets.md new file mode 100644 index 0000000..4966dcd --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/advanced/presets.md @@ -0,0 +1,673 @@ +--- +id: advanced/presets +title: 预设配置 +sidebar_position: 3 +--- + +# 预设配置 + +使用预定义配置进行快速设置。 + +## 什么是预设？ + +预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。 + +## 使用预设 + +### CLI 方式（命令行） + +CLI 方式适合开发者通过命令行快速操作。 + +#### 安装预设 + +**从本地目录安装：** + +```bash +ccr preset install /path/to/preset-directory +``` + +**重新配置已安装的预设：** + +```bash +ccr preset install my-preset +``` + +:::note 注意 +CLI 方式**不支持**从 URL 直接安装预设。如需从 GitHub 安装，请先克隆到本地或使用 Web UI。 +::: + +#### 使用预设 + +安装预设后，可以使用预设名称启动 Claude Code： + +```bash +# 使用指定预设启动 +ccr my-preset "your prompt" + +# 后台任务使用预设 +ccr my-preset --background "your prompt" +``` + +预设会： +- 自动加载预配置的 Provider +- 应用预设的路由规则 +- 使用预设中配置的 transformer + +#### 列出所有预设 + +```bash +ccr preset list +``` + +此命令将显示所有已安装的预设及其名称、版本和描述。 + +#### 查看预设信息 + +```bash +ccr preset info my-preset +``` + +#### 删除预设 + +```bash +ccr preset delete my-preset +``` + +### Web UI 方式 + +Web UI 提供更友好的可视化界面，支持更多安装方式。 + +#### 访问 Web UI + +```bash +ccr ui +``` + +然后在浏览器中打开 `http://localhost:3000` + +#### 从 GitHub 仓库安装 + +1. 点击"预设商城"按钮 +2. 在预设列表中选择要安装的预设 +3. 点击"安装"按钮 + +或手动输入 GitHub 仓库地址： + +``` +格式：https://github.com/username/repo +示例：https://github.com/example/ccr-presets +``` + +#### 重新配置预设 + +1. 在预设列表中点击"查看详情"按钮 +2. 在详情页面中修改配置项 +3. 点击"应用"保存配置 + +#### 管理预设 + +- **查看**：点击预设右侧的信息图标 +- **删除**：点击预设右侧的删除图标 + +## 创建自定义预设 + +### 预设目录结构 + +预设以目录形式存储，每个预设包含以下结构： + +``` +~/.claude-code-router/presets// +├── manifest.json # 必填：预设配置文件 +├── transformers/ # 可选：自定义转换器 +│ └── custom-transformer.js +├── scripts/ # 可选：自定义脚本 +│ └── status.js +└── README.md # 可选：说明文档 +``` + +### 动态配置系统 + +CCR 引入了强大的动态配置系统，支持： + +- **多种输入类型**：选择器、多选、确认框、文本输入、数字输入等 +- **条件逻辑**：根据用户输入动态显示/隐藏配置项 +- **变量引用**：配置项之间可以互相引用 +- **动态选项**：选项列表可以从预设配置或用户输入中动态生成 + +#### Schema 字段类型 + +| 类型 | 说明 | 示例 | +|------|------|------| +| `password` | 密码输入（隐藏显示） | API Key | +| `input` | 单行文本输入 | Base URL | +| `number` | 数字输入 | 最大Token数 | +| `select` | 单选下拉框 | 选择Provider | +| `multiselect` | 多选框 | 启用功能 | +| `confirm` | 确认框 | 是否使用代理 | +| `editor` | 多行文本编辑器 | 自定义配置 | + +#### 条件运算符 + +| 运算符 | 说明 | 示例 | +|--------|------|------| +| `eq` | 等于 | `{"field": "provider", "operator": "eq", "value": "openai"}` | +| `ne` | 不等于 | `{"field": "advanced", "operator": "ne", "value": true}` | +| `in` | 包含于 | `{"field": "feature", "operator": "in", "value": ["a", "b"]}` | +| `nin` | 不包含于 | `{"field": "type", "operator": "nin", "value": ["x", "y"]}` | +| `exists` | 字段存在 | `{"field": "apiKey", "operator": "exists"}` | +| `gt/lt/gte/lte` | 大于/小于/大于等于/小于等于 | 用于数字比较 | + +#### 动态选项类型 + +##### static - 静态选项 +```json +"options": { + "type": "static", + "options": [ + {"label": "选项1", "value": "value1"}, + {"label": "选项2", "value": "value2"} + ] +} +``` + +##### providers - 从 Providers 配置提取 +```json +"options": { + "type": "providers" +} +``` +自动从 `Providers` 数组中提取 name 作为选项。 + +##### models - 从指定 Provider 的 models 提取 +```json +"options": { + "type": "models", + "providerField": "{{selectedProvider}}" +} +``` +根据用户选择的 Provider，动态显示该 Provider 的 models。 + +#### 模板变量 + +使用 `{{变量名}}` 语法在 template 中引用用户输入： + +```json +"template": { + "Providers": [ + { + "name": "{{providerName}}", + "api_key": "{{apiKey}}" + } + ] +} +``` + +#### 配置映射 + +对于复杂的配置需求，使用 `configMappings` 精确控制值的位置： + +```json +"configMappings": [ + { + "target": "Providers[0].api_key", + "value": "{{apiKey}}" + }, + { + "target": "PROXY_URL", + "value": "{{proxyUrl}}", + "when": { + "field": "useProxy", + "operator": "eq", + "value": true + } + } +] +``` + +#### 完整示例 + +```json +{ + "name": "multi-provider-example", + "version": "1.0.0", + "description": "多Provider配置示例 - 支持OpenAI和DeepSeek切换", + "author": "CCR Team", + "keywords": ["openai", "deepseek", "multi-provider"], + "ccrVersion": "2.0.0", + "schema": [ + { + "id": "primaryProvider", + "type": "select", + "label": "主要Provider", + "prompt": "选择您主要使用的LLM提供商", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "使用OpenAI的GPT模型" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "使用DeepSeek的高性价比模型" + } + ] + }, + "required": true, + "defaultValue": "openai" + }, + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的API Key", + "placeholder": "sk-...", + "required": true + }, + { + "id": "defaultModel", + "type": "select", + "label": "默认模型", + "prompt": "选择默认使用的模型", + "options": { + "type": "static", + "options": [ + {"label": "GPT-4o", "value": "gpt-4o"}, + {"label": "GPT-4o-mini", "value": "gpt-4o-mini"} + ] + }, + "required": true, + "defaultValue": "gpt-4o", + "when": { + "field": "primaryProvider", + "operator": "eq", + "value": "openai" + } + }, + { + "id": "enableProxy", + "type": "confirm", + "label": "启用代理", + "prompt": "是否通过代理访问API？", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "prompt": "输入代理服务器地址", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ], + "template": { + "Providers": [ + { + "name": "{{primaryProvider}}", + "api_base_url": "https://api.openai.com/v1", + "api_key": "{{apiKey}}", + "models": ["{{defaultModel}}"] + } + ], + "Router": { + "default": "{{primaryProvider}}/{{defaultModel}}" + }, + "PROXY_URL": "{{proxyUrl}}" + }, + "configMappings": [ + { + "target": "PROXY_URL", + "value": "{{proxyUrl}}", + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ] +} +``` + +### manifest.json 完整字段说明 + +`manifest.json` 是预设的核心配置文件，使用 JSON5 格式（支持注释）。 + +#### 1. 元数据字段（Metadata） + +这些字段用于描述预设的基本信息： + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | string | ✓ | 预设名称（唯一标识符） | +| `version` | string | ✓ | 版本号（遵循 semver 规范） | +| `description` | string | - | 预设描述 | +| `author` | string | - | 作者信息 | +| `homepage` | string | - | 项目主页 URL | +| `repository` | string | - | 源代码仓库 URL | +| `license` | string | - | 许可证类型 | +| `keywords` | string[] | - | 关键词标签 | +| `ccrVersion` | string | - | 兼容的 CCR 版本 | +| `source` | string | - | 预设来源 URL | +| `sourceType` | string | - | 来源类型（`local`/`gist`/`registry`） | +| `checksum` | string | - | 内容校验和（SHA256） | + +示例： + +```json +{ + "name": "my-preset", + "version": "1.0.0", + "description": "我的自定义预设", + "author": "Your Name", + "homepage": "https://github.com/yourname/ccr-presets", + "repository": "https://github.com/yourname/ccr-presets.git", + "license": "MIT", + "keywords": ["openai", "production"], + "ccrVersion": "2.0.0" +} +``` + +#### 2. 配置字段（Configuration） + +这些字段会直接合并到 CCR 的配置中，所有 `config.json` 支持的字段都可以在这里使用： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `Providers` | array | Provider 配置数组 | +| `Router` | object | 路由配置 | +| `transformers` | array | 转换器配置 | +| `StatusLine` | object | 状态栏配置 | + +示例： + +```json +{ + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + "PORT": 8080 +} +``` + +#### 3. 动态配置系统字段 + +这些字段用于创建可交互的配置模板： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `schema` | array | 配置输入表单定义 | +| `template` | object | 配置模板（使用变量引用） | +| `configMappings` | array | 配置映射规则 | +| `userValues` | object | 用户填写的值（运行时使用） | +| `requiredInputs` | array | 必填输入项列表（自动生成） | + +**schema 字段类型：** + +| 类型 | 说明 | 使用场景 | +|------|------|----------| +| `password` | 密码输入（隐藏） | API Key | +| `input` | 单行文本输入 | URL | +| `number` | 数字输入 | 端口号 | +| `select` | 单选下拉框 | 选择 Provider | +| `multiselect` | 多选框 | 启用功能 | +| `confirm` | 确认框 | 是否启用 | +| `editor` | 多行文本编辑器 | 自定义配置 | + +动态配置示例： + +```json +{ + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的 API Key", + "required": true + }, + { + "id": "provider", + "type": "select", + "label": "Provider", + "options": { + "type": "static", + "options": [ + {"label": "OpenAI", "value": "openai"}, + {"label": "DeepSeek", "value": "deepseek"} + ] + }, + "defaultValue": "openai" + } + ], + "template": { + "Providers": [ + { + "name": "#{provider}", + "api_key": "#{apiKey}" + } + ] + } +} +``` + +### 创建预设示例 + +#### 示例 1：简单预设（无动态配置） + +```bash +# 创建预设目录 +mkdir -p ~/.claude-code-router/presets/simple-openai + +# 创建 manifest.json +cat > ~/.claude-code-router/presets/simple-openai/manifest.json << 'EOF' +{ + "name": "simple-openai", + "version": "1.0.0", + "description": "简单的 OpenAI 配置", + "author": "Your Name", + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + + "requiredInputs": [ + { + "id": "Providers[0].api_key", + "prompt": "Enter OpenAI API Key", + "placeholder": "OPENAI_API_KEY" + } + ] +} +EOF + +# 配置预设（输入 API Key） +ccr preset install simple-openai + +# 使用预设 +ccr simple-openai "your prompt" +``` + +#### 示例 2：高级预设（动态配置） + +```bash +# 创建预设目录 +mkdir -p ~/.claude-code-router/presets/advanced-config + +# 创建 manifest.json +cat > ~/.claude-code-router/presets/advanced-config/manifest.json << 'EOF' +{ + "name": "advanced-config", + "version": "1.0.0", + "description": "支持多 Provider 选择的高级配置", + "author": "Your Name", + "keywords": ["openai", "deepseek", "multi-provider"], + + "schema": [ + { + "id": "provider", + "type": "select", + "label": "选择 Provider", + "prompt": "选择您主要使用的 LLM 提供商", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "使用 OpenAI 的 GPT 模型" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "使用 DeepSeek 的高性价比模型" + } + ] + }, + "defaultValue": "openai", + "required": true + }, + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的 API Key", + "placeholder": "sk-...", + "required": true + }, + { + "id": "enableProxy", + "type": "confirm", + "label": "启用代理", + "prompt": "是否通过代理访问 API？", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "prompt": "输入代理服务器地址", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ], + + "template": { + "Providers": [ + { + "name": "#{provider}", + "api_base_url": "#{provider === 'openai' ? 'https://api.openai.com/v1' : 'https://api.deepseek.com'}", + "api_key": "#{apiKey}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + "Router": { + "default": "#{provider}/gpt-4o", + "background": "#{provider}/gpt-4o-mini" + } + }, + + "configMappings": [ + { + "target": "PROXY_URL", + "value": "#{proxyUrl}", + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ] +} +EOF + +# 配置预设（会提示输入） +ccr preset install advanced-config + +# 使用预设 +ccr advanced-config "your prompt" +``` + +### 导出当前配置为预设 + +如果您已经配置好了 CCR，可以导出当前配置： + +```bash +# 导出当前配置 +ccr preset export my-exported-preset +``` + +导出时会自动： +- 识别敏感字段（如 `api_key`）并替换为环境变量占位符 +- 生成 `schema` 用于收集用户输入 +- 生成 `template` 和 `configMappings` + +可选项： + +```bash +ccr preset export my-exported-preset \ + --description "导出的配置" \ + --author "Your Name" \ + --tags "production,openai" +``` + +:::tip 分享预设 +导出的预设目录可以直接分享给他人。接收者可以： +- **CLI 方式**：将目录放到 `~/.claude-code-router/presets/`，然后运行 `ccr preset install 预设名` +- **Web UI 方式**：将目录上传到 GitHub，然后通过仓库 URL 安装 +::: + +## 预设文件位置 + +预设保存在： + +``` +~/.claude-code-router/presets/ +``` + +每个预设都是一个目录，包含 `manifest.json` 文件。 + +## 最佳实践 + +1. **使用动态配置**：为需要用户输入的配置项使用schema系统 +2. **提供默认值**：为非必填项提供合理的默认值 +3. **条件显示**：使用when条件避免不必要的输入 +4. **清晰的标签**：为每个字段提供清晰的label和prompt +5. **验证输入**：使用validator确保输入的有效性 +6. **版本控制**：将常用预设保存在版本控制中 +7. **文档化**：为自定义预设添加描述和版本信息 + +## 下一步 + +- [CLI 参考](/zh/docs/cli/start) - 完整的 CLI 命令参考 +- [配置](/zh/docs/config/basic) - 详细配置指南 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/preset.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/preset.md new file mode 100644 index 0000000..f3db458 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/preset.md @@ -0,0 +1,254 @@ +--- +sidebar_position: 5 +--- + +# ccr preset + +管理预设（Presets）——可共享和重用的配置模板。 + +## 概述 + +预设功能让您可以： +- 将当前配置保存为可重用的模板 +- 与他人分享配置 +- 安装社区提供的预配置方案 +- 在不同配置之间轻松切换 + +## 命令 + +### export + +将当前配置导出为预设。 + +```bash +ccr preset export <名称> [选项] +``` + +**选项：** +- `--output <路径>` - 自定义输出目录路径 +- `--description <文本>` - 预设描述 +- `--author <名称>` - 预设作者 +- `--tags <标签>` - 逗号分隔的关键字 +- `--include-sensitive` - 包含 API 密钥等敏感数据（不推荐） + +**示例：** +```bash +ccr preset export my-config --description "我的生产环境配置" --author "您的名字" +``` + +**执行过程：** +1. 读取 `~/.claude-code-router/config.json` 中的当前配置 +2. 提示输入描述、作者和关键字（如未通过命令行提供） +3. 自动清理敏感字段（API 密钥变为占位符） +4. 在 `~/.claude-code-router/presets/<名称>/` 创建预设目录 +5. 生成包含配置和元数据的 `manifest.json` + +### install + +从本地目录安装预设。 + +```bash +ccr preset install <来源> +``` + +**来源：** +- 本地目录路径：`/path/to/preset-directory` +- 预设名称（用于重新配置已安装的预设）：`preset-name` + +**示例：** +```bash +# 从目录安装 +ccr preset install ./my-preset + +# 重新配置已安装的预设 +ccr preset install my-preset +``` + +**执行过程：** +1. 从预设目录读取 `manifest.json` +2. 验证预设结构 +3. 如果预设包含 `schema`，提示输入必需的值（API 密钥等） +4. 将预设复制到 `~/.claude-code-router/presets/<名称>/` +5. 在 `manifest.json` 中保存用户输入 + +**注意：** 目前不支持从 URL 安装。请先下载预设目录。 + +### list + +列出所有已安装的预设。 + +```bash +ccr preset list +``` + +**示例输出：** +``` +Available presets: + +• my-config (v1.0.0) + My production setup + by Your Name + +• openai-setup + Basic OpenAI configuration +``` + +### info + +显示预设的详细信息。 + +```bash +ccr preset info <名称> +``` + +**显示内容：** +- 版本、描述、作者、关键字 +- 配置摘要（Providers、Router 规则） +- 必需输入（如果有） + +**示例：** +```bash +ccr preset info my-config +``` + +### delete / rm / remove + +删除已安装的预设。 + +```bash +ccr preset delete <名称> +ccr preset rm <名称> +ccr preset remove <名称> +``` + +**示例：** +```bash +ccr preset delete my-config +``` + +## 预设结构 + +预设是一个包含 `manifest.json` 文件的目录： + +```json +{ + "name": "my-preset", + "version": "1.0.0", + "description": "我的配置", + "author": "作者姓名", + "keywords": ["openai", "production"], + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "{{apiKey}}", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + + "Router": { + "default": "openai:gpt-4" + }, + + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "OpenAI API 密钥", + "prompt": "请输入您的 OpenAI API 密钥" + } + ] +} +``` + +### Schema 系统 + +`schema` 字段定义用户在安装时必须提供的输入： + +**字段类型：** +- `password` - 隐藏输入（用于 API 密钥） +- `input` - 文本输入 +- `select` - 单选下拉框 +- `multiselect` - 多选下拉框 +- `confirm` - 是/否确认 +- `editor` - 多行文本编辑器 +- `number` - 数字输入 + +**动态选项：** +```json +{ + "id": "provider", + "type": "select", + "label": "选择提供商", + "options": { + "type": "providers" + } +} +``` + +**条件显示：** +```json +{ + "id": "model", + "type": "select", + "label": "选择模型", + "when": { + "field": "provider", + "operator": "exists" + }, + "options": { + "type": "models", + "providerField": "#{selectedProvider}" + } +} +``` + +## 分享预设 + +分享预设的步骤： + +1. **导出配置：** + ```bash + ccr preset export my-preset + ``` + +2. **分享目录：** + ```bash + ~/.claude-code-router/presets/my-preset/ + ``` + +3. **分发方式：** + - 上传到 GitHub 仓库 + - 创建 GitHub Gist + - 打包为 zip 文件分享 + - 发布到 npm（未来功能） + +4. **用户安装：** + ```bash + ccr preset install /path/to/my-preset + ``` + +## 安全性 + +### 自动清理 + +默认情况下，`export` 会清理敏感字段： +- 名为 `api_key`、`apikey`、`password`、`secret` 的字段会被替换为 `{{字段名}}` 占位符 +- 这些占位符会成为 schema 中的必需输入 +- 用户在安装时会被提示提供自己的值 + +### 包含敏感数据 + +要包含实际值（不推荐）： +```bash +ccr preset export my-preset --include-sensitive +``` + +**警告：** 永远不要分享包含敏感数据的预设！ + +## 相关文档 + +- [配置指南](/zh/docs/cli/config/basic) - 基础配置 +- [项目级配置](/zh/docs/cli/config/project-level) - 项目特定设置 +- [服务器：预设](/zh/docs/server/advanced/presets) - 高级预设主题 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/statusline.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/statusline.md new file mode 100644 index 0000000..20f4940 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/commands/statusline.md @@ -0,0 +1,402 @@ +--- +id: cli/commands/statusline +title: ccr statusline +sidebar_position: 5 +--- + +# ccr statusline + +显示可自定义的状态栏，实时展示 Claude Code 会话信息，包括工作区、Git 分支、模型、token 使用情况等。 + +## 概述 + +`ccr statusline` 命令从 stdin 读取 JSON 数据，并在终端中渲染格式精美的状态栏。它设计用于与 Claude Code 的 hook 系统集成，以显示实时会话信息。 + +## 使用方法 + +### 基本用法 + +```bash +ccr statusline +``` + +该命令期望通过 stdin 接收 JSON 数据，通常通过管道从 Claude Code hook 传递： + +```bash +echo '{"hook_event_name":"...","session_id":"...","..."}' | ccr statusline +``` + +### Hook 集成 + +在您的 Claude Code 设置中配置： + +```json +{ + "hooks": { + "postResponse": { + "command": "ccr statusline", + "input": "json" + } + } +} +``` + +## 可用主题 + +### 默认主题 + +简洁优雅的主题，使用 Nerd Font 图标和彩色文本： + +``` + 󰉋 my-project  main 󰚩 claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +### Powerline 主题 + +vim-powerline 风格，带背景色和箭头分隔符： + +``` + 󰉋 my-project  main 󰚩 claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +通过在配置中设置 `currentStyle: "powerline"` 激活。 + +### 简单主题 + +回退主题，不带图标，适用于不支持 Nerd Font 的终端： + +``` +my-project main claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +当 `USE_SIMPLE_ICONS=true` 或在不支持的终端上自动使用。 + +## 可用模块 + +状态栏模块显示不同类型的信息： + +| 模块 | 说明 | 变量 | +|------|------|------| +| **workDir** | 当前工作目录名称 | `{{workDirName}}` | +| **gitBranch** | 当前 Git 分支 | `{{gitBranch}}` | +| **model** | 使用的模型 | `{{model}}` | +| **usage** | Token 使用情况（输入/输出） | `{{inputTokens}}`, `{{outputTokens}}` | +| **context** | 上下文窗口使用情况 | `{{contextPercent}}`, `{{contextWindowSize}}` | +| **speed** | Token 处理速度 | `{{tokenSpeed}}`, `{{isStreaming}}` | +| **cost** | API 成本 | `{{cost}}` | +| **duration** | 会话持续时间 | `{{duration}}` | +| **lines** | 代码变更 | `{{linesAdded}}`, `{{linesRemoved}}` | +| **script** | 自定义脚本输出 | 动态 | + +## 配置 + +在 `~/.claude-code-router/config.json` 中配置 statusline： + +### 默认样式示例 + +```json +{ + "StatusLine": { + "currentStyle": "default", + "default": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "model", + "icon": "󰚩", + "text": "{{model}}", + "color": "bright_cyan" + }, + { + "type": "usage", + "icon": "↑", + "text": "{{inputTokens}}", + "color": "bright_green" + }, + { + "type": "usage", + "icon": "↓", + "text": "{{outputTokens}}", + "color": "bright_yellow" + } + ] + } + } +} +``` + +### Powerline 样式示例 + +```json +{ + "StatusLine": { + "currentStyle": "powerline", + "powerline": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "white", + "background": "bg_bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "white", + "background": "bg_bright_magenta" + } + ] + } + } +} +``` + +### 完整功能示例 + +```json +{ + "StatusLine": { + "currentStyle": "default", + "default": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "model", + "icon": "󰚩", + "text": "{{model}}", + "color": "bright_cyan" + }, + { + "type": "context", + "icon": "🪟", + "text": "{{contextPercent}}% / {{contextWindowSize}}", + "color": "bright_green" + }, + { + "type": "speed", + "icon": "⚡", + "text": "{{tokenSpeed}} t/s {{isStreaming}}", + "color": "bright_yellow" + }, + { + "type": "cost", + "icon": "💰", + "text": "{{cost}}", + "color": "bright_magenta" + }, + { + "type": "duration", + "icon": "⏱️", + "text": "{{duration}}", + "color": "bright_white" + }, + { + "type": "lines", + "icon": "📝", + "text": "+{{linesAdded}}/-{{linesRemoved}}", + "color": "bright_cyan" + } + ] + } + } +} +``` + +## 自定义脚本 + +您可以通过执行脚本创建自定义模块： + +```json +{ + "type": "script", + "icon": "🔧", + "scriptPath": "/path/to/script.js", + "options": { + "customOption": "value" + } +} +``` + +脚本格式（CommonJS）： + +```javascript +// my-status-module.js +module.exports = function(variables, options) { + // 访问变量如 model、gitBranch 等 + // 从配置中访问选项 + return `Custom: ${variables.model}`; +}; + +// 或异步 +module.exports = async function(variables, options) { + const data = await fetchSomeData(); + return data; +}; +``` + +## 颜色选项 + +### 标准颜色 + +- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` +- `bright_black`, `bright_red`, `bright_green`, `bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white` + +### 背景颜色 + +添加前缀 `bg_`：`bg_blue`, `bg_bright_red` 等。 + +### 十六进制颜色 + +使用 24 位 TrueColor 和十六进制代码： + +```json +{ + "color": "#FF5733", + "background": "bg_#1E90FF" +} +``` + +## 可用变量 + +所有变量都可以在模块文本中使用 `{{variableName}}` 访问： + +| 变量 | 说明 | 示例 | +|------|------|------| +| `{{workDirName}}` | 当前目录名称 | `my-project` | +| `{{gitBranch}}` | Git 分支名称 | `main` | +| `{{model}}` | 模型名称 | `claude-3-5-sonnet-20241022` | +| `{{inputTokens}}` | 输入 tokens（格式化） | `12.3k` | +| `{{outputTokens}}` | 输出 tokens（格式化） | `5.2k` | +| `{{tokenSpeed}}` | 每秒 tokens 数 | `45` | +| `{{isStreaming}}` | 流式传输状态 | `streaming` 或空 | +| `{{contextPercent}}` | 上下文使用百分比 | `45` | +| `{{contextWindowSize}}` | 总上下文窗口 | `200k` | +| `{{cost}}` | 总成本 | `$0.15` | +| `{{duration}}` | 会话持续时间 | `2m34s` | +| `{{linesAdded}}` | 添加的行数 | `150` | +| `{{linesRemoved}}` | 删除的行数 | `25` | +| `{{sessionId}}` | 会话 ID（前 8 个字符） | `a1b2c3d4` | + +## 环境变量 + +使用环境变量控制行为： + +| 变量 | 值 | 说明 | +|------|------|------| +| `USE_SIMPLE_ICONS` | `true`/`false` | 强制使用不带图标的简单主题 | +| `NERD_FONT` | 任意值 | 自动检测 Nerd Font 支持 | + +## 示例 + +### 极简状态栏 + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "model", + "text": "{{model}}" + }, + { + "type": "usage", + "text": "↑{{inputTokens}} ↓{{outputTokens}}" + } + ] + } + } +} +``` + +输出：`claude-3-5-sonnet-20241022 ↑12.3k ↓5.2k` + +### 开发者生产力重点 + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "lines", + "icon": "📝", + "text": "+{{linesAdded}}/-{{linesRemoved}}", + "color": "bright_cyan" + }, + { + "type": "duration", + "icon": "⏱️", + "text": "{{duration}}", + "color": "bright_white" + } + ] + } + } +} +``` + +输出：` feature/auth 📝 +150/-25 ⏱️ 2m34s` + +## Preset 集成 + +Statusline 主题可以包含在 presets 中。当您安装带有 statusline 配置的 preset 时，激活该 preset 时会自动应用。 + +查看 [Presets](/docs/server/advanced/presets) 了解更多信息。 + +## 故障排除 + +### 图标不显示 + +在环境中设置 `USE_SIMPLE_ICONS=true`： + +```bash +export USE_SIMPLE_ICONS=true +``` + +### 颜色不工作 + +确保您的终端支持 TrueColor（24 位颜色）： + +```bash +export COLORTERM=truecolor +``` + +### Git 分支不显示 + +确保您在 Git 仓库中并安装了 `git` 命令。 + +## 相关命令 + +- [ccr status](/docs/cli/commands/status) - 检查服务状态 +- [ccr preset](/docs/cli/commands/preset) - 管理带 statusline 主题的 presets diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/config/basic.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/config/basic.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/config/basic.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/config/basic.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/config/project-level.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/config/project-level.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/config/project-level.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/config/project-level.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/intro.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/intro.md similarity index 89% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/intro.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/intro.md index b50f69c..c661c54 100644 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/intro.md +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/intro.md @@ -12,12 +12,12 @@ Claude Code Router CLI (`ccr`) 是一个命令行工具，用于管理和控制 - **代码执行**：直接执行 `claude` 命令 - **环境集成**：输出环境变量用于 shell 集成 - **Web UI**：打开 Web 管理界面 -- **状态栏**：集成到编辑器状态栏 +- **状态栏**：使用 `ccr statusline` 显示自定义会话状态 ## 安装 ```bash -npm install -g @musistudio/claude-code-router-cli +npm install -g @musistudio/claude-code-router ``` 或使用项目别名： @@ -80,4 +80,5 @@ eval "$(ccr activate)" - [安装指南](/docs/cli/installation) - 详细安装说明 - [快速开始](/docs/cli/quick-start) - 5 分钟上手 - [命令参考](/docs/category/cli-commands) - 完整命令列表 +- [状态栏](/docs/cli/commands/statusline) - 自定义状态栏 - [配置说明](/docs/category/cli-config) - 配置文件详解 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/model.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/model.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/model.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/model.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/other-commands.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/other-commands.md new file mode 100644 index 0000000..7732494 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/other-commands.md @@ -0,0 +1,85 @@ +--- +id: cli/other-commands +title: 其他命令 +sidebar_position: 4 +--- + +# 其他命令 + +管理 Claude Code Router 的其他 CLI 命令。 + +## ccr stop + +停止运行中的服务器。 + +```bash +ccr stop +``` + +## ccr restart + +重启服务器。 + +```bash +ccr restart +``` + +## ccr code + +通过路由器执行 claude 命令。 + +```bash +ccr code [参数...] +``` + +## ccr ui + +在浏览器中打开 Web UI。 + +```bash +ccr ui +``` + +## ccr activate + +输出用于与外部工具集成的 shell 环境变量。 + +```bash +ccr activate +``` + +## 全局选项 + +这些选项可用于任何命令： + +| 选项 | 说明 | +|------|------| +| `-h, --help` | 显示帮助 | +| `-v, --version` | 显示版本号 | +| `--config <路径>` | 配置文件路径 | +| `--verbose` | 启用详细输出 | + +## 示例 + +### 停止服务器 + +```bash +ccr stop +``` + +### 使用自定义配置重启 + +```bash +ccr restart --config /path/to/config.json +``` + +### 打开 Web UI + +```bash +ccr ui +``` + +## 相关文档 + +- [入门](/zh/docs/intro) - Claude Code Router 简介 +- [配置](/zh/docs/config/basic) - 配置指南 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/start.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/start.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/start.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/start.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/status.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/status.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/status.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/cli/status.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/basic.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/basic.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/basic.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/basic.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/providers.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/providers.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/providers.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/providers.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/routing.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/routing.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/routing.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/routing.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/transformers.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/transformers.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/config/transformers.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/config/transformers.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/current.json b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/current.json new file mode 100644 index 0000000..3bebc6f --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/current.json @@ -0,0 +1,78 @@ +{ + "version.label": { + "message": "Next", + "description": "The label for version current" + }, + "sidebar.tutorialSidebar.category.Server": { + "message": "服务器", + "description": "The label for category 'Server' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Server.link.generated-index.title": { + "message": "Claude Code Router 服务器", + "description": "The generated-index page title for category 'Server' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Server.link.generated-index.description": { + "message": "部署和管理 Claude Code Router 服务器", + "description": "The generated-index page description for category 'Server' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.API Reference": { + "message": "API 参考", + "description": "The label for category 'API Reference' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.API Reference.link.generated-index.title": { + "message": "API 参考", + "description": "The generated-index page title for category 'API Reference' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.API Reference.link.generated-index.description": { + "message": "服务器 API 接口文档", + "description": "The generated-index page description for category 'API Reference' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Configuration": { + "message": "配置", + "description": "The label for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Configuration.link.generated-index.title": { + "message": "服务器配置", + "description": "The generated-index page title for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Configuration.link.generated-index.description": { + "message": "服务器配置说明", + "description": "The generated-index page description for category 'Configuration' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Advanced": { + "message": "高级", + "description": "The label for category 'Advanced' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Advanced.link.generated-index.title": { + "message": "高级主题", + "description": "The generated-index page title for category 'Advanced' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Advanced.link.generated-index.description": { + "message": "高级功能和自定义", + "description": "The generated-index page description for category 'Advanced' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.CLI": { + "message": "CLI", + "description": "The label for category 'CLI' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.CLI.link.generated-index.title": { + "message": "Claude Code Router CLI", + "description": "The generated-index page title for category 'CLI' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.CLI.link.generated-index.description": { + "message": "命令行工具使用指南", + "description": "The generated-index page description for category 'CLI' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Commands": { + "message": "命令", + "description": "The label for category 'Commands' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Commands.link.generated-index.title": { + "message": "CLI 命令", + "description": "The generated-index page title for category 'Commands' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Commands.link.generated-index.description": { + "message": "完整的命令参考", + "description": "The generated-index page description for category 'Commands' in sidebar 'tutorialSidebar'" + } +} diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/installation.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/installation.md similarity index 80% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/installation.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/installation.md index d6355c6..517bf9f 100644 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/installation.md +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/installation.md @@ -17,19 +17,19 @@ sidebar_position: 2 ## 通过 npm 安装 ```bash -npm install -g @musistudio/claude-code-router-cli +npm install -g @musistudio/claude-code-router ``` ## 通过 pnpm 安装 ```bash -pnpm add -g @musistudio/claude-code-router-cli +pnpm add -g @musistudio/claude-code-router ``` ## 通过 Yarn 安装 ```bash -yarn global add @musistudio/claude-code-router-cli +yarn global add @musistudio/claude-code-router ``` ## 验证安装 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/intro.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/intro.md similarity index 74% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/intro.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/intro.md index 7a4560b..111661b 100644 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/intro.md +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/intro.md @@ -7,9 +7,9 @@ slug: / # 欢迎使用 Claude Code Router -[![npm version](https://badge.fury.io/js/%40musistudio%2Fclaude-code-router-cli.svg)](https://www.npmjs.com/package/@musistudio/claude-code-router-cli) +[![npm version](https://badge.fury.io/js/%40musistudio%2Fclaude-code-router.svg)](https://www.npmjs.com/package/@musistudio/claude-code-router) ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) -![Node Version](https://img.shields.io/node/v/@musistudio/claude-code-router-cli.svg) +![Node Version](https://img.shields.io/node/v/@musistudio/claude-code-router.svg) **Claude Code Router** 是一个强大的工具，允许你在没有 Anthropic 账户的情况下使用 [Claude Code](https://claude.ai/code)，并将请求路由到其他 LLM 提供商。 @@ -29,11 +29,11 @@ slug: / ### 安装 ```bash -npm install -g @musistudio/claude-code-router-cli +npm install -g @musistudio/claude-code-router # 或 -pnpm add -g @musistudio/claude-code-router-cli +pnpm add -g @musistudio/claude-code-router # 或 -yarn global add @musistudio/claude-code-router-cli +yarn global add @musistudio/claude-code-router ``` ### 基本使用 @@ -61,10 +61,10 @@ claude code Claude Code Router 由四个主要组件组成： -- **CLI** (`@musistudio/claude-code-router-cli`): 提供 `ccr` 命令的命令行工具 -- **Server** (`@musistudio/claude-code-router-server`): 处理 API 路由和转换的核心服务器 -- **Shared** (`@musistudio/claude-code-router-shared`): 共享常量和工具 -- **UI** (`@musistudio/claude-code-router-ui`): Web 管理界面（React + Vite） +- **CLI** (`@musistudio/claude-code-router`): 提供 `ccr` 命令的命令行工具 +- **Server** (`@CCR/server`): 处理 API 路由和转换的核心服务器 +- **Shared** (`@CCR/shared`): 共享常量和工具 +- **UI** (`@CCR/ui`): Web 管理界面（React + Vite） ## 许可证 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/quick-start.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/quick-start.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/quick-start.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/quick-start.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/config-api.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/config-api.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/config-api.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/config-api.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/logs-api.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/logs-api.md similarity index 86% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/logs-api.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/logs-api.md index 5dc6ec2..c66cbfb 100644 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/logs-api.md +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/logs-api.md @@ -164,27 +164,3 @@ curl -X DELETE "http://localhost:3456/api/logs?file=/home/user/.claude-code-rout - **maxFiles**: 3 - 保留最近 3 个日志文件 - **interval**: 1d - 每天轮转 - **maxSize**: 50M - 单个文件最大 50MB - -## 日志分析 - -### 使用 jq 分析日志 - -```bash -# 查看所有错误日志 -curl "http://localhost:3456/api/logs" \ - -H "x-api-key: your-api-key" | \ - jq -r '.[] | fromjson | select(.level >= 40)' - -# 统计请求次数 -curl "http://localhost:3456/api/logs" \ - -H "x-api-key: your-api-key" | \ - jq -r '.[] | fromjson | .req.method' | \ - sort | uniq -c -``` - -### 实时监控日志 - -```bash -# 通过 API 实时获取最新日志 -watch -n 5 'curl -s "http://localhost:3456/api/logs" -H "x-api-key: your-api-key" | jq -r ".[-10:]"' -``` diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/messages-api.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/messages-api.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/messages-api.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/messages-api.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/overview.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/overview.md similarity index 74% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/overview.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/overview.md index 0fb0ef5..31f46f0 100644 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/api/overview.md +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/api/overview.md @@ -50,27 +50,6 @@ curl -H "x-api-key: your-api-key" http://localhost:3456/api/config | `/ui` | GET | Web 管理界面 | | `/ui/` | GET | Web 管理界面（重定向） | -## 错误响应 - -所有 API 在发生错误时返回统一的错误格式： - -```json -{ - "error": { - "type": "invalid_request_error", - "message": "错误描述" - } -} -``` - -常见 HTTP 状态码： - -- `200` - 成功 -- `400` - 请求参数错误 -- `401` - 未授权（API Key 无效） -- `404` - 资源不存在 -- `500` - 服务器内部错误 - ## 认证 ### API Key 认证 @@ -84,16 +63,6 @@ curl -X POST http://localhost:3456/v1/messages \ -d '...' ``` -### 无认证模式 - -当没有配置 Providers 时，服务器会监听在 `0.0.0.0` 且无需认证： - -```json5 -{ - "Providers": [] -} -``` - ## 流式响应 消息 API 支持流式响应（Server-Sent Events）： @@ -117,13 +86,3 @@ data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"} event: message_stop data: {"type":"message_stop"} ``` - -## 速率限制 - -服务器本身不实现速率限制，建议通过反向代理（如 Nginx）配置。 - -## 版本管理 - -当前 API 版本：`v1` - -所有 `/v1/*` 端点保持向后兼容。 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/deployment.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/deployment.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/deployment.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/deployment.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/intro.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/intro.md similarity index 100% rename from docs/i18n/zh-CN/docusaurus-plugin-content-docs/server/intro.md rename to docs/i18n/zh-CN/docusaurus-plugin-content-docs.backup.20260101_205603/server/intro.md diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/agents.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/agents.md deleted file mode 100644 index 695d1f4..0000000 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/agents.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -id: advanced/agents -title: Agent 系统 -sidebar_position: 2 ---- - -# Agent 系统 - -使用 Agent 系统扩展功能。 - -## 什么是 Agent？ - -Agent 是可插拔的功能模块，可以： -- 检测是否应处理请求 -- 修改请求 -- 提供自定义工具 - -## 内置 Agent - -### Image Agent - -通过检测请求中的图像 URL 或文件路径来处理图像相关任务。 - -当检测到图像相关内容时，Image Agent 会： -1. 标记请求需要图像处理 -2. 添加图像分析工具到请求中 -3. 拦截工具调用事件 -4. 执行图像分析并返回结果 - -## Agent 配置 - -Agent 在服务器配置中配置并自动加载。 - -### 启用 Image Agent - -Image Agent 内置于服务器中，无需额外配置。当请求包含图像内容时自动激活。 - -### 强制使用 Image Agent - -如果您的模型不支持工具调用，可以在配置中设置 `config.forceUseImageAgent` 为 `true`： - -```json -{ - "Router": { - "image": "gemini,gemini-2.5-pro" - }, - "forceUseImageAgent": true -} -``` - -## Agent 工具调用流程 - -1. **检测阶段**：在 `preHandler` 钩子中检测并标记 agents -2. **准备阶段**：将 agent 工具添加到请求中 -3. **拦截阶段**：在 `onSend` 钩子中拦截工具调用事件 -4. **执行阶段**：执行 agent 工具并发起新的 LLM 请求 -5. **返回阶段**：将结果流式返回 - -## Agent 类型定义 - -```typescript -interface IAgent { - name: string; - shouldHandle: (req: any, config: any) => boolean; - reqHandler: (req: any, config: any) => void; - tools: Map; -} - -interface ITool { - name: string; - description: string; - input_schema: object; - handler: (args: any, context: any) => Promise; -} -``` - -## 创建自定义 Agent - -自定义 Agent 支持正在开发中！ - -## 使用示例 - -### 图像分析请求 - -当您发送包含图像的请求时： - -``` -请分析这张图片：/path/to/image.png -``` - -Image Agent 将： -1. 检测到图像路径 -2. 添加图像分析工具 -3. 调用配置的图像处理模型 -4. 返回分析结果 - -### 路由到支持图像的模型 - -在配置中指定用于图像任务的模型： - -```json -{ - "Router": { - "image": "gemini,gemini-2.5-pro" - } -} -``` - -## 下一步 - -- [预设](/zh/docs/advanced/presets) - 使用预定义配置 -- [自定义路由器](/zh/docs/advanced/custom-router) - 编写自定义路由逻辑 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/presets.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/presets.md deleted file mode 100644 index 91bf70b..0000000 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/advanced/presets.md +++ /dev/null @@ -1,394 +0,0 @@ ---- -id: advanced/presets -title: 预设配置 -sidebar_position: 3 ---- - -# 预设配置 - -使用预定义配置进行快速设置。 - -## 什么是预设？ - -预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。 - -## 动态配置系统 (v2.0+) - -CCR 2.0 引入了强大的动态配置系统，支持： - -- **多种输入类型**：选择器、多选、确认框、文本输入、数字输入等 -- **条件逻辑**：根据用户输入动态显示/隐藏配置项 -- **变量引用**：配置项之间可以互相引用 -- **动态选项**：选项列表可以从预设配置或用户输入中动态生成 - -### Schema 字段类型 - -| 类型 | 说明 | 示例 | -|------|------|------| -| `password` | 密码输入（隐藏显示） | API Key | -| `input` | 单行文本输入 | Base URL | -| `number` | 数字输入 | 最大Token数 | -| `select` | 单选下拉框 | 选择Provider | -| `multiselect` | 多选框 | 启用功能 | -| `confirm` | 确认框 | 是否使用代理 | -| `editor` | 多行文本编辑器 | 自定义配置 | - -### 条件运算符 - -| 运算符 | 说明 | 示例 | -|--------|------|------| -| `eq` | 等于 | `{"field": "provider", "operator": "eq", "value": "openai"}` | -| `ne` | 不等于 | `{"field": "advanced", "operator": "ne", "value": true}` | -| `in` | 包含于 | `{"field": "feature", "operator": "in", "value": ["a", "b"]}` | -| `nin` | 不包含于 | `{"field": "type", "operator": "nin", "value": ["x", "y"]}` | -| `exists` | 字段存在 | `{"field": "apiKey", "operator": "exists"}` | -| `gt/lt/gte/lte` | 大于/小于/大于等于/小于等于 | 用于数字比较 | - -### 动态选项类型 - -#### static - 静态选项 -```json -"options": { - "type": "static", - "options": [ - {"label": "选项1", "value": "value1"}, - {"label": "选项2", "value": "value2"} - ] -} -``` - -#### providers - 从 Providers 配置提取 -```json -"options": { - "type": "providers" -} -``` -自动从 `Providers` 数组中提取 name 作为选项。 - -#### models - 从指定 Provider 的 models 提取 -```json -"options": { - "type": "models", - "providerField": "{{selectedProvider}}" -} -``` -根据用户选择的 Provider，动态显示该 Provider 的 models。 - -### 模板变量 - -使用 `{{变量名}}` 语法在 template 中引用用户输入： - -```json -"template": { - "Providers": [ - { - "name": "{{providerName}}", - "api_key": "{{apiKey}}" - } - ] -} -``` - -### 配置映射 - -对于复杂的配置需求，使用 `configMappings` 精确控制值的位置： - -```json -"configMappings": [ - { - "target": "Providers[0].api_key", - "value": "{{apiKey}}" - }, - { - "target": "PROXY_URL", - "value": "{{proxyUrl}}", - "when": { - "field": "useProxy", - "operator": "eq", - "value": true - } - } -] -``` - -### 完整示例 - -```json -{ - "name": "multi-provider-example", - "version": "1.0.0", - "description": "多Provider配置示例 - 支持OpenAI和DeepSeek切换", - "author": "CCR Team", - "keywords": ["openai", "deepseek", "multi-provider"], - "ccrVersion": "2.0.0", - "schema": [ - { - "id": "primaryProvider", - "type": "select", - "label": "主要Provider", - "prompt": "选择您主要使用的LLM提供商", - "options": { - "type": "static", - "options": [ - { - "label": "OpenAI", - "value": "openai", - "description": "使用OpenAI的GPT模型" - }, - { - "label": "DeepSeek", - "value": "deepseek", - "description": "使用DeepSeek的高性价比模型" - } - ] - }, - "required": true, - "defaultValue": "openai" - }, - { - "id": "apiKey", - "type": "password", - "label": "API Key", - "prompt": "请输入您的API Key", - "placeholder": "sk-...", - "required": true - }, - { - "id": "defaultModel", - "type": "select", - "label": "默认模型", - "prompt": "选择默认使用的模型", - "options": { - "type": "static", - "options": [ - {"label": "GPT-4o", "value": "gpt-4o"}, - {"label": "GPT-4o-mini", "value": "gpt-4o-mini"} - ] - }, - "required": true, - "defaultValue": "gpt-4o", - "when": { - "field": "primaryProvider", - "operator": "eq", - "value": "openai" - } - }, - { - "id": "enableProxy", - "type": "confirm", - "label": "启用代理", - "prompt": "是否通过代理访问API？", - "defaultValue": false - }, - { - "id": "proxyUrl", - "type": "input", - "label": "代理地址", - "prompt": "输入代理服务器地址", - "placeholder": "http://127.0.0.1:7890", - "required": true, - "when": { - "field": "enableProxy", - "operator": "eq", - "value": true - } - } - ], - "template": { - "Providers": [ - { - "name": "{{primaryProvider}}", - "api_base_url": "https://api.openai.com/v1", - "api_key": "{{apiKey}}", - "models": ["{{defaultModel}}"] - } - ], - "Router": { - "default": "{{primaryProvider}}/{{defaultModel}}" - }, - "PROXY_URL": "{{proxyUrl}}" - }, - "configMappings": [ - { - "target": "PROXY_URL", - "value": "{{proxyUrl}}", - "when": { - "field": "enableProxy", - "operator": "eq", - "value": true - } - } - ] -} -``` - -## 可用预设 - -### Development（开发） - -针对软件开发任务优化： -- 快速响应时间 -- 适合代码生成 -- 成本效益高 - -配置特点： -- 使用轻量级模型处理后台任务 -- 为代码任务选择专用模型 -- 优化的超时设置 - -### Research（研究） - -针对研究和分析优化： -- 支持长上下文 -- 高质量响应 -- 更强大的模型 - -配置特点： -- 使用具有大上下文窗口的模型 -- 为分析任务选择高级模型 -- 较长的超时时间 - -### Balanced（平衡） - -在速度和质量之间取得平衡： -- 良好的通用性能 -- 合理的成本 -- 广泛的模型支持 - -配置特点： -- 混合使用快速和高质量的模型 -- 适合大多数日常任务 -- 平衡的成本效益 - -## 使用预设 - -使用 CLI 应用预设： - -```bash -ccr preset apply development -``` - -列出可用预设： - -```bash -ccr preset list -``` - -## 创建自定义预设 - -创建包含 `schema` 和 `template` 的预设文件： - -```bash -# 创建预设目录 -mkdir -p ~/.claude-code-router/presets/my-preset - -# 创建 manifest.json -cat > ~/.claude-code-router/presets/my-preset/manifest.json << 'EOF' -{ - "name": "my-preset", - "version": "1.0.0", - "description": "我的自定义预设", - "schema": [ - { - "id": "apiKey", - "type": "password", - "label": "API Key", - "required": true - } - ], - "template": { - "Providers": [ - { - "name": "my-provider", - "api_key": "{{apiKey}}" - } - ] - } -} -EOF - -# 应用预设（会提示输入API Key） -ccr my-preset -``` - -您也可以通过保存配置并稍后重新加载来创建自定义预设： - -```bash -# 将当前配置保存为预设 -ccr preset save my-preset - -# 加载已保存的预设 -ccr preset apply my-preset -``` - -## 预设管理 - -### 列出所有预设 - -```bash -ccr preset list -``` - -输出示例： - -``` -可用预设: - development - 开发优化配置 - research - 研究优化配置 - balanced - 平衡配置 - my-preset - 自定义预设 -``` - -### 应用预设 - -```bash -ccr preset apply <预设名称> -``` - -应用预设后，服务器将自动重启以加载新配置。 - -### 删除预设 - -```bash -ccr preset delete <预设名称> -``` - -## 预设文件位置 - -预设保存在： - -``` -~/.claude-code-router/presets/ -``` - -每个预设都是一个目录，包含 `manifest.json` 文件。 - -## 导出和导入预设 - -### 导出当前配置 - -```bash -ccr config show > my-config.json -``` - -### 导入配置 - -```bash -ccr config edit -# 然后粘贴导入的配置 -``` - -## 最佳实践 - -1. **使用动态配置**：为需要用户输入的配置项使用schema系统 -2. **提供默认值**：为非必填项提供合理的默认值 -3. **条件显示**：使用when条件避免不必要的输入 -4. **清晰的标签**：为每个字段提供清晰的label和prompt -5. **验证输入**：使用validator确保输入的有效性 -6. **版本控制**：将常用预设保存在版本控制中 -7. **文档化**：为自定义预设添加描述和版本信息 - -## 下一步 - -- [CLI 参考](/zh/docs/cli/start) - 完整的 CLI 命令参考 -- [配置](/zh/docs/config/basic) - 详细配置指南 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/other-commands.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/other-commands.md deleted file mode 100644 index a331331..0000000 --- a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/other-commands.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -id: cli/other-commands -title: 其他命令 -sidebar_position: 4 ---- - -# 其他命令 - -管理 Claude Code Router 的其他 CLI 命令。 - -## ccr stop - -停止运行中的服务器。 - -```bash -ccr stop -``` - -## ccr restart - -重启服务器。 - -```bash -ccr restart -``` - -## ccr code - -通过路由器执行 claude 命令。 - -```bash -ccr code [参数...] -``` - -## ccr activate - -输出 shell 环境变量以供集成使用。 - -```bash -ccr activate -``` - -输出： - -```bash -export ANTHROPIC_API_URL="http://localhost:3456/v1" -export ANTHROPIC_API_KEY="sk-xxxxx" -``` - -在 shell 中使用： - -```bash -eval "$(ccr activate)" -``` - -`activate` 命令设置以下环境变量： - -- `ANTHROPIC_AUTH_TOKEN`: 来自配置的 API 密钥 -- `ANTHROPIC_BASE_URL`: 本地路由器端点（默认：`http://127.0.0.1:3456`） -- `NO_PROXY`: 设置为 `127.0.0.1` 以防止代理干扰 -- `DISABLE_TELEMETRY`: 禁用遥测 -- `DISABLE_COST_WARNINGS`: 禁用成本警告 -- `API_TIMEOUT_MS`: 来自配置的 API 超时时间 - -## ccr ui - -在浏览器中打开 Web UI。 - -```bash -ccr ui -``` - -## ccr statusline - -集成状态栏（从 stdin 读取 JSON）。 - -```bash -echo '{"status":"running"}' | ccr statusline -``` - -## ccr config - -配置管理命令。 - -### 编辑配置 - -```bash -ccr config edit -``` - -在默认编辑器中打开配置文件。 - -### 验证配置 - -```bash -ccr config validate -``` - -验证当前配置文件。 - -### 显示配置 - -```bash -ccr config show -``` - -显示当前配置（敏感值已隐藏）。 - -## ccr preset - -预设管理命令。 - -### 列出预设 - -```bash -ccr preset list -``` - -### 应用预设 - -```bash -ccr preset apply <名称> -``` - -### 保存预设 - -```bash -ccr preset save <名称> -``` - -保存当前配置为预设。 - -## ccr log - -查看服务器日志。 - -```bash -ccr log [选项] -``` - -选项： -- `-f, --follow`: 跟踪日志输出（类似 `tail -f`） -- `-n <行数>`: 显示的行数 - -## 全局选项 - -这些选项可用于任何命令： - -| 选项 | 说明 | -|------|------| -| `-h, --help` | 显示帮助 | -| `-v, --version` | 显示版本号 | -| `--config <路径>` | 配置文件路径 | -| `--verbose` | 启用详细输出 | - -## 示例 - -### 停止服务器 - -```bash -ccr stop -``` - -### 使用自定义配置重启 - -```bash -ccr restart --config /path/to/config.json -``` - -### 查看并设置环境变量 - -```bash -eval "$(ccr activate)" -``` - -### 打开 Web UI - -```bash -ccr ui -``` - -### 跟踪日志 - -```bash -ccr log -f -``` - -### 列出可用预设 - -```bash -ccr preset list -``` - -### 应用预设 - -```bash -ccr preset apply development -``` - -## 相关文档 - -- [入门](/zh/docs/intro) - Claude Code Router 简介 -- [配置](/zh/docs/config/basic) - 配置指南 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/model.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/model.md new file mode 100644 index 0000000..a8a0082 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/model.md @@ -0,0 +1,127 @@ +--- +title: ccr model +sidebar_position: 2 +--- + +# ccr model + +交互式模型选择和配置。 + +## 用法 + +```bash +ccr model [命令] +``` + +## 命令 + +### 选择模型 + +交互式选择模型： + +```bash +ccr model +``` + +这将显示一个包含可用提供商和模型的交互式菜单。 + +### 设置默认模型 + +直接设置默认模型： + +```bash +ccr model set , +``` + +示例： + +```bash +ccr model set deepseek,deepseek-chat +``` + +### 列出模型 + +列出所有配置的模型： + +```bash +ccr model list +``` + +### 添加模型 + +添加新模型到配置： + +```bash +ccr model add , +``` + +示例： + +```bash +ccr model add groq,llama-3.3-70b-versatile +``` + +### 删除模型 + +从配置中删除模型： + +```bash +ccr model remove , +``` + +## 示例 + +### 交互式选择 + +```bash +$ ccr model + +? 选择一个提供商: deepseek +? 选择一个模型: deepseek-chat + +默认模型设置为: deepseek,deepseek-chat +``` + +### 直接配置 + +```bash +ccr model set deepseek,deepseek-chat +``` + +### 查看当前配置 + +```bash +ccr model list +``` + +输出： + +``` +已配置的模型: + deepseek,deepseek-chat (默认) + groq,llama-3.3-70b-versatile + gemini,gemini-2.5-pro +``` + +## 交互式功能 + +`ccr model` 命令提供以下功能： + +1. **查看当前配置**：查看所有已配置的模型和路由器设置 +2. **切换模型**：快速更改每个路由器类型使用的模型 +3. **添加新模型**：向现有提供商添加模型 +4. **创建新提供商**：设置完整的提供商配置，包括： + - 提供商名称和 API 端点 + - API 密钥 + - 可用模型 + - 转换器配置，支持： + - 多个转换器（openrouter、deepseek、gemini 等） + - 转换器选项（例如，带自定义限制的 maxtoken） + - 提供商特定路由（例如，OpenRouter 提供商偏好） + +CLI 工具会验证所有输入并提供有用的提示来引导您完成配置过程，使管理复杂设置变得容易，无需手动编辑 JSON 文件。 + +## 相关命令 + +- [ccr start](/zh/docs/cli/start) - 启动服务器 +- [ccr config](/zh/docs/cli/other-commands#ccr-config) - 编辑配置 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/other.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/other.md new file mode 100644 index 0000000..ff54b07 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/other.md @@ -0,0 +1,84 @@ +--- +title: 其他命令 +sidebar_position: 4 +--- + +# 其他命令 + +管理 Claude Code Router 的其他 CLI 命令。 + +## ccr stop + +停止运行中的服务器。 + +```bash +ccr stop +``` + +## ccr restart + +重启服务器。 + +```bash +ccr restart +``` + +## ccr code + +通过路由器执行 claude 命令。 + +```bash +ccr code [参数...] +``` + +## ccr ui + +在浏览器中打开 Web UI。 + +```bash +ccr ui +``` + +## ccr activate + +输出用于与外部工具集成的 shell 环境变量。 + +```bash +ccr activate +``` + +## 全局选项 + +这些选项可用于任何命令： + +| 选项 | 说明 | +|------|------| +| `-h, --help` | 显示帮助 | +| `-v, --version` | 显示版本号 | +| `--config <路径>` | 配置文件路径 | +| `--verbose` | 启用详细输出 | + +## 示例 + +### 停止服务器 + +```bash +ccr stop +``` + +### 使用自定义配置重启 + +```bash +ccr restart --config /path/to/config.json +``` + +### 打开 Web UI + +```bash +ccr ui +``` + +## 相关文档 + +- [入门](/zh/docs/intro) - Claude Code Router 简介 +- [配置](/zh/docs/config/basic) - 配置指南 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/preset.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/preset.md new file mode 100644 index 0000000..f3db458 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/preset.md @@ -0,0 +1,254 @@ +--- +sidebar_position: 5 +--- + +# ccr preset + +管理预设（Presets）——可共享和重用的配置模板。 + +## 概述 + +预设功能让您可以： +- 将当前配置保存为可重用的模板 +- 与他人分享配置 +- 安装社区提供的预配置方案 +- 在不同配置之间轻松切换 + +## 命令 + +### export + +将当前配置导出为预设。 + +```bash +ccr preset export <名称> [选项] +``` + +**选项：** +- `--output <路径>` - 自定义输出目录路径 +- `--description <文本>` - 预设描述 +- `--author <名称>` - 预设作者 +- `--tags <标签>` - 逗号分隔的关键字 +- `--include-sensitive` - 包含 API 密钥等敏感数据（不推荐） + +**示例：** +```bash +ccr preset export my-config --description "我的生产环境配置" --author "您的名字" +``` + +**执行过程：** +1. 读取 `~/.claude-code-router/config.json` 中的当前配置 +2. 提示输入描述、作者和关键字（如未通过命令行提供） +3. 自动清理敏感字段（API 密钥变为占位符） +4. 在 `~/.claude-code-router/presets/<名称>/` 创建预设目录 +5. 生成包含配置和元数据的 `manifest.json` + +### install + +从本地目录安装预设。 + +```bash +ccr preset install <来源> +``` + +**来源：** +- 本地目录路径：`/path/to/preset-directory` +- 预设名称（用于重新配置已安装的预设）：`preset-name` + +**示例：** +```bash +# 从目录安装 +ccr preset install ./my-preset + +# 重新配置已安装的预设 +ccr preset install my-preset +``` + +**执行过程：** +1. 从预设目录读取 `manifest.json` +2. 验证预设结构 +3. 如果预设包含 `schema`，提示输入必需的值（API 密钥等） +4. 将预设复制到 `~/.claude-code-router/presets/<名称>/` +5. 在 `manifest.json` 中保存用户输入 + +**注意：** 目前不支持从 URL 安装。请先下载预设目录。 + +### list + +列出所有已安装的预设。 + +```bash +ccr preset list +``` + +**示例输出：** +``` +Available presets: + +• my-config (v1.0.0) + My production setup + by Your Name + +• openai-setup + Basic OpenAI configuration +``` + +### info + +显示预设的详细信息。 + +```bash +ccr preset info <名称> +``` + +**显示内容：** +- 版本、描述、作者、关键字 +- 配置摘要（Providers、Router 规则） +- 必需输入（如果有） + +**示例：** +```bash +ccr preset info my-config +``` + +### delete / rm / remove + +删除已安装的预设。 + +```bash +ccr preset delete <名称> +ccr preset rm <名称> +ccr preset remove <名称> +``` + +**示例：** +```bash +ccr preset delete my-config +``` + +## 预设结构 + +预设是一个包含 `manifest.json` 文件的目录： + +```json +{ + "name": "my-preset", + "version": "1.0.0", + "description": "我的配置", + "author": "作者姓名", + "keywords": ["openai", "production"], + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "{{apiKey}}", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + + "Router": { + "default": "openai:gpt-4" + }, + + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "OpenAI API 密钥", + "prompt": "请输入您的 OpenAI API 密钥" + } + ] +} +``` + +### Schema 系统 + +`schema` 字段定义用户在安装时必须提供的输入： + +**字段类型：** +- `password` - 隐藏输入（用于 API 密钥） +- `input` - 文本输入 +- `select` - 单选下拉框 +- `multiselect` - 多选下拉框 +- `confirm` - 是/否确认 +- `editor` - 多行文本编辑器 +- `number` - 数字输入 + +**动态选项：** +```json +{ + "id": "provider", + "type": "select", + "label": "选择提供商", + "options": { + "type": "providers" + } +} +``` + +**条件显示：** +```json +{ + "id": "model", + "type": "select", + "label": "选择模型", + "when": { + "field": "provider", + "operator": "exists" + }, + "options": { + "type": "models", + "providerField": "#{selectedProvider}" + } +} +``` + +## 分享预设 + +分享预设的步骤： + +1. **导出配置：** + ```bash + ccr preset export my-preset + ``` + +2. **分享目录：** + ```bash + ~/.claude-code-router/presets/my-preset/ + ``` + +3. **分发方式：** + - 上传到 GitHub 仓库 + - 创建 GitHub Gist + - 打包为 zip 文件分享 + - 发布到 npm（未来功能） + +4. **用户安装：** + ```bash + ccr preset install /path/to/my-preset + ``` + +## 安全性 + +### 自动清理 + +默认情况下，`export` 会清理敏感字段： +- 名为 `api_key`、`apikey`、`password`、`secret` 的字段会被替换为 `{{字段名}}` 占位符 +- 这些占位符会成为 schema 中的必需输入 +- 用户在安装时会被提示提供自己的值 + +### 包含敏感数据 + +要包含实际值（不推荐）： +```bash +ccr preset export my-preset --include-sensitive +``` + +**警告：** 永远不要分享包含敏感数据的预设！ + +## 相关文档 + +- [配置指南](/zh/docs/cli/config/basic) - 基础配置 +- [项目级配置](/zh/docs/cli/config/project-level) - 项目特定设置 +- [服务器：预设](/zh/docs/server/advanced/presets) - 高级预设主题 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/start.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/start.md new file mode 100644 index 0000000..de4436e --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/start.md @@ -0,0 +1,82 @@ +--- +title: ccr start +sidebar_position: 1 +--- + +# ccr start + +启动 Claude Code Router 服务器。 + +## 用法 + +```bash +ccr start [选项] +``` + +## 选项 + +| 选项 | 别名 | 说明 | +|------|------|------| +| `--port ` | `-p` | 监听端口号（默认：3456） | +| `--config ` | `-c` | 配置文件路径 | +| `--daemon` | `-d` | 作为守护进程运行（后台进程） | +| `--log-level ` | `-l` | 日志级别（fatal/error/warn/info/debug/trace） | + +## 示例 + +### 使用默认设置启动 + +```bash +ccr start +``` + +### 在自定义端口启动 + +```bash +ccr start --port 3000 +``` + +### 使用自定义配置启动 + +```bash +ccr start --config /path/to/config.json +``` + +### 作为守护进程启动 + +```bash +ccr start --daemon +``` + +### 启用调试日志 + +```bash +ccr start --log-level debug +``` + +## 环境变量 + +您也可以使用环境变量配置服务器： + +| 变量 | 说明 | +|------|------| +| `PORT` | 监听端口号 | +| `CONFIG_PATH` | 配置文件路径 | +| `LOG_LEVEL` | 日志级别 | +| `CUSTOM_ROUTER_PATH` | 自定义路由器函数路径 | +| `HOST` | 绑定主机地址（默认：0.0.0.0） | + +## 输出 + +启动成功后，您将看到： + +``` +Claude Code Router is running on http://localhost:3456 +API endpoint: http://localhost:3456/v1 +``` + +## 相关命令 + +- [ccr stop](/zh/docs/cli/other-commands#ccr-stop) - 停止服务器 +- [ccr restart](/zh/docs/cli/other-commands#ccr-restart) - 重启服务器 +- [ccr status](/zh/docs/cli/other-commands#ccr-status) - 检查服务器状态 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/status.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/status.md new file mode 100644 index 0000000..87b5cbd --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/status.md @@ -0,0 +1,63 @@ +--- +title: ccr status +sidebar_position: 3 +--- + +# ccr status + +显示 Claude Code Router 服务器的当前状态。 + +## 用法 + +```bash +ccr status +``` + +## 输出 + +### 运行中的服务器 + +当服务器正在运行时： + +``` +Claude Code Router 状态: 运行中 +版本: 2.0.0 +PID: 12345 +端口: 3456 +运行时间: 2小时34分钟 +配置: /home/user/.claude-code-router/config.json +``` + +### 已停止的服务器 + +当服务器未运行时： + +``` +Claude Code Router 状态: 已停止 +``` + +## 退出代码 + +| 代码 | 说明 | +|------|------| +| 0 | 服务器正在运行 | +| 1 | 服务器已停止 | +| 2 | 检查状态时出错 | + +## 示例 + +```bash +$ ccr status + +Claude Code Router 状态: 运行中 +版本: 2.0.0 +PID: 12345 +端口: 3456 +运行时间: 2小时34分钟 +``` + +## 相关命令 + +- [ccr start](/zh/docs/cli/start) - 启动服务器 +- [ccr stop](/zh/docs/cli/other-commands#ccr-stop) - 停止服务器 +- [ccr restart](/zh/docs/cli/other-commands#ccr-restart) - 重启服务器 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/statusline.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/statusline.md new file mode 100644 index 0000000..97620fb --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/commands/statusline.md @@ -0,0 +1,401 @@ +--- +title: ccr statusline +sidebar_position: 5 +--- + +# ccr statusline + +显示可自定义的状态栏，实时展示 Claude Code 会话信息，包括工作区、Git 分支、模型、token 使用情况等。 + +## 概述 + +`ccr statusline` 命令从 stdin 读取 JSON 数据，并在终端中渲染格式精美的状态栏。它设计用于与 Claude Code 的 hook 系统集成，以显示实时会话信息。 + +## 使用方法 + +### 基本用法 + +```bash +ccr statusline +``` + +该命令期望通过 stdin 接收 JSON 数据，通常通过管道从 Claude Code hook 传递： + +```bash +echo '{"hook_event_name":"...","session_id":"...","..."}' | ccr statusline +``` + +### Hook 集成 + +在您的 Claude Code 设置中配置： + +```json +{ + "hooks": { + "postResponse": { + "command": "ccr statusline", + "input": "json" + } + } +} +``` + +## 可用主题 + +### 默认主题 + +简洁优雅的主题，使用 Nerd Font 图标和彩色文本： + +``` + 󰉋 my-project  main 󰚩 claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +### Powerline 主题 + +vim-powerline 风格，带背景色和箭头分隔符： + +``` + 󰉋 my-project  main 󰚩 claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +通过在配置中设置 `currentStyle: "powerline"` 激活。 + +### 简单主题 + +回退主题，不带图标，适用于不支持 Nerd Font 的终端： + +``` +my-project main claude-3-5-sonnet-20241022 ↑ 12.3k ↓ 5.2k +``` + +当 `USE_SIMPLE_ICONS=true` 或在不支持的终端上自动使用。 + +## 可用模块 + +状态栏模块显示不同类型的信息： + +| 模块 | 说明 | 变量 | +|------|------|------| +| **workDir** | 当前工作目录名称 | `{{workDirName}}` | +| **gitBranch** | 当前 Git 分支 | `{{gitBranch}}` | +| **model** | 使用的模型 | `{{model}}` | +| **usage** | Token 使用情况（输入/输出） | `{{inputTokens}}`, `{{outputTokens}}` | +| **context** | 上下文窗口使用情况 | `{{contextPercent}}`, `{{contextWindowSize}}` | +| **speed** | Token 处理速度 | `{{tokenSpeed}}`, `{{isStreaming}}` | +| **cost** | API 成本 | `{{cost}}` | +| **duration** | 会话持续时间 | `{{duration}}` | +| **lines** | 代码变更 | `{{linesAdded}}`, `{{linesRemoved}}` | +| **script** | 自定义脚本输出 | 动态 | + +## 配置 + +在 `~/.claude-code-router/config.json` 中配置 statusline： + +### 默认样式示例 + +```json +{ + "StatusLine": { + "currentStyle": "default", + "default": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "model", + "icon": "󰚩", + "text": "{{model}}", + "color": "bright_cyan" + }, + { + "type": "usage", + "icon": "↑", + "text": "{{inputTokens}}", + "color": "bright_green" + }, + { + "type": "usage", + "icon": "↓", + "text": "{{outputTokens}}", + "color": "bright_yellow" + } + ] + } + } +} +``` + +### Powerline 样式示例 + +```json +{ + "StatusLine": { + "currentStyle": "powerline", + "powerline": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "white", + "background": "bg_bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "white", + "background": "bg_bright_magenta" + } + ] + } + } +} +``` + +### 完整功能示例 + +```json +{ + "StatusLine": { + "currentStyle": "default", + "default": { + "modules": [ + { + "type": "workDir", + "icon": "󰉋", + "text": "{{workDirName}}", + "color": "bright_blue" + }, + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "model", + "icon": "󰚩", + "text": "{{model}}", + "color": "bright_cyan" + }, + { + "type": "context", + "icon": "🪟", + "text": "{{contextPercent}}% / {{contextWindowSize}}", + "color": "bright_green" + }, + { + "type": "speed", + "icon": "⚡", + "text": "{{tokenSpeed}} t/s {{isStreaming}}", + "color": "bright_yellow" + }, + { + "type": "cost", + "icon": "💰", + "text": "{{cost}}", + "color": "bright_magenta" + }, + { + "type": "duration", + "icon": "⏱️", + "text": "{{duration}}", + "color": "bright_white" + }, + { + "type": "lines", + "icon": "📝", + "text": "+{{linesAdded}}/-{{linesRemoved}}", + "color": "bright_cyan" + } + ] + } + } +} +``` + +## 自定义脚本 + +您可以通过执行脚本创建自定义模块： + +```json +{ + "type": "script", + "icon": "🔧", + "scriptPath": "/path/to/script.js", + "options": { + "customOption": "value" + } +} +``` + +脚本格式（CommonJS）： + +```javascript +// my-status-module.js +module.exports = function(variables, options) { + // 访问变量如 model、gitBranch 等 + // 从配置中访问选项 + return `Custom: ${variables.model}`; +}; + +// 或异步 +module.exports = async function(variables, options) { + const data = await fetchSomeData(); + return data; +}; +``` + +## 颜色选项 + +### 标准颜色 + +- `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white` +- `bright_black`, `bright_red`, `bright_green`, `bright_yellow`, `bright_blue`, `bright_magenta`, `bright_cyan`, `bright_white` + +### 背景颜色 + +添加前缀 `bg_`：`bg_blue`, `bg_bright_red` 等。 + +### 十六进制颜色 + +使用 24 位 TrueColor 和十六进制代码： + +```json +{ + "color": "#FF5733", + "background": "bg_#1E90FF" +} +``` + +## 可用变量 + +所有变量都可以在模块文本中使用 `{{variableName}}` 访问： + +| 变量 | 说明 | 示例 | +|------|------|------| +| `{{workDirName}}` | 当前目录名称 | `my-project` | +| `{{gitBranch}}` | Git 分支名称 | `main` | +| `{{model}}` | 模型名称 | `claude-3-5-sonnet-20241022` | +| `{{inputTokens}}` | 输入 tokens（格式化） | `12.3k` | +| `{{outputTokens}}` | 输出 tokens（格式化） | `5.2k` | +| `{{tokenSpeed}}` | 每秒 tokens 数 | `45` | +| `{{isStreaming}}` | 流式传输状态 | `streaming` 或空 | +| `{{contextPercent}}` | 上下文使用百分比 | `45` | +| `{{contextWindowSize}}` | 总上下文窗口 | `200k` | +| `{{cost}}` | 总成本 | `$0.15` | +| `{{duration}}` | 会话持续时间 | `2m34s` | +| `{{linesAdded}}` | 添加的行数 | `150` | +| `{{linesRemoved}}` | 删除的行数 | `25` | +| `{{sessionId}}` | 会话 ID（前 8 个字符） | `a1b2c3d4` | + +## 环境变量 + +使用环境变量控制行为： + +| 变量 | 值 | 说明 | +|------|------|------| +| `USE_SIMPLE_ICONS` | `true`/`false` | 强制使用不带图标的简单主题 | +| `NERD_FONT` | 任意值 | 自动检测 Nerd Font 支持 | + +## 示例 + +### 极简状态栏 + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "model", + "text": "{{model}}" + }, + { + "type": "usage", + "text": "↑{{inputTokens}} ↓{{outputTokens}}" + } + ] + } + } +} +``` + +输出：`claude-3-5-sonnet-20241022 ↑12.3k ↓5.2k` + +### 开发者生产力重点 + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "gitBranch", + "icon": "", + "text": "{{gitBranch}}", + "color": "bright_magenta" + }, + { + "type": "lines", + "icon": "📝", + "text": "+{{linesAdded}}/-{{linesRemoved}}", + "color": "bright_cyan" + }, + { + "type": "duration", + "icon": "⏱️", + "text": "{{duration}}", + "color": "bright_white" + } + ] + } + } +} +``` + +输出：` feature/auth 📝 +150/-25 ⏱️ 2m34s` + +## Preset 集成 + +Statusline 主题可以包含在 presets 中。当您安装带有 statusline 配置的 preset 时，激活该 preset 时会自动应用。 + +查看 [Presets](/docs/server/advanced/presets) 了解更多信息。 + +## 故障排除 + +### 图标不显示 + +在环境中设置 `USE_SIMPLE_ICONS=true`： + +```bash +export USE_SIMPLE_ICONS=true +``` + +### 颜色不工作 + +确保您的终端支持 TrueColor（24 位颜色）： + +```bash +export COLORTERM=truecolor +``` + +### Git 分支不显示 + +确保您在 Git 仓库中并安装了 `git` 命令。 + +## 相关命令 + +- [ccr status](/docs/cli/commands/status) - 检查服务状态 +- [ccr preset](/docs/cli/commands/preset) - 管理带 statusline 主题的 presets diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/basic.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/basic.md new file mode 100644 index 0000000..710f2c8 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/basic.md @@ -0,0 +1,208 @@ +# CLI 基础配置 + +CLI 使用与 Server 相同的配置文件：`~/.claude-code-router/config.json` + +## 配置文件位置 + +```bash +~/.claude-code-router/config.json +``` + +## 快速配置 + +使用交互式命令配置： + +```bash +ccr model +``` + +这将引导你完成： +1. 选择 LLM 提供商 +2. 配置 API Key +3. 选择模型 +4. 设置路由规则 + +## 手动配置 + +### 编辑配置文件 + +```bash +# 打开配置文件 +nano ~/.claude-code-router/config.json +``` + +### 最小配置示例 + +```json5 +{ + // API 密钥（可选，用于保护服务） + "APIKEY": "your-api-key-here", + + // LLM 提供商 + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "$OPENAI_API_KEY", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + + // 默认路由 + "Router": { + "default": "openai,gpt-4" + } +} +``` + +## 环境变量 + +配置支持环境变量插值： + +```json5 +{ + "Providers": [ + { + "apiKey": "$OPENAI_API_KEY" // 从环境变量读取 + } + ] +} +``` + +在 `.bashrc` 或 `.zshrc` 中设置： + +```bash +export OPENAI_API_KEY="sk-..." +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +## 常用配置项 + +### HOST 和 PORT + +```json5 +{ + "HOST": "127.0.0.1", // 监听地址 + "PORT": 3456 // 监听端口 +} +``` + +### 日志配置 + +```json5 +{ + "LOG": true, // 启用日志 + "LOG_LEVEL": "info" // 日志级别 +} +``` + +### 路由配置 + +```json5 +{ + "Router": { + "default": "openai,gpt-4", + "background": "openai,gpt-3.5-turbo", + "think": "openai,gpt-4", + "longContext": "anthropic,claude-3-opus" + } +} +``` + +## 配置验证 + +配置文件会自动验证。常见错误： + +- **缺少 Providers**：必须至少配置一个提供商 +- **API Key 缺失**：如果配置了 Providers，必须提供 API Key +- **模型不存在**：确保模型在提供商的 models 列表中 + +## 配置备份 + +每次更新配置时会自动备份： + +``` +~/.claude-code-router/config.backup.{timestamp}.json +``` + +## 重新加载配置 + +修改配置后需要重启服务： + +```bash +ccr restart +``` + +## 查看当前配置 + +```bash +# 通过 API 查看 +curl http://localhost:3456/api/config + +# 或查看配置文件 +cat ~/.claude-code-router/config.json +``` + +## 示例配置 + +### OpenAI + +```json5 +{ + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "$OPENAI_API_KEY", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + "Router": { + "default": "openai,gpt-4" + } +} +``` + +### Anthropic + +```json5 +{ + "Providers": [ + { + "name": "anthropic", + "baseUrl": "https://api.anthropic.com/v1", + "apiKey": "$ANTHROPIC_API_KEY", + "models": ["claude-3-5-sonnet-20241022", "claude-3-opus-20240229"] + } + ], + "Router": { + "default": "anthropic,claude-3-5-sonnet-20241022" + } +} +``` + +### 多提供商 + +```json5 +{ + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "$OPENAI_API_KEY", + "models": ["gpt-4", "gpt-3.5-turbo"] + }, + { + "name": "anthropic", + "baseUrl": "https://api.anthropic.com/v1", + "apiKey": "$ANTHROPIC_API_KEY", + "models": ["claude-3-5-sonnet-20241022", "claude-3-opus-20240229"] + } + ], + "Router": { + "default": "openai,gpt-4", + "think": "anthropic,claude-3-5-sonnet-20241022", + "background": "openai,gpt-3.5-turbo" + } +} +``` diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/project-level.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/project-level.md new file mode 100644 index 0000000..9b2f402 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/config/project-level.md @@ -0,0 +1,213 @@ +# 项目级配置 + +除了全局配置，`ccr` 还支持为特定项目设置不同的路由规则。 + +## 项目配置文件 + +项目配置文件位于： + +``` +~/.claude/projects//claude-code-router.json +``` + +其中 `` 是 Claude Code 项目的唯一标识符。 + +## 项目配置结构 + +```json5 +{ + "Router": { + "default": "openai,gpt-4", + "background": "openai,gpt-3.5-turbo" + } +} +``` + +## 查找项目 ID + +### 方法一：使用 CLI + +```bash +# 在项目目录中运行 +ccr status +``` + +输出会显示当前项目 ID： + +``` +Project: my-project (abc123def456) +``` + +### 方法二：查看 Claude Code 配置 + +```bash +cat ~/.claude.json +``` + +找到你的项目 ID： + +```json +{ + "projects": { + "abc123def456": { + "path": "/path/to/your/project", + "name": "my-project" + } + } +} +``` + +## 创建项目配置 + +### 手动创建 + +```bash +# 创建项目配置目录 +mkdir -p ~/.claude/projects/abc123def456 + +# 创建配置文件 +cat > ~/.claude/projects/abc123def456/claude-code-router.json << 'EOF' +{ + "Router": { + "default": "anthropic,claude-3-5-sonnet-20241022", + "background": "openai,gpt-3.5-turbo" + } +} +EOF +``` + +### 使用 ccr model 命令 + +```bash +# 在项目目录中运行 +cd /path/to/your/project +ccr model --project +``` + +## 配置优先级 + +路由配置的优先级（从高到低）： + +1. **自定义路由函数** (`CUSTOM_ROUTER_PATH`) +2. **项目级配置** (`~/.claude/projects//claude-code-router.json`) +3. **全局配置** (`~/.claude-code-router/config.json`) +4. **内置路由规则** + +## 使用场景 + +### 场景一：不同项目使用不同模型 + +```json5 +// Web 项目使用 GPT-4 +~/.claude/projects/web-project-id/claude-code-router.json: +{ + "Router": { + "default": "openai,gpt-4" + } +} + +// AI 项目使用 Claude +~/.claude/projects/ai-project-id/claude-code-router.json: +{ + "Router": { + "default": "anthropic,claude-3-5-sonnet-20241022" + } +} +``` + +### 场景二：测试项目使用低成本模型 + +```json5 +~/.claude/projects/test-project-id/claude-code-router.json: +{ + "Router": { + "default": "openai,gpt-3.5-turbo", + "background": "openai,gpt-3.5-turbo" + } +} +``` + +### 场景三：长上下文项目 + +```json5 +~/.claude/projects/long-context-project-id/claude-code-router.json: +{ + "Router": { + "default": "anthropic,claude-3-opus-20240229", + "longContext": "anthropic,claude-3-opus-20240229" + } +} +``` + +## 验证项目配置 + +```bash +# 查看当前项目使用的路由 +ccr status + +# 查看日志确认路由决策 +tail -f ~/.claude-code-router/claude-code-router.log +``` + +## 删除项目配置 + +```bash +rm ~/.claude/projects//claude-code-router.json +``` + +删除后会回退到全局配置。 + +## 完整示例 + +假设你有两个项目： + +### 全局配置（`~/.claude-code-router/config.json`） + +```json5 +{ + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "$OPENAI_API_KEY", + "models": ["gpt-4", "gpt-3.5-turbo"] + }, + { + "name": "anthropic", + "baseUrl": "https://api.anthropic.com/v1", + "apiKey": "$ANTHROPIC_API_KEY", + "models": ["claude-3-5-sonnet-20241022"] + } + ], + "Router": { + "default": "openai,gpt-4", + "background": "openai,gpt-3.5-turbo" + } +} +``` + +### Web 项目配置 + +```json5 +{ + "Router": { + "default": "openai,gpt-4" + } +} +``` + +### AI 项目配置 + +```json5 +{ + "Router": { + "default": "anthropic,claude-3-5-sonnet-20241022", + "think": "anthropic,claude-3-5-sonnet-20241022" + } +} +``` + +这样： +- Web 项目使用 GPT-4 +- AI 项目使用 Claude +- 所有项目的后台任务使用 GPT-3.5-turbo（继承全局配置） diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/installation.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/installation.md new file mode 100644 index 0000000..6a9456d --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/installation.md @@ -0,0 +1,46 @@ +--- +title: 安装 +sidebar_position: 2 +--- + +# 安装 + +使用您喜欢的包管理器全局安装 Claude Code Router。 + +## 前置要求 + +- **Node.js**: >= 18.0.0 +- **pnpm**: >= 8.0.0（如果使用 pnpm） +- 来自您偏好的 LLM 提供商的 API 密钥 + +## 通过 npm 安装 + +```bash +npm install -g @musistudio/claude-code-router +``` + +## 通过 pnpm 安装 + +```bash +pnpm add -g @musistudio/claude-code-router +``` + +## 通过 Yarn 安装 + +```bash +yarn global add @musistudio/claude-code-router +``` + +## 验证安装 + +安装完成后，验证 `ccr` 命令是否可用： + +```bash +ccr --version +``` + +您应该看到版本号显示。 + +## 下一步 + +安装完成后，前往 [快速开始](/zh/docs/quick-start) 了解如何配置和使用路由器。 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/intro.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/intro.md new file mode 100644 index 0000000..b96e1b1 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/intro.md @@ -0,0 +1,70 @@ +--- +title: 欢迎使用 Claude Code Router +sidebar_position: 1 +slug: / +--- + +# 欢迎使用 Claude Code Router + +[![npm version](https://badge.fury.io/js/%40musistudio%2Fclaude-code-router.svg)](https://www.npmjs.com/package/@musistudio/claude-code-router) +![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) +![Node Version](https://img.shields.io/node/v/@musistudio/claude-code-router.svg) + +**Claude Code Router** 是一个强大的工具，允许你在没有 Anthropic 账户的情况下使用 [Claude Code](https://claude.ai/code)，并将请求路由到其他 LLM 提供商。 + +## 特性 + +- **多提供商支持**: 路由到 DeepSeek、Gemini、Groq、OpenRouter 等 +- **智能路由**: 内置不同任务类型的场景（后台、思考、网络搜索、图像） +- **项目级配置**: 每个项目自定义路由 +- **自定义路由函数**: 编写 JavaScript 定义自己的路由逻辑 +- **转换器系统**: 无缝适配不同提供商之间的 API 差异 +- **代理系统**: 可扩展的插件架构，实现自定义功能 +- **Web UI**: 内置管理界面，方便配置 +- **CLI 集成**: 与现有的 Claude Code 工作流无缝集成 + +## 快速开始 + +### 安装 + +```bash +npm install -g @musistudio/claude-code-router +# 或 +pnpm add -g @musistudio/claude-code-router +# 或 +yarn global add @musistudio/claude-code-router +``` + +### 基本使用 + +```bash +# 启动路由器服务器 +ccr start + +# 配置 Claude Code 使用路由器 +export ANTHROPIC_API_URL="http://localhost:8080/v1" +export ANTHROPIC_API_KEY="your-api-key" + +# 现在可以正常使用 Claude Code！ +claude code +``` + +## 下一步 + +- [安装指南](/docs/installation) - 详细安装说明 +- [快速开始](/docs/quick-start) - 5 分钟入门 +- [配置](/docs/config/basic) - 了解如何配置路由器 +- [CLI 参考](/docs/cli/start) - 完整的 CLI 命令参考 + +## 架构 + +Claude Code Router 由四个主要组件组成： + +- **CLI** (`@musistudio/claude-code-router`): 提供 `ccr` 命令的命令行工具 +- **Server** (`@CCR/server`): 处理 API 路由和转换的核心服务器 +- **Shared** (`@CCR/shared`): 共享常量和工具 +- **UI** (`@CCR/ui`): Web 管理界面（React + Vite） + +## 许可证 + +MIT © [musistudio](https://github.com/musistudio) diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/quick-start.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/quick-start.md new file mode 100644 index 0000000..605e2e0 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/cli/quick-start.md @@ -0,0 +1,82 @@ +--- +title: 快速开始 +sidebar_position: 3 +--- + +# 快速开始 + +5 分钟内启动并运行 Claude Code Router。 + +## 1. 启动路由器 + +```bash +ccr start +``` + +路由器默认将在 `http://localhost:8080` 上启动。 + +## 2. 配置环境变量 + +在您的 shell 中设置以下环境变量： + +```bash +export ANTHROPIC_API_URL="http://localhost:8080/v1" +export ANTHROPIC_API_KEY="your-provider-api-key" +``` + +或者使用 `ccr activate` 命令获取环境变量： + +```bash +eval "$(ccr activate)" +``` + +## 3. 使用 Claude Code + +现在您可以正常使用 Claude Code： + +```bash +claude code +``` + +您的请求将通过 Claude Code Router 路由到您配置的提供商。 + +## 4. 配置提供商（可选） + +要配置多个提供商或自定义路由，使用： + +```bash +ccr model +``` + +这将打开一个交互式菜单来选择和配置模型。 + +或者直接编辑配置文件： + +```bash +# 在默认编辑器中打开配置 +ccr config edit +``` + +配置文件示例 (`~/.claude-code-router/config.json`)： + +```json +{ + "Providers": [ + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "your-deepseek-api-key", + "models": ["deepseek-chat", "deepseek-coder"] + } + ], + "Router": { + "default": "deepseek,deepseek-chat" + } +} +``` + +## 下一步 + +- [基础配置](/zh/docs/config/basic) - 了解配置选项 +- [路由配置](/zh/docs/config/routing) - 配置智能路由规则 +- [CLI 命令](/zh/docs/cli/start) - 探索所有 CLI 命令 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/custom-router.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/custom-router.md new file mode 100644 index 0000000..48d3122 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/custom-router.md @@ -0,0 +1,148 @@ +--- +title: 自定义路由器 +sidebar_position: 1 +--- + +# 自定义路由器 + +使用 JavaScript 编写自己的路由逻辑。 + +## 创建自定义路由器 + +创建一个导出路由函数的 JavaScript 文件： + +```javascript +// custom-router.js +module.exports = async function(req, config) { + // 获取用户消息 + const userMessage = req.body.messages.find(m => m.role === 'user')?.content; + + // 自定义逻辑 + if (userMessage && userMessage.includes('解释代码')) { + return 'openrouter,anthropic/claude-3.5-sonnet'; + } + + // 返回 null 以使用默认路由 + return null; +}; +``` + +## 参数说明 + +路由函数接收以下参数： + +| 参数 | 类型 | 说明 | +|------|------|------| +| `req` | object | 来自 Claude Code 的请求对象，包含请求体 | +| `config` | object | 应用程序的配置对象 | + +## 配置 + +在 `config.json` 中设置 `CUSTOM_ROUTER_PATH` 以使用您的自定义路由器： + +```json +{ + "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js" +} +``` + +## 返回格式 + +路由函数应返回以下格式的字符串： + +``` +{provider-name},{model-name} +``` + +示例： + +``` +deepseek,deepseek-chat +``` + +如果返回 `null`，则回退到默认路由配置。 + +## 错误处理 + +如果路由函数抛出错误或返回无效格式，路由器将回退到默认路由配置。 + +## 示例：基于时间的路由 + +```javascript +module.exports = async function(req, config) { + const hour = new Date().getHours(); + + // 工作时间使用更快的模型 + if (hour >= 9 && hour <= 18) { + return 'groq,llama-3.3-70b-versatile'; + } + + // 非工作时间使用更强大的模型 + return 'deepseek,deepseek-chat'; +}; +``` + +## 示例：成本优化 + +```javascript +module.exports = async function(req, config) { + const userMessage = req.body.messages.find(m => m.role === 'user')?.content; + + // 简单任务使用较便宜的模型 + if (userMessage && userMessage.length < 100) { + return 'groq,llama-3.3-70b-versatile'; + } + + // 复杂任务使用默认模型 + return null; +}; +``` + +## 示例：任务类型路由 + +```javascript +module.exports = async function(req, config) { + const userMessage = req.body.messages.find(m => m.role === 'user')?.content; + + if (!userMessage) return null; + + // 代码相关任务 + if (userMessage.includes('代码') || userMessage.includes('code')) { + return 'deepseek,deepseek-coder'; + } + + // 解释任务 + if (userMessage.includes('解释') || userMessage.includes('explain')) { + return 'openrouter,anthropic/claude-3.5-sonnet'; + } + + // 默认 + return null; +}; +``` + +## 测试您的路由器 + +通过检查日志来测试您的自定义路由器： + +```bash +tail -f ~/.claude-code-router/claude-code-router.log +``` + +查找路由决策以查看正在选择哪个模型。 + +## 子代理路由 + +对于子代理内的路由，您必须在子代理提示词的**开头**包含 `provider,model` 来指定特定的提供商和模型。 + +**示例：** + +``` +openrouter,anthropic/claude-3.5-sonnet +请帮我分析这段代码是否存在潜在的优化空间... +``` + +## 下一步 + +- [Agent](/zh/docs/advanced/agents) - 使用 Agent 扩展功能 +- [预设](/zh/docs/advanced/presets) - 使用预定义配置 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/preset-format.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/preset-format.md new file mode 100644 index 0000000..a32fb41 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/preset-format.md @@ -0,0 +1,1197 @@ +--- +title: Preset 格式规范 +sidebar_position: 4 +--- + +# Preset 格式规范 + +本文档详细说明了 Preset 配置文件的格式规范、字段定义和使用方法。 + +## 概述 + +Preset 是一个预定义的配置包，用于快速配置 Claude Code Router。Preset 以目录形式存储，内部包含一个 `manifest.json` 文件。 + +### 文件结构 + +``` +~/.claude-code-router/presets// +└── manifest.json +``` + +### 存储位置 + +- **预设目录**: `~/.claude-code-router/presets//` + +## manifest.json 结构 + +`manifest.json` 是一个扁平化的 JSON 文件（支持 JSON5 格式），包含三个主要部分： + +1. **元数据（Metadata）**: 描述预设的基本信息 +2. **配置（Configuration）**: 实际的配置内容 +3. **动态配置系统**: Schema、Template 和 ConfigMappings + +```json +{ + // === 元数据字段 === + "name": "my-preset", + "version": "1.0.0", + "description": "我的预设配置", + "author": "作者名", + "homepage": "https://example.com", + "repository": "https://github.com/user/repo", + "license": "MIT", + "keywords": ["openai", "production"], + "ccrVersion": "2.0.0", + + // === 配置字段 === + "Providers": [...], + "Router": {...}, + "transformers": [...], + "StatusLine": {...}, + "PROXY_URL": "...", + "PORT": 8080, + + // === 动态配置系统 === + "schema": [...], + "template": {...}, + "configMappings": [...], + "requiredInputs": [...], + "userValues": {...} +} +``` + +## 元数据字段 + +### 必填字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | string | Preset 名称，唯一标识符 | +| `version` | string | 版本号（遵循 semver 规范） | + +### 可选字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `description` | string | Preset 描述 | +| `author` | string | 作者信息 | +| `homepage` | string | 项目主页 URL | +| `repository` | string | 源代码仓库 URL | +| `license` | string | 许可证类型 | +| `keywords` | string[] | 关键词标签 | +| `ccrVersion` | string | 兼容的 CCR 版本 | +| `source` | string | Preset 来源 URL | +| `sourceType` | string | 来源类型（`local`/`gist`/`registry`） | +| `checksum` | string | 内容校验和（SHA256） | + +### 元数据示例 + +```json +{ + "name": "openai-production", + "version": "1.2.0", + "description": "OpenAI 生产环境配置，包含代理和多模型支持", + "author": "Your Name", + "homepage": "https://github.com/yourname/ccr-presets", + "repository": "https://github.com/yourname/ccr-presets.git", + "license": "MIT", + "keywords": ["openai", "production", "proxy"], + "ccrVersion": "2.0.0" +} +``` + +## 配置字段 + +配置字段直接对应 CCR 的配置文件结构（`config.json`）。 + +### Providers + +Provider 配置数组，定义 LLM 服务提供商。 + +```json +{ + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"], + "transformer": "anthropic", + "timeout": 60000, + "max_retries": 3 + } + ] +} +``` + +#### Provider 字段说明 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | string | 是 | Provider 名称（唯一标识） | +| `api_base_url` | string | 是 | API 基础地址 | +| `api_key` | string | 是 | API 密钥（可以是环境变量） | +| `models` | string[] | 是 | 支持的模型列表 | +| `transformer` | string | 否 | 使用的转换器 | +| `timeout` | number | 否 | 超时时间（毫秒） | +| `max_retries` | number | 否 | 最大重试次数 | +| `headers` | object | 否 | 自定义 HTTP 头 | + +### Router + +路由配置，定义请求如何路由到不同的模型。 + +```json +{ + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini", + "think": "openai/gpt-4o", + "longContext": "openai/gpt-4o", + "longContextThreshold": 100000, + "webSearch": "openai/gpt-4o", + "image": "openai/gpt-4o" + } +} +``` + +#### Router 字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `default` | string | 默认路由（格式：`provider/model`） | +| `background` | string | 后台任务路由 | +| `think` | string | 思考模式路由 | +| `longContext` | string | 长上下文路由 | +| `longContextThreshold` | number | 长上下文阈值（token 数） | +| `webSearch` | string | 网络搜索路由 | +| `image` | string | 图像处理路由 | + +### Transformers + +转换器配置数组，用于处理不同 Provider 的 API 差异。 + +```json +{ + "transformers": [ + { + "path": "./transformers/custom-transformer.js", + "use": ["provider1", "provider2"], + "options": { + "max_tokens": 4096 + } + }, + { + "use": [ + ["provider3", { "option": "value" }] + ] + } + ] +} +``` + +#### Transformer 字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `path` | string | 自定义转换器路径（相对或绝对） | +| `use` | array | 应用到哪些 Provider | +| `options` | object | 转换器选项 | + +### StatusLine + +状态栏配置，自定义终端状态显示。 + +```json +{ + "StatusLine": { + "default": { + "modules": [ + { + "type": "text", + "text": "CCR", + "color": "cyan" + }, + { + "type": "provider", + "showModel": true + }, + { + "type": "script", + "scriptPath": "./scripts/status.js" + } + ] + } + } +} +``` + +### 其他配置字段 + +支持所有 `config.json` 中的字段： + +```json +{ + "PORT": 8080, + "HOST": "0.0.0.0", + "PROXY_URL": "http://127.0.0.1:7890", + "LOG_LEVEL": "info", + "NON_INTERACTIVE_MODE": false +} +``` + +## 动态配置系统 + +动态配置系统是 CCR 2.0 的核心功能，允许创建可交互的配置模板。 + +### Schema（配置输入表单） + +Schema 定义了安装时需要用户输入的字段。 + +#### Schema 字段类型 + +| 类型 | 说明 | 使用场景 | +|------|------|----------| +| `password` | 密码输入（隐藏） | API Key、密钥 | +| `input` | 单行文本输入 | URL、名称 | +| `number` | 数字输入 | 端口号、超时时间 | +| `select` | 单选下拉框 | 选择 Provider、模型 | +| `multiselect` | 多选框 | 启用功能列表 | +| `confirm` | 确认框 | 是否启用某功能 | +| `editor` | 多行文本编辑器 | 自定义配置、脚本 | + +#### Schema 字段定义 + +```json +{ + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的 OpenAI API Key", + "placeholder": "sk-...", + "required": true, + "validator": "^sk-.*" + }, + { + "id": "provider", + "type": "select", + "label": "选择 Provider", + "prompt": "选择您主要使用的 LLM 提供商", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "使用 OpenAI 的 GPT 模型" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "使用 DeepSeek 的高性价比模型" + } + ] + }, + "defaultValue": "openai", + "required": true + }, + { + "id": "model", + "type": "select", + "label": "模型", + "prompt": "选择默认使用的模型", + "options": { + "type": "models", + "providerField": "#{provider}" + }, + "when": { + "field": "provider", + "operator": "exists" + }, + "required": true + }, + { + "id": "maxTokens", + "type": "number", + "label": "最大 Token 数", + "prompt": "设置请求的最大 token 数", + "min": 1, + "max": 128000, + "defaultValue": 4096 + }, + { + "id": "useProxy", + "type": "confirm", + "label": "使用代理", + "prompt": "是否通过代理访问 API？", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "prompt": "输入代理服务器地址", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "useProxy", + "operator": "eq", + "value": true + } + }, + { + "id": "customConfig", + "type": "editor", + "label": "自定义配置", + "prompt": "输入 JSON 格式的自定义配置", + "rows": 10 + } + ] +} +``` + +#### Schema 字段详细说明 + +##### 基础字段 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `id` | string | 是 | 字段唯一标识符（用于变量引用） | +| `type` | string | 否 | 字段类型（默认 `password`） | +| `label` | string | 否 | 显示标签 | +| `prompt` | string | 否 | 提示信息/描述 | +| `placeholder` | string | 否 | 占位符文本 | + +##### 验证字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `required` | boolean | 是否必填（默认 `true`） | +| `validator` | RegExp/string/function | 验证规则 | +| `min` | number | 最小值（number 类型） | +| `max` | number | 最大值（number 类型） | + +##### 选项字段（select/multiselect） + +| 字段 | 类型 | 说明 | +|------|------|------| +| `options` | array/object | 静态选项数组或动态选项配置 | + +##### 条件字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `when` | object/object[] | 显示条件（支持 AND 逻辑） | +| `defaultValue` | any | 默认值 | +| `dependsOn` | string[] | 显式声明依赖字段 | + +#### 条件运算符 + +| 运算符 | 说明 | 示例 | +|--------|------|------| +| `eq` | 等于 | `{"field": "type", "operator": "eq", "value": "openai"}` | +| `ne` | 不等于 | `{"field": "advanced", "operator": "ne", "value": true}` | +| `in` | 包含于（数组） | `{"field": "feature", "operator": "in", "value": ["a", "b"]}` | +| `nin` | 不包含于（数组） | `{"field": "type", "operator": "nin", "value": ["x", "y"]}` | +| `exists` | 字段存在 | `{"field": "apiKey", "operator": "exists"}` | +| `gt` | 大于 | `{"field": "count", "operator": "gt", "value": 0}` | +| `lt` | 小于 | `{"field": "count", "operator": "lt", "value": 100}` | +| `gte` | 大于等于 | `{"field": "count", "operator": "gte", "value": 1}` | +| `lte` | 小于等于 | `{"field": "count", "operator": "lte", "value": 99}` | + +#### 动态选项类型 + +##### static - 静态选项 + +```json +{ + "options": { + "type": "static", + "options": [ + {"label": "选项1", "value": "value1"}, + {"label": "选项2", "value": "value2"} + ] + } +} +``` + +##### providers - 从 Providers 配置提取 + +```json +{ + "options": { + "type": "providers" + } +} +``` +自动从 `Providers` 数组中提取 `name` 作为选项。 + +##### models - 从指定 Provider 的 models 提取 + +```json +{ + "options": { + "type": "models", + "providerField": "#{selectedProvider}" + } +} +``` +根据用户选择的 Provider，动态显示该 Provider 的 models。 + +### Template（配置模板） + +Template 定义了如何根据用户输入生成配置。 + +#### 变量语法 + +使用 `#{变量名}` 语法引用用户输入： + +```json +{ + "template": { + "Providers": [ + { + "name": "#{providerName}", + "api_base_url": "#{baseUrl}", + "api_key": "#{apiKey}", + "models": ["#{defaultModel}"] + } + ], + "Router": { + "default": "#{providerName}/#{defaultModel}" + } + } +} +``` + +#### Template 示例 + +```json +{ + "template": { + "Providers": [ + { + "name": "#{primaryProvider}", + "api_base_url": "#{baseUrl}", + "api_key": "#{apiKey}", + "models": ["#{defaultModel}"], + "timeout": #{timeout} + } + ], + "Router": { + "default": "#{primaryProvider}/#{defaultModel}", + "background": "#{primaryProvider}/#{backgroundModel}" + }, + "PROXY_URL": "#{proxyUrl}", + "PORT": #{port} + } +} +``` + +### ConfigMappings（配置映射） + +ConfigMappings 用于精确控制用户输入值如何映射到配置的特定位置。 + +#### ConfigMapping 结构 + +```json +{ + "configMappings": [ + { + "target": "Providers[0].api_key", + "value": "#{apiKey}" + }, + { + "target": "PROXY_URL", + "value": "#{proxyUrl}", + "when": { + "field": "useProxy", + "operator": "eq", + "value": true + } + }, + { + "target": "PORT", + "value": 8080 + } + ] +} +``` + +#### 字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `target` | string | 目标字段路径（支持数组语法） | +| `value` | string/any | 值来源（变量引用或固定值） | +| `when` | object/object[] | 应用条件 | + +#### 目标路径语法 + +- `Providers[0].api_key` - 第一个 Provider 的 api_key +- `Router.default` - Router 的 default 字段 +- `PORT` - 顶层配置字段 + +### userValues（用户值存储） + +userValues 存储用户在安装时填写的值，运行时自动应用。 + +```json +{ + "userValues": { + "apiKey": "sk-xxx...", + "provider": "openai", + "defaultModel": "gpt-4o", + "useProxy": true, + "proxyUrl": "http://127.0.0.1:7890" + } +} +``` + +### requiredInputs（必填输入） + +requiredInputs 是导出预设时自动生成的字段列表，用于提示用户需要填写哪些信息。 + +```json +{ + "requiredInputs": [ + { + "id": "Providers[0].api_key", + "prompt": "Enter api_key", + "placeholder": "OPENAI_API_KEY" + }, + { + "id": "PROXY_URL", + "prompt": "Enter proxy URL", + "placeholder": "PROXY_URL" + } + ] +} +``` + +## 敏感字段处理 + +CCR 会自动识别敏感字段（如 `api_key`、`secret`、`password` 等），并将其替换为环境变量占位符。 + +### 自动识别的敏感字段 + +- `api_key`, `apiKey`, `apikey` +- `api_secret`, `apiSecret` +- `secret`, `SECRET` +- `token`, `TOKEN` +- `password`, `PASSWORD` +- `private_key`, `privateKey` +- `access_key`, `accessKey` + +### 环境变量占位符格式 + +```bash +# 推荐格式 +${VARIABLE_NAME} + +# 也支持 +$VARIABLE_NAME +``` + +### 示例 + +**原始配置:** +```json +{ + "Providers": [ + { + "name": "openai", + "api_key": "sk-abc123..." + } + ] +} +``` + +**导出后:** +```json +{ + "Providers": [ + { + "name": "openai", + "api_key": "${OPENAI_API_KEY}" + } + ], + "requiredInputs": [ + { + "id": "Providers[0].api_key", + "prompt": "Enter api_key", + "placeholder": "OPENAI_API_KEY" + } + ] +} +``` + +## 完整示例 + +### 简单预设（无动态配置） + +```json +{ + "name": "simple-openai", + "version": "1.0.0", + "description": "简单的 OpenAI 配置", + "author": "Your Name", + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + + "requiredInputs": [ + { + "id": "Providers[0].api_key", + "prompt": "Enter OpenAI API Key", + "placeholder": "OPENAI_API_KEY" + } + ] +} +``` + +### 高级预设（动态配置） + +```json +{ + "name": "multi-provider-advanced", + "version": "2.0.0", + "description": "多 Provider 高级配置，支持动态选择和代理", + "author": "Your Name", + "keywords": ["openai", "deepseek", "proxy", "multi-provider"], + "ccrVersion": "2.0.0", + + "schema": [ + { + "id": "primaryProvider", + "type": "select", + "label": "主要 Provider", + "prompt": "选择您主要使用的 LLM 提供商", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "使用 OpenAI 的 GPT 模型，质量高" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "使用 DeepSeek 的高性价比模型" + } + ] + }, + "required": true, + "defaultValue": "openai" + }, + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的 API Key", + "placeholder": "sk-...", + "required": true, + "validator": "^sk-.+" + }, + { + "id": "defaultModel", + "type": "select", + "label": "默认模型", + "prompt": "选择默认使用的模型", + "options": { + "type": "static", + "options": [ + {"label": "GPT-4o", "value": "gpt-4o"}, + {"label": "GPT-4o-mini", "value": "gpt-4o-mini"} + ] + }, + "required": true, + "defaultValue": "gpt-4o", + "when": { + "field": "primaryProvider", + "operator": "eq", + "value": "openai" + } + }, + { + "id": "backgroundModel", + "type": "select", + "label": "后台任务模型", + "prompt": "选择用于后台任务的轻量级模型", + "options": { + "type": "static", + "options": [ + {"label": "GPT-4o-mini", "value": "gpt-4o-mini"} + ] + }, + "required": true, + "defaultValue": "gpt-4o-mini", + "when": { + "field": "primaryProvider", + "operator": "eq", + "value": "openai" + } + }, + { + "id": "maxTokens", + "type": "number", + "label": "最大 Token 数", + "prompt": "设置单次请求的最大 token 数", + "min": 1, + "max": 128000, + "defaultValue": 4096 + }, + { + "id": "timeout", + "type": "number", + "label": "超时时间（秒）", + "prompt": "设置 API 请求超时时间", + "min": 10, + "max": 300, + "defaultValue": 60 + }, + { + "id": "enableProxy", + "type": "confirm", + "label": "启用代理", + "prompt": "是否通过代理访问 API？", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "prompt": "输入代理服务器地址", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + }, + "validator": "^https?://.+" + }, + { + "id": "features", + "type": "multiselect", + "label": "启用功能", + "prompt": "选择要启用的额外功能", + "options": { + "type": "static", + "options": [ + {"label": "长上下文支持", "value": "longContext"}, + {"label": "网络搜索", "value": "webSearch"}, + {"label": "图像处理", "value": "image"} + ] + }, + "defaultValue": [] + } + ], + + "template": { + "Providers": [ + { + "name": "#{primaryProvider}", + "api_base_url": "#{primaryProvider === 'openai' ? 'https://api.openai.com/v1' : 'https://api.deepseek.com'}", + "api_key": "#{apiKey}", + "models": [ + "#{defaultModel}", + "#{backgroundModel}" + ], + "timeout": #{timeout * 1000} + } + ], + "Router": { + "default": "#{primaryProvider}/#{defaultModel}", + "background": "#{primaryProvider}/#{backgroundModel}" + }, + "NON_INTERACTIVE_MODE": false + }, + + "configMappings": [ + { + "target": "PROXY_URL", + "value": "#{proxyUrl}", + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + }, + { + "target": "Router.longContext", + "value": "#{primaryProvider}/#{defaultModel}", + "when": { + "field": "features", + "operator": "in", + "value": ["longContext"] + } + }, + { + "target": "Router.webSearch", + "value": "#{primaryProvider}/#{defaultModel}", + "when": { + "field": "features", + "operator": "in", + "value": ["webSearch"] + } + }, + { + "target": "Router.image", + "value": "#{primaryProvider}/#{defaultModel}", + "when": { + "field": "features", + "operator": "in", + "value": ["image"] + } + } + ] +} +``` + +## 验证规则 + +### Preset 验证检查项 + +1. **元数据验证** + - ✓ `name` 字段存在 + - ✓ `version` 字段存在（警告） + +2. **配置验证** + - ✓ `config` 部分存在 + - ✓ 每个 Provider 有 `name` 字段 + - ✓ 每个 Provider 有 `api_base_url` 字段 + - ✓ 每个 Provider 有 `models` 数组（警告） + +3. **Schema 验证** + - ✓ 字段 `id` 唯一 + - ✓ 条件字段引用存在 + - ✓ 动态选项配置正确 + +### 错误和警告 + +**错误（Error）:** +- 缺少必填字段 +- Provider 配置不完整 +- Schema 字段重复 + +**警告（Warning）:** +- 缺少可选字段 +- Provider 没有 models +- 未使用的 schema 字段 + +## 最佳实践 + +### 1. 使用动态配置系统 + +```json +{ + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "required": true + } + ], + "template": { + "Providers": [ + { + "api_key": "#{apiKey}" + } + ] + } +} +``` + +### 2. 提供合理的默认值 + +```json +{ + "id": "timeout", + "type": "number", + "label": "超时时间", + "defaultValue": 60, + "min": 10, + "max": 300 +} +``` + +### 3. 使用条件显示减少不必要的输入 + +```json +{ + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "when": { + "field": "useProxy", + "operator": "eq", + "value": true + } +} +``` + +### 4. 清晰的标签和提示 + +```json +{ + "id": "apiKey", + "type": "password", + "label": "OpenAI API Key", + "prompt": "请输入您的 OpenAI API Key（以 sk- 开头）", + "placeholder": "sk-...", + "validator": "^sk-.+" +} +``` + +### 5. 使用验证确保数据质量 + +```json +{ + "id": "port", + "type": "number", + "label": "端口号", + "min": 1024, + "max": 65535, + "validator": (value) => { + if (value < 1024 || value > 65535) { + return "端口号必须在 1024-65535 之间"; + } + return true; + } +} +``` + +### 6. 版本控制 + +遵循 semver 规范： +- `1.0.0` - 初始版本 +- `1.1.0` - 新增功能（向后兼容） +- `1.0.1` - Bug 修复 +- `2.0.0` - 破坏性变更 + +### 7. 文档化 + +```json +{ + "name": "my-preset", + "version": "1.0.0", + "description": "详细的预设描述，说明用途和特点", + "author": "作者名 ", + "homepage": "https://github.com/user/preset", + "repository": "https://github.com/user/preset.git", + "keywords": ["openai", "production", "proxy"], + "license": "MIT" +} +``` + +### 8. 使用相对路径 + +对于预设中的自定义文件（如转换器、脚本），使用相对路径： + +```json +{ + "transformers": [ + { + "path": "./transformers/custom.js" + } + ], + "StatusLine": { + "default": { + "modules": [ + { + "type": "script", + "scriptPath": "./scripts/status.js" + } + ] + } + } +} +``` + +相对路径会在安装时自动转换为绝对路径。 + +## 导出和导入 + +### 导出当前配置 + +```bash +ccr preset export my-preset +``` + +可选项： + +```bash +ccr preset export my-preset \ + --description "我的预设" \ + --author "Your Name" \ + --tags "openai,production" +``` + +### 安装预设 + +**CLI 方式：** + +```bash +# 从本地目录安装 +ccr preset install /path/to/preset + +# 重新配置已安装的预设 +ccr preset install my-preset +``` + +:::note 注意 +CLI 方式**不支持**从 URL 安装。如需从 GitHub 安装，请使用 Web UI 或先克隆到本地。 +::: + +**Web UI 方式：** + +1. 访问 Web UI：`ccr ui` +2. 点击"预设商城"按钮 +3. 选择预设或输入 GitHub 仓库 URL +4. 点击安装 + +### 管理预设 + +```bash +# 列出所有预设 +ccr preset list + +# 查看预设信息 +ccr preset info my-preset + +# 删除预设 +ccr preset delete my-preset +``` + +## 常见问题 + +### Q: 如何处理多个 Provider？ + +A: 在 template 中定义多个 Provider，使用条件逻辑： + +```json +{ + "schema": [ + { + "id": "useSecondary", + "type": "confirm", + "label": "启用备用 Provider" + }, + { + "id": "secondaryKey", + "type": "password", + "label": "备用 API Key", + "when": { + "field": "useSecondary", + "operator": "eq", + "value": true + } + } + ], + "template": { + "Providers": [ + { + "name": "primary", + "api_key": "#{primaryKey}" + }, + { + "name": "secondary", + "api_key": "#{secondaryKey}" + } + ] + }, + "configMappings": [ + { + "target": "Providers", + "value": [ + { + "name": "primary", + "api_key": "#{primaryKey}" + } + ], + "when": { + "field": "useSecondary", + "operator": "ne", + "value": true + } + } + ] +} +``` + +### Q: 如何支持条件配置？ + +A: 使用 `when` 条件和 `configMappings`： + +```json +{ + "configMappings": [ + { + "target": "PROXY_URL", + "value": "#{proxyUrl}", + "when": { + "field": "useProxy", + "operator": "eq", + "value": true + } + } + ] +} +``` + +### Q: 如何验证用户输入？ + +A: 使用 `validator` 字段： + +```json +{ + "id": "url", + "type": "input", + "label": "API 地址", + "validator": "^https?://.+" +} +``` + +### Q: 如何创建多语言预设？ + +A: 使用条件选择语言： + +```json +{ + "schema": [ + { + "id": "language", + "type": "select", + "label": "语言", + "options": [ + {"label": "中文", "value": "zh"}, + {"label": "English", "value": "en"} + ] + } + ] +} +``` + +## 相关文档 + +- [预设配置使用指南](/zh/docs/advanced/presets) +- [配置基础](/zh/docs/config/basic) +- [Provider 配置](/zh/docs/config/providers) +- [路由配置](/zh/docs/config/routing) +- [转换器配置](/zh/docs/config/transformers) diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/presets.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/presets.md new file mode 100644 index 0000000..3c0cd02 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/advanced/presets.md @@ -0,0 +1,672 @@ +--- +title: 预设配置 +sidebar_position: 3 +--- + +# 预设配置 + +使用预定义配置进行快速设置。 + +## 什么是预设？ + +预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。 + +## 使用预设 + +### CLI 方式（命令行） + +CLI 方式适合开发者通过命令行快速操作。 + +#### 安装预设 + +**从本地目录安装：** + +```bash +ccr preset install /path/to/preset-directory +``` + +**重新配置已安装的预设：** + +```bash +ccr preset install my-preset +``` + +:::note 注意 +CLI 方式**不支持**从 URL 直接安装预设。如需从 GitHub 安装，请先克隆到本地或使用 Web UI。 +::: + +#### 使用预设 + +安装预设后，可以使用预设名称启动 Claude Code： + +```bash +# 使用指定预设启动 +ccr my-preset "your prompt" + +# 后台任务使用预设 +ccr my-preset --background "your prompt" +``` + +预设会： +- 自动加载预配置的 Provider +- 应用预设的路由规则 +- 使用预设中配置的 transformer + +#### 列出所有预设 + +```bash +ccr preset list +``` + +此命令将显示所有已安装的预设及其名称、版本和描述。 + +#### 查看预设信息 + +```bash +ccr preset info my-preset +``` + +#### 删除预设 + +```bash +ccr preset delete my-preset +``` + +### Web UI 方式 + +Web UI 提供更友好的可视化界面，支持更多安装方式。 + +#### 访问 Web UI + +```bash +ccr ui +``` + +然后在浏览器中打开 `http://localhost:3000` + +#### 从 GitHub 仓库安装 + +1. 点击"预设商城"按钮 +2. 在预设列表中选择要安装的预设 +3. 点击"安装"按钮 + +或手动输入 GitHub 仓库地址： + +``` +格式：https://github.com/username/repo +示例：https://github.com/example/ccr-presets +``` + +#### 重新配置预设 + +1. 在预设列表中点击"查看详情"按钮 +2. 在详情页面中修改配置项 +3. 点击"应用"保存配置 + +#### 管理预设 + +- **查看**：点击预设右侧的信息图标 +- **删除**：点击预设右侧的删除图标 + +## 创建自定义预设 + +### 预设目录结构 + +预设以目录形式存储，每个预设包含以下结构： + +``` +~/.claude-code-router/presets// +├── manifest.json # 必填：预设配置文件 +├── transformers/ # 可选：自定义转换器 +│ └── custom-transformer.js +├── scripts/ # 可选：自定义脚本 +│ └── status.js +└── README.md # 可选：说明文档 +``` + +### 动态配置系统 + +CCR 引入了强大的动态配置系统，支持： + +- **多种输入类型**：选择器、多选、确认框、文本输入、数字输入等 +- **条件逻辑**：根据用户输入动态显示/隐藏配置项 +- **变量引用**：配置项之间可以互相引用 +- **动态选项**：选项列表可以从预设配置或用户输入中动态生成 + +#### Schema 字段类型 + +| 类型 | 说明 | 示例 | +|------|------|------| +| `password` | 密码输入（隐藏显示） | API Key | +| `input` | 单行文本输入 | Base URL | +| `number` | 数字输入 | 最大Token数 | +| `select` | 单选下拉框 | 选择Provider | +| `multiselect` | 多选框 | 启用功能 | +| `confirm` | 确认框 | 是否使用代理 | +| `editor` | 多行文本编辑器 | 自定义配置 | + +#### 条件运算符 + +| 运算符 | 说明 | 示例 | +|--------|------|------| +| `eq` | 等于 | `{"field": "provider", "operator": "eq", "value": "openai"}` | +| `ne` | 不等于 | `{"field": "advanced", "operator": "ne", "value": true}` | +| `in` | 包含于 | `{"field": "feature", "operator": "in", "value": ["a", "b"]}` | +| `nin` | 不包含于 | `{"field": "type", "operator": "nin", "value": ["x", "y"]}` | +| `exists` | 字段存在 | `{"field": "apiKey", "operator": "exists"}` | +| `gt/lt/gte/lte` | 大于/小于/大于等于/小于等于 | 用于数字比较 | + +#### 动态选项类型 + +##### static - 静态选项 +```json +"options": { + "type": "static", + "options": [ + {"label": "选项1", "value": "value1"}, + {"label": "选项2", "value": "value2"} + ] +} +``` + +##### providers - 从 Providers 配置提取 +```json +"options": { + "type": "providers" +} +``` +自动从 `Providers` 数组中提取 name 作为选项。 + +##### models - 从指定 Provider 的 models 提取 +```json +"options": { + "type": "models", + "providerField": "{{selectedProvider}}" +} +``` +根据用户选择的 Provider，动态显示该 Provider 的 models。 + +#### 模板变量 + +使用 `{{变量名}}` 语法在 template 中引用用户输入： + +```json +"template": { + "Providers": [ + { + "name": "{{providerName}}", + "api_key": "{{apiKey}}" + } + ] +} +``` + +#### 配置映射 + +对于复杂的配置需求，使用 `configMappings` 精确控制值的位置： + +```json +"configMappings": [ + { + "target": "Providers[0].api_key", + "value": "{{apiKey}}" + }, + { + "target": "PROXY_URL", + "value": "{{proxyUrl}}", + "when": { + "field": "useProxy", + "operator": "eq", + "value": true + } + } +] +``` + +#### 完整示例 + +```json +{ + "name": "multi-provider-example", + "version": "1.0.0", + "description": "多Provider配置示例 - 支持OpenAI和DeepSeek切换", + "author": "CCR Team", + "keywords": ["openai", "deepseek", "multi-provider"], + "ccrVersion": "2.0.0", + "schema": [ + { + "id": "primaryProvider", + "type": "select", + "label": "主要Provider", + "prompt": "选择您主要使用的LLM提供商", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "使用OpenAI的GPT模型" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "使用DeepSeek的高性价比模型" + } + ] + }, + "required": true, + "defaultValue": "openai" + }, + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的API Key", + "placeholder": "sk-...", + "required": true + }, + { + "id": "defaultModel", + "type": "select", + "label": "默认模型", + "prompt": "选择默认使用的模型", + "options": { + "type": "static", + "options": [ + {"label": "GPT-4o", "value": "gpt-4o"}, + {"label": "GPT-4o-mini", "value": "gpt-4o-mini"} + ] + }, + "required": true, + "defaultValue": "gpt-4o", + "when": { + "field": "primaryProvider", + "operator": "eq", + "value": "openai" + } + }, + { + "id": "enableProxy", + "type": "confirm", + "label": "启用代理", + "prompt": "是否通过代理访问API？", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "prompt": "输入代理服务器地址", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ], + "template": { + "Providers": [ + { + "name": "{{primaryProvider}}", + "api_base_url": "https://api.openai.com/v1", + "api_key": "{{apiKey}}", + "models": ["{{defaultModel}}"] + } + ], + "Router": { + "default": "{{primaryProvider}}/{{defaultModel}}" + }, + "PROXY_URL": "{{proxyUrl}}" + }, + "configMappings": [ + { + "target": "PROXY_URL", + "value": "{{proxyUrl}}", + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ] +} +``` + +### manifest.json 完整字段说明 + +`manifest.json` 是预设的核心配置文件，使用 JSON5 格式（支持注释）。 + +#### 1. 元数据字段（Metadata） + +这些字段用于描述预设的基本信息： + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | string | ✓ | 预设名称（唯一标识符） | +| `version` | string | ✓ | 版本号（遵循 semver 规范） | +| `description` | string | - | 预设描述 | +| `author` | string | - | 作者信息 | +| `homepage` | string | - | 项目主页 URL | +| `repository` | string | - | 源代码仓库 URL | +| `license` | string | - | 许可证类型 | +| `keywords` | string[] | - | 关键词标签 | +| `ccrVersion` | string | - | 兼容的 CCR 版本 | +| `source` | string | - | 预设来源 URL | +| `sourceType` | string | - | 来源类型（`local`/`gist`/`registry`） | +| `checksum` | string | - | 内容校验和（SHA256） | + +示例： + +```json +{ + "name": "my-preset", + "version": "1.0.0", + "description": "我的自定义预设", + "author": "Your Name", + "homepage": "https://github.com/yourname/ccr-presets", + "repository": "https://github.com/yourname/ccr-presets.git", + "license": "MIT", + "keywords": ["openai", "production"], + "ccrVersion": "2.0.0" +} +``` + +#### 2. 配置字段（Configuration） + +这些字段会直接合并到 CCR 的配置中，所有 `config.json` 支持的字段都可以在这里使用： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `Providers` | array | Provider 配置数组 | +| `Router` | object | 路由配置 | +| `transformers` | array | 转换器配置 | +| `StatusLine` | object | 状态栏配置 | + +示例： + +```json +{ + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + "PORT": 8080 +} +``` + +#### 3. 动态配置系统字段 + +这些字段用于创建可交互的配置模板： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `schema` | array | 配置输入表单定义 | +| `template` | object | 配置模板（使用变量引用） | +| `configMappings` | array | 配置映射规则 | +| `userValues` | object | 用户填写的值（运行时使用） | +| `requiredInputs` | array | 必填输入项列表（自动生成） | + +**schema 字段类型：** + +| 类型 | 说明 | 使用场景 | +|------|------|----------| +| `password` | 密码输入（隐藏） | API Key | +| `input` | 单行文本输入 | URL | +| `number` | 数字输入 | 端口号 | +| `select` | 单选下拉框 | 选择 Provider | +| `multiselect` | 多选框 | 启用功能 | +| `confirm` | 确认框 | 是否启用 | +| `editor` | 多行文本编辑器 | 自定义配置 | + +动态配置示例： + +```json +{ + "schema": [ + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的 API Key", + "required": true + }, + { + "id": "provider", + "type": "select", + "label": "Provider", + "options": { + "type": "static", + "options": [ + {"label": "OpenAI", "value": "openai"}, + {"label": "DeepSeek", "value": "deepseek"} + ] + }, + "defaultValue": "openai" + } + ], + "template": { + "Providers": [ + { + "name": "#{provider}", + "api_key": "#{apiKey}" + } + ] + } +} +``` + +### 创建预设示例 + +#### 示例 1：简单预设（无动态配置） + +```bash +# 创建预设目录 +mkdir -p ~/.claude-code-router/presets/simple-openai + +# 创建 manifest.json +cat > ~/.claude-code-router/presets/simple-openai/manifest.json << 'EOF' +{ + "name": "simple-openai", + "version": "1.0.0", + "description": "简单的 OpenAI 配置", + "author": "Your Name", + + "Providers": [ + { + "name": "openai", + "api_base_url": "https://api.openai.com/v1", + "api_key": "${OPENAI_API_KEY}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + + "Router": { + "default": "openai/gpt-4o", + "background": "openai/gpt-4o-mini" + }, + + "requiredInputs": [ + { + "id": "Providers[0].api_key", + "prompt": "Enter OpenAI API Key", + "placeholder": "OPENAI_API_KEY" + } + ] +} +EOF + +# 配置预设（输入 API Key） +ccr preset install simple-openai + +# 使用预设 +ccr simple-openai "your prompt" +``` + +#### 示例 2：高级预设（动态配置） + +```bash +# 创建预设目录 +mkdir -p ~/.claude-code-router/presets/advanced-config + +# 创建 manifest.json +cat > ~/.claude-code-router/presets/advanced-config/manifest.json << 'EOF' +{ + "name": "advanced-config", + "version": "1.0.0", + "description": "支持多 Provider 选择的高级配置", + "author": "Your Name", + "keywords": ["openai", "deepseek", "multi-provider"], + + "schema": [ + { + "id": "provider", + "type": "select", + "label": "选择 Provider", + "prompt": "选择您主要使用的 LLM 提供商", + "options": { + "type": "static", + "options": [ + { + "label": "OpenAI", + "value": "openai", + "description": "使用 OpenAI 的 GPT 模型" + }, + { + "label": "DeepSeek", + "value": "deepseek", + "description": "使用 DeepSeek 的高性价比模型" + } + ] + }, + "defaultValue": "openai", + "required": true + }, + { + "id": "apiKey", + "type": "password", + "label": "API Key", + "prompt": "请输入您的 API Key", + "placeholder": "sk-...", + "required": true + }, + { + "id": "enableProxy", + "type": "confirm", + "label": "启用代理", + "prompt": "是否通过代理访问 API？", + "defaultValue": false + }, + { + "id": "proxyUrl", + "type": "input", + "label": "代理地址", + "prompt": "输入代理服务器地址", + "placeholder": "http://127.0.0.1:7890", + "required": true, + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ], + + "template": { + "Providers": [ + { + "name": "#{provider}", + "api_base_url": "#{provider === 'openai' ? 'https://api.openai.com/v1' : 'https://api.deepseek.com'}", + "api_key": "#{apiKey}", + "models": ["gpt-4o", "gpt-4o-mini"] + } + ], + "Router": { + "default": "#{provider}/gpt-4o", + "background": "#{provider}/gpt-4o-mini" + } + }, + + "configMappings": [ + { + "target": "PROXY_URL", + "value": "#{proxyUrl}", + "when": { + "field": "enableProxy", + "operator": "eq", + "value": true + } + } + ] +} +EOF + +# 配置预设（会提示输入） +ccr preset install advanced-config + +# 使用预设 +ccr advanced-config "your prompt" +``` + +### 导出当前配置为预设 + +如果您已经配置好了 CCR，可以导出当前配置： + +```bash +# 导出当前配置 +ccr preset export my-exported-preset +``` + +导出时会自动： +- 识别敏感字段（如 `api_key`）并替换为环境变量占位符 +- 生成 `schema` 用于收集用户输入 +- 生成 `template` 和 `configMappings` + +可选项： + +```bash +ccr preset export my-exported-preset \ + --description "导出的配置" \ + --author "Your Name" \ + --tags "production,openai" +``` + +:::tip 分享预设 +导出的预设目录可以直接分享给他人。接收者可以： +- **CLI 方式**：将目录放到 `~/.claude-code-router/presets/`，然后运行 `ccr preset install 预设名` +- **Web UI 方式**：将目录上传到 GitHub，然后通过仓库 URL 安装 +::: + +## 预设文件位置 + +预设保存在： + +``` +~/.claude-code-router/presets/ +``` + +每个预设都是一个目录，包含 `manifest.json` 文件。 + +## 最佳实践 + +1. **使用动态配置**：为需要用户输入的配置项使用schema系统 +2. **提供默认值**：为非必填项提供合理的默认值 +3. **条件显示**：使用when条件避免不必要的输入 +4. **清晰的标签**：为每个字段提供清晰的label和prompt +5. **验证输入**：使用validator确保输入的有效性 +6. **版本控制**：将常用预设保存在版本控制中 +7. **文档化**：为自定义预设添加描述和版本信息 + +## 下一步 + +- [CLI 参考](/zh/docs/cli/start) - 完整的 CLI 命令参考 +- [配置](/zh/docs/config/basic) - 详细配置指南 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/config-api.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/config-api.md new file mode 100644 index 0000000..e0baf88 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/config-api.md @@ -0,0 +1,220 @@ +# 配置 API + +## GET /api/config + +获取当前服务器配置。 + +### 请求示例 + +```bash +curl http://localhost:3456/api/config \ + -H "x-api-key: your-api-key" +``` + +### 响应示例 + +```json +{ + "HOST": "0.0.0.0", + "PORT": 3456, + "APIKEY": "sk-xxxxx", + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "sk-...", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + "Router": { + "default": "openai,gpt-4" + }, + "transformers": [ + "anthropic" + ] +} +``` + +## POST /api/config + +更新服务器配置。更新后会自动备份旧配置。 + +### 请求示例 + +```bash +curl -X POST http://localhost:3456/api/config \ + -H "x-api-key: your-api-key" \ + -H "content-type: application/json" \ + -d '{ + "HOST": "0.0.0.0", + "PORT": 3456, + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "$OPENAI_API_KEY", + "models": ["gpt-4"] + } + ], + "Router": { + "default": "openai,gpt-4" + } + }' +``` + +### 配置对象结构 + +#### 基础配置 + +| 字段 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `HOST` | string | 否 | 监听地址（默认 127.0.0.1） | +| `PORT` | integer | 否 | 监听端口（默认 3456） | +| `APIKEY` | string | 否 | API 密钥 | +| `LOG` | boolean | 否 | 是否启用日志（默认 true） | +| `LOG_LEVEL` | string | 否 | 日志级别（debug/info/warn/error） | + +#### Providers 配置 + +```json +{ + "Providers": [ + { + "name": "provider-name", + "baseUrl": "https://api.example.com/v1", + "apiKey": "your-api-key", + "models": ["model-1", "model-2"] + } + ] +} +``` + +| 字段 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `name` | string | 是 | 提供商名称 | +| `baseUrl` | string | 是 | API 基础 URL | +| `apiKey` | string | 是 | API 密钥 | +| `models` | array | 是 | 支持的模型列表 | + +#### Router 配置 + +```json +{ + "Router": { + "default": "provider,model", + "longContextThreshold": 100000, + "routes": { + "background": "lightweight-model", + "think": "powerful-model", + "longContext": "long-context-model", + "webSearch": "search-model", + "image": "vision-model" + } + } +} +``` + +#### Transformers 配置 + +```json +{ + "transformers": [ + { + "name": "anthropic", + "provider": "provider-name", + "models": ["model-1"], + "options": {} + } + ] +} +``` + +### 响应示例 + +成功： + +```json +{ + "success": true, + "message": "Config saved successfully" +} +``` + +### 配置备份 + +每次更新配置时，旧配置会自动备份到： + +``` +~/.claude-code-router/config.backup.{timestamp}.json +``` + +保留最近 3 个备份。 + +## GET /api/transformers + +获取服务器加载的所有转换器列表。 + +### 请求示例 + +```bash +curl http://localhost:3456/api/transformers \ + -H "x-api-key: your-api-key" +``` + +### 响应示例 + +```json +{ + "transformers": [ + { + "name": "anthropic", + "endpoint": null + }, + { + "name": "openai", + "endpoint": null + }, + { + "name": "gemini", + "endpoint": "https://generativelanguage.googleapis.com" + } + ] +} +``` + +### 转换器列表 + +内置转换器： + +- `anthropic` - Anthropic Claude 格式 +- `openai` - OpenAI 格式 +- `deepseek` - DeepSeek 格式 +- `gemini` - Google Gemini 格式 +- `openrouter` - OpenRouter 格式 +- `groq` - Groq 格式 +- `maxtoken` - 调整 max_tokens 参数 +- `tooluse` - 工具使用转换 +- `reasoning` - 推理模式转换 +- `enhancetool` - 增强工具功能 + +## 环境变量插值 + +配置支持环境变量插值： + +```json +{ + "Providers": [ + { + "apiKey": "$OPENAI_API_KEY" + } + ] +} +``` + +或使用 `${VAR_NAME}` 格式： + +```json +{ + "baseUrl": "${API_BASE_URL}" +} +``` diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/logs-api.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/logs-api.md new file mode 100644 index 0000000..c66cbfb --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/logs-api.md @@ -0,0 +1,166 @@ +# 日志 API + +## GET /api/logs/files + +获取所有可用的日志文件列表。 + +### 请求示例 + +```bash +curl http://localhost:3456/api/logs/files \ + -H "x-api-key: your-api-key" +``` + +### 响应示例 + +```json +[ + { + "name": "ccr-20241226143022.log", + "path": "/home/user/.claude-code-router/logs/ccr-20241226143022.log", + "size": 1024000, + "lastModified": "2024-12-26T14:30:22.000Z" + }, + { + "name": "ccr-20241226143021.log", + "path": "/home/user/.claude-code-router/logs/ccr-20241226143021.log", + "size": 980000, + "lastModified": "2024-12-26T14:30:21.000Z" + } +] +``` + +### 字段说明 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `name` | string | 文件名 | +| `path` | string | 完整文件路径 | +| `size` | integer | 文件大小（字节） | +| `lastModified` | string | 最后修改时间（ISO 8601） | + +文件按修改时间倒序排列。 + +## GET /api/logs + +获取指定日志文件的内容。 + +### 查询参数 + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `file` | string | 否 | 日志文件路径（默认使用 app.log） | + +### 请求示例（获取默认日志） + +```bash +curl "http://localhost:3456/api/logs" \ + -H "x-api-key: your-api-key" +``` + +### 请求示例（获取指定文件） + +```bash +curl "http://localhost:3456/api/logs?file=/home/user/.claude-code-router/logs/ccr-20241226143022.log" \ + -H "x-api-key: your-api-key" +``` + +### 响应示例 + +```json +[ + "{\"level\":30,\"time\":1703550622000,\"pid\":12345,\"hostname\":\"server\",\"msg\":\"Incoming request\",\"req\":{\"id\":1,\"method\":\"POST\",\"url\":\"/v1/messages\",\"remoteAddress\":\"127.0.0.1\"}}", + "{\"level\":30,\"time\":1703550622500,\"pid\":12345,\"hostname\":\"server\",\"msg\":\"Request completed\",\"res\":{\"statusCode\":200,\"responseTime\":500}}", + "..." +] +``` + +返回的是日志行数组，每行是一个 JSON 字符串。 + +### 日志格式 + +日志使用 Pino 格式： + +```json +{ + "level": 30, + "time": 1703550622000, + "pid": 12345, + "hostname": "server", + "msg": "Incoming request", + "req": { + "id": 1, + "method": "POST", + "url": "/v1/messages", + "remoteAddress": "127.0.0.1" + } +} +``` + +### 日志级别 + +| 级别 | 值 | 说明 | +|------|------|------| +| `trace` | 10 | 最详细的日志 | +| `debug` | 20 | 调试信息 | +| `info` | 30 | 一般信息 | +| `warn` | 40 | 警告信息 | +| `error` | 50 | 错误信息 | +| `fatal` | 60 | 致命错误 | + +## DELETE /api/logs + +清除指定日志文件的内容。 + +### 查询参数 + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `file` | string | 否 | 日志文件路径（默认使用 app.log） | + +### 请求示例（清除默认日志） + +```bash +curl -X DELETE "http://localhost:3456/api/logs" \ + -H "x-api-key: your-api-key" +``` + +### 请求示例（清除指定文件） + +```bash +curl -X DELETE "http://localhost:3456/api/logs?file=/home/user/.claude-code-router/logs/ccr-20241226143022.log" \ + -H "x-api-key: your-api-key" +``` + +### 响应示例 + +```json +{ + "success": true, + "message": "Logs cleared successfully" +} +``` + +## 日志位置 + +### 服务器日志 + +位置：`~/.claude-code-router/logs/` + +文件命名：`ccr-{YYYYMMDD}{HH}{MM}{SS}.log` + +内容：HTTP 请求、API 调用、服务器事件 + +### 应用日志 + +位置：`~/.claude-code-router/claude-code-router.log` + +内容：路由决策、业务逻辑事件 + +## 日志轮转 + +服务器日志使用 rotating-file-stream 自动轮转： + +- **maxFiles**: 3 - 保留最近 3 个日志文件 +- **interval**: 1d - 每天轮转 +- **maxSize**: 50M - 单个文件最大 50MB diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/messages-api.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/messages-api.md new file mode 100644 index 0000000..c5ffcd2 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/messages-api.md @@ -0,0 +1,220 @@ +# 消息 API + +## POST /v1/messages + +发送消息到 LLM，兼容 Anthropic Claude API 格式。 + +### 请求格式 + +```bash +curl -X POST http://localhost:3456/v1/messages \ + -H "x-api-key: your-api-key" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-3-5-sonnet-20241022", + "max_tokens": 1024, + "messages": [ + { + "role": "user", + "content": "Hello, Claude!" + } + ] + }' +``` + +### 请求参数 + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `model` | string | 是 | 模型名称（会被路由到实际提供商） | +| `messages` | array | 是 | 消息数组 | +| `max_tokens` | integer | 是 | 最大生成 Token 数 | +| `system` | string | 否 | 系统提示词 | +| `tools` | array | 否 | 可用工具列表 | +| `stream` | boolean | 否 | 是否使用流式响应（默认 false） | +| `temperature` | number | 否 | 温度参数（0-1） | + +### 消息对象格式 + +```json +{ + "role": "user|assistant", + "content": "string | array" +} +``` + +### 响应格式（非流式） + +```json +{ + "id": "msg_xxx", + "type": "message", + "role": "assistant", + "content": [ + { + "type": "text", + "text": "Hello! How can I help you today?" + } + ], + "model": "claude-3-5-sonnet-20241022", + "stop_reason": "end_turn", + "usage": { + "input_tokens": 10, + "output_tokens": 20 + } +} +``` + +### 流式响应 + +设置 `stream: true` 启用流式响应： + +```json +{ + "model": "claude-3-5-sonnet-20241022", + "max_tokens": 1024, + "messages": [...], + "stream": true +} +``` + +流式响应事件类型： + +- `message_start` - 消息开始 +- `content_block_start` - 内容块开始 +- `content_block_delta` - 内容增量 +- `content_block_stop` - 内容块结束 +- `message_delta` - 消息元数据（usage） +- `message_stop` - 消息结束 + +### 工具使用 + +支持函数调用（Tool Use）： + +```json +{ + "model": "claude-3-5-sonnet-20241022", + "max_tokens": 1024, + "messages": [ + { + "role": "user", + "content": "What's the weather like?" + } + ], + "tools": [ + { + "name": "get_weather", + "description": "Get the current weather", + "input_schema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City name" + } + }, + "required": ["location"] + } + } + ] +} +``` + +### 多模态支持 + +支持图片输入： + +```json +{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": "iVBORw0KGgo..." + } + }, + { + "type": "text", + "text": "Describe this image" + } + ] +} +``` + +## POST /v1/messages/count_tokens + +计算消息的 Token 数量。 + +### 请求格式 + +```bash +curl -X POST http://localhost:3456/v1/messages/count_tokens \ + -H "x-api-key: your-api-key" \ + -H "content-type: application/json" \ + -d '{ + "model": "claude-3-5-sonnet-20241022", + "messages": [ + { + "role": "user", + "content": "Hello!" + } + ], + "tools": [], + "system": "You are a helpful assistant." + }' +``` + +### 请求参数 + +| 参数 | 类型 | 必需 | 说明 | +|------|------|------|------| +| `model` | string | 是 | 模型名称 | +| `messages` | array | 是 | 消息数组 | +| `tools` | array | 否 | 工具列表 | +| `system` | string | 否 | 系统提示词 | + +### 响应格式 + +```json +{ + "input_tokens": 42 +} +``` + +## 错误响应 + +### 400 Bad Request + +```json +{ + "error": { + "type": "invalid_request_error", + "message": "messages is required" + } +} +``` + +### 401 Unauthorized + +```json +{ + "error": { + "type": "authentication_error", + "message": "Invalid API key" + } +} +``` + +### 500 Internal Server Error + +```json +{ + "error": { + "type": "api_error", + "message": "Failed to connect to provider" + } +} +``` diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/overview.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/overview.md new file mode 100644 index 0000000..31f46f0 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/api/overview.md @@ -0,0 +1,88 @@ +# API 概览 + +Claude Code Router Server 提供了完整的 HTTP API，支持： + +- **消息 API**：兼容 Anthropic Claude API 的消息接口 +- **配置 API**：读取和更新服务器配置 +- **日志 API**：查看和管理服务日志 +- **工具 API**：计算 Token 数量 + +## 基础信息 + +**Base URL**: `http://localhost:3456` + +**认证方式**: API Key（通过 `x-api-key` 请求头） + +```bash +curl -H "x-api-key: your-api-key" http://localhost:3456/api/config +``` + +## API 端点列表 + +### 消息相关 + +| 端点 | 方法 | 描述 | +|------|------|------| +| `/v1/messages` | POST | 发送消息（兼容 Anthropic API） | +| `/v1/messages/count_tokens` | POST | 计算消息的 Token 数量 | + +### 配置管理 + +| 端点 | 方法 | 描述 | +|------|------|------| +| `/api/config` | GET | 获取当前配置 | +| `/api/config` | POST | 更新配置 | +| `/api/transformers` | GET | 获取可用的转换器列表 | + +### 日志管理 + +| 端点 | 方法 | 描述 | +|------|------|------| +| `/api/logs/files` | GET | 获取日志文件列表 | +| `/api/logs` | GET | 获取日志内容 | +| `/api/logs` | DELETE | 清除日志 | + +### 服务管理 + +| 端点 | 方法 | 描述 | +|------|------|------| +| `/api/restart` | POST | 重启服务 | +| `/ui` | GET | Web 管理界面 | +| `/ui/` | GET | Web 管理界面（重定向） | + +## 认证 + +### API Key 认证 + +在请求头中添加 API Key： + +```bash +curl -X POST http://localhost:3456/v1/messages \ + -H "x-api-key: your-api-key" \ + -H "content-type: application/json" \ + -d '...' +``` + +## 流式响应 + +消息 API 支持流式响应（Server-Sent Events）： + +```bash +curl -X POST http://localhost:3456/v1/messages \ + -H "x-api-key: your-api-key" \ + -H "content-type: application/json" \ + -d '{"stream": true, ...}' +``` + +流式响应格式： + +``` +event: message_start +data: {"type":"message_start","message":{...}} + +event: content_block_delta +data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}} + +event: message_stop +data: {"type":"message_stop"} +``` diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/basic.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/basic.md new file mode 100644 index 0000000..e457766 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/basic.md @@ -0,0 +1,160 @@ +--- +title: 基础配置 +sidebar_position: 1 +--- + +# 基础配置 + +学习如何配置 Claude Code Router 以满足您的需求。 + +## 配置文件位置 + +配置文件位于： + +``` +~/.claude-code-router/config.json +``` + +## 配置结构 + +### Providers（提供商） + +配置 LLM 提供商以将请求路由到： + +```json +{ + "Providers": [ + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "your-api-key", + "models": ["deepseek-chat", "deepseek-coder"] + }, + { + "name": "groq", + "api_base_url": "https://api.groq.com/openai/v1/chat/completions", + "api_key": "your-groq-api-key", + "models": ["llama-3.3-70b-versatile"] + } + ] +} +``` + +### Router（路由器） + +配置默认使用的模型： + +```json +{ + "Router": { + "default": "deepseek,deepseek-chat" + } +} +``` + +格式：`{provider-name},{model-name}` + +### Transformers（转换器） + +对请求/响应应用转换： + +```json +{ + "transformers": [ + { + "path": "/path/to/custom-transformer.js", + "options": { + "key": "value" + } + } + ] +} +``` + +### 环境变量 + +在配置中使用环境变量： + +```json +{ + "Providers": [ + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "$DEEPSEEK_API_KEY" + } + ] +} +``` + +同时支持 `$VAR_NAME` 和 `${VAR_NAME}` 语法。 + +## 完整示例 + +```json +{ + "PORT": 8080, + "APIKEY": "your-secret-key", + "PROXY_URL": "http://127.0.0.1:7890", + "LOG": true, + "LOG_LEVEL": "debug", + "API_TIMEOUT_MS": 600000, + "Providers": [ + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "$DEEPSEEK_API_KEY", + "models": ["deepseek-chat", "deepseek-coder"], + "transformer": { + "use": ["deepseek"] + } + }, + { + "name": "groq", + "api_base_url": "https://api.groq.com/openai/v1/chat/completions", + "api_key": "$GROQ_API_KEY", + "models": ["llama-3.3-70b-versatile"] + } + ], + "Router": { + "default": "deepseek,deepseek-chat", + "longContextThreshold": 100000, + "background": "groq,llama-3.3-70b-versatile" + } +} +``` + +## 编辑配置 + +使用 CLI 编辑配置： + +```bash +ccr config edit +``` + +这将在您的默认编辑器中打开配置文件。 + +## 重新加载配置 + +编辑配置后，重启路由器： + +```bash +ccr restart +``` + +## 配置选项说明 + +- **PORT**: 服务器端口号（默认：3456） +- **APIKEY**: API 密钥，用于身份验证 +- **HOST**: 服务器监听地址（默认：127.0.0.1，如果配置了 Providers 且没有设置 APIKEY，则强制为 127.0.0.1） +- **PROXY_URL**: 代理服务器地址 +- **LOG**: 是否启用日志（默认：true） +- **LOG_LEVEL**: 日志级别（fatal/error/warn/info/debug/trace） +- **API_TIMEOUT_MS**: API 请求超时时间（毫秒） +- **NON_INTERACTIVE_MODE**: 非交互模式（用于 CI/CD 环境） + +## 下一步 + +- [提供商配置](/zh/docs/config/providers) - 详细的提供商配置 +- [路由配置](/zh/docs/config/routing) - 配置路由规则 +- [转换器](/zh/docs/config/transformers) - 应用转换 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/providers.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/providers.md new file mode 100644 index 0000000..4374fd9 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/providers.md @@ -0,0 +1,212 @@ +--- +title: 提供商配置 +sidebar_position: 2 +--- + +# 提供商配置 + +配置 LLM 提供商的详细指南。 + +## 支持的提供商 + +### DeepSeek + +```json +{ + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "your-api-key", + "models": ["deepseek-chat", "deepseek-coder", "deepseek-reasoner"], + "transformer": { + "use": ["deepseek"] + } +} +``` + +### Groq + +```json +{ + "name": "groq", + "api_base_url": "https://api.groq.com/openai/v1/chat/completions", + "api_key": "your-api-key", + "models": ["llama-3.3-70b-versatile"] +} +``` + +### Gemini + +```json +{ + "name": "gemini", + "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/", + "api_key": "your-api-key", + "models": ["gemini-2.5-flash", "gemini-2.5-pro"], + "transformer": { + "use": ["gemini"] + } +} +``` + +### OpenRouter + +```json +{ + "name": "openrouter", + "api_base_url": "https://openrouter.ai/api/v1/chat/completions", + "api_key": "your-api-key", + "models": [ + "anthropic/claude-3.5-sonnet", + "google/gemini-2.5-pro-preview" + ], + "transformer": { + "use": ["openrouter"] + } +} +``` + +### Ollama（本地模型） + +```json +{ + "name": "ollama", + "api_base_url": "http://localhost:11434/v1/chat/completions", + "api_key": "ollama", + "models": ["qwen2.5-coder:latest"] +} +``` + +### 火山引擎 + +```json +{ + "name": "volcengine", + "api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions", + "api_key": "your-api-key", + "models": ["deepseek-v3-250324", "deepseek-r1-250528"], + "transformer": { + "use": ["deepseek"] + } +} +``` + +### ModelScope + +```json +{ + "name": "modelscope", + "api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions", + "api_key": "", + "models": [ + "Qwen/Qwen3-Coder-480B-A35B-Instruct", + "Qwen/Qwen3-235B-A22B-Thinking-2507" + ], + "transformer": { + "use": [ + ["maxtoken", { "max_tokens": 65536 }], + "enhancetool" + ], + "Qwen/Qwen3-235B-A22B-Thinking-2507": { + "use": ["reasoning"] + } + } +} +``` + +### DashScope（阿里云） + +```json +{ + "name": "dashscope", + "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions", + "api_key": "your-api-key", + "models": ["qwen3-coder-plus"], + "transformer": { + "use": [ + ["maxtoken", { "max_tokens": 65536 }], + "enhancetool" + ] + } +} +``` + +## 提供商配置选项 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|------|------| +| `name` | string | 是 | 提供商的唯一标识符 | +| `api_base_url` | string | 是 | API 基础 URL | +| `api_key` | string | 是 | API 认证密钥 | +| `models` | string[] | 否 | 可用模型列表 | +| `transformer` | object | 否 | 应用的转换器配置 | + +## 模型选择 + +在路由中选择模型时，使用以下格式： + +``` +{provider-name},{model-name} +``` + +例如： + +``` +deepseek,deepseek-chat +``` + +## 使用环境变量 + +您可以在配置中使用环境变量来保护 API 密钥： + +```json +{ + "Providers": [ + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "$DEEPSEEK_API_KEY", + "models": ["deepseek-chat"] + } + ] +} +``` + +支持 `$VAR_NAME` 和 `${VAR_NAME}` 两种语法。 + +## 转换器配置 + +转换器用于适配不同提供商的 API 差异。您可以在提供商级别或模型级别配置转换器： + +### 提供商级别转换器 + +应用于提供商的所有模型： + +```json +{ + "name": "openrouter", + "transformer": { + "use": ["openrouter"] + } +} +``` + +### 模型级别转换器 + +应用于特定模型： + +```json +{ + "name": "deepseek", + "transformer": { + "use": ["deepseek"], + "deepseek-chat": { + "use": ["tooluse"] + } + } +} +``` + +## 下一步 + +- [路由配置](/zh/docs/config/routing) - 配置请求如何路由 +- [转换器](/zh/docs/config/transformers) - 对请求应用转换 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/routing.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/routing.md new file mode 100644 index 0000000..e5280ed --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/routing.md @@ -0,0 +1,164 @@ +--- +title: 路由配置 +sidebar_position: 3 +--- + +# 路由配置 + +配置如何将请求路由到不同的模型。 + +## 默认路由 + +为所有请求设置默认模型： + +```json +{ + "Router": { + "default": "deepseek,deepseek-chat" + } +} +``` + +## 内置场景 + +### 后台任务 + +将后台任务路由到轻量级模型： + +```json +{ + "Router": { + "background": "groq,llama-3.3-70b-versatile" + } +} +``` + +### 思考模式（计划模式） + +将思考密集型任务路由到更强大的模型： + +```json +{ + "Router": { + "think": "deepseek,deepseek-reasoner" + } +} +``` + +### 长上下文 + +路由长上下文请求： + +```json +{ + "Router": { + "longContextThreshold": 100000, + "longContext": "gemini,gemini-2.5-pro" + } +} +``` + +### 网络搜索 + +路由网络搜索任务： + +```json +{ + "Router": { + "webSearch": "gemini,gemini-2.5-flash" + } +} +``` + +### 图像任务 + +路由图像相关任务： + +```json +{ + "Router": { + "image": "gemini,gemini-2.5-pro" + } +} +``` + +## 项目级路由 + +在 `~/.claude/projects//claude-code-router.json` 中为每个项目配置路由： + +```json +{ + "Router": { + "default": "groq,llama-3.3-70b-versatile" + } +} +``` + +项目级配置优先于全局配置。 + +## 自定义路由器 + +创建自定义 JavaScript 路由器函数： + +1. 创建路由器文件（例如 `custom-router.js`）： + +```javascript +module.exports = async function(req, config) { + // 分析请求上下文 + const userMessage = req.body.messages.find(m => m.role === 'user')?.content; + + // 自定义路由逻辑 + if (userMessage && userMessage.includes('解释代码')) { + return 'openrouter,anthropic/claude-3.5-sonnet'; + } + + // 返回 null 以使用默认路由 + return null; +}; +``` + +2. 在 `config.json` 中设置 `CUSTOM_ROUTER_PATH`： + +```json +{ + "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js" +} +``` + +## Token 计数 + +路由器使用 `tiktoken` (cl100k_base) 来估算请求 token 数量。这用于： + +- 确定请求是否超过 `longContextThreshold` +- 基于 token 数量的自定义路由逻辑 + +## 子代理路由 + +使用特殊标签为子代理指定模型： + +``` +provider,model +请帮我分析这段代码... +``` + +## 动态模型切换 + +在 Claude Code 中使用 `/model` 命令动态切换模型： + +``` +/model provider_name,model_name +``` + +示例：`/model openrouter,anthropic/claude-3.5-sonnet` + +## 路由优先级 + +1. 项目级配置 +2. 自定义路由器 +3. 内置场景路由 +4. 默认路由 + +## 下一步 + +- [转换器](/zh/docs/config/transformers) - 对请求应用转换 +- [自定义路由器](/zh/docs/advanced/custom-router) - 高级自定义路由 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/transformers.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/transformers.md new file mode 100644 index 0000000..0f08fc1 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/transformers.md @@ -0,0 +1,282 @@ +--- +title: 转换器 +sidebar_position: 4 +--- + +# 转换器 + +转换器用于适配不同提供商之间的 API 差异。 + +## 内置转换器 + +### anthropic + +将请求转换为兼容 Anthropic 风格的 API： + +```json +{ + "transformer": { + "use": ["anthropic"] + } +} +``` + +如果只使用这一个转换器，它将直接透传请求和响应（您可以用来接入其他支持 Anthropic 端点的服务商）。 + +### deepseek + +专门用于 DeepSeek API 的转换器： + +```json +{ + "transformer": { + "use": ["deepseek"] + } +} +``` + +### gemini + +用于 Google Gemini API 的转换器： + +```json +{ + "transformer": { + "use": ["gemini"] + } +} +``` + +### groq + +用于 Groq API 的转换器： + +```json +{ + "transformer": { + "use": ["groq"] + } +} +``` + +### openrouter + +用于 OpenRouter API 的转换器： + +```json +{ + "transformer": { + "use": ["openrouter"] + } +} +``` + +OpenRouter 转换器还支持 `provider` 路由参数，以指定 OpenRouter 应使用哪些底层提供商： + +```json +{ + "transformer": { + "use": ["openrouter"], + "moonshotai/kimi-k2": { + "use": [ + ["openrouter", { + "provider": { + "only": ["moonshotai/fp8"] + } + }] + ] + } + } +} +``` + +### maxtoken + +设置特定的 `max_tokens` 值： + +```json +{ + "transformer": { + "use": [ + ["maxtoken", { "max_tokens": 65536 }] + ] + } +} +``` + +### tooluse + +通过 `tool_choice` 参数优化某些模型的工具使用： + +```json +{ + "transformer": { + "use": ["tooluse"] + } +} +``` + +### reasoning + +用于处理 `reasoning_content` 字段： + +```json +{ + "transformer": { + "use": ["reasoning"] + } +} +``` + +### sampling + +用于处理采样信息字段，如 `temperature`、`top_p`、`top_k` 和 `repetition_penalty`： + +```json +{ + "transformer": { + "use": ["sampling"] + } +} +``` + +### enhancetool + +对 LLM 返回的工具调用参数增加一层容错处理（注意：这会导致不再流式返回工具调用信息）： + +```json +{ + "transformer": { + "use": ["enhancetool"] + } +} +``` + +### cleancache + +清除请求中的 `cache_control` 字段： + +```json +{ + "transformer": { + "use": ["cleancache"] + } +} +``` + +### vertex-gemini + +处理使用 Vertex 鉴权的 Gemini API： + +```json +{ + "transformer": { + "use": ["vertex-gemini"] + } +} +``` + +## 应用转换器 + +### 全局应用 + +应用于提供商的所有请求： + +```json +{ + "Providers": [ + { + "name": "deepseek", + "api_base_url": "https://api.deepseek.com/chat/completions", + "api_key": "your-api-key", + "transformer": { + "use": ["deepseek"] + } + } + ] +} +``` + +### 模型特定应用 + +应用于特定模型： + +```json +{ + "name": "deepseek", + "transformer": { + "use": ["deepseek"], + "deepseek-chat": { + "use": ["tooluse"] + } + } +} +``` + +### 传递选项 + +某些转换器接受选项： + +```json +{ + "transformer": { + "use": [ + ["maxtoken", { "max_tokens": 8192 }] + ] + } +} +``` + +## 自定义转换器 + +创建自定义转换器插件： + +1. 创建转换器文件： + +```javascript +module.exports = { + name: 'my-transformer', + transformRequest: async (req, config) => { + // 修改请求 + return req; + }, + transformResponse: async (res, config) => { + // 修改响应 + return res; + } +}; +``` + +2. 在配置中加载： + +```json +{ + "transformers": [ + { + "path": "/path/to/transformer.js", + "options": { + "key": "value" + } + } + ] +} +``` + +## 实验性转换器 + +### gemini-cli（实验性） + +通过 Gemini CLI 对 Gemini 的非官方支持。 + +### qwen-cli（实验性） + +通过 Qwen CLI 对 qwen3-coder-plus 的非官方支持。 + +### rovo-cli（实验性） + +通过 Atlassian Rovo Dev CLI 对 GPT-5 的非官方支持。 + +## 下一步 + +- [高级主题](/zh/docs/advanced/custom-router) - 高级路由自定义 +- [Agent](/zh/docs/advanced/agents) - 使用 Agent 扩展功能 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/deployment.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/deployment.md new file mode 100644 index 0000000..dde5e65 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/deployment.md @@ -0,0 +1,182 @@ +# Server 部署 + +Claude Code Router Server 支持多种部署方式，从本地开发到生产环境。 + +## Docker 部署（推荐） + +### 使用 Docker Hub 镜像 + +```bash +docker run -d \ + --name claude-code-router \ + -p 3456:3456 \ + -v ~/.claude-code-router:/app/.claude-code-router \ + musistudio/claude-code-router:latest +``` + +### 使用 Docker Compose + +创建 `docker-compose.yml`： + +```yaml +version: '3.8' +services: + claude-code-router: + image: musistudio/claude-code-router:latest + container_name: claude-code-router + ports: + - "3456:3456" + volumes: + - ./config:/app/.claude-code-router + environment: + - LOG_LEVEL=info + - HOST=0.0.0.0 + - PORT=3456 + restart: unless-stopped +``` + +启动服务： + +```bash +docker-compose up -d +``` + +### 自定义构建 + +从源码构建 Docker 镜像： + +```bash +git clone https://github.com/musistudio/claude-code-router.git +cd claude-code-router +docker build -t claude-code-router:latest . +``` + +## 配置文件挂载 + +将配置文件挂载到容器中： + +```bash +docker run -d \ + --name claude-code-router \ + -p 3456:3456 \ + -v $(pwd)/config.json:/app/.claude-code-router/config.json \ + musistudio/claude-code-router:latest +``` + +配置文件示例： + +```json5 +{ + // 服务器配置 + "HOST": "0.0.0.0", + "PORT": 3456, + "APIKEY": "your-api-key-here", + + // 日志配置 + "LOG": true, + "LOG_LEVEL": "info", + + // LLM 提供商配置 + "Providers": [ + { + "name": "openai", + "baseUrl": "https://api.openai.com/v1", + "apiKey": "$OPENAI_API_KEY", + "models": ["gpt-4", "gpt-3.5-turbo"] + } + ], + + // 路由配置 + "Router": { + "default": "openai,gpt-4" + } +} +``` + +## 环境变量 + +支持通过环境变量覆盖配置： + +| 变量名 | 说明 | 默认值 | +|--------|------|--------| +| `HOST` | 监听地址 | `127.0.0.1` | +| `PORT` | 监听端口 | `3456` | +| `APIKEY` | API 密钥 | - | +| `LOG_LEVEL` | 日志级别 | `debug` | +| `LOG` | 是否启用日志 | `true` | + +## 生产环境建议 + +### 1. 使用反向代理 + +使用 Nginx 作为反向代理： + +```nginx +server { + listen 80; + server_name your-domain.com; + + location / { + proxy_pass http://localhost:3456; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_cache_bypass $http_upgrade; + } +} +``` + +### 2. 配置 HTTPS + +使用 Let's Encrypt 获取免费证书： + +```bash +sudo certbot --nginx -d your-domain.com +``` + +### 3. 日志管理 + +配置日志轮转和持久化： + +```yaml +version: '3.8' +services: + claude-code-router: + image: musistudio/claude-code-router:latest + volumes: + - ./logs:/app/.claude-code-router/logs + environment: + - LOG_LEVEL=warn +``` + +### 4. 健康检查 + +配置 Docker 健康检查： + +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:3456/api/config"] + interval: 30s + timeout: 10s + retries: 3 +``` + +## 访问 Web UI + +部署完成后，访问 Web UI： + +``` +http://localhost:3456/ui/ +``` + +通过 Web UI 可以： +- 查看和管理配置 +- 监控日志 +- 查看服务状态 + +## 二次开发 + +如果需要基于 CCR Server 进行二次开发，请查看 [API 参考](/docs/category/api)。 diff --git a/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/intro.md b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/intro.md new file mode 100644 index 0000000..ddb3ff3 --- /dev/null +++ b/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/intro.md @@ -0,0 +1,77 @@ +# Server 简介 + +Claude Code Router Server 是一个核心服务组件，负责将 Claude Code 的 API 请求路由到不同的 LLM 提供商。它提供了完整的 HTTP API，支持： + +- **API 请求路由**：将 Anthropic 格式的请求转换为各种提供商的 API 格式 +- **认证与授权**：支持 API Key 认证 +- **配置管理**：动态配置提供商、路由规则和转换器 +- **Web UI**：内置管理界面 +- **日志系统**：完整的请求日志记录 + +## 架构概述 + +``` +┌─────────────┐ ┌──────────────────┐ ┌──────────────┐ +│ Claude Code │────▶│ CCR Server │────▶│ LLM Provider │ +│ Client │ │ (Router + │ │ (OpenAI/ │ +└─────────────┘ │ Transformer) │ │ Gemini/etc)│ + └──────────────────┘ └──────────────┘ + │ + ├─ Web UI + ├─ Config API + └─ Logs API +``` + +## 核心功能 + +### 1. 请求路由 +- 基于 Token 数量的智能路由 +- 项目级路由配置 +- 自定义路由函数 +- 场景化路由（background、think、longContext 等） + +### 2. 请求转换 +- 支持多种 LLM 提供商的 API 格式转换 +- 内置转换器：Anthropic、DeepSeek、Gemini、OpenRouter、Groq 等 +- 可扩展的转换器系统 + +### 3. Agent 系统 +- 插件式的 Agent 架构 +- 内置图片处理 Agent +- 自定义 Agent 支持 + +### 4. 配置管理 +- JSON5 格式配置文件 +- 环境变量插值 +- 配置热更新（需重启服务） + +## 使用场景 + +### 场景一：个人本地服务 +在本地运行服务，供个人 Claude Code 使用： + +```bash +ccr start +``` + +### 场景二：团队共享服务 +使用 Docker 部署，为团队成员提供共享服务： + +```bash +docker run -d -p 3456:3456 musistudio/claude-code-router +``` + +### 场景三：二次开发 +基于暴露的 API 构建自定义应用： + +```bash +GET /api/config +POST /v1/messages +GET /api/logs +``` + +## 下一步 + +- [Docker 部署指南](/docs/server/deployment) - 学习如何部署服务 +- [API 参考](/docs/category/api) - 查看完整的 API 文档 +- [配置说明](/docs/category/server-config) - 了解服务器配置选项 diff --git a/docs/i18n/zh-CN/docusaurus-theme-classic/footer.json b/docs/i18n/zh-CN/docusaurus-theme-classic/footer.json index 9df3917..ad3e176 100644 --- a/docs/i18n/zh-CN/docusaurus-theme-classic/footer.json +++ b/docs/i18n/zh-CN/docusaurus-theme-classic/footer.json @@ -41,7 +41,7 @@ }, "link.item.label.NPM Package": { "message": "NPM 包", - "description": "The label of footer link with label=NPM Package linking to https://www.npmjs.com/package/@musistudio/claude-code-router-cli" + "description": "The label of footer link with label=NPM Package linking to https://www.npmjs.com/package/@musistudio/claude-code-router" }, "copyright": { "message": "Copyright © 2025 Claude Code Router. 保留所有权利。", diff --git a/docs/package.json b/docs/package.json index e8dae37..297cef8 100644 --- a/docs/package.json +++ b/docs/package.json @@ -24,6 +24,7 @@ "devDependencies": { "@docusaurus/module-type-aliases": "^3.9.2", "@docusaurus/types": "^3.9.2", + "@tailwindcss/typography": "^0.5.19", "@types/react": "18", "@types/react-dom": "18", "autoprefixer": "^10.4.21", diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 80f9426..9fa17f9 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -33,6 +33,7 @@ const sidebars: SidebarsConfig = { { type: 'category', label: 'Configuration', + key: 'server-configuration-category', link: { type: 'generated-index', title: 'Server Configuration', @@ -57,7 +58,6 @@ const sidebars: SidebarsConfig = { }, items: [ 'server/advanced/custom-router', - 'server/advanced/agents', 'server/advanced/presets', ], }, @@ -89,12 +89,15 @@ const sidebars: SidebarsConfig = { 'cli/commands/start', 'cli/commands/model', 'cli/commands/status', + 'cli/commands/statusline', + 'cli/commands/preset', 'cli/commands/other', ], }, { type: 'category', label: 'Configuration', + key: 'cli-configuration-category', link: { type: 'generated-index', title: 'CLI Configuration', diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 774de0d..77f83df 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -27,6 +27,72 @@ --animation-duration-fast: 0.15s; } +/* Apply Tailwind Typography to Docusaurus markdown content */ +@layer components { + /* Apply prose styles to article content (main markdown container in Docusaurus) */ + article { + @apply prose prose-neutral max-w-none; + @apply prose-headings:font-bold prose-headings:text-neutral-900; + @apply prose-h1:text-3xl prose-h1:mt-8 prose-h1:mb-4; + @apply prose-h2:text-2xl prose-h2:mt-6 prose-h2:mb-3; + @apply prose-h3:text-xl prose-h3:mt-5 prose-h3:mb-2; + @apply prose-h4:text-lg prose-h4:mt-4 prose-h4:mb-2; + @apply prose-p:text-base prose-p:leading-7 prose-p:mb-4; + @apply prose-a:text-primary-600 prose-a:no-underline hover:prose-a:underline; + @apply prose-strong:text-neutral-900 prose-strong:font-semibold; + @apply prose-code:text-primary-600 prose-code:px-1 prose-code:py-0.5 prose-code:bg-neutral-100 prose-code:rounded; + @apply prose-pre:bg-neutral-900 prose-pre:text-neutral-100; + @apply prose-blockquote:border-l-4 prose-blockquote:border-primary-600 prose-blockquote:pl-4 prose-blockquote:italic; + @apply prose-ul:list-disc prose-ul:pl-6; + @apply prose-ol:list-decimal prose-ol:pl-6; + } + + /* Handle nested markdown containers */ + .markdown, + .theme-doc-markdown { + @apply prose prose-neutral; + @apply prose-headings:font-bold prose-headings:text-neutral-900; + @apply prose-h1:text-3xl prose-h1:mt-8 prose-h1:mb-4; + @apply prose-h2:text-2xl prose-h2:mt-6 prose-h2:mb-3; + @apply prose-h3:text-xl prose-h3:mt-5 prose-h3:mb-2; + @apply prose-h4:text-lg prose-h4:mt-4 prose-h4:mb-2; + @apply prose-p:text-base prose-p:leading-7 prose-p:mb-4; + @apply prose-a:text-primary-600 prose-a:no-underline hover:prose-a:underline; + @apply prose-strong:text-neutral-900 prose-strong:font-semibold; + @apply prose-code:text-primary-600 prose-code:px-1 prose-code:py-0.5 prose-code:bg-neutral-100 prose-code:rounded; + @apply prose-pre:bg-neutral-900 prose-pre:text-neutral-100; + @apply prose-blockquote:border-l-4 prose-blockquote:border-primary-600 prose-blockquote:pl-4 prose-blockquote:italic; + @apply prose-ul:list-disc prose-ul:pl-6; + @apply prose-ol:list-decimal prose-ol:pl-6; + } +} + +/* Override Docusaurus default max-width - must be outside @layer to take precedence */ +.markdown, +.theme-doc-markdown { + max-width: 56rem !important; + margin-left: auto !important; + margin-right: auto !important; + padding-left: 1rem; + padding-right: 1rem; +} + +@media (min-width: 640px) { + .markdown, + .theme-doc-markdown { + padding-left: 1.5rem; + padding-right: 1.5rem; + } +} + +@media (min-width: 1024px) { + .markdown, + .theme-doc-markdown { + padding-left: 2rem; + padding-right: 2rem; + } +} + /* Custom styles */ .hero { padding: 4rem 0; @@ -219,6 +285,53 @@ a { white-space: nowrap; } +/* Prevent "Edit this page" button from wrapping */ +.theme-edit-this-page { + display: inline-flex; + align-items: center; + gap: 0.25rem; + white-space: nowrap; +} + +/* Breadcrumbs alignment */ +.breadcrumbs { + margin-top: 0; + display: flex; + align-items: center; + flex-wrap: wrap; +} + +.breadcrumbs__item { + display: inline-flex; + align-items: center; + line-height: 1; +} + +.breadcrumbs__link { + display: inline-flex; + align-items: center; + gap: 0.25rem; + line-height: 1; +} + +.breadcrumbs__link svg { + display: inline-flex; + align-items: center; +} + +.breadcrumbs__link span { + display: inline-flex; + align-items: center; +} + +/* Breadcrumb separator alignment */ +.breadcrumbs__item::after, +.breadcrumbs__item--separator { + display: inline-flex; + align-items: center; + margin: 0 0.5rem; +} + /* Responsive improvements */ @media (max-width: 996px) { .features { diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index 7a09858..4cfdb68 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -124,7 +124,7 @@ function HomepageHeader() { {/* Copy Button */}