Files
deepseek-harness/packages/shell/bash-local/README.zh.md
T
Yichen Jiang bb20149360 refactor(shell): register foreground commands as jobs at start and drop the promotion protocol
With a job registry composed, tool-bash and tool-pwsh now register every
command with ctx.jobs as it starts and wait on the job with the registry's
own bounded wait: a command that finishes in time returns the ordinary
foreground result and its record is removed, one that outlives the timeout
returns the same job id it already had, and a kill from outside the call is
reported as `[stopped: <reason>]`. Nothing changes hands at the deadline, so
the shell seam loses `onExpiry: 'offer'`, `ShellExecution.promotion`, and
`ShellPromotionOffer`, and both local executors drop their offer arm.

The registry stays optional: the tools register a foreground-only definition
while no registry is composed and swap to the job-backed one inside a
`ctx.inject(['jobs'])` fork, so a composition without jobs keeps a plain bash
with no job tools in the model's schema. A refused registration at the start
(admission, no controller) runs under the executor's deadline kill, and a wait
that expires before the process spawned ends as the preparation timeout.

JobRegistry gains `remove(id, caller?)` and the `settled` event reports
`awaited`, so dsh-tool-jobs no longer keeps its own wait ledger; it withholds
notices for awaited settlements and for kills the model requested. The tool
catalog harvest composes the registry so the shipped schema stays documented,
and the two compaction fixtures move their context window from 10000 to 10300
tokens because the branch's larger tool schemas pushed their condensed history
over the old trigger, which requested a fourth scripted model call.
2026-09-21 15:23:08 +08:00

9.4 KiB
Raw Blame History

description, kind
description kind
面向部署方与维护者的默认 POSIX Bash 执行器说明,用于选择、配置或排查基于 shell seam 的非隔离命令执行。 package-reference

@deepseek-ai/dsh-bash-local

English | 中文

概述

dsh-bash-local 是 POSIX 上的默认 Bash 执行器:每条命令都以全新的非登录 bash -c 进程运行,不读取 rc 文件,因此调用之间不会残留任何 shell 状态。它会为每条命令应用已配置的预算——工作目录、超时、输出上限——对超时与取消进行分类,并在流溢出时返回有界输出与 spill 文件恢复。命令以 harness 进程自身的权限运行:本执行器不做任何隔离,需要沙箱能力时请组合 dsh-bash-sandbox。挂载后,面向模型的 bash 工具会与它对接。

目录


使用本包

当组合需要在 POSIX 上执行 Bash 命令且不需要隔离时,挂载此执行器。它注册为 ctx.shell,面向模型的 bash 工具会立即基于它工作:agent(智能体)调用工具,命令即以全新 bash -c 进程按下面的预算运行。

最小配置

按你需要的预算加载执行器;每个字段都有默认值,因此最小的组合就是单独一个插件条目。当组合了设置提供方时,用户段会叠加在该条目之上,预算无需重载即可在运行时变更(见运行时调整预算)。

- id: bash
  name: '@deepseek-ai/dsh-bash-local'
  config:
    cwd: /path/to/workspace
    timeoutMs: 120000
字段 默认值 含义
cwd process.cwd() 命令的默认工作目录
timeoutMs 120,000 默认前台超时,单位为毫秒
maxTimeoutMs 600,000 每次调用超时覆盖值的上限
maxOutputBytes 64,000 每流内存输出上限;溢出后 spill 到临时文件
maxSpillBytes 67,108,864 每流完整输出的 spill 上限
graceMs 3,000 终止升级与退出后管道排空的宽限时间

生成的配置目录是每个受支持字段及其 JSDoc 的穷尽式真源。

运行命令

通过等待 execution 的 result() 投影来运行命令。非零退出、超时或取消都会 resolve 为描述性结果——只有基础设施失败才 reject。每次调用的 timeoutMs 覆盖值受配置上限约束,workdir 未设置时则回退到配置的默认值;受信任的调用方还可以为单次调用提高 stdout 捕获预算,而 stderr 仍使用 maxOutputBytes。环境默认面向模型:NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat 可防止分页器与 ANSI 颜色破坏输出,调用方显式提供的条目仍然优先。

const execution = await ctx.shell.execute(ctx.shell.resolve({ command: 'ls -la' }))
const result = await execution.result()
if (result.timedOut) console.log('timed out after', result.timeoutMs)

后台进程

以 onExpiry: 'none' 解析并等待 execute 返回句柄即可在后台运行命令;不布置任何 deadline。取消或准备失败会在发布句柄前拒绝调用。readOutput() 把流增量合并为一次消费式读取,并在 [stderr] 分段下标记 stderr;kill() 终止提供方管理的 range;done 在直接命令关闭时结算且绝不 reject。job id、所有权、轮询与通知属于通用 ctx.jobs 运行时,工具层会把句柄注册进去。

运行时调整预算

当组合了设置提供方时,本执行器以组合条目为 base 注册该能力共享的 shell 设置命名空间,因此 settings.yaml 中的用户段会叠加其上,下一条命令即按新预算运行。schema 无法判定的值——正有限数字与 graceMs 的定时器上界——会在写入时被拒绝,运行中的执行器保持它最后一份可用的段;没有提供方时,运行的就是组合条目。


理解实现

实现细节——点击展开

本节解释执行器的设计并指出实现它们的代码位置;可观察行为已在使用本包中完整说明。

设计概念

本执行器是基于 subprocess 能力的 ctx.shell seam 的 Service Provider:它负责所有 bash 层职责——命令默认化与上限、deadline 融合与原因分类、面向模型的终端环境,以及后台读取合并——而 managed-range 机制(有界 spill 输出、凭据清除、终止升级、完全停稳与 dispose(资源释放))属于 subprocess 服务。每次调用都 spawn 全新的非登录 bash -c,不读取 rc 文件,因此命令是确定性的,shell 状态绝不会在调用之间泄漏。

源码地图

文件 职责
src/index.ts 插件入口:LocalBashExecutor、Config、设置段接线
— 不发布运行时不变式伴生入口;除由所属 seam 强制执行的约定外,本包不公开独立的事件序列或可变数据关系。
tests/executor.spec.ts 已演练的行为:预算、分类、后台句柄、归属
tests/settings.spec.ts 设置段叠加在组合条目之上

主要流程

一次调用分三步:resolve() 从配置与请求填充 workdir/timeoutMs/onExpiry/stdoutMaxBytes(并限制每次调用的覆盖值);execute 按到期策略布置 deadline——'kill' 把钳位后的超时与调用方的中止信号融合为一个 deadline,'none' 不布置任何 deadline——再以显式字节上限与 graceMs 通过 ctx.subprocess spawn ['bash', '-c', command];结算的 subprocess 结果被分类——只有执行器自身的超时报告 timedOut,上游取消报告 aborted,自身因信号终止的命令两者皆不报告——并投影为带收集输出的 ShellRunResult。

前台 deadline 从 argv 准备开始,并在准备与执行之间保持同一信号和剩余预算。准备阶段超时返回空输出、timedOut: true,且 exitCode 和 signal 均为 null;调用方在发布进程前取消仍会拒绝调用。准备晚到的成功或失败不会触发 spawn。

不变式与归属

  • graceMs 预算必须为正有限值且不大于 MAX_TIMER_DELAY_MS,这样 Node 就能用一个定时器表示它;无效值在写入处被拒绝。
  • 环境分层固定:先是终端覆盖值,然后是调用方的 env,最后才是受信任的 dshEnv 快照;subprocess 服务独立清除环境中的凭据与继承的 DSH_* 名称。
  • 后台进程属于 subprocess 服务:它能在仅重载执行器后存活,并在服务 dispose 时被终止且等待退出。

进一步探索

当执行器约定不够用时阅读以下页面。这些页面从 seam 讲到提供隔离的同级包及其底层机制。

  • shell seam —— 本提供方实现的执行器约定,包括请求/spec 拆分。
  • bash-sandbox —— 需要沙箱能力时,应改为组合此隔离执行器。
  • tool-bash —— 基于本执行器的面向模型 bash 工具。
  • Bash 执行器子系统 —— 请求/spec 词汇、结果与完整的服务约定。
  • subprocess-local —— 本执行器背后的 managed-range 机制。

模型体验

通过 dsh-tool-bash 间接影响;该工具会渲染本执行器有界的 stdout/stderr 尾部、后台进程增量、spill 文件路径与基础设施失败。

KV Cache 影响

不会直接导致 KV Cache 失效;请求前缀的任何变更由具名消费方负责。

已知限制与延期工作

这些限制说明本执行器何时不合适。它们是当前包约束,不是路线图。

  • 自身不提供隔离——命令以 harness 进程的权限运行;需要隔离的部署组合 dsh-bash-sandbox,每次调用的 allow/deny/ask 策略则属于工具的 pre-execute waterfall(瀑布式事件)。
  • 没有持久 shell 或 PTY——每次调用都启动全新的非登录 bash -c;仅持久化 cwd 与交互式终端会话均继续延期,直到真实工作流需要它们。
  • 仅支持 POSIX——bash 二进制已硬编码,底层服务的进程组语义也是 POSIX 的;不支持 Windows。
  • 后台提供方失败提示就是整条 stderr 流——SubprocessHandle.done 可能在目标命令开始执行前或后被拒绝,而 subprocess 服务不会为从未上报结果的目标命令 缓冲任何输出,因此执行器把不声明失败阶段的 subprocess failed before reporting an outcome: … 作为观测到的 stderr 流提供(偏移读取方按各自偏移重读),并只折入恰好一个 readOutput() 增量;丢弃了该增量的消耗式读取方只能经 observed.stderr 恢复它。

开发备注

维护者的工作上下文——点击展开

无。