diff --git a/Dockerfile b/Dockerfile index 147c7ce..4c0c868 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,5 @@ ARG NODE_IMAGE=node:22-bookworm +ARG RUNTIME_NODE_IMAGE=node:22-bookworm-slim FROM ${NODE_IMAGE} AS build WORKDIR /app @@ -13,7 +14,16 @@ RUN npm ci COPY . . RUN npm run build:docker -FROM ${NODE_IMAGE} AS runtime +FROM ${NODE_IMAGE} AS production-deps +WORKDIR /app +ENV NODE_ENV=production + +COPY package.json package-lock.json ./ +COPY packages/core/package.json packages/core/package.json +RUN npm ci --omit=dev --workspace=@claude-code-router/core --include-workspace-root=false \ + && npm cache clean --force + +FROM ${RUNTIME_NODE_IMAGE} AS runtime ENV NODE_ENV=production \ CCR_DATA_DIR=/data \ CCR_WEB_HOST=127.0.0.1 \ @@ -28,14 +38,25 @@ ENV NODE_ENV=production \ WORKDIR /app RUN apt-get update \ - && apt-get install -y --no-install-recommends ca-certificates nginx \ + && apt-get install -y --no-install-recommends ca-certificates libstdc++6 nginx \ && rm -rf /var/lib/apt/lists/* \ - && rm -f /etc/nginx/sites-enabled/default /etc/nginx/conf.d/default.conf + && rm -f /etc/nginx/sites-enabled/default /etc/nginx/conf.d/default.conf \ + && rm -rf \ + /opt/yarn-* \ + /usr/local/bin/corepack \ + /usr/local/bin/npm \ + /usr/local/bin/npx \ + /usr/local/bin/yarn \ + /usr/local/bin/yarnpkg \ + /usr/local/include/node \ + /usr/local/lib/node_modules/corepack \ + /usr/local/lib/node_modules/npm \ + /usr/local/share/doc \ + /usr/local/share/man COPY package.json package-lock.json ./ COPY packages/core/package.json packages/core/package.json -RUN npm ci --omit=dev --workspace=@claude-code-router/core --include-workspace-root=false \ - && npm cache clean --force +COPY --from=production-deps /app/node_modules node_modules COPY --from=build /app/packages/core/dist packages/core/dist COPY --from=build /app/packages/ui/dist/renderer /usr/share/nginx/html diff --git a/README.md b/README.md index a564e4d..10f4c32 100644 --- a/README.md +++ b/README.md @@ -9,12 +9,44 @@ Documentation

+
+ + + + + + + + +
+ + Kimi K2.7 Code sponsor banner + +
+ + Kimi Code Subscription +  ·  + API Global +  ·  + API China + +
+

+ Thanks to Kimi for sponsoring this project! Kimi K2.7 Code is an open-source, coding-focused agentic model developed by Moonshot AI, with substantial gains on real-world long-horizon coding tasks and higher end-to-end success across complex software engineering workflows. It also cuts thinking-token usage by approximately 30% compared with K2.6. Inside CCR, Kimi ships as built-in provider presets: import the pay-as-you-go API or the Kimi Code subscription in one click and route your coding agent's requests to Kimi, the subscription endpoint passes straight through natively with no protocol conversion, API endpoints are adapted automatically, and your balance and subscription usage show up right in the CCR dashboard. +

+

+ CCR already supports Kimi. Visit the Kimi Open Platform (中文站 | Global) to try the API, or explore the cost-effective Coding Plan. +

+
+ +
+ +Claude Code Router Desktop is a local gateway and desktop control panel for routing agent requests from Claude Code, Codex, ZCode, and compatible clients to the model provider you actually want to use. +

Claude Code Router Desktop screenshot

-Claude Code Router Desktop is a local gateway and desktop control panel for routing agent requests from Claude Code, Codex, ZCode, and compatible clients to the model provider you actually want to use. - ## Why Use CCR - Use one local endpoint for multiple agent tools instead of configuring every client separately. @@ -177,6 +209,20 @@ Codex support is powered by [musistudio/codexl](https://github.com/musistudio/co TeamoRouter + + + code0.ai icon +
+ code0.ai + + + + + claudeapi icon +
+ claudeapi + + diff --git a/README_zh.md b/README_zh.md index f7056a5..183df2d 100644 --- a/README_zh.md +++ b/README_zh.md @@ -9,12 +9,44 @@ 文档

+
+ + + + + + + + +
+ + Kimi K2.7 Code 赞助横幅 + +
+ + Kimi Code 订阅 +  ·  + API 中文站 +  ·  + API Global + +
+

+ 感谢 Kimi 赞助本项目！Kimi K2.7 Code 是 Moonshot AI 推出的编程专用开源智能体模型，在真实长程编程与复杂软件工程工作流中显著提升端到端任务成功率，同时优化推理效率，相比 K2.6 平均减少约 30% 的推理 token 消耗。在 CCR 中，Kimi 已作为内置供应商预设开箱即用：无论按量付费 API 还是 Kimi Code 订阅，一键导入即可把你的编程 Agent 请求路由到 Kimi，订阅端点原生直通、无需协议转换，API 端点自动适配，账户余额与订阅用量也能直接在 CCR 面板中查看。 +

+

+ CCR 已内置 Kimi 供应商预设。前往 Kimi 开放平台（中文站｜Global）体验 API，或了解高性价比 Coding Plan 套餐。 +

+
+ +
+ +Claude Code Router Desktop 是一个本地网关和桌面控制台，用来把 Claude Code、Codex、ZCode 以及兼容客户端的 Agent 请求路由到你真正想使用的模型服务。 +

Claude Code Router Desktop 项目截图

-Claude Code Router Desktop 是一个本地网关和桌面控制台，用来把 Claude Code、Codex、ZCode 以及兼容客户端的 Agent 请求路由到你真正想使用的模型服务。 - ## 为什么使用 CCR - 用一个本地入口连接多个 Agent 工具，不需要在每个客户端里重复配置 Provider。 @@ -176,6 +208,20 @@ CCR 可以完全通过桌面 UI 完成配置。首次使用建议按下面顺序 TeamoRouter + + + code0.ai 图标 +
+ code0.ai + + + + + claudeapi 图标 +
+ claudeapi + + diff --git a/build/test.mjs b/build/test.mjs index 9e5d67e..be7b4ad 100644 --- a/build/test.mjs +++ b/build/test.mjs @@ -68,6 +68,7 @@ function runtimeEntryPointsForSuite(suiteName) { return []; } return [ + path.join(coreSourceRoot, "mcp", "fusion-vision-mcp.ts"), path.join(coreSourceRoot, "mcp", "toolhub-mcp.ts") ]; } diff --git a/docker/README.md b/docker/README.md index c176bfd..2b51a1f 100644 --- a/docker/README.md +++ b/docker/README.md @@ -60,11 +60,15 @@ migrated to the public Nginx router endpoint, and removes its temporary container and volume. Set `CCR_DOCKER_TEST_SKIP_BUILD=1` to reuse an already built image. -The Dockerfile defaults to `node:22-bookworm` for reliable native SQLite -installation. To use a different Node base image: +The Dockerfile uses `node:22-bookworm` for build and native SQLite dependency +installation, then copies the production dependencies into a smaller +`node:22-bookworm-slim` runtime image. To use different base images: ```sh -docker build --build-arg NODE_IMAGE=node:22-bookworm-slim -t claude-code-router:local . +docker build \ + --build-arg NODE_IMAGE=node:22-bookworm \ + --build-arg RUNTIME_NODE_IMAGE=node:22-bookworm-slim \ + -t claude-code-router:local . ``` ## Environment diff --git a/docs/public/provider-icons/claudeapi.png b/docs/public/provider-icons/claudeapi.png new file mode 100644 index 0000000..776ced8 Binary files /dev/null and b/docs/public/provider-icons/claudeapi.png differ diff --git a/docs/public/provider-icons/code0.png b/docs/public/provider-icons/code0.png new file mode 100644 index 0000000..32d81c1 Binary files /dev/null and b/docs/public/provider-icons/code0.png differ diff --git a/docs/src/content/docs/en/configuration.md b/docs/src/content/docs/en/configuration.md index 36f1c24..2294e3a 100644 --- a/docs/src/content/docs/en/configuration.md +++ b/docs/src/content/docs/en/configuration.md @@ -2,29 +2,37 @@ title: Claude Code Router Detailed Configuration pageTitle: Detailed Configuration eyebrow: Detailed Configuration -lead: Configure the overview dashboard, API keys, server, providers, routing, Agent Config, Fusion, Bots, tray, and the config database location in detail. +lead: "Separate main app pages from settings pages while following the app's actual order: main pages cover overview, providers, Agent Config, routing, Fusion, API keys, logs and observability, server, and extensions; settings pages cover ToolHub, Bots, data, and tray." --- ## Page Structure -Detailed configuration docs are split into standalone pages. Every left-sidebar item opens a page; the right outline is reserved for headings inside the current page. +Detailed configuration docs are split into standalone pages. Every left-sidebar item opens a page; the right outline is reserved for headings inside the current page. Main pages follow the app's left navigation order. Settings pages are grouped separately and follow the settings dialog order. + +## Main Pages | Page | Covers | | --- | --- | | Overview Dashboard | System status, account balance, usage widgets, layout editing, and share cards | -| API Keys | Client access keys, expiration, and local limits | -| Server | Host, port, proxy mode, system proxy, network capture, and CA certificate | | Provider Config | Upstream services, protocol, Base URL, model list, and credentials | | One click import | Provider deeplink protocol, manifest import, one-click import buttons, and security boundaries | -| Routing Config | Default routing, conditional rules, fallback, and request rewrites | -| Logs & Observability | Request logs, Agent execution traces, tool calls, and tool results | -| Fusion Models | Combine a base model with vision, search, or MCP tools into a new selectable model | | Agent Config | Agent launch method, model, scope, multi-instance launching, and Bot binding | +| Routing Config | Default routing, conditional rules, fallback, and request rewrites | +| Fusion Models | Combine a base model with vision, search, or MCP tools into a new selectable model | +| API Keys | Client access keys, expiration, and local limits | +| Logs & Observability | Request logs, Agent execution traces, tool calls, and tool results | +| Server | Host, port, proxy mode, system proxy, network capture, and CA certificate | | Extension Mechanism | Wrapper plugins, core gateway plugins, custom extension creation, and debugging | + +## Settings Pages + +| Page | Covers | +| --- | --- | +| ToolHub | Collapse many MCP servers into one dynamic tool resolution entry point for agents | | Bots And IM Agent Relay | Bot forwarding, handoff mode, and platform pages | -| Tray Configuration | Tray icon, balance progress, and tray window widgets | | Config Database Location | SQLite config database location maintained by the desktop app | +| Tray Configuration | Tray icon, balance progress, and tray window widgets | ## Content Relationships -Overview Dashboard shows system status and usage. API Keys control client access to CCR. Server controls the local gateway listener and proxy features. Provider Config and One click import cover how upstream model services enter CCR. Routing determines where model requests go. Agent Config covers Claude Code, Codex, and ZCode launch, multi-instance usage, and model selection. Fusion covers vision, web search, and MCP tools. Extension Mechanism covers local plugin creation, installation, and debugging. Bots cover IM platform relay. Tray Configuration covers the menu bar icon and tray window. +Overview Dashboard shows system status and usage. Provider Config and One click import cover how upstream model services enter CCR. Agent Config covers Claude Code, Codex, and ZCode launch, multi-instance usage, and model selection. Routing determines where model requests go. Fusion covers vision, web search, and MCP tools. API Keys control client access to CCR. Logs & Observability cover request logs and agent execution traces. Server controls the local gateway listener and proxy features. Extension Mechanism covers local plugin creation, installation, and debugging. ToolHub, Bots, Config Database Location, and Tray Configuration match the corresponding settings pages in the settings dialog. diff --git a/docs/src/content/docs/en/configuration/provider-deeplink.md b/docs/src/content/docs/en/configuration/provider-deeplink.md index 80e6cf0..b2dd290 100644 --- a/docs/src/content/docs/en/configuration/provider-deeplink.md +++ b/docs/src/content/docs/en/configuration/provider-deeplink.md @@ -78,6 +78,14 @@ Choose a provider below to get started. CCR shows what will be added before savi TeamoRouterAnthropic / Chat / Responses + + + code0.aiAnthropic / Chat / Responses + + + + claudeapiAnthropic Messages + ## Embeddable Button Component diff --git a/docs/src/content/docs/en/configuration/routing.md b/docs/src/content/docs/en/configuration/routing.md index a378c56..f21a521 100644 --- a/docs/src/content/docs/en/configuration/routing.md +++ b/docs/src/content/docs/en/configuration/routing.md @@ -162,7 +162,7 @@ Network errors move to the next attempt. Status-code fallback depends on the mod | Retry | `408`, `409`, `429`, `5xx` | | Fallback targets | Any `4xx` or `5xx` | -For `429` rate-limit responses, CCR waits before the next attempt. It honors `Retry-After` when the upstream provides it; otherwise it uses exponential backoff starting at 1 second and capped at 30 seconds per attempt. +Before moving to the next attempt, CCR waits for every fallback-triggering failure, including network errors. It honors a positive `Retry-After` header when the upstream provides one; otherwise it uses exponential backoff starting at 1 second and capped at 30 seconds per attempt. **Fallback targets** also switches on `4xx` because model-not-found, auth, or provider-side rejection errors may only affect the current target. If the fallback model works, the request can still succeed. diff --git a/docs/src/content/docs/en/configuration/toolhub.md b/docs/src/content/docs/en/configuration/toolhub.md new file mode 100644 index 0000000..c098456 --- /dev/null +++ b/docs/src/content/docs/en/configuration/toolhub.md @@ -0,0 +1,167 @@ +--- +title: ToolHub +pageTitle: ToolHub +eyebrow: Detailed Configuration +lead: Collapse many MCP servers into one compact entry point so agents lazy-load task-specific tools and save context. +--- + +## When To Use It + +As your MCP setup grows, exposing every tool directly to an agent makes the eager tool list large and easier to misuse. ToolHub exposes one `ccr-toolhub` MCP server with two meta tools: + +- `tool_hub.resolve`: searches the available MCP tool catalog for the current task. +- `tool_hub.invoke`: calls a real MCP tool that was selected for this task. + +Use ToolHub for tools that are not needed often but are still useful occasionally. It lazy-loads them only when a task actually needs them. The main value is saving context: large low-frequency tool catalogs do not have to stay in the agent's eager tool list, which reduces context use and the chance of selecting the wrong tool. Simple local code, file, or conversation tasks usually do not need ToolHub. + +## How It Works + +1. Enable ToolHub in **Settings → ToolHub**. +2. Select a configured model as the **Resolver model**. It reads the MCP tool catalog and chooses the tools needed for the task. Prefer `deepseek-v4-flash`, or another stable lightweight model in a similar flash-price tier. +3. Add or import backend MCP servers. ToolHub supports `stdio`, `streamable-http`, and `sse`. +4. Open Claude Code or Codex from CCR. CCR writes the `ccr-toolhub` MCP server into that agent config. +5. When the agent receives a request about external services, installed MCP capabilities, or business APIs, it calls `tool_hub.resolve` first, then uses `tool_hub.invoke` to run the selected tools. + +ToolHub combines MCP servers configured on the ToolHub page with compatible global Agent MCP servers from older configs, and excludes `ccr-toolhub` itself to avoid recursive calls. + +## Built-In Browser Automation + +When ToolHub is enabled in CCR Desktop and **Built-in browser automation** is turned on, agents can use the desktop built-in browser for web tasks. You do not need to add a browser backend on the ToolHub page, and you do not need a separate API key; CCR connects to it through the local gateway authentication path. + +To enable it: + +1. Open **Settings → ToolHub** and turn on **Enable ToolHub**. +2. Turn on **Built-in browser automation** on the same page. This switch is shown only after ToolHub is enabled. +3. After saving settings, reopen Claude Code or Codex from CCR so the new agent instance loads the latest configuration. + +> Already-running agent instances usually do not pick up this switch immediately. Restart the agent instance, or use the agent's own controls to restart ToolHub. + +Built-in browser automation is useful for tasks that need real browser state, such as opening sites, reading pages, filling forms, clicking buttons, scrolling, or completing web flows like ordering, booking, lookup, and checkout when no domain-specific capability exists. After it is enabled, the agent can: + +- Open or attach built-in browser tabs, then navigate to URLs or search queries. +- Read page content and find buttons, links, form fields, and other page elements. +- Click, type, select, press keys, and scroll page elements. +- Wait for page loads, navigation, dialogs, or human handoff results before continuing. +- Request human help for login, verification codes, CAPTCHA, human checks, or manual confirmation. + +When a web flow needs login, verification codes, CAPTCHA, a human check, or manual confirmation, CCR shows the built-in browser window and displays the requested action in the top toolbar. After the user clicks **Done** or **Hide**, the agent receives the result and continues. Handoff waits support up to 10 minutes. + +### Chrome Login Import Extension + +Built-in browser automation can also import login state for selected domains from system Chrome into CCR's in-app browser. This lets the agent reuse sites where you are already signed in to Chrome. It requires the unpacked Chrome extension in this repository: `extension/chrome`. + +Install it: + +1. Open `chrome://extensions` in Chrome. +2. Enable **Developer mode**. +3. Click **Load unpacked**. +4. Select the repository's `extension/chrome` directory. + +Import flow: + +1. When a task needs existing Chrome login state, the agent can request an import; the user can also click the key button in CCR's in-app browser toolbar. +2. CCR creates a one-time import job and opens a confirmation page. If your default browser is not Chrome, copy the confirmation URL into Chrome with the extension installed. +3. Review the requested domains on the confirmation page, then click **Confirm and Import**. +4. The Chrome extension reads cookies and localStorage for those domains and submits them to CCR. After it completes, the agent can continue the task in the built-in browser. + +The extension reads only the domains listed in the CCR import job. It does not enumerate every Chrome cookie. For localStorage, the extension temporarily opens non-active tabs for the selected origins, reads `localStorage`, and closes those tabs. If the confirmation page says the extension does not have site access, allow the extension to access the target domains in Chrome extension settings, reload the unpacked extension, and try again. + +> Note: Built-in browser automation depends on CCR Desktop's built-in browser and is only available in the desktop app. CLI, server deployments, and pure web environments do not include this built-in capability; use an external browser automation MCP server instead. + +## Options + +| Option | Description | +| --- | --- | +| Enable ToolHub | Exposes `ccr-toolhub` to agents. If no backend MCP server is available, CCR does not generate a ToolHub MCP config. | +| Built-in browser automation | Shown only after ToolHub is enabled. Lets agents use CCR Desktop's built-in browser for web tasks. | +| Resolver model | Choose from configured provider models. Prefer `deepseek-v4-flash`, or another stable lightweight model in a similar flash-price tier with enough tool-description understanding. | +| Max tools | Maximum tools returned by one resolve call. Range `1` to `20`, default `10`. | +| Timeout ms | Base timeout for ToolHub resolving and invocation. Range `8000` to `300000`, default `60000`. If a backend MCP server needs a longer request timeout, CCR raises the effective invocation timeout to match the backend. | +| MCP servers | Backend tool sources. Each server needs a unique name plus transport, command or URL, environment variables, headers, and timeouts. | +| Import JSON | Imports common MCP JSON shapes. Supports a root object, array, `mcpServers`, or `mcp_servers`. | + +## Add MCP Servers + +### stdio + +Use `stdio` for local command-line MCP servers. Configure: + +- **Command**: launch command, such as `npx`, `node`, or `python`. +- **Arguments**: command arguments. +- **Working directory**: optional working directory. +- **Stdio message mode**: keep `content-length` by default; use `newline-json` for line-delimited JSON servers. +- **Environment variables**: variables needed only by this MCP server. + +### streamable-http / sse + +Remote MCP servers need a URL. Authentication can use: + +- **API key**: stored directly in the config. +- **API key env**: read from an environment variable. +- **Headers**: custom request headers. + +If a remote server starts slowly or has long-running calls, adjust that server's **Startup timeout** or **Request timeout**. + +## JSON Example + +The desktop app's SQLite config is the effective source, so prefer editing through the UI. The fields below are useful for backups, migration, or troubleshooting: + +```json +{ + "toolHub": { + "enabled": true, + "browserAutomation": true, + "llm": { + "apiKey": "sk-...", + "baseUrl": "https://api.openai.com/v1", + "model": "gpt-5-mini" + }, + "maxTools": 10, + "requestTimeoutMs": 60000, + "mcpServers": [ + { + "name": "filesystem", + "transport": "stdio", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], + "env": {}, + "stdioMessageMode": "content-length", + "requestTimeoutMs": 30000, + "startupTimeoutMs": 600000 + } + ] + } +} +``` + +The import dialog also accepts common MCP JSON: + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } +} +``` + +## ToolHub vs Fusion MCP + +| Capability | ToolHub | Fusion Custom MCP Tool | +| --- | --- | --- | +| Entry point | Agent-side `ccr-toolhub` MCP server | Capability inside one Fusion model | +| Tool selection | Dynamically resolves a tool bundle for each task | Fixed tools selected in the model config | +| Best for | Many MCP servers, changing tool catalogs, agent-led capability discovery | Adding a known tool set to one model | +| Visibility | Claude Code or Codex configs opened through CCR | Routes or agents that select that Fusion model | + +## Troubleshooting + +- Agent cannot see ToolHub: make sure ToolHub is enabled and at least one backend MCP server is configured or **Built-in browser automation** is turned on, then reopen Claude Code or Codex from CCR. +- Missing resolver model or API key: select a configured resolver model and confirm the provider credential works. +- The agent cannot use built-in browser automation: make sure you are using CCR Desktop, turned on **Built-in browser automation** in **Settings → ToolHub**, and reopened Claude Code or Codex from CCR. CLI, server deployments, and pure web environments do not include this built-in capability. +- Chrome login import confirmation keeps waiting for the extension: make sure the unpacked `extension/chrome` extension is loaded in Chrome and has site access for the target domains. If your default browser is not Chrome, copy the confirmation URL into Chrome manually. +- No tools are resolved: confirm the MCP server can list tools, improve tool names and descriptions, or increase **Max tools**. +- Calls time out: check ToolHub **Timeout ms** and the backend server request/startup timeouts. +- Import fails: validate JSON, avoid duplicate server names, make sure `stdio` entries have a command and remote entries have a URL. diff --git a/docs/src/content/docs/zh/configuration.md b/docs/src/content/docs/zh/configuration.md index 6515d0f..c4db009 100644 --- a/docs/src/content/docs/zh/configuration.md +++ b/docs/src/content/docs/zh/configuration.md @@ -2,29 +2,37 @@ title: Claude Code Router 详细配置 pageTitle: 详细配置 eyebrow: 详细配置 -lead: 深入配置概览仪表盘、API 密钥、服务、供应商、路由、Agent配置、Fusion、Bot、托盘和配置数据库位置。这里是按功能查字段和扩展能力的地方。 +lead: 按应用中的实际顺序，将主页页面和设置页分开说明：主页覆盖概览、供应商、Agent配置、路由、Fusion、API 密钥、日志&观测、服务和扩展；设置页覆盖 ToolHub、Bot、数据和托盘。 --- ## 页面结构 -详细配置文档已经拆成独立页面。左侧目录中的每一项都会进入一个页面；当前页面内的标题由右侧大纲负责。 +详细配置文档已经拆成独立页面。左侧目录中的每一项都会进入一个页面；当前页面内的标题由右侧大纲负责。主页页面跟随应用左侧主导航顺序；设置页单独分组，并按设置弹窗顺序排列。 + +## 主页页面 | 页面 | 内容 | | --- | --- | | 概览仪表盘 | 系统状态、账户余额、用量组件、布局编辑和分享卡片 | -| API 密钥 | 客户端访问 Key、过期时间和本地限额 | -| 服务配置 | Host、Port、代理模式、系统代理、网络捕获和 CA 证书 | | 供应商配置 | 上游服务、协议、基础 URL、模型列表和凭据 | | 一键导入供应商 | Provider deeplink 协议、Manifest 导入、一键导入按钮和安全边界 | -| 路由配置 | 条件规则、fallback 和请求改写 | -| 日志&观测 | 请求日志、Agent 执行追踪、工具调用和工具结果 | -| Fusion 组合模型 | 把基础模型与视觉、搜索、MCP 工具组合成新的可选模型 | | Agent配置 | Agent 启动方式、模型、作用范围、多开和 Bot 绑定 | +| 路由配置 | 条件规则、fallback 和请求改写 | +| Fusion 组合模型 | 把基础模型与视觉、搜索、MCP 工具组合成新的可选模型 | +| API 密钥 | 客户端访问 Key、过期时间和本地限额 | +| 日志&观测 | 请求日志、Agent 执行追踪、工具调用和工具结果 | +| 服务配置 | Host、Port、代理模式、系统代理、网络捕获和 CA 证书 | | 扩展机制 | Wrapper plugin、Core gateway plugin、自定义扩展创建和调试 | + +## 设置页 + +| 页面 | 内容 | +| --- | --- | +| ToolHub | 将多个 MCP server 收束成一个 Agent 可用的动态工具检索入口 | | Bot 与 IM 接力 Agent | Bot 转发、接力模式和平台页面 | -| 托盘配置 | 托盘图标、余额进度条和托盘窗口组件 | | 配置数据库位置 | 桌面 App 维护的 SQLite 配置数据库位置 | +| 托盘配置 | 托盘图标、余额进度条和托盘窗口组件 | ## 内容关系 -概览仪表盘用于查看系统状态和用量；API 密钥控制客户端访问 CCR；服务配置控制本地网关监听和代理能力；供应商配置和一键导入供应商页面覆盖上游模型服务如何进入 CCR；路由决定模型请求的上游去向；Agent配置页面覆盖 Claude Code、Codex 和 ZCode 的启动、多开与模型选择；Fusion 页面覆盖图像、搜索和 MCP 工具；扩展机制页面覆盖本地插件的创建、安装和调试；Bot 页面覆盖 IM 平台接力；托盘配置覆盖菜单栏图标和托盘窗口。 +概览仪表盘用于查看系统状态和用量；供应商配置和一键导入供应商页面覆盖上游模型服务如何进入 CCR；Agent配置页面覆盖 Claude Code、Codex 和 ZCode 的启动、多开与模型选择；路由决定模型请求的上游去向；Fusion 页面覆盖图像、搜索和 MCP 工具；API 密钥控制客户端访问 CCR；日志&观测覆盖请求日志和 Agent 执行链路；服务配置控制本地网关监听和代理能力；扩展机制覆盖本地插件的创建、安装和调试。ToolHub、Bot、配置数据库位置和托盘配置对应设置弹窗中的同名配置页。 diff --git a/docs/src/content/docs/zh/configuration/provider-deeplink.md b/docs/src/content/docs/zh/configuration/provider-deeplink.md index 703ad8e..ac471c7 100644 --- a/docs/src/content/docs/zh/configuration/provider-deeplink.md +++ b/docs/src/content/docs/zh/configuration/provider-deeplink.md @@ -78,6 +78,14 @@ lead: 快速添加常见模型供应商，确认无误后即可保存，减少 TeamoRouterAnthropic / Chat / Responses + + + code0.aiAnthropic / Chat / Responses + + + + claudeapiAnthropic Messages + ## 嵌入式按钮组件 diff --git a/docs/src/content/docs/zh/configuration/routing.md b/docs/src/content/docs/zh/configuration/routing.md index c00f069..332eda9 100644 --- a/docs/src/content/docs/zh/configuration/routing.md +++ b/docs/src/content/docs/zh/configuration/routing.md @@ -162,7 +162,7 @@ Fallback 处理请求失败后的降级。第一次选模型由路由完成； | 继续重试 | `408`、`409`、`429`、`5xx` | | 失败降级目标 | 任意 `4xx` 或 `5xx` | -对于 `429` 限流响应，CCR 会在下一次尝试前等待。上游提供 `Retry-After` 时会优先遵守；否则使用从 1 秒开始、单次最多 30 秒的指数退避。 +进入下一次尝试前，CCR 会对每个触发 Fallback 的失败进行等待，包括网络错误。上游提供正数 `Retry-After` 时会优先遵守；否则使用从 1 秒开始、单次最多 30 秒的指数退避。 **失败降级目标** 对 `4xx` 也会切换，是因为模型不存在、鉴权或供应商侧拒绝等错误可能只影响当前目标。切换后如果备用模型可用，请求仍然可以成功。 diff --git a/docs/src/content/docs/zh/configuration/toolhub.md b/docs/src/content/docs/zh/configuration/toolhub.md new file mode 100644 index 0000000..defadd0 --- /dev/null +++ b/docs/src/content/docs/zh/configuration/toolhub.md @@ -0,0 +1,167 @@ +--- +title: ToolHub +pageTitle: ToolHub +eyebrow: 详细配置 +lead: 将多个 MCP server 收束成一个紧凑入口，让 Agent 按任务懒加载需要的工具，减少工具列表占用的上下文。 +--- + +## 适用场景 + +当你接入的 MCP server 越来越多时，直接把所有工具暴露给 Agent 会让工具列表变长，也更容易选错工具。ToolHub 会向 Agent 暴露一个 `ccr-toolhub` MCP server，里面只有两个元工具： + +- `tool_hub.resolve`：根据用户任务和上下文检索可用 MCP 工具。 +- `tool_hub.invoke`：调用已经被本轮任务选中的真实 MCP 工具。 + +它适合把不常用但偶尔会用到的工具统一懒加载，在任务真正需要时才交给 Agent 使用。核心价值是节省上下文：避免把大量低频工具常驻在 Agent 的工具列表里，减少上下文占用和选错工具的概率。简单本地代码、文件或普通聊天任务通常不需要经过 ToolHub。 + +## 工作方式 + +1. 在 **设置 → ToolHub** 中启用 ToolHub。 +2. 选择一个已配置模型作为 **检索模型**。它负责阅读 MCP 工具目录并挑选本轮任务需要的工具；建议使用 `deepseek-v4-flash`，或同等 Flash 价位、响应稳定的轻量模型。 +3. 添加或导入后端 MCP server。ToolHub 支持 `stdio`、`streamable-http` 和 `sse`。 +4. 从 CCR 打开 Claude Code 或 Codex。CCR 会在对应 Agent 配置中写入 `ccr-toolhub`。 +5. Agent 遇到外部服务、已安装 MCP 能力或业务 API 相关请求时，先调用 `tool_hub.resolve`，再用 `tool_hub.invoke` 执行选中的工具。 + +ToolHub 会合并 **ToolHub 页面配置的 MCP servers** 和兼容旧配置中的全局 Agent MCP servers，并自动排除 `ccr-toolhub` 自身，避免递归调用。 + +## 内置浏览器自动化 + +在 CCR Desktop 中启用 ToolHub，并打开 **内置浏览器自动化** 开关后，Agent 可以使用桌面端内置浏览器完成网页操作。不需要在 ToolHub 页面手动添加浏览器后端，也不需要额外 API Key；CCR 会使用本地网关鉴权连接它。 + +启用步骤： + +1. 打开 **设置 → ToolHub**，先开启 **启用 ToolHub**。 +2. 在同一页打开 **内置浏览器自动化** 开关。该开关只会在 ToolHub 已启用时显示。 +3. 保存设置后，从 CCR 重新打开 Claude Code 或 Codex，让新的 Agent 实例加载最新配置。 + +> 已经运行中的 Agent 实例通常不会立即拿到这个开关变化。要让现有会话生效，请重启该 Agent 实例，或使用 Agent 自身能力重启 ToolHub。 + +内置浏览器自动化适合让 Agent 处理需要真实浏览器状态的任务，例如打开网站、读取页面、填写表单、点击按钮、在页面中滚动，或在没有专用业务能力时完成下单、预约、查询、结账等网页流程。开启后 Agent 可以： + +- 打开或附加内置浏览器标签页、导航 URL 或搜索词。 +- 读取页面内容，并找到按钮、链接、输入框等页面元素。 +- 点击、输入、选择、按键和滚动页面元素。 +- 等待页面加载、跳转、弹窗或人类接管结果，再继续后续步骤。 +- 在登录、验证码、CAPTCHA、人机验证或人工确认时请求用户接管。 + +当网页流程需要登录、验证码、CAPTCHA、人机验证或人工确认时，CCR 会显示内置浏览器窗口，并在顶部工具栏提示用户需要完成的步骤。用户点击 **Done** 或 **Hide** 后，Agent 会收到结果并继续执行。接管等待最长支持 10 分钟。 + +### Chrome 登录态导入扩展 + +内置浏览器自动化还支持把系统 Chrome 中指定域名的登录状态导入 CCR 内置浏览器。这样 Agent 处理网页任务时，可以复用你已经在 Chrome 中登录过的网站状态。该能力需要安装仓库里的 Chrome 解包扩展：`extension/chrome`。 + +安装方式： + +1. 在 Chrome 打开 `chrome://extensions`。 +2. 开启 **Developer mode**。 +3. 点击 **Load unpacked**。 +4. 选择仓库中的 `extension/chrome` 目录。 + +导入流程： + +1. 当任务需要复用 Chrome 登录状态时，Agent 会请求导入；用户也可以在 CCR 内置浏览器工具栏点击钥匙按钮主动发起。 +2. CCR 创建一次性导入任务，并打开确认页。如果默认浏览器不是 Chrome，请把确认页 URL 复制到已安装扩展的 Chrome 中打开。 +3. 用户在确认页检查要导入的域名，点击 **Confirm and Import**。 +4. Chrome 扩展读取这些域名的 cookies 和 localStorage，提交给 CCR；完成后 Agent 可以继续使用内置浏览器执行任务。 + +扩展只读取 CCR 导入任务列出的域名，不会枚举 Chrome 中的全部 cookies。读取 localStorage 时，扩展会临时打开对应 origin 的非激活标签页，读取后自动关闭。若确认页提示扩展没有站点访问权限，请在 Chrome 扩展设置中允许该扩展访问目标域名，然后重新加载解包扩展再重试。 + +> 注意：内置浏览器自动化依赖 CCR Desktop 的内置浏览器，只在桌面端可用。CLI、服务器部署或纯 Web 环境没有这项内置能力，请改用外部浏览器自动化 MCP server。 + +## 配置项 + +| 配置项 | 说明 | +| --- | --- | +| 启用 ToolHub | 开启后才会向 Agent 暴露 `ccr-toolhub`。如果没有可用后端 MCP server，CCR 不会生成 ToolHub MCP 配置。 | +| 内置浏览器自动化 | 仅在启用 ToolHub 后显示。开启后让 Agent 可以使用 CCR Desktop 的内置浏览器完成网页操作。 | +| 检索模型 | 从已配置供应商模型中选择。建议使用 `deepseek-v4-flash`，或同等 Flash 价位、响应稳定、工具理解能力足够的轻量模型。 | +| 最大工具数 | 单次解析最多返回的工具数量，范围 `1` 到 `20`，默认 `10`。 | +| 超时毫秒 | ToolHub 解析和调用的基础超时时间，范围 `8000` 到 `300000`，默认 `60000`。如果后端 MCP server 需要更长 request timeout，CCR 会按后端超时自动抬高实际调用超时。 | +| MCP servers | 后端工具来源。每个 server 需要唯一名称，并配置 transport、命令或 URL、环境变量、headers 和超时。 | +| Import JSON | 导入常见 MCP JSON。支持根对象、数组、`mcpServers` 或 `mcp_servers`。 | + +## 添加 MCP Server + +### stdio + +`stdio` 适合本地命令行 MCP server。需要填写： + +- **Command**：启动命令，例如 `npx`、`node`、`python`。 +- **Arguments**：命令参数。 +- **Working directory**：可选工作目录。 +- **Stdio message mode**：默认 `content-length`，如果 server 使用逐行 JSON，选择 `newline-json`。 +- **Environment variables**：只放这个 MCP server 需要的变量。 + +### streamable-http / sse + +远程 MCP server 需要填写 URL。鉴权可以使用： + +- **API key**：直接保存在配置中。 +- **API key env**：从环境变量读取。 +- **Headers**：添加自定义请求头。 + +如果远程服务启动慢或请求耗时长，可以单独调高该 server 的 **Startup timeout** 或 **Request timeout**。 + +## JSON 示例 + +桌面 App 的 SQLite 配置是当前生效来源，建议优先通过 UI 修改。下面字段适用于备份、迁移或排查时理解 ToolHub 配置结构： + +```json +{ + "toolHub": { + "enabled": true, + "browserAutomation": true, + "llm": { + "apiKey": "sk-...", + "baseUrl": "https://api.openai.com/v1", + "model": "gpt-5-mini" + }, + "maxTools": 10, + "requestTimeoutMs": 60000, + "mcpServers": [ + { + "name": "filesystem", + "transport": "stdio", + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"], + "env": {}, + "stdioMessageMode": "content-length", + "requestTimeoutMs": 30000, + "startupTimeoutMs": 600000 + } + ] + } +} +``` + +导入 MCP JSON 时也可以使用常见格式： + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + } + } +} +``` + +## 与 Fusion MCP 的区别 + +| 能力 | ToolHub | Fusion 自定义 MCP 工具 | +| --- | --- | --- | +| 使用入口 | Agent 侧的 `ccr-toolhub` MCP server | 某个 Fusion 模型内部能力 | +| 工具选择 | 每个任务动态检索并返回工具包 | 模型配置中固定选择工具 | +| 适合场景 | MCP server 很多、工具目录经常变化、希望 Agent 自主发现能力 | 给某个模型补一组明确工具 | +| 可见范围 | 通过 CCR 打开的 Claude Code 或 Codex 配置 | 选择该 Fusion 模型的路由或 Agent | + +## 排查 + +- Agent 看不到 ToolHub：确认已启用 ToolHub，并且至少配置了一个后端 MCP server 或开启了 **内置浏览器自动化**，然后从 CCR 重新打开 Claude Code 或 Codex。 +- 提示缺少检索模型或 API Key：在 **检索模型** 中选择已配置模型，并确认供应商凭据可用。 +- Agent 无法使用内置浏览器自动化：确认正在使用 CCR Desktop，并且已在 **设置 → ToolHub** 中开启 **内置浏览器自动化**，然后从 CCR 重新打开 Claude Code 或 Codex。CLI、服务器部署或纯 Web 环境没有这项内置能力。 +- Chrome 登录态导入确认页一直等待扩展：确认已在 Chrome 中加载 `extension/chrome` 解包扩展，并允许扩展访问要导入的目标域名。如果默认浏览器不是 Chrome，请手动把确认页 URL 复制到 Chrome。 +- 解析不到工具：检查 MCP server 是否能正常列出工具，工具名称和描述是否足够清楚，必要时提高 **最大工具数**。 +- 调用超时：分别检查 ToolHub 的 **超时毫秒** 和单个 MCP server 的 request/startup timeout。 +- 导入失败：检查 JSON 是否有效、server 名称是否重复、`stdio` 是否有 command，远程 transport 是否有 URL。 diff --git a/docs/src/i18n/content.ts b/docs/src/i18n/content.ts index 8569685..58a9dc1 100644 --- a/docs/src/i18n/content.ts +++ b/docs/src/i18n/content.ts @@ -60,25 +60,33 @@ export const docsContent = { configuration: { sidebarGroups: [ { - label: "详细配置", + label: "主页页面", icon: "wand", items: [ "概览仪表盘", "供应商配置", "一键导入供应商", - "路由配置", - "日志&观测", - "Fusion 组合模型", "Agent配置", + "路由配置", + "Fusion 组合模型", "API 密钥", + "日志&观测", "服务配置", - "托盘配置", "扩展机制", - "Bot 与 IM 接力 Agent", - "配置数据库位置", ], active: "概览仪表盘", }, + { + label: "设置页", + icon: "book", + items: [ + "ToolHub", + "Bot 与 IM 接力 Agent", + "配置数据库位置", + "托盘配置", + ], + active: "", + }, ], expandableSidebarItems: ["Fusion 组合模型", "Bot 与 IM 接力 Agent"], sidebarChildren: { @@ -105,6 +113,7 @@ export const docsContent = { 内置图像能力: "/configuration/fusion-vision/", 内置联网搜索: "/configuration/fusion-web-search/", "自定义 MCP 工具": "/configuration/fusion-mcp-tool/", + ToolHub: "/configuration/toolhub/", Agent配置: "/configuration/profile/", "API 密钥": "/configuration/api-keys/", 服务配置: "/configuration/server/", @@ -208,25 +217,33 @@ export const docsContent = { configuration: { sidebarGroups: [ { - label: "Detailed Configuration", + label: "Main Pages", icon: "wand", items: [ "Overview Dashboard", "Provider Config", "One click import", - "Routing Config", - "Logs & Observability", - "Fusion Models", "Agent Config", + "Routing Config", + "Fusion Models", "API Keys", + "Logs & Observability", "Server", - "Tray Configuration", "Extension Mechanism", - "Bots And IM Agent Relay", - "Config Database Location", ], active: "Overview Dashboard", }, + { + label: "Settings Pages", + icon: "book", + items: [ + "ToolHub", + "Bots And IM Agent Relay", + "Config Database Location", + "Tray Configuration", + ], + active: "", + }, ], expandableSidebarItems: ["Fusion Models", "Bots And IM Agent Relay"], sidebarChildren: { @@ -243,6 +260,7 @@ export const docsContent = { "Built-In Vision": "/en/configuration/fusion-vision/", "Built-In Web Search": "/en/configuration/fusion-web-search/", "Custom MCP Tool": "/en/configuration/fusion-mcp-tool/", + ToolHub: "/en/configuration/toolhub/", "Agent Config": "/en/configuration/profiles/", "API Keys": "/en/configuration/api-keys/", Server: "/en/configuration/server/", diff --git a/docs/src/layouts/DocsLayout.astro b/docs/src/layouts/DocsLayout.astro index 6be2c33..60d714c 100644 --- a/docs/src/layouts/DocsLayout.astro +++ b/docs/src/layouts/DocsLayout.astro @@ -291,6 +291,11 @@ const sidebarCloseLabel = locale === "zh" ? "关闭目录" : "Close navigation";