@musistudio/claude-code-router 1.0.9 → 1.0.10

package/README.md

@@ -29,13 +29,11 @@ ccr code
 
 ```json
 {
-  "OPENAI_API_KEY": "sk-xxx",
-  "OPENAI_BASE_URL": "https://api.deepseek.com",
-  "OPENAI_MODEL": "deepseek-chat",
   "Providers": [
     {
       "name": "openrouter",
-      "api_base_url": "https://openrouter.ai/api/v1",
+      // IMPORTANT: api_base_url must be a complete (full) URL.
+      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
       "api_key": "sk-xxx",
       "models": [
         "google/gemini-2.5-pro-preview",
@@ -46,18 +44,48 @@ ccr code
     },
     {
       "name": "deepseek",
-      "api_base_url": "https://api.deepseek.com",
+      // IMPORTANT: api_base_url must be a complete (full) URL.
+      "api_base_url": "https://api.deepseek.com/chat/completions",
       "api_key": "sk-xxx",
-      "models": ["deepseek-reasoner"]
+      "models": ["deepseek-chat", "deepseek-reasoner"],
+      "transformer": {
+        "use": ["deepseek"],
+        "deepseek-chat": {
+          // Enhance tool usage for the deepseek-chat model using the ToolUse transformer.
+          "use": ["tooluse"]
+        }
+      }
     },
     {
       "name": "ollama",
-      "api_base_url": "http://localhost:11434/v1",
+      // IMPORTANT: api_base_url must be a complete (full) URL.
+      "api_base_url": "http://localhost:11434/v1/chat/completions",
       "api_key": "ollama",
       "models": ["qwen2.5-coder:latest"]
+    },
+    {
+      "name": "gemini",
+      // IMPORTANT: api_base_url must be a complete (full) URL.
+      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
+      "api_key": "sk-xxx",
+      "models": ["gemini-2.5-flash", "gemini-2.5-pro"],
+      "transformer": {
+        "use": ["gemini"]
+      }
+    },
+    {
+      "name": "volcengine",
+      // IMPORTANT: api_base_url must be a complete (full) URL.
+      "api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
+      "api_key": "sk-xxx",
+      "models": ["deepseek-v3-250324", "deepseek-r1-250528"],
+      "transformer": {
+        "use": ["deepseek"]
+      }
     }
   ],
   "Router": {
+    "default": "deepseek,deepseek-chat", // IMPORTANT OPENAI_MODEL has been deprecated
     "background": "ollama,qwen2.5-coder:latest",
     "think": "deepseek,deepseek-reasoner",
     "longContext": "openrouter,google/gemini-2.5-pro-preview"
@@ -86,40 +114,12 @@ ccr code
 
 - [x] Support change models
 - [x] Github Actions
-- [ ] More robust plugin support
 - [ ] More detailed logs
 
-## Plugins
-You can modify or enhance Claude Code’s functionality by installing plugins. The mechanism works by using middleware to modify request parameters — this allows you to rewrite prompts or add/remove tools.
-
-To use a plugin, place it in the ~/.claude-code-router/plugins/ directory and specify the plugin name in config.js using the `usePlugins` option.like this
-```json
-// ~/.claud-code-router/config.json
-{
-  ...,
-  "usePlugins": ["notebook-tools-filter", "toolcall-improvement"]
-}
-```
-
-Currently, the following plugins are available:
-
-
-- **notebook-tools-filter**    
-This plugin filters out tool calls related to Jupyter notebooks (.ipynb files). You can use it if your work does not involve Jupyter.
-
-
-- **toolcall-improvement**    
-If your LLM doesn’t handle tool usage well (for example, always returning code as plain text instead of modifying files — such as with deepseek-v3), you can use this plugin.    
-This plugin simply adds the following system prompt. If you have a better prompt, you can modify it.
-```markdown
-## **Important Instruction:**  
-You must use tools as frequently and accurately as possible to help the user solve their problem.  
-Prioritize tool usage whenever it can enhance accuracy, efficiency, or the quality of the response.
-```
-
-
 ## Github Actions
+
 You just need to install `Claude Code Actions` in your repository according to the [official documentation](https://docs.anthropic.com/en/docs/claude-code/github-actions). For `ANTHROPIC_API_KEY`, you can use any string. Then, modify your `.github/workflows/claude.yaml` file to include claude-code-router, like this:
+
 ```yaml
 name: Claude Code
 
@@ -151,7 +151,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      
+
       - name: Prepare Environment
         run: |
           curl -fsSL https://bun.sh/install | bash
@@ -165,7 +165,7 @@ jobs:
           }
           EOF
         shell: bash
-        
+
       - name: Start Claude Code Router
         run: |
           nohup ~/.bun/bin/bunx @musistudio/claude-code-router@1.0.8 start &
@@ -179,6 +179,7 @@ jobs:
         with:
           anthropic_api_key: "test"
 ```
+
 You can modify the contents of `$HOME/.claude-code-router/config.json` as needed.
 GitHub Actions support allows you to trigger Claude Code at specific times, which opens up some interesting possibilities.
 
@@ -190,7 +191,6 @@ For example, between 00:30 and 08:30 Beijing Time, using the official DeepSeek A
 
 So maybe in the future, I’ll describe detailed tasks for Claude Code ahead of time and let it run during these discounted hours to reduce costs?
 
-
 ## Some tips:
 
 Now you can use deepseek-v3 models directly without using any plugins.
@@ -205,22 +205,36 @@ Some interesting points: Based on my testing, including a lot of context informa
 
 ## Some articles:
 
-1. [Project Motivation and Principles](blog/en/project-motivation-and-how-it-works.md) ([中文版看这里](blog/zh/项目初衷及原理.md))
+1. [Project Motivation and Principles](blog/en/project-motivation-and-how-it-works.md) ([项目初衷及原理](blog/zh/项目初衷及原理.md))
+2. [Maybe We Can Do More with the Router](blog/en/maybe-we-can-do-more-with-the-route.md) ([或许我们能在 Router 中做更多事情](blog/zh/或许我们能在Router中做更多事情.md))
 
 ## Buy me a coffee
 
-If you find this project helpful, you can choose to sponsor the author with a cup of coffee. Please provide your GitHub information so I can add you to the sponsor list below.  
+If you find this project helpful, you can choose to sponsor the author with a cup of coffee. Please provide your GitHub information so I can add you to the sponsor list below.
 
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F31GN2GM)
 
-| ![alipay](/blog/images/alipay.jpg) | ![wechat](/blog/images/wechat.jpg) |
-|----------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
+<table>
+  <tr>
+    <td><img src="/blog/images/alipay.jpg" width="200" /></td>
+    <td><img src="/blog/images/wechat.jpg" width="200" /></td>
+  </tr>
+</table>
 
 ## Sponsors
 
 Thanks to the following sponsors:
 
-@Simon Leischnig (If you see this, feel free to contact me and I can update it with your GitHub information)    
-[@duanshuaimin](https://github.com/duanshuaimin)     
-[@vrgitadmin](https://github.com/vrgitadmin)     
-@*o(看到后可通过主页邮箱联系我修改github用户名)
+@Simon Leischnig (If you see this, feel free to contact me and I can update it with your GitHub information)  
+[@duanshuaimin](https://github.com/duanshuaimin)  
+[@vrgitadmin](https://github.com/vrgitadmin)  
+@\*o (可通过主页邮箱联系我修改 github 用户名)  
+@\*\*聪 (可通过主页邮箱联系我修改 github 用户名)  
+@\*说 (可通过主页邮箱联系我修改 github 用户名)  
+@\*更 (可通过主页邮箱联系我修改 github 用户名)  
+@\*更 (可通过主页邮箱联系我修改 github 用户名)  
+@K\*g (可通过主页邮箱联系我修改 github 用户名)  
+@R\*R (可通过主页邮箱联系我修改 github 用户名)  
+@[@bobleer](https://github.com/bobleer) (可通过主页邮箱联系我修改 github 用户名)  
+@\*苗 (可通过主页邮箱联系我修改 github 用户名)  
+@\*划 (可通过主页邮箱联系我修改 github 用户名)

package/blog/en/maybe-we-can-do-more-with-the-route.md

@@ -0,0 +1,105 @@
+# Maybe We Can Do More with the Router
+
+Since the release of `claude-code-router`, I’ve received a lot of user feedback, and quite a few issues are still open. Most of them are related to support for different providers and the lack of tool usage from the deepseek model.
+
+Originally, I created this project for personal use, mainly to access claude code at a lower cost. So, multi-provider support wasn’t part of the initial design. But during troubleshooting, I discovered that even though most providers claim to be compatible with the OpenAI-style `/chat/completions` interface, there are many subtle differences. For example:
+
+1. When Gemini's tool parameter type is string, the `format` field only supports `date` and `date-time`, and there’s no tool call ID.
+
+2. OpenRouter requires `cache_control` for caching.
+
+3. The official DeepSeek API has a `max_output` of 8192, but Volcano Engine’s limit is even higher.
+
+Aside from these, smaller providers often have quirks in their parameter handling. So I decided to create a new project, [musistudio/llms](https://github.com/musistudio/llms), to deal with these compatibility issues. It uses the OpenAI format as a base and introduces a generic Transformer interface for transforming both requests and responses.
+
+Once a `Transformer` is implemented for each provider, it becomes possible to mix-and-match requests between them. For example, I implemented bidirectional conversion between Anthropic and OpenAI formats in `AnthropicTransformer`, which listens to the `/v1/messages` endpoint. Similarly, `GeminiTransformer` handles Gemini <-> OpenAI format conversions and listens to `/v1beta/models/:modelAndAction`.
+
+When both requests and responses are transformed into a common format, they can interoperate seamlessly:
+
+```
+AnthropicRequest -> AnthropicTransformer -> OpenAIRequest -> GeminiTransformer -> GeminiRequest -> GeminiServer
+```
+
+```
+GeminiResponse -> GeminiTransformer -> OpenAIResponse -> AnthropicTransformer -> AnthropicResponse
+```
+
+Using a middleware layer to smooth out differences may introduce some performance overhead, but the main goal here is to enable `claude-code-router` to support multiple providers.
+
+As for the issue of DeepSeek’s lackluster tool usage — I found that it stems from poor instruction adherence in long conversations. Initially, the model actively calls tools, but after several rounds, it starts responding with plain text instead. My first workaround was injecting a system prompt to remind the model to use tools proactively. But in long contexts, the model tends to forget this instruction.
+
+After reading the DeepSeek documentation, I noticed it supports the `tool_choice` parameter, which can be set to `"required"` to force the model to use at least one tool. I tested this by enabling the parameter, and it significantly improved the model’s tool usage. We can remove the setting when it's no longer necessary. With the help of the `Transformer` interface in [musistudio/llms](https://github.com/musistudio/llms), we can modify the request before it’s sent and adjust the response after it’s received.
+
+Inspired by the Plan Mode in `claude code`, I implemented a similar Tool Mode for DeepSeek:
+
+```typescript
+export class TooluseTransformer implements Transformer {
+  name = "tooluse";
+
+  transformRequestIn(request: UnifiedChatRequest): UnifiedChatRequest {
+    if (request.tools?.length) {
+      request.messages.push({
+        role: "system",
+        content: `<system-reminder>Tool mode is active. The user expects you to proactively execute the most suitable tool to help complete the task. 
+Before invoking a tool, you must carefully evaluate whether it matches the current task. If no available tool is appropriate for the task, you MUST call the \`ExitTool\` to exit tool mode — this is the only valid way to terminate tool mode.
+Always prioritize completing the user's task effectively and efficiently by using tools whenever appropriate.</system-reminder>`,
+      });
+      request.tool_choice = "required";
+      request.tools.unshift({
+        type: "function",
+        function: {
+          name: "ExitTool",
+          description: `Use this tool when you are in tool mode and have completed the task. This is the only valid way to exit tool mode.
+IMPORTANT: Before using this tool, ensure that none of the available tools are applicable to the current task. You must evaluate all available options — only if no suitable tool can help you complete the task should you use ExitTool to terminate tool mode.
+Examples:
+1. Task: "Use a tool to summarize this document" — Do not use ExitTool if a summarization tool is available.
+2. Task: "What’s the weather today?" — If no tool is available to answer, use ExitTool after reasoning that none can fulfill the task.`,
+          parameters: {
+            type: "object",
+            properties: {
+              response: {
+                type: "string",
+                description:
+                  "Your response will be forwarded to the user exactly as returned — the tool will not modify or post-process it in any way.",
+              },
+            },
+            required: ["response"],
+          },
+        },
+      });
+    }
+    return request;
+  }
+
+  async transformResponseOut(response: Response): Promise<Response> {
+    if (response.headers.get("Content-Type")?.includes("application/json")) {
+      const jsonResponse = await response.json();
+      if (
+        jsonResponse?.choices[0]?.message.tool_calls?.length &&
+        jsonResponse?.choices[0]?.message.tool_calls[0]?.function?.name ===
+          "ExitTool"
+      ) {
+        const toolArguments = JSON.parse(toolCall.function.arguments || "{}");
+        jsonResponse.choices[0].message.content = toolArguments.response || "";
+        delete jsonResponse.choices[0].message.tool_calls;
+      }
+
+      // Handle non-streaming response if needed
+      return new Response(JSON.stringify(jsonResponse), {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    } else if (response.headers.get("Content-Type")?.includes("stream")) {
+      // ...
+    }
+    return response;
+  }
+}
+```
+
+This transformer ensures the model calls at least one tool. If no tools are appropriate or the task is finished, it can exit using `ExitTool`. Since this relies on the `tool_choice` parameter, it only works with models that support it.
+
+In practice, this approach noticeably improves tool usage for DeepSeek. The tradeoff is that sometimes the model may invoke irrelevant or unnecessary tools, which could increase latency and token usage.
+
+This update is just a small experiment — adding an `“agent”` to the router. Maybe there are more interesting things we can explore from here.

package/blog/zh//346/210/226/350/256/270/346/210/221/344/273/254/350/203/275/345/234/250Router/344/270/255/345/201/232/346/233/264/345/244/232/344/272/213/346/203/205.md

@@ -0,0 +1,95 @@
+# 或许我们能在 Router 中做更多事情
+
+自从`claude-code-router`发布以来，我收到了很多用户的反馈，至今还有不少的 issues 未处理。其中大多都是关于不同的供应商的支持和`deepseek`模型调用工具不积极的问题。
+之前开发这个项目主要是为了我自己能以较低成本使用上`claude code`，所以一开始的设计并没有考虑到多供应商的情况。在实际的排查问题中，我发现尽管市面上所有的供应商几乎都宣称兼容`OpenAI`格式调用，即通过`/chat/compeletions`接口调用，但是其中的细节差异非常多。例如:
+
+1. Gemini 的工具参数类型是 string 时，`format`参数只支持`date`和`date-time`，并且没有工具调用 ID。
+
+2. OpenRouter 需要使用`cache_control`进行缓存。
+
+3. DeepSeek 官方 API 的 `max_output` 为 8192，而火山引擎的会更大。
+
+除了这些问题之外，还有一些其他的小的供应商，他们或多或少参数都有点问题。于是，我打算开发一个新的项目[musistudio/llms](https://github.com/musistudio/llms)来处理这种不同服务商的兼容问题。该项目使用 OpenAI 格式为基础的通用格式，提供了一个`Transformer`接口，该接口用于处理转换请求和响应。当我们给不同的服务商都实现了`Transformer`后，我们可以实现不同服务商的混合调用。比如我在`AnthropicTransformer`中实现了`Anthropic`<->`OpenAI`格式的互相转换，并监听了`/v1/messages`端点，在`GeminiTransformer`中实现了`Gemini`<->`OpenAI`格式的互相转换，并监听了`/v1beta/models/:modelAndAction`端点，当他们的请求和响应都被转换成一个通用格式的时候，就可以实现他们的互相调用。
+
+```
+AnthropicRequest -> AnthropicTransformer -> OpenAIRequest -> GeminiTransformer -> GeminiRequest -> GeminiServer
+```
+
+```
+GeminiReseponse -> GeminiTransformer -> OpenAIResponse -> AnthropicTransformer -> AnthropicResponse
+```
+
+虽然使用中间层抹平差异可能会带来一些性能问题，但是该项目最初的目的是为了让`claude-code-router`支持不同的供应商。
+
+至于`deepseek`模型调用工具不积极的问题，我发现这是由于`deepseek`在长上下文中的指令遵循不佳导致的。现象就是刚开始模型会主动调用工具，但是在经过几轮对话后模型只会返回文本。一开始的解决方案是通过注入一个系统提示词告知模型需要积极去使用工具以解决用户的问题，但是后面测试发现在长上下文中模型会遗忘该指令。
+查看`deepseek`文档后发现模型支持`tool_choice`参数，可以强制让模型最少调用 1 个工具，我尝试将该值设置为`required`，发现模型调用工具的积极性大大增加，现在我们只需要在合适的时候取消这个参数即可。借助[musistudio/llms](https://github.com/musistudio/llms)的`Transformer`可以让我们在发送请求前和收到响应后做点什么，所以我参考`claude code`的`Plan Mode`，实现了一个使用与`deepseek`的`Tool Mode`
+
+```typescript
+export class TooluseTransformer implements Transformer {
+  name = "tooluse";
+
+  transformRequestIn(request: UnifiedChatRequest): UnifiedChatRequest {
+    if (request.tools?.length) {
+      request.messages.push({
+        role: "system",
+        content: `<system-reminder>Tool mode is active. The user expects you to proactively execute the most suitable tool to help complete the task. 
+Before invoking a tool, you must carefully evaluate whether it matches the current task. If no available tool is appropriate for the task, you MUST call the \`ExitTool\` to exit tool mode — this is the only valid way to terminate tool mode.
+Always prioritize completing the user's task effectively and efficiently by using tools whenever appropriate.</system-reminder>`,
+      });
+      request.tool_choice = "required";
+      request.tools.unshift({
+        type: "function",
+        function: {
+          name: "ExitTool",
+          description: `Use this tool when you are in tool mode and have completed the task. This is the only valid way to exit tool mode.
+IMPORTANT: Before using this tool, ensure that none of the available tools are applicable to the current task. You must evaluate all available options — only if no suitable tool can help you complete the task should you use ExitTool to terminate tool mode.
+Examples:
+1. Task: "Use a tool to summarize this document" — Do not use ExitTool if a summarization tool is available.
+2. Task: "What’s the weather today?" — If no tool is available to answer, use ExitTool after reasoning that none can fulfill the task.`,
+          parameters: {
+            type: "object",
+            properties: {
+              response: {
+                type: "string",
+                description:
+                  "Your response will be forwarded to the user exactly as returned — the tool will not modify or post-process it in any way.",
+              },
+            },
+            required: ["response"],
+          },
+        },
+      });
+    }
+    return request;
+  }
+
+  async transformResponseOut(response: Response): Promise<Response> {
+    if (response.headers.get("Content-Type")?.includes("application/json")) {
+      const jsonResponse = await response.json();
+      if (
+        jsonResponse?.choices[0]?.message.tool_calls?.length &&
+        jsonResponse?.choices[0]?.message.tool_calls[0]?.function?.name ===
+          "ExitTool"
+      ) {
+        const toolArguments = JSON.parse(toolCall.function.arguments || "{}");
+        jsonResponse.choices[0].message.content = toolArguments.response || "";
+        delete jsonResponse.choices[0].message.tool_calls;
+      }
+
+      // Handle non-streaming response if needed
+      return new Response(JSON.stringify(jsonResponse), {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+      });
+    } else if (response.headers.get("Content-Type")?.includes("stream")) {
+      // ...
+    }
+    return response;
+  }
+}
+```
+
+该工具将始终让模型至少调用一个工具，如果没有合适的工具或者任务已完成可以调用`ExitTool`来退出工具模式，因为是依靠`tool_choice`参数实现的，所以仅适用于支持该参数的模型。经过测试，该工具能显著增加`deepseek`的工具调用次数，弊端是可能会有跟任务无关或者没有必要的工具调用导致增加任务执行事件和消耗的 `token` 数。
+
+这次更新仅仅是在 Router 中实现一个`agent`的一次小探索，或许还能做更多其他有趣的事也说不定...