3.5 KiB
Agent Note: TUI 状态行标示排队中的 steering 消息
Status: implemented
English | 中文
Problem
轮次运行期间，编辑器提交会调用 agent.steer()，在运行中的轮次后面加入 steering（中途引导）队列（前门 Agent Note）。运行时的状态行只以 Enter sends steering, Esc cancels 提示收尾，因此按下 Enter 后没有任何反馈表明消息已入队、也看不出有多少条正在等待送达模型。连续 steering 多次的用户无法把队列和被吞掉的按键区分开。
Decision
agent（智能体）的收件箱（inbox）才是权威的 steering 队列，但 TUI 无法观测它，因此徽标是根据 TUI 成功提交的 steering 和 steering/message 事件重建出的实时计数，而非对队列本身的投影。
- 运行时的状态行经
formatTurnStatus组装：queued > 0时在Enter sends steering, Esc cancels提示前插入${queued} queued ·徽标，为零时是纯提示文本；其前的阶段标签与耗时归详细状态行所有。 createTuiChat记录每一次在running状态下成功的agent.steer()提交；agent loop（智能体循环）每排空一条并发出steering/message会话事件时，就按来源移除匹配项；agent 离开running时则重置整个列表。- 计数通过
setMessage刷新到实时的Loader上；空闲时刷新是空操作，因为 loader 只在运行中的轮次期间存在。 - 重置放在
agent/status状态切换里，而非setStatus中，因为setStatus在轮次中途的颜色方案变化时也会运行，绝不能清掉一个实时计数。
Alternatives considered
仅从会话日志推导计数（入队数减去排空数，回放时重算）。否决：取消会清空 inbox 而不记录排空，因此日志无法区分一条消息是被排空还是被丢弃；「离开运行态即重置」这个锚点更简单，且每轮自我校正。
在 setStatus 内重置。 否决：setStatus 会在轮次中途的 applyColorScheme 时重新运行，会错误地把实时计数清零；状态切换才是轮次真正结束的唯一位置。
统计每一次公开的 inbox 入队。 否决：AgentMessage 刻意省略驱动器路由状态，因此观察方无法区分排队轮次与 steering。TUI 转而自行维护徽标所代表的那些提交。
把措辞或某个阈值做成配置。 否决：「插件里不许硬编码可调参数」规则针对的是随部署变化的行为，不是品牌文案；welcome/提示字符串本就是固定的展示文案。
Consequences
- 徽标是尽力而为的实时 UI 状态，不写入日志：它由事件重建、每轮重置、从不持久化，因此恢复（resume）出的运行中轮次徽标从零开始。
- 队列中途取消会经由「离开运行态即重置」干净地清掉徽标，排空到零以下则是空操作——两者都不会残留一个陈旧计数。
- 通过此 TUI 以外的入口提交的 steering 不会出现在徽标中；该计数反馈的是此编辑器的提交，而不是 agent 的完整 inbox。
packages/ui/tui/src/index.ts保持 100% 的单文件覆盖率。
Testing
packages/ui/tui/tests/tui.spec.ts 通过真实的 createTuiChat 驱动运行时状态帧：为零时显示纯提示，编辑器提交后递增到 2 queued，每条消息排空时递减，忽略无关的排空，并在轮次结束时重置。