mirror of
https://github.com/musistudio/claude-code-router.git
synced 2026-01-30 06:12:06 +00:00
support docker
This commit is contained in:
musistudio
192
CLAUDE.md
192
CLAUDE.md
@@ -2,43 +2,163 @@
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Commands
|
||||
## Project Overview
|
||||
|
||||
- **Build the project**:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
- **Start the router server**:
|
||||
```bash
|
||||
ccr start
|
||||
```
|
||||
- **Stop the router server**:
|
||||
```bash
|
||||
ccr stop
|
||||
```
|
||||
- **Check the server status**:
|
||||
```bash
|
||||
ccr status
|
||||
```
|
||||
- **Run Claude Code through the router**:
|
||||
```bash
|
||||
ccr code "<your prompt>"
|
||||
```
|
||||
- **Release a new version**:
|
||||
```bash
|
||||
npm run release
|
||||
```
|
||||
Claude Code Router is a tool that routes Claude Code requests to different LLM providers. It uses a Monorepo architecture with four main packages:
|
||||
|
||||
## Architecture
|
||||
- **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 and utilities
|
||||
- **ui** (`@musistudio/claude-code-router-ui`): Web management interface (React + Vite)
|
||||
|
||||
This project is a TypeScript-based router for Claude Code requests. It allows routing requests to different large language models (LLMs) from various providers based on custom rules.
|
||||
## Build Commands
|
||||
|
||||
- **Entry Point**: The main command-line interface logic is in `src/cli.ts`. It handles parsing commands like `start`, `stop`, and `code`.
|
||||
- **Server**: The `ccr start` command launches a server that listens for requests from Claude Code. The server logic is initiated from `src/index.ts`.
|
||||
- **Configuration**: The router is configured via a JSON file located at `~/.claude-code-router/config.json`. This file defines API providers, routing rules, and custom transformers. An example can be found in `config.example.json`.
|
||||
- **Routing**: The core routing logic determines which LLM provider and model to use for a given request. It supports default routes for different scenarios (`default`, `background`, `think`, `longContext`, `webSearch`) and can be extended with a custom JavaScript router file. The router logic is likely in `src/utils/router.ts`.
|
||||
- **Providers and Transformers**: The application supports multiple LLM providers. Transformers adapt the request and response formats for different provider APIs.
|
||||
- **Claude Code Integration**: When a user runs `ccr code`, the command is forwarded to the running router service. The service then processes the request, applies routing rules, and sends it to the configured LLM. If the service isn't running, `ccr code` will attempt to start it automatically.
|
||||
- **Dependencies**: The project is built with `esbuild`. It has a key local dependency `@musistudio/llms`, which probably contains the core logic for interacting with different LLM APIs.
|
||||
- `@musistudio/llms` is implemented based on `fastify` and exposes `fastify`'s hook and middleware interfaces, allowing direct use of `server.addHook`.
|
||||
- 无论如何你都不能自动提交git
|
||||
### Build all packages
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### Build individual packages
|
||||
```bash
|
||||
pnpm build:cli # Build CLI
|
||||
pnpm build:server # Build Server
|
||||
pnpm build:ui # Build UI
|
||||
```
|
||||
|
||||
### Development mode
|
||||
```bash
|
||||
pnpm dev:cli # Develop CLI (ts-node)
|
||||
pnpm dev:server # Develop Server (ts-node)
|
||||
pnpm dev:ui # Develop UI (Vite)
|
||||
```
|
||||
|
||||
### Publish
|
||||
```bash
|
||||
pnpm release # Build and publish all packages
|
||||
```
|
||||
|
||||
## Core Architecture
|
||||
|
||||
### 1. Routing System (packages/server/src/utils/router.ts)
|
||||
|
||||
The routing logic determines which model a request should be sent to:
|
||||
|
||||
- **Default routing**: Uses `Router.default` configuration
|
||||
- **Project-level routing**: Checks `~/.claude/projects/<project-id>/claude-code-router.json`
|
||||
- **Custom routing**: Loads custom JavaScript router function via `CUSTOM_ROUTER_PATH`
|
||||
- **Built-in scenario routing**:
|
||||
- `background`: Background tasks (typically lightweight models)
|
||||
- `think`: Thinking-intensive tasks (Plan Mode)
|
||||
- `longContext`: Long context (exceeds `longContextThreshold` tokens)
|
||||
- `webSearch`: Web search tasks
|
||||
- `image`: Image-related tasks
|
||||
|
||||
Token calculation uses `tiktoken` (cl100k_base) to estimate request size.
|
||||
|
||||
### 2. Transformer System
|
||||
|
||||
The project uses the `@musistudio/llms` package (external dependency) to handle request/response transformations. Transformers adapt to different provider API differences:
|
||||
|
||||
- Built-in transformers: `anthropic`, `deepseek`, `gemini`, `openrouter`, `groq`, `maxtoken`, `tooluse`, `reasoning`, `enhancetool`, etc.
|
||||
- Custom transformers: Load external plugins via `transformers` array in `config.json`
|
||||
|
||||
Transformer configuration supports:
|
||||
- Global application (provider level)
|
||||
- Model-specific application
|
||||
- Option passing (e.g., `max_tokens` parameter for `maxtoken`)
|
||||
|
||||
### 3. Agent System (packages/server/src/agents/)
|
||||
|
||||
Agents are pluggable feature modules that can:
|
||||
- Detect whether to handle a request (`shouldHandle`)
|
||||
- Modify requests (`reqHandler`)
|
||||
- Provide custom tools (`tools`)
|
||||
|
||||
Built-in agents:
|
||||
- **imageAgent**: Handles image-related tasks
|
||||
|
||||
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
|
||||
|
||||
### 4. SSE Stream Processing
|
||||
|
||||
The server uses custom Transform streams to handle Server-Sent Events:
|
||||
- `SSEParserTransform`: Parses SSE text stream into event objects
|
||||
- `SSESerializerTransform`: Serializes event objects into SSE text stream
|
||||
- `rewriteStream`: Intercepts and modifies stream data (for agent tool calls)
|
||||
|
||||
### 5. Configuration Management
|
||||
|
||||
Configuration file location: `~/.claude-code-router/config.json`
|
||||
|
||||
Key features:
|
||||
- Supports environment variable interpolation (`$VAR_NAME` or `${VAR_NAME}`)
|
||||
- JSON5 format (supports comments)
|
||||
- Automatic backups (keeps last 3 backups)
|
||||
- Hot reload requires service restart (`ccr restart`)
|
||||
|
||||
Configuration validation:
|
||||
- If `Providers` are configured, both `HOST` and `APIKEY` must be set
|
||||
- Otherwise listens on `0.0.0.0` without authentication
|
||||
|
||||
### 6. Logging System
|
||||
|
||||
Two separate logging systems:
|
||||
|
||||
**Server-level logs** (pino):
|
||||
- Location: `~/.claude-code-router/logs/ccr-*.log`
|
||||
- Content: HTTP requests, API calls, server events
|
||||
- Configuration: `LOG_LEVEL` (fatal/error/warn/info/debug/trace)
|
||||
|
||||
**Application-level logs**:
|
||||
- Location: `~/.claude-code-router/claude-code-router.log`
|
||||
- Content: Routing decisions, business logic events
|
||||
|
||||
## CLI Commands
|
||||
|
||||
```bash
|
||||
ccr start # Start server
|
||||
ccr stop # Stop server
|
||||
ccr restart # Restart server
|
||||
ccr status # Show status
|
||||
ccr code # Execute claude command
|
||||
ccr model # Interactive model selection and configuration
|
||||
ccr activate # Output shell environment variables (for integration)
|
||||
ccr ui # Open Web UI
|
||||
ccr statusline # Integrated statusline (reads JSON from stdin)
|
||||
```
|
||||
|
||||
## Subagent Routing
|
||||
|
||||
Use special tags in subagent prompts to specify models:
|
||||
```
|
||||
<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>
|
||||
Please help me analyze this code...
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
```
|
||||
cli → server → shared
|
||||
server → @musistudio/llms (core routing and transformation logic)
|
||||
ui (standalone frontend application)
|
||||
```
|
||||
|
||||
## Development Notes
|
||||
|
||||
1. **Node.js version**: Requires >= 18.0.0
|
||||
2. **Package manager**: Uses pnpm (monorepo depends on workspace protocol)
|
||||
3. **TypeScript**: All packages use TypeScript, but UI package is ESM module
|
||||
4. **Build tools**:
|
||||
- cli/server/shared: esbuild
|
||||
- ui: Vite + TypeScript
|
||||
5. **@musistudio/llms**: This is an external dependency package providing the core server framework and transformer functionality, type definitions in `packages/server/src/types.d.ts`
|
||||
|
||||
## Configuration Example Locations
|
||||
|
||||
- Main configuration example: Complete example in README.md
|
||||
- Custom router example: `custom-router.example.js`
|
||||
|
||||
Reference in New Issue
Block a user