DSH plugin 子进程:spawn spec、stdio 处置与退出事实到底怎么读懂
自己 spawn 子进程时,“输出抓不全”与“退出原因说不清”通常来自同一个误解:以为 seam 会替你兜底。 DSH plugin 的子进程 seam 明确不应用任何默认值,每条流的处置、每个限制、每个目录都得在 spec 上写清楚。 DSH插件 自己 spawn 子进程时,把 stdio 的每条路都写清楚,输出才不会抓不全。
这个 seam 不应用任何默认值
所有处置与限制都由调用方显式给出,隐藏默认值被视为设计缺陷。(来源)
SubprocessSpawnSpec 的字段就是全部输入:argv、cwd、stdio、graceMs、可选 signal 与可选 env。官方注释写得很直白:该 seam 不应用任何默认值,因为应由调用方自己的配置决定这些值,而不是由某个隐藏的子进程服务默认值决定。
argv 绝不经过 shell 解释——argv[0] 是程序,其余是参数。这和 dsh-shell 的请求/规格拆分是同一套思路:显式在边界上完成,执行层不再猜。如果你需要管道或重定向,显式跑一个 shell 并把命令作为参数传进去。
graceMs 也有明确约束:正有限毫秒数,且不大于 MAX_TIMER_DELAY_MS。它既是提供方终止过程的宽限期,也用于进程退出后排空仍未关闭的收集管道——一个幸存者持有的继承描述符不能无限期拖住结果。
可执行文件查找属于同一个执行世界
spawn 的工作目录、可执行路径与文件系统提供方共享同一套路径与进程命名空间。(来源)
resolveExecutable(command, env?, signal?) 做两件事:验证绝对可执行文件路径,或通过提供方清理后的 PATH 加有意覆盖来解析裸名称。
一条容易被忽略的拒绝规则:含分隔符的相对路径会被拒绝,因为解析基准未定义,提供方宁可显式失败也不猜。SubprocessExecutableNotFoundError 表示可执行文件不存在;提供方与传输故障仍作为普通错误报告,两者不要混成一个错误处理分支。
受管 DSH_* 与 env 的合并顺序
DSH_* 先被丢弃再注入,调用方 env 无法冒充受管事实。(来源)
DSH_* 是归 Harness 所有的子进程事实。实现会在合并调用方显式 env 之前,丢弃环境中已有的 DSH_* 名称,因此当前事实只会以有意提供的字符串条目形式到达。
env 的合并语义还有两个细节:它被合并到提供方清理过的父环境基底上,且不做命名空间校验;一个字符串就是调用方有意的选择,所以被转发的凭据形条目或当前 DSH_* 事实会穿过清除保留下来。而显式的 undefined 是一个墓碑,会删除子进程普通环境里已有的值。
这条设计意味着“清除”不是绝对安全网,而是默认基线:你要主动传,才会带过去。
stdio 处置全部显式
三种输出处置对应三种完全不同的消费方式。(来源)
stdin 有三种:'ignore' 把 fd 0 留在 /dev/null;'pipe' 暴露 handle.stdin 供调用方持续写入;{ data } 写入字节后关闭,即批处理形态。
stdout 与 stderr 有三种:'pipe' 暴露原始 Readable 给调用方做协议解码;'inherit' 直通父描述符,子进程诊断落到 harness 自己的流上;SubprocessCollect 对象做有界内存缓冲,并提供基于偏移的读取。
collect 形态有两个上限:maxBytes 是内存上限,溢出时保留尾部;可选 spill.maxBytes 是整流产的上限,流比它更大时会丢弃已经不完整的 spill 文件。官方给出的取舍很清楚——协议分帧(LSP JSON-RPC、ACP ndjson)用原始管道,诊断直通用 inherit,有界批量输出用收集模式;spill 可选,所以语言服务器的 stderr 可以只在内存里留个尾部,不落任何文件。
还有 control?: 'pipe':请求一条独立的字节模式双工通道,省略就不创建。原生启动失败可能让它缺失,读取前要先判空。
需要判断“这个环境里默认用哪个 shell”时,用 terminalEnvironment(signal?),它返回执行环境的平台(posix 或 windows)与可选的 defaultShell。这些事实来自提供方,而非 Web 服务器或浏览器;可执行文件查找与终端分配仍是独立操作。
句柄:读取器不消费,终止走 managed range
收集模式的读取按偏移进行,多个读者互不抢字节。(来源)
spawn 同步返回活动句柄,目标与受管范围标识保留在 provider 内部。收集模式读取器接受全流字节偏移量且从不消费,所以独立读取器不会抢走彼此的增量;管道化的流归调用方所有。
SubprocessOutputReader.readFrom(fromByte) 返回四项:text、nextOffset、lossy 与可选 spillPath。当请求的偏移已经滑出内存尾部窗口时读取是 lossy 的——它返回整段保留尾部,缺口只能从 spill 文件恢复。结算后调 readFrom(0) 就是批处理结果,此时 lossy 意味着内存尾部丢了头,对应 CollectedOutput.truncated 事实。
终止有两个动词:terminate() 启动提供方记录的终止过程,幂等、范围消失后是 no-op,spec 的 abort 信号也会触发它;waitForExit(signal?) 观察同一个 provider-managed range,而不只是 spawn 命令的结束,因此幸存的工作仍然可观察。范围为空返回 true,信号先中止返回 false,提供方无法再观察范围时抛错。
结果只承载退出事实
done 不判定超时与取消,也不带输出。(来源)
SubprocessOutcome 只有两个字段:exitCode(信号致死时为 null)与 signal(正常退出时为 null)。它是 Node close 事件的词汇,刻意不含超时或取消分类,也不含输出。
原因分工很明确:服务会在中止时终止进程,但绝不判定原因;调用方读取归自己所有的 deadline 信号来做分类,例如 bash 执行器的 timedOut/aborted 拆分。收集到的输出在结算后仍可经 handle.collected 读取,因此批量与流式调用方共用一条访问路径。
如果你想在 done 里找“是不是超时了”,那一定找错层了。超时是你自己的定时器事实,不是子进程事实。
终端原语不是 spawn 的替代品
需要控制终端语义时用 spawnTerminal,普通 spawn() 重建不出来。(来源)
spawnTerminal(spec) 是非管道进程原语。提供方分配控制终端,并负责 UTF-8 文本传输、前台进程组检查与信号发送,以及一项须等待的 TERM→KILL 操作;该操作会让提供方仍可观察到的每个会话成员完全停稳。
它的定位边界也很清楚:PTY 后端仍负责提示符检测、就绪推断、scrollback、沙箱策略与持久会话所有权。终端句柄公开 pid、有序输出、done、write、resize、inspectForeground、inspectActivity、signalForeground 与须等待的 terminate。resize(cols, rows) 更新正在运行的 PTY 尺寸,进程退出后拒绝调用;inspectActivity() 的 state 只会是 idle、busy 或 unknown,revision 随观察到的活动或输入变化。
验证:大输出与信号退出
验证要覆盖截断、偏移读取与退出事实三件事,缺一件就会漏掉一类线上问题。(来源) 六步:
- 用 collect 模式 spawn 一个输出超过
maxBytes的命令,断言readFrom(0)的lossy为真且给出spillPath。 - 不启用 spill 重复上一步,断言
lossy仍为真但没有路径,且只拿到尾部。 - 两个读取器各自用不同偏移读同一条流,断言互不影响、没有字节被抢走。
- 发一个
SIGTERM让命令自行退出,断言done的signal是SIGTERM、exitCode为null。 - 用已预中止的
signal调spawn,断言同步抛错,且没有句柄发布。 - 调用
terminate()后再调waitForExit(),断言范围清空;对一个已结束的句柄再terminate(),断言是 no-op。
如果第 1 步没有 lossy,先确认是否误用了管道模式——管道从不缓冲,也不会给你偏移读取。
shell 层怎么把请求解析成 spec,可以对照Shell resolve 拆分;大输出截断的编码问题见子进程字节截断与 UTF-8。
一句话收束: spec 不做默认值、argv 不过 shell、DSH_* 先清后注,stdio 三条路各管一段,读取按偏移不消费,done 只报退出事实。
常见问题
不会,DSH plugin 的 spawn spec 不应用任何默认值。DSH plugin 要求每条流的处置、限制与目录都显式给出,由调用方自己的配置决定,而不是某个隐藏的服务默认值。
不会,DSH plugin 明确 argv 绝不经过 shell 解释。DSH plugin 把 argv[0] 当程序、其余当参数,需要 shell 语法请显式调用 shell。
不会,DSH plugin 的读取器接受全流字节偏移且从不消费。DSH plugin 让独立读取器各自按偏移读取,不会抢走彼此的增量;管道化的流则归调用方所有。
不会,DSH plugin 的 done 只承载退出事实。DSH plugin 在中止时终止进程但不判定原因,调用方要读自己拥有的 deadline 信号来做 timedOut 与 aborted 分类。
相关术语
- SubprocessSpawnSpec
- SubprocessSpawnSpec 是完全指定的 spawn 请求,含 argv、cwd、stdio、graceMs、可选 signal 与 env。— packages/subprocess/subprocess/src/types.ts
- SubprocessCollect
- SubprocessCollect 是单条流的有界内存收集配置,含 maxBytes 与可选的整流产 spill 上限。— packages/subprocess/subprocess/src/types.ts
- SubprocessHandle
- SubprocessHandle 是活动子进程句柄,提供流、收集读取器、done、terminate 与 waitForExit。— packages/subprocess/subprocess/src/types.ts
- SubprocessOutcome
- SubprocessOutcome 只承载 Node close 事件词汇的退出码与信号,不含超时或取消分类,也不含输出。— packages/subprocess/subprocess/src/types.ts
来源
- DeepSeek Harness 官方参考 - 子进程· deepseek-ai
- packages/subprocess/subprocess/src/types.ts· deepseek-ai