pi-ai upgrade compatibility
pi-ai 升级兼容性
The pi-ai adapter classifies upstream compatibility fields explicitly and persists only replay metadata needed by later requests. An SDK upgrade can add fields to either set without changing the Harness provider-neutral API. Unclassified configuration fields fail compilation; omitted replay metadata can silently change subsequent provider requests.
English
Problem
The pi-ai adapter classifies upstream compatibility fields explicitly and persists only replay metadata needed by later requests. An SDK upgrade can add fields to either set without changing the Harness provider-neutral API. Unclassified configuration fields fail compilation; omitted replay metadata can silently change subsequent provider requests.
Decision
The adapter follows pi-ai 0.85.1. thinkingTokenBudgetField, vllmPriority, and supportsMaxOutputTokens are opt-in gateway controls; thinking.budget joins the existing template placeholders. The SDK owns budget resolution and serialization. supportsMidConvoEffort and allowedFallbackModels remain catalog-owned because their correctness depends on exact Anthropic transports, model capabilities, and fallback pricing.
Optional providerThinkingLevel remains in the adapter replay-v2 response metadata so Anthropic history retains its provider-native effort. Absence remains valid; neither the replay version nor the released Session format changes. Replay metadata retains the requested model while responseModel retains an Anthropic alias resolution or fallback. Reconstruction restores that native model so pi-ai still applies its cross-model signature rules. The provider-neutral LLM API stays unchanged; the provider-routed replay ownership rules still apply. The 0.84.2 Anthropic adapter initializes model from the request and records only response id and usage at message start. It never writes responseModel, so its replay records retain the requested model without native-model metadata.
Alternatives considered
Withhold every new field. This would misclassify deployment-owned gateway controls as catalog facts: upstream explicitly leaves budget-field selection and vLLM priority out of its generated catalog.
Expose every new field. This would let arbitrary gateways claim model-specific Anthropic effort and fallback support without the catalog evidence that makes those features valid.
Consequences
Compile-time coverage retains explicit field classification. Compatibility tests cover schema acceptance, invalid values, protocol applicability, and materialization without changing defaults. Replay conversion tests cover optional effort preservation. Mixed-protocol catalog tests use the installed OpenCode catalog. Provider behavior remains upstream-owned; live provider verification is separate from keyless adapter tests.
中文
Problem
pi-ai 适配器显式分类上游兼容字段，并且只持久化后续请求需要的回放元数据。SDK 升级可能在不改变 Harness 提供方无关 API 的情况下为任一集合新增字段。未分类的配置字段会导致编译失败；遗漏回放元数据则可能静默改变后续提供方请求。
Decision
适配器遵循 pi-ai 0.85.1。thinkingTokenBudgetField、vllmPriority 和 supportsMaxOutputTokens 是显式启用的网关控制；thinking.budget 加入现有模板占位符。SDK 拥有预算解析和序列化。supportsMidConvoEffort 和 allowedFallbackModels 仍由目录拥有，因为其正确性依赖确切的 Anthropic 传输、模型能力和回退定价。
可选的 providerThinkingLevel 保存在适配器 replay-v2 响应元数据中，让 Anthropic 历史保留提供方原生 effort。缺失仍然有效；回放版本与已发布 Session 格式均不改变。回放来源保留请求模型，responseModel 则保留 Anthropic 别名解析或回退后的模型。重建会恢复该原生模型，让 pi-ai 继续应用其跨模型签名规则。提供方无关的 LLM API 保持不变；按提供方路由的回放归属规则 仍然适用。0.84.2 Anthropic 适配器从请求初始化 model，并且在消息开始时只记录响应 ID 和用量。它从不写入 responseModel，因此其回放记录保留请求模型，不携带原生模型元数据。
Alternatives considered
保留所有新增字段为不可配置。 这会把部署拥有的网关控制误分类为目录事实：上游明确不在生成目录中设置预算字段选择和 vLLM 优先级。
开放所有新增字段。 这会允许任意网关在缺少目录证据时声明支持模型专属的 Anthropic effort 与回退能力，而这些证据正是相关功能有效的依据。
Consequences
编译期覆盖保留显式字段分类。兼容性测试 覆盖 schema 接受、无效值、协议适用范围及物化，且不改变默认值。回放转换测试 覆盖可选 effort 的保留。混合协议目录测试使用已安装的 OpenCode 目录。提供方行为仍由上游拥有；真实提供方验证与无需密钥的适配器测试分开。