用途:该技能面向维护 Switchyard 编码智能体启动器(switchyard launch claude / codex / openclaw 及 switchyard/cli/launchers/ 目录)的场景,帮助理解启动器如何把 profile 支撑的 SwitchyardApp 值包装成外部 CLI 可用的运行时。
主要能力与结构:单模型启动通过 build_tier_passthrough_switchyard(...) 构建直通 profile;多路由启动用 load_route_bundle_table(...) 加载路由 YAML 并返回 RouteTable;FastAPI 应用由 build_switchyard_app(...) 提供单 profile 运行时或 RouteTable。启动器代码不应重新引入 SwitchyardRecipes、工厂注册表、中间件包或请求/响应管道包装器。
使用方式:--routing-profiles 是位于子命令之前的全局 switchyard 标志,--model 保留在启动器子命令上,二者在需要单一初始模型的入口互斥。示例:switchyard launch claude --model nvidia/moonshotai/kimi-k2.5;switchyard --routing-profiles ~/.config/switchyard/profiles.yaml launch claude;switchyard --routing-profiles routes.yaml serve --port 4000。OpenRouter 走 OpenAI 兼容路径,可一次性传 --base-url https://openrouter.ai/api/v1 --api-key "$OPENROUTER_API_KEY",或用 switchyard configure 保存默认值;启动器子命令不假设接受 --provider。
路由行为:RouteTable 把入站请求模型值映射到 profile 运行时。type: model 仅注册 YAML 键别名;passthrough 注册键与发现的直连模型;random_routing、deterministic、stage_router 注册路由键及直连强弱直通项;plan_execute 注册路由键与执行器直通,规划器为内部逻辑;latency_service 与 noop 注册路由键。intake 等仅运行时钩子以 kwargs 传给路由表构建器,YAML 不声明任意 Python 处理器。
限制与反模式:不要为路由策略新增启动器标志,应加路由字段;不要在启动器代码中手动构建 Switchyard(...);不要新增 stats 收集器,应传入一个 StatsAccumulator;路由后端应放在 switchyard/lib/ 或 Rust 组件;避免在启动器模块顶层导入重包,需惰性导入以支持精简安装下的 --help。测试可运行 uv run pytest tests/test_launch_claude.py tests/test_launch_codex.py tests/test_launch_openclaw.py tests/test_launch_route_builder.py tests/test_user_config.py tests/test_model_discovery.py tests/test_verify.py tests/test_route_bundle.py -v -o addopts=。建议编辑前配合 switchyard-codebase-exploration,编辑后配合 switchyard-testing-ci。