​

指令佇列 (2026-01-16)

​

為什麼

• 自動回覆執行可能成本高昂（LLM 呼叫），且當多則入站訊息在短時間內抵達時，容易彼此衝突。
• 序列化可避免競逐共用資源（工作階段檔案、記錄、CLI stdin），並降低上游速率限制的風險。

​

How it works

• 具備通道（lane）感知的 FIFO 佇列，會以可設定的並行上限排空各通道（未設定的通道預設為 1；main 預設為 4，subagent 為 8）。
• runEmbeddedPiAgent 依 工作階段金鑰（通道 session:<key>）入佇列，以保證每個工作階段同時間只有一個有效執行。
• 接著，每個工作階段的執行會被排入 全域通道（預設為 main），因此整體並行度受 agents.defaults.maxConcurrent 限制。
• 啟用詳細記錄時，若排隊等待超過約 2 秒，佇列中的執行會在開始前送出簡短提示。
• 輸入中指示（typing indicators）仍會在入佇列時立即觸發（若頻道支援），因此在輪到我們之前，使用者體驗不會改變。

​

佇列模式（依頻道）

• steer：立即注入目前的執行（在下一個工具邊界之後取消尚未完成的工具呼叫）。若非串流，則回退為後續回合。 若未進行串流，則會回退為 followup。
• followup：在目前執行結束後，排入下一個代理程式回合。
• collect：將所有佇列中的訊息合併為單一個 followup 回合（預設）。 如果訊息目標為不同的頻道／執行緒，則會各自排空，以保留路由。
• steer-backlog（亦稱 steer+backlog）：現在引導 且 保留訊息以供後續回合使用。
• interrupt（舊版）：中止該工作階段的作用中執行，然後執行最新的訊息。
• queue（舊版別名）：同 steer。

• 所有介面 → collect

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

​

佇列選項

• debounceMs：在啟動後續回合前等待安靜期（避免「繼續、繼續」）。
• cap：每個工作階段可佇列的最大訊息數。
• drop：溢位策略（old、new、summarize）。

​

每個工作階段的覆寫設定

• 將 /queue <mode> 作為獨立指令送出，以儲存目前工作階段的模式。
• 選項可組合：/queue collect debounce:2s cap:25 drop:summarize
• /queue default 或 /queue reset 會清除工作階段覆寫。

​

範圍與保證

• 適用於所有使用 Gateway 回覆管線的入站頻道之自動回覆代理程式執行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。
• 預設通道（main）在整個程序中用於傳入事件 + 主要心跳；設定 agents.defaults.maxConcurrent 以允許多個工作階段並行。
• 可能存在其他通道（例如 cron、subagent），使背景工作能並行執行而不阻塞入站回覆。
• 每個工作階段的通道可確保同一時間只有一個代理執行會接觸到該工作階段。
• 無外部相依或背景工作執行緒；純 TypeScript + promises。

​

疑難排解

• 若指令看似卡住，請啟用詳細記錄，並查看是否有「queued for …ms」的行，以確認佇列正在排空。
• 如果你需要查看佇列深度，請啟用詳細日誌並留意佇列計時相關的行。