第 6 课：模型与认证配置

结论

模型配置不是一个字符串。Pi 需要同时回答：有哪些 provider、每个 provider 有哪些 model、认证从哪里来、当前模型是否支持所选 thinking level、失败时能否找到可用 fallback。

入口问题

当模型不可用时，如何判断问题出在 provider 注册、模型选择、认证解析还是请求阶段？

心智模型

• AuthStorage 负责密钥、OAuth token 和运行时覆盖。
• ModelRegistry 负责模型发现、provider 配置和可用性判断。
• Provider adapter 负责把统一请求转成供应商请求。
• Session runtime 在每次调用前解析当前模型和认证。

源码推演（省略版）

下面不是完整源码，而是把本课主线压缩成可以在文档里直接阅读的关键形状。读者即使不打开本地源码，也应该能看出运行时如何组织职责。

async function resolveModel(request: ModelRequest) {
  const provider = registry.provider(request.providerId);
  const model = provider.findModel(request.modelId);
  const auth = await authStorage.resolve(provider.authScope);

  if (!model) return { ok: false, reason: "unknown-model" };
  if (!auth) return { ok: false, reason: "missing-auth" };
  return { ok: true, provider, model, auth };
}

• 这段省略版源码把“模型不可用”拆成可诊断的分支。
• 教学时不要只说“API key 有问题”，而要让学生定位失败发生在哪一层。
• 模型 id、provider id 和 thinking 配置应该进入 trace，方便复现。

课堂练习

设计一个模型检查结果对象，至少包含 provider、model、auth 状态、thinking 支持和错误原因。

掌握标准

• 能说明 AuthStorage 和 ModelRegistry 的分工。
• 能把模型失败拆成配置、认证、provider 和请求四类。
• 能解释为什么 trace 里要记录模型元数据。

课后习题

1. 实践题：基于本课的省略版源码，补出一个最小实现草图，要求写清输入、输出、副作用和错误处理。
2. 思考题：本课机制如果只靠 prompt 约束，而不放进 harness 或 runtime，会出现什么工程风险？