命令队列 (2026-01-16)

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

为什么

• 自动回复运行可能很昂贵（LLM 调用），当多个入站消息同时到达时可能会发生冲突。
• 序列化避免了争夺共享资源（会话文件、日志、CLI stdin），并减少了上游速率限制的可能性。

工作原理

• 通道感知的 FIFO 队列以可配置的并发上限（默认未配置通道为 1；main 默认为 4，subagent 为 8）排出每个通道。
• runEmbeddedPiAgent 按会话键入队（通道 session:<key>），以保证每个会话只有一个活动运行。
• 然后每个会话运行被排队到一个全局通道（默认为 main），以便整体并行度受 agents.defaults.maxConcurrent 限制。
• 启用详细日志时，排队的运行如果等待超过约 2 秒才启动，会发出简短通知。
• 打字指示器仍会在入队时立即触发（当通道支持时），因此在我们等待轮到自己时用户体验不变。

队列模式（按通道）

入站消息可以引导当前运行、等待后续回复，或两者兼做：

• steer：立即注入到当前运行中（在下一次工具边界后取消待处理的工具调用）。如果不流式传输，回退到 followup。
• followup：为当前运行结束后的下一个代理轮次入队。
• collect：将所有排队的消息合并为单个后续回复（如果消息针对不同的通道/线程，它们会单独排出以保留路由）。
• steer-backlog（ aka steer+backlog）：立即 steering 并且保留消息以供后续回复。
• interrupt（旧版）：中止该会话的活动运行，然后运行最新消息。
• queue（旧版别名）：与 steer 相同。

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

默认值（未在配置中设置时）：

• 所有界面 → collect

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

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

队列选项

选项适用于 followup、collect 和 steer-backlog（以及当回退到 followup 时的 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）对于入站 + 主要心跳是进程级的；设置 agents.defaults.maxConcurrent 以允许多个会话并行运行。
• 可能存在其他通道（例如 cron、subagent），以便后台作业可以并行运行而不会阻塞入站回复。
• 每会话通道保证一次只有一个代理运行触及给定会话。
• 无外部依赖或后台工作线程；纯 TypeScript + promises。

故障排除

• 如果命令似乎卡住了，启用详细日志并查找”排队等待 …ms”行以确认队列正在排出。
• 如果你需要队列深度，启用详细日志并观察队列计时行。