DSH plugin 插件开发的信任边界:同进程插件能做什么、哪里必须 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;空的存储值在任何地方都视为不存在。
对应到插件开发,三条做法值得固定下来:
- 配置字段存名字 — 例如
apiKeyRef: 'OPENAI_API_KEY',不要把密钥写进默认值或日志。 - 使用点解析 — 每次调用前
resolve,不把结果存进长期变量;轮换后的新值会在下一次请求生效。 - 失败不猜 — 未配置就是未配置,返回明确错误,不要回退到某个硬编码的测试密钥。
反过来,绕过 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。
这两条合起来意味着,插件拿到网页内容后要做三件事:
- 当数据处理 — 不把抓回的内容当指令执行,不拼接进系统提示词。
- 限制外发 — 需要把用户数据发出去时,先确认目标地址是允许的,而不是照着内容里的链接跳。
- 守住大小 — 抓回的内容可能很大,先按上限截断,再进入后续流程。
还有一条容易被忽略:重定向也会把你带到没预期的主机。允许的重定向由后端处理,但跨源跳转需要新的工具调用,插件不该自己跟随任意跳转去拉取内容。
DSH plugin 必须 fail-closed 的四处
这些位置“降级继续”比“直接失败”危险得多。(来源)
| 位置 | 失败时的正确反应 | 为什么不能降级 |
|---|---|---|
| 沙箱约束 | 以 SANDBOX_UNAVAILABLE 拒绝 | 官方明确静默无隔离透传永远不合法 |
| 用户审批 | 非 allowed-once 一律拒绝 | 缺失或抛错的应答者按 unavailable 处理 |
| 凭据解析 | 返回未配置错误 | 回退到猜测值等于绕过授权 |
| 路径校验 | 在 resolve 前拒绝 | target 生成后无法再判断来源 |
这四处有一个共同点:失败时继续跑,用户看不到任何异常,但风险已经发生。插件作者要做的不是“尽量让它跑起来”,而是“让它在该停的地方停下并说清楚原因”。
一份 DSH plugin 边界自检
写完插件过一遍,能挡住大部分“看起来能用”的隐患。(来源)
- 搜索代码里有没有
process.env直读凭据,能否换成CredentialRef。 - 搜索有没有
node:fs直写,能否换成ctx.fs并带上守卫。 - 检查文件路径来源,是否在 resolve 前做过符号链接或越界检查。
- 检查网络结果的使用方式,是否把外部文本当成了指令。
- 检查四处 fail-closed 的失败分支,确认没有
catch后继续执行。
验证:四类越界尝试
用一个故意越界的插件,确认每一处都真的会拒绝。(来源)
- 把凭据引用指向一个不存在的名字,断言插件返回未配置错误,而不是用空串继续调用。
- 把目标路径写成指向系统目录的符号链接,断言 resolve 前的检查拒绝,且没有发生写入。
- 抓一个返回 404 的地址,断言拿到的是带状态码的结果而不是异常,并确认后续流程按“内容不可信”处理。
- 移除沙箱后端后调用受限执行,断言以
SANDBOX_UNAVAILABLE失败,且没有命令被真正 spawn。 - 注册一个抛异常的审批应答者,断言结果是
unavailable,调用方拒绝了该操作。
如果第 2 步写入发生了,说明检查被放在了 resolve 之后;第 4 步命令跑了,说明某处把失败吞掉后继续降级执行。
凭据侧的完整解析语义可以对照凭据与已提交变更;文件守卫与补丁的细节见文件系统补丁与守卫;沙箱的逐调用策略见沙箱与 argv 包装。
一句话收束: 插件默认完全信任,边界只能自己写;凭据存引用并按次解析,路径在 resolve 前检查,外部内容只当数据,沙箱、审批、凭据、路径四处宁可失败也不要降级。
常见问题
DSH plugin 的插件代码与宿主同进程,官方沙箱约束的是受限子进程的文件效果,不是插件模块本身。DSH plugin 的 SandboxMode 只管子进程能写哪些路径,插件自己的读盘、联网、读环境变量都不经过它,所以边界要插件自己守。
DSH plugin 插件可以直接读进程环境,但那会绕开轮换与来源记录。CredentialRef 把配置里的引用与提供方持有的值分开,按操作重新解析,空存储值视为不存在;走 seam 才能拿到来源层、脱敏预览与热更新语义。
因为 DSH plugin 的 targetKey 是不透明身份,后端可能是本地路径,也可能是工作区 URI 或文件 id。DSH plugin 的 resolve 会跟随符号链接产生稳定标识,想拒绝符号链接来源必须在 resolve 之前用 lstat 检查,拿到 target 之后就无法回头判断原始路径了。
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 官方参考 - 进程沙箱
来源
- DeepSeek Harness 官方参考 - 文件系统· deepseek-ai
- DeepSeek Harness 官方参考 - 用户凭据· deepseek-ai