$ cat ~/map/pi-background-task.md

pi-background-task

六个基于 tmux 的后台任务工具：启动长命令、分页日志、输入、等待与停止。

extensions✓ 9月11日

事实速查

安装

pi install npm:pi-background-task

## 速览

一个 pi 扩展，提供六个基于 tmux 的后台任务工具：启动任务、按字节偏移分页读日志、发送终端输入、免模型轮询的等待与停止任务，输出全程持久捕获。

$六个代理工具——task_start、task_status、task_logs、task_send、task_wait、task_kill——覆盖后台任务全生命周期；task_start 立即返回一个任务 ID。
$每个任务都跑在真实的 tmux PTY 里，pipe-pane 捕获完整输出流；task_logs 按字节偏移分页读取（用返回的 nextOffset 续读），单次上限 64 KiB，吵闹的进程也刷不爆模型上下文。
$task_wait 在一次工具调用内等待任一或全部任务，任务完成时才唤醒 Pi——没有 LLM 轮询循环。
$task_send 可向 shell、REPL、调试器与 TUI 发送字面文本、回车或白名单控制键；/bg-attach 只打印确切的 tmux attach 命令，绝不会抢占 Pi 的终端。
$任务可见性跟随 Pi 的会话树：/resume、/fork、/new 与分支切换不会混入无关历史，重载、恢复、分叉与新会话切换也不会杀掉任务。
$要求 pi 0.85.1 或更新版本、Node.js 20+、PATH 上有 tmux，运行于 macOS 或 Linux；Windows 用户可在 WSL 里运行 Pi。

Q 我想亲自盯着一个后台任务，怎么做？

/bg-attach 会打印该任务 ID 对应的 tmux attach 命令——扩展绝不会自动替换 Pi 的终端。

Q 任务历史存在哪里？

任务沿 Pi 的会话树追踪。/bg-tasks 列出当前根到叶分支上的任务，/bg-tasks all 包含项目全部历史，/bg-clear 在确认后删除当前分支可见的已完成记录。