「命令明明还在跑,怎么输出从中间开始了?」「任务 ID 都有了,为什么说它没成功?」这两个问题在 DSH 后台任务排查中经常出现,背后其实是同一个原因:把三层不同的东西混为一谈。
排查时,下面六种误判最常见:
- 以为长命令就自动等于后台任务;
- 以为返回了任务 ID 就意味着工作会成功完成;
- 把
running/stopping当成所有输出都已可读; - 把
completed/killed/failed当成输出和副作用都符合预期; - 把输出文本当成完整输出,不知道早期部分可能已经淘汰;
- 看到任务 ID 就以为自己有权限操作它。
先记住这一点:进程句柄、任务注册表和输出环各自独立;某一层的字段,只能证明这一层的情况。 站内基础版可参考长命令和后台任务的关系。
一、命令何时才算「任务」
Shell 参考将命令执行能力置于 ctx.shell 下。调用它的 start() 后,启动准备会异步完成,随后返回一个 ShellProcess 句柄。
需要注意的是,句柄本身没有任务 ID,也没有所有者。 如果启动准备失败或被取消,请求可能在句柄发布之前就被拒绝,此时不会得到句柄。
Bash 消费者把这个进程句柄适配成 ctx.jobs.start() 的钩子,之后才由独立的 jobs 参考所述通用注册表来管理标识、所有权和生命周期。
这一区分很重要,文档明确指出:
- Shell 服务可以存在,而组合里没有 job 注册表;
- 一个 job 也可以代表 Shell 进程以外的生产者。
因此,「命令已经启动」不等于「已经有一个可跟踪的任务」,两者不能互相推导。
五条观察,各自只能证明一件事
| 观察 | 能说明什么 | 不能说明什么 |
|---|---|---|
| Shell 进程句柄 | 启动准备已发布句柄 | 已注册任务 ID |
| 任务 ID | 注册表已标识受管理工作 | 进程已成功完成 |
running 或 stopping |
工作尚未达到任务终态 | 所有输出已可获取 |
completed、killed 或 failed |
任务已经结束 | 输出或副作用符合预期 |
| 输出文本 | 已读取部分保留输出 | 更早输出没有丢失 |
这张表最好从右往左读——它列的全是「你以为证明了、其实没证明」的东西。
任务 ID 不是通行证
任务注册表使用带 kind 前缀的 ID,但访问控制依赖所有者授权,而不是 ID 保密。
因此,检查或停止带所有者的任务时,需要关注所属会话。 运行时也允许无所有者任务,因此具体生产者与部署的行为很重要。看到 ID 就觉得「这是我的任务」,是个很常见的越权假设。
二、Bash 工具何时转入后台
工具目录描述了支持 job 的一次性 Bash 工具及其 run_in_background 字段,也描述了超时时将工作转入后台的行为。
这里有一项必须留意的限制:可用 schema 取决于组合。没有 job 注册表、或者禁用了后台执行时,仅有前台形式,不暴露后台字段。
因此,先检查实际提供的工具,不要假设每次 Shell 调用都支持任务。
三个概念,不是一件事
文档明确要求:工具层行为不能与底层 Shell 执行器的超时策略混为一谈。
- Shell 请求的
onExpiry默认为kill; - 解析后的 spec 也可以指定文档支持的其他到期行为;
- 工具消费者可能对这个接缝作不同的适配。
由此得出结论:
- 命令可能被明确放到后台(
run_in_background); - 支持 job 的工具可能在超时后转入后台;
- 其他消费者也可能使用执行器自己的策略(比如直接 kill)。
长命令、超时、后台任务是相关但不同的事实。
前台结果:四个字段要一起读
对于前台结果,timedOut、aborted、signal 和 exitCode 是分别报告的字段。
有一条特别容易踩的:进程可能捕获超时信号,然后以零退出码结束。 所以单看退出码,不足以认定执行未被中断且成功。
另外,文档按首先发生的原因区分超时与调用方中止;即使它们在进程关闭前竞争,两个标记也互斥。正确做法是一起阅读完整结果,不要把这些字段压成一个状态。
三、跟踪后台命令的五个步骤
- 检查部署实际提供的 Bash 与任务控制 schema。 在依赖
run_in_background或自动转后台之前,先确认后台执行可用。 - 以合适的工作目录与权限启动命令。 如果返回了任务 ID,把它与所属会话一起记录——ID 代表需要跟踪的工作,而不是成功结果。
- 用部署提供的
job_output控件收集输出并检查状态。 持续观察到任务结束,或者你决定停止它;可用控件取决于实际组合。 - 需要取消时用
job_kill,然后观察最终状态。 注意:进入stopping不等于任务已经结束。 - 检查最终状态、详情、输出完整性和命令的实际效果。 达到终态并不自动证明命令产生的文件、服务或其他结果符合要求。
五个状态与两条会话记录
jobs 运行时分别定义 running、stopping、completed、killed 和 failed。
对于有所有者的任务,它会在原所属会话发布 job/registered 与 job/settled 两条记录,通过共同的 jobId 配对。
这两条记录的性质要说清楚:记录描述的是注册表提交,而不是操作系统进程的精确边界或 CPU 时间。 因此,缺少结束记录时,应视为证据不完整,而不是自行推断成功。
四、输出是怎样保存的
每个任务都有有界输出环。拉取型来源被泵入环中,生产者也可以追加输出;结束前注册表会最后排空一次,然后关闭流。
需要区分两种读取方式:
- 模型的消费式读取使用注册表保存的游标;
- 观察者可以按绝对偏移读取,不影响该游标。
通道包括 stdout、stderr 和 log。有一点容易误解:生产者的 log 叙述只供观察者查看,不进入模型的消费式读取。
有损读取是「正常返回」,不是错误
这里有一条尤其需要记住:由于保留空间有上限,输出开头可能被淘汰。
读取者请求的偏移早于保留窗口时,得到的是有损读取,而不是一个错误。 也就是说,读取不会提示「请求的内容已经不存在」,而会返回一段形式正常、实际不完整的输出。
JobView.output 提供 total 和 earliest 两个偏移,还可能列出拉取来源保留的完整流文件 spillPaths。注意措辞:如果报告了路径,它可能有助于查找更完整输出,但参考没有承诺每个生产者都有该文件。
因此,不要默认保留下来的尾部就是全部输出。
更低一层的句柄语义
在 Shell 层,ShellProcess 结束后仍可读取;进程结束时 done 会 resolve 而不会 reject。子进程提供方拒绝则表现为被终止的进程,并在 stderr 留下错误。
因此,句柄信息与任务注册表状态由适配器关联;不能只看其中一层的标签,就推断另一层的全部情况。
五、会话或服务结束后会怎样
Shell 参考区分了两种情况及其后果:
- 子进程服务释放时,会终止仍在运行的进程并等待
done; - 仅执行器重新加载时,让它们继续运行。
文档明确指出:这是生命周期边界,并不保证后台命令能够跨越所有重启。
jobs 运行时还会依据所属会话限制访问,并确定生命周期清理的范围。所以,「能不能在某次关闭后继续观察」这件事,应检查具体生产者和部署,不能一概而论。
证据要在还能读的时候取
生产进程结束后,任务结果可能仍可见,但输出保留有上限;而且结束时输出环还会缩减至结束后的限制。
因此,
- 需要保留证据时,应在可用期间通过受支持的控件收集,并遵循环境的数据处理规则;
- 不要猜测磁盘路径;
- 也不要认为仅凭注册表 ID,就能在重启后恢复已经丢失的进程。
六、走一遍:输出缺头,状态说不清
下面用一个具体场景串起前面的规则,看看三层信息如何分别发挥作用。
1. 现象
一条长时间运行的命令返回了任务 ID。过一会儿使用 job_output 查看输出时,发现最早的一批日志不见了,内容从中间某行开始,而状态显示为 completed。于是有人判断:「命令已经跑完,只是日志丢了」。
2. 分别检查三层信息
- 输出这一层:比较
JobView.output的earliest与你要的偏移。如果请求的偏移更早,那本来就是有损读取——不报错是设计如此。再看有没有spillPaths,但不要假定它一定存在。 - 任务这一层:
completed只说明注册表记录的终态。要确认job/registered与job/settled是否成对出现;缺少结束记录时应视为证据不完整。 - 进程这一层:后台进程的结局在事实信息里,沙箱运行器故障要看
runnerFailed;这一层的标签不能反推另一层的全部细节。
3. 三个不能省略的动作
- 记录归属:把任务 ID 与所属会话一起写下。ID 本身不是权限凭据。
- 在输出还在保留窗口内时收集证据:结束时输出环还会缩减,事后补是补不回来的。
- 核对实际效果:终态之后仍要检查命令产生的文件、服务或副作用,
completed不替你做这件事。
4. 几种容易被误认为「bug」的正常行为
- 输出从中间开始 —— 有损读取的预期行为;
- 拿不到句柄 —— 启动准备阶段就被拒绝;
- 有 ID 但操作被拒 —— 所有权或所属会话不匹配;
- 没有
run_in_background字段 —— 当前组合不暴露后台形式; - 退出码 0 但结果不对 —— 进程捕获了超时信号。
记住这五种情况,可以减少很多无效排查。想进一步区分交互式终端与后台任务,可参考后台任务与交互式终端有什么区别。
七、限制与安全边界
- 后台执行改变的是观察方式,不会让命令自动安全、授予额外权限或免除副作用审查。
- 要检查实际调用使用的沙箱与审批策略:后台化不是权限提升的替代品。
- 沙箱运行器故障与普通进程结果要分开看:前台执行可能抛出
SANDBOX_UNAVAILABLE,已结束的后台进程则在事实信息中报告runnerFailed。 - 不要静默地以更大权限重试被拒绝的操作。
- 输出和 spill 文件可能包含敏感信息:分享前应限制访问并检查内容。
- 任务所有权是授权边界,不能替代命令审查;有效 ID 不证明调用者有权限。
- 参考并不保证每个安装都提供任务注册表、全部控件、无限输出,或跨进程重启的持久任务。
- 终态不等于结果正确:
completed只说明任务结束,不说明文件、服务或副作用符合预期。 - 有损读取不会报错:请求过早的输出会得到一段看起来正常但不完整的内容。
八、术语速查
- Shell 进程句柄:执行器访问已启动进程及其输出的入口。
- 任务注册表:管理通用任务标识、所有权、输出和生命周期的服务。
- 所有者:用于限制有所有者任务访问范围的会话。
- 终态:任务进入最终结果的状态转换。
- 输出环:带绝对偏移、有界保留的任务输出。
- 有损读取:所请求的较早输出已不再保留的读取。
相关阅读
本文依据 DeepSeek Harness 官方 Shell 参考、jobs 参考和工具目录整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog