ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 插件开发的信任边界:同进程插件能做什么、哪里必须 fail-closed

插件开发发布于 2026-11-17作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness插件开发信任边界fail-closed
插件能读凭据吗、能任意写盘吗、外部内容该不该信?本文按凭据、文件、网络与审批四处边界展开,说明同进程插件的默认信任模型、四处必须 fail-closed 的位置,以及四类越界尝试的验证方式。

插件开发的第一条安全事实:插件代码和宿主同进程,框架不为你的模块提供沙箱。 官方的沙箱策略约束的是受限子进程能写哪些路径,不约束插件自己读环境变量、读文件、发请求。(来源)所以 DSH插件 的边界不是“框架拦住你”,而是“你自己在哪一行选择拒绝”。

DSH plugin 同进程意味着默认完全信任

信任模型的默认值是“你能做宿主能做的一切”,安全靠自律与 seam。(来源)

插件通过 apply(ctx) 拿到上下文,用 ctx.fs、ctx.web、ctx.approval 这些入口做事。这些入口是能力 seam,不是权限门:它们提供一致的语义与错误分类,但不阻止你绕过去直接 node:fs 或 fetch。

这条事实决定了三件事。第一,安全边界必须在代码里显式写出来,不能指望框架兜底。第二,绕开 seam 的代价不是报错,而是丢失来源记录、守卫与可观测性。第三,review 插件时要看“有没有绕”,而不只看“调没调对 API”。

下面四处是插件开发里最常需要做判断的地方。

凭据边界:DSH plugin 的引用归配置,值归提供方

配置里放的应该是引用,不是明文;解析结果也不该跨操作缓存。(来源)

官方把凭据拆成两半:settings 与 cordis.yml 携带引用(环境变量名),值归 dsh-credentials-local 这类提供方所有。resolve 每次操作重新解析,先查提供方存储,再回退到环境与 .env;空的存储值在任何地方都视为不存在。

对应到插件开发,三条做法值得固定下来:

  1. 配置字段存名字 — 例如 apiKeyRef: 'OPENAI_API_KEY',不要把密钥写进默认值或日志。
  2. 使用点解析 — 每次调用前 resolve,不把结果存进长期变量;轮换后的新值会在下一次请求生效。
  3. 失败不猜 — 未配置就是未配置,返回明确错误,不要回退到某个硬编码的测试密钥。

反过来,绕过 seam 直接读 process.env 也能跑,但你拿不到来源层、脱敏预览与“空值视为不存在”的一致性,排查时少一条线索。

文件边界:DSH plugin 的不透明身份与符号链接

拿到 target 之后就没有原始路径了,想拒绝符号链接必须在 resolve 之前。(来源)

文件系统的入口先把路径解析成 FsTarget,targetKey 是不透明身份:本地后端可能是 realpath 风格的字符串,远程后端可能是工作区 URI 或文件 id。消费方可以展示 displayPath,但不该解析 targetKey 来拼路径或做判断。

安全上最关键的一条是符号链接:resolve() 会有意跟随 symlink 以产生稳定标识,而 lstat 不跟随。所以“拒绝指向系统目录的软链”这类规则只能写在 resolve 之前;一旦拿到 target,你已经无法区分它原本是文件还是软链。

写文件时同理:守卫(createIfAbsent、replaceIfVersion)防的是覆盖与并发,不防路径本身指向哪里。路径来源不可信时,先做解析前的检查,再谈写入。

网络边界:DSH plugin 把外部内容当数据

抓取成功不等于内容可信,非 2xx 也只是结果而不是异常。(来源)

Web seam 的语义是:HTTP 状态码属于被抓资源的状态,404 或 500 仍然返回带状态码与正文的结果;WebError 只用于无法安全获取或表示资源的情况。同时,HTTP 提供方不限制目的地址,模型可以把数据发到它能访问的任何 URL。

这两条合起来意味着,插件拿到网页内容后要做三件事:

  1. 当数据处理 — 不把抓回的内容当指令执行,不拼接进系统提示词。
  2. 限制外发 — 需要把用户数据发出去时,先确认目标地址是允许的,而不是照着内容里的链接跳。
  3. 守住大小 — 抓回的内容可能很大,先按上限截断,再进入后续流程。

还有一条容易被忽略:重定向也会把你带到没预期的主机。允许的重定向由后端处理,但跨源跳转需要新的工具调用,插件不该自己跟随任意跳转去拉取内容。

DSH plugin 必须 fail-closed 的四处

这些位置“降级继续”比“直接失败”危险得多。(来源)

位置失败时的正确反应为什么不能降级
沙箱约束以 SANDBOX_UNAVAILABLE 拒绝官方明确静默无隔离透传永远不合法
用户审批非 allowed-once 一律拒绝缺失或抛错的应答者按 unavailable 处理
凭据解析返回未配置错误回退到猜测值等于绕过授权
路径校验在 resolve 前拒绝target 生成后无法再判断来源

这四处有一个共同点:失败时继续跑,用户看不到任何异常,但风险已经发生。插件作者要做的不是“尽量让它跑起来”,而是“让它在该停的地方停下并说清楚原因”。

一份 DSH plugin 边界自检

写完插件过一遍,能挡住大部分“看起来能用”的隐患。(来源)

  1. 搜索代码里有没有 process.env 直读凭据,能否换成 CredentialRef。
  2. 搜索有没有 node:fs 直写,能否换成 ctx.fs 并带上守卫。
  3. 检查文件路径来源,是否在 resolve 前做过符号链接或越界检查。
  4. 检查网络结果的使用方式,是否把外部文本当成了指令。
  5. 检查四处 fail-closed 的失败分支,确认没有 catch 后继续执行。

验证:四类越界尝试

用一个故意越界的插件,确认每一处都真的会拒绝。(来源)

  1. 把凭据引用指向一个不存在的名字,断言插件返回未配置错误,而不是用空串继续调用。
  2. 把目标路径写成指向系统目录的符号链接,断言 resolve 前的检查拒绝,且没有发生写入。
  3. 抓一个返回 404 的地址,断言拿到的是带状态码的结果而不是异常,并确认后续流程按“内容不可信”处理。
  4. 移除沙箱后端后调用受限执行,断言以 SANDBOX_UNAVAILABLE 失败,且没有命令被真正 spawn。
  5. 注册一个抛异常的审批应答者,断言结果是 unavailable,调用方拒绝了该操作。

如果第 2 步写入发生了,说明检查被放在了 resolve 之后;第 4 步命令跑了,说明某处把失败吞掉后继续降级执行。

凭据侧的完整解析语义可以对照凭据与已提交变更;文件守卫与补丁的细节见文件系统补丁与守卫;沙箱的逐调用策略见沙箱与 argv 包装。

一句话收束: 插件默认完全信任,边界只能自己写;凭据存引用并按次解析,路径在 resolve 前检查,外部内容只当数据,沙箱、审批、凭据、路径四处宁可失败也不要降级。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 插件开发的代码会被框架沙箱限制吗,还是和宿主完全同权限?

DSH plugin 的插件代码与宿主同进程,官方沙箱约束的是受限子进程的文件效果,不是插件模块本身。DSH plugin 的 SandboxMode 只管子进程能写哪些路径,插件自己的读盘、联网、读环境变量都不经过它,所以边界要插件自己守。

DSH plugin 里插件能直接读环境变量里的凭据吗,还是必须走凭据 seam?

DSH plugin 插件可以直接读进程环境,但那会绕开轮换与来源记录。CredentialRef 把配置里的引用与提供方持有的值分开,按操作重新解析,空存储值视为不存在;走 seam 才能拿到来源层、脱敏预览与热更新语义。

DSH plugin 文件系统为什么强调不要解析 targetKey,这对安全有什么影响?

因为 DSH plugin 的 targetKey 是不透明身份,后端可能是本地路径,也可能是工作区 URI 或文件 id。DSH plugin 的 resolve 会跟随符号链接产生稳定标识,想拒绝符号链接来源必须在 resolve 之前用 lstat 检查,拿到 target 之后就无法回头判断原始路径了。

DSH plugin 插件开发时哪些失败必须拒绝而不是降级,比如沙箱起不来还能继续跑吗?

DSH plugin 在受限策略下不能继续。它明确要求静默的无隔离透传永远不合法,没有可用后端时 confine 以 SANDBOX_UNAVAILABLE 拒绝。审批同理,只有 allowed-once 才放行,缺失或抛错的应答者一律按 unavailable 拒绝。

相关术语

CredentialRef
CredentialRef 是以 POSIX 风格环境变量名命名的品牌化凭据引用,解析时先查提供方存储,再回退到环境与 .env 层。— DeepSeek Harness 官方参考 - 用户凭据
FsTarget
FsTarget 是文件系统后端解析出的稳定身份,含不透明 targetKey 与仅供展示的 displayPath,消费方不得解析 targetKey。— DeepSeek Harness 官方参考 - 文件系统
ApprovalOutcome
ApprovalOutcome 是闭合的审批结果,只有 allowed-once 允许继续,rejected、cancelled 与 unavailable 一律按拒绝处理。— DeepSeek Harness 官方参考 - 用户审批
SandboxMode
SandboxMode 是受限进程的文件效果策略,取值为 read-only、workspace-write 与 danger-full-access,只管文件不管网络。— DeepSeek Harness 官方参考 - 进程沙箱

来源