← Pi Agents

引导、排队与改变方向

当你在 Pi 工作时键入消息会发生什么——引导消息在当前轮次之后进入,后续跟进消息等待一次运行结束,而 Escape 会把队列还给你。

智能体正在迁移你的 schema,已经进行了十一次工具调用。你看得出来,大概再来三步它就要错了,而现在停下来,会浪费它已经了解到的关于数据库层的一切。

你键入。你按下 Enter。然后那条消息等着——因为 Pi 不打算在一次工具调用中途打断,而它把你的指令交付出去的那一刻,是循环里一个特定的、有文档记载的点。

两条队列,不是一条

how-pi-works.md 用一句话把它说清:“引导消息在当前助手轮次之后进入。后续跟进消息在智能体完成其待处理工作之后进入。中止会停止当前一次运行,并把排队的消息还给编辑器。”

这就是全部的区别。引导改变当前的任务。后续跟进在它之后添加工作。两者都会排队;它们在不同的时刻被交付。

在终端里,usage.md 把它们映射到按键上:

你想做什么 操作
调整当前的任务 键入一条消息并按 Enter
在当前任务之后添加工作 键入一条消息并按 Alt+Enter
把排队的消息还给编辑器 按 Alt+Up
停止当前的任务 按 Escape

“用 Enter 发送的消息会等到当前响应及其工具调用完成,然后引导下一个响应。用 Alt+Enter 发送的后续跟进消息会等到 Pi 完成当前的任务。”

这个按键绑定名为 app.message.followUp,默认 alt+enter,在 Windows 和 WSL 上是 ctrl+q——因为"Windows Terminal 默认把 Alt+Enter 绑定为全屏。“运行 /hotkeys,看看你的会话实际有什么。

一轮是什么

“引导消息在当前助手轮次之后进入。“一轮的定义在 json.md:“一轮就是一条助手响应,加上该响应产生的任何工具调用与工具结果。”

所以交付点是精确的:在助手响应执行完它所有的工具调用之后,在下一次 LLM 调用之前。不是在一个工具之后。是在模型要求的整批之后。

这就是为什么引导有时感觉晚、有时又感觉及时。如果模型在一次响应里要求了三次工具调用,你的引导消息就在三次全部之后落地。如果它只要求一次,就在那一次之后落地。

关于压缩的参考资料确认了它位于轮次调度器内部,而不是在它旁边:当阈值被越过时,Pi 在 prepareNextTurn 期间进行压缩,“然后执行既有的追赶式引导轮询,位置在 turn_start 之前。“引导消息在轮次流水线中一个定义好的点上被轮询。

把它展开,就是一条在飞行中的引导消息:

    sequenceDiagram
    participant U as 你
    participant P as Pi
    participant M as 模型
    U->>P: steer,在第 1 轮运行时键入
    Note over P: 已排队,模型还读不到它
    P->>M: 第 1 轮的请求
    M-->>P: 一条响应,三次工具调用
    P->>P: 把三次全部运行
    Note over P: turn_end
    P->>M: 下一个请求,带着那条引导消息
    M-->>P: 第 2 轮回答这个纠正
    P-->>U: agent_end,然后是 agent_settled
  

在同一时刻发送的一条后续跟进消息会跳过上面每一条箭头:它"只有在智能体没有更多工具调用或引导消息时才会被交付。“这就是"更晚"的全部含义——它由什么仍未完成来定义,而不是由一个时钟。

一次到达多少条消息

两个设置,都默认一次一条:

设置 类型 默认值 说明
steeringMode "all" | "one-at-a-time" "one-at-a-time" 排队的引导消息如何被交付。
followUpMode "all" | "one-at-a-time" "one-at-a-time" 排队的后续跟进消息如何被交付。

来自 rpc-commands.md:

  • "all":在当前助手轮次执行完它的工具调用之后,交付所有引导消息。
  • "one-at-a-time":每完成一个助手轮次,交付一条引导消息。这是默认值。

后续跟进消息也有同样两种模式,其中 "all" 交付"智能体完成时的所有后续跟进消息”,而 "one-at-a-time" 交付"智能体每完成一次,交付一条后续跟进消息。”

一次一条是更好的默认值,原因从设置名上看不出来。如果你排了队三条纠正,而三条同时到达,模型会把它们看成一条未加区分的指令。如果它们每轮到达一条,每一条都能得到一轮模型的注意力,并且可能被随后发生的事确认、满足或反驳。

从程序里

三条命令,而其中一条并不像它看起来那样。

{"type": "steer", "message": "Stop and do this instead"}

引导消息"在当前助手轮次执行完其工具调用之后、在下一次 LLM 调用之前"被交付。技能命令和提示词模板会被展开。扩展命令不被允许——文档说改用 prompt。

响应会告诉你发生了什么:

{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}

“data.disposition 的含义是:如果一个输入处理器消费了这次 steer,它就是 "handled";如果 Pi 把它排了队(包括在一个处理器转换它之后),它就是 "queued"。它并不保证这条消息一直保持排队状态。”

最后一句话对一个 UI 很重要。queued 并不承诺:在你收到响应的那一刻,这条消息仍在等待。

后续跟进消息是同样的形状:

{"type": "follow_up", "message": "After you're done, also do this"}

“只有在智能体没有更多工具调用或引导消息时才交付。“注意这隐含的顺序:引导消息先于后续跟进消息排空。如果你把两者都排了队,后续跟进消息会等着引导消息落地并被回答。

而 prompt 有第三种模式:

{"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"}

“如果智能体已经在流式输出,你必须指定 streamingBehavior 才能把消息排队。如果智能体正在流式输出而没有指定 streamingBehavior,该命令会返回一个错误。""followUp" 是另一个可接受的值。

它的 disposition 有三个状态而不是两个:"handled"、"queued" 或 "started"——"started" 表示 Pi 接受了它来开始一次运行。

观察队列

每一次队列变化都是一个事件,而且它带着整个当前队列:

{"type":"queue_update","steering":["Change direction"],"followUp":["Summarize when finished"]}

“两个字段都包含完整的当前队列。“完整,而不是增量——所以你不必拿你发出去的去核对到达的。你可以把它直接渲染进一条状态行。

同样的数据可以同步取得。get_state 返回:

{
  "type": "response",
  "command": "get_state",
  "success": true,
  "data": {
    "isStreaming": false,
    "steeringMode": "all",
    "followUpMode": "one-at-a-time",
    "pendingMessageCount": 0
  }
}

SDK 暴露的是同样的区分:"steer() 和 followUp() 直接暴露那些行为,如果输入被排了队(包括在一个扩展转换它之后)就返回 "queued",如果一个扩展消费了它就返回 "handled"。”

中止而不丢掉你的文本

Escape 停止一次运行。但是,两条排队的消息会怎样?

“中止会停止当前一次运行,并把排队的消息还给编辑器。”

rpc-commands.md 描述了该行为的客户端实现,而它不只是 abort:“移除排队的引导消息和后续跟进消息,并返回它们的文本”——即 clear_queue。“要实现交互式 Esc 行为,请在 abort 之前发送 clear_queue,然后把返回的文本恢复到客户端编辑器里。当排队的消息仍留在会话中时,abort 会继续它们。”

    sequenceDiagram
    participant U as 你
    participant P as Pi
    Note over P: 轮次正在运行,两条消息已排队
    U->>P: clear_queue
    P-->>U: steering 和 followUp 文本
    U->>P: abort
    Note over P: 运行停止,没有剩余待处理项
    U->>P: 文本被恢复到编辑器里
  

顺序就是全部要点。clear_queue 先把文本取出来;abort 然后在没有任何待处理项的情况下停止这次运行。如果先 abort,而队列仍在会话里存活,你就得以某种别的方式找回文本。

扩展命令立即运行

有一处不对称会绊住正在写 RPC 客户端的人。来自 rpc-commands.md:“如果该消息是一条扩展命令(例如 /mycommand),它即使在流式输出期间也会立即执行。扩展命令通过 pi.sendMessage() 管理它们自己的 LLM 交互。”

所以 /guard status 会在智能体运行到一半时运行,而一条包含 /guard 的引导消息会被拒绝。原因是结构性的:一条扩展命令是一个 UI 动作,而一条引导消息是模型输入。

工作何时真正结束

这是你将要写的每一个客户端里的陷阱。

错误:"agent_end 意味着一次运行结束了。”

正确:agent_end 只结束一次低层的智能体运行,而"自动重试、溢出恢复、压缩重试、引导或后续跟进工作仍可能继续。"extensions.md 把 turn_end 和 agent_before_settle 称为"可行动的边界”,它们的处理器可以串起条目并返回 continue: true 以再发一次模型请求。agent_settled 不声明任何结果类型——它只作通知——而它有文档记载的含义是"Pi 不会通过重试、压缩恢复或排队的消息自动继续。”

rpc.md 对协议作者说了同样的话:“当客户端需要知道 Pi 不会自动继续时,等待 agent_settled。”

如果你在 agent_end 上打印最终答案,接着一条引导消息到达,你打印出的就是不完整的东西。如果你在 agent_end 上宣告成功,接着一次重试跟随,你就宣告了两次成功。

选择键入什么

两个问题。你想说的是对眼下正在发生之事的纠正,还是留给以后的条目?纠正用 Enter——它落在运行内部,并引导下一个响应。条目用 Alt+Enter,并等到这次运行无事可做。

如果两者都成立——现在停下来并且还有后续工作——发送引导消息,让它落地,然后把后续跟进消息排队。调度器先把引导排空。

在智能体工作时键入,感觉像一次打断,而其实不是。如果你需要当前这次运行现在就停,那是 Escape,不是一条消息。

这是从外面看的那次运行循环。至于它携带什么,那是下一个问题,因为一条把正确的消息送到错误的点的队列,仍然是一条丢失的指令——而它交付的形状,并不是你假定的那些形状。

运行了什么

examples/ch25-queue/ 在一个刻意缓慢的工具运行时,把消息排进一个真实会话,并检查下一个请求的转录记录:

  • 引导消息落在该轮次的工具调用之后、下一个请求之前:该请求包含 user:start、助手消息、工具结果,然后是 user:change direction;
  • 一条后续跟进消息在智能体仍有工作时不会被交付,而在它做完之后被交付;
  • 引导消息先于后续跟进消息排空,即使后续跟进消息先排队也一样;
  • queue_update 每次都带着完整的队列:第二次更新仍列出了第一条消息,而最后一次更新是空的;
  • one-at-a-time(默认)在下一个请求里交付了一条引导消息,而 all 交付了两条;
  • clearQueue() 返回了 { steering: ["S1"], followUp: ["F1"] },即一个界面会恢复到它的编辑器里的那段文本;
  • 一条扩展命令在智能体流式输出时运行了,而一条包含这种命令的引导消息被拒绝;
  • 在流式输出期间发出的一次 prompt,如果没有给出行为,是一个错误,而不是一次猜测。

全部与本章相符。