Volume 2 · Chapter 31

设置、凭据与身份：机器状态的三张面孔

设置（settings）是「可热更新的用户配置」，凭据（credentials）是「可替换来源的密钥」，身份（identity）是「匿名但稳定的用户标识」。三者都遵守 AGENTS.md 的一条硬约定：可调参数必须可配置，配置可热更新。

(卷一连接点) 04 页热更新 · 10 页 adapter 的 API key 解析 · 16 页 env 基线 → 本域：settings / settings-file / credentials / credentials-local / anonymous-user-id → (回心脏) 配置变化经热重组/事件到达各 provider

示例本次示例：改一个设置与换一个 key

示例轨迹 31-1 · settings.yaml 的热更新

# 本机真实文件：~/.dsh/settings.yaml
# 编辑：agentLoop: { maxParallelToolCalls: 4 }
# → settings-file provider 变更通知 → 订阅者重读
# → 13 页调度器的池容量变 4（下次执行生效，无需重启）
# 与 04 页 patch 热更新的分工：
#   settings = 数据热更新（运行时值）
#   patch = 结构热更新（换插件/重配置）

来源：31 页 §3 + 13 页 maxParallelToolCalls

示例轨迹 31-2 · API key 的按请求解析

# ~/.dsh/.credentials.yaml 或环境变量存 DEEPSEEK_API_KEY
# 10 页 adapter 每次 stream 时经 credentials 解析（不是启动时）
# → 换 key：改文件/环境变量 → 下次请求用新 key
# → key 不进 09 页的冻结 config、不进 request/header 日志
# （31 页易错点：config 会落盘，key 混进去就是泄密）

来源：31 页 §5 + 10 页 adapter 的 key 解析

§1挂载条目

settings → dsh-settings-file（401 行）——文件后端的设置 provider
credentials → dsh-credentials-local（966 行）——env/.env 后端的凭据 provider
identity（anonymous-user-id）——匿名身份（131 行）

§2包文件地图

包	规模	角色
`packages/settings/settings/`	—	Service Definition：`SettingsProvider extends Service`（src/index.ts:350）——命名空间化的设置读写 + 变更通知
`packages/settings/settings-file/`	2 文件 / 401 行	Provider：文件后端
`packages/credentials/credentials/`	—	Service Definition：`CredentialProvider extends Service`（src/index.ts:177）——凭证引用解析
`packages/credentials/credentials-local/`	2 文件 / 966 行	Provider：env + 根 .env 分层（00 页 loadLayeredEnv 的同族）
`packages/identity/anonymous-user-id/`	2 文件 / 131 行	匿名稳定 id（遥测的归因键）

§3机制：三层配置面

settings：命名空间化（如 agentLoop、shell）的键值 + 变更通知。provider 订阅变更事件重读——这就是「改设置即时生效」的通道（与 04 页的补丁热更新互补：settings 是数据热更新，patch 是结构热更新）。
credentials：凭证引用（名字）→ 值的解析。10 页 adapter 的 API key 按请求解析（不缓存进 config）——所以换 key 不需要重启。
identity：一个机器生成的稳定匿名 id——遥测/统计的归因键，不是登录态。

§4关键代码

packages/settings/settings/src/index.ts设置提供方契约350

350export abstract class SettingsProvider extends Service {

packages/credentials/credentials/src/index.ts凭据提供方契约177

177export abstract class CredentialProvider extends Service {

350

设置域的 Definition。所有「部署时可变」的调优都走它——AGENTS.md 的「无硬编码可调参数」约定在代码层面的落点。

177

凭据域的 Definition。引用与值的分离是关键：consumer 只持引用（名字），provider 在请求时解析值——值从不进冻结的 config。

§5易错点

凭证不进请求 config（10 页的冻结链）：config 会被深冻结、落 request/header 事件（09 页）——若 key 混进去，就等于把密钥写进日志。所以 10 页 adapter 的 key 是 stream 时经 credentials 解析的。

16 页 env 基线的 scrub 与 credentials 的分工：scrubbedParentEnv 剥离宿主环境里的凭证（不给子进程）；credentials 是显式引用的通道（只给申请的 consumer）。两者合起来才是完整的密钥卫生。