05 三档可移植性逃生口

05 三档可移植性逃生口

本节摘要:前面四节讲了一套漂亮的抽象——它能把 20+ 厂商的差异吸收掉。但现实是:没有抽象能覆盖所有厂商的所有特性。某厂商的思维模式、路由偏好、特殊请求头......这些「非通用」特性如果硬塞进抽象,会让抽象膨胀到不可用。OpenCode 的解法是三档可移植性逃生口:从最可移植的「生成参数」,到按厂商分组的「providerOptions」,到最后手段的「http 透传」,逐档提供「越狱」能力。本节讲清这三档各自的适用场景与取舍——什么时候用哪一档,以及为什么不要一上来就用最强那档。

一、抽象的两难

先承认一个现实:抽象与覆盖是一对矛盾。

• 抽象越「干净」(只支持通用特性)→ 越可移植,但覆盖不了厂商专属特性
• 抽象越「脏」(塞满厂商专属特性)→ 覆盖全,但不可移植、难维护

OpenCode 的策略是:抽象只管通用部分,厂商专属特性通过「逃生口」透传。这样抽象保持干净,需要时又能逃生。

二、三档逃生口

OpenCode 提供三档逃生口,按「可移植性」从高到低排列:

第一档:生成参数(generation)        ──► 最可移植,优先用
   ▼ 不够用时
第二档:providerOptions              ──► 按厂商分组,中等可移植
   ▼ 还不够用时
第三档:http 透传                    ──► 最后手段,不可移植
​

第一档:生成参数(generation)

这是最可移植的一档,涵盖所有厂商都支持的通用生成参数:

优先用这一档。如果你的需求能被这些通用参数满足,代码对所有厂商都可移植——换厂商不用改。

💡 默认先问「能不能用第一档解决」:遇到需求时,先查通用参数里有没有对应的。90% 的常见需求(调随机性、限长度、设停止词)都能在这里解决。

第二档:providerOptions

当第一档不够(你要的是某厂商的专属特性),用第二档。这一档按厂商分组,允许你传厂商专属选项:

// 概念性示例:传某厂商的专属选项
{
  providerOptions: {
    anthropic: { thinking: { ... } },      // Anthropic 的思维模式
    google: { thinkingConfig: { ... } },   // Google 的思维配置
    openrouter: { routing: { ... } },      // OpenRouter 的路由偏好
  }
}
​

这一档的特点:

• 按厂商分组:选项归属明确,不会混淆。
• 中等可移植:你用了某厂商的选项,代码就与该厂商耦合了——但耦合是「显式且隔离」的(只在这个分组里),不影响其他厂商路径。
• 类型安全:通常配合模式校验,避免传错字段。

用这一档的时机:第一档满足不了、且你要的特性是某厂商明确提供的(如思维链、路由偏好)。

第三档:http 透传(最后手段)

当第二档也不够(你要改的是请求体、请求头、查询参数这种底层东西),用第三档——直接透传 HTTP 细节:

// 概念性示例:直接改 HTTP 请求
{
  http: {
    body: { ...额外请求体字段... },
    headers: { ...额外请求头... },
    query: { ...额外查询参数... },
  }
}
​

这一档的特点:

• 不可移植:你直接改了 HTTP,代码与该厂商的 API 细节强绑定。
• 最后手段:只在「别无他法」时用(如某厂商有个非标准的请求头必须设)。
• 风险最高:绕过了抽象的校验与翻译,出错时抽象层帮不了你。

⚠️ 慎用第三档:它等于「跳出抽象直接捅 HTTP」。一旦用了,你的代码就极其脆弱——厂商 API 一改你就挂。只有在确认第一档、第二档都解决不了时才用,并要做好「这个部分不可移植」的心理准备。

三、决策流程:用哪一档

把三档串成一个决策流程:

有需求
   │
   ▼ 第一档(生成参数)能解决吗?
   ├─ 能 ──► 用第一档(最可移植)
   │
   └─ 不能 ──► 第二档(providerOptions)有对应厂商选项吗?
        ├─ 有 ──► 用第二档(中等可移植)
        │
        └─ 没有 ──► 第三档(http 透传)(最后手段,慎用)
​

这个流程的核心原则是:能可移植就别耦合,能显式就别裸捅。每一档都是「上一档不够时才降级」。

四、为什么这样设计

这三档体现了 OpenCode 对抽象的成熟态度——抽象是默认,逃生是例外:

• 默认走抽象:大多数需求用第一档解决,代码干净、可移植。
• 必要时逃生:少数厂商专属需求走第二档,显式且隔离地耦合。
• 极端时裸捅:极少数底层需求走第三档,但明确知道这是「不可移植的特例」。

如果只有抽象没有逃生口,遇到厂商专属特性就只能「改抽象」——抽象会被各种特例污染,最终不可维护。如果只有逃生口没有抽象,代码会到处是厂商分支,也不可维护。三档共存,才兼顾了「干净」与「覆盖」。

五、第 6 章收尾:你现在理解的 LLM 抽象层

读完第 6 章五节,你完成了对 LLM 抽象层的完整理解:

这套抽象是 OpenCode 能优雅支持 20+ 厂商的根本。它的核心思想是:把厂商差异下沉(到协议/分帧/传输),把统一接口上浮(到 LLMEvent),需要逃生时分档提供越狱能力。

本节要点回顾

1. 抽象与覆盖矛盾:抽象越干净越可移植但覆盖少,逃生口解决「覆盖」问题。
2. 第一档生成参数:maxTokens/temperature/topP 等,最可移植,优先用。
3. 第二档 providerOptions:按厂商分组,中等可移植,显式隔离地耦合厂商特性。
4. 第三档 http 透传:直接改请求体/头/查询,不可移植,最后手段慎用。
5. 决策原则:能可移植就别耦合,能显式就别裸捅,逐档降级。
6. 第 6 章结束:你已掌握 LLM 抽象全貌——差异下沉、统一上浮、分档逃生。

第 6 章结束。接下来轮到 OpenWork 教程的正文填充——从第 1 章环境准备开始。