Files
CLIProxyAPI/internal/pluginhost/model_router.go
sususu98 87132e54d7 feat(plugin): add ModelRouter before auth with single-slot routing targets (#3865)
* feat(plugin): add ModelRouter before auth with single-slot routing targets

## Motivation

Plugins that need to change execution based on the **original inbound request**
(protocol format, raw body, headers, query, stream flag, metadata, etc.) often
resorted to virtual/trampoline models or routing inside interceptors. This
commit adds **ModelRouter**: a pluggable layer **before** model-to-provider
resolution and AuthManager credential selection, so plugins can declare who
executes a request without spoofing the client model name.

This is a **new capability**, not a bugfix on the existing chain. With no
ModelRouter plugins loaded, behavior matches upstream.

## Pipeline placement

- `execute`, `stream`, and `count` (and image paths via AuthManager) call
  `applyModelRouter()` before building `coreexecutor.Request`.
- Routing runs **before** the request interceptor (before auth), so routers see
  the client’s original context. After a plugin executor is chosen, the existing
  **after-auth interceptor → response/stream interceptor** chain still applies.
- Internal `ExecuteModel` / `ExecuteModelStream` (host callbacks) support
  `SkipRouterPluginID` so nested calls do not re-enter the same router.

## Routing API (single slot, mutually exclusive)

`ModelRouteResponse` uses **one target slot** to avoid ambiguity when both
`TargetExecutorPluginID` and `TargetProvider` were set and the host ignored one:

| Field | Meaning |
|-------|---------|
| `Handled` | `false`: this router declines; try the next router or default path |
| `TargetKind` | `self` \| `executor` \| `provider` (pick one) |
| `Target` | `self`/`executor`: plugin ID; `provider`: built-in provider key |
| `TargetModel` | Optional on `provider` only; empty keeps client `RequestedModel` |
| `Reason` | Optional diagnostic text |

- **self**: the router plugin’s own executor (`Target` normalized to the router’s plugin ID).
- **executor**: another plugin’s executor; host pre-checks with `executorPluginReady()`
  (executor declared and provider identifier resolvable) to avoid handled routes that 500 at execution.
- **provider**: skip registry model resolution; fixed built-in AuthManager path; optional
  `TargetModel` for execution model only—**does not** change outward requested-model metadata.

Routers run in **descending plugin priority** (tie-break: ascending plugin ID). Panic, error,
invalid target, or unavailable executor/provider → log and **fall through to the next router**;
if none handle, use the original provider+auth flow.

## Context exposed to routers

`ModelRouteRequest` includes:

- `SourceFormat`, `RequestedModel`, `Stream`
- `Headers`, `Query`, `Body` (defensive copies)
- `Metadata` (best-effort read-only context snapshot)
- `AvailableProviders`: built-in provider keys with at least one **non-disabled** auth
  (`AuthManager.AvailableProviders()`). **Does not** reflect per-model cooldown or transient
  unavailability—treat as an optimistic snapshot.

Adds `AuthManager.HasProviderAuth()` and `AvailableProviders()`, excluding `Disabled` and
`StatusDisabled` auths consistently with credential selection.

## Host and RPC

- Go plugins: `pluginapi.ModelRouter` + `RouteModel()`.
- RPC plugins: `pluginabi.MethodModelRoute` (`model.route`), capability flag `model_router`.
- `pluginhost.Host` implements `RouteModel` / `RouteModelExcept`; handlers use
  `SetModelRouterHost` or a `PluginHost` type assertion; **direct executor** paths use
  `ExecutePluginExecutor*` / `CountPluginExecutor`.
- No bundled example ModelRouter plugin; capability is active only when a third-party plugin
  declares `model_router` and loads.

## Plugin RPC schema (policy A, upstream-aligned)

- `pluginabi.SchemaVersion` stays **1**: capability additions (`model_router`, `model.route`)
  do not bump the number; increment only on breaking RPC JSON changes.
- Host sends `schema_version` at register; reject only if the plugin declares a **higher**
  version than the host.
- No unpublished “ModelRouter requires schema ≥ 3” gate (v3 single-slot API was never public).
- Existing plugins and examples without `model_router` (`schema_version: 1`) need no changes.
- RPC ModelRouter: `schema_version: 1` + `model_router: true` + implement `model.route`.

## Path consistency within this commit

- Provider routes reuse image-only model checks (e.g. `gpt-image-2`) on the normalized model,
  same as the default AuthManager path.
- `count` aligned with execute/stream: `SkipRouterPluginID`, query/headers injection,
  interceptor skip semantics.
- Handlers: `modelRoutersEnabled` treats hosts without `HasModelRouters` as disabled
  (same as before ModelRouter existed); `pluginhost.Host` implements the detector.
- API docs: `ModelRouter` explicitly includes built-in **provider** targets (in addition to
  plugin executors and the router’s own executor).

## Testing

go test ./internal/pluginhost ./sdk/api/handlers ./sdk/pluginapi ./sdk/pluginabi ./sdk/cliproxy/auth
go build -o test-output ./cmd/server && rm test-output
go test ./...

* fix(handlers): address ModelRouter review feedback

- Use modelExecutionQuery for plugin executor and AuthManager paths so
  inbound URL query matches router/header behavior
- Guard queryFromContext when gin Request.URL is nil
- Read plugin executor stream chunks via nextStreamChunk to exit on cancel
- Drop redundant clonePluginMetadata on capability record meta

Tests cover query propagation, stream cancel, and nil URL safety.

* feat(plugin): add Claude web search router example

Add a Claude Code web_search ModelRouter example that can route matching Claude requests through Antigravity, Codex, xAI, or Tavily.

The plugin includes executor orchestration, backend fallback/penalty handling, Tavily API key support, Claude-compatible response assembly, stream forwarding, and focused unit coverage for detection, fallback routing, model resolution, penalties, stream forwarding, and Tavily behavior.

Verification: go test -count=1 ./... in examples/plugin/claude-web-search-router/go; go build -buildmode=c-shared for the plugin; go build ./cmd/server; live local CPA curl coverage for plugin load, four explicit routes, fallback, and Codex spark routing.

* fix(pluginhost): validate executor routes before fallback

* fix(pluginhost): skip oauth-only executor routes
2026-06-16 19:15:34 +08:00

156 lines
5.2 KiB
Go

package pluginhost
import (
"bytes"
"context"
"strings"
"github.com/router-for-me/CLIProxyAPI/v7/sdk/pluginapi"
log "github.com/sirupsen/logrus"
)
func (h *Host) RouteModel(ctx context.Context, req pluginapi.ModelRouteRequest) (pluginapi.ModelRouteResponse, bool) {
return h.RouteModelExcept(ctx, req, "")
}
func (h *Host) HasModelRouters() bool {
return h.HasModelRoutersExcept("")
}
func (h *Host) HasModelRoutersExcept(skipPluginID string) bool {
if h == nil {
return false
}
skipPluginID = strings.TrimSpace(skipPluginID)
for _, record := range h.Snapshot().records {
if record.plugin.Capabilities.ModelRouter != nil && !h.isPluginFused(record.id) && record.id != skipPluginID {
return true
}
}
return false
}
func (h *Host) RouteModelExcept(ctx context.Context, req pluginapi.ModelRouteRequest, skipPluginID string) (pluginapi.ModelRouteResponse, bool) {
if h == nil {
return pluginapi.ModelRouteResponse{}, false
}
skipPluginID = strings.TrimSpace(skipPluginID)
req.AvailableProviders = h.availableProvidersSnapshot()
for _, record := range h.Snapshot().records {
router := record.plugin.Capabilities.ModelRouter
if router == nil || h.isPluginFused(record.id) || record.id == skipPluginID {
continue
}
nextReq := cloneModelRouteRequest(req)
nextReq.Plugin = clonePluginMetadata(record.meta)
nextReq.PluginID = record.id
resp, ok := h.callModelRouter(ctx, record.id, router, nextReq)
if !ok || !resp.Handled {
continue
}
resp, valid := normalizeModelRouteResponse(record.id, resp)
if !valid {
log.WithFields(log.Fields{"plugin_id": record.id, "target_kind": resp.TargetKind, "target": resp.Target}).Warn("pluginhost: model router returned invalid target")
continue
}
switch resp.TargetKind {
case pluginapi.ModelRouteTargetProvider:
if !h.HasBuiltinProvider(resp.Target) {
log.WithFields(log.Fields{"plugin_id": record.id, "target_provider": resp.Target}).Warn("pluginhost: model router returned unavailable provider")
continue
}
return resp, true
case pluginapi.ModelRouteTargetSelf, pluginapi.ModelRouteTargetExecutor:
if !h.executorPluginReady(resp.Target, nextReq) {
log.WithFields(log.Fields{"plugin_id": record.id, "target_plugin_id": resp.Target}).Warn("pluginhost: model router returned unavailable executor plugin")
continue
}
return resp, true
default:
log.WithFields(log.Fields{"plugin_id": record.id, "target_kind": resp.TargetKind}).Warn("pluginhost: model router returned unsupported target kind")
continue
}
}
return pluginapi.ModelRouteResponse{}, false
}
func (h *Host) callModelRouter(ctx context.Context, pluginID string, router pluginapi.ModelRouter, req pluginapi.ModelRouteRequest) (out pluginapi.ModelRouteResponse, ok bool) {
if h == nil || router == nil || h.isPluginFused(pluginID) {
return pluginapi.ModelRouteResponse{}, false
}
defer func() {
if recovered := recover(); recovered != nil {
h.fusePlugin(pluginID, "ModelRouter.RouteModel", recovered)
out = pluginapi.ModelRouteResponse{}
ok = false
}
}()
resp, errRoute := router.RouteModel(ctx, req)
if errRoute != nil {
log.WithField("plugin_id", pluginID).WithError(errRoute).Warn("pluginhost: model router failed")
return pluginapi.ModelRouteResponse{}, false
}
return resp, true
}
func normalizeModelRouteResponse(routerPluginID string, resp pluginapi.ModelRouteResponse) (pluginapi.ModelRouteResponse, bool) {
resp.TargetModel = strings.TrimSpace(resp.TargetModel)
switch resp.TargetKind {
case pluginapi.ModelRouteTargetSelf:
resp.Target = strings.TrimSpace(routerPluginID)
if resp.Target == "" {
return pluginapi.ModelRouteResponse{}, false
}
return resp, true
case pluginapi.ModelRouteTargetExecutor:
resp.Target = strings.TrimSpace(resp.Target)
if resp.Target == "" {
return pluginapi.ModelRouteResponse{}, false
}
return resp, true
case pluginapi.ModelRouteTargetProvider:
resp.Target = strings.ToLower(strings.TrimSpace(resp.Target))
if resp.Target == "" {
return pluginapi.ModelRouteResponse{}, false
}
return resp, true
default:
return pluginapi.ModelRouteResponse{}, false
}
}
func cloneModelRouteRequest(req pluginapi.ModelRouteRequest) pluginapi.ModelRouteRequest {
req.Headers = cloneHeader(req.Headers)
req.Query = cloneValues(req.Query)
req.Body = bytes.Clone(req.Body)
req.Metadata = cloneInterceptorMetadata(req.Metadata)
req.AvailableProviders = cloneStringSlice(req.AvailableProviders)
return req
}
// HasBuiltinProvider reports whether a built-in provider currently has at least one
// registered auth record.
func (h *Host) HasBuiltinProvider(provider string) bool {
if h == nil || h.authManager == nil {
return false
}
return h.authManager.HasProviderAuth(provider)
}
// BuiltinProviders returns built-in provider keys that currently have auth registered.
func (h *Host) BuiltinProviders() []string {
if h == nil || h.authManager == nil {
return nil
}
return h.authManager.AvailableProviders()
}
// availableProvidersSnapshot returns a defensive copy of BuiltinProviders for routing input.
func (h *Host) availableProvidersSnapshot() []string {
providers := h.BuiltinProviders()
if len(providers) == 0 {
return nil
}
return cloneStringSlice(providers)
}