job-babysitter

Job Babysitter

用途

不再手动轮询长时间运行的后台任务。无需在猜测任务何时完成的同时，执行几十到上百次 ls -lh / ps 检查，只需启动一个后台监视器，通过平台期启发式检测任务的最终状态，然后给出判定—— 已完成、需要关注或已阻塞——以及准确的下一条命令。

后台任务的夜班护士：定时检查运行状态，只有确实出现问题时才会升级处理。

适用场景

当任务运行时间较长、手动看护会分散注意力时使用：

• 媒体编码／转码（ffmpeg、视频转录、音频提取）
• 嵌入或向量数据库构建（qmd embed、索引构建）
• 在后台运行的批处理 Agent / LLM 工作流
• 容易挂起的浏览器／抓取守护进程（real-browser、agent-browser）

不要用于几秒内就能完成的任务，或一次 Bash 调用就能返回结果的任务。

核心原则：保持轻量，依靠执行框架

此技能负责协调 Claude Code 自带的原语——不要重新实现它们：

• 使用 run_in_background: true 启动监视器。监视器退出后，执行框架会自动重新调用 Agent——无需手动轮询循环。
• 监视器（scripts/watch_job.py）负责确定性部分：采用退避策略进行轮询、检测平台期、区分已完成和卡住状态，并输出判定 JSON。
• 此技能的价值在于按任务类型设置启发式规则、安全恢复操作手册和通知路由——详见 references/playbook.md。

工作流

1. 确定任务信号

按可靠性顺序确定可以监视哪些信号：

• PID — 进程 ID（最可靠的完成信号）。从任务启动命令、pgrep 或 ps 中获取。
• 输出文件 — 随任务进度增长的文件（例如 ffmpeg 目标文件）。
• 日志文件 — 持续追加内容的日志（例如嵌入进度日志）。

阅读 references/playbook.md §“按任务类型划分的完成启发式规则”，为具体任务类型（ffmpeg、嵌入、批处理、浏览器）选择标志。

2. 在后台启动监视器

使用 run_in_background: true 运行。已知 PID 时，务必传入 --pid；添加文件／日志信号作为佐证。将判定写入一个已知路径。

scripts/watch_job.py \
  --label "lab05 stream encode" \
  --pid <PID> \
  --output-file /path/to/output.mp4 \
  --plateau-bytes 65536 --plateau-polls 5 --stuck-after 120 \
  --max-wait 7200 \
  --verdict-out /tmp/job-babysitter-<label>.json

监视器每次轮询时都会输出一行 JSON 心跳（可查看其末尾内容以跟踪实时进度），并在退出时将最终判定 JSON 写入 --verdict-out。

调整参数请参阅操作手册；建议默认值：--interval 10（逐步退避至 60）、--plateau-polls 4、--stuck-after 300、--max-wait 7200。

3. 监视器退出后，读取判定并进行处理

后台监视器完成后，执行框架会重新调用 Agent。读取判定 JSON。它包含 status ∈ {done, needs-attention, blocked}、reason、suggested_next、经过时间和最终大小。

• done → 验证输出确实有效（参见操作手册中相应任务类型的“完成检查”，例如媒体使用 ffprobe、嵌入检查数量是否匹配），然后继续原任务。
• needs-attention → 任务仍在运行，但已进入平台期（可能已卡住）。遵循恢复操作手册：首先进行只读诊断。未经用户允许，绝不要终止任务或执行破坏性恢复操作（pkill、WAL checkpoint、VACUUM）。
• blocked → 监视器在达到 --max-wait 后放弃等待。如实说明：“放弃等待”≠“失败”。可提出重新检查或延长等待上限。

4. 按选定渠道发送通知

默认在当前会话中恢复。如果用户选择了某个渠道（Telegram、语音／TTS、桌面通知），则按照 references/playbook.md §“通知路由”进行通知。务必包含状态表情符号、标签、经过时间和准确的下一条命令。

防护规则（不可妥协）

• 绝不要仅凭一次缓慢轮询就采取行动。 只有在出现平台期且经过的时间超过 --stuck-after 时，才能判定为“卡住”——监视器在返回需要关注状态前已经执行此检查。
• 执行任何破坏性恢复前都要先询问——pkill、kill、WAL 检查点、VACUUM、 守护进程重启。先进行只读诊断。
• 如实报告。 区分已完成、已“放弃等待”和已“卡死”。绝不要暗示监视器未观察到的成功。
• 采用退避方式轮询，而非紧密循环——监视器会处理此事；绝不要用手动快速轮询循环包装它。

资源

• scripts/watch_job.py — 后台监视器：平台期检测、卡住与完成的判定、 结论 JSON。仅使用标准库，Python 3.11+。
• references/playbook.md — 各任务类型的完成判定规则、安全恢复 表和通知路由。选择监视器标志或处理需要关注／受阻结论时加载。