后台任务

适合把需要保持运行的命令交给后台，例如启动项目预览服务，同时整理不依赖服务结果的使用说明。还有独立工作可继续，才是使用后台任务的理由；并不是所有耗时命令都应该放到后台。

它是怎么工作的

助手调用 bg_run 后，命令在当前项目目录中启动，工具立即返回任务 ID。进程继续运行，助手可以接着完成另一件独立的工作。

输出会写入日志，运行状态进入任务中心。任务自然结束或执行失败时，会在对话中显示通知，但不会自动唤醒助手继续处理；需要分析结果时，再明确告诉助手。

从启动到停止

先安装插件 @jetcrab/pi-desk-bg-run，按提示加载。已有会话需要更新工具时，在空闲后执行“更多 → 重载 Pi 配置”。

告诉助手需要后台运行的命令，以及接下来可以独立做什么。下面以“预览服务 + 整理说明”为示意，界面、命令与日志均为示例，不会启动真实进程。

1. 找到任务摘要：任务启动后，当前会话输入框上方会显示执行中的任务。点击摘要，打开“任务中心”。
2. 查看详情与日志：在列表中选择任务，核对名称、状态和输出。日志可以帮助判断服务是否就绪，启动成功不代表你的业务检查已经通过。
3. 用完后停止：在详情中点击“打断”，再点“确认打断”。状态变为“已停止”，对应命令及其完整进程树会被终止。

也可以让助手用 bg_status 查询当前会话的任务，用 bg_kill 按任务 ID 停止。停止后执行中摘要会消失；需要回看记录时，从会话“更多 → 任务中心”进入。

每次启动时指定参数

后台任务没有独立设置页。任务名、命令和超时时间都由助手在每次调用 bg_run 时传入。

图中 pnpm run preview 只作示意，实际命令以你的项目为准。超时以秒计，必须是正整数；不填时，持续运行到进程结束或被停止，不表示它能永久驻留。

使用边界

• 需要等待结果，就同步执行。 测试、构建或验收结果决定下一步时，让助手等待命令完成；反复查状态不算独立工作。
• 不是持久守护服务。 关闭会话或进行分支导航会停止任务；用完后主动停止，不依赖它长期托管服务。
• 日志有上限。 每个任务最多保留 20MB 输出，超出后会终止，超时也会终止；失败时查看状态和日志原因。
• Windows 使用 Bash。 命令由 bash.exe 执行，需要可用的 Bash 环境，不要照搬 PowerShell 语法。