观测:job、spill 文件与 exit code 的真实语义
后台任务不是防火墙、输出超限会落到临时文件、exit 1 在 Windows 上可能只是被杀。用三份实测返回原文讲清 job_output 与退出码的读法。
目录
在 DSH 里"命令跑没跑成"不是一个是非题。同一个 exitCode: 0 可能是成功,也可能什么都没做;同一个 exitCode: 1 可能是失败,也可能是被中断。这篇把我实际遇到的三类观测对象拆开:后台 job、输出溢出(spill)、退出码语义,每个都给真实返回。
一、前台 vs 后台:run_in_background 分水岭
ops_bash 的返回有两种形态,区别不在内容而在 kind 字段。
前台(默认)返回结构化结果:
{
"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 的真实返回。三个细节:
exitCode: 7原样透出,不吞。stdout只有before——exit之后的echo after没跑,符合 shell 语义。status是completed而不是failed。status描述的是"这次执行动作结束了吗",不是"命令成功了吗",成败看exitCode。这个区分我第一次看反了,以为 exit 7 会返回failed。
后台(run_in_background: true)立刻返回一个句柄:
{ "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}) 收:
{ "status": "completed", "text": "JOB-DONE\n" }注意 exit 7 在 job_output 的返回里消失了。它的契约是"读输出",不是"报退出码"。要看退出码得回到 job_list 的 job 最终状态,或者前台重跑。
我当时以为:后台 job 的
job_output会给我完整结果,跟前台一样。 实际:job_output只给文本。退出码要么在 job 状态里,要么重新前台跑一遍。
二、spill:输出超限不是截断,是搬家
我跑了个 seq 1 9000(约 9 万行)。返回里没有文本,只有一个路径:
{
"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 很容易被误读成"数据丢了"。实际上:
wc -l <spillPath> → 90009000 行全在。spill 的语义是"对话里只放一小段,全量写到临时文件"。文件名里有三个标识:
| 片段 | 含义 |
|---|---|
dsh-subprocess-P1s2wj | 每次执行一个随机临时目录 |
19468 | 创建它的进程 PID(就是那个监听 3765 的 GUI 进程) |
1-953a199560de | 子进程序号 + 随机串 |
这个设计解决了一个真实矛盾:命令输出可能很大,但对话上下文很贵。先落盘、再决定读不读——要细节就 read 那个路径,不要就完全不用管。
还有一条配套的账本:~/.dsh/ops-spill-ledger.jsonl。我这边它是 0 行——说明 spill 记账是惰性的,不是每次都写。
三、退出码语义:Windows 上 exit 1 不等于失败
DSH 的系统提示里专门写了一段:
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。
所以判断逻辑应该是:
exitCode === 0 → 成功
exitCode !== 0 && signal !== null → POSIX 信号终止
exitCode === 1 && signal === null
&& 之前发生过中断/超时 → 视为被终止,不是逻辑失败
exitCode 其它非零 → 真的失败,读 stderr我之前在一个中断之后看到 exit 1,花了半小时排查"为什么命令失败"——它根本没失败,是被杀了。
四、三层观测对象
排查问题时我按这个顺序看,成本从低到高:
| 层 | 看什么 | 成本 | 能回答什么 |
|---|---|---|---|
| 1. 返回体 | status / exitCode / truncated | 0 | 这次调用发生了什么 |
| 2. spill 文件 | spillPath 的全文 | 一次 read | 输出里到底有什么 |
| 3. 会话事件流 | session.v4.jsonl.zstd | 解压 + 解析 | 多轮之间发生了什么 |
第 3 层最有用也最贵。会话事件流是 zstd 多帧 JSONL,必须循环 decompressobj + unused_data 才能解全(我第一次单次解只出 1 条事件,以为文件坏了):
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,是对齐的。
五、一个真实的失败归因链
那次压缩失败(见压缩篇)我是这样定位的:
- 返回体抛出
ToolCallError,消息里带attempts=[t0:timeout (target-timeout 25000ms (elapsed 25011ms))]。 - 这句话同时给了预算(25000ms)和实际(25011ms),还给了原因(timeout)和候选数(t0 表示第一个候选就挂了)。
- 得出归因:不是配置错、不是鉴权错,是压得太多导致超时。
如果它只返回"压缩失败",我得从头猜。好的错误信息应该包含预算、实际值、原因三件事,这条我后来写脚本都在照这个标准输出。
六、观测的三个常见误读
除了上面那些,还有三种我实际犯过的读法错误。
第一种:把 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 生命周期、权限变更)。