人机协作（HITL）

wesclaw 内置人在回路（Human-in-the-Loop）机制，让你在关键时刻参与 AI 决策。

什么是 HITL

HITL 是 AI 在需要人类参与时的交互机制。当 AI 遇到不确定、危险或需要确认的操作时，会暂停执行并请求你的输入。

三种触发场景

场景触发条件说明
主动询问Agent 调用 ask_user 工具AI 需要你提供信息或做出选择
浏览器等待需要用户在浏览器中操作如登录、验证码等
循环检测CycleDetector 发现死循环AI 陷入重复操作，需要指导

主动询问

ask_user 工具

AI 在以下情况主动询问：

用户："部署到生产环境"

AI：我即将执行以下操作，需要你确认：
  1. 停止当前服务
  2. 备份数据库
  3. 部署新版本
  4. 重启服务
  
  是否继续？[确认/取消]

典型场景

场景AI 询问内容
危险操作"即将删除文件，是否继续？"
多方案选择"有 A/B/C 三种方案，你倾向哪种？"
信息缺失"需要数据库连接地址"
歧义消除"你说的 X 是指 A 还是 B？"

浏览器等待

browser_wait_for_user

当 AI 操作浏览器遇到需要人工操作时：

AI 打开登录页面
  → 需要你输入账号密码
  → AI 暂停等待
  → 你完成操作后通知 AI
  → AI 继续后续操作

AlwaysOn 安全阀

browser_wait_for_user 是 Cell 启动时无条件注册的安全阀：

循环检测

CycleDetector HITL

当 AI 陷入重复操作时：

  1. 首次触发：注入纠正消息，重置计数器
  2. 再次触发：HITL 询问用户
AI 检测到死循环：
  相同的操作已执行 7 次，结果相同。

  选项：
  1. 继续尝试（提供新的方向）
  2. 跳过这个步骤
  3. 终止任务

超时处理

前端交互

审批提示

HITL 请求通过 SSE 推送到前端：

响应方式

操作效果
确认AI 继续执行
拒绝AI 取消当前操作
提供信息AI 使用你的输入继续
超时AI 自动终止

与治理的关系

治理链不产生 HITL

重要区别：

两个独立系统

危险命令（rm -rf /）
  → Hardline 直接拒绝
  → 不经过 HITL

AI 需要确认（"要删除这个文件吗？"）
  → Agent 调用 ask_user
  → HITL 弹出审批

注意事项