如何在Whaleness中给运行中的Agent插话:queue与steer功能完整指南
如何在Whaleness中给运行中的Agent插话:queue与steer功能完整指南
用 Whaleness(DeepSeek Harness Mobile)连接 Harness 后,Agent 往往要跑很久。这时候最常见的痛点是:Agent 正在执行任务,我突然想补充一句"顺便把日志也加上",或者想中途改个方向——难道只能干等它跑完?
不用等。Whaleness 通过 消息队列(queue) 和 插话(steer) 两种机制,让你在 Agent 运行中就能"插话":
- queue(排队):消息先进入 Host 的待执行队列,Agent 完成当前步骤后按序处理;
- steer(插话):把某条排队消息立即"提升",由 Host 择机交给 Agent 响应。
本文带你从零理解这套机制的工作原理、界面操作和背后的实现。
为什么需要给 Agent 插话
想象这个场景:你让 Agent 执行一个耗时命令,它正在等待。这时你发现需求漏了一条,于是输入"Reply EDITED."想改一下要求。如果 App 没有队列能力,这条消息要么被丢弃,要么得等当前轮次彻底结束。
Whaleness 的做法是:
- 生成中输入文字后,主按钮由"停止"变为"发送",没有输入时仍可停止当前生成;
- 普通发送会明确提交
mode=queue,消息被放进 Host 的会话队列; - 输入框上方会出现一个队列横条,实时展示所有
placement=queued的条目。
也就是说,"插话"不是 App 私自中断 Agent,而是把消息安全地递交给 Host,执行顺序仍由 Host 决定,App 不会取消或重启 Agent。
队列界面怎么用:排队、编辑、插话三步操作
队列横条位于输入框上方,左右边缘与输入框对齐,出现时从底部展开并淡入(iOS 开启"减弱动态效果"时仅淡入)。每条排队消息都提供三个操作:
| 操作 | 图标 | 行为 |
|---|---|---|
| 编辑(铅笔) | ✏️ | 先向 Host 提交 queue-update/action=remove,收到 accepted=true 后把原文字回填到主输入框,修改后重新发送(已有草稿不会被覆盖,编辑内容追加到其后) |
| 删除(垃圾桶) | 🗑️ | 提交 queue-update/action=remove,Host 确认后条目移除 |
| 立即插话(向上箭头) | ⬆️ | 提交 queue-update/action=steer,按原条目 ID 提升,保留 Host 中的原始消息和附件,不另造重复消息 |
几个值得注意的细节:
- 多条消息默认折叠,可展开查看,队列高度受限,不会挤占对话区;
- 带附件(非文本内容)的条目可以删除、插话,但不允许文本编辑——以免移除附件后无法完整重发,这与官方 Web 的编辑能力保持一致;
- 请求失败时不删除本地队列、不伪造成功;
- 当会话尚未运行、连接断开、网关缺少
queue-control能力、或已有队列操作正在等待确认时,相应按钮会被禁用。
网关能力检测在 iOS 端由 AppStore.swift 完成,只有 hello 帧中携带 queue-control 能力时才启用队列操作;Android 端则见 ConversationScreen.kt。iOS 的"立即插话"按钮定义在 ConversationView.swift。
queue 与 steer 的底层实现
这套功能的协议层定义在 GatewayProtocol.kt 中,共三类请求:
message:发送消息时携带mode字段,仅允许"queue"或"steer"两个取值(见 GatewayProtocol.kt#L510);queue-update:对指定sessionId+itemId执行remove或steer操作,等待queue-item-updated回执;session-queues/session-queue:Host 下发的队列基线快照与单会话更新。
真正的状态管理收敛在共享模块 SharedQueueStore.kt 中,Android 与 iOS 共用同一套逻辑,两端只负责原生 UI 与网络执行。它的核心设计原则:
- 只展示
placement=queued的条目,steering和context不会被重复展示为排队消息(见 SharedQueueStore.kt#L8); - 队列以 Host 全量快照替换,操作不做乐观删除——必须等
queue-item-updated回执且accepted=true才更新本地(见 SharedQueueStore.kt#L74-L89); - 操作互斥:同一时间只允许一个队列操作在途,防止并发点击造成混乱。
关于 steering 消息的展示还有一处巧思:已被提升但尚未写入持久历史的插话消息,Android 与 iOS 都会通过共享投影显示为普通用户气泡(临时行不修改持久事件序号水位,正式 user/message 到达时按原消息 ID 原地更新同一行),实现细节见 SharedConversationStore.kt。
实际效果:真实 Host 联调验证
这套链路已在真实 Host 上完整跑通,测试会话中依次验证了:
- Agent 执行等待命令期间发送
Reply ORIGINAL.,消息出现在输入框上方的队列条中; - 点击铅笔,Host 确认移出后原文字回填并聚焦输入框;
- 修改为
Reply EDITED.并重新发送,Host 日志确认mode=queue,队列显示修改后的文字; - 点击向上箭头,Host 接受
queue-update,条目从排队 UI 移除,执行仍交由 Host; - 再发送
Reply REMOVE.,点击垃圾桶,Host 确认后条目移除。
后续还观察到排队消息被 Host 消费后正式进入对话正文,完整过程记录在 Docs/queue-steer-integration.md 中。
常见问题:插话会不会打断 Agent?
- 不会。 App 提交的是"意图"(排队/提升/删除),Host 决定何时、如何把插话交给 Agent,App 本身不干预执行;
- 会不会丢消息? 不会。发送需等待
sent回执才清空输入框,失败和超时都会保留输入内容;重新连接后以 Host 新基线重建队列; - 后台会不会漏掉插话? 后台保活逻辑同时考虑"活动轮次"和"Host 待执行队列",插话或被删除的排队项不会被误计为未完成的新轮次;
- 网关要升级吗? 最初的队列操作无需更改网关;插话回显修复仅在实时用户事件中补充了
raw.id(取自 Host 原始消息 ID),没有改变 Host 执行逻辑。旧网关不带 ID 时按正文和附件顺序匹配,跨端同时发送相同正文时无法保证精确关联,建议配合更新后的网关使用。
写在最后
queue 与 steer 让 Whaleness 不只是"看 Agent 干活"的窗口,而是可以中途参与对话的协作者:想排队就 queue,想立即插话就 steer,想反悔还有编辑和删除兜底。所有操作都以 Host 回执为准,状态永远与服务端一致。
想进一步了解,可以继续阅读:



