ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 凭据:已提交变更与内嵌 Platform 凭证到底怎么对齐才不会混乱

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness凭据CredentialRefPlatformSession
改了凭据但解析到的还是旧值,或平台内嵌凭证与用户凭据冲突。本文讲两个键空间的分工、按操作重解析的热更新机制、reference-updated 的服务对象,以及 PlatformSession 快照的复用规则。

“凭据改了但没生效”,先别怀疑缓存层;先确认你有没有跨操作复用解析结果。 DSH plugin 的凭据 seam 明确要求每次操作重新解析:这种按操作读取本身就是热更新机制,而不是缺陷。 DSH插件 改完凭据没生效,先确认你有没有跨操作缓存解析结果。

凭据把机密挡在配置之外

配置里存的是引用,值归提供方。(来源)

dsh-credentials 的凭据 seam 把机密挡在配置之外:settings 分节与 cordis.yml 条目携带的是引用(环境变量名),值归 dsh-credentials-local 这类提供方所有。

消费方每个操作解析一次引用——LLM 适配器每次模型请求解析一次,因此轮换后的凭据无需任何重启即可作用于紧随其后的下一次请求。

有一条 seam 级规则约束每个提供方:空的存储值在任何地方都视为不存在。

两个键空间回答两个问题

引用可以回退,记录不能。(来源)

CredentialRef 回答“这个环境变量名背后是什么”:先查提供方管理的存储,再回退到进程环境与 .env 文件这类环境层。空存储值在这半边处处视为不存在——resolve 跳过它,describe 报告未配置——所以空白永远不会伪装成已配置的机密。

CredentialKey 回答“这个插件为这个 id 持有什么凭据”。这里没有分层可言:授权授予没有可读取的环境,因此记录存在本身就是全部事实。modifyRecord 是唯一的写路径,因为正确的写入依赖当前值——令牌刷新就是一次锁内的读、判断、替换。

两个键空间不要混用:想配置一个 API 密钥,用 CredentialRef;想保存一个 OAuth 授予,用 CredentialKey。

记录这半边还有三个方法:readRecord(key) 原样返回所有者写入的值,不解释 GrantRecord 载荷;describeRecord(key) 只报存在性、判别字段与可写性;listRecords() 枚举每条记录的地址与标签,但不含值。官方解释了为什么只有记录需要枚举:配置界面从 settings schema 得知引用存在,而记录没有这种发现路径,不能列出就既看不到用户被授权了什么,也找不到卸载插件留下的孤儿。

modifyRecord(key, mutate) 的排他性在存储支持时跨进程成立,这正是令牌刷新安全的前提——两个进程同时轮换同一个刷新令牌,否则先写入的那份会被覆盖。

解析:每次操作都重解析

来源层会告诉你值从哪来,这比值本身更适合排查。(来源)

引用以 POSIX 风格环境变量名命名一条凭据。brand 防止调用方将凭据引用与在包或进程之间传递的其他字符串混用;构造时校验 shell 标识符语法。

resolve(ref) 返回值及提供该值的来源层(由提供方定义;本地提供方使用 env、file、project-env 与 user-env),未配置期间返回 undefined。

消费方在每个操作中重新解析,绝不跨操作缓存。这条纪律的效果就是热更新:你在设置页保存新值,下一次模型请求立刻用它。反过来,如果你在插件里把 resolve 结果存到长期变量里,就要自己负责失效。

set(ref, value) 只接受非空值,存储值优先于环境回退;unset(ref) 移除一个不存在的引用是 no-op,而移除后环境层可能重新生效。这三条语义在提供方之间一致,所以不要写“先读再判断空串”的绕路逻辑。

describe:配置界面的事实,不含值

masked 是脱敏预览,不是完整凭据。(来源)

describe(ref) 在绝不暴露值的前提下回应配置界面:引用当前是否可解析、来自哪一层、set 当前能否成功。可选的 masked 字段携带提供方生成的脱敏预览,不包含完整凭据。

本地提供方将其管理的文件排在启动环境之前,因此保存值总会成为生效且可写的那一层;移除后会重新使用启动环境或 .env 后备值。

这解释了两个现场:保存后 source 变成提供方层是预期;移除后值又“回来”了,是后备层重新生效,而不是删除失败。

已提交变更:只服务界面刷新

reference-updated 不是给业务消费方的。(来源)

credentials/reference-updated(ref) 在提供方管理的来源发生已提交变更后发出——set、unset,或在存储中观察到的外部编辑。进程环境自身的变化不可观测,永不发出事件。

消费方不需要该事件(它们按操作重新解析);它服务于配置界面刷新「已配置」徽标。

这条分工意味着:你在插件里等这个事件来触发重连是错的;正确做法是下一次操作直接重新 resolve。

CredentialsController 承担 seam 之外的线缆义务:批量扇出的上限、逐字段的视图投影、引用语法校验与拒绝映射。完整机密值只单向流入,这里没有任何方法会把它返回。

内嵌 Platform 凭证:复用快照,不主动拉资料

userId 为 null 不会延迟调用方。(来源)

PlatformSession 是 getPlatformSession 返回的仅限 Host 快照:origin 指定所配置的 Platform 签发来源,token 包含其已存账号凭证。

userId 复制最近一次成功 getProfile 得到的稳定账号 ID;尚无一次成功读取或资料不含 ID 时为 null。快照复用该 ID,不自行发起资料请求,因此 ID 未知时只会让 userId 为 null,而不会延迟调用方。

资料读取首次取得稳定 ID 或该 ID 变化时,仅通知使用 watch(signal, true) 的 Host 订阅者,供标识使用方重新读取快照。使用方以 origin 与 userId 作为持久化浏览器存储的键,为 null 时退回临时存储。

两条失败语义:账号已退登或读取凭证期间凭证变化时不返回快照;签发来源不匹配时失败。原生使用方负责在凭证变化时使文档失效。账号 Remote API、AccountView 与 AccountDetails 均不包含此快照——它是 Host 内部事实,不是给浏览器的通用数据。

验证:提交一次变更并重新解析

验证要覆盖来源层切换、空值拒绝与界面事件。(来源) 六步:

  1. 未配置时 resolve,断言返回 undefined,describe().configured 为 false。
  2. 调 set(ref, 'sk-test'),断言 resolve 立刻返回新值且 source 是提供方层。
  3. 再调 set(ref, ''),断言被拒绝,而不是存成空串。
  4. 调 describe,断言 masked 存在但不包含完整值。
  5. 调 unset(ref) 后重新 resolve,断言后备层(环境或 .env)重新生效,或返回 undefined。
  6. 全程不重启,验证下一次请求已使用新值。

如果第 3 步存进了空串,先检查是不是绕过了 seam 直接写存储——空值语义是提供方必须遵守的 seam 级规则。

CredentialRef 的解析优先级见凭据 seam 概览;设置面板里的凭据配置见设置面板。

一句话收束: 引用可回退而记录不能、按操作重解析就是热更新、空值视为不存在、describe 只给脱敏预览、reference-updated 只服务界面、PlatformSession 复用 ID 不延迟调用方。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 修改完凭据之后,需要重启进程才能让新值生效吗?

不需要,DSH plugin 让消费方每次操作都重新解析。DSH plugin 明确要求不得跨操作缓存,这种按操作读取正是热更新机制。

DSH plugin 如果把凭据值存成空字符串,会生效吗,该怎么清除?

不会,DSH plugin 把空存储值在任何地方都视为不存在。DSH plugin 的 resolve 会跳过它,describe 报告为未配置,所以要清除请用 unset。

DSH plugin 的环境变量变化会发 reference-updated 吗?

不会,DSH plugin 明确说进程环境自身的变化不可观测。DSH plugin 只在提供方管理的来源发生已提交变更时发出该事件。

DSH plugin 的 PlatformSession 会主动查资料吗?

不会,DSH plugin 的快照复用最近一次成功读取到的账号 ID。DSH plugin 在 ID 未知时只让 userId 为 null,不会延迟调用方去发起资料请求。

相关术语

CredentialRef
CredentialRef 是以 POSIX 风格环境变量名命名的品牌化凭据引用,构造时校验 shell 标识符语法。— packages/credentials/credentials/src/index.ts
CredentialKey
CredentialKey 回答某插件为某个 id 持有哪份凭据,记录存在本身就是全部事实。— packages/credentials/credentials/src/index.ts
ResolvedCredential
ResolvedCredential 是一次解析的结果,含非空机密值与提供方定义的来源层 id。— packages/credentials/credentials/src/index.ts
PlatformSession
PlatformSession 是 getPlatformSession 返回的仅限 Host 快照,含签发来源、账号凭证与可空的稳定 userId。— packages/credentials/credentials/src/index.ts

来源