命令队列 (2026-01-16)

我们通过一个微型进程内队列串行化入站自动回复运行(所有通道),以防止多个代理运行发生冲突,同时仍允许跨会话的安全并行性。

原因

自动回复运行可能开销较大(LLM调用),当多个入站消息接近同时到达时可能会发生冲突。
串行化避免了共享资源(会话文件、日志、CLI标准输入)的竞争,并降低了上游速率限制的可能性。

工作原理

一个支持通道的FIFO队列以可配置的并发上限排空每个通道(未配置通道默认为1;main默认为4,subagent默认为8)。
runEmbeddedPiAgent 按会话键(通道 session:<key>)入队,以保证每个会话只有一个活跃运行。
然后每个会话运行被排入全局通道(默认为 main),因此整体并行性由 agents.defaults.maxConcurrent 限制。
启用详细日志时,如果排队运行在启动前等待超过约2秒,将发出简短通知。
输入指示器仍会在入队时立即触发(当通道支持时),因此用户体验在我们等待轮次时不会改变。

队列模式(按通道)

入站消息可以引导当前运行、等待后续轮次或同时执行两者:

steer:立即注入到当前运行中(在下一个工具边界后取消待处理的工具调用)。如果未流式传输,则回退到后续处理。
followup:在当前运行结束后排队等待下一个代理轮次。
collect:将所有排队的消息合并为单个后续轮次(默认)。如果消息针对不同的通道/线程,它们将单独排空以保留路由。
steer-backlog(又名 steer+backlog):立即引导并保留消息以供后续轮次使用。
interrupt(遗留):中止该会话的活跃运行,然后运行最新消息。
queue(遗留别名):与 steer 相同。

Steer-backlog意味着在引导运行后可以获得后续响应,因此流式传输表面可能看起来像重复。如果希望每个入站消息只有一个响应, 请优先使用 collect/steer。发送 /queue collect 作为独立命令(按会话)或设置 messages.queue.byChannel.discord: "collect"。

默认值(配置中未设置时):

所有表面 → collect

通过 messages.queue 全局或按通道配置:

json5

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

队列选项

选项适用于 followup、collect 和 steer-backlog(以及当 steer 回退到后续处理时):

debounceMs:在启动后续轮次之前等待安静(防止"继续,继续")。
cap:每个会话的最大排队消息数。
drop:溢出策略(old、new、summarize)。

Summarize保留一个简短的丢弃消息项目符号列表,并将其作为合成后续提示注入。默认值:debounceMs: 1000、cap: 20、drop: summarize。

按会话覆盖

发送 /queue <mode> 作为独立命令以存储当前会话的模式。
选项可以组合:/queue collect debounce:2s cap:25 drop:summarize
/queue default 或 /queue reset 清除会话覆盖。

范围和保证

适用于使用网关回复管道的所有入站通道的自动回复代理运行(WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat等)。
默认通道(main)是进程范围的,用于入站 + main心跳;设置 agents.defaults.maxConcurrent 以允许多个会话并行。
可能存在其他通道(例如 cron、subagent),因此后台作业可以并行运行而不会阻塞入站回复。
按会话通道保证在给定时间只有一个代理运行接触给定会话。
无外部依赖或后台工作线程;纯TypeScript + promises。

故障排除

如果命令似乎卡住,启用详细日志并查找"queued for …ms"行以确认队列正在排空。
如果需要队列深度,启用详细日志并关注队列计时行。

命令队列 (2026-01-16) ​

原因 ​

工作原理 ​

队列模式(按通道) ​

队列选项 ​

按会话覆盖 ​

范围和保证 ​

故障排除 ​