osolmaz/switch

switch 是一个 TypeScript 框架，把任务建模成状态机，由决策模型通过回答有类型的题目来推进。像 Jev 这样的决策模型输出的是有限选项上的概率，而不是文本，因此无法像编程 Agent 那样生成工具调用；switch 在代码中生成这些选项，模型每一步只从中选一个，直到不再有问题。它适合围绕这类模型构建评测裁判、棋类或其他有限选择的窄任务 Agent。

一次运行如何推进

使用者实现一个 domain，提供初始状态、问题函数、转移函数和可选的 view。每一步中，问题函数产生 bool、choice 或 score 问题，模型带概率作答，转移函数据此生成下一个状态。没有问题时运行结束；请求失败或达到可选的步数上限也会结束。picking 辅助函数从一组下一步选项生成 choice 问题；可选的 outcome 说明用例如何结束，每次状态、问题和答案都会写入 trace。

一个具体用途是评测裁判：不必把 200 页文档的每一页都塞进上下文，模型可以单步读取文件、查看页面图像和搜索词条，只读取某个评分项所需的内容。仓库提供了 rubric judge 示例，以及棋类和 WikiRace 示例，详见 README。

使用方式

核心包、模型适配器、CLI 辅助包和测试用 decider 可从 npm 安装，需要 Node.js 22.18 或更新版本。@osolmaz/switch/models 提供 piAiDecider，适用于 pi-ai 列为 classifier 的模型（包括 Jev），API key 从环境变量读取。@osolmaz/switch/testing 中的假 decider 让测试不调用模型。示例和浏览器 viewer 不在 npm 上，需要 clone 仓库并用 pnpm 安装 workspace。

要把 domain 变成程序，需要编写一个 harness，其 setup 返回 runner，再用 commandLine 包装，得到 run 和 replay 命令。该辅助包本身是 Commander 程序，可以追加自定义命令。run 会写出包含每个用例结果、trace 和请求的运行目录，停止的运行可在中断处继续。replay 依据 trace 在无模型的情况下重跑；--fork <n> 重放前 n 步后由模型继续，详见 domain 文档。

限制与模型适配

README 直接说明模型能力有限：Jev 下棋很弱，作为裁判也还不足以替代最强的对话模型。作者给出的路径是在单一 domain 上用生成的数据微调开源决策模型，并预期这样在该任务上更好也更便宜。token 预算和 replay 的细节记录在 domain 文档中。

项目采用 MIT 许可证。HotRepo 在 2026-10-30 的 TypeScript 新项目榜上记录了 236 个总 star；这是新项目榜某一日期的快照，不是每日增长量。