> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 权限规则

> 为特定工具与调用编写允许、拒绝和询问规则

`PermissionRule` 把某个工具与具体的调用模式映射到三种行为之一：`ALLOW`、`DENY`、`ASK`。规则在每种[权限模式](/versions/2.0.5dev/zh/building-blocks/permission-system/permission-mode)下都以最高优先级评估：拒绝与询问规则最先，允许规则排在工具内置检查之后。

每条规则由下述字段组成。当权限引擎评估一条规则时，它会用 `rule_content` 与实际调用入参调用该工具的 `match_rule()` 方法，判断规则是否命中。

<ParamField path="tool_name" type="str" required>
  规则适用的工具名：`"Bash"`、`"Read"`、`"Write"`、`"Edit"`，或任意自定义工具名。
</ParamField>

<ParamField path="rule_content" type="str | None" required>
  匹配模式，语义随 `tool_name` 变化：

  * **Bash**：通配前缀模式（`npm run:*` 命中 `npm run build`、`npm run test`）
  * **Read / Write / Edit**：glob 模式（`src/**/*.py` 命中 `src/` 下任意 `.py`）
  * **其他工具**：对 JSON 序列化后的参数做精确匹配
</ParamField>

<ParamField path="behavior" type="PermissionBehavior" required>
  `ALLOW`、`DENY` 或 `ASK`
</ParamField>

<ParamField path="source" type="str" required>
  规则来源：`"userSettings"`、`"projectSettings"`、`"session"` 等。
</ParamField>

## 匹配模式示例

`rule_content` 由各工具的 `match_rule()` 方法消费，并由 `ToolBase.generate_suggestions()` 自动生成。由于这两个方法都属于工具接口的一部分，每个工具可以独立定义自己的模式语法与匹配逻辑。

AgentScope 内置工具的模式约定如下：

<Tabs>
  <Tab title="Bash">
    针对 **`command`** 参数做匹配。模式格式为 `COMMAND_PREFIX:*`：前缀是命令的首段 token，`*` 匹配后续任意参数。

    | 模式             | 匹配                             | 不匹配           |
    | -------------- | ------------------------------ | ------------- |
    | `npm run:*`    | `npm run build`、`npm run test` | `npm install` |
    | `git commit:*` | `git commit -m "fix"`          | `git push`    |
    | `rm:*`         | `rm file.txt`、`rm -rf /tmp/x`  | `ls`          |

    ```python theme={null}
    PermissionRule(
        tool_name="Bash",
        rule_content="npm run:*",
        behavior=PermissionBehavior.ALLOW,
        source="userSettings",
    )
    ```
  </Tab>

  <Tab title="文件类工具（Read / Write / Edit）">
    针对 **`file_path`** 参数，通过 `fnmatch` 做 glob 匹配。

    | 模式            | 匹配                  |
    | ------------- | ------------------- |
    | `src/**`      | `src/` 下任意文件        |
    | `src/**/*.py` | `src/` 下的 Python 文件 |
    | `config.json` | 精确匹配该文件             |

    ```python theme={null}
    PermissionRule(
        tool_name="Write",
        rule_content="src/**",
        behavior=PermissionBehavior.ALLOW,
        source="userSettings",
    )
    ```
  </Tab>
</Tabs>

## 配置规则

规则通过两种途径进入引擎：初始化时静态配置，或运行时由用户接受建议规则动态加入。

**初始化时**：在创建智能体时把规则传入 `PermissionContext`：

```python theme={null}
from agentscope.agent import Agent
from agentscope.state import AgentState
from agentscope.permission import (
    PermissionContext, PermissionMode, PermissionRule, PermissionBehavior
)

agent = Agent(
    name="my_agent",
    system_prompt="...",
    model=model,
    state=AgentState(
        permission_context=PermissionContext(
            mode=PermissionMode.DEFAULT,
            allow_rules={
                "Bash": [PermissionRule(tool_name="Bash", rule_content="npm run:*",
                                        behavior=PermissionBehavior.ALLOW, source="userSettings")],
                "Write": [PermissionRule(tool_name="Write", rule_content="src/**",
                                         behavior=PermissionBehavior.ALLOW, source="userSettings")],
            },
            deny_rules={
                "Bash": [PermissionRule(tool_name="Bash", rule_content="rm:*",
                                        behavior=PermissionBehavior.DENY, source="userSettings")],
            },
        )
    ),
)
```

**运行时通过建议规则**：当权限系统返回 ASK 时，会基于本次调用自动生成建议规则。把已接受的规则附在 `UserConfirmResultEvent.rules` 中回传，智能体会自动写入引擎：

```python theme={null}
from agentscope.event import UserConfirmResultEvent

# ASK 决策中包含基于本次调用生成的 suggested_rules。
# 接受建议时，把它放入结果事件即可：
result = UserConfirmResultEvent(
    confirmed=True,
    rules=[suggested_rule],  # 已接受的规则会被持久化进引擎
)
```

<Note>
  允许规则无法覆盖工具发出的**安全 ASK**（`bypass_immune=True`），例如写入 `~/.ssh/` 的操作。详见[安全检查契约](/versions/2.0.5dev/zh/building-blocks/permission-system/tool-check#安全检查契约)。
</Note>