DSH plugin 后台任务输出环:绝对字节偏移、消费方视图与生命周期到底怎么读才不丢字节
后台任务的输出问题很少是“写得慢”,多半是把游标当成共享状态,或者把 output 事件当成了数据推送。 DSH plugin 的输出环用绝对字节偏移做坐标:写入整块落地、偏移一旦分配就不再移动、读取分消费与非消费两条路。先把这套坐标搞清,再谈读取。 DSH插件 读后台任务输出时,先分清消费式与非消费式两条读取路径。
ID、kind 与状态各自管什么
id 只做命名空间,访问控制靠拥有者授权。(来源)
JobId 是按 <kind>-<short-uuid> 生成的品牌化 id,kind 后是 UUID 的 16 位小写十六进制字符。官方特别说明:访问控制依赖拥有者授权,而非 id 的保密性。所以不要把 id 当成能力凭证,它只是标签。
JobKind 派生自可合并扩展的 map,注册表把每个 value 当作不透明的 id 命名空间。JobStatus 只有五个值:running、stopping、completed、killed、failed。
生产方特有的事实有两条落点:运行期间进 JobView.progress,结算后进 JobView.detail。这条分工决定你在列表里看到的“进度”和“终态原因”不是同一份数据,不要混用。
有主任务在会话里留两条日志记录
job/registered 与 job/settled 是持久事实,但可能不完整。(来源)
有所有者的 job 会在原始所有者 Session 中发布这两条记录,全局唯一的 jobId 同时配对它们并控制运行中的 job。SDK 通过 session.event 转发这些仅日志记录,不依赖输出读取。
时间戳的口径要看清:它描述注册表提交时刻,不是 CPU 时间,也不是精确的操作系统进程边界。缺少结算记录时,这个区间就是不完整的。
producerReported 表示生产方通过兑现 done 报告了终态;强制销毁或 promise 拒绝时为 false。它不独立确认资源已释放——这一点容易误读,别拿它当“清理已完成”的证据。
三条时序事实值得抄进排查清单:
job/settled可能出现在turn/end之后;- SDK 的 run 结果只覆盖自身观测窗口,需要更晚结算的消费方应保留 Session 订阅或读持久化历史;
- 应用销毁可能在最后一条结算写入存储前就停止事件路由或关闭写句柄,此时消费方不得虚构结束时间戳。
生产方拥有资源,运行时拥有身份与环
run() 是分界线:它之前可能失败,它之后不再做预检。(来源)
JobSpec 声明身份、拥有者会话、可选的拉取式输出源与启动器。运行时会在完成预检后携带 JobHandle 调用 run(),随后提交注册,不再执行可能失败的步骤。生产方拥有执行资源;运行时拥有身份、访问、生命周期状态与输出环。
outputLimitBytes 是一个容易被误读的字段:它是每条完整的面向模型完成通知或输出读取的 UTF-8 字节上限,包含控制器状态元数据。它与环保留量无关——它限制的是消费侧模型 surface,从不限制观察者。
owner 的语义很硬:它必须是当前注册在该 id 之下的活体 Agent,其销毁会取消并等待该 job。省略 owner 会创建一个无主 job,任何调用方都能看到,直到服务销毁。
JobHooks 只有两项:cancel(reason?) 必须同步、幂等、最终结算 done,抛出会传播;done 在生产方释放资源后 resolve,而不是只在工作完成时 resolve,且不得 reject——运行时会把拒绝转成 failed。如果拆卸取消抛错,运行时可能只强制失败注册表记录,而不声称工作已停止。
输出环:绝对偏移、整块落地、结算封环
偏移是这套机制的唯一坐标,读取方式决定你会不会重复或丢字节。(来源)
每个 job 拥有一个有界环。拉取源被泵入其中,JobHandle.append 的推送整块落地;模型通过注册表保管的游标(JobRegistry.read)消耗该环,任意数量观察者按绝对字节偏移读取它(JobRegistry.readAt),二者互不干扰。
JobChunk 有四个字段:at、text、可选 channel 与可选 gapBefore。at 是首字节绝对偏移,一旦分配永不移动;gapBefore 表示紧邻这块之前的字节已经丢失,可能来自生产方,也可能来自保留策略。
JobChannel 标记 stdout、stderr 与 log。注意 log 是只到达观察者、从不进入模型消耗式读取的生产方叙述——它适合放“正在做什么”,不适合放必须被模型看到的内容。
结算会封流,并把保留量裁剪到结算上限;环没有独立生命周期。JobOutputRead.next 永远是块边界,因为追加整块落地、裁剪只推进块起点。官方点出一条风险:提供方若返回部分块,消费方按块拼接时会静默重复文本。
拉取源保留的 spill 文件是 job 元数据(JobView.output.spillPaths,每次泵读取都会刷新),不是逐块元数据。所以即使环淘汰了字节、甚至缺口块本身也被淘汰,模型的丢失输出提示仍能点名那个文件。
消费方视图只有一份 JobView
模型工具、浏览器名册与观测流看的是同一个投影,不是三套字段。(来源)
JobView 是只读投影,每次调用都是新对象,绝不是活的注册表状态。owner 携带划定访问边界的会话 id;注册表会为生命周期清理解析其背后的活体 Agent,但从不把该对象交出去。
字段分工:progress 是生产方实时行,结算时清除;detail 是终态原因,合并了记录下来的 kill 原因;output 给出三个坐标——total 是下一块起始偏移(没写过时为 0),earliest 是最老的保留字节,恰好大于零时表示保留策略丢过头。
list、get、read、readAt、kill 与 wait 都接收调用方的 SessionId:省略调用方时仅可访问无主 job,传入会话时还可访问该会话拥有的 job。这条规则解释了两类“看不到任务”的现场:不是任务丢了,而是调用方身份没带对。
事件只播报,不推负载
output 事件只是一个信号,读完还要你自己去拉。(来源)
注册表通过一条带过滤的流宣布每次提交。生命周期事件(registered、progress、stopping、removed)携带其所宣布提交之后的投影;settled 额外标出 cause 与 awaited——后者表示这次结算是否释放了一个正在 wait 的调用方,完成播报方据此跳过已经交付的那一份。
output 事件只携带 id 与新的 total。观察者从自己的游标调度 readAt,注册表从不推送负载。这条设计让“读多少、从哪读”完全由消费方决定,也意味着你不能靠事件本身拼出内容。
验证:写超容量输出
验证要覆盖三处:偏移是否连续、淘汰后是否还能定位、结算后是否封环。(来源) 六步:
- 连续
append三段文本,记录每段at,断言后一段起点等于前一段长度的累加。 - 用
readAt(0)读一次,断言next等于当前total,且再读一次不重复返回同一块。 - 写入超过环容量的内容,断言
earliest大于零、readAt(0)的lossy为真。 - 检查
output.spillPaths,断言缺口仍能定位到完整流文件,即使缺口块本身已被淘汰。 - 用
read消费游标读到结算,断言result只在结算后第一次读取出现。 - 结算后再
append,断言写入被记录并丢弃,而不是抛错打断拆卸路径。
如果第 2 步出现重复,通常是消费方把 next 当成“已读字节数”自己又加了块长度,而不是直接沿用返回值。
后台任务与子进程句柄的衔接,可以对照子进程 spawn spec;前台与后台的边界见Shell resolve 拆分。
一句话收束: id 不是凭证,两条日志记录可能不完整,偏移永不移动、读取分消费与非消费,output 事件只给信号,结算即封环。
常见问题
不能,DSH plugin 的访问控制依赖拥有者授权,而不是 id 的保密性。DSH plugin 的 JobId 只是按 kind 加短 uuid 生成的品牌化标识,知道 id 不等于有权操作。
会,DSH plugin 明确说 job/settled 可能出现在 turn/end 之后。DSH plugin 里轮次完成不表示所有有主 job 都已停止,需要较晚结算的消费方应保留订阅或读持久化历史。
不会,DSH plugin 的 readAt 是非消费式读取。DSH plugin 让任意数量观察者按绝对字节偏移读取同一输出环,彼此不干扰;消耗式读取只属于注册表保管的模型游标。
不会,DSH plugin 的 output 事件只携带 id 与新的 total。DSH plugin 让观察者从自己的游标调度 readAt,注册表从不推送负载。
相关术语
- JobId
- JobId 是按 kind 加短 uuid 生成的品牌化标识,kind 后是 UUID 的 16 位小写十六进制字符。— packages/jobs/jobs/src/types.ts
- JobStatus
- JobStatus 是任务生命周期状态,取值为 running、stopping、completed、killed 与 failed。— packages/jobs/jobs/src/types.ts
- JobChunk
- JobChunk 是输出环中的一块,含绝对偏移 at、文本、可选 channel 与缺口标记 gapBefore。— packages/jobs/jobs/src/types.ts
- JobView
- JobView 是每个读者消费的唯一只读投影,模型工具、浏览器名册与观测流共用同一形状。— packages/jobs/jobs/src/types.ts
来源
- DeepSeek Harness 官方参考 - 后台任务运行时· deepseek-ai
- packages/jobs/jobs/src/types.ts· deepseek-ai