观测:job、spill 文件与 exit code 的真实语义

后台任务不是防火墙、输出超限会落到临时文件、exit 1 在 Windows 上可能只是被杀。用三份实测返回原文讲清 job_output 与退出码的读法。

目录
  1. 一、前台 vs 后台:run_in_background 分水岭
  2. 二、spill:输出超限不是截断,是搬家
  3. 三、退出码语义:Windows 上 exit 1 不等于失败
  4. 四、三层观测对象
  5. 五、一个真实的失败归因链
  6. 六、观测的三个常见误读
  7. 复盘

在 DSH 里"命令跑没跑成"不是一个是非题。同一个 exitCode: 0 可能是成功,也可能什么都没做;同一个 exitCode: 1 可能是失败,也可能是被中断。这篇把我实际遇到的三类观测对象拆开:后台 job、输出溢出(spill)、退出码语义,每个都给真实返回。

一、前台 vs 后台:run_in_background 分水岭

ops_bash 的返回有两种形态,区别不在内容而在 kind 字段。

前台(默认)返回结构化结果:

json
{
  "kind": "foreground",
  "status": "completed",
  "exitCode": 7,
  "signal": null,
  "timedOut": false,
  "stdout": { "text": "before\n", "truncated": false },
  "stderr": { "text": "", "truncated": false }
}

这条是我跑的 echo before; exit 7; echo after 的真实返回。三个细节:

  1. exitCode: 7 原样透出,不吞。
  2. stdout 只有 before——exit 之后的 echo after 没跑,符合 shell 语义。
  3. status 是 completed 而不是 failed。status 描述的是"这次执行动作结束了吗",不是"命令成功了吗",成败看 exitCode。这个区分我第一次看反了,以为 exit 7 会返回 failed。

后台(run_in_background: true)立刻返回一个句柄:

json
{ "kind": "background", "jobId": "bash-03b1b2fb2cb04671", "label": "background job probe" }

我拿这个 job 跑了 sleep 8; echo JOB-DONE; exit 7,然后用 job_output({job_id, wait: true, timeout_ms: 20000}) 收:

json
{ "status": "completed", "text": "JOB-DONE\n" }

注意 exit 7 在 job_output 的返回里消失了。它的契约是"读输出",不是"报退出码"。要看退出码得回到 job_list 的 job 最终状态,或者前台重跑。

我当时以为:后台 job 的 job_output 会给我完整结果,跟前台一样。 实际:job_output 只给文本。退出码要么在 job 状态里,要么重新前台跑一遍。

二、spill:输出超限不是截断,是搬家

我跑了个 seq 1 9000(约 9 万行)。返回里没有文本,只有一个路径:

json
{
  "exitCode": 0,
  "truncated": true,
  "spillPath": "C:\\Users\\admin\\AppData\\Local\\Temp\\dsh-subprocess-P1s2wj\\dsh-subprocess-19468-1-953a199560de-stdout.log",
  "timedOut": false
}

此处的 truncated: true 很容易被误读成"数据丢了"。实际上:

text
wc -l <spillPath>   →  9000

9000 行全在。spill 的语义是"对话里只放一小段,全量写到临时文件"。文件名里有三个标识:

片段含义
dsh-subprocess-P1s2wj每次执行一个随机临时目录
19468创建它的进程 PID(就是那个监听 3765 的 GUI 进程)
1-953a199560de子进程序号 + 随机串

这个设计解决了一个真实矛盾:命令输出可能很大,但对话上下文很贵。先落盘、再决定读不读——要细节就 read 那个路径,不要就完全不用管。

还有一条配套的账本:~/.dsh/ops-spill-ledger.jsonl。我这边它是 0 行——说明 spill 记账是惰性的,不是每次都写。

三、退出码语义:Windows 上 exit 1 不等于失败

DSH 的系统提示里专门写了一段:

text
Non-zero exits are reported as [exit code: N] markers; investigate failures
before moving on. On Windows a killed process settles as [exit code: 1]
without a signal marker; treat a bare exit 1 after an interruption as a
termination, not a command failure.

这是平台差异,不是 bug。POSIX 里进程被信号杀死,signal 字段会是 "SIGTERM" 之类;Windows 没有这套信号模型,被杀的子进程统一收尾成 exit 1 且 signal: null。

所以判断逻辑应该是:

text
exitCode === 0                          → 成功
exitCode !== 0 && signal !== null       → POSIX 信号终止
exitCode === 1 && signal === null
   && 之前发生过中断/超时               → 视为被终止,不是逻辑失败
exitCode 其它非零                        → 真的失败,读 stderr

我之前在一个中断之后看到 exit 1,花了半小时排查"为什么命令失败"——它根本没失败,是被杀了。

四、三层观测对象

排查问题时我按这个顺序看,成本从低到高:

层看什么成本能回答什么
1. 返回体status / exitCode / truncated0这次调用发生了什么
2. spill 文件spillPath 的全文一次 read输出里到底有什么
3. 会话事件流session.v4.jsonl.zstd解压 + 解析多轮之间发生了什么

第 3 层最有用也最贵。会话事件流是 zstd 多帧 JSONL,必须循环 decompressobj + unused_data 才能解全(我第一次单次解只出 1 条事件,以为文件坏了):

text
frames 199  events 540
tool/ptc-dispatch-start 90    tool/ptc-dispatch 90
step/start 58                 step/end 58
assistant/message 56          tool/call 56      tool/result 56
job/registered 10             job/settled 10
llm/retry 3                   turn/start 2      turn/end 2

这里能回答单次返回答不了的问题:llm/retry 3 说明模型层重试了 3 次;job/registered 10 和 job/settled 10 数量相等,说明没有悬挂的后台任务。

判活规则(来自 DSH监控使用说明.md,我验证过):turn/start 数量 > turn/end 数量 = 这一轮还没结束;同时会话文件 mtime 在 90 秒内被改 = 正在跑。我这轮是 2 个 turn/start、2 个 turn/end,是对齐的。

五、一个真实的失败归因链

那次压缩失败(见压缩篇)我是这样定位的:

  1. 返回体抛出 ToolCallError,消息里带 attempts=[t0:timeout (target-timeout 25000ms (elapsed 25011ms))]。
  2. 这句话同时给了预算(25000ms)和实际(25011ms),还给了原因(timeout)和候选数(t0 表示第一个候选就挂了)。
  3. 得出归因:不是配置错、不是鉴权错,是压得太多导致超时。

如果它只返回"压缩失败",我得从头猜。好的错误信息应该包含预算、实际值、原因三件事,这条我后来写脚本都在照这个标准输出。

六、观测的三个常见误读

除了上面那些,还有三种我实际犯过的读法错误。

第一种:把 truncated 当成"内容不全"。 truncated: true 只说明进对话的那份被截了,spill 文件是完整的。真正"内容不全"的信号是 status: partial 加一个 continuation 字段——那才表示还有下一页没读。这两个词长得像,含义完全不同。

第二种:只看 stdout 不看 stderr。 我有一次因为命令"成功"(exit 0)就跳过检查,结果 stderr 里全是警告,而正是那些警告解释了后面为什么输出格式不对。现在我的模板里永远把两者一起读,并且单独给 stderr.text 一个位置。

第三种:把 job 的 running 当成"还活着"。 job_list 里的状态就是工具自己记的,它不代表进程真的在跑。真正的判活要靠外部证据:会话文件的 mtime、turn/start 与 turn/end 的差值。DSH监控使用说明.md 里给的 90 秒窗口是个经验值,我实测同一个客户端写盘间隔通常远小于它。

三层里最容易被忽略的是第 2 层——spill 文件。它就在临时目录里,名字不起眼,但它是唯一能拿到完整输出的地方。我现在的习惯是:凡是一次输出超过几百行的命令,先看返回里有没有 spillPath,有就直接读那个文件的前几十行确认结构,而不是重新跑一遍命令。

复盘

观测这件事的核心是分清"执行结束"和"命令成功"——status: completed + exitCode: 7 同时出现不矛盾。第二是别被 truncated: true 骗,它可能只是搬家到 spill。第三是记住 Windows 的 exit 1 有歧义。这三条之外,最有杠杆的是会话事件流:它记了模型层看不见的东西(重试、job 生命周期、权限变更)。