81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
|
---
|
|||
|
|
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]] — 工具系统总览
|