pi-ai（下）：Provider 适配、认证与工具调用协议

先打一个比方：api/ 目录就像 JDBC 驱动集合——上层（Agent Loop）只面向 StreamFunction 这一个「接口」编程，下层每个厂商协议一个实现文件。Pi 目前内置的适配器家族如下（均在 packages/ai/src/api/）：

每个 <api>.ts 旁边都有一个 <api>.lazy.ts，例如 anthropic-messages.lazy.ts 全文只有一行核心逻辑：

动机很直接：anthropic-messages.ts 约 70 KB、内部 import Anthropic from "anthropic"；openai-completions.ts 约 64 KB、拉入整个 openai SDK。而 Pi 的 CLI 启动时要做的事只是列出 40 多个 Provider、展示模型选择器——如果为了一行帮助文本就把所有厂商 SDK 都加载进来，冷启动会显著变慢。

lazy.ts 提供两个原语。lazyApi(load) 把动态 import() 包装成 ProviderStreams（含 stream / streamSimple，以及可选的 fetchDeferred / cancelDeferred）；首次真正发请求时才加载实现模块，宿主的 import cache 会去重。lazyStream(model, setup) 则解决「异步 setup 与同步返回流的矛盾」：

• 同步返回一个 AssistantMessageEventStream，调用方立刻拿到可迭代对象；
• 后台执行 setup（认证解析、模块加载），完成后把内部流转发给外层；
• setup 失败不抛同步异常，而是以 error 事件收尾，stopReason 为 error 或（若 signal 已中止）aborted。

每个适配器的入口签名都是同构的：stream(model, context, options) => AssistantMessageEventStream。无论哪个协议，出站前都要经过一条固定的「清洗 → 转换 → 装配」管道。下面这张图是本讲的核心，建议对照源码走一遍：

这个 200 行的共享函数（api/transform-messages.ts）在进入任何协议转换前，把跨厂商的坑统一抹平：

1. 图像降级：模型的 input 不含 "image" 时，把 user 消息与 toolResult 里的图片替换成 "(image omitted: model does not support images)" 占位文本。
2. 跨模型 thinking 清理：thinking 签名（signature / encrypted reasoning）只对产出它的模型有效，切换模型回放历史时会直接 400。函数对非同模型的 thinking 块整块丢弃（redacted / 有签名的除外——它们是回放所必需的）。
3. 工具调用 ID 归一化：OpenAI Responses 生成的 ID 可达 450+ 字符、含 | 等特殊字符；Anthropic 要求 ^[a-zA-Z0-9_-]+$ 且最长 64。函数建立 old→new 映射表，assistant 消息里的 toolCall.id 与后续 toolResult.toolCallId 成对替换。
4. 孤儿 tool call 补结果：对没有对应 toolResult 的 tool call 合成 { text: "No result provided", isError: true } 的 toolResult——这既满足了所有协议「tool_use 后必须紧跟 tool_result」的硬约束，也保住了 thinking 签名的位置；同时整条跳过 stopReason 为 error/aborted 的 assistant 消息，避免回放残缺轮次。

anthropic-messages.ts 的 buildParams() 先取首条 system 消息单独处理：文本进顶层 params.system 数组（每段可挂 cache_control 断点），对话体交给 convertMessages()。角色映射的关键差异：Anthropic 没有 tool 角色——toolResult 消息被转换成 role 为 user 的消息，内容是 tool_result 块；连续多条 toolResult 合并进同一条 user 消息（z.ai 端点的要求）。assistant 的 toolCall 块变成 tool_use 块，thinking 块原样携带 signature。真实 wire 格式（节选）：

两个细节值得记住：错误 tool result 里的图片会被 splitErrorToolResultImages() 拆出来，图片挪到该轮所有 tool_result 之后（Anthropic 拒绝错误结果里带非文本内容）；OAuth 订阅令牌（Claude Pro/Max）时必须在 system 里注入 "You are Claude Code, Anthropic's official CLI for Claude." 身份声明，且工具名会映射为 Claude Code 的命名。

openai-responses.ts 把对话装配成扁平的 input 数组（实现在 openai-responses-shared.ts 的 convertResponsesMessages()）：system 指令变成 role: "developer"（推理模型）或 "system"；assistant 的工具调用变成独立的 { type: "function_call", call_id, name, arguments } item（arguments 是 JSON 字符串）；toolResult 变成 { type: "function_call_output", call_id, output }。buildParams() 还处理一批 OpenAI 特有的约束：

• max_output_tokens 最小 16（低于 16 直接被拒，见源码引用的 issue #6265）；
• prompt_cache_key 用会话 ID 经 clampOpenAIPromptCacheKey() 截断；store: false 默认不落服务端；
• 推理模型的 effort 走 reasoning.effort，并 include: ["reasoning.encrypted_content"] 以便回放加密思考；
• item ID 必须以 fc_ 开头——normalizeToolCallId() 把 Pi 内部的 callId|itemId 复合 ID 拆开归一，异模型的调用还要 shortHash 重造 itemId。

两者对照后你会得出本讲的第一个结论：「兼容 OpenAI」的表面之下，藏着一整套约束差异——这就是 compat 开关体系（supportsStrictMode、supportsMidConvoSystemMessages、promptCacheKeyMode 等十余项）存在的原因，每个开关描述的都是一个「验证过的差异」，而非猜测。

providers/ 与 api/ 是两个正交的维度：api 是「说什么协议」，provider 是「谁在说话」。一个 provider 声明自己的 ID、名称、baseUrl、认证方式、模型目录，并绑定一个 api 实现。目录里每厂商两个文件：<name>.ts（注册逻辑，通常不到百行）与 <name>.models.ts（由 catalog/generate.ts 自动生成的模型目录）。以 Anthropic 为例：

模型元数据真正躺在 providers/data/<name>.json 里（上下文窗口、maxTokens、定价、compat 开关等），*.models.ts 只是把 JSON 变成带类型的导出。all.ts 则是汇总点：它 import 全部 40 多个 xxxProvider() 工厂函数，提供 builtinProviders() 列表与 builtinModels()——先 createModels() 再逐个 setProvider()，得到一个装满内置厂商的 Models 集合。另外 getBuiltinModel(provider, modelId) 能以字面量类型读出单个模型，供不需要完整集合的场景使用。

「新增一个厂商」因此有清晰的清单：写 providers/<id>.ts 注册、（可选）providers/data/<id>.json + *.models.ts 目录、在 all.ts 挂上工厂；若协议是新的还要在 api/ 写适配器与 .lazy.ts；若登录流程是新的则在 auth/oauth/ 加一个文件。

auth/ 目录分两层：根目录四个文件定义抽象，oauth/ 子目录放各厂商的登录流程实现。

官方文档（docs/models.md）给出一句话版本：运行时 --api-key 最先，其次 auth.json 存储凭据，再次 models.json 里的 apiKey，最后才是环境变量或云凭据。源码 resolve.ts 里的实现顺序与注释完全对应——「A stored credential owns the provider」（存储凭据拥有该 provider，环境变量只在什么都没存时兜底）：

1. overrides?.apiKey：命令行 / API 传入的一次性 key，直接构造 ApiKeyCredential 走 resolveApiKey()；
2. credentials.read(providerId)：读 auth.json。若是 OAuth 凭据且需要刷新（剩余有效期 < 默认 5 分钟），进 refreshStoredOAuthCredential()；
3. 都没有时，走 provider.auth.apiKey.resolve() 的 ambient 链——各 provider 自己决定顺序，例如 Anthropic 是 ANTHROPIC_AUTH_TOKEN → ANTHROPIC_OAUTH_TOKEN → ANTHROPIC_API_KEY → 工作负载联合身份（federation）。

一个容易踩的坑：CI 里设了 ANTHROPIC_API_KEY 却仍用订阅账号的请求——因为本地 auth.json 里存过 OAuth 凭据，它优先级更高。想让环境变量生效，先 /logout。反过来，Models.getAuth() 不会在刷新失败后悄悄回落到环境变量，避免「看起来能跑其实在用另一把钥匙」。

CredentialStore 的 modify() 是唯一写路径，按 provider ID 串行化（进程内 promise 链，文件存储再叠加文件锁）。刷新令牌之所以必须放进锁里：许多授权服务器在 refresh 时会轮换 refresh token（旧的一次性作废），若两个并发请求各自刷新，后写盘的会覆盖先写盘的，直接把唯一有效的 refresh token 弄丢。源码还特意注释：刷新一旦开始就不再响应 abort——取消的调用方可能丢弃唯一有效的 token，因此只用 15 秒超时兜底。

PKCE（Proof Key for Code Exchange，RFC 7636）解决的问题是：CLI 这种「公共客户端」没有 client secret，授权码截获攻击下原本不堪一击。做法是在发起授权前先生成一对 verifier / challenge：

流程：客户端把 challenge（SHA-256 哈希，S256 方式）随授权请求发出，只有持有原始 verifier 的客户端才能在回调时通过验证完成换码——即使授权码在重定向途中被截获，攻击者没有 verifier 也无法使用它。Pi 的回调由 callback-server.ts 在本机临时监听（localhost 回调），随用随关。

不适合开本地端口的场景走设备码流程（RFC 8628）：向服务器申请 device_code + user_code，用户在任意浏览器输入码完成授权，客户端轮询 token 端点。device-code.ts 严格按 RFC 实现：服务器未给 interval 时默认 5 秒；收到 slow_down 按 RFC 3.5 节把间隔加 5 秒（若服务器在 interval 字段给了新下限则优先用服务器值——源码注释解释这是为了容忍 WSL/VM 时钟漂移）；到期抛出超时错误。

接入新端点的第一条路径完全不用写代码：~/.pi/agent/models.json。只要端点说的是 Pi 已支持的协议（绝大多数 Ollama、LM Studio、vLLM、SGLang 与代理部署），声明 baseUrl + api + models 即可。官方文档给出的 Ollama 完整示例：

几个语义要点（均出自 docs/models.md 与 models-configuration.md）：

• 那个假的 apiKey: "ollama" 只是让模型对 Pi「可用」，Ollama 本身会忽略它；
• 打开 /model 会重新加载该文件，改完不用重启；
• providers 下的 key 是 provider ID：命中内置 ID（如 anthropic）就是修改它，新 ID 则新增 provider（必须有 baseUrl 和 provider 或 model 级的 api）；
• models 条目按 id 匹配：新 ID 追加，已有 ID 整体替换；只想改内置模型的元数据请用 modelOverrides，它不会替换模型列表，未知 ID 直接忽略，嵌套对象（如 cost）按字段合并、标量整体替换；
• 给内置 provider 只设 baseUrl，等于把它的所有模型与认证原样路由到代理：{ "providers": { "anthropic": { "baseUrl": "https://proxy.example.com/v1" } } }。

apiKey 与 headers 的值支持同一套语法：字面量、$NAME / ${NAME} 环境变量插值、以 ! 开头的命令输出（请求时执行、Pi 不缓存）；转义用 $$ 与 $! 分别得到字面 $ 与前导 !。典型用法——从 1Password CLI 动态取短期密钥：

模型条目还能声明 reasoning / thinkingLevelMap / input / inputLimits / promptCache / cost 等元数据；OpenAI 系 API 还支持 samplingParams 与按思考级别的 samplingParamsByThinkingLevel（键是 Pi 的 off/minimal/low/medium/high/xhigh/max，后写的值按 key 覆盖）。安全提示照抄文档：!command 会在请求时在你机器上执行，models.json 里的凭据命令务必保密，不要加载不可信目录下的配置。

当需求超出静态配置——需要动态发现模型、自定义登录流、或实现没人支持的 wire 协议——走第二条路：Provider 扩展。它是 Pi 扩展系统的一个应用：在扩展工厂里调用 pi.registerProvider()，Pi 会等待异步工厂完成后再继续启动，所以注册的模型对启动时的模型选择和 pi --list-models 都可见。官方文档的「最小合适集成」选择表：

两个高频变形：只注册 baseUrl/headers 可以重定向内置 provider（保留其目录与认证，适合代理场景，文档特别提醒不要顺手复制内置模型列表——那会把「小覆盖」变成「目录替换」，随上游漂移）；注册完整的 Provider（来自 @earendil-works/pi-ai，即 §5.3 里 createProvider() 的产物）可获得原生认证、模型过滤、refreshModels 发现等全部能力。若协议已有人实现，优先复用 Pi 内置 API 实现并只定制认证与端点——文档直言这比复制一份 stream 实现更安全，能保留 Pi 的消息转换、工具处理、用量统计与兼容性行为。

虚拟模型（virtual model）是 /model 列表里可选的一项，但每次请求前由 route() 决定实际派发给哪个物理模型——用户只选一次「auto」，框架按任务、成本或会话状态自动在大小模型之间切换。Pi 严格区分两对概念：选择（用户选的虚拟模型与级别，记入 model_change 事件，恢复会话时还原）与派发（每次请求真正使用的物理模型，记在 assistant 消息的 provider/model 字段上）。Provider 永远只看到物理模型，回放历史与手动切模型行为一致。

route() 的 reason 分四种：user（用户新消息后的首个请求）、continuation（agent loop 里的后续请求，如工具结果回填后）、retry（失败重试，failed 带失败详情）、direct（agent loop 之外，如压缩摘要）。示例里的「sticky」策略是实用关键：continuation 与 retry 保持上一物理模型，保住 prompt cache 与 thinking 签名的有效性。路由器还可以返回 state（必须 JSON 可序列化），Pi 把它存在会话分支上、随分支与 fork 走、压缩后仍保留。约束：虚拟模型不能路由到另一个虚拟模型；路由抛错或选中无凭据的模型时，该请求以错误结束。

第 4 讲定义了统一的 Tool 接口，这里补上「归一化」的完整链路。首先是 toToolDeclaration()——把一个工具从「可执行对象」降维成「给模型看的声明」：

这个看似朴素的深拷贝有两层用意：其一，剥离执行相关的字段——进入 transcript / system 消息的工具只有声明，没有实现；其二，JSON.parse(JSON.stringify(...)) 顺手丢掉 TypeBox Schema 上的不可枚举 kind 标记与 undefined 字段，使 declarationsEqual()（序列化后字符串比较）成为精确比较。会话中的工具增删由此可被记录：系统消息携带 toolsAdded / toolsRemoved，getCurrentTools() 按序重放得到当前工具集；一个「改名重定义」会被拆成「移除 + 新增」。

Tool.parameters 是参数的 JSON Schema（可用 pi-schema 构建器、TypeBox 或任意 JSON Schema 对象生成）。之所以统一在 JSON Schema 而不是 TypeScript 类型或各协议私有格式：一是它是所有厂商工具协议的事实交集——Anthropic 的 input_schema 与 OpenAI 的 parameters 本质都是 JSON Schema；二是它可序列化，能随会话持久化、跨进程传输、被运行时校验（第 7 讲的工具参数校验就建立在它之上）；三是 strict 结构化输出只需对 schema 做「收紧」变换（makeStrictJsonSchema()，如补 additionalProperties: false），无需理解厂商方言。

出站时各适配器的 convertTools() 把统一声明翻译成协议格式，形态差异不小：

Anthropic 侧的 convertTools() 有两处独特处理：其一，根级关键字限制——Anthropic 会拒绝根级 anyOf/oneOf/allOf，所以非 strict 时只保留 type/properties/required 加上共享定义（$defs/definitions，让属性里的 $ref 仍可解析）；其二，strict 黑名单——minimum/maximum/exclusiveMin/Max/multipleOf/maxItems(≠0,1)/uniqueItems/minContains/maxContains/minProperties/maxProperties 以及白名单之外的 format 会让整个请求 400，源码用 isAnthropicStrictUnsupportedKeyword 逐 key 检查后决定是否标 strict: true。

strict 工具还有配额问题：strict-tool-limits.ts 记录了 Claude 的观测上限——最多 20 个 strict 工具、全部 strict 工具合计 16 个可选/联合类型参数。超限时返回特定错误信息，Pi 把该会话标记进一个内存 Set，之后的请求直接以非 strict 发送（工具集很少在会话中途变化，重试 strict 只会再次被拒，还会因工具定义改写而打掉 prompt cache）。该 Set 注册了会话级清理，并设有 10,000 条上限。