第 07 章：认证是一等子系统

阅读日期：2026-09-14。书中版本基线：核心分析 v0.66.0，作者自述对照 v0.82.1；本笔记未独立验证源码或发行版本。

设计问题、机制与取舍

长任务中的过期、凭证来源差异和并发刷新，促使认证下沉至 pi-ai。ProviderAuth 声明能力，CredentialStore 管凭证，AuthContext 注入环境访问，AuthInteraction 把登录交互收敛为 prompt/notify。

OAuth refresh 执行有副作用的交换，toAuth 派生请求认证；过期后在 modify 锁内再次检查，避免重复刷新。存储凭证失败不静默切换环境账户。checkAuth 供状态检查，getAuth 服务请求；底层原因与错误码并存。存储后端和登录界面仍由宿主提供，CLI 登录涉及 PKCE、回调或设备码流程。

来源：本章原文。这是压缩后的原创读书笔记，完整论证、示例及版本说明请回到原章。

工程应用检查（整理者推导）

个人工具若同时支持 API key 与订阅账户，应让状态界面只读账户元数据，避免打开设置页就执行凭证命令或触发刷新。运行日志保留认证来源类别和错误码，秘密值不要进入知识笔记、模型上下文或调试截图。

可以构造两个并发请求共享过期凭证的测试：只有一个执行刷新，另一个在锁内重新读取后使用新凭证。再加入“等待锁时用户退出登录”和“刷新失败但环境里存在其他 key”两种情形，确认系统不会悄悄换账户继续执行。跨进程安全还取决于实际存储是否实现了相应锁。

凭证派生出来的地址与请求头应每次按有效凭证生成，不能把首次登录结果永久贴在模型目录上。登录机制分析不代表某个订阅允许任意第三方使用，落地时仍查对应产品当时的正式接口。这些是整理者的工程应用检查，不是对本机账户配置的修改。