凭据、设置、存储与遥测

先玩再讲。上方是磁盘上的凭据文件，下面两个进程同时在跑请求：左边是 DSH 的做法，每次请求都回文件现取一遍 key；右边是很多程序的惯用做法，启动时读一次，存进内存用到死。脚本会在运行中途轮换一次 key、再把 key 清空，点播放，看两边各是什么下场。

先说清一件事：DSH 的设置文件和 cordis.yml 里没有任何一处写着 API key 的值。它们携带的是引用，一个 POSIX 风格的环境变量名，比如 DEEPSEEK_API_KEY。值归凭据提供方所有，本地提供方按四层来源找：进程环境优先级最高，然后是 $DSH_HOME/.credentials.yaml 文档，最后是项目和用户的 .env。这就是副标题说的「配置不落盘」：落盘的只有名字，机密被挡在配置之外（docs/subsystems/credentials.zh.md 第 5 行）。

然后是本课最重要的一条规则：消费方在每个操作中重新解析引用，绝不跨操作缓存。文档原话说得很直白，这种按操作进行的读取正是热更新机制（同文档第 20 行）。落到 DeepSeek 适配器上，就是 packages/llm/llm-deepseek/src/adapter.ts 第 214 至 222 行：每次 stream() 开头，把连接配置和 key 一起冻成一份快照，这个请求从头到尾用这一份，下一次请求自动重新解析。

大纲里问的边界条件在这里有了答案。请求进行到一半你轮换了 key，本次请求拿旧 key 跑完，新 key 从下一次请求开始生效，中间不会出现半新半旧。而且 key 是从连接快照里解析出来的，端点和发给它的密钥永远来自同一代配置，配置回滚时不会出现新端点配旧 key 的杂交（该处注释写明了这个意图）。

还有两条容易忽视的 seam 级规则。第一，空的存储值在任何地方都视为不存在，把 key 设成空字符串等于没配，下一次请求直接报 MISSING_CREDENTIAL，演示最后一步就是它。第二，配置界面走 describe(ref)，只回「配没配、来自哪层、能不能写」，绝不回值；由进程环境供值的引用被报成 writable: false，因为往那里写会表面成功、而解析继续返回环境里的旧值，seam 干脆提前拒绝（同文档第 34 行）。

最能看出这套架构干净的是 credentials/updated 事件（同文档第 50 行）。凭据变更时确实会发事件，但文档专门写了一句：消费方不需要它，它只服务于配置界面刷新「已配置」徽标。热更新靠的是读取时机，压根不靠通知广播，没有失效消息要追、没有订阅要管理。

这段在 resolveApiKey 函数体内（第 225 行起），每次模型请求都会走一遍：挂了凭据 seam 就向它现解析，没挂 seam 就退回启动环境变量。注意 else 分支里的注释，没有 seam 时不存在可排序的托管存储，环境就是全部的凭据平面：

    if (credentials !== undefined) {
      const hit = await credentials.resolve(ref)
      if (hit !== undefined) return assertUsableApiKey(hit.value, 'llm-deepseek', ref)
    } else {
      // Without the seam there is no managed store to rank against, so the
      // environment is the whole credential plane.
      const ambient = launchEnvironmentOf(ctx).get(ref)
      if (ambient !== undefined && ambient.value.length > 0) {
        return assertUsableApiKey(ambient.value, 'llm-deepseek', ref)
      }
    }

两条路都落空，紧跟着抛出的就是 MISSING_CREDENTIAL（第 241 至 245 行），报错把两个配置入口都写在话里，演示左侧最后那条红字就是它的原文。

设置是另一处坑。用户拿编辑器改 settings.yaml，web 界面也在改，两个 harness 进程可能同时开着。朴素实现是把内存里的设置快照直接序列化写回，后写的赢，把先写的整段抹掉：你在编辑器里刚加的配置，被另一个进程一次保存冲得干干净净。

DSH 的写路径把这条堵死了（Agent Note 2026-07-30-settings-write-path-integrity.md）。每次写盘之前先重读磁盘、合并外部改动，然后在一把跨进程文件锁里完成「读、渲染、原子提交」一整轮。锁的实现是 withFileLock：用 wx 标志独占创建 <文件名>.lock，创建成功即持锁；别人占着就指数退避重试，从初始延迟一路翻倍到上限，超过时限报错。读者不参与抢锁，提交靠临时文件 rename 原子替换，读到的永远是完整的一版。

有个细节值得停一下：等锁超时后，它宁可报错也不删掉别人的锁文件。函数上方的注释给了理由，锁文件的年龄证明不了它的主人已经死了，抢占一把还活着的锁比等待超时危险得多，清理孤儿锁是运维动作。又是熟悉的配方：拿不准，宁可吵闹地失败，别静默地闯祸。

出处：packages/util/atomic-write/src/index.ts 第 86 至 111 行的 withFileLock，核对日期 2026-08-13。

KV 存储的 SQLite 后端把版本立场延续了下来。STORAGE_SQLITE_SCHEMA_VERSION 当前是 1，写在 PRAGMA user_version 里；打开数据库时，全新的空库盖上当前版本戳，其他任何版本一律拒绝打开，没有就地迁移。和上一课的会话日志版本是同一套哲学：未发布软件没有需要保全的历史数据，与其背着一堆迁移代码，不如明确拒绝。

还有一处小而硬的取舍：journal 模式默认 WAL，坏文件系统可以退到几种回滚日志模式，但 memory 和 off 被从类型上排除了（同文件第 23 至 29 行注释）。理由一句话，扔掉日志持久性会静默违反 KV 后端合同里的持久性条款。想快可以，想快到说谎不行。

遥测这块最怕的是喧宾夺主，DSH 把它做成一项可选能力 seam：不在 agent loop 主干上，没有任何遥测内容会进入模型请求，harness 的职责到 emit() 为止（docs/subsystems/session-telemetry.zh.md）。每条记录导出前要过一道脱敏流水线，部署方挂规则监听器；监听器抛异常按 fail-closed 处理，直接扣下这条记录不发。脱敏只改导出副本，权威会话日志一个字都不动。

最后是匿名身份的设计。一个随机 UUID v4 落在 $DSH_HOME/.anonymous-user-id，三个消费方共用：OTel 上报的 user.id、/feedback 命令的确认回执、以及每次发往 DeepSeek 的 x-deepseek-harness-user-id 请求头（packages/identity/anonymous-user-id/README.zh.md）。共用一个 id，接收侧才能把三路记录关联起来，不用各自生成三个身份。

妙在创建时机。llm-deepseek 里这个 id 是懒创建的，userId ??= getOrCreateAnonymousUserId()，第一次真正要用才生成文件（index.ts 第 248 至 249 行）；而 stream() 里凭据解析排在身份解析之前（adapter.ts 第 221 至 222 行）。连起来看：一台从没配过 key 的机器，发起的请求在凭据那步就失败了，磁盘上不会平白多出一个跟踪身份。工具还没为你干过一件事，就先给你编了个号，这种事 DSH 不干。