深入理解 DSH plugin 用户提问:呈现意图、计时窗口、迟到回复与投影到底怎么对齐才对
“用户晚点回答,工具却又返回了一次结果”,这类问题多半是把 pending 当成了完成。 DSH plugin 的用户交互 seam 里,pending 明确表示“问题仍可回答”,不是空答案,也不是授权。理解这个区别,才能读懂计时与迟到回复。 DSH插件 把 pending 当成空答案,是迟到回复类问题最常见的起点。
三个形状与呈现意图
intent 只改展示,答案编码完全一样。(来源)
AskUserQuestionOption 有 label 与可选 description。label 既是面向用户的选项文字,也是面向模型的选中值——这一点决定了答案里出现的是标签字符串,而不是索引。
AskUserQuestionItem 包含:稳定的 id(随答案原样返回,使批量问题仍可路由)、question、可选 detail(随问题渲染但不放进选项标签)、可选 header、可选 options、可选 multiSelect(默认单选)与可选 intent。
请求里 questions 是数组,这样 UI 可以在一个流程中呈现相关提示,同时保持每个回答有稳定的 id。如果提供 agent,它必须与存活调用方是同一实例;只有当前注册表把该实例识别为运行时根时,交互 seam 才接纳它。
AskUserQuestionIntent 只有两种:
plan-review— 指定批准选项,并要求提供计划正文;approve按名字指定(不按位置),且必须命名本问题的某个选项,否则在ask()被拒;每个其他选项都表示不批准。approval— 阻塞式权限决策,固定动作、无自由文本;要求只有一个阻塞式问题,带有说明以及互不相同的拒绝、允许与可选始终允许标签,完整对应已提供的选项,不支持多选或计时等待。
approval 的 subject 只是供人识别的元数据,永远不是授权身份。不识别某个 tag 的 UI 会退回通用选项列表,答案编码不受影响。
回答的四种编码
单选时 custom 覆盖 selected,多选时可以并存。(来源)
提供方为每个问题 id 返回一个回答项 AskUserQuestionAnswerItem,含 id、selected 与可选 custom:
- 单选且用户选了选项 —
selected有一个标签,无custom; - 单选且用户输入自由文本 —
custom携带“其他”回答,selected为空; - 多选且补充自由文本 —
custom可以补充selected中的标签; - 被跳过的问题 — UI 可以用
selected为空且无custom的回答项,在其余问题均已完成的批次中保留它。
第 4 条常被误解成“空答案”。它不是失败,而是显式保留:批次完整性靠这条规则维持。
计时问题与 pending
计时窗口关掉后,agent 可以继续独立工作。(来源)
计时问题在有界的前台窗口内等待,然后让 agent 继续独立工作。用户在窗口内回答,工具返回整批答案;否则 TimedUserQuestionResult 为 { pending: true, callId }。
官方对 pending 的界定很硬:它表示问题仍可回答,不是空答案、拒绝、确认或授权。
前台回答器收到的是 wait: { callId, timed: true }:callId 标识卡片及前台等待。Client 调用 attachWait 接手等待并取得剩余时长;传输层只转发原事件,不检查或改写这些字段。不带 timed 的 wait 表示无限期等待的具名卡片请求;没有 wait 则是无卡片 key 的阻塞请求。
attachWait 与 deadline 的所有权
deadline 在 Host,倒计时在 Client,两者不能互相替代。(来源)
Client 接手通过业务 Remote stream 表达,不等同于 Gateway 投递。TimedQuestionWait 保存原 Host deadline,仅在没有接手记录时运行计时器。
attachWait stream 发出当前剩余时长,Client 用本地时钟倒计时。聚焦、编辑与“慢慢回答”状态仍归本地所有。stream 取消会释放相应接手记录;最后一个接手方离开后,Host 恢复原 deadline。
无人接手时,超时会中止前台 waterfall 专属的 signal 并返回 pending,不取消 Turn。Gateway 与 api-remotes 不包含问答专属计时策略——这条分工保证了计时逻辑只有一处。
userQuestions 投影只记问题与结算
投影不记等待状态、聚焦状态或 deadline。(来源)
userQuestions 投影把现有事件折叠成可回答的问题集合与已结算的集合。它的口径很克制:每个 request/header 都记录了模型看到的确切工具 schema;只有请求头声明了带 timeout 参数的 timed ask_user_question schema,投影才跟踪原生调用,而阻塞式 legacy 工具从不声明它。
跟踪规则:原生 tool/call 打开一个问题;tool/result 只在两种情况下把它标为 continued——带 pending 载荷,或是 Session resume 修复补写的 TOOL_OUTCOME_UNKNOWN 合成结果。回答批次把它连同该批次移入 settled,其他结果或失败都丢弃它。
run_code 的 PTC 子调用如果在 tool/ptc-dispatch 结果中返回 pending,也会进入投影,尽管请求头只列出 run_code。
迟到回复的结算点很精确:消息获准成为 user/message 时,才把已继续的问题连同消息中的回答批次移入 settled。原因是计时调用自己的结果记录的是超时,transcript 行无处可读用户最终的选择。
排队的回复可在准入前取消,此时问题仍可回答。回复正文不含可读批次时,该调用以零答案结算;回复指向的调用已不在可回答集合中时不改变任何内容。
answer 的准入与错误
开放中的问题只能走 waterfall,continued 之后才走 Remote。(来源)
开放中的问题只能通过 waterfall 回答。问题变为 continued 后,answer Remote 方法向所属 agent 排入一条用户消息,并在其空闲时唤醒它。消息的 source 为 user-question-reply,outcome 为 answered,正文是 answer_to_pending_question 载荷。
三条准入规则:开放或未知调用返回 false;回复仍在排队时的第二次提交以 REPLY_QUEUED 拒绝,Host 重启后也一样;遗漏或重复问题的回答批次以 BAD_ANSWER 拒绝。
两个容易误判的现象:收起 Client 面板不会发送内容;前台超时只结束工具等待。已继续的问题没有期限,在回复进入会话前仍可回答。Host 重启后 Session 重开时 Remote 层会恢复根 agent,之后的迟到回复会作为新一轮进入。
错误类型是 UserQuestionError,继承 HarnessError,因此 ctx.tools.execute() 会保留 { name, code },用于面向模型的工具失败,例如 EMPTY_QUESTIONS、BAD_INTENT、NO_PROVIDER、ASK_ABORTED 或 UI 侧取消。
验证:超时后回答
验证要确认“超时不等于失败”,以及“迟到回复只结算一次”。(来源) 六步:
- 提交一个计时问题但不回答,断言工具返回
{ pending: true, callId },且轮次没有结束。 - 调
answer提交回复,断言向所属 agent 排入用户消息并在空闲时唤醒。 - 在回复排队时再提交一次,断言以
REPLY_QUEUED拒绝。 - 提交一个缺少某个问题 id 的批次,断言以
BAD_ANSWER拒绝。 - 重启 Host 后再回答同一问题,断言迟到回复作为新一轮进入并结算。
- 在回复获准前撤销一个空闲注入式的排队回复,断言问题仍可回答。
如果第 2 步之后原工具结果被改写,说明实现把迟到回复写回了旧调用,这违反“计时调用的结果记录超时”的约定。
审批与提问的组合用法,可以对照审批与用户提问;计划模式的评审路径见计划模式状态恢复。
一句话收束: intent 只改展示、pending 不是答案、deadline 在 Host 倒计时在 Client、投影不记等待、迟到回复只在消息准入时结算一次。
常见问题
不是,DSH plugin 的 pending 只表示问题仍可回答。DSH plugin 明确说它不是空答案、拒绝、确认或授权。
不会,DSH plugin 的前台超时只结束工具等待。DSH plugin 在无人接手时中止前台 waterfall 专属的 signal 并返回 pending,不取消 Turn。
不会,DSH plugin 的原工具结果记录的是超时。DSH plugin 让迟到回复在消息获准成为 user/message 时,把问题与回答批次移入 settled,transcript 从那里读最终选择。
会被拒绝,DSH plugin 用 REPLY_QUEUED 表示回复仍在排队。DSH plugin 在 Host 重启后同样会拒绝这种重复提交。
相关术语
- AskUserQuestionIntent
- AskUserQuestionIntent 是调用方声明的呈现意图,只有 plan-review 与 approval 两种 kind,只改展示不改答案编码。— packages/interaction/user-questions/src/index.ts
- TimedUserQuestionResult
- TimedUserQuestionResult 是计时提问的结果,要么是整批答案,要么是带 callId 的 pending 标记。— packages/interaction/user-questions/src/index.ts
- UserQuestionState
- UserQuestionState 描述一个问题还能否由工具返回答案,取值为 open 或 continued。— packages/interaction/user-questions/src/index.ts
- SettledUserQuestion
- SettledUserQuestion 是一个已结算的计时提问,含 callId 与记录下来的回答批次。— packages/interaction/user-questions/src/index.ts
来源
- DeepSeek Harness 官方参考 - 用户交互· deepseek-ai
- packages/interaction/user-questions/src/index.ts· deepseek-ai