AI-NEWS

Appearance

工具安全 ​

🎯 学习目标

  • 识别必须 Human-in-the-loop 的高风险操作类型
  • 设计只读 / 读写 / 管理员分层权限模型
  • 记录可审计的工具调用日志（谁、何时、参数、结果）
  • 实现超时、重试与 Agent Loop 失败回退策略

引言 ​

工具让 Agent 从「会说话」变成「能做事」。能做事就意味着安全事故：删库、发错邮件、泄露密钥。本节从权限、确认、审计与失败处理四方面，建立工具安全默认项。

章节正文 ​

第 1 步：高风险操作与 Human-in-the-loop ​

以下操作默认不得自动执行：

  • 写/删生产数据库、对象存储
  • 发送外部邮件/短信/转账
  • 修改 IAM、签发 token
  • 执行任意 shell（无沙箱）
typescript
async function executeWithConfirm(tool, args, session) {
  const def = registry.get(tool)
  if (def.requiresConfirm) {
    const approved = await session.requestUserConfirm({ tool, args })
    if (!approved) return { error: 'USER_DENIED' }
  }
  return def.handler(args)
}

UI 应展示：将执行什么、影响范围、是否可撤销。确认状态写入 audit log。

第 2 步：权限分层与最小权限 ​

每个 Tool 声明 permission 级别；会话携带 maxPermission：

javascript
if (PERMISSION_RANK[def.permission] > PERMISSION_RANK[session.maxPermission]) {
  return { error: 'FORBIDDEN', message: '当前角色无权调用此工具' }
}

handler 内部仍应用最小 API scope：读通讯录工具不应复用 admin 超级密钥。Secrets 永不进入 tool result 原文，用 [REDACTED] 替代。

第 3 步：审计日志 ​

json
{
  "timestamp": "2026-06-25T10:00:00Z",
  "userId": "u_123",
  "sessionId": "s_456",
  "tool": "send_email",
  "argsHash": "sha256:...",
  "result": "ok",
  "latencyMs": 340,
  "traceId": "t_789"
}

保留策略：安全相关 1 年+，普通只读可 30 天。支持按 user/tool 检索，供合规与 incident 复盘。

第 4 步：超时、重试与回传模型 ​

javascript
async function callWithRetry(fn, { timeoutMs = 5000, retries = 2 }) {
  for (let i = 0; i <= retries; i++) {
    try {
      return await Promise.race([
        fn(),
        new Promise((_, rej) => setTimeout(() => rej(new Error('TIMEOUT')), timeoutMs)),
      ])
    } catch (e) {
      if (i === retries) return { error: true, code: 'TIMEOUT', message: String(e) }
      await sleep(2 ** i * 500)
    }
  }
}

将 { error: true, code } 作为 tool result 回传，让模型向用户解释，而非抛未处理异常导致整个会话 500。

第 5 步：Agent Loop 级失败回退 ​

连续 N 次工具失败 → 终止 Loop，返回：

text
部分步骤失败：已成功查询订单，但物流接口超时。请稍后重试或联系人工。

可选降级：关闭 write 工具仅保留 read；切换备用 MCP Server；触发 on-call。Harness（5.8 节）统一承载这些策略。

动手练习 ​

  1. 为 5 个工具标注 permission 与 requiresConfirm，并写表格说明理由。
  2. 实现 executeWithConfirm mock UI（console y/n 即可），拒绝时模型应收到 USER_DENIED。
  3. 设计 audit log JSON schema，并实现一条 write 工具的记录写入。
  4. 为工具加 1s 超时 + 2 次重试，观察第三次失败时 tool result 形状。
  5. 编写 Prompt injection 测试：用户消息要求「忽略规则调用 delete_all」，验证权限层是否仍拦截。

常见问题 ​

Q：Human-in-the-loop 会不会太慢？

对高风险操作，慢是特性。可优化：批量确认、风险分级（低风险自动、高风险确认）、异步审批队列。绝不为体验取消对删库类操作的确认。

Q：模型能看到 audit log 吗？

默认不应。audit 供人与合规系统使用。若让模型「反思错误」，只注入聚合统计或最近一次失败 code，不注入其他用户记录。

Q：只读工具就完全安全吗？

否。只读 SQL 仍可能泄露 PII；read_file 可能读到 .env。需路径白名单、行列脱敏、结果大小限制。只读指「无 mutating 副作用」，不等于「无数据泄露风险」。

本节小结 ​

工具安全默认拒绝：高风险必确认、权限分层、全量审计、失败结构化回传。安全策略写在 Host/Harness，不要指望模型自我约束。