deepseek-harness/docs/core-data-structures/user-interaction.zh.md

用户交互

English | 中文

dsh-user-interaction 的用户交互 seam。它是提供方无关的词汇，工具或权限插件在需要人类回答后 agent（智能体）才能继续时使用这套词汇。UI 表面提供活跃的 UserInteractionProvider：dsh-stdio-demo 在 readline 中渲染问题，dsh-acp 将其映射为 ACP（Agent Client Protocol）表单征询。

源码：packages/ui/user-interaction/src/index.ts

问题选项

AskUserQuestionOption 是可选择项的形状。label 是面向用户的选项文字，同时也是面向模型的选中值；description 是可选的 UI 帮助文本。

interface AskUserQuestionOption {
  /** User-facing label. */
  label: string
  /** Optional extra context rendered by capable UIs. */
  description?: string
}

问题条目

AskUserQuestionItem 是请求中的一个问题。模型提供一个稳定的 id，回答时原样回传，使批量问题可路由。

interface AskUserQuestionItem {
  /** Stable model-provided question id, echoed in the answer. */
  id: string
  /** The question to display. */
  question: string
  /** Optional short heading/group label. */
  header?: string
  /** Optional choices the UI can render as a menu. */
  options?: AskUserQuestionOption[]
  /** Whether more than one option may be selected. Defaults to single-select. */
  multiSelect?: boolean
}

提问请求

AskUserQuestionRequest 是跨包（package）的请求。questions 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。

interface AskUserQuestionRequest {
  /** Questions to display. */
  questions: AskUserQuestionItem[]
  /** Calling agent, when the request came from an agent tool call. */
  agent?: Agent
  /** Abort signal for the owning tool/step. */
  signal?: AbortSignal
}

回答

提供方为每个已回答的问题 id 返回一条回答。selected 包含选中的选项标签，custom 在用户输入自由文本时携带「其他」回答。当 custom 存在时，selected 为空；自定义文本是对选中项的覆盖，而非补充。

interface AskUserQuestionAnswerItem {
  /** The answered question id. */
  id: string
  /** Selected option labels. Empty when the answer is purely custom text. */
  selected: string[]
  /** Optional free-text "Other" answer. */
  custom?: string
}

interface AskUserQuestionAnswer {
  /** Structured answers keyed by question id. */
  answers: AskUserQuestionAnswerItem[]
}

提供方

同一上下文中只能有一个活跃的提供方。提供方注册绑定到 effect，因此 HMR（热模块替换）或 dispose（资源释放）会移除当前活跃的 UI。

interface UserInteractionProvider {
  ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
}

错误

UserInteractionError 继承 HarnessError，因此 ctx.tools.execute() 会保留 { name, code }，用于面向模型的工具失败，如 EMPTY_QUESTIONS、NO_PROVIDER、ASK_ABORTED 或 ACP 侧取消。

class UserInteractionError extends HarnessError {
  constructor(message: string, code: string, options?: ErrorOptions) {
    super(message, code, options)
    this.name = 'UserInteractionError'
  }
}