pi-subagents前台与后台切换指南:一个ctrl+b秒懂即时移交技巧
pi-subagents前台与后台切换指南:一个ctrl+b秒懂即时移交技巧
pi-subagents 是一款为 pi 带来 Claude Code 风格子代理(Sub-Agents)与任务编排能力的扩展。它最容易被忽略、却最实用的技巧之一,就是前台与后台一键切换:当某个前台 Agent 调用卡住了你的对话时,只需按下 ctrl+b,即可把这个正在运行的任务即时移交给后台继续执行——会话、进行到一半的步骤、工作现场全部原样保留。本文用最短路径带你秒懂这个移交技巧。
为什么需要前台/后台切换?
在 pi-subagents 中,子代理默认以后台模式运行:调用立刻返回一个 agent ID,完成后会收到带结果预览的通知。但当你显式传入 run_in_background: false 时,这个 Agent 调用会阻塞当前对话,直到任务跑完——适合短平快的任务,一旦任务耗时超出预期,你就被"钉"在了原地。
ctrl+b 正是为这种场景设计的逃生门:不需要杀任务、不需要重跑,把正在前台阻塞的运行原封不动地移交后台,主会话立刻恢复自由。
ctrl+b 一键移交:三步上手
🚀 场景:模型发起了一个前台 Agent 调用(例如一次耗时的代码探索),对话正在阻塞等待。
- 看到提示:前台调用运行约 2 秒后,该工具行会显示
(ctrl+b to run in background)提示,说明此刻可以移交。 - 按下
ctrl+b:在提示编辑器有焦点时按下,所有正在运行的前台Agent调用会一次性全部移交后台,顶部弹出Sent N agents to the background.通知。 - 等待通知:被阻塞的调用立即返回 agent ID(与
run_in_background: true的返回完全一致),任务跑完后像普通后台代理一样送达完成通知,需要完整输出时再用get_subagent_result获取。
关键源码见 src/index.ts,这里注册了 ctrl+b 的按键监听与移交逻辑;行为不变量的测试在 test/foreground-detach.test.ts。
只想移交其中一个?用会话查看器里的 b 键
ctrl+b 是"批量移交",如果你只想把某一个运行中的前台代理送进后台,用单点移交:
- 打开 FleetView(编辑器下方的代理列表,空提示符下按
↓或←进入)或/agents → Running agents - 选中目标代理打开会话查看器,直接按
b键,即可只把这一个运行移交后台,其余前台调用不受影响
单点移交的入口注册逻辑在 src/index.ts,FleetView 的按键处理在 src/ui/fleet-list.ts。
移交后到底发生了什么?
这是 ctrl+b 最令人安心的地方:被移交的运行什么都没变,变的只是"谁来负责接住结果"。
| 维度 | 移交前(前台阻塞) | 移交后(后台运行) |
|---|---|---|
| 会话 / 进行中的回合 | 运行中 | 完全相同,继续跑 |
| transcript 与 worktree | 照常写入 | 保持原样 |
| 父会话 | 被阻塞 | 立即解除阻塞,工具调用返回 agent ID |
| 结果送达 | 内联返回完整输出 | 常规后台完成通知(带结果预览) |
| 并发槽位 | 占用前台池 | 释放前台槽位,改占一个后台槽位 |
| 中途转向 / 停止 | Esc 可打断 | Esc 不再触达,需从 /agents 按 x(再按一次确认) |
两个细节值得注意:
- 后台池满也不排队:如果后台并发池(
maxConcurrent,默认 10)已满,被移交的代理会超出容量继续运行,而不是被挂起——它已经在跑了,没必要罚站。 - 同一消息的其他工具调用不受影响:pi 会把一条助手消息里的多个工具调用作为一个批次执行,所以即使
Agent已移交,同批其他调用跑完后模型才会拿到下一回合。
并发槽位的转移逻辑可在 src/agent-manager.ts 中查阅。
常见疑问与限制 ⚠️
Q:ctrl+b 按了没反应?
这个键只在"有前台 Agent 正在运行 且 提示编辑器持有焦点"时才被占用,其余时间 ctrl+b 仍是 pi 原生的"光标左移"。如果你开着一个对话框或处于会话查看器的转向输入框,ctrl+b 也不会被拦截。
Q:能移回前台吗?
不能。移交是单向的,没有回到前台的路径。想停止它,请用 /agents → Running agents 中按 x(连按两次确认)。被停止的代理会返回标注为"不完整"的部分输出。
Q:哪些运行不支持移交? 以下四种不提供移交入口:
- 还在排队等并发槽位、尚未真正开始的前台调用
- 前台
resume(恢复旧会话,不走新建路径) - Workflow 子代理与嵌套子代理(它们本就不进主会话的并发池)
另外,没有自动超时——前台阻塞不会随时间自动降级为后台,需要你自己按下 ctrl+b(或 b)。
技巧速查表 📋
| 操作 | 效果 |
|---|---|
提示编辑器内按 ctrl+b |
批量移交所有运行中的前台 Agent |
会话查看器内按 b |
只移交当前打开的这个前台运行 |
| 移交后按 Esc | 无效——已脱离父会话中断链 |
/agents → Running agents 按 x x |
停止已移交后台的代理 |
get_subagent_result |
获取移交代理的完整结果文本 |
掌握 ctrl+b 之后,前台代理不再是"要么等完、要么杀掉"的二选一,而是一个可以随时放手的弹性任务——这正是 pi-subagents 对齐 Claude Code 交互体验的核心细节之一。
