09 pi-ai 的抽象 统一 39 家 provider 的代价，藏在一个 .gitignore 条目里

先记住这一句

这层抽象要解决的问题不只是「请求格式不同」。真正难的是三件事：认证方式各不相同（API key / OAuth / 订阅账号 / 云厂商 IAM）、流式事件语义不同、以及模型能力矩阵每周都在变（上下文窗口、价格、是否支持 thinking、是否支持工具）。

前两件靠代码解决，第三件靠不把它当代码——生成、不入库、构建时刷新。

模型数据不在 git 里

// This file is auto-generated by scripts/generate-models.ts
// Do not edit manually - run 'npm run generate-models' to update

import values from "./data/anthropic.json" with { type: "json" };
import { flattenModelCatalog, type ModelCatalog } from "../model-catalog.ts";

export const ANTHROPIC_MODELS: ModelCatalog<typeof values, "anthropic"> =
	flattenModelCatalog("anthropic", values);

后果直接写在 README 的开发命令里：npm run build 会先刷新模型数据再构建；想不联网构建必须用 build:offline。README.md:56

发布用的源码归档里则包含这份生成数据，这样打包者能离线复现官方二进制。README.md:74

一条显式的收录标准

库只收支持 tool calling 的模型。ai/README.md:5 这一句把 pi-ai 从「通用 LLM SDK」区分了出来——它是 agent 的基础设施，不是中立的多家封装。

认证：显式值永远赢

调 models.stream() 时，认证经由所属 provider 解析并合并进请求；每次请求里显式给的值永远优先（环境变量、存储的凭证、OAuth token 都排在后面）。ai/README.md:330

并且解析结果可以不发请求就查——models.getAuth(provider) 或 getAuth(model)。对一个要同时支持 API key、OAuth 订阅、云厂商凭证的库来说，「能单独查认证怎么解析出来的」是必要的可调试性。

这也解释了 第 03 章里循环为什么要 getApiKey 回调：OAuth token 会过期，而一个 run 可能跑很久，认证必须在每次 LLM 调用时重新解析，不能在构造时固定。

把模型元数据当构建产物，而不是源码

好处：模型清单每周都在变（新模型、改价、改窗口），入库会让 git 历史里塞满与代码无关的数据变更，而且永远滞后。构建时刷新意味着发版时的清单总是新的。

代价有三条，都很实在：

• 克隆下来不联网就构建不了（除非已有一份快照可供 build:offline）。
• 构建结果不可复现——同一个 commit 在不同日期构建，产出的模型清单不同。发布源码归档里带上数据，正是为了补这个洞。
• 上游目录挂了或改格式，构建就挂。

与 第 16 章那套「依赖精确锁版本、拒绝同日发布」的谨慎相比，这里的取舍是反向的：依赖代码要钉死，模型数据要最新。区分依据是——依赖代码会执行，模型元数据只是数据。

为什么值得自己写，而不是用现成的多 provider 库

5.8 万行是很大的投入。从收录标准（只要支持 tool calling 的模型）和认证设计（订阅账号、OAuth）能看出理由：通用库优化的是「换 provider 容易」，agent 需要的是「工具调用、流式、成本、thinking 级别在所有 provider 上语义一致」——后者要深入到每家的细节里去抹平，而不是找最大公约数。

这个判断是否值 5.8 万行，取决于你要支持几家。支持 2 家不值，支持 39 家大概值。

上游讲这条理由，是在仓库之外：Earendil《What is a Harness?》（2026-08-20），比 ac4ac9e 晚 13 天。文中的理由是用户侧的选择权，直说是为了 “take power and leverage away from the AI labs and into the hands of end users”。

• 「39 个 provider」是按 *.models.ts 文件数统计的，其中若干是同一家的不同接入方式（如 openai / openai-codex / azure-openai-responses），也包含若干区域变体（minimax / minimax-cn）。真实的「厂商数」小于 39。
• 构建可复现性依赖发布归档。直接从 git checkout 构建，产物与官方发布不保证一致。
• 模型能力矩阵的正确性取决于上游目录。上游标错了窗口大小，pi 就跟着错，而 第 06 章的压缩阈值直接依赖这个数字。
• 官方叙事略过了账单。立场文讲用户拿到什么——换个模型再问一次；代码讲这份自由由谁买单：正因为各家在工具调用、流式、thinking 级别上语义不一致，「朴素地换模型」才不成立，才需要 5.8 万行逐家抹平；而模型清单不入库、构建时刷新（§2），说明被抹平的这一面一直在变。两笔账不同源，但同指一件事——translation layer 在文章里是一项功能，在代码里是一项持续的维护成本（这是本书的推论）。
• 抹平速度跟不上时，先失效的是叙事那一侧。当某家 provider 的语义变化快过 5.8 万行的跟进速度，官方讲的「换个模型再问一次」会退化成「换个模型，然后发现工具调用行为变了」——立场文说的是这个设计为谁而做，代码说的是它要多少钱维持，两者并不互相担保。
• 不收录不支持 tool calling 的模型是设计选择而非疏漏。想用纯对话模型跑 pi，路径是自定义 provider（docs/custom-provider.md），不是等它被收录。

• 区分「会执行的依赖」和「只是数据的依赖」，用相反的策略。前者钉死版本、拒绝新鲜；后者构建时刷新、要最新。 适用条件：你依赖会频繁变化的外部目录（模型清单、汇率、地区码）。但要为可复现构建准备一份归档快照。
• 认证解析要能「不发请求就查」。多种认证方式共存时，「到底用了哪个凭证」是最常见的支持问题。 适用条件：支持两种以上认证方式。
• 在每次请求时重新解析认证，而不是在客户端构造时固定。OAuth token 会在长任务中途过期。 适用条件：支持 OAuth 或任何有效期凭证。纯 API key 场景固定下来更简单。
• 把「支持 N 家 provider」当成持续的维护成本，不是一次性工程。抹平语义差异靠人力跟进，模型元数据靠构建时刷新——两笔都不会自己停。 适用条件：你打算对外承诺「随时可换模型」。承诺之前先定下谁来跟进上游变化：宣传里的自由，代码里是需要有人持续承担的维护成本。

给场景，判断 pi 会怎么做