openrouter-decisions

OpenRouter 决策模型

决策模型读取应用状态，并以概率回答类型化问题，而不是生成文本。模型负责判断，代码负责计算。代码拥有工作流和每个确定性步骤，模型则补充代码无法做出的判断。它不是聊天模型、编码 Agent，也不是驱动聊天模型或编码 Agent 的大模型的替代品。

OpenRouter 上的每个决策模型都使用相同的 Decisions API（也通过兼容 TypeSafe-SDK 的 System One API 提供）和相同的基本原语；一次请求中的各项判断会彼此独立、并行评估。

需求	基本原语	返回内容
从已定义的选项中选择一个	choice	choice、每个选项的 probabilities、confidence
判断某个条件是否成立	noul	noul，即答案为是的概率
判断事物在有序等级中的程度	score	score（按概率加权的位置）、每个等级的 probabilities、confidence
判断图像中某个事物的位置（仅限 Jev 1.14）	box	以图像比例表示的 box 边缘、confidence

编写请求或读取响应、发送图像，或通过 System One API 或 TypeSafe SDK 调用时，请阅读 references/decisions-api.md。设计真值表、状态、措辞和标准，排查错误答案，以及查阅示例模式时，请阅读 references/question-design.md。从实时目录返回的决策模型中进行选择时，请阅读 references/models.md。问题涉及数量、日期、否定、间接引用或不可信文本时，请阅读 references/decision-model-limits.md，因为这些都是决策模型无法处理的内容。

步骤

1. 将判断与计算分开。 当一个步骤的答案范围有限、需要判断而非计算，并且概率可以让代码采取行动、暂缓处理或升级处理时，该步骤适合交给决策模型；必须生成文本、值或代码的步骤，或答案已存在于代码可读取字段中的步骤，则保持原样。算术、计数、日期排序、查找、阈值比较，以及用于提取事实（如路径、ID 格式、金额）的字符串或模式匹配，都应留在代码中；代码已持有的值绝不应再次向模型询问。若关键词、正则表达式、令牌重叠或相似度启发式是在代替判断（这段文本是否表示 X、这是否是同一请求、这是否相关），那么它本身就是判断：应由决策模型取代，并将其规则移入问题的纳入和排除标准，而不是保留为预筛选条件。如果代码端的事实已足以确定某个输入的操作（路径规则、硬性策略、超出上限的金额、空输入），代码就直接返回相应操作，并跳过该输入的模型调用。如果代码在比较之前需要从自由文本中解析值，应根据真实输入中的格式编写解析器，并将解析失败视为单独的结果。内容生成应交给生成式模型，随后决策模型可以从生成的候选项中选择。完成标准：每个剩余项目都是适用于某个基本原语的判断。

2. 根据判断选择原语。 互斥的备选项属于 choice，它是相对判断，用于确定哪个选项成立。可独立检验的条件属于 noul，它是绝对判断，因此所有标签都可能不成立；可以同时成立的标签各用一个 noul。沿单一维度变化的程度属于 score，其各级别都描述一种独立成立的情况。书面规则中的一个无序标签属于一个 choice，其判定标准应复述这些标签，而不是用多个 noul 再在代码中组合。按顺序排列的级别（1 到 5 的评分、从低到严重）属于 score，其判定标准应按顺序复述各级别，即使代码将结果存储为标签也一样。只有在代码将这些判断与自身事实组合，或在其他地方重复使用时，才拆分为多个 noul。代码中对可比较的逐项 score 进行排序，即可实现分级排名。在图像中定位目标属于 box。完成标准：每项判断都有对应的原语和理由。

3. 构建状态。 只发送问题会读取的内容。源文本、身份、关系、政策和当前事实都放入命名的 JSON 字段，并先在代码中筛选和检索。代码独自使用的内容应排除在外（标记、计数、计算得出的布尔值，以及任何会影响代码侧规则的字段，例如限制评分上限的套餐等级）；代码根据返回的答案应用该规则。无关材料会降低准确性。完成标准：state 中的每个字段至少被一个问题读取，且问题需要的内容均未遗漏。

4. 编写问题。 instructions 说明判断内容，并包含任务自身的纳入和排除规则（什么情况算符合，什么情况看似相似但不符合）。criteria 定义可能的答案，并作为 instructions 的延伸来表述；以一种方式提问，不使用双重否定。询问事实，而不是文本。例如，“这项更改是否会造成破坏性影响”适用；“描述中是否提到破坏性更改”和“报告是否如此说明”都不适用。因此，应将每个问题表述为被判断对象的属性（“这条评价是否带有宣传性质”），并让模型根据状态进行推断。使用反引号路径指向嵌套字段，例如 `ticket.messages[0].text`。choice 应列出所有可行选项。如果可能没有任何选项符合，则在同一请求中将 choice（或 box）与一个 noul 配对，询问是否存在符合项；与 none 选项相比，这种方式在 Jev 1.14 上效果更好；在其他模型上也应测试两种方式。如果选项是运行时的候选项，则按选项名称为状态设置键，并在判定标准中写出选项名称，绝不能使用数组索引。问题键供代码使用，不会发送给模型，因此每个问题都必须包含完整含义。对同一状态提出的独立问题应放在同一个请求中。只有当某个答案会决定要获取什么状态或下一步提供哪些选项时，才需要第二个请求。完成标准：仔细的人只凭 state、instructions 和 criteria 就能回答每个问题。

5. 选择模型并调用 Decisions API。 决策模型集合会发生变化，因此切勿凭记忆选择。使用 scripts/models.ts（或 GET /api/v1/models?output_modalities=decisions）列出 OpenRouter 当前提供的模型，并根据 references/models.md 中的标准筛选：上下文长度足以容纳实际状态并留有余量，价格符合调用量需求，提供商覆盖范围符合可用性需求。目录无法告诉你模型会如何回答你的问题，因此，如果还剩不止一个候选模型，请使用 decide.ts --compare 让每个候选模型都运行第 7 步的探测集，并根据实际回答、延迟和成本进行选择。将选定的 canonical_slug（或带版本号的 id）固定在一个配置值中，切勿使用别名，因为别名可能会改变你依赖的概率。之后更换模型时，只需修改该配置并重新运行第 7 步。将 API 密钥保留在服务端。关于请求类型、验证以及 HTTP 和 SDK 调用，请导入或复制 scripts/lib.ts 中的 parseRequest 和 decide，而不是重新编写。请求返回每个问题键对应的一个类型化答案，并将响应中的 model 字符串与答案一同记录，即表示完成。

6. 在代码中设置门槛。 阈值和业务规则应以命名常量的形式写在代码中，紧挨着原始的 noul 和 probabilities。在进行探测前，noul 的门槛为 >= 0.5（或者高于 0.7 时为是、低于 0.3 时为否；若有回退选项，中间区间则路由到回退），而 choice 取其 choice 字段。所有更严格的数值都留到第 7 步确定。choice 或 box 与表示存在性的 noul 配对时，只在该 noul 的是分支中读取；否分支采用不匹配结果，不确定区间（若存在）采用指定的回退选项，并且真值表要列出全部三种操作。比较方向要与问题所问的方向一致，因此 is_breaking.noul >= T 表示存在破坏性，“安全”则是 else。只有当代码路径有两种结果时，单一门槛才适用。如果已有回退选项（审核队列、默认值、更大的模型），就将其保留为概率接近门槛时的处理结果，并在第 7 步设置该区间的宽度。只有当这种回退比错误答案更便宜时，才使用 confidence。它衡量的是分布的集中程度，而不是答案是否正确或操作是否获准。noul 接近 0.5 表示“是”和“否”的可能性相近，并非强度中等。阈值不能从一个 noul 沿用到 choice，也不能从一个模型沿用到另一个模型；一道问题的 P(yes) 加上另一道问题的 P(not yes) 不一定等于 1。每个阈值都是命名常量，并在旁边写明每种错误的后果，即表示完成。

7. 先探测，再信任。 使用随附脚本，对有代表性的输入运行实际问题，并查看原始概率。涵盖明确案例、模糊案例、不匹配案例、空输入或偏题输入、否定陈述，以及试图为自身分类辩护的对抗性文本。根据这些数值设置阈值，而不是照搬常见默认值；模型变更时重复探测。每个边缘案例都按预期路由，且每个阈值都有对应的观测数值，即表示完成。

cd <skill-path>/scripts && npm install
npx tsx models.ts request.json                     # live catalog with context, price, providers, and fit for this request
npx tsx decide.ts request.json --model <model-id>  # raw HTTP to one model
npx tsx decide.ts request.json --sdk               # through @openrouter/sdk
npx tsx decide.ts request.json --compare           # same request to every pinned model in the catalog

request.json 包含 { "state", "questions" }，并可选包含 "model"。--model 会覆盖请求中的模型；如果两者都未设置，则使用环境变量中的 DECISION_MODEL。脚本会输出答案、解析后的模型版本、延迟和成本；--compare 则会为每个模型输出一条记录，并在模型失败时内联显示错误。