憑據、設定、存儲與遙測

先玩再講。上方是磁盤上的憑據文件，下面兩個進程同時在跑請求：左邊是 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 不幹。