ToolApprovalCard 工具审批
工具调用的确认卡:参数完整可查、允许与拒绝一步直提、多项横向翻页
ToolApprovalCard 展示 useChat().approvals 中的一项待办审批;ToolApprovalGroup 把多项
折成一张卡横向翻页。组件只处理交互,查询与提交由 hooks 完成,server 按 Provider 最新状态再次校验。
import { ToolApprovalCard, ToolApprovalGroup } from "@openagentpack/kit-chat-ui";copy-in 接入(复制后 import 改为项目内路径):
pnpm kit:add tool-approvalcopy-in 只复制组件源码,本组件没有额外 npm 依赖。交给 coding agent 接入时使用 kit-components Skill;主题与渲染依赖见 组件总览。
何时使用
- Agent 请求执行工具且需要人确认时(HITL):卡片经
Chat的approvals插槽内嵌到消息流 末尾,完整参数展开可查后一步允许或拒绝;输入区上方只保留一条「等待审批」的精简提示。 - 同批出现多个待审批时用
ToolApprovalGroup:一次只显示一张卡,处理完自动切到剩余待审批, 各 call 分别确认,不提供隐式「全部批准」。
代码演示
预览使用本地状态模拟,不连接服务;演示面板内可查看源码与接入命令。
基本用法
允许与拒绝一步直提,不弹确认窗(完整参数已可见);提交中按钮进入 busy,成功后卡片只显示状态。
提交失败与恢复
onDecision 抛错时卡片显示错误行并保持可重试;结果不明或已失效时提供安静的刷新入口,
连接恢复不会自动重发允许或拒绝。信息不完整或类型不受支持的卡仅供查看,保留「停止执行」。
多项审批翻页
ToolApprovalGroup 一次只渲染一张卡,用 ‹ 1/2 › 翻页;当前项处理完成后自动切到剩余的
待审批,手动翻页的选择始终保留。
API
ToolApprovalCard
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
approval | 当前请求、实际参数、可操作性与状态,来自 hooks | ChatToolApproval | 必填 |
onDecision | 提交允许或拒绝;失败显示错误行并保持可重试 | (decision: ToolApprovalDecision) => Promise<void> | 必填 |
onRefresh | 重新查询审批结果与有效待办 | () => Promise<void> | 必填 |
onStop | 中断整个执行,独立于拒绝单个工具;仅在卡片不可操作时显示「停止执行」 | () => void | — |
actionable 且 status === "pending" 时可操作:允许与拒绝都是一步直提,busy 态防重复点击;
submitting / submitted 只显示状态、不出按钮。uncertain 与 stale 显示刷新入口,
由调用方重新查询后确认结果。等待审批时输入区保持可编辑(Sender 的
submitDisabled={!chat.canSend})。
ToolApprovalGroup
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
approvals | 待审批列表,来自 hooks | ChatToolApproval[] | 必填 |
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 |
status | hooks 推导的状态: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。更多主题配置见
组件总览。