OpenAgentPack Kit
组件反馈

ToolApprovalCard 工具审批

工具调用的确认卡:参数完整可查、允许与拒绝一步直提、多项横向翻页

ToolApprovalCard 展示 useChat().approvals 中的一项待办审批;ToolApprovalGroup 把多项 折成一张卡横向翻页。组件只处理交互,查询与提交由 hooks 完成,server 按 Provider 最新状态再次校验。

import { ToolApprovalCard, ToolApprovalGroup } from "@openagentpack/kit-chat-ui";

copy-in 接入(复制后 import 改为项目内路径):

pnpm kit:add tool-approval

copy-in 只复制组件源码,本组件没有额外 npm 依赖。交给 coding agent 接入时使用 kit-components Skill;主题与渲染依赖见 组件总览。

何时使用

  • Agent 请求执行工具且需要人确认时(HITL):卡片经 Chat 的 approvals 插槽内嵌到消息流 末尾,完整参数展开可查后一步允许或拒绝;输入区上方只保留一条「等待审批」的精简提示。
  • 同批出现多个待审批时用 ToolApprovalGroup:一次只显示一张卡,处理完自动切到剩余待审批, 各 call 分别确认,不提供隐式「全部批准」。

代码演示

预览使用本地状态模拟,不连接服务;演示面板内可查看源码与接入命令。

基本用法

允许与拒绝一步直提,不弹确认窗(完整参数已可见);提交中按钮进入 busy,成功后卡片只显示状态。

ToolApprovalCard(允许与拒绝)

提交失败与恢复

onDecision 抛错时卡片显示错误行并保持可重试;结果不明或已失效时提供安静的刷新入口, 连接恢复不会自动重发允许或拒绝。信息不完整或类型不受支持的卡仅供查看,保留「停止执行」。

ToolApprovalCard(异常与恢复)

多项审批翻页

ToolApprovalGroup 一次只渲染一张卡,用 ‹ 1/2 › 翻页;当前项处理完成后自动切到剩余的 待审批,手动翻页的选择始终保留。

ToolApprovalGroup(多项审批翻页)

API

ToolApprovalCard

属性说明类型默认值
approval当前请求、实际参数、可操作性与状态,来自 hooksChatToolApproval必填
onDecision提交允许或拒绝;失败显示错误行并保持可重试(decision: ToolApprovalDecision) => Promise<void>必填
onRefresh重新查询审批结果与有效待办() => Promise<void>必填
onStop中断整个执行,独立于拒绝单个工具;仅在卡片不可操作时显示「停止执行」() => void—

actionable 且 status === "pending" 时可操作:允许与拒绝都是一步直提,busy 态防重复点击; submitting / submitted 只显示状态、不出按钮。uncertain 与 stale 显示刷新入口, 由调用方重新查询后确认结果。等待审批时输入区保持可编辑(Sender 的 submitDisabled={!chat.canSend})。

ToolApprovalGroup

属性说明类型默认值
approvals待审批列表,来自 hooksChatToolApproval[]必填
onDecision透传给当前卡片同 ToolApprovalCard必填
onRefresh透传给当前卡片同 ToolApprovalCard必填
onStop透传给当前卡片同 ToolApprovalCard—

默认显示第一个 pending 的待审批;翻页器只在多于一项时出现,用 batch_id:call_id 定位当前卡。

ChatToolApproval

属性说明类型
batch_id / call_id审批批次与调用标识,提交决策时原样回传string
request_event_id原审批请求的事件 id;线程归属由服务端从该请求事件读取string | null
name工具名,卡片标题展示string
arguments实际参数,完整 JSON 原文可展开核对unknown
tool_type工具类型标记,卡片右上角展示string
server_label工具来源标记string
session_thread_id请求所属线程string
actionable是否可操作;false 时卡片仅供查看boolean
statushooks 推导的状态:pending 可操作,submitting / submitted 只读,uncertain / stale 提供刷新"pending" | "submitting" | "submitted" | "uncertain" | "stale"
result已处理项的最终结果"allow" | "deny"

ToolApprovalDecision

属性说明类型
batch_id / call_id目标待办标识string
result允许或拒绝"allow" | "deny"
deny_message拒绝原因,最长 200 字符string

底层 API 为 GET/POST /api/kit/sessions/:id/tool-approvals:POST 仅批准已存在的当前待办, 不能借此创建新调用;越权返回 404,过期或重复返回 409。提交后由服务端按 Provider 最新状态 再次校验归属、当前待办与重复响应。参数与工具输出以文本展示,不作为 HTML 执行。

主题变量(Design Token)

引入 @openagentpack/kit-chat-ui/theme.css 后使用以下冻结 token。下表列出亮色值, 暗色由 data-kit-theme="dark" 使用对应色板。

Token用途默认主题工作区主题
--kit-warning-fg标题左侧警示图标#b45309#805917
--kit-border卡片与类型标记描边、参数展开区分隔线#e3e6ef#e5e5e5
--kit-surface卡片底色#ffffff#ffffff
--kit-bg-subtle参数摘要条底色、翻页按钮悬停底色#f6f7fb#f7f7f7
--kit-accent「允许」按钮底色#4f46e5#171717
--kit-accent-fg「允许」按钮文字#ffffff#ffffff
--kit-danger提交失败错误行#dc2626#ad372f
--kit-fg-muted状态文字、参数摘要、恢复与翻页按钮#5b6478#737373

圆角走 --kit-radius / --kit-radius-sm,卡片入场与参数展开分别用 --kit-animate-in / --kit-animate-expand;键盘焦点环用 --kit-focus, 文字档位为 --kit-text-label / --kit-text-caption。更多主题配置见 组件总览。

本页目录