Clarify Tool 澄清工具

概述

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

Schema 定义

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 交互，采用纯文本 + 数字映射方案：

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

WebSocket 协议

// 服务端 → 客户端
{ 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 — 工具系统总览

2.8 KiB Raw Blame History Unescape Escape

Clarify Tool 澄清工具

概述

Schema 定义

数据流

核心文件

微信渠道降级

WebSocket 协议

关联页面

2.8 KiB

Raw Blame History