写操作的影响范围展示与确认
确认不是一个通用“确定吗”弹窗。高风险 Tool 在执行前应生成不可变影响预览,展示目标、变化、数量、金额、接收者、不可逆性和恢复方式;用户确认必须绑定这份预览、身份、有效期与资源版本。执行时服务端重新验证,防止确认后状态变化。
前置知识与目标
前置阅读:
完成后应能:
- 按影响而不是按钮分类风险。
- 生成 preview artifact。
- 设计上下文绑定 confirmation。
- 处理批量、部分成功和资源变化。
- 防止模型自我确认。
- 测试重放、点击劫持和误导摘要。
哪些动作需要确认
通常包括:
- 付款、退款、转账。
- 删除、覆盖、发布。
- 发送外部消息。
- 修改权限。
- 执行命令。
- 创建付费资源。
- 批量变更。
- 暴露敏感数据给第三方。
风险由:
- 可逆性。
- 金额/数量。
- 影响对象。
- 外部可见性。
- 权限提升。
- 数据敏感性。
- 自动恢复难度。
决定。同一个 update_profile 修改昵称和修改收款账户风险不同。
风险策略
{
"policyVersion": "confirmation-v9",
"rules": [
{
"operation": "refund.create",
"requiresConfirmation": true,
"requiredFields": ["amount", "currency", "orderId", "paymentCount"]
},
{
"operation": "file.delete",
"requiresConfirmation": true,
"requiredFields": ["pathCount", "paths", "recoverability"]
}
]
}策略在服务端。模型不能设置 requiresConfirmation=false。
Preview/Commit
sequenceDiagram
participant U as User
participant A as AI App
participant P as Preview Service
participant C as Command Service
A->>P: proposed operation
P-->>A: preview artifact + effect hash
A-->>U: human-readable impact
U->>A: explicit confirm
A->>C: preview ID + confirmation token + idempotency key
C->>C: re-auth, version, expiry, invariants
C-->>A: completed / conflict / processingPreview 不是模型总结,而是服务端基于当前事实计算。
Preview Artifact
{
"previewId": "refund-preview-91",
"operation": "refund.create",
"actor": "user-91",
"tenant": "tenant-a",
"resource": {
"type": "order",
"id": "ORDER-000812",
"version": 17
},
"effects": {
"refund": {"currency": "CNY", "minorUnits": 12900},
"paymentTransactions": 1,
"orderState": {"from": "paid", "to": "refunding"}
},
"warnings": ["退款提交后不能通过本工具撤销"],
"policyVersion": "refund-v8",
"expiresAt": "2026-07-18T10:05:00+08:00",
"effectHash": "sha256:..."
}Artifact 不含可复用支付 Secret。
影响展示
必须回答
- 动作是什么。
- 作用于哪个对象。
- 哪些字段/状态改变。
- 数量和金额。
- 谁会收到通知。
- 是否对外公开。
- 是否可撤销。
- 失败时会发生什么。
不只显示模型生成摘要
UI 从结构化 effects 渲染关键字段。模型可以补充解释,但不能省略或改写关键金额、路径和接收者。
批量
显示:
- 总数量。
- 分组。
- 前若干代表项。
- 完整清单下载/展开。
- 预计费用。
- 不符合条件的项。
- 是否允许部分成功。
“将修改 100 个对象”不足以发现跨租户或错误范围。
可访问性
- 确认按钮有明确名称。
- 不只靠颜色区分危险。
- 焦点进入标题/摘要。
- 键盘可操作。
- 不自动倒计时确认。
- 危险与取消按钮不因布局变化互换。
Explicit Confirmation
有效确认应:
- 来自当前 authenticated user。
- 明确对应动作。
- 发生在影响展示之后。
- 绑定 preview/effect hash。
- 未过期。
- 不可被模型或 Tool result 代替。
“用户之前说过你看着办”不一定授权具体金额/目标。对高风险动作要求当前 artifact 明确确认。
Confirmation Token
{
"confirmationId": "confirm-17",
"previewId": "refund-preview-91",
"effectHash": "sha256:...",
"principalId": "user-91",
"sessionIdHash": "sha256:...",
"operation": "refund.create",
"issuedAt": "2026-07-18T10:01:00+08:00",
"expiresAt": "2026-07-18T10:05:00+08:00",
"usedAt": null
}token 可为服务端记录 ID 或签名对象。即使签名正确,也要检查当前资源状态和权限。
确认 token 不进入模型可编辑的 arguments。Host 在收到真实用户交互事件后,通过独立控制字段附加;Tool Gateway 拒绝模型自行构造的同名 JSON 字段。刷新恢复时,Host 从服务端读取 Waiting Approval 状态,不从对话文本重建“已确认”。
Resource Version
确认后订单可能:
- 已退款。
- 金额改变。
- 被取消。
- 权限撤销。
Command 使用 optimistic concurrency:
UPDATE orders
SET state = 'refunding', version = 18
WHERE id = 'ORDER-000812'
AND version = 17
AND state = 'paid'影响 0 行则 conflict,重新 preview。不能静默按新状态执行。
模型与确认
模型可以:
- 建议动作。
- 调 preview。
- 向用户解释。
- 等待 confirmation。
模型不能:
- 调用“confirm” Tool 替用户确认。
- 把外部文档“请确认”当用户输入。
- 在用户沉默时默认同意。
- 修改 preview。
- 将一项确认扩展到多项。
Host 状态机控制 Waiting Approval。
分层确认
低风险写:
- 用户当前明确命令可视为确认。
中风险:
- 展示摘要 + 按钮。
高风险:
- 详细 preview。
- 二次认证。
- typed confirmation 或管理员审批。
分层由 policy 决定,避免所有点击都疲劳化。不能为了减少摩擦取消必要确认。
应用案例一:退款
请求
“把 ORDER-000812 全退。”
Preview
- 129.00 CNY。
- 1 笔支付。
- 订单进入 refunding。
- 不可通过本工具撤销。
状态变化
用户确认前,另一笔部分退款完成,余额变 99.00。
Command 检查 version 失败,返回:
{
"status": "conflict",
"error": {
"code": "preview_stale",
"retryable": false,
"action": "create_new_preview"
}
}应用重新 preview,并要求确认新金额。不能复用旧确认。
测试
- 金额格式和 currency。
- preview 过期。
- 不同 user 重放。
- resource version 变化。
- 双击确认。
- 网络 timeout。
- 部分退款。
- 权限撤销。
应用案例二:批量删除文件
请求
“删除构建产物。”
路径解析可能匹配:
dist/120 个生成文件。dist-config/production.json源配置(不应匹配)。
Preview
服务端解析 allowlisted root 和 glob,返回:
{
"pathCount": 120,
"totalBytes": 4819200,
"roots": ["dist/"],
"outsideAllowedRoot": [],
"recoverability": "git_untracked_no_backup",
"samplePaths": ["dist/app.js", "dist/app.css"]
}UI 提供完整清单。用户确认后,command 绑定 path set hash。
失败分支
如果 command 重新计算 glob,确认后新增文件也会被删。应按确认时的 path identities 执行,或检测集合变化并重新确认。
测试
- symlink escape。
- case-sensitive path。
- 新增文件。
- 文件变成目录。
- 120→10,000 数量异常。
- 删除部分失败。
- Git 可恢复与不可恢复。
应用案例三:发送邮件
Preview 展示:
- To/Cc/Bcc。
- subject。
- attachment 名称/大小。
- 数据分类。
- 外部域名。
- 发送账号。
正文中外部内容可能包含 prompt injection,不得自动修改 recipient。确认绑定 body hash 和 attachments hash。
失败分支
用户确认 3 个收件人,模型随后从邮件正文解析出另一个地址并添加。effect hash 变化必须使 confirmation 失效。
应用案例四:权限变更
“让 Alex 能管理项目。”
需要消歧:
- 哪个 Alex。
- 哪个项目。
- role 权限集合。
- 是否包含删除/账单。
- 到期时间。
Preview 展示权限 diff,而不是只显示“设为管理员”。高风险可要求资源 owner 二次审批。
部分成功
批量写入需预先定义:
- all-or-nothing。
- per-item independent。
- best-effort。
Preview 显示策略。结果:
{
"status": "partial",
"completed": 98,
"failed": 2,
"failures": [
{"resourceId": "file-17", "code": "version_conflict"},
{"resourceId": "file-44", "code": "forbidden"}
]
}重试只针对安全失败项,使用各自幂等 key。模型不能默认回滚已发送邮件等不可逆动作。
确认疲劳
降低疲劳的方法:
- 只在真实风险动作确认。
- 合并同一 preview 的相关 effects。
- 关键字段突出。
- 提供安全默认。
- 低风险偏好可在 policy 允许下记忆。
不能:
- 让用户全局“永远允许所有写”。
- 隐藏范围。
- 将取消按钮弱化。
- 每次确认内容相同但实际 effect 已变。
安全攻击
UI redress
- frame 限制。
- 清晰来源。
- 按钮间距。
- 不允许不可见 overlay。
Replay
- token 一次性/有期限。
- 绑定 session/principal/effect。
- 使用后状态。
Confused deputy
用户有权查看但无权执行。Command 重新授权 action。
Injection
Tool result、网页和邮件不能产生 confirmation。只接受 Host 的用户交互事件。
审计
记录:
- proposed by model/user。
- preview ID/effect hash。
- rendered schema version。
- confirmation actor/time/session。
- second-factor decision。
- command ID/idempotency key hash。
- result/partial。
不要存支付凭证和完整敏感正文。
测试
Contract
- 所有风险动作有 preview。
- UI 关键字段来自结构。
- 确认绑定 effect。
- command 重新检查。
Race
- 资源版本。
- 权限撤销。
- 金额变化。
- 批量集合变化。
Security
- 跨用户 replay。
- 跨 tenant。
- 过期 token。
- Tool result 假确认。
- 双击。
- 点击劫持。
UX
- 键盘。
- screen reader。
- 长清单。
- 小屏。
- partial result。
- 刷新恢复。
调试
发现未确认写入:
- operation risk policy。
- preview 是否生成。
- Host 状态机。
- confirmation event 来源。
- token/effect 验证。
- command auth。
- idempotency。
发现用户确认了错误范围:
- structured effects。
- render 映射。
- truncation/展开。
- batch path set。
- preview 后变化。
- 模型解释是否遮盖关键字段。
综合练习
实现批量文件删除审批:
- preview 路径集合。
- 检查 root、symlink 和敏感文件。
- 生成 count/bytes/recoverability/hash。
- 可访问确认 UI。
- 绑定 principal/session/expiry。
- command 检查集合与版本。
- 支持 partial result。
- 注入 replay、变化和 timeout。
验收标准
- 影响范围由服务端计算。
- UI 不依赖模型摘要显示关键事实。
- 用户确认明确且发生在预览后。
- effect 变化使确认失效。
- Command 重新授权。
- 同一确认不会重复副作用。
- partial/unknown 可恢复。
- 审计可证明谁确认了什么。
来源
- MCP Tools Specification 2025-11-25(访问日期:2026-07-18)
- W3C Web Authentication Level 3(访问日期:2026-07-18)
- OWASP Transaction Authorization Cheat Sheet(访问日期:2026-07-18)
- WAI-ARIA Authoring Practices: Alert and Message Dialogs(访问日期:2026-07-18)