CMDC.Plugin.Builtin.HumanApproval (cmdc v0.5.1)

Copy Markdown View Source

P0 人类审批插件 — 高风险工具执行前等待人类确认(HITL)。

拦截 before_tool 事件,对指定工具(默认 "shell")的非白名单命令 广播 {:approval_required, approval_map} 事件并阻止工具执行。

审批信息直接以 map 形式内嵌在事件 payload 中,无需独立 struct:

%{
  id: "a1b2c3d4",
  tool: "shell",
  args: %{"command" => "rm /tmp/test"},
  session_id: "...",
  hint: "请回复「确认执行:rm /tmp/test」...",
  requested_at: 1_700_000_000_000
}

两种审批模式(共存)

模式 A — 外部 API 审批(管理后台推荐)

HumanApproval 拦截 {:before_tool, "shell", args}
      广播 {:approval_required, approval_map}
      block_tool  Agent 回到 idle
    
外部系统收到事件管理员审批
    
 Pipeline 发送 {:tool_approved, approval_id} 事件
     放行  命令进入 pending_approvals下次 before_tool 自动通过

模式 B — 用户 re-prompt 审批(Bot 对话场景)

用户: "帮我删除 /tmp/test"
      block_toolhint 提示用户回复确认前缀
    
用户: "确认执行:rm /tmp/test"
      before_prompt 识别 confirm_prefix  命令进入 pending_approvals
      下次 before_tool 自动放行

配置

{CMDC.Plugin.Builtin.HumanApproval,
  require_approval_for: ["shell"],     # 需要审批的工具名列表
  safe_commands: [                     # 免审批命令(正则或字符串前缀)
    ~r/^curl\s/,
    ~r/^ls(\s|$)/,
    ~r/^pwd$/,
    "echo "
  ],
  confirm_prefix: "确认执行:",         # 模式 B 的确认前缀
  timeout_ms: 120_000                  # 审批超时(默认 2 分钟,0 表示不超时)
}