用途
switchback-free 用于维护 switchback 中的 sb-free 虚拟模型，使其回退（fallback）列表只包含 openrouter.ai、opencode.ai 等提供商中经验证的免费模型。
主要能力
- 检查 pi/opencode 设置中实际启用的提供商，仅查询活跃提供商的模型列表。
- 按各提供商参考文件记录的方法获取模型列表。
- 识别免费模型：名称以 :free 或 -free 结尾，或位于提供商已知免费名单中（如 opencode.ai 的 big-pickle）。优先使用实时模型列表数据，硬编码名单仅作特殊情况的回退。
- 验证候选模型是否出现在提供商的模型列表响应中。
- 清理陈旧名称：当前 sb-free 回退列表中已不再出现在模型列表里的硬编码名称会被移除；仍可解析但质量不佳的模型保留在列表中，并建议用户手动禁用（pi 中或 OpenCode 插件中使用 /switchback-disable <provider/model>），禁用记录持久化在 disabled.json 中，不会因技能重写回退列表而丢失。
- 写入配置：更新 switchback.yaml 中的 sb-free 虚拟模型，回退列表按提供商字母顺序、再按模型名确定性排序。
配置位置
唯一配置文件为 ~/.config/switchback/switchback.yaml，可用环境变量 SWITCHBACK_CONFIG_DIR 迁移整个目录。pi 的副本（如 ~/.pi/agent/switchback.yaml 或 <cwd>/.pi/switchback.yaml）会被忽略，不应写入；若存在此类遗留文件，应把其中条目移入共享文件。文件保存时须能解析和校验：加载器会在编辑损坏时抛错，models: 内重复的 id: 只保留第一条并警告。
决策模型
链路通过 decisionModel: 中的地址指定分类器（例如 decisionModel: typesafe/jev-latest 或 decisionModel: ollama/tev1:0.8b）；连接详情在无法从分类器目录解析时，存放在以同一地址为键的顶层 decisionModels: 映射中。没有 jev: 块。详见 docs/configuration.md → Decision model。
新增提供商
需创建 references/<provider-name>.md，包含：如何在 pi/opencode 中检查该提供商是否启用、如何查询其模型列表（端点或 CLI 命令）、已知免费模型后缀或特殊情况名称；并在 SKILL.md 的提供商表中添加一行，同时更新工作流第 1 步以引用新提供商。
现有提供商参考文件
- openrouter.ai — references/openrouter.md
- opencode.ai（opencode、opencode-go）— references/opencode-ai.md
- nousresearch.com — references/nousresearch.md
验证方式与原因
该技能通过检查提供商模型列表端点是否成功返回模型来验证免费模型，而非发起完整推理 API 调用。完整调用会混杂无效/废弃模型、连接失败、认证错误、配额耗尽等多种失败模式，需要脆弱的错误分类逻辑；模型列表命中则是模型在查询时存在且可达的可靠信号。代价是模型可能通过验证但在两次运行之间被移除或临时不可用而在推理时失败；这可以接受，因为每次运行技能都会重新查询回退列表，陈旧条目会在下次调用时清理。
适用场景
需要为 switchback 自动生成或刷新免费模型回退列表，并希望只保留经验证、当前可达的免费模型时使用。
限制
验证仅基于模型列表接口，不保证推理时可用；免费模型的具体范围取决于各提供商的模型列表与已知免费名单；配置须写入统一的共享配置文件。