去年做内部 AI 中台评审的时候我见到一个特别典型的场景Agent 已经能自动发邮件、写数据库、甚至调内部工单系统但权限校验还停留在“能连上就放行”。开发同学的理由也很直接“反正只有内部人能调用”可内部人也分普通员工和管理员啊。那天 Agent 差点把测试环境的地址同步给了全体客户我才意识到AI 这道门不是靠模型能力兜底而是要靠一套像 Spring Security 之于 Web 应用那样的权限闸门。这篇文章要聊的就是给 Agent Skills 设计一套“元工具权限系统”。元工具可以理解成 Agent 世界的万能手柄它代表 Agent 去实际调用各种 Skill 和底层工具如果你不对手柄本身做管控那等于把生产库的连接串直接贴到 Prompt 里。我会从 Spring Security 的视角切入把认证、授权、拦截链、审计这些 Web 开发者已经烂熟于心的概念翻译成 AI Agent 场景下可落地的设计再给出一套可以直接上手实现的中间件方案。1. 先想清楚Agent Skills 和元工具到底管什么1.1 SkillsAI 能力的“业务接口”做过 Web 后端的人都知道Controller 暴露的是一组 HTTP 接口前端通过路径和参数去调用。Agent Skills 本质上也是这个套路只不过语言模型不是人来驱动的调用方而是通过语义理解来决定何时调用哪个能力。每个 Skill 通常包含三样东西一段给模型的描述、一组入参定义、一个具体的执行函数。模型看到用户说“帮我发一封周报邮件”会去匹配 Skill 描述生成入参然后调用后端函数。这里有个很容易被忽略的细节Skill 不只是“一段代码”它同时是模型世界的“语义入口”和物理世界的“执行入口”。正因为模型能通过描述猜测这个能力能干什么如果描述写得模糊或者权限没有在入口处卡住模型就可能用错误的方式去使用本该受限的能力。1.2 元工具所有 Skill 的流量入口当一个 Agent 的工具列表膨胀到几百个之后常规做法是把所有 Skill 注册到一个统一的执行器里模型只需要调用这个执行器执行器再根据工具名去路由到具体函数。这个执行器就是我标题里说的“元工具”。它像 Spring MVC 里的 DispatcherServlet本身不干活但所有请求都要经过它由它决定把工作交给哪个 Controller。元工具有个特点它接收的入参通常是tool_name和arguments。模型说“调用 toolA参数是xx”元工具就原样转发。这意味着什么如果元工具不做权限校验任何有权限调用元工具的角色就间接拥有了所有 Skill 的权限。这就好比给每个员工发了一张能开全公司所有门的万能门禁卡卡本身是好用的但一旦被复制损失就是全量的。1.3 为什么权限要放在元工具这一层你可能会问直接在每个 Skill 函数体里做权限判断不行吗工程上完全可以但维护性极差。你希望每个 Skill 的开发者在写业务逻辑的同时还要自己处理身份解析、策略匹配、日志上报那代码里会充满重复的权限模板而且不同人写的校验强度还不一样总有人忘记写。把权限收敛到元工具这一层本质上就是 Spring Security 里的 Filter Chain AOP 思想让横切逻辑和业务逻辑解耦。元工具作为统一的被拦截点所有 Skill 调用都从它经过权限策略只需维护一份审计也只需在元工具里做一次不会遗漏。即使将来新增了一个 Skill只要注册信息里带上权限标记元工具就能自动按同一套规则放行或拦截不需要 Skill 内做任何改动。2. Spring Security 给我们的四张“地图”2.1 认证先回答“是谁在叫车”Spring Security 的认证要回答“你是谁”。在 Agent 场景下这个“谁”不是单指用户而是一条调用链最外层是最终用户中间可能有主 Agent、子 Agent最后才是某个 Skill 执行器。系统里任何一个环节被冒充后面所有权限判断都会失真。我见过不少团队只在接入层校验一次 JWT然后把用户 ID 塞进全局变量里一路用到 Skill 里。这在同步单线程模型下勉强能跑但 Agent 现在普遍是并发的、多任务并行执行的一个用户的请求可能在多个子 Agent 中同时执行全局变量很容易串号。正确的做法是把认证结果做成一个不可变的“调用上下文”像请求头一样沿着调用链一路透传。这个上下文至少包含用户 ID、角色列表、Agent 实例 ID、租户 ID最好还有一个请求级的 requestId方便后续把认证信息和审计日志对上。在元工具里我们只信任这个上下文里携带的信息而不是让元工具自己去重新解析一次外部 Token否则每个 Skill 都要写一遍 Token 解析逻辑。2.2 授权把权限控制到“Skill 级动作”Spring Security 里的授权通常配置到 URL 或者方法级别例如/admin/**需要ROLE_ADMIN。在 Agent Skills 场景里资源粒度要控制到“Skill 名称 动作”级别。一个 Skill 内部可能包含多个底层工具操作例如“发送邮件”技能对应 SMTP 调用“读取文件”技能对应文件系统读取权限设计需要能单独控制“能不能用某个 Skill”“能不能触发某个动作”。我在实际设计中习惯把所有可执行对象统一成权限字符串例如skill:email:send、skill:file:read、tool:database:execute。这样策略匹配就很自然了用户拥有哪些权限字符串当前请求的目标 Skill 需要哪些权限字符串两者取交集。你也可以把权限字符串分成更细的维度比如加资源前缀project:alpha:skill:email:send表示只能操作 Alpha 项目下的邮件能力。这里有一个容易被忽略的点Skill 描述和 Tool 参数也可能泄露资源。模型在调用“文件读取”工具时如果参数里包含路径而权限只校验了 Skill 名称没有校验路径前缀用户就可能通过 Prompt 注入让模型去读不该读的文件。所以授权还要包含对参数的校验这也是后面章节会展开的。2.3 拦截链把权限校验做成必经收费站Spring Security 的 Servlet Filter 链是线性的请求按顺序经过一堆过滤器任何一个过滤器拒绝请求就到此为止。Agent 场景里元工具就是这个拦截链上的“最后一个关卡”。你可以在元工具前面叠加各种过滤器——输入校验、Prompt 注入检测、限流、敏感词过滤——但最终放行前必须经过权限裁决。我在代码里通常把权限中间件做成了三层第一层解析调用上下文第二层做权限策略决策第三层做调用前校验。这三层跟 Spring Security 的AuthenticationFilter、AuthorizationFilter、MethodSecurityInterceptor是一一对应的。把所有拦截逻辑收敛在元工具入口好处是出了问题只需要看这一条链路不用去翻几十个 Skill 里各自写的小逻辑。2.4 默认拒绝宁可误伤不可裸奔Spring Security 在配置里一直强调“默认拒绝”也就是说没有显式允许的请求一律拒绝。但很多 Agent 团队在配置权限时恰恰相反默认是放行的只把少数敏感工具加入黑名单。黑名单模式在工具数量少的时候还能应付工具一多漏掉一个就出事故。我在设计元工具权限时始终把默认策略设成“拒绝”。即使是内部运营需要新的 Skill也先走“白名单申请”明确谁能用、什么条件下能用再上线。这样做的代价是初期有少量正常调用会被拦截但安全收益远大于那点业务摩擦。你可以反过来想Spring Security 都不敢用黑名单保护 Admin 接口AI Agent 直接操作生产系统为什么敢3. 元工具权限系统的核心模块设计3.1 权限模型主体、动作、资源、条件权限模型不需要发明新概念沿用经典的“谁、对什么、做什么、什么条件下”四元组就行。以我实现过的模型来说大概是这样一张表维度含义示例主体最终用户、角色、Agent 实例user:zhangsan,role:ops动作对 Skill/工具的访问方式invoke,read,admin资源目标 Skill 或底层工具skill:email:send,tool:file:read条件环境约束、参数约束、时间约束projectalpha,pathPrefix/data/workspace这里主体之所以要包含 Agent 实例是因为一个 Agent 可能是被多个用户复用的。User A 调用“数据分析 Agent”去查询数据和 User B 调用同一个 Agent 查询数据底层工具能执行的动作必须不同。把 Agent 实例当作主体的一部分可以让权限策略跟随到具体的执行链路上而不是只看最终用户身份。3.2 决策流程一次元工具调用的完整安检一次元工具调用到达权限系统后我建议的决策流程包括六个步骤。第一步从调用上下文里取出主体信息第二步确定请求的目标资源也就是 Skill 名和对应的权限字符串第三步提取条件属性包括路径、项目、时间等第四步读取该主体的所有权限策略第五步做策略匹配按“拒绝优先”顺序判断第六步输出决策结果并记录审计日志。整个过程如果超过 5 毫秒都算不合格。这里有个细节决策过程应该设计成“无副作用”的。不能因为在权限判断时修改了用户状态导致同一个请求在不同执行路径下出现不同的权限结果。策略引擎最好是纯函数输入主体、资源、条件输出 allow/deny不依赖外部可变状态。这样调试简单也方便压测。3.3 策略配置用 YAML 描述“谁能对谁做什么”权限策略可以用多种方式存储我推荐从 YAML 或 JSON 文件开始等策略数量超过几百条再迁移到数据库。这样配置更透明每次修改都能走代码评审。下面是我常用的一份策略文件片段permissions: - principal: role:employee effect: allow actions: - skill:email:read - skill:calendar:read - principal: role:ops effect: allow actions: - skill:file:write conditions: pathPrefix: /data/workspace - principal: user:zhangsan effect: deny actions: - skill:email:send这份配置表达了三层意思所有员工可以读邮件和日历运维角色的写文件技能仅限指定目录而用户 zhangsan 被明确禁止发送邮件。策略匹配时要注意“拒绝优先”即使某个用户符合 allow 规则只要有一条 deny 规则命中就拒绝。这也是从 Spring Security 的AuthorizationDeniedException机制里学来的——越具体的限制应该越早生效。3.4 审计追踪为每一次 AI 调用留下底账权限系统如果只做拦截不做记录那它只能防止事故不能复盘事故。每次元工具调用都应该记录谁、什么时候、调了哪个 Skill、入参是什么、决策结果是允许还是拒绝、如果拒绝拒绝了哪一条规则。这些数据不仅是安全优化依据也是后续调 Prompt、调工具描述的重要证据。我建议审计日志和调用链路追踪用同一个 requestId。这样以后排查“Agent 为什么做了件奇怪的事”能够从用户请求一路追踪到模型决策、到元工具调用、到权限裁决再到最终的执行结果。没有这张链路遇到事故就只能靠猜。如果合规要求高审计日志还需要做防篡改存储至少要做到只能追加、不能修改比如写入独立的日志服务或者用哈希链做校验。4. 动手实现给元工具加一个权限中间件4.1 选型思路技术栈不重要模式才重要很多 Web 开发者转型 AI 后老想着要不要学个新框架我的建议是不用纠结。权限系统的核心模式在 FastAPI、Spring Boot、Node.js 里完全一样。下面我用 Python FastAPI 风格来写因为这是目前 AI Agent 周边工具最常用的技术栈但你看完照样能翻译成 Java 或 TypeScript 版本。我们假设项目结构里已经有一个元工具入口函数invoke_skill(skill_name, arguments, context)。这个函数是所有 Skill 调用的必经之路。我们要做的就是在这个函数的第一行插入权限校验逻辑和一个过滤器链没什么区别。4.2 权限上下文解析从请求头到 Tool 调用第一步是解析调用上下文。我在实践里用了一个 dataclass 来表示上下文它包含用户 ID、角色集合、Agent 实例 ID以及一个 requestId。调用来源不同解析方式也不同来自外部 HTTP API 的从请求头取 JWT来自 Agent 内部链路的从上一步调用结果的元数据里透传。这里最关键的一点是一定要在入口处把上下文构造好并绑定到当前执行任务上不能随手全局变量传递。dataclass class CallContext: user_id: str roles: set[str] agent_instance_id: str request_id: str def parse_context(request_headers: dict) - CallContext: token request_headers.get(authorization) payload decode_jwt(token) return CallContext( user_idpayload[sub], rolesset(payload.get(roles, [])), agent_instance_idrequest_headers.get(x-agent-instance-id, default), request_idrequest_headers.get(x-request-id, uuid4().hex), )我在实际项目中做过一个小优化解析完 JWT 后会缓存一段时间的解析结果避免在同一个请求里多次解密 Token。缓存 key 可以是user_id agent_instance_id缓存有效期设 5 到 10 分钟。账要算清楚不能为了省一次解析把已删除用户的权限还留在缓存里。4.3 在元工具调用链路上做权限裁决接下来是在invoke_skill入口调用权限服务。权限服务要做的两件事第一根据 Skill 名找到对应的权限字符串第二根据上下文的角色和用户 ID 去匹配策略做决策。代码不复杂复杂的是策略匹配的顺序和条件判断。class PermissionDecision: def __init__(self, allowed: bool, matched_rule: str): self.allowed allowed self.matched_rule matched_rule class PermissionService: def check(self, ctx: CallContext, skill_name: str, args: dict) - PermissionDecision: # 1. 默认拒绝 decision PermissionDecision(False, default-deny) # 2. 获取该 skill 对应的资源标识 resource fskill:{skill_name} principal_candidates {fuser:{ctx.user_id}} | {frole:{r} for r in ctx.roles} # 3. 按优先级遍历策略deny 优先 for policy in load_policies(): if not matches_principal(policy, principal_candidates): continue if resource not in policy[actions]: continue if not matches_conditions(policy, args): continue if policy[effect] deny: return PermissionDecision(False, frule:{policy.get(id)}) decision PermissionDecision(True, frule:{policy.get(id)}) return decisionmatches_conditions函数是重点。它要负责检查路径前缀、项目编码、时间窗口等参数约束。比如一个文件写入技能要求路径必须以/data/workspace/开头如果 Agent 传入的路径是/etc/passwd那么即使角色是运维也不能放行。这个能力对 Agent 特别重要因为模型可能被 Prompt 诱导传入恶意参数权限系统必须在参数层做一次约束。4.4 执行结果反向校验防止 Skill 偷偷越权权限校验放在调用前只能保证入口受控但 Skill 执行时可能因为代码 bug 或依赖的第三方服务出了问题变成了一个“合法的非法操作”。比如一个读取文件的 Skill 被允许读/data/reports它内部却尝试读取了/data/private。这种绕过不容易被入口校验发现。我在实现时加了一层“执行结果反向校验”Skill 返回结果后元工具会检查返回的数据是否落在授权范围内。可以是简单的路径过滤、字段裁剪也可以是对敏感数据做脱敏。这本质上和数据层的行级权限差不多属于纵深防御。如果你在第一步已经拦截住了参数这层可以做轻量校验不必重复所有权限规则。5. 上线后必须处理的几个“幽灵问题”5.1 工具直接绕过元工具权限变摆设第一个大坑是 Skill 内部直接调用了底层 SDK 或数据库没有经过元工具的入口。比如你在元工具里做好了权限但某个 Skill 为了省事直接import client然后client.execute(sql)权限系统完全感知不到。这在快速迭代的团队里非常常见。我的解决方案是把底层工具调用全部收口到一个 package 里禁止业务 Skill 直接实例化客户端。代码评审时看到类似local_db_client、file_system.open这类非通过元工具的 I/O 调用直接打回。跑 CI 时还可以在代码里加静态扫描规则只允许元工具模块拥有底层资源句柄其他模块只能调用元工具暴露的接口。5.2 Agent 子任务并发导致“身份串号”第二个幽灵问题是上下文串号。Agent 在运行时经常开局多个子任务不同子任务处理不同用户的数据。如果权限上下文被设计成全局共享变量一个用户的数据可能被另一个用户看到。这个问题在异步框架里尤其明显一不留神会把 A 的身份带到 B 的请求里。我推荐在每个 Agent 任务开始时创建独立的CallContext实例并通过方法参数或框架的上下文变量如 Python 的contextvars、Java 的ThreadLocal包一层传递。绝对不要用模块级全局字典存用户信息。调试时可以打印一个包含 requestId 的调用链日志一旦发现同一个 requestId 下出现了两个不同 user_id基本就是上下文传递代码写错了。5.3 策略缓存和动态 Skill 列表不一致权限策略如果做了缓存那么 Skill 注册信息更新后缓存可能还保留旧的权限要求。新上线的 Skill 可能被默认拒绝下线的 Skill 反而还能被调用。这种不一致很难靠日志发现通常表现为“同一个请求之前能过现在被拒了”或者反过来。解决方式有两种一是在 Skill 注册或下线时主动清理相关缓存 key二是给缓存加一个全局版本号每次策略变更都递增版本号加载策略时对比版本号决定是否刷新。第二种方式实现起来更简单适合集中式配置。实际项目里我更推荐两种结合本地策略缓存设一个合理过期时间比如 60 秒同时注册一个配置中心的监听器做版本失效。5.4 权限管控过宽成了“免责声明”最后一个坑不是技术问题而是管理问题。很多人上线权限系统结果把所有员工的权限都设成“允许所有 Skill”那权限系统就变成了摆设出了事只能说“我们已经记录了日志”。如果审计日志真的被用作免责证明那系统本身就失败了。我给团队定的标准是默认拒绝策略必须真实生效所有新接入的 Skill 必须显式声明权限要求上线前要过一遍策略评审。同时定期导出“哪些角色拥有哪些敏感技能”清单给业务方确认。权限系统的价值不在于策略多复杂而在于每次拦截都是真实有效的。宁可让某些正常操作被拦一次也不要让危险操作畅通无阻地跑一个月。我在实际操作中还有一个很深的体会权限系统上线初期会收到大量“怎么又被拦了”的反馈不要急着放宽策略先看审计日志里被拦截的理由是否合理。很多时候模型只是没把参数传入正确前缀的目录或者用户角色缺了一个 Skill 标注这些是语义问题不是权限问题。等模型和工具描述逐渐收敛后类似误拦会明显减少。如果你正在做 Agent 接入生产系统我建议先挑两个敏感度最高的 Skill 做试点把权限系统整体跑通再逐步扩大范围。权限设计这件事做得越早后面推翻的成本就越低。Spring Security 花了这么多年教会我们的一件事就是能力边界不是靠自觉而是靠系统强制边界。AI 时代这句话依然成立。