---
title: Clarify Tool 澄清工具
created: 2026-04-16
updated: 2026-04-16
type: entity
tags: [tool, agent, websocket]
sources: [packages/backend/src/modules/netaclaw/tools/builtin/clarify.ts, packages/backend/src/modules/netaclaw/runtime/attempt.ts, packages/backend/src/modules/netaclaw/gateway/server.ts, packages/frontend/src/modules/agent/components/clarify-card.vue]
---

# Clarify Tool 澄清工具

## 概述

Agent 在 ReAct 循环中向用户提出澄清问题的交互工具。支持选择题（最多4项）和开放式问题。通过 Promise 阻塞 Agent 执行，等待用户回答后继续。注册在 [[tool-catalog]] 的 `interaction` 工具集。

## Schema 定义

```typescript
const ClarifyParams = Type.Object({
  question: Type.String({ description: '要问用户的问题' }),
  choices: Type.Optional(Type.Array(Type.String(), {
    maxItems: 4, description: '预设选项（最多4个）'
  })),
});
```

## 数据流

```
Agent 调用 clarify → attempt.ts 检测 → onClarifyRequest 回调
    ↓
WebSocket 网关: 生成 requestId → clarifyResolvers.set() → 发送 clarify_request
    ↓
前端 Store: 创建 role='clarify' 消息 → 渲染 clarify-card 组件
    ↓
用户点击选项/输入回答 → sendClarifyResponse() → 发送 clarify_response
    ↓
WebSocket 网关: clarifyResolvers.get(requestId).resolve(answer)
    ↓
Agent 继续 ReAct 循环
```

## 核心文件

| 文件 | 职责 |
|------|------|
| `tools/builtin/clarify.ts` | 工具定义 + Schema |
| `runtime/attempt.ts:72-93` | 特殊处理：检测 clarify 调用，触发回调 |
| `gateway/server.ts:263-269` | 生成 requestId，Promise 阻塞，转发 WS 事件 |
| `gateway/protocol.ts:132-136` | `clarify_request` / `clarify_response` 协议定义 |
| `前端 store/chat.ts:248-258` | 接收事件，创建 clarify 消息 |
| `前端 components/clarify-card.vue` | 渲染问题+选项按钮+自定义输入 |
| `service/agent_channel.ts:347-384` | 微信渠道纯文本降级 |

## 微信渠道降级

微信不支持 WebSocket 交互，采用**纯文本 + 数字映射**方案：

1. 构造文本消息：`❓ 问题\n1. 选项1\n2. 选项2\n请回复数字或直接输入`
2. 通过微信 API 发送，存入 `pendingClarify` Map
3. 用户回复数字 → 映射到 `choices[num-1]`；回复文本 → 直接使用
4. 解决 Promise，Agent 继续

## WebSocket 协议

```typescript
// 服务端 → 客户端
{ type: 'clarify_request', sessionId, data: { requestId, question, choices? } }

// 客户端 → 服务端
{ type: 'clarify_response', sessionId, requestId, answer }
```

## 关联页面

- [[tool-catalog]] — 工具目录（interaction 工具集）
- [[agent-runtime]] — ReAct 循环中的 clarify 回调
- [[websocket-gateway]] — clarify 事件转发
- [[agent-channel]] — 微信渠道降级实现
- [[tool-system]] — 工具系统总览