命令队列（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（亦称steer+backlog）：立即引导并为跟进轮次保留消息。interrupt（遗留）：中止该会话的活跃运行，再运行最新消息。queue（遗留别名）：同steer。
Steer-backlog 意味着引导运行后你可得到跟进响应，故流式传输表面可能显得重复。若希望每条入站消息一个响应，推荐 collect/steer。发送 /queue collect 作为独立命令（按会话）或设置 messages.queue.byChannel.discord: "collect"。未在配置中设置时默认：所有表面 → collect。全局或按频道配置经 messages.queue。
队列选项
选项适用于 followup、collect、steer-backlog（以及 steer 回退到 followup 时）：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 清除会话覆盖。
作用域与保证
适用于使用网关回复管道的所有入站频道的自动回复代理运行。默认通道（main）为入站 + main 心跳的进程级；设置 agents.defaults.maxConcurrent 允许多会话并行。额外通道可能存在（如 cron、subagent），使后台任务可并行运行而不阻塞入站回复。按会话通道保证同一时刻仅一次代理运行触及给定会话。无外部依赖或后台工作线程；纯 TypeScript + promises。
故障排查
若命令似乎卡住，启用详细日志并查找”queued for …ms”行以确认队列正在排空。若需队列深度，启用详细日志并观察队列计时行。