使用说明

人工智能生态系统蜘蛛开关

MCP（模型上下文协议）服务器，使代理能够从 ai-lib生态系统.

特性

协议驱动：从ai协议清单（ARCH-001）加载的所有模型配置
多提供商支持：在OpenAI、Anthropic、谷歌、DeepSeek等之间切换
运行时不可知：使用ai-lib-python SDK进行统一模型交互
符合MCP标准：通过stdio传输实现标准MCP工具
能力发现：查询可用模型及其功能
运行时配置文件信号：公开上层路由策略引擎的运行时能力配置文件
本地准备提示: list_models 包括每个提供程序的API密钥存在和代理就绪情况
显式退出路径: exit_switcher 重置切换器运行时/状态以进行干净回退
自动协议设置：自动检测本地 ai-protocol 路径和集合 AI_PROTOCOL_PATH 对于当前流程
官方Dist同步：官方尽力同步 dist/v1/*.json 快照到本地 ai-protocol/dist/v1
预制能力指数 （0.7.0）：离线 spiderswitch index build +MCP启动时快速加载JSON（无需重新解析YAML）
智能路由: recommend_model / auto_switch 符合当地的BYOK政策； query_index 用于基于能力的查找
主观体验: record_experience 积累质量/速度/价值评级，以提高未来的排名
代理部署手册: spiderswitch setup 一次性安装；看见 docs/AGENT_DEPLOY_GUIDE.md

快速开始

代理人： 看 docs/AGENT_DEPLOY_GUIDE.md 对于自包含的部署脚本（安装→ 协议→ MCP配置→ 验证）。跑 spiderswitch setup --client cursor 对于单次拍摄设置。

安装

来自PyPI （版本发布后推荐）：

pip install spiderswitch
# or pin a version:
pip install "spiderswitch>=0.7.0"

PyPI：https://pypi.org/project/spiderswitch/--如果最新的PyPI版本在GitHub之后，请从松开车轮相反（参见 docs/PUBLISHING.md).

来源（开发）：

# Clone the repository
git clone https://github.com/ailib-official/spiderswitch.git
cd spiderswitch

# Install dependencies
pip install -e .

环境设置

设置API密钥：

export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

推荐的提供程序密钥映射：

提供者	环境变量
openai	`OPENAI_API_KEY`
人因论	`ANTHROPIC_API_KEY`
谷歌 `GOOGLE_API_KEY` 或 `GEMINI_API_KEY`
deepseek	`DEEPSEEK_API_KEY`
科恩	`COHERE_API_KEY`
米斯特拉尔	`MISTRAL_API_KEY`

安全说明：

更喜欢环境变量而不是传递 api_key 在工具论证中。
服务器会编辑日志中的敏感字段，但在参数中传递机密仍然会增加客户端跟踪中的暴露风险。

可选的运行时环境控件：

SPIDERSWITCH_SYNC_ON_INIT=1 在运行时初始化期间启用dist-sync（默认：禁用）。
SPIDERSWITCH_SYNC_DIST=0 在显式调用dist-sync时禁用它。
AI_PROTOCOL_DIST_BASE_URL 覆盖原始dist源代码（默认的GitHub官方原始URL）。
AI_PROTOCOL_DIST_API_BASE_URL 以覆盖GitHub API列出的模型/提供商的源dist-json。
SPIDERSWITCH_LIST_CACHE_TTL_SEC 为了 list_models 缓存TTL（默认值： 5).
SPIDERSWITCH_STATUS_CACHE_TTL_SEC 为了 get_status 缓存TTL（默认值： 2).
SPIDERSWITCH_INDEX_PATH 覆盖持久化能力索引位置（默认值： ~/.spiderswitch/index/capability-index.json).
SPIDERSWITCH_INDEX_MAX_AGE_SEC 当加载的索引超过TTL（秒）时发出警告。
SPIDERSWITCH_INDEX_REBUILD_ON_START=1 如果索引文件丢失，则在启动时从YAML重建（慢速回退）。

一键安装（插件市场风格）

bash scripts/install_one_click.sh

然后建立ai协议， 预先构建能力指数，并验证：

spiderswitch setup --client cursor          # protocol + MCP config + index build + doctor
# or manually:
spiderswitch protocol setup
export AI_PROTOCOL_PATH="$HOME/.spiderswitch/ai-protocol"
spiderswitch index build                    # persist ~/.spiderswitch/index/capability-index.json
spiderswitch init --client cursor --output ~/.cursor/mcp.spiderswitch.json --force
spiderswitch doctor --json

离线安装（气隙/内联网）

从本地控制盘或本地源代码目录安装：

bash scripts/install_offline.sh /path/to/spiderswitch-<version>-py3-none-any.whl
# or
bash scripts/install_offline.sh /path/to/spiderswitch-source

配置

添加到MCP客户端配置中：

对于OpenCode

配置文件： ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spiderswitch": {
      "type": "local",
      "command": ["python3", "-m", "spiderswitch.server"],
      "enabled": true,
      "environment": {
        "AI_PROTOCOL_PATH": "/path/to/ai-protocol",
        "OPENAI_API_KEY": "sk-your-key",
        "ANTHROPIC_API_KEY": "sk-ant-your-key",
        "DEEPSEEK_API_KEY": "sk-your-key"
      }
    }
  }
}

适用于克劳德桌面/光标

配置文件： ~/.config/claude-desktop/config.json 或 ~/.cursor/mcp.json

{
  "mcpServers": {
    "spiderswitch": {
      "command": "python3",
      "args": ["-m", "spiderswitch.server"],
      "env": {
        "AI_PROTOCOL_PATH": "/path/to/ai-protocol"
      }
    }
  }
}

验证（OpenCode）

# List loaded MCP servers
opencode mcp list

# Expected output:
# ✓ spiderswitch connected
#   python3 -m spiderswitch.server

用法

在您的代理中，调用MCP工具：

# List available models
models = await mcp_client.call_tool("list_models", {})

# Switch to Claude 3.5 Sonnet
await mcp_client.call_tool(
    "switch_model",
    {"model": "anthropic/claude-3-5-sonnet"}
)

# Check current status
status = await mcp_client.call_tool("get_status", {})

可用的MCP工具

1.开关型号

切换到不同的AI模型/提供商。

参数：

model （string，必填）：模型标识符（例如。， openai/gpt-4o, anthropic/claude-3-5-sonnet)
api_key （字符串，可选）：显式API键（重写环境变量；不建议用于生产）
base_url （字符串，可选）：用于测试/模拟的自定义基URL
runtime_id （字符串，可选）：由上层策略选择的运行时目标

退货：

{
  "status": "success",
  "data": {
    "id": "anthropic/claude-3-5-sonnet",
    "provider": "anthropic",
    "capabilities": ["streaming", "tools", "vision"],
    "proxy_status": {
      "provider": "anthropic",
      "proxy_required_guess": false,
      "proxy_configured": false,
      "configured_proxy_env_vars": [],
      "hint": null
    },
    "warnings": []
  },
  "message": "Successfully switched to anthropic/claude-3-5-sonnet"
}

2.列表模型

列出注册提供商的所有可用型号。

参数：

filter_provider （字符串，可选）：按提供者ID筛选
filter_capability （字符串，可选）：按能力筛选(streaming, tools, vision, embeddings, audio)
runtime_id （字符串，可选）：由上层策略选择的运行时目标

退货：

{
  "status": "success",
  "data": {
    "count": 2,
    "runtime_profile": {
      "runtime_id": "python-runtime",
      "language": "python",
      "supports": ["model_switching", "capability_filtering", "provider_manifest_loading"]
    },
    "models": [
      {
        "id": "openai/gpt-4o",
        "provider": "openai",
        "capabilities": ["streaming", "tools", "vision"],
        "api_key_status": {
          "provider": "openai",
          "has_api_key": true,
          "expected_env_vars": ["OPENAI_API_KEY"],
          "configured_env_vars": ["OPENAI_API_KEY"]
        },
        "proxy_status": {
          "provider": "openai",
          "proxy_required_guess": true,
          "proxy_configured": false,
          "configured_proxy_env_vars": [],
          "hint": "This provider may require proxy access in your network region. Set HTTPS_PROXY/HTTP_PROXY in the MCP server process environment if needed."
        }
      },
      {
        "id": "anthropic/claude-3-5-sonnet",
        "provider": "anthropic",
        "capabilities": ["streaming", "tools", "vision"]
      }
    ],
    "filtered": {
      "require_api_key": false,
      "provider": null,
      "capability": null
    }
  }
}

3.获取状态

获取当前模型状态和配置。

参数：

runtime_id （字符串，可选）：查询特定运行时范围内的状态

退货：

{
  "status": "success",
  "data": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet",
    "capabilities": ["streaming", "tools", "vision"],
    "runtime_profile": {
      "runtime_id": "python-runtime",
      "language": "python",
      "supports": ["model_switching", "capability_filtering", "provider_manifest_loading"]
    },
    "is_configured": true,
    "connection_epoch": 3,
    "last_switched_at": "2026-03-02T09:00:00+00:00"
  }
}

4.出口切换器

显式重置spiderswitch状态和运行时客户端。

参数：

runtime_id （字符串，可选）：作用域重置的运行时id
scope （字符串，可选）： all （默认）或 runtime

退货：

{
  "status": "success",
  "data": {
    "exited": true,
    "status": {
      "provider": null,
      "model": null,
      "is_configured": false
    }
  }
}

5.推荐型号

使用本地策略为当前任务推荐最佳模型（BYOK，无上游API调用）。

参数：

task_hint （字符串，可选）： chat, code, reasoning, vision, summarize, cheap, quality （默认值 chat)
tier （字符串，可选）： economy, balanced, premium （默认值 balanced)
required_capabilities （阵列，可选）：额外所需的功能（例如。， tools, vision)
prefer_provider （字符串，可选）：限制为单个提供程序
runtime_id （字符串，可选）：由上层策略选择的运行时目标

返回所选模型、排名的备选方案、评分原因和定价，无需切换。

6.自动开关

在一次调用中推荐并切换到当前任务的最佳模型（BYOK，本地策略）。

参数： 与相同的路由输入 recommend_model，加 api_key, base_url （可选，转发到交换机）。

返回带有嵌入式的切换模型数据 recommendation 有效载荷。

7.查询索引

按结构化需求（能力、方面、标签、层次、主观得分）查询预构建的能力指数。

参数：

required_capabilities, required_facets, required_tags （数组，可选）
provider, tier, task_hint （可选）
ready_only （布尔值，默认值 true --仅限BYOK型号）
min_subjective_score （可选）
limit （可选，默认 20)

需要持久化索引(spiderswitch index build).MCP启动直接加载它，而无需重新解析YAML。

8.记录经验

记录模型的主观评分（1-5）。累积分数影响 query_index 以及路由排名。

参数：

model_id （必填）
quality, speed, value （可选，1-5）
task_hint （可选）

CLI（对代理友好）

命令	目的
`spiderswitch serve`	运行MCP stdio服务器
`spiderswitch setup --client cursor`	一键：协议+MCP配置+ 索引构建 +医生
`spiderswitch index build`	预构建能力指数（对cron友好）
`spiderswitch index`	加载持久化索引摘要（JSON，快速）
`spiderswitch doctor [--json]`	健康检查+修复提示
`spiderswitch info`	工具、提示、运行时配置文件（JSON）

看 docs/AGENT_DEPLOY_GUIDE.md 了解完整的部署策略。

快速注射（药剂指导）

spiderswitch内置导航，让特工们知道当和怎么切换模型，使用两种MCP本地机制：

服务器说明 --通过MCP传递 Server(instructions=...) 现场和大多数客户端在初始化过程中都会出现，因此操作策略会被注入自动进入代理的系统上下文（始终打开）。
MCP提示 --客户端/用户可以附加的可重用、参数化的模板需求。通过标准暴露 prompts/list 和 prompts/get 方法。

可用提示：

提示	论点	目的
`spiderswitch_guide`	（无）	注入系统级指南，使代理蜘蛛能够感知。
`route_task`	`task` （必填）， `task_hint`, `tier`	指示代理人 `auto_switch` 在回答之前，先找到具体任务的最佳模型

示例（伪MCP客户端）：

# Discover prompts
prompts = await mcp_client.list_prompts()

# Inject the guide once per session
guide = await mcp_client.get_prompt("spiderswitch_guide")
system_messages.extend(guide.messages)

# Or route a specific task to the best model
routed = await mcp_client.get_prompt(
    "route_task",
    {"task": "Refactor this module and add tests", "task_hint": "code", "tier": "premium"},
)
# routed.messages instructs the agent to call auto_switch(task_hint="code", tier="premium")

如果 task_hint/tier 被省略（或无效）， route_task 指示代理进行推断允许集合中的最佳提示： chat, code, reasoning, vision, summarize, cheap, quality.

API关键指南和故障排除

当 switch_model 由于缺少凭据而失败，响应包括：

provider：哪个提供程序缺少凭据
expected_env_vars：接受的环境变量名称
hint：可操作的设置说明

典型设置流程：

在MCP服务器进程环境中配置提供程序密钥。
如果您的客户端不支持热环境重新加载，请重新启动MCP服务器进程。
呼叫 switch_model.
证实 get_status.

ai lib错误分类（重试/回退信号）

当 switch_model 由于上游ai-lib-python错误而失败，响应重用ai-lib生态系统错误契约并包括 error.details.ai_lib_error 因此代理可以以编程方式做出反应：

{
  "status": "error",
  "error": {
    "type": "ModelSwitcherError",
    "code": "SPIDER-SWITCH-FAILED",
    "details": {
      "provider": "openai",
      "ai_lib_error": {
        "source": "ai-lib-python",
        "family": "RemoteError",
        "error_class": "rate_limited",
        "status_code": 429,
        "retryable": true,
        "fallbackable": true,
        "retry_after": 2.0,
        "request_id": "req-1"
      }
    }
  }
}

retryable：之后可以安全地重试相同的模型 retry_after 秒。
fallbackable：适合切换到其他型号/提供商。

运行时配置文件(runtime_profile.operational_metrics.ai_lib)同样报道检测到实时ai库版本、可选功能标志和支持的ai协议版本在运行过程中，为上层路由器提供准确的性能图。

与代理运行时的连接协调

此MCP服务器在内部管理模型客户端生命周期。为了避免与代理自己的连接管理器发生冲突：

将MCP切换器视为模型选择的控制平面。
让代理方观察 get_status.connection_epoch.
仅在以下情况下重建代理端缓存会话 connection_epoch 增加。

此模式可防止模型切换后过时的会话重用，并支持确定性同步。

运行时路由边界

spiderswitch仅使用显式运行时信号执行路由操作：

运行时能力模型通过以下方式公开 runtime_profile （运行时中立模式）。
运行时选择策略仍保留在上层应用程序中。
内置注册表/解析器仅解析 runtime_id 并且没有实施成本/质量/业务战略。

建筑

spiderswitch/
├── src/spiderswitch/
│   ├── server.py             # MCP server (tools + prompts + instructions)
│   ├── prompts.py            # Injectable agent guidance (instructions + MCP prompts)
│   ├── model_ids.py          # Shared model-id resolution (single source of truth)
│   ├── tools/                # MCP tool implementations
│   │   ├── switch.py         # switch_model tool
│   │   ├── list.py           # list_models tool
│   │   ├── status.py         # get_status tool
│   │   ├── reset.py          # exit_switcher tool
│   │   ├── recommend.py      # recommend_model tool
│   │   ├── auto_switch.py    # auto_switch tool
│   │   ├── query_index.py    # query_index tool
│   │   └── record_experience.py  # record_experience tool
│   ├── runtime/              # Runtime abstraction layer
│   │   ├── base.py           # Base runtime interface
│   │   ├── python_runtime.py # ai-lib-python implementation
│   │   └── registry.py       # Runtime registry/resolver
│   ├── policy/               # Local smart-routing policy engine
│   │   ├── engine.py         # Scoring/ranking
│   │   └── loader.py         # ai-protocol catalog loader
│   ├── index/                # Pre-built capability index (load at startup)
│   │   ├── store.py          # JSON persistence + protocol fingerprint
│   │   ├── builder.py        # Inverted indexes + query
│   │   └── experience.py     # Subjective experience store
│   ├── hints.py              # Heuristic error/fix catalog for agents
│   ├── validation.py         # Input validation + provider readiness
│   ├── response.py           # Unified MCP response format
│   ├── errors.py             # Error taxonomy + ai-lib error bridge
│   └── state.py              # State management
├── tests/                    # Test suite
└── pyproject.toml            # Project configuration

发展

运行测试

# Install test dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src/spiderswitch

使用模拟服务器进行测试

使用人工智能协议模拟:

# Start mock server
docker-compose up -d ai-protocol-mock

# Run with mock
MOCK_HTTP_URL=http://localhost:4010 python -m spiderswitch.server

代码风格

# Format code
ruff format src tests

# Lint
ruff check src tests

# Type check
mypy src

协议驱动设计（ARCH-001）

此服务器遵循ai-lib设计原则：

一切逻辑皆算子，一切配置皆协议

所有提供程序配置都从ai协议清单加载。没有硬编码特定于提供者的逻辑。添加新的提供程序只需要ai协议中的清单文件。

路由边界：

spiderswitch仅公开运行时/模型能力信号。
路由策略策略（成本/延迟/断路器/业务规则）属于上层应用程序。

确定性路由契约：

运行时解析顺序固定为 request runtime_id -> active state runtime_id -> default runtime.
重置支持作用域行为(scope=runtime)在不进行全局拆卸的情况下清除目标运行时。
合同测试 tests/test_runtime.py 验证解析器顺序和范围重置稳定性。

许可证

本项目根据以下任一方式获得许可：

Apache许可证，版本2.0(特许通行证或http://www.apache.org/licenses/LICENSE-2.0)
MIT许可证(许可证-麻省理工学院或http://opensource.org/licenses/MIT)

由您选择。

贡献

欢迎投稿！请确保：

代码遵循PEP 8并通过 ruff check
键入提示传递 mypy --strict
包括对新功能的测试
文档已更新

蜘蛛女巫 -MCP与ai lib相遇的地方。 🤖🔀

AI模型切换服务

使用说明

人工智能生态系统蜘蛛开关

特性

快速开始

安装

环境设置

一键安装（插件市场风格）

离线安装（气隙/内联网）

配置

对于OpenCode

适用于克劳德桌面/光标

验证（OpenCode）

用法

可用的MCP工具

1.开关型号

2.列表模型

3.获取状态

4.出口切换器

5.推荐型号

6.自动开关

7.查询索引

8.记录经验

CLI（对代理友好）

快速注射（药剂指导）

API关键指南和故障排除

ai lib错误分类（重试/回退信号）

与代理运行时的连接协调

运行时路由边界

建筑

发展

运行测试

使用模拟服务器进行测试

代码风格

协议驱动设计（ARCH-001）

相关项目

许可证

贡献

使用说明

人工智能生态系统蜘蛛开关

特性

快速开始

安装

环境设置

一键安装（插件市场风格）

离线安装（气隙/内联网）

配置

对于OpenCode

适用于克劳德桌面/光标

验证（OpenCode）

用法

可用的MCP工具

1.开关型号

2.列表模型

3.获取状态

4.出口切换器

5.推荐型号

6.自动开关

7.查询索引

8.记录经验

CLI（对代理友好）

快速注射（药剂指导）

API关键指南和故障排除

ai lib错误分类（重试/回退信号）

与代理运行时的连接协调

运行时路由边界

建筑

发展

运行测试

使用模拟服务器进行测试

代码风格

协议驱动设计（ARCH-001）

相关项目

许可证

贡献

相关 MCP

MCP 统一网关

协议桥接服务器

代理连接工具

游戏开发工具集线器

AI模型管理服务器

MCP接入点服务器