README.zh.md 14 KB
description: "面向用户与维护者的文件型凭据提供方：选择、配置或排查本地凭据存储及其环境分层。"
kind: "package-reference"
@deepseek-ai/dsh-credentials-local
English | 中文
概述
dsh-credentials-local 把 API 密钥和其他机密保存在 harness home 下的私有文件中。你可以通过配置界面保存凭据，也可以直接编辑文件；变更会自动重载，保存的值也会跨重启保留。凭据查找采用固定优先级：启动环境优先，其次是存储文件、项目 .env 和 harness home 的 .env；新保存的值会立即覆盖 .env 中的旧值。只有你的 OS 用户能读取该文件，但 agent（智能体）的工具进程以同一用户身份运行，因此该存储无法向 agent 隔离机密。
目录
使用本包
本包为组合提供本地凭据存储：API 密钥与其他机密只需保存一次，之后每个按名引用它们的请求都会用到。常用路径是显式的：加载存储、通过配置界面或 ctx.credentials 保存密钥，然后在需要时由产品解析。
何时使用
把它作为默认本地存储：产品的基础组合会加载它，你通过配置界面保存的密钥会立即生效。当部署必须让提供方密钥远离自身 agent 时选择其他存储——文件权限做不到这一点，因为 agent 的工具进程以你的 OS 用户身份运行（见「谁能读取该文件」）。
设置
- name: '@deepseek-ai/dsh-credentials-local'
config:
path: /absolute/path/to/.credentials.yaml
| 字段 | 默认值 | 含义 |
|---|---|---|
path |
<harness home>/.credentials.yaml |
凭据文件所在位置 |
dshHome |
$DSH_HOME 或 ~/.dsh |
path 缺省时使用的 harness home |
watch |
true |
文件在磁盘上变化时自动重载 |
debounceMs |
100 |
变化后等待这么久再重载，单位为毫秒 |
生成的配置目录完整列出了所有受支持字段及其 JSDoc，是这些信息的真源。
存储与移除密钥
用 set 保存密钥、用 unset 移除、用 describe 检查密钥是否已配置——与凭据 API 提供的操作相同：
import type { Context } from '@deepseek-ai/cordis'
import { credentialRef } from '@deepseek-ai/dsh-credentials'
declare const ctx: Context
const ref = credentialRef('DEEPSEEK_API_KEY')
await ctx.credentials.set(ref, 'sk-…') // save
await ctx.credentials.describe(ref) // { configured, source?, writable } — never the value
await ctx.credentials.unset(ref) // remove
你保存的密钥会被下一个按名引用它的请求使用；describe 报告它是否已设置、来自哪里、能否写入——绝不返回值本身。记录也持久化在同一文件中：插件按 <owner>/<id> 寻址一条记录，并用 seam 的记录操作（readRecord、describeRecord、listRecords、modifyRecord、deleteRecord）管理它。
密钥从哪里来
密钥按一个固定顺序解析——先有值的位置胜出：
| 位置 | 可写？ | 优先于 |
|---|---|---|
你启动时的环境（DEEPSEEK_API_KEY=… dsh） |
否 | 一切 |
| 存储文件 | 是（set/unset） |
两个 .env 文件 |
项目的 .env（<invocation cwd>/.env） |
不在此处 | 主目录 .env |
主目录的 .env（$DSH_HOME/.env） |
不在此处 | 无 |
启动环境优先，因为按次覆盖——DEEPSEEK_API_KEY=… dsh、CI 机密、容器 -e——代表本次运行的明确意图；它无法从产品内部修改，因此被报告为只读，写入会被拒绝。其他一切来源都输给存储文件，这正是你保存的密钥会立即生效的原因，即使某个 .env 里还留着更旧的密钥；没有存储任何东西时，那两个 .env 层会参与解析。环境层是启动时拍摄的启动器环境快照，因此启动之后才导出的变量不会被看到。
凭据文件本身
带版本的 YAML 文档，每个键空间一个分节，除此之外别无他物：
version: 1
refs:
DEEPSEEK_API_KEY: sk-…
OPENAI_API_KEY: sk-…
records:
llm-pi-ai/openai-codex:
kind: grant
payload: # written verbatim; this provider does not interpret it
type: oauth
access: eyJhbGciOi…
refresh: rft_9f8e7d…
expires: 1786000000000
llm-pi-ai/amazon-bedrock:
kind: api-key # environment values, no key: this route uses an AWS profile
env:
AWS_PROFILE: prod
llm-pi-ai/amazon-bedrock-dev:
kind: api-key # neither: the owner confirmed the ambient credential chain
你可以直接编辑该文件——存储会自动重载并接收变更，包括你删除的密钥或记录。refs 按环境变量名存放密钥值；records 按 <owner>/<id> 存放各插件的凭据，每条都带 api-key 或 grant 标签，其中 grant 的 payload 由存储逐字保留，因为只有它的拥有者能解释。产品写入时会保留注释与未触及条目的排版；直接位于某条目上方的注释属于该条目的注解，会随它一起删除。文件只存放凭据，因此任何其他内容都会被明确拒绝，而不是被静默忽略：非 mapping 的根、未知的顶层键、在其键空间内不可寻址的键、类型错误或空的值、未知的记录标签或字段、重复键以及格式错误的 YAML 都会在启动时失败；运行期热重载时则保留最后可用内容并告警。
密钥的值可以是任意文本，包括多行值——不需要任何引号技巧。空值等于「没有密钥」，这正是文件中的空字符串被拒绝的原因：移除密钥是删除它，而不是把它置空。grant 的 payload 必须经受 JSON 往返，进出两个方向都会强制这一点，因此存储会拒绝无法逐字读回的值。如果磁盘上的文件已无法解析，保存会失败，而不是覆盖产品读不懂的内容。
谁能读取该文件
只有你的 OS 用户能读取该文件：产品以仅属主可访问的权限创建它，在 POSIX 上还会拒绝加载任何其他用户可读的文件——错误会提示你运行 chmod 600。Windows 没有可检查的 mode，因此在那里跳过该检查而不是伪造它。agent 不是另一个用户：它的工具进程以你的身份运行，因此它们读这个文件与读你拥有的任何其他文件毫无二致。产品绝不把文件路径交给 agent，也绝不把文件载入环境，因此要拿到某个值，需要刻意去读一条并未交给 agent 的路径。这是审慎，不是边界：必须让提供方密钥远离自身 agent 的部署无法靠文件权限做到。
可能出错的地方
- 启动环境提供的密钥是只读的——
DEEPSEEK_API_KEY=… dsh在本轮运行中优先，保存或移除它都会被拒绝。请先在启动 shell 中清除该变量。 - 空值无法保存——存储空字符串会被拒绝；请改为移除密钥。
- 存储拒绝加载它无法信任的文件——任何其他用户可读的文件、格式错误的 YAML 或无法访问的路径都会在启动时失败；运行期热重载则保留最后可用内容并告警。
- 同一时刻的修改都会被保留——如果你在产品写入的同时编辑文件，你的变更会被并入，而不是被覆盖。
理解实现
实现细节——点击展开
本节解释提供方背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。 ### 设计理念 - **一套明确的优先级。** 继承环境优先，因为它是本次运行的明确意图且无法从进程内部修改；它之下的所有来源都输给受管存储，因此已存密钥永远不会被陈旧的 `.env` 挤掉。 - **文档只存放凭据。** 它是带 `refs` 与 `records` 分节的版本化文档，而不是 dotenv 文件：一个 harness 拥有、且绝不物化进环境的存储，不能同时充当用户的环境层，否则会以自己的优先级遮蔽非机密条目。 - **写入打补丁，重载整体替换。** 行编辑在跨进程写锁下保留注释与未触及条目；重载整体交换解析后的快照，已删除条目绝不在内存滞留。 - **信任攸关处明确报错。** 启动与重载都会拒绝不可读、无效或可被属主之外读取的文档；运行期重载失败时会保留最后可用快照并告警，而不是拖垮进程。 ### 源码地图 | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | 提供方：层解析、严格文档解析、写锁下的引用与记录写路径、watcher 生命周期、权限检查 | | — | 未发布运行时不变式配套入口；Service Definition 的配套入口（`dsh-credentials/invariant`）负责 `credentials/reference-updated` 生命周期约定；本提供方的文件与环境分层属于异步 I/O，并由其单元测试套件加以约束。 | ### 解析与写入路径 `resolve` 与 `describe` 按优先级顺序读取继承环境快照、已解析文档快照与 `.env` 后备层。`set`/`unset` 排入同一条独占操作链：入口检查提前拒绝（已释放、空值、被环境遮蔽），队列在运行时会重新判定，随后在写锁下执行读-改-写、提交，并恰好触发一次 `credentials/reference-updated`。 `modifyRecord` 走同一条链与同一把锁：它重新读取文档、把当前记录交给变更函数、准入其结果——非空的 API 密钥、能经受 JSON 往返的 grant payload——整体渲染该记录并提交，恰好触发一次 `credentials/record-updated`。并非由产品 CLI（命令行界面）启动的组合只有继承环境这一层。 ### 重载生命周期 watcher 事件或就绪时的对账会将一次刷新排到同一链条之后。`reconcileFromDisk` 重新检查权限、重读文本，文本有差异时整体替换两个快照，并按变更引用或记录逐个发布事件；与文本缓存一致的内容——包括提供方自己的写入——是 no-op。释放时设置关闭标志、停止接收事件、关闭 watcher，并等待排队操作结算完毕，确保资源销毁后不再发布任何事件。 ### 文档版本化 文档携带 `version: 1`，每次写入都会盖上版本戳。启动时若识别出预发布扁平布局——没有 `version` 的裸引用名 mapping——会在写锁下就地升级，把原始行嵌套到 `refs:` 之下，值、注释与拼写逐字节保留；任何其他无版本形态都会按名拒绝，而不会被当作空存储。运行期热重载绝不迁移：中途恢复的扁平文档会保留最后可用快照，直到下一次启动。 ### 诊断信息绝不引用值 YAML 解析器自己的消息会引用出错的那行源码，而在这份文档里那行就是机密本身。因此每条诊断只携带错误码与位置——键名可以安全打印，值不行。进一步探索
当提供方级约定不够用时阅读以下页面。它们从 seam 约定逐步进入环境快照、原子写入原语与启动期环境层。
- 凭据引用 seam——
resolve、describe、set、unset、记录操作与 seam 的更新事件。 - 凭据子系统参考——
CredentialRef、按操作解析、对 UI 安全的CredentialInfo、提供方层。 - 启动环境快照——解析读取的冻结层快照，而非
process.env。 - 原子写入——每次写入所用的写锁与原子替换。
- 应用启动与 Harness home 各层——产品 CLI 如何把
.env载入快照与process.env。
模型体验
经由 ctx.credentials 的消费方间接生效：消费方拥有存储值所启用的全部模型可见行为。
KV Cache 影响
无直接失效；存储值绝不进入请求前缀。
已知限制与延期工作
这些限制说明本提供方何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是任务积压。
- 同一引用的并发写入是后写胜出——写锁加读-改-写让并发写入者不会丢掉彼此的条目，但两个写入者编辑同一个引用时仍以较后的写入为准；没有修订检查。
- 同 UID 进程可以读取该文档——文件效果沙箱模式不会拒绝读取，OS 钥匙串提供方仍是延后项。
- 环境变化不可见——快照在启动时冻结，因此启动之后 export 的变量既不会进入解析，也不会进入
describe；要更换来自环境的凭据需要重启。 - 原子但不具备崩溃持久性——继承自
dsh-atomic-write；存储在启动时重新读取。