@spinejit/pi-background-job0.1.0

pi-background-job

English | 简体中文

Pi 的后台任务与输出监视插件，设计参考 Claude Code 的后台任务和 Monitor。agent 启动构建、服务或日志监视后可以继续处理其他工作，有事件发生时会自动收到通知，无需轮询，也无需编写 sleep 循环。

background_job(action="start", command="npm run build", name="build")
background_job(action="status")
background_job(action="stop", name="build")
monitor(command="tail -f app.log | grep --line-buffered -E 'ready|ERROR'", description="errors in app.log")

为什么这样设计

• 事件驱动，无需轮询。 任务退出或 monitor 收到一批新输出行时，都会作为一条消息发回启动它的会话。若会话处于空闲状态，消息会直接触发新一轮执行；若会话正忙，消息会在当前工具批次执行完毕、下一次调用模型之前送达。agent 不必消耗额外轮次去轮询任务状态。
• 生命周期归属 Pi 进程。 任务的生命周期与启动它的 Pi 进程一致，退出 Pi 时会自动停止本进程的所有任务。无需安装或清理常驻守护进程；需要比 Pi 存活更久的任务应交给 systemd 或 tmux。
• 同一套机制，两个工具。 background_job 和 monitor 共用同一套底层任务机制，区别仅在于监听目标：前者监听进程退出，后者监听 stdout 新增行。
• 普通文件存储，单一写者。 每个 Pi 进程将任务记录和日志保存在各自的目录中，仅由本进程写入，因此不需要文件锁。

特性

• 支持按名字启动、列出和停止任务；/jobs 可列出任务，选中运行中的任务即可将其停止。
• 退出消息包含退出码或信号、运行时长、日志路径以及最后 20 行输出。
• monitor 将 200 ms 内的 stdout 输出行合并为一批发送；达到超时上限（默认 5 分钟，最长 30 分钟）或输出过于密集（每分钟超过 30 条消息）时自动停止。
• stop 对整个进程组发送信号：先发 SIGTERM，2 秒后仍有残留进程再发 SIGKILL。
• footer 实时显示当前会话正在运行的后台任务和 monitor 数量。
• 在 codemode 的 on 和 only 模式下，脚本内均可直接调用。
• 自动清理超过 30 天的历史记录和日志，仍在运行的任务除外。

安装

pi install npm:@spinejit/pi-background-job

不安装，仅在当前会话中试用：

pi -e npm:@spinejit/pi-background-job

当前回合必须先拿到结果才能继续的命令（例如决定下一步怎么改的测试），请使用前台 bash。配合 pi-timeout-policy 使用，可避免前台命令无限挂住。

要点

完整参考（消息格式、codemode 细节、生命周期）见 English README。核心规则如下：

• 消息只投递给启动该任务的会话；若该会话不在前台则不投递，但任务结束信息仍会照常写入任务记录。
• 任务记录保存在 <Pi agent dir>/state/background-job/<bootId>/<pid>-<start time>/（通常位于 ~/.pi/agent/state/ 下），每个名字对应一个 JSON 记录，每次运行对应一个日志文件。
• 任务名字在单个 Pi 进程内唯一。status 会列出所有 Pi 进程的任务；stop 不会停止其他存活 Pi 进程的任务，但可以停止孤儿任务（启动它的 Pi 进程已退出）。
• /reload 保留运行中的任务；/new、/resume 和 fork 保留后台任务，但会停止原会话的 monitor；退出 Pi（包括 SIGTERM/SIGHUP）会终止本进程的所有任务。
• 在 print 和 JSON 模式下，模型停止输出即结束运行，仅投递运行期间到达的消息，启动结果中会写明这一限制。
• 后台 shell 使用 Pi 的 shell 配置，继承环境变量，并将 Pi 管理的 <Pi agent dir>/bin 置于 PATH 最前面。插件不读取 shellCommandPrefix 设置，所需前缀请直接写进命令中。

限制

• 仅支持 Unix 系统（依赖进程组）。Windows 需另行编写基于进程树或 job object 的适配层。
• 按设计，任务不会比启动它的 Pi 进程存活更久。
• 已脱离原进程组的进程（例如通过 setsid 启动）不受 stop 控制。

兼容性

已在 Pi 1.3.0 和 1.4.0、Node 22.23 下测试通过。要求 Node >= 22.19。Pi 相关包均声明为 "*" peer dependencies。

开发

npm test              # 核心逻辑和事件层
npm run test:e2e      # 用脚本化模型驱动的真实 Pi 会话
npm run test:codemode # 真实 codemode，在 on/only 模式下成对比较直接调用和嵌套调用

端到端测试使用临时的 PI_CODING_AGENT_DIR，不会修改本机的用户 Pi 配置。共存测试还会加载本仓库旁边（或 PI_TIMEOUT_POLICY_DIR 指定）的 pi-timeout-policy checkout，没有时跳过。核心测试和端到端测试会按设计向自身启动的测试任务发送 SIGTERM 和 SIGKILL，并清理过期的测试记录。

@spinejit 的其他插件

• pi-btw-cached：在主会话自己的请求上发起 /btw 侧问。
• pi-timeout-policy：为 bash、grep、find 提供统一的超时策略。
• pi-compact-tree：Pi 终端界面的紧凑过程树视图。

许可证

Apache-2.0，见 LICENSE。