首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >SuperAgent 交互设计升级实录 ——把「派发」变成可读的界面

SuperAgent 交互设计升级实录 ——把「派发」变成可读的界面

原创
作者头像
OneCode
发布于 2026-11-08 22:52:03
发布于 2026-11-08 22:52:03
1710
举报
文章被收录于专栏:ooderAgentooderAgent

把「派发」变成可读的界面

副标题:——SuperAgent 交互设计升级实录:一次委派只留两条消息,一道人工门先把选项还给人 日期:2026-11-08 | 范围:chatnext-base(App.js / Copy.js / ConfirmBar.js / TimelineTree.js / TaskPanel.js)· ooder-a2a(投递确认) 证据口径:源码契约(模块 + 行号)+ 客户生产环境真实实例实拍 9 张截图 + 2 张示意图(2026-11-08) 前篇:《常驻之后:SuperAgent 的架构真相,与 A/B/C 的三层范式》


摘要

上一篇讲的是「补什么」:常驻会话、Thread 直通、两级过滤、只读恢复、可回滚归属——SuperAgent 生产的是任务之间的关系,不是业务结果。

这一篇讲「关系怎么被看见」。

因为记账层一旦落地,交互层马上会遇到三个新问题:

  1. 内部路由事件开始刷屏
  2. :TASK_REQUEST、TASK_STATUS、FLOW-RELAY 都是系统事实,不是用户消息。全渲染是噪声,全隐藏又会让「谁在替我干活」消失。
  3. 成功与失败会同时出现在屏幕上
  4. :执行体回执、任务步骤、时间轴各有一套状态。没有单一说法,用户就无法判断「现在到底成没成」。
  5. 人工门成了唯一的阻塞点
  6. :门卡如果只渲染「上传区」而吞掉了业务选项,用户不是「不想选」,而是「没得选」。

本文按这三条,拆开本轮交互升级的七个动作,并用真实实例截图逐张说明。所有截图都来自真实点击产生的状态,不用接口造数、不跳转补拍。

关键词:交互契约;单一文案源;回执气泡;参与者口径;人工门;UPLOAD_OR_CHOICE;时间轴身份;投递快速失败


一、先把「谁在说话」分层

1.1 三层事实,三个视图

SuperAgent 运行时会产生三类事实,它们必须落在三个不同的地方,而不是挤进同一个消息流:

事实

例子

应该出现在哪

用户面结果

「已接管执行:流程已启动(实例 a1b2c3d4,当前 已暂停)」

消息流(气泡)

执行面步骤

「请求已发送 / 正在理解您的需求…」

任务步骤面板

协议面身份

TASK_REQUEST sa-router→fin.tax、TASK_RESPONSE fin.tax→sa-router

事件时间轴(可审计,不默认上屏)

这条分工不是审美选择,而是「记账层」的必然结果:账本可以很细,但界面默认只应该收敛成一句话。

图 1:财务域工作台默认态。左栏是会话与状态徽标,中间是快捷入口与输入区,右下角是控制台入口(调试用,不是异常提示)。

1.2 三条可执行原则

本轮所有改动都服从三条判据:

  • P1 会话是实现细节
  • :用户关心的是「这件事到哪了」,不是 sessionId;
  • P2 人工注意力稀缺
  • :只在需要人拍板、或结果可用时打扰;一次只问一个具体问题;
  • P9 降级不静默
  • :失败必须带原因与下一步,不能只留一句「处理中」。

二、升级一:一次派发,只留两条消息

2.1 症状:内部管道把消息流变成了协议日志

在接入 SA 派发平面之后,消息流里一度同时出现:

  • 手机号/节点/追踪串:A2A 聚合 · sa-router → fin.tax · TASK_REQUEST;
  • 裸状态徽标:PUBLISHED / RECV;
  • 心跳行、FLOW-RELAY 内部中继行;
  • 以及执行体回执正文(这才是用户真正需要的)。

结果是「一次委派」在屏幕上被写成七八条同质记录,真正的结果被淹掉。

2.2 判据:内部发送者 + 非失败 + 路由类消息 → 不出泡

收口点在 Copy.js(L738-799) 的 a2aLine():

代码语言:javascript
复制
// ★ 2026-11-07(SA 交互契约 v1):内部编排管道(sa-router / p2a-route / studio)
//   之间的请求/回执/状态推进属于系统路由事实,不再生成气泡;
//   一次派发只保留「一条进度 + 一条结果」。失败仍然渲染。
var orchestration = isInternalSender(d.fromAgentId) || isInternalSender(d.toAgentId);
if (!fail && orchestration
        && (t === 'TASK_REQUEST' || t === 'DATA_REQUEST'
            || t === 'TASK_RESPONSE' || t === 'DATA_RESPONSE'
            || t === 'TASK_STATUS' || t === 'NOTIFICATION')) {
    return '';
}

三个细节值得注意:

  1. 只过滤「非失败」
  2. :失败一定要上屏,并且带原因;
  3. 只过滤「内部发送者」
  4. :业务执行体之间的委托仍然可见(这正是「谁在替谁干活」);
  5. 过滤的是「气泡」,不是「事件」
  6. :事件照样进时间轴,审计能力没有丢。

2.3 单一文案源:气泡与台账共用一句话

同一条 A2A 记录,既会进入消息流气泡,也会进入协作台账。历史上两处各写一套,同一事件出现两种说法。

现在两处都调用同一个 a2aLine():

  • 成功:✅ 「税务雷达执行体」返回:…(回显执行体原文);
  • 失败:⚠️ 「X」未能完成任务:… 或 ⚠️ 未能送达「X」:…;
  • 进行中:🤖 已将任务委托给「X」,等待执行…;
  • 心跳、内部中继:空串,不渲染。

图 2:内部事件 → 单一文案源 → 四个视图。过滤的是气泡,不是事件;一次委派的用户面预算最多两条(进度 + 结果)。

图 3:输入 @税 后弹出「指派智能体 · “税”」。同名执行体不止一个,因此副标题把部署形态放在最前面(「场景宿主(本机)」/「独立智能体(远端)」),差异在面板截断之前就可见;完整名称与 agentId 保留在悬停提示里。


三、升级二:回执正文必须「有话说」

3.1 现场问题:回执只剩「正在等待」

实时 SSE 帧里,执行体的回复可能只带 d.content,不带 payload_json。若只从 payload 取正文,回执气泡就会退化成:

🤖 正在等待「税务雷达执行体」返回结果…

任务其实已经接管了,界面却还在等。

3.2 做法:正文兜底

Copy.js(L775-785) 补了一步兜底:

代码语言:javascript
复制
// ★ 回执兜底:执行体回执/答复可能只带 d.content(SSE 实时帧无 payload)。
var body = a2aPayloadText(payload);
if (!body && d.content
        && (t === 'TASK_RESPONSE' || t === 'DATA_RESPONSE' || t === 'AGENT_RECORD')) {
    body = String(d.content);
}
if (t === 'TASK_RESPONSE' || t === 'DATA_RESPONSE') {
    if (body) return '✅ 「' + from + '」返回:' + body;
    if (st === 'RECV' || st === 'LOCAL_CONSUMED') return '✅ 「' + from + '」已回复。';
    return '🤖 正在等待「' + from + '」返回结果…';
}

3.3 实拍:回执气泡长什么样

图 4:用户说「导出上个月的税负分析结果」,消息流内出现发言人名为「税务雷达执行体」的回执气泡:✅ 「税务雷达执行体」返回:「fin.tax」已接管执行:流程已启动(实例号已脱敏,当前 已暂停)。请在会话内完成待办(上传明细 / 人工确认)后继续。

这一条气泡同时满足了四件事:

  • 谁做的
  • :发言人名 + 头像;
  • 做了什么
  • :已接管执行、流程实例号;
  • 现在什么状态
  • :已暂停(不是「成功」也不是「失败」);
  • 下一步
  • :上传明细 / 人工确认。

输入区底部同时出现 🤖1 · 税务雷达执行体——参与者口径与气泡口径一致。


四、升级三:参与者口径统一(🤖N 与 👥N)

4.1 同一件事,不要两种叫法

多人协作显示 👥N,多 Agent 协作却在另一个地方显示英文 agentId,甚至出现 fin. / llm. 前缀。用户既不知道「有几个智能体」,也不知道「它是谁」。

现在的口径在 App.js(L1562-1573):

代码语言:javascript
复制
/** 协作 Agent 参与者展示(与会话参与者 👥N 并列,避免两套参与者口径分叉) */
App.prototype._renderAgentParts = function (ids) {
    var el = global.document.getElementById('cn-agent-parts');
    if (!ids || !ids.length) { el.textContent = ''; el.style.display = 'none'; return; }
    var names = ids.map(function (x) { return self._agentDisplayName(x); });
    el.textContent = '🤖' + ids.length + ' · ' + names.join('、');
    el.title = '参与协作的 Agent:' + names.join('、') + '(' + ids.join('、') + ')';
};

规则很硬:

  • 正文只出中文名
  • (税务雷达执行体),不出 fin.tax;
  • 原始 ID 只进 tooltip
  • ,排障时可复制;
  • 人数在 👥,智能体数在 🤖
  • ,两个口径并列,不互相冒充。

4.2 刷新以后,关系还在

A2A 台账回放(App.js(L1469-1507))在打开/切换会话时拉取:

代码语言:javascript
复制
GET /api/studio/a2a/messages?conversationId=<id>&limit=50

然后把每一行以与实时事件同构的载荷重新 bus.dispatch('a2a_record'),复用同一套幂等去重与渲染。这意味着:刷新、换机、切会话之后,「谁委托了谁」仍然可见,而不是只在当轮内存里。

图 5:协作面板给出「业务智能体 → 税务雷达执行体,委托任务 ×2」,并统计 p95 间隔 213ms;消息明细标注「已转交」。这比一个「处理中」转圈更能回答「卡在哪」。


五、升级四:人工门,把「选项」还给用户

这是本轮最重要的一处设计决定,因为它直接决定用户「有没有得选」。

5.1 现场问题:四个业务选项只渲染出一个上传区

客户实测的门是 tb_intent_disambiguate:

  • 服务端下发 type=FILE_UPLOAD;
  • 同时下发 options.length=4(上传单据 / 从有成取数 / 查询规则 / 重新描述)。

如果先看 type:只要是 FILE_UPLOAD 就进上传分支。结果四个业务选项一个都没渲染成按钮,用户只看到一个上传区——而这道门问的其实是「你想怎么推进」。

5.2 判定:类型由「有没有选项」决定

ConfirmBar.js(L296-320) 把判定改成确定性顺序:

代码语言:javascript
复制
ConfirmBar.prototype._resolveType = function (n) {
    var opts = Array.isArray(n.options) ? n.options : [];
    var hasOptions = opts.length > 0;
    var t = String(n.type || '').toUpperCase();
    if (t === 'INPUT') return 'INPUT';
    var uploadOpt = opts.some(...);                       // 任一选项声明 followUp=FILE_UPLOAD
    if (t === 'UPLOAD_OR_CHOICE') return hasOptions ? 'UPLOAD_OR_CHOICE' : 'FILE_UPLOAD';
    if (t === 'FILE_UPLOAD') return (hasOptions || uploadOpt) ? 'UPLOAD_OR_CHOICE' : 'FILE_UPLOAD';
    if (hasOptions) return uploadOpt ? 'UPLOAD_OR_CHOICE' : 'CHOICE';
    return 'OPERATION';                                   // 服务端操作栏
};

一句话:带上传项的多选项门 → UPLOAD_OR_CHOICE;上传只是其中一条路,不是全部。

5.3 交互硬约束:展开上传,不吞掉别的选项

UPLOAD_OR_CHOICE 的交互面(ConfirmBar.js(L337-402))有六条硬约束:

  1. 点「上传」项就地展开上传区,不提交、不改变其它选项;
  2. 展开后其余选项仍在原位、可见、可点(面板追加在列表之后,不替换、不遮挡);
  3. 上传区按钮(上传并继续 / 跳过上传 / 收起)只作用于本门;
  4. 选项与展开按钮都是 <button>,带 aria-expanded 与 aria-controls;
  5. 焦点落点明确:展开 → 落区;收起 → 触发展开的那个按钮;
  6. 「取消」始终在,且不伪装成「确认」。

图 6:tb_intent_disambiguate 门的真实渲染。标题「需要确认 / 意图歧义消解」,正文「请确认是否继续」,四个选项全部成为可点行:「☁️ 从有成导入单据 / 📤 上传数据文件并执行 / ✍️ 重新描述您的需求 / 🔍 查询规则与历史记录」,底部「1773 秒后超时(需人工处理)」+ 进度条 + 「取消」。任务面板同步显示「等待人工处理(未完成)」,而不是一句「本轮完成」。

5.4 三种门,三种徽标

门不是只有一种语义。_html() 里按风险等级给出三种徽标(ConfirmBar.js(L160-170)):

徽标

触发条件

用户应该怎么理解

🔴 强制人工

critical=true(财务红线:金额/对外承诺)

必须人拍板,不允许自动放行

⚠️ 例外介入

humanMode=EXCEPTION_INTERVENTION

出错了,需要人决定怎么恢复

需要确认

其余 HUMAN 节点

正常流程中的一次选择

倒计时也分两档(ConfirmBar.js(L619-644)):

  • 可自动通过:N 秒后自动继续;
  • 需人工处理:N 秒后超时(需人工处理);
  • 升级人工:N 秒后超时 → 升级人工例外介入(不会自动放行)。

「超时」在不同门上的后果不同,文案就不能一样。

5.5 键盘与读屏也要能走完这道门

门的可操作性是硬指标,不是加分项:

  • 选项、展开按钮、取消都是 <button>,天然可聚焦;
  • 展开按钮带 aria-expanded 与 aria-controls="cn-upload-panel",读屏能知道「这里可以展开、展开后会多出一块区域」;
  • 焦点管理有明确落点:展开后焦点进入落区,收起后回到触发展开的那个按钮——键盘用户不会「按一下 Tab 就找不到自己了」;
  • 任务面板头部已经是正确范式:role=button + tabindex=0 + aria-expanded,并支持 Enter/Space(TaskPanel.js(L56-66))。

这三条合起来,意味着一个只用键盘的财务人员,也能在不看鼠标的情况下完成「选一条路 → 展开上传 → 收起 → 取消」。

图 7:先判定「有没有选项」,再谈生命周期。类型判定是确定性的;超时、失效、升级人工是三种不同结局,必须三种界面。


六、升级五:门的「后事」——超时、失效,不渲染死卡

门是会过期的。三种结局必须有三种界面:

结局

触发

界面

已超时

倒计时到 0

「已超时」徽标 + X 已超时未处理(N 秒),本次确认已失效,请重新发起,4 秒后自动收起

已失效(stale)

流程已推进/终结,该门作废

「未确认」徽标 + 后端 staleReason 原文,6 秒后收起

提交中/提交失败

用户点了选项

按钮进入提交态;失败保留门,不清空已选

实现分别在 _showExpired() 与 _showInvalidated()(ConfirmBar.js(L710-743))。关键点是 stale 文案取后端 staleReason,前端不自行编造——这避免了「门为什么没了」变成猜谜。

门被判定失效时,界面不能只留一句「请在下方卡片中选择」——卡片已经不在渲染队列里,那句话会把用户指向空白。因此失效提示要常驻到用户行动或新门到达,并给出唯一确定出口「重新描述需求」:

图 8:失效门提示条「未确认 / 流程已推进,该人工门未确认。」+「重新描述需求」。该条不自动消失,直到用户点击或新门到达;点击后清空输入、聚焦输入框、收起提示条。


七、升级六:时间轴上的「人」与「身份」

7.1 人工节点要能一眼看出「在等谁、等多久」

时间轴的人工节点页脚(TimelineTree.js(L151-179))固定渲染四段信息:

  • 必须处理
  • 标签(mandatory);
  • [活动名] 提示语
  • ;
  • 审批人:…
  • / 委托目标:…;
  • 相对时间(51 分钟前)。

这比「等待确认」四个字有用得多:谁在等、等了多久、该找谁。

7.2 流程控制不该藏在菜单里

时间轴头部常驻 检查点 / 暂停 / 恢复 / 终止(TimelineTree.js(L198-215))。长任务卡住时,用户不必回到对话里「求它停」。

图 9:20:12 新建会话的真实运行态。时间轴(节点 9:session:1 / process:1 / notice:3 / phase:1 / activity:1 / human:1 / artifact:1)显示「路由 → tax-burden-scene → 意图理解 → 意图歧义消解(A2P waiting)」,并标出「必须处理 / 等待确认」;下方是同一个门的可操作卡片;再下方是协作面板(本会话 0 条,无委托)。

7.3 SA 身份必须可审计

用户默认不该看到 sa-router → fin.tax,但审计时必须看得到。时间轴把协议事实按 A2A 徽章呈现:

图 10(局部):TASK_REQUEST sa-router→fin.tax、TASK_RESPONSE fin.tax→sa-router、TASK_RESPONSE fin.tax→node-a…(节点 ID 已遮挡)三条 A2A 记录均为 done;同一棵树里还有 tax-burden-scene__tb_youcheng_sync、上传解析、正文 等业务节点。协议面与业务面在同一棵树里可对照,但默认折叠。

7.4 任务步骤的「增量语义」

步骤面板最容易做成「每来一个事件就重排一遍」,结果用户正在看的那一行突然跳走。当前实现用四条规则避免这件事(TaskPanel.js(L142-230)):

  • 按 key 复用行
  • ,不重建 DOM;
  • 最多 50 行
  • ,超出后折叠旧行,并提示「已省略 N 步」;
  • 只保留最近 2 个 done
  • ,避免历史刷屏;
  • 回退只移动高亮、不删节点;重复到达只加「第 N 次」
  • ——这样「重试了一次」是可见的,而不是像什么都没发生。

交互上的意义只有一个:面板可以一直开着,不会因为更新而打断阅读。


八、升级七:失败要「快」,但不能「哑」

8.1 5000ms 投递确认:把无限等待变成明确失败

MQTT 组播/定向在「对端进程已停」时依然会「发布成功」,于是只能空等到请求超时。现在的做法是(A2AProtocolServiceImpl.java(L1632-1655)):

代码语言:javascript
复制
// ★ 投递确认快速失败:以执行端本就会回的 TASK_STATUS(ACCEPTED) 作为投递凭据
if (request.getDeliveryTimeout() > 0) {
    ...
    if (acceptedRequestIds.remove(rid)) return;   // 已被受理:继续等 TASK_RESPONSE
    pending.complete(A2AResponse.failure(rid, from, STATUS_UNDELIVERABLE,
            "投递未获受理回执(" + deliveryMs + "ms)"));
}

线上口径是 delivery-timeout-ms=5000。它不解决「对端没起来」,但它把「用户盯着转圈 60 秒」变成「5 秒后知道没送达」。

8.2 文案分档:送达失败 ≠ 执行失败

a2aLine() 对失败做三档区分:

场景

文案

投递失败(UNDELIVERABLE)

⚠️ 未能送达「X」:…(目标解析不出中文名时用无主语句式)

执行体返回失败

⚠️ 「X」未能完成任务:…

其他失败

⚠️ 本次协作未能完成:…

原始技术信息不上屏;系统类失败另给「转交技术智能体」入口。

8.3 实拍:一次真实的快速失败

19:19 在同一实例上发送 @税务雷达执行体 帮我看看本月税务情况,先给出思路,消息流给出:

「llm.tax」未能完成该请求:投递未获受理回执(5000ms)

失败并不止于这句话:气泡下方直接给出两条可点的下一步——「重试上一条」把本轮请求(含 @ 绑定)原样填回输入框、由人确认后再发;「换个智能体」预填 @ 并打开候选面板。同时任务步骤头部改判为「本轮未完成」,失败的那一步标红,避免「失败回执」与「本轮完成」同屏并存。

图 11:「llm.tax」未能完成该请求:投递未获受理回执(5000ms) 下方是「重试上一条 / 换个智能体」;任务面板显示「1/2 步完成 · 本轮未完成」,「已转交「llm.tax」」一步标红。重试只做「填回 + 人工确认」,不自动重发——服务端没有按原 messageId 重放的幂等接口。


九、边界与下一步

9.1 三个不做

  1. 不把时间轴做成默认主视图
  2. 。账本可见 ≠ 过程全量可见;默认展开会把「读结果」变回「读日志」。
  3. 不用前端定时器伪造进度
  4. 。「只对账、不重派」是底线,假进度会在失败时放大不信任。
  5. 不为了并行而开多列聊天窗
  6. 。Super-agent 的并行是任务级并行,不是多个窗口同时刷。

9.2 如果只做三件事

  • 建连对账
  • :connected / 页面可见性恢复 / 切会话三处触发,拉 messages + messages/incomplete + worklist 做差异合并,界面显示「正在同步 / 已同步」;
  • 待发队列
  • :忙时消息入队、上屏「待发送」,当前轮结束自动发,按 content + 3s 窗口 去重;
  • 错误卡
  • :error 事件补 code / retryable / turnId / userAction,前端统一「原因 / 影响 / 下一步 + 重试」。

三者都不需要动 Super-agent 运行时。


十、结论

  1. 交互层的第一职责不是「展示过程」,而是「给出单一说法」。
  2. 一次派发最多两条消息、气泡与台账共用 a2aLine(),是这条原则的最小实现。
  3. 回执必须有正文。d.content
  4. 兜底看起来是一个字段级修补,实际决定的是「用户能不能在 5 秒内知道事情到哪了」。
  5. 人工门的第一原则是「别吞选项」。UPLOAD_OR_CHOICE
  6. 把「上传」从「唯一入口」降为「其中一条路」,这是本轮最值得复用的交互模式。
  7. 失败要快,但不能哑。
  8. 5000ms 投递快速失败把无限等待变成明确失败;失败气泡现在带「重试上一条 / 换个智能体」,任务步骤同步改判为「本轮未完成」。
  9. 协议面不是不能给用户看,而是不能默认给用户看。
  10. 时间轴的 A2A 徽章证明:可审计与可读可以同时成立。

一句话收束:SuperAgent 把「任务之间的关系」记成了账;交互设计要做的,是把账翻成一句人话,并且在需要人拍板的那一刻,把选项完整地放到他面前。


说明:文中截图取自真实运行实例,已做脱敏——企业与账号信息以「客户」「财务管理员」代称,流程实例号、会话 ID、节点 ID 在正文中以占位值表示、在截图中做像素遮挡。fin.tax / llm.tax / sa-router 等协议标识保留原样,因为它们是本文论证所需的系统结构。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 把「派发」变成可读的界面
  • 摘要
  • 一、先把「谁在说话」分层
  • 1.1 三层事实,三个视图
  • 1.2 三条可执行原则
  • 二、升级一:一次派发,只留两条消息
  • 2.1 症状:内部管道把消息流变成了协议日志
  • 2.2 判据:内部发送者 + 非失败 + 路由类消息 → 不出泡
  • 2.3 单一文案源:气泡与台账共用一句话
  • 三、升级二:回执正文必须「有话说」
  • 3.1 现场问题:回执只剩「正在等待」
  • 3.2 做法:正文兜底
  • 3.3 实拍:回执气泡长什么样
  • 四、升级三:参与者口径统一(🤖N 与 👥N)
  • 4.1 同一件事,不要两种叫法
  • 4.2 刷新以后,关系还在
  • 五、升级四:人工门,把「选项」还给用户
  • 5.1 现场问题:四个业务选项只渲染出一个上传区
  • 5.2 判定:类型由「有没有选项」决定
  • 5.3 交互硬约束:展开上传,不吞掉别的选项
  • 5.4 三种门,三种徽标
  • 5.5 键盘与读屏也要能走完这道门
  • 六、升级五:门的「后事」——超时、失效,不渲染死卡
  • 七、升级六:时间轴上的「人」与「身份」
  • 7.1 人工节点要能一眼看出「在等谁、等多久」
  • 7.2 流程控制不该藏在菜单里
  • 7.3 SA 身份必须可审计
  • 7.4 任务步骤的「增量语义」
  • 八、升级七:失败要「快」,但不能「哑」
  • 8.1 5000ms 投递确认:把无限等待变成明确失败
  • 8.2 文案分档:送达失败 ≠ 执行失败
  • 8.3 实拍:一次真实的快速失败
  • 九、边界与下一步
  • 9.1 三个不做
  • 9.2 如果只做三件事
  • 十、结论
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档