文章目录
-
- 一、概述
- 二、项目结构总览
- 三、核心组件深度解析
-
- 3.1 权限模式（PermissionMode）
- 3.2 权限行为（PermissionBehavior）
- 3.3 权限上下文（PermissionContext）
- 3.4 权限规则（PermissionRule）
- 3.5 权限决策（PermissionDecision）
- 四、权限引擎：决策流程全解析
-
- 4.1 六步优先级决策流程
- 4.2 核心代码逻辑
- 4.3 规则匹配机制
- 五、工具层与安全检查（不可绕过）
-
- 5.1 工具基类（ToolBase）
- 5.2 Bash 工具：最复杂的权限检查
- 5.3 文件操作工具（Read/Write/Edit）
- 5.4 危险常量清单
- 六、规则匹配策略详解
-
- 6.1 Bash 命令匹配
- 6.2 文件路径匹配
- 6.3 通用匹配
- 七、建议规则生成机制
-
- 7.1 Bash 建议规则
- 7.2 文件工具建议规则
- 八、实践案例
-
- 8.1 基本权限检查流程
- 8.2 用户确认流程
- 8.3 不同模式的行为差异
- 九、常见问题解答（FAQ）
-
- Q1：为什么某些规则未生效？
- Q2：BYPASS 模式下为什么仍被拦截？
- Q3：ASK 提示频繁出现怎么办？
- Q4：Bash 命令匹配使用通配符还是前缀更好？
- Q5：如何扩展自定义工具的权限检查？
- Q6：DONT_ASK 模式与无人值守任务
- 十、总结
- 附：依赖关系总览
一、概述
在 AI Agent 框架中，工具调用（Tool Calling）是核心能力之一，但同时也是安全风险的高发地带。当 Agent 可以执行 Bash 命令、读写文件、编辑代码时，如何确保这些操作在可控范围内？如何防止恶意注入或误操作导致系统级破坏？
AgentScope 2.0 提供了一套精心设计的权限控制子系统。该系统位于 src/agentscope/permission/ 目录下，围绕\”规则 + 上下文 + 决策\”的核心模型构建，通过多层次决策逻辑确保只有经过授权的操作才能被执行，同时为用户提供透明的决策过程和便捷的权限管理方式。
本文将基于 AgentScope 2.0 源码，从架构设计、核心组件、决策流程、安全检查机制、规则匹配策略、实践案例等多个维度，对这套权限控制系统进行深度剖析。
二、项目结构总览
权限控制子系统的代码组织如下：
src/agentscope/permission/
├── __init__.py # 模块入口
├── _types.py # 权限类型定义（模式与行为枚举）
├── _context.py # 权限上下文（模式、工作目录、规则容器）
├── _rule.py # 权限规则模型
├── _decision.py # 权限决策结果
└── _engine.py # 权限引擎（核心决策逻辑）
src/agentscope/tool/
├── _base.py
