DSH plugin 的 ShellExecRequest:resolve 拆分、前后台与沙箱信息
把 ShellExecRequest 直接丢给执行器,是接 shell seam 时最常见的错误。 DSH plugin 把“调用方想要什么”和“执行器实际按什么跑”拆成两个类型,中间必须过一次 resolve()。跳过这一步,前后台行为就会分叉。 DSH插件 接 shell seam 时把请求与规格分开看,前后台行为就不会分叉。
resolve 把请求和规格分成两层
请求允许缺省,规格必须齐全,缺省值的补全与封顶都发生在 resolve()。(来源)
ShellExecRequest 是面向模型或插件的形状:command 必填,workdir、timeoutMs、onExpiry、stdoutMaxBytes、signal、stdin、env、dshEnv 与 sandboxPolicy 都可有可无。ShellExecSpec 则是执行器实际使用的完全解析规格:workdir、timeoutMs、onExpiry 与 stdoutMaxBytes 全部必填。
工具层的正确顺序是:先 ctx.shell.resolve(request),再 execute(spec)。这条规则对应仓库的“包边界处显式优于隐式”——默认值不在执行器里偷偷补,而是在边界上显式补完。
onExpiry 默认是 'kill'。当它被解析成 'none' 时,解析后的 timeoutMs 不武装任何定时器,只会原样回显到 ShellRunResult.timeoutMs。这个细节解释了为什么有些调用“设了超时却没被杀”:值存在,但不生效。
DSH_* 环境是 Harness 所有的事实
DSH_* 不是普通环境变量,它们由框架重建,不能被继承值污染。(来源)
面向模型的 bash 工具通过 ctx.shellEnv 收集这些变量,再经 ShellExecRequest.dshEnv 传递;子进程服务在合并当前快照之前会移除继承而来的 DSH_* 名称。因此一个不可用的当前事实不会继承 harness 进程里的旧值。
DshEnvironmentKey 与 DshEnvironment 词汇归子进程 seam 所有,由 dsh-shell 重导出。ctx.shellEnv 注册表本身很窄:register(contributor) 注册一个贡献者(名称与键唯一,内建键保留,随调用 fiber 销毁)、collect(execution) 生成一次执行的可信快照、list() 只枚举声明而不执行解析器。
stdin 与 env 是受信任的进程内插件输入,不由 dsh-tool-bash 暴露。本地执行器会先清除环境中的凭据,再合并调用方显式提供的 env;dshEnv 在最后合并,所以 env 条目永远无法顶替受管事实。模型需要 stdin 时应当用 heredoc 或管道,而不是指望这个参数。
前台结果:四个正交字段
超时、取消、退出码、信号分别独立报告,不能用一个布尔值概括。(来源)
ShellRunResult 的字段设计就是为了防止误读:
exitCode— 退出码;准备阶段过期或进程被信号杀死时为null;signal— 终止信号,没有报告时为null;timedOut— 执行器自身超时是第一因时为true;aborted— 调用方AbortSignal是第一因时为true;timeoutMs— 本次运行实际生效的超时(补全与封顶之后);stdout/stderr— 两条CollectedOutput;sandbox— 沙箱事实,未沙箱化时缺失。
timedOut 与 aborted 互斥:一个融合的截止时间同时驱动超时与调用方取消,两者在进程关闭前竞速时只报告第一因。但 timedOut 与 exitCode 不互斥——一个进程可以同时超时并以 0 退出,因为它捕获了信号。这就是“四个正交字段”的含义。
每个流是一个 CollectedOutput:可能被截断的文本加恢复信息。截断时 text 是尾部,完整流会溢出到一个私有文件。这些字段归子进程 seam 所有,由 dsh-shell 重导出。
后台句柄:没有 id,也没有 owner
start() 返回的是进程句柄,不是任务;任务身份由上层运行时接管。(来源)
start() 在异步启动准备完成后返回句柄;取消或准备失败会在发布前拒绝调用。句柄没有 id 或 owner——dsh-tool-bash 把它适配为 ctx.jobs.start() 钩子,随后由通用运行时拥有任务标识与生命周期。
done 在底层进程结算时完成,且绝不 reject;子进程提供方的拒绝会生成状态为 killed 的进程,并把不声明阶段的错误写入 stderr。进程结算后仍可读取输出,沙箱事实会在 done 完成前写入。
三个读取相关的方法各有边界:
readOutput()— 消费式增量读取,连续读取不会重复投递;丢数据时置lossy,并给出stdoutSpillPath或stderrSpillPath;observed— 非消费式偏移读取,独立的观察者不会从readOutput抢走字节,还能读到被拒绝 spawn 留在 stderr 的提供方失败说明;kill()— 终止提供方管理的范围,已结束则返回false,幂等。
前后台的分界是“调用方等什么”
“前台”不是 spawn 的属性,而是调用方等到的位置。(来源)
官方说得很直接:等 ShellExecution.result 的调用方跑的是前台;保留句柄的调用方跑的是后台。只等一会儿的调用方会用 onExpiry: 'none' 并自行限时,句柄在调用方停止等待后仍然有效。
result 只在基础设施失败时 reject。非零退出、超时被杀、取消被杀都会以描述性结果 resolve,并带上第一因与回显的 timeoutMs。所以“命令失败”不该用 try/catch 接,而该读 exitCode 与 timedOut。
还有一条生命周期事实值得记住:仍在运行的进程会在其所属组合拆除时被停止并等待。与子进程 seam 一起时,这个边界是 ctx.subprocess 的销毁,因此只重载执行器不会杀掉进程。
沙箱事实与拒绝分类
沙箱信息独立于退出状态报告,拒绝与失败要分开看。(来源)
使用沙箱的执行器通过 sandboxMode 暴露已配置的模式回退值。工具层请求 @deepseek-ai/dsh-sandbox-policy,把每个调用会话的持久 sandbox/mode 覆盖值与不可变 cwd 解析为 ShellExecRequest.sandboxPolicy;经用户批准、严格更宽松的调用只替换模式。模式仅管辖文件效果。
ShellSandboxInfo 报告四件事:实际运行的模式 mode、是否拒绝了文件操作 denied、强制执行完整度 enforcement,以及命令运行前沙箱 runner 是否已失败 runnerFailed。
两条故障路径要分清:前台执行在受限模式没有可用后端时会抛出 SANDBOX_UNAVAILABLE;已结束的后台进程只能通过事实通道报告 runnerFailed。模型在结果中会收到拒绝与 runner 事实,仅当拒绝标记指出生效模式时才得知该模式。
验证:同一命令走前后台
验证要覆盖结果字段的正交性,以及两种句柄的读取语义差别。(来源) 六步:
- 用
resolve()解析一个只给command的请求,断言workdir、timeoutMs、onExpiry、stdoutMaxBytes都已补齐。 - 前台跑一个超过
timeoutMs的命令,断言timedOut为真、exitCode为null、输出为截断尾部。 - 前台跑一个捕获信号后以 0 退出的命令,断言
timedOut与exitCode同时有值。 - 后台起一个持续输出的命令,连续两次
readOutput(),断言第二次不含第一次的字节。 - 后台跑一个被沙箱拒绝的命令,断言
denied为真,且前台等价调用会抛SANDBOX_UNAVAILABLE。 - 只重载执行器,断言后台进程仍在运行;拆除
ctx.subprocess后再断言它被停止并等待。
如果第 3 步结果不是“同时有值”,说明实现把超时与退出码合成了一个状态,那会掩盖进程自己处理了信号的事实。
shell 与子进程 seam 的整体分工,可以对照shell 与子进程 seam;spawn spec 的细节见子进程 spawn spec。
一句话收束: 请求过 resolve 才成规格,DSH_* 由框架重建,结果字段正交报告,后台句柄没有身份,沙箱拒绝与命令失败要分开读。
常见问题
不能,DSH plugin 要求先过 resolve。DSH plugin 的 execute 只接收完全解析后的 ShellExecSpec,可选字段的默认值与上限都由 resolve 补全,工具层不该跳过这一步。
不一定,DSH plugin 的字段是正交报告的。DSH plugin 允许一个进程同时超时并以 0 退出(例如它捕获了信号),所以 timedOut 与 exitCode 是两个独立事实。
不能,DSH plugin 的 ShellProcess 没有 id 也没有 owner。DSH plugin 由 dsh-tool-bash 把它适配到 ctx.jobs.start(),任务标识与生命周期此后归通用运行时。
不会,DSH plugin 的 readOutput 是消费式读取。DSH plugin 连续读取不会重复投递;如果截断丢了未读字节,会置 lossy 并给出可用的 spill 文件路径。
相关术语
- ShellExecRequest
- ShellExecRequest 是面向模型或插件的执行请求,workdir、timeoutMs 与 stdoutMaxBytes 等字段可选,由 resolve 补全。— packages/shell/shell/src/types.ts
- ShellExecSpec
- ShellExecSpec 是执行器实际使用的完全解析规格,workdir、timeoutMs、onExpiry 与 stdoutMaxBytes 等字段均为必填。— packages/shell/shell/src/types.ts
- ShellRunResult
- ShellRunResult 是前台运行结果,正交报告 exitCode、signal、timedOut、aborted、timeoutMs 与两条输出流。— packages/shell/shell/src/types.ts
- ShellProcess
- ShellProcess 是后台进程句柄,提供状态、退出事实、done、readOutput、observed 与 kill,但没有 id 或 owner。— packages/shell/shell/src/types.ts
来源
- DeepSeek Harness 官方参考 - Shell 执行器· deepseek-ai
- packages/shell/shell/src/types.ts· deepseek-ai