进阶第 7 章：工具 UI 与批准

业务问题

AI 编码助手会修改文件、执行命令。客服 Agent 会查询或修改订单。前端必须让用户看清工具做了什么，并能批准或拒绝高风险操作。

交互图解：工具执行、权限与批准流程 · 查看图解导读

核心原理

工具调用不应只显示一个 JSON。应根据工具意图选择 UI：

• generic：通用调用。
• terminal：命令输出。
• diff：文件变更。
• read：文件阅读。
• search：搜索结果。
• web：网络检索。

执行前策略：

• allow：直接执行。
• deny：拒绝并解释。
• ask：请求用户批准。

真实项目中的映射

编码助手工具 UI：

• 读取文件显示行号。
• 编辑文件显示 diff。
• 执行命令显示终端输出和退出码。

客服 Agent 工具 UI：

• 查询订单显示结构化字段。
• 修改订单显示变更前后。
• 高风险操作显示批准卡片。

DeepSeek Harness 对应实现

DeepSeek Harness 中，工具的 presentCall 和 presentResult 返回 render intent，例如 generic、terminal、diff、read、search、web。

tools/pre-execute 可以返回 allow、deny 或 ask。ask 需要 approval 服务。

进一步阅读：

• packages/core/tools/src/presentation.ts
• docs/subsystems/approval.md

代码示例

type ToolApproval = {
  toolName: string
  summary: string
  risk: 'low' | 'medium' | 'high'
}

function ApprovalCard({
  approval,
  onApprove,
  onDeny,
}: {
  approval: ToolApproval
  onApprove(): void
  onDeny(): void
}) {
  return (
    <section>
      <strong>{approval.toolName}</strong>
      <p>{approval.summary}</p>
      <span>风险：{approval.risk}</span>
      <button onClick={onApprove}>允许</button>
      <button onClick={onDeny}>拒绝</button>
    </section>
  )
}

真实产品还要处理超时、后端拒绝和权限变更。

面试追问

问：为什么工具 UI 不能只显示 JSON？

回答要点：

• JSON 不直观。
• 文件 diff、命令输出、搜索结果需要不同展示。
• 用户需要快速判断是否批准。

问：allow、deny、ask 如何选择？

回答要点：

• 低风险可逆操作用 allow。
• 明确禁止的危险操作用 deny。
• 有影响但可接受的操作用 ask。

问：前端批准后，后端为什么还要校验？

回答要点：

• 前端请求可被伪造。
• 权限可能已变化。
• 后端是最终安全边界。

实践任务

为“写文件”和“执行命令”设计工具视图和批准卡片，并写出用户批准后的事件流。

验收标准

• 能列举常见工具 render intent。
• 能设计 allow/deny/ask UI。
• 能解释后端再次校验的必要性。