跳到主要内容

命令队列 (2026-01-16)

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

为什么需要​

  • 自动回复运行可能开销很大（LLM 调用），并且当多个入站消息紧密到达时可能会发生冲突。
  • 串行化避免了对共享资源（会话文件、日志、CLI 标准输入）的竞争，并降低了触发上游速率限制的可能性。

工作原理​

  • 一个感知车道（lane-aware）的 FIFO 队列，每个车道都有可配置的并发上限（未配置的车道默认为 1；主车道默认为 4，子 Agent 车道默认为 8）。
  • runEmbeddedPiAgent 按 会话密钥 入队（车道为 session:<key>），以确保每个会话只有一个活动的运行。
  • 然后，每个会话运行都被排入一个 全局车道（默认为 main），因此整体并行度受 agents.defaults.maxConcurrent 限制。
  • 当启用详细日志（verbose logging）时，如果排队的运行在开始前等待了超过约 2 秒，会发出简短的通知。
  • 输入指示器在入队时仍会立即触发（当渠道支持时），因此在等待轮到我们时，用户体验保持不变。

队列模式（按渠道）​

入站消息可以引导当前的运行、等待后续轮次，或者两者兼而有之：

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

Steer-backlog 意味着您可能会在引导运行后获得后续响应，因此流式传输界面可能看起来像是有重复。如果您希望每条入站消息对应一个响应，请首选 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（以及回退到后续轮次时的 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 清除会话覆盖。

范围和保证​

  • 适用于所有使用 Gateway 回复流水线的入站渠道的自动回复 Agent 运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、网页聊天等）。
  • 默认车道（main）是进程范围的，用于入站 + 主心跳；设置 agents.defaults.maxConcurrent 以允许并行运行多个会话。
  • 可能存在其他车道（例如 cron, subagent），因此后台作业可以并行运行而不会阻塞入站回复。
  • 按会话车道确保每次只有一个 Agent 运行触及给定的会话。
  • 无外部依赖或后台工作线程；纯 TypeScript + promises。

故障排除​

  • 如果命令似乎卡住了，请启用详细日志并查找 “queued for …ms” 行，以确认队列正在排空。
  • 如果您需要查看队列深度，请启用详细日志并观察队列计时行。