DeepSeek Harness 凭据子系统：密钥不进配置

跑 Agent 项目，密钥是躲不开的东西：模型 API 的访问令牌几乎每个功能都要用。常见的做法是把密钥直接写进配置文件，再由各处代码自行读取。deepseek-harness 把这件事单独拆成了一个凭据子系统，它的核心判断只有一句话：密钥值不应该出现在任何配置表面上，配置里应该出现的只是对密钥的引用。围绕这个判断，它设计了一条完整的凭据接缝，让配置、值和消费者各归其位。本文基于该项目的凭据子系统文档，拆解其中的关键机制。

引用与值分离：配置里只有名字

这条接缝里，设置段和 cordis.yml 条目携带的不是密钥，而是一个引用：一个 POSIX 风格的环境变量名，比如 DEEPSEEK_API_KEY。引用在类型系统里是一个品牌类型 CredentialRef，构造时会校验它是否符合 shell 标识符语法。这个品牌的存在很务实：它让凭据引用和其他在包之间、进程之间传递的普通字符串在类型上不可混用，把传错字符串这类问题挡在编译期。

密钥值本身由提供者保管，比如内置的本地提供者 dsh-credentials-local。配置面只持有名字，值永远不进配置文件，也就不会跟着配置的流转和展示一起扩散。

值从哪里来：四个来源层

本地提供者管理四个来源层：进程环境变量 env、存储文件 file、项目级环境 project-env 和用户级环境 user-env。解析返回的不只是值，还有供出这个值的来源层标识，调用方可以据此知道凭据现在是谁在供值。四个层之间的优先级属于提供者的实现细节，文档约定的是层的名字，以及解析结果必须带来源标识。

按操作解析：轮换密钥不用重启

这是整套设计里最要紧的一条：解析按调用进行，消费者在每次操作时重新解析，绝不跨操作缓存。文档明确说，LLM 适配器在每次模型请求时解析一次凭据。这意味着密钥轮换之后，新值在下一次请求就生效，中间不需要重启进程，也不需要手动刷新缓存。按操作读取本身就是热更新机制。

解析返回一个 ResolvedCredential 结构，里面是非空的密钥值和供出它的来源层；引用尚未配置时返回 undefined 而不是抛错，调用方据此走未配置的分支。

空值即不存在

接缝有一条对所有提供者生效的全局规则：存储值为空，等价于这个凭据不存在。解析会跳过空值，状态查询会把它报告为未配置。这条规则堵住了一个隐蔽的坑：如果不做约定，一个空字符串可能被当成已配置但值异常，让上层在半配置状态下做出错误动作。在这条规则下，空白永远不会伪装成一个配置好的密钥。

describe：给界面看状态，不给值

配置界面需要知道一个引用配置了没有、从哪一层来、现在能不能写入，但它不该看到值。describe 就是为此准备的：返回 configured、source、writable 三个事实，唯独不返回密钥值。

writable 这个字段处理了一个很实际的问题。如果引用当前由活的进程环境变量供值，本地提供者会把它报告为不可写：此时调用 set，写入看起来成功了，但解析仍会继续返回那个遮蔽着的环境变量值，属于典型的假成功。接缝干脆拒绝这种写入，界面也可以提前把这个引用渲染成只读，而不是让用户写完再疑惑为什么没生效。

写入与删除的边界

set 负责把一个非空值持久化进提供者管理的可写来源，它有两种拒绝场景：只读来源遮蔽引用时拒绝，值是空字符串时也拒绝，清空请改用 unset。unset 负责移除引用，删除一个本来就不存在的引用是无操作，不算错误。写入与删除同样遵守空值即不存在与只读遮蔽两条规则。

变更事件：给界面刷新，不给消费者

credentials/updated 事件在提供者管理的来源发生已提交变更后派发：可能是 set、unset，也可能是外部对存储的编辑被观察到了。而进程环境变量的变化是不可观测的，这类变化永远不会触发事件。

一个值得注意的取舍是：普通消费者并不需要这个事件，因为按操作解析已经保证了每次都拿到最新值；事件是给配置界面刷新已配置角标用的。监听器如果出错，无论同步抛出还是异步拒绝，都会被隔离并记录，不影响已提交操作的结果；唯一例外是带 INVARIANT 编码的失败，它会在所有监听器跑完后重新抛出。而且这个重抛只能由同步监听器触达派发方，所以在这个事件上做不变量检查不能写成异步函数。

这套设计值得借鉴什么

回头看，这个子系统的价值不在某个单点技术，而在三条约束的组合：引用与值分离，让密钥远离配置表面；按操作解析，让轮换从一次运维动作变成对业务无感的事；describe 把可写性提前告诉界面，把假成功挡在发生之前。任何要管密钥的项目在做设计时，这三条都值得参考。