建议在 dsh-llm-pi-ai 开放 OpenRouter 路由锚定（compat.openRouterRouting）

[Joxos]

使用场景

OpenRouter 对每个模型聚合多家上游。默认 auto 路由下，z-ai/glm-5.3*（以及类似的 deepseek/*）的请求可能被打到第三方节点：fp4/int4 量化缩水（Relace）、上下文截短（Reka / io-net）、输出上限缩水（DeepInfra 16K）。用官方文档的请求字段

{"provider": {"only": ["Z-AI"], "allow_fallbacks": false}}

锚定官方厂商，可保持官方 fp8 权重、官方价格（GLM 在 OR 上零加价）与官方 prompt-cache 语义。这是部署者偏好，正是 provider profile 应该能表达的东西。

现状

• pi-ai 已端到端支持：Model.compat.openRouterRouting 会被 openai-completions 实现写进请求体 provider 字段，且有完整 OpenRouterRouting 类型（only/order/ignore/allow_fallbacks/quantizations 等）。
• dsh-llm-pi-ai 在 COMPLETIONS_COMPAT_GATE 里把 openRouterRouting 标为 'withhold'，settings.yaml 里写它会直接报 "not configurable here"。
• 仓库内搜索 openRouterRouting：0 条相关 issue/讨论。

为什么 withhold 的理由在此不适用

门禁的文档理由是："withhold 用于 pi-ai 已安装 catalog 为具名厂商设置的字段"——比如 zaiToolStream、sessionAffinityFormat，目录确实为需要的厂商设置了它们。

openRouterRouting 不属于这类：pi-ai 的 openrouter 目录数据（0.82 与 0.84 两版已核实）从不设置它（默认 {}）。它不是目录知道的厂商 quirk，而是只有部署者才能决定的路由偏好。继续 withhold 的结果是部署方只能接受 auto 路由（可能悄悄打到量化缩水节点），或绕开 DSH（本地代理、改直连、fork）。

提案

1. COMPLETIONS_COMPAT_GATE 中 openRouterRouting 由 'withhold' 改为 'offer'；编译期证明（EveryProfileFieldIsOffered / EveryOfferedFieldIsDocumented / EveryProfileFieldMatchesUpstream）会自动要求并校验新增字段。
2. PiAiCompatProfile 增加 openRouterRouting?: OpenAICompletionsCompat['openRouterRouting']（带 JSDoc），并在 src/config.ts 的 compatProfile schema 增加对应成员。
3. 建议加一道与本包「拒绝而非静默忽略」风格一致的守卫：pi-ai 只在 baseURL 为 openrouter.ai 时生效该字段（其他地址静默忽略，见 earendil-works/pi#5347）——可以在非 openrouter 路由上拒绝，或至少文档明示作用域。vercelGatewayRouting 如需可同模式开放。

期望配置：

llm-pi-ai:
  providers:
    openrouter:
      apiKeyEnv: OPENROUTER_API_KEY
      compat:
        openRouterRouting:
          only: [Z-AI]
          allow_fallbacks: false

备查链接

• 上游 master 分类门禁：https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/catalog.ts
• 上游 master schema：https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/src/config.ts
• 关联讨论（自托管网关 first-class 化）：Proposal: make self-hosted gateways first-class providers in deepseek-harness (split `packages/llm`) #2529
• OpenRouter 路由选择文档：https://openrouter.ai/docs/guides/routing/provider-selection

---

若方向被认可，欢迎团队采纳并排期；按项目 CONTRIBUTING 说明，目前暂不接受外部 PR，此帖仅作需求反馈，供团队参考。

[argszero]

Verified your claims against alpha.2 (0a53fb55be) — the withhold is real, the field is real, and the only thing between the two is the gate line.

Confirmation:

• packages/llm/llm-pi-ai/src/catalog.ts:217 COMPLETIONS_COMPAT_GATE, and :235 openRouterRouting: 'withhold' — exactly as you reported. The gate is typed satisfies Record<keyof OpenAICompletionsCompat, CompatDisposition> (:242), which is itself proof the field is a first-class compat key: pi-ai core declares and consumes it end-to-end; dsh only withholds it dispositionally.
• The reject path is the gate, not the config plumbing: config.ts:123 accepts compat?: PiAiCompatProfile per model, :249 builds the schema, and :442 passes compat through unchanged — so the only blocker for openRouterRouting on a hand-declared OpenRouter route is that one 'withhold'.

The discriminator I'd draw — and it aligns with a precedent in this same codebase:

The wire-compat note (2026-08-18-pi-ai-wire-compat-surface.md) justifies withhold as "a field pi-ai's installed catalog sets for a named vendor stays withheld" — zaiToolStream, vercelGatewayRouting, sessionAffinityFormat are static vendor capabilities the catalog can know and set. Routing preference is a different kind of thing: provider: { only: ["Z-AI"], allow_fallbacks: false } is deployment intent — which upstream the operator wants to anchor — not a capability the endpoint or catalog can infer. A field whose correct value varies per deployment belongs in offer, not withhold.

There's a direct precedent: supportsDeveloperRole was the same shape (#3076 / #551 cluster). pi-ai's catalog defaulted it to true on standard-looking URLs, which broke custom gateways that reject the developer role — the fix was to offer the field and pass it through resolveModelCompat, not to keep withholding it. The withhold list exists for "catalog already knows", and every member of this family (developer-role support, routing anchor) is a case where the catalog's inference doesn't match real deployments.

Concretely: the change is one line (catalog.ts:235 'withhold' → 'offer'); the config passthrough (:442) and schema (:249) already handle it; the drift-gate spec (tests/catalog.spec.ts) pins the gate shape so the intent stays documented. No security regression: allow_fallbacks: false is more deterministic than the status quo, and a hand-declared route naming provider.only is operator-authored input, not an attacker surface.

One thing worth adding to the proposal: the README / gate comment should state the discriminator ("withhold = catalog-set static vendor capability; offer = deployment intent the catalog can't infer"), so the next field of this class doesn't need a 0-issue search to get un-stuck.