# Agent 向用户提问 — 技术方案设计

> 版本: v1.0 | 日期: 2026-06-24 | 状态: 待评审

## 1. 需求概述

Agent 在执行任务过程中，需要在不中断任务流的情况下向用户发起提问，用于：

- 获取用户偏好或需求澄清
- 模糊指令的二次确认
- 实现方案的多选一决策
- 提供选项让用户选择方向

底层基于 ToolCall 机制实现，工具名为 `ask_user_questions`。

## 2. 核心设计思路

### 2.1 与现有机制的类比

本功能在架构上与 **LOCAL 模式工具审批流** 高度相似：


| 维度    | 工具审批 (approval)         | 向用户提问 (ask_user_questions) |
| ----- | ----------------------- | -------------------------- |
| 触发方   | ToolDispatcher 根据权限判断   | LLM 主动调用工具                 |
| 阻塞方式  | CompletableFuture.get() | CompletableFuture.get()    |
| 客户端渲染 | ApprovalStack 卡片        | QuestionPanel 问答面板         |
| 用户操作  | 批准 / 拒绝                 | 选择选项 / 自由输入                |
| 返回值   | 执行结果或拒绝错误               | 用户回答的结构化 JSON              |
| 执行模式  | 仅 LOCAL 模式              | **CLOUD 和 LOCAL 均可**       |


关键区别：审批是安全机制，由 ToolDispatcher 根据权限等级决定；提问是能力工具，由 LLM 自主决定何时调用。因此提问工具需要**独立于权限系统**，在任何执行模式下都能将问题路由到客户端。

### 2.2 端到端流程

```
LLM 输出 tool_call: ask_user_questions
    │
    ▼
AgentLoop.executeToolCalls()
    │
    ▼
ToolDispatcher.dispatch()
    │  识别为特殊工具，路由到客户端
    ▼
发送 ask_user_questions WsEvent → 客户端
    │
    ▼
客户端渲染 QuestionPanel 组件
    │  用户选择选项 或 输入自定义文本
    ▼
客户端发送 ask_user_questions_result WsEvent → 服务端
    │
    ▼
CompletableFuture 完成，AgentLoop 继续
    │
    ▼
LLM 收到 tool_result，继续执行任务
```

## 3. 后端设计

### 3.1 新增工具：AskUserQuestionsTool

**文件**: `backend/src/main/java/cn/etarch/mao/harness/tool/impl/AskUserQuestionsTool.java`

```java
@Component
public class AskUserQuestionsTool implements Tool {

    @Override
    public String getName() {
        return "ask_user_questions";
    }

    @Override
    public String getDescription() {
        return """
            Use this tool when you need to ask the user questions during execution. \
            This allows you to gather user preferences or requirements, clarify ambiguous \
            instructions, get decisions on implementation choices as you work, or offer \
            choices to the user about what direction to take.
            \
            Usage notes:
            - Users will always be able to select "Other" to provide custom text input
            - Use multiSelect: true to allow multiple answers to be selected
            - If you recommend a specific option, make it the first in the list and add \
              "(Recommended)" at the end of the label
            - preview supports rendered markdown in a monospace box, multi-line with newlines
            - Previews only render for single-select questions (not multiSelect)
            - When any option has preview, UI switches to side-by-side layout
            """;
    }

    @Override
    public Map<String, Object> getInputSchema() {
        // 返回 JSON Schema，详见下方
    }

    @Override
    public Map<String, Object> getOutputSchema() {
        // 返回 JSON Schema
    }

    @Override
    public String execute(String arguments, Long sessionId, String workspace) {
        // 此方法不应被直接调用 — 由特殊路由处理
        // 如果被调用，返回错误提示
        return "{\"error\": \"ask_user_questions must be dispatched to client\"}";
    }
}
```

**Input Schema**:

```json
{
  "type": "object",
  "required": ["questions"],
  "properties": {
    "questions": {
      "type": "array",
      "minItems": 1,
      "maxItems": 4,
      "items": {
        "type": "object",
        "required": ["question", "header", "options", "multiSelect"],
        "properties": {
          "question": {
            "type": "string",
            "description": "The complete question, ending with ?"
          },
          "header": {
            "type": "string",
            "maxLength": 12,
            "description": "Very short label, shown as chip/tag"
          },
          "options": {
            "type": "array",
            "minItems": 2,
            "maxItems": 4,
            "items": {
              "type": "object",
              "required": ["label", "description"],
              "properties": {
                "label": {
                  "type": "string",
                  "description": "Display text, 1-5 words"
                },
                "description": {
                  "type": "string",
                  "description": "Explanation of what this option means"
                },
                "preview": {
                  "type": "string",
                  "description": "Optional preview content (mockups, code, diagrams)"
                }
              }
            }
          },
          "multiSelect": {
            "type": "boolean",
            "description": "true = multiple answers allowed"
          }
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Optional tracking metadata"
    }
  }
}
```

**Output Schema**:

```json
{
  "type": "object",
  "properties": {
    "answers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "question": { "type": "string" },
          "selectedLabels": {
            "type": "array",
            "items": { "type": "string" }
          },
          "customInput": { "type": "string" }
        }
      }
    }
  }
}
```

### 3.2 ToolDispatcher 路由改造

**文件**: `backend/src/main/java/cn/etarch/mao/harness/tool/ToolDispatcher.java`

新增特殊路由判断。`ask_user_questions` 不属于 `SERVER_ONLY_TOOLS`（那组是 task_* 工具），需要独立处理：

```java
// 新增常量
private static final String ASK_USER_QUESTIONS = "ask_user_questions";

// dispatch() 方法中新增分支（在 SERVER_ONLY_TOOLS 判断之后）
if (ASK_USER_QUESTIONS.equals(toolName)) {
    return dispatchAskUserQuestions(arguments, sessionId, workspace);
}
```

`dispatchAskUserQuestions()` 方法实现：

1. 生成 `requestId`（UUID）
2. 构建 `WsEvent`（type = `ask_user_questions`），data 中包含 `requestId` + 工具参数
3. 通过 `StreamingWsRegistry.send()` 发送给用户
4. 创建 `CompletableFuture<String>` 并注册到一个专用的 `AskUserQuestionsRegistry`
5. 阻塞等待 `future.get()`，设置超时（默认 5 分钟）
6. 超时返回 `{"error": "User did not respond within timeout"}`

**为什么不用 LocalToolExecutor**: LocalToolExecutor 绑定了 LOCAL 模式的连接管理（检查客户端是否在线、发送 tool_execute 事件），而提问工具需要在 CLOUD 模式下也能工作。需要独立的发送/等待机制。

### 3.3 新增 AskUserQuestionsRegistry

**文件**: `backend/src/main/java/cn/etarch/mao/harness/tool/AskUserQuestionsRegistry.java`

```java
@Component
public class AskUserQuestionsRegistry {

    // key: (sessionId, requestId) -> CompletableFuture<String>
    private final Map<String, CompletableFuture<String>> pending = new ConcurrentHashMap<>();

    public CompletableFuture<String> register(Long sessionId, String requestId) {
        CompletableFuture<String> future = new CompletableFuture<>();
        pending.put(key(sessionId, requestId), future);
        return future;
    }

    public void complete(Long sessionId, String requestId, String result) {
        CompletableFuture<String> future = pending.remove(key(sessionId, requestId));
        if (future != null) {
            future.complete(result);
        }
    }

    public void failAllForSession(Long sessionId) {
        // 会话取消时，清理所有待响应的提问
        pending.entrySet().removeIf(e -> {
            if (e.getKey().startsWith(sessionId + ":")) {
                e.getValue().complete("{\"error\": \"Session cancelled\"}");
                return true;
            }
            return false;
        });
    }

    private String key(Long sessionId, String requestId) {
        return sessionId + ":" + requestId;
    }
}
```

### 3.4 WebSocket 协议扩展

**新增事件类型**:


| 方向              | type                        | data 字段                              | 说明   |
| --------------- | --------------------------- | ------------------------------------ | ---- |
| Server → Client | `ask_user_questions`        | `{ requestId, questions, metadata }` | 发送提问 |
| Client → Server | `ask_user_questions_result` | `{ requestId, answers }`             | 返回回答 |


**WsEvent 示例 — Server → Client**:

```json
{
  "type": "ask_user_questions",
  "sessionId": 123,
  "data": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "questions": [
      {
        "question": "Which framework should we use for the new module?",
        "header": "Framework",
        "options": [
          { "label": "Vue 3 (Recommended)", "description": "Composition API + TypeScript, matches existing stack" },
          { "label": "React", "description": "Larger ecosystem but different from current codebase" }
        ],
        "multiSelect": false
      }
    ]
  }
}
```

**WsEvent 示例 — Client → Server**:

```json
{
  "type": "ask_user_questions_result",
  "sessionId": 123,
  "data": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "answers": [
      {
        "question": "Which framework should we use for the new module?",
        "selectedLabels": ["Vue 3 (Recommended)"],
        "customInput": null
      }
    ]
  }
}
```

### 3.5 StreamingWsHandler 处理

**文件**: `backend/src/main/java/cn/etarch/mao/session/ws/StreamingWsHandler.java`

在 `handleTextMessage()` 的 switch 分支中新增：

```java
case "ask_user_questions_result" -> handleAskUserQuestionsResult(sessionId, data);
```

`handleAskUserQuestionsResult()` 实现：

1. 从 data 中提取 `requestId` 和 `answers`
2. 将 answers 序列化为 JSON 字符串
3. 调用 `askUserQuestionsRegistry.complete(sessionId, requestId, jsonResult)`

### 3.6 取消处理

在 `StreamingWsHandler.handleCancel()` 中，除了现有的 `localToolSessionRegistry.failAllForUser()` 外，新增：

```java
askUserQuestionsRegistry.failAllForSession(sessionId);
```

确保取消时 AgentLoop 中阻塞的 CompletableFuture 能被释放。

### 3.7 AgentLoop 无感知

AgentLoop 本身**不需要任何改动**。它只看到：

1. `dispatchTool()` 返回了一个 JSON 字符串（用户的回答）
2. 将结果加入 context，继续循环

这与现有工具执行模式完全一致。

### 3.8 ToolResultSummarizer 扩展

**文件**: `backend/src/main/java/cn/etarch/mao/session/util/ToolResultSummarizer.java`

新增对 `ask_user_questions` 的摘要生成：

```java
case "ask_user_questions" -> {
    // 解析 answers，生成类似 "回答了 2 个问题" 的摘要
    yield "回答了 " + answerCount + " 个问题";
}
```

## 4. 桌面端设计

### 4.1 WebSocket 事件路由

**文件**: `desktop/src/composables/useStreamWS.ts`

在 `routeEvent()` 中新增 case：

```typescript
case 'ask_user_questions':
  sessionStore.appendAskQuestion(event.data)
  break
```

**文件**: `desktop/src/stores/session.ts`

新增 store 方法 `appendAskQuestion(data)`：

- 将提问数据存入当前活跃会话的 `pendingQuestions` 队列
- 类似于 `pendingApprovals` 的管理模式

### 4.2 新增 QuestionPanel 组件

**文件**: `desktop/src/components/chat/QuestionPanel.vue`

渲染位置：与 `ApprovalStack` 同级，位于聊天区域底部或消息流中。

**UI 结构**:

```
┌─────────────────────────────────────────────────┐
│  Agent wants to know:                           │
│                                                 │
│  ┌─ Framework ─────────────────────────────┐    │
│  │ Which framework should we use for the   │    │
│  │ new module?                             │    │
│  │                                         │    │
│  │ ○ Vue 3 (Recommended)                   │    │
│  │   Composition API + TypeScript,         │    │
│  │   matches existing stack                │    │
│  │                                         │    │
│  │ ○ React                                 │    │
│  │   Larger ecosystem but different from   │    │
│  │   current codebase                      │    │
│  │                                         │    │
│  │ ┌─ Other ──────────────────────────┐    │    │
│  │ │ Type your own answer...          │    │    │
│  │ └──────────────────────────────────┘    │    │
│  └─────────────────────────────────────────┘    │
│                                                 │
│                              [ Submit ]          │
└─────────────────────────────────────────────────┘
```

**带 Preview 的 side-by-side 布局**:

```
┌──────────────────────────────────────────────────────┐
│  Agent wants to know:                                │
│                                                      │
│  ┌─ Layout ───────────────────┬─ Preview ──────────┐ │
│  │ Which layout approach?     │ ┌────────────────┐ │ │
│  │                            │ │ // mockup code  │ │ │
│  │ ○ Sidebar (Recommended)    │ │ <div class="s"> │ │ │
│  │   Fixed left panel         │ │   <aside/>      │ │ │
│  │                            │ │   <main/>       │ │ │
│  │ ○ Top bar                  │ │ </div>          │ │ │
│  │   Horizontal navigation    │ │                 │ │ │
│  │                            │ └────────────────┘ │ │
│  │ ┌─ Other ──────────────┐   │                    │ │
│  │ │ Type your answer...  │   │                    │ │
│  │ └──────────────────────┘   │                    │ │
│  └────────────────────────────┴────────────────────┘ │
│                                                      │
│                                         [ Submit ]   │
└──────────────────────────────────────────────────────┘
```

**Multi-select 布局**:

```
┌─────────────────────────────────────────────────┐
│  Agent wants to know:                           │
│                                                 │
│  ┌─ Features ──────────────────────────────┐    │
│  │ Which features should we include?       │    │
│  │                                         │    │
│  │ ☑ Dark mode                             │    │
│  │   Toggle between light and dark themes  │    │
│  │                                         │    │
│  │ ☐ i18n support                          │    │
│  │   Multi-language internationalization   │    │
│  │                                         │    │
│  │ ☑ Export to PDF                         │    │
│  │   Generate PDF reports                  │    │
│  │                                         │    │
│  │ ┌─ Other ──────────────────────────┐    │    │
│  │ │ Type your own answer...          │    │    │
│  │ └──────────────────────────────────┘    │    │
│  └─────────────────────────────────────────┘    │
│                                                 │
│                              [ Submit ]          │
└─────────────────────────────────────────────────┘
```

### 4.3 组件接口设计

```typescript
interface QuestionOption {
  label: string
  description: string
  preview?: string
}

interface Question {
  question: string
  header: string
  options: QuestionOption[]
  multiSelect: boolean
}

interface QuestionAnswer {
  question: string
  selectedLabels: string[]
  customInput: string | null
}

interface PendingQuestion {
  requestId: string
  questions: Question[]
  metadata?: Record<string, unknown>
}
```

### 4.4 用户交互逻辑

**单选 (multiSelect: false)**:

- 点击选项切换选中状态（radio 行为）
- 同一问题只能选中一个选项
- "Other" 输入框始终可见，输入文本时自动取消选项选中
- 选中选项时清空 "Other" 输入框
- Submit 按钮在至少选中一个选项或 "Other" 有内容时可用

**多选 (multiSelect: true)**:

- 点击选项切换选中状态（checkbox 行为）
- 可选中多个选项
- "Other" 输入框始终可见
- Submit 按钮在至少选中一个选项或 "Other" 有内容时可用

**Preview 渲染**:

- 仅在单选模式且选项含 preview 时渲染
- 切换到 side-by-side 布局
- 预览内容以 markdown 渲染在 monospace 容器中
- 选中不同选项时，右侧预览跟随切换

### 4.5 回答提交

用户点击 Submit 后：

1. 收集所有问题的回答，构建 `answers` 数组
2. 通过 useStreamWS 发送 `ask_user_questions_result` 事件：
   ```typescript
   ws.send(JSON.stringify({
     type: 'ask_user_questions_result',
     sessionId: activeSessionId,
     data: {
       requestId: pendingQuestion.requestId,
       answers: collectedAnswers
     }
   }))
   ```
3. 从 store 中移除该 pendingQuestion，QuestionPanel 消失

回答不需要以用户消息形式插入消息流。tool_call（包含问题）和 tool_result（包含回答）已完整记录在消息历史中，ToolCallCard 的 Input/Output 区域即可展示问答详情。

### 4.6 与 ApprovalStack 的共存

QuestionPanel 和 ApprovalStack 是独立的交互通道，可以同时存在：

- ApprovalStack 处理工具执行审批（安全机制）
- QuestionPanel 处理 Agent 提问（信息收集）

两者在 UI 上不冲突，各自管理自己的队列。当同时存在时，QuestionPanel 显示在 ApprovalStack 上方（因为提问通常更紧急，需要用户关注）。

## 5. 数据持久化

### 5.1 消息存储

提问和回答作为普通的 tool_call + tool_result 对存储，无需新增表或字段：

- **Assistant 消息**：包含 `tool_call` 记录，toolName = `ask_user_questions`，arguments = 完整的 questions JSON
- **Tool 消息**：role = `TOOL`，toolCallId 关联到上述 tool_call，content = answers JSON

现有消息查询和回放机制自动支持。

### 5.2 历史回放

当用户重新打开会话或刷新页面时：

- 消息从 DB 加载，`ask_user_questions` 的 tool_call 和 tool_result 正常展示在 ToolCallCard 中
- 不会重新弹出 QuestionPanel（那是实时交互组件）

## 6. 边界情况处理

### 6.1 超时

- 默认超时：5 分钟
- 超时后返回 `{"error": "User did not respond within timeout"}`
- LLM 收到超时错误后可自行决定是否重试或换一种方式继续
- 超时时间可通过 application.yml 配置

### 6.2 会话取消

- 用户取消时，`failAllForSession()` 释放所有阻塞的 CompletableFuture
- 返回 `{"error": "Session cancelled"}`
- AgentLoop 检测到取消标志后退出循环

### 6.3 WebSocket 断连

- 客户端断连时，服务端的 CompletableFuture 仍阻塞
- 超时机制作为兜底
- 可选：在 WebSocket close handler 中也触发 failAllForSession

### 6.4 多设备

- 同一用户多设备登录时，`StreamingWsRegistry.send()` 会广播到所有连接
- 任一设备回答即可，先到先得
- 其他设备收到回答后应清除本地的 QuestionPanel

### 6.5 队列消息

- 当 Agent 正在等待用户回答时，新消息应进入队列（与 RUNNING 状态一致）
- 用户回答后 Agent 继续执行，完成后自动消费队列

## 7. 文件变更清单

### 后端


| 文件                                            | 变更类型   | 说明                              |
| --------------------------------------------- | ------ | ------------------------------- |
| `harness/tool/impl/AskUserQuestionsTool.java` | **新增** | 工具定义                            |
| `harness/tool/AskUserQuestionsRegistry.java`  | **新增** | 提问等待注册表                         |
| `harness/tool/ToolDispatcher.java`            | 修改     | 新增 ask_user_questions 路由分支      |
| `session/ws/StreamingWsHandler.java`          | 修改     | 处理 ask_user_questions_result 事件 |
| `session/ws/WsEvent.java`                     | 无变更    | WsEvent 是通用 envelope，无需改        |
| `session/util/ToolResultSummarizer.java`      | 修改     | 新增 ask_user_questions 摘要        |
| `harness/core/AgentLoop.java`                 | 无变更    | 无需感知此工具                         |
| `application.yml`                             | 修改     | 新增超时配置项（可选）                     |


### 桌面端


| 文件                                  | 变更类型   | 说明                        |
| ----------------------------------- | ------ | ------------------------- |
| `components/chat/QuestionPanel.vue` | **新增** | 提问渲染组件                    |
| `composables/useStreamWS.ts`        | 修改     | 路由 ask_user_questions 事件  |
| `stores/session.ts`                 | 修改     | 新增 pendingQuestions 状态和方法 |
| `types/chat.ts`                     | 修改     | 新增 Question 相关类型定义        |
| `composables/useChat.ts`            | 修改     | 提问回答提交逻辑                  |
| `components/chat/MessageBubble.vue` | 可选修改   | 提问工具调用的展示优化               |


### 管理后台

无变更。管理后台不涉及实时对话交互。

## 8. 实施计划

一次性实施落地，包含以下工作项：

**后端**：
1. 新增 `AskUserQuestionsTool` — 工具定义（name、description、inputSchema、outputSchema）
2. 新增 `AskUserQuestionsRegistry` — 提问等待注册表（CompletableFuture 管理）
3. 修改 `ToolDispatcher` — 新增 `ask_user_questions` 路由分支，绕过权限系统直接路由到客户端
4. 修改 `StreamingWsHandler` — 处理 `ask_user_questions_result` 事件 + 取消时 failAll
5. 修改 `ToolResultSummarizer` — 新增 `ask_user_questions` 摘要

**桌面端**：
6. 新增 `QuestionPanel.vue` — 提问渲染组件，支持单选/多选/自由输入/preview side-by-side 布局
7. 修改 `useStreamWS.ts` — 路由 `ask_user_questions` 事件到 store
8. 修改 `session.ts` — 新增 `pendingQuestions` 状态和 `appendAskQuestion` / `removeAskQuestion` 方法
9. 修改 `chat.ts` — 新增 Question 相关 TypeScript 类型定义
10. 修改 `useChat.ts` — 提问回答提交逻辑
11. 修改 `TaskView.vue` — 在聊天区域底部挂载 `QuestionPanel`，与 `ApprovalStack` 同级

**不包含**：压力测试、单元测试、管理后台变更。

## 9. 设计决策记录

| # | 问题 | 决策 |
|---|------|------|
| 1 | 回答是否以用户消息形式插入消息流？ | **否**。tool_call + tool_result 已包含完整问答，无需额外插入用户消息 |
| 2 | 是否限制提问频率？ | **不限制**。LLM 可在一轮对话中多次调用此工具 |
| 3 | QuestionPanel 的位置？ | **固定在聊天区域底部**（类似 ApprovalStack），长对话时不会被滚动出视野 |
| 4 | "Other" 输入是否需要非空校验？ | **是**。选中 "Other" 但未输入内容时，Submit 按钮禁用 |