当 Agent 能执行 Bash、读写文件、调用 MCP 时,「能不能干」比「会不会干」更重要。本文基于开源框架 AgentScope 的权限子系统,拆解一套面向工具调用的权限模型:规则怎么存、怎么匹配、怎么和 HITL(人在环)续跑咬合。
一、为什么 Agent 需要独立的权限层
传统后端权限多半挂在「用户 → API → 资源」上。Agent 场景不一样:
- 调用方是模型,不是人。模型可能连续发出
rm -rf、改配置文件、跑任意 shell。 - 危险粒度在「工具入参」。同样是
Bash,ls和rm -rf /风险完全不同;同样是Write,写src/和写~/.bashrc也不同。 - 决策常常要人确认,但不能阻塞整条异步链路。权限系统必须能输出「ASK」,让 Agent 停车,等 UI 确认后再续跑。
因此 AgentScope 把权限做成 工具执行前的独立引擎:Agent 循环只管 ReAct,权限引擎只管 ALLOW / DENY / ASK。
二、整体架构:三层结构
可以用一张关系图概括:
Agent._execute_tool_call
│
▼
PermissionEngine.check_permission(tool, tool_input)
│
├─ 读 PermissionContext(mode + 规则表 + 工作目录)
├─ 按 PermissionMode 走不同策略
├─ 用 tool.match_rule(rule_content, input) 做细粒度匹配
└─ 必要时调用 tool.check_permissions(...)(工具自检 / Safety ASK)
│
▼
PermissionDecision
ALLOW → 真正执行
DENY → 写回拒绝结果,继续/结束循环
ASK → RequireUserConfirmEvent,HITL 停车
核心类型都在 agentscope.permission:
| 类型 | 职责 |
|---|---|
PermissionContext | 会话级权限状态(可随 AgentState 持久化) |
PermissionRule | 一条细粒度规则 |
PermissionMode | 粗粒度总策略 |
PermissionBehavior | 单次决策结果:allow / deny / ask / passthrough |
PermissionEngine | 评估器 |
PermissionDecision | 评估输出(含建议规则、是否 safety ASK) |
Agent 初始化时会挂上:
self._engine = PermissionEngine(self.state.permission_context)
多轮会话共用同一份 permission_context:你确认「记住这条规则」之后,后面几轮仍然生效。
三、数据结构:规则到底长什么样
1. PermissionRule:一条规则
class PermissionRule(BaseModel):
tool_name: str # 管哪个工具
rule_content: str | None # 管这个工具的哪类入参
behavior: PermissionBehavior # allow / deny / ask
source: str # 溯源标签,不参与匹配
要点:
- 索引维度是
tool_name,不是用户角色、不是 API path。 rule_content不是全局统一语法,由各工具的match_rule解释。source是自由字符串(如suggested、userSettings),只做展示/溯源,引擎匹配时不读。
2. PermissionContext:规则仓库
class PermissionContext(BaseModel):
mode: PermissionMode = PermissionMode.DEFAULT
working_directories: dict[str, AdditionalWorkingDirectory]
allow_rules: dict[str, list[PermissionRule]] # key = tool_name
deny_rules: dict[str, list[PermissionRule]]
ask_rules: dict[str, list[PermissionRule]]
内存里大概是这样:
PermissionContext(
mode=PermissionMode.DEFAULT,
allow_rules={
"Bash": [
PermissionRule(
tool_name="Bash",
rule_content="git status",
behavior=PermissionBehavior.ALLOW,
source="userSettings",
),
],
"Read": [
PermissionRule(
tool_name="Read",
rule_content="src/**",
behavior=PermissionBehavior.ALLOW,
source="suggested",
),
],
},
deny_rules={
"Bash": [
PermissionRule(
tool_name="Bash",
rule_content="rm -rf",
behavior=PermissionBehavior.DENY,
source="projectSettings",
),
],
},
ask_rules={},
)
设计上很克制:先按工具名分桶,再在桶内用入参模式匹配。这比「全局 ACL 表达式」更贴合 Agent 工具调用的形态。
四、rule_content 怎么匹配:不是全等
很多人第一反应是「规则内容要完全等于命令」。AgentScope 不是这样。
匹配委托给工具自己的 match_rule:
| 工具 | 匹配方式 |
|---|---|
| Bash(无通配符) | 子串包含:"npm install" in command |
Bash(git:*) | 前缀:git 或 git ... |
Bash(带 *) | 通配 / 正则 fullmatch |
| Read / Write / Edit | glob:fnmatch(path, "src/**") |
rule_content is None | 该工具所有调用都命中 |
| 普通 FunctionTool(未覆写) | 只有 None 才能匹配;有内容则不匹配 |
举例:
规则: Bash + "npm install" + ALLOW
调用: Bash("npm install express")
结果: 命中(子串),直接放行
规则: Read + "src/**" + ALLOW
调用: Read("src/main.py")
结果: 命中(glob),放行
调用: Read("/etc/passwd")
结果: 不命中,继续走后续策略(多半 ASK)
复合 Bash(cmd1 && cmd2)还会先被拆成子命令再评估:deny/ask 是「任一命中」,allow 往往要求「全部覆盖」——这点对安全很重要。
五、PermissionMode:粗策略怎么和细规则叠加
PermissionMode 是会话级总开关,每种 mode 有独立的 _check_<mode> 方法,避免「一个巨型 if-else」。
| Mode | 直觉 |
|---|---|
DEFAULT | 最安全:没规则就问;读操作也未必自动过 |
ACCEPT_EDITS | 人在旁边快速迭代:工作目录内的读写更宽松 |
EXPLORE | 只读探索:改文件 / 危险命令直接拒 |
BYPASS | 基本信任沙箱:少问,主要靠 deny/ask 规则兜底 |
DONT_ASK | 无人值守:所有 ASK 转 DENY,偏安全 |
以最常见的 DEFAULT 为例,评估顺序大致是:
1. deny_rules 命中? → DENY
2. ask_rules 命中? → ASK(附带建议规则)
3. 只读快路径? → ALLOW(部分场景)
4. tool.check_permissions(...)
- ALLOW / DENY → 直接返回
- Safety ASK(bypass_immune=True)→ 必须问人,allow 规则盖不住
- 普通 ASK / PASSTHROUGH → 继续
5. allow_rules 命中? → ALLOW
6. 默认 → ASK
这里有个很关键的细节:Safety ASK(bypass_immune=True)。
例如疑似 rm -rf /、写入危险路径、命令注入模式——即使你以前点过「允许类似操作」,也不能用 allow 规则把这次危险调用「静默放行」。BYPASS 模式会刻意弱化这类提示(契约就是少问),真正硬护栏应靠 deny 规则。
六、和 Agent 循环如何咬合(HITL)
权限不是「同步 input() 卡住进程」,而是事件驱动:
Acting 执行工具
→ 引擎返回 ASK
→ tool_call.state = ASKING
→ yield RequireUserConfirmEvent
→ 本次 reply 以「未完成」方式结束(没有 ReplyEnd 的完成语义)
用户在 UI 确认 / 拒绝
→ 再次 reply(UserConfirmResultEvent)
续跑:
确认 → state=ALLOWED,可 add_rule,再真正执行
拒绝 → 写入 DENIED 工具结果,模型下一轮会看到拒绝原因
这和 AgentScope 的 ReAct 状态机一致:_next_action 发现还有 awaiting 的 tool call,就会「停车等外部事件」,而不是阻塞事件循环。
用户点「允许并记住」时,UI 通常会把 suggested_rules 一并带回;Agent 侧:
for rule in confirmation.rules:
self._engine.add_rule(rule)
建议规则一般由工具的 generate_suggestions 生成,例如:
- Bash:
npm run→ 建议npm run:* - 读文件:
src/a.py→ 建议src/** source常标成"suggested"
七、一次完整走读
假设当前 context:
mode = DEFAULT
allow: Bash + "git status"
deny: Bash + "rm -rf"
| 模型发起的调用 | 引擎结果 | 后续 |
|---|---|---|
Bash("git status") | ALLOW | 直接执行 |
Bash("rm -rf /tmp/x") | DENY | 工具结果写回拒绝文案 |
Bash("npm install") | ASK | 弹确认;若记住 npm install,写入 allow_rules |
Write("~/.bashrc") | 可能 Safety ASK | 即使有宽泛 allow,也可能仍要当面确认 |
对业务开发者而言,你很少手写规则表;更常见是:
- 启动时设好
mode和工作目录; - 让 HITL 在运行中积累 allow/deny;
- 项目级危险模式用 deny 规则预置。
八、设计取舍:值得抄的几点
1. 工具名分桶 + 入参模式,而不是通用策略语言
Agent 的「资源」本质上是工具调用。按 tool_name 索引、把匹配语义下沉到工具,比引入一套复杂 DSL 更贴业务,也方便第三方工具自定义 match_rule。
2. mode 与 rule 正交
mode 管「默认姿态」,rule 管「例外清单」。EXPLORE / DONT_ASK / BYPASS 改变的是评估流程,而不是把所有规则重写一遍。
3. ASK 是一等公民,且可带建议规则
权限系统不仅说「不行」,还说「如果你想以后少问,建议加这条规则」。这比冷冰冰的拒绝更适合 Agent 产品体验。
4. Safety ASK 防止「记住一次就永久危险」
bypass_immune 把「方便」和「危险」拆开:普通操作可以记住,高危操作必须当场确认(在非 BYPASS 场景下)。
5. 状态可持久化
规则住在 AgentState.permission_context,和对话 context 一起存。会话恢复后,权限习惯还在。
九、上手最小示例
from agentscope.permission import (
PermissionContext,
PermissionEngine,
PermissionMode,
PermissionRule,
PermissionBehavior,
)
ctx = PermissionContext(mode=PermissionMode.DEFAULT)
engine = PermissionEngine(ctx)
engine.add_rule(
PermissionRule(
tool_name="Bash",
rule_content="git:*",
behavior=PermissionBehavior.ALLOW,
source="userSettings",
)
)
engine.add_rule(
PermissionRule(
tool_name="Bash",
rule_content="rm -rf",
behavior=PermissionBehavior.DENY,
source="projectSettings",
)
)
# Agent 里通常不必手动 check;执行工具前框架会调用:
# decision = await engine.check_permission(tool, tool_input)
挂到 Agent 上时,只要构造时带上(或事后改)state.permission_context 即可;引擎在 Agent.__init__ 里已经接好。
十、小结
AgentScope 的权限设计可以压成一句话:
按工具名归档规则,按入参模式匹配;用 Mode 定默认姿态,用 ASK + HITL 做人机协同,用 Safety ASK 兜住真正危险的操作。
如果你也在做「能动手的 Agent」,不妨优先想清楚这三件事:
- 权限客体是「工具调用」还是「HTTP 资源」?
- ASK 是阻塞式对话框,还是可续跑的事件?
- 「记住规则」会不会把高危操作永久放行?
想清楚这三点,你的 Agent 安检台就有了骨架;其余都是产品和体验上的填充。
参考(源码入口)
agentscope/permission/_rule.py— 规则模型agentscope/permission/_context.py— 上下文与规则表agentscope/permission/_types.py— Mode / Behavioragentscope/permission/_engine.py— 评估引擎agentscope/permission/_decision.py— 决策与 Safety ASKagentscope/agent/_agent.py—_execute_tool_call/ HITL 续跑agentscope/tool/_builtin/_bash.py等 —match_rule/generate_suggestions
(文中示例基于 AgentScope 当前实现梳理,细节以仓库源码为准。)