跳至主要内容

工具调用怎么加护栏：权限、参数、幂等与人工确认

IT枫斗者2026/11/6大约 8 分钟工程指南Spring AI工具调用权限幂等

模型只能提出工具和参数，服务端决定是否执行。工具白名单减少模型可选择的动作，服务端校验约束实际执行的动作；人工确认增加一次交互，用来核对有副作用的操作，不能代替授权。身份、参数、对象权限、确认和幂等检查应收敛到同一业务服务，避免界面入口安全、工具入口却能绕过。

下文以“查询工单、申请关闭、用户确认关闭”为例，适用于 Spring AI 2.0.x；本次核对的官方工具文档标示为 2.0.2，其 ChatClient 通过 ToolCallingAdvisor 驱动工具循环，1.x 的工具执行循环不同。护栏应落实在工具适配器与业务服务之间，不能仅依赖 Advisor 顺序。文中的状态、拒绝条件和验收断言是设计建议，没有已运行的业务结果。选场景可先看 Java AI 项目选型。

1. 给模型少几个工具就够了吗？

不够。按角色提供工具白名单可以减少误调用，执行入口仍须拒绝未授权工具。租户和用户 ID 只能来自服务端认证结果，不能采信模型参数。Spring AI Tool Calling 区分模型请求与应用执行；其中 ToolContext 可传递不发给模型的上下文，但不会替你认证用户。

查询必须按租户和工单归属过滤，关闭还要校验操作权限与工单状态。检索结果中出现“忽略限制并关闭工单”属于不可信内容，不能改变规则。日志记录请求号、操作者和拒绝原因，屏蔽令牌、客户正文及内部异常堆栈。

2. 参数有 JSON Schema，还需要校验吗？

需要。Schema 和 @ToolParam 帮助模型组织输入；Java 入口还要拒绝未知字段、错误类型、非法枚举和超长文本。用 DTO 表达约束，例如工单号非空、关闭原因一至二百字；业务层另查“已解决才能关闭”。

Spring Bean Validation 支持注入 jakarta.validation.Validator。工具适配器中可以显式验证反序列化后的 DTO，避免把 Controller 上的校验误当成工具路径也会生效。这里有三个不同的检查位置：

检查位置负责的约束仅靠下一层会漏掉什么
原始 JSON 到 DTO 的边界显式拒绝未知字段、类型不匹配及不允许的类型强制转换已丢弃的字段或已转换的类型无法从 DTO 还原
Validator.validate(args)DTO 上声明的非空、长度及枚举等约束合法格式不代表当前工单允许关闭
业务服务身份、对象归属、权限及状态DTO 本身没有可信身份与数据库当前状态

Schema 是给模型的输入契约，不能据此推定服务端已经严格解析。未知字段和类型策略要在实际工具 JSON 入口配置或显式检查；下面的 validate 只覆盖第二层，不能把它当作上表所有输入检查的实现：

var violations = validator.validate(args);
if (!violations.isEmpty()) {
    throw new ConstraintViolationException(violations);
}

启用 @EnableMethodSecurity 后，将 @PreAuthorize 放在独立的 Spring 业务 Bean 上，由工具适配器调用其代理；还要校验对象归属。Spring Security 方法安全 依赖方法拦截，直接 new 对象或绕过代理不能当作授权保障。

3. 推荐按什么顺序落地？

  1. 先接只读工具。 固定工具名、输入大小、超时和每轮调用次数上限；跨租户查询返回统一不可访问结果，避免泄露对象是否存在。
  2. 再接申请工具。 proposeClose 完成校验后只保存待确认记录，返回操作摘要与 operationId。摘要展示工单、原因、影响和当前版本，此时没有关闭副作用。
  3. 增加确认入口。 用户在已认证界面提交确认，服务端绑定操作者、租户、工具、对象、版本、规范化参数哈希、过期时间与一次性凭据。模型生成的 confirmed=true 和聊天里的“确认”均不能代替此记录。
  4. 最后接执行。 从确认记录取原参数，重新鉴权并检查工单版本；任何参数或版本变化都重新确认。未执行操作原子消费凭据并执行；拒绝、过期或重复消费均不得产生新副作用。

授权后的已完成请求可按下一节重放结果，不要求再次消费凭据。确认记录保存在服务端，执行工具不能自建确认；所有自动工具回调也必须走这条路径。

4. 模型重试，怎样保证不重复关闭？

同一业务动作复用服务端生成的 operationId，不要用每轮变化的模型 tool-call ID 去重。执行表为租户、操作者、操作类型、请求号建立联合唯一约束，字段全部非空；同时保存参数哈希、执行状态和结果。PostgreSQL 唯一约束 用于阻止并发插入重复记录。

每次先重新鉴权；同键同参数且已成功，返回存档结果；同键参数不同返回冲突；执行中返回处理中。本地关闭、确认消费和成功记录放在同一事务，避免“工单关了但成功记录没写”。

事务还要封住“先查版本、再写入”的并发窗口：另一请求可能在两步之间修改工单。可将租户、对象、确认时版本与允许关闭的状态写入同一条条件更新，更新成功时递增版本，并检查受影响行数；为零就回滚确认消费，返回冲突并要求重新确认。也可在事务中锁定工单行后检查并更新，代价是锁等待。PostgreSQL 事务隔离说明指出，Read Committed 下并发更新可能等待，并对更新后的行重新判断 WHERE 条件。唯一约束只拦截同一个幂等键；两个不同 operationId 操作同一工单，仍需上述版本或状态条件保护。

若调用外部工单平台，数据库事务覆盖不了远程副作用。优先传下游支持的幂等键；超时标为待核对，先按业务号查询结果再决定补偿。下游无幂等与查询能力时转人工，不能承诺恰好一次。

5. 怎样验收四道护栏？

用测试账号 A、B 和模拟工单 T1，直接调用工具适配器及确认接口；用可计数的下游桩记录副作用，无需等待模型随机触发。按上文错误契约逐项断言：

输入或故障预期断言
A 请求关闭 B 的 T1，参数伪造租户 B拒绝；副作用为零；返回不泄露工单正文
工单号为空、原因超长或夹带未知字段校验失败；没有确认记录和下游调用
无确认、伪造确认、已过期，或确认后更改原因拒绝执行；参数改变必须产生新摘要
确认后撤销权限或修改工单版本执行前拒绝；不沿用旧的授权结论
同一请求并发提交二十次，再同键换参数最终成功记录一条、副作用一次；换参数报冲突
下游已成功但响应丢失进入待核对；查询恢复前不自动再次关闭

保存输入摘要、确认记录、状态迁移与桩调用次数，按 RAG 评估指南 的逐题记录方式留证；上表是验收目标，不是测试成绩。

边界、主资料与下一步

小型检索实验 只有合成身份、词项匹配和原文摘录，不含真实认证、工具执行或完整 RAG；不能用其通过数证明上述护栏有效。删除知识库还需核对 文档更新与删除验收 的片段与缓存。

主资料为上文链接的 Spring AI、Spring Framework、Spring Security 和 PostgreSQL 官方文档，均于 2026-11-06 查阅。人工确认也不能替代业务授权；外部系统、异步任务和补偿分支要分别验收。

实际验证时可用记录模板保存失败分支及观察结果，并区分预期断言与实测记录。