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

# 权限

> 使用声明式权限规则控制 Deep Agents 的文件系统访问

使用声明式权限规则控制智能体可以读取或写入的文件和目录。将一系列规则传递给 `permissions=`，智能体的内置文件系统工具将遵守这些规则。

:::python

> [!NOTE]
>
> 权限需要 `deepagents>=0.5.2`。

::!

:::js

> [!NOTE]
>
> 权限需要 `deepagents>=1.9.1`。

::!

:::python
权限仅适用于内置文件系统工具（`ls`、`read_file`、`glob`、`grep`、`write_file`、`edit_file`、`delete`）。访问文件系统的自定义工具和 MCP 工具不受此限制。权限也不适用于 [沙盒后端](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md)，后者通过 `execute` 工具支持任意命令执行。
::!

:::js
权限仅适用于内置文件系统工具（`ls`、`read_file`、`glob`、`grep`、`write_file`、`edit_file`）。访问文件系统的自定义工具和 MCP 工具不受此限制。权限也不适用于 [沙盒后端](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/sandboxes.md)，后者通过 `execute` 工具支持任意命令执行。
::!

> [!TIP]
>
> 当您需要在内置文件系统工具上使用基于路径的允许/拒绝规则时，请使用 `permissions`。当您需要自定义验证逻辑（速率限制、审计日志、内容检查）或需要控制自定义工具时，请使用 [后端策略钩子](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/backends.md#添加策略钩子)。

## 基本用法

:::python

将一系列 @\[`FilesystemPermission`] 规则传递给 @\[`create_deep_agent`]。规则按声明顺序评估。第一个匹配的规则生效。如果没有规则匹配，则允许操作。

```python theme={null}
from deepagents import FilesystemPermission, create_deep_agent


# Read-only agent: deny all writes
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
```

::!

:::js

将一系列 `FilesystemPermission` 规则传递给 `createDeepAgent`。规则按声明顺序评估。第一个匹配的规则生效。如果没有规则匹配，则允许操作。

```ts theme={null}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("basic: agent not created");
```

::!

## 规则结构

:::python

每个 `FilesystemPermission` 有三个字段：

| 字段 | 类型 | 描述 |
| - | - | - |
| `operations` | `list["read" \| "write"]` | 该规则适用的操作。`"read"` 涵盖 `ls`、`read_file`、`glob`、`grep`。`"write"` 涵盖 `write_file`、`edit_file`、`delete`。 |
| `paths` | `list[str]` | 用于匹配文件路径的通配符模式（例如，`["/workspace/**"]`）。支持 `**` 用于递归匹配和 `{a,b}` 用于选择。 |
| `mode` | `"allow" \| "deny" \| "interrupt"` | 匹配操作是允许、拒绝还是需要人工批准。默认为 `"allow"`。参见 [需要人工批准](#需要人工批准)。 |

规则使用先匹配者胜出评估：第一个 `operations` 和 `paths` 与当前调用匹配的规则决定结果。如果没有规则匹配，调用将被 **允许**（宽松默认）。

::!

:::js

每个 `FilesystemPermission` 有三个字段：

| 字段 | 类型 | 描述 |
| - | - | - |
| `operations` | `("read" \| "write")[]` | 该规则适用的操作。`"read"` 涵盖 `ls`、`read_file`、`glob`、`grep`。`"write"` 涵盖 `write_file`、`edit_file`。 |
| `paths` | `string[]` | 用于匹配文件路径的通配符模式（例如，`["/workspace/**"]`）。支持 `**` 用于递归匹配和 `{a,b}` 用于选择。 |
| `mode` | `"allow" \| "deny"` | 匹配操作是允许还是拒绝。默认为 `"allow"`。 |

规则使用先匹配者胜出评估：第一个 `operations` 和 `paths` 与当前调用匹配的规则决定结果。如果没有规则匹配，调用将被 **允许**（宽松默认）。

路径必须是绝对路径（以 `/` 开头），不能包含 `..` 或 `~`。无效路径在智能体构建时抛出异常。

::!

:::python

## 需要人工批准

> [!NOTE]
>
> `"interrupt"` 模式需要 `deepagents>=0.6.8`。

将 `mode="interrupt"` 设置为需要人工批准，而不是直接允许或拒绝匹配操作。当智能体在匹配中断模式规则的路径上调用内置写入工具（`write_file`、`edit_file`、`delete`）时，`create_deep_agent` 会引发人工参与中断，而不是运行工具，并且审阅者可以批准、编辑或拒绝调用。

```python theme={null}
from deepagents import FilesystemPermission, create_deep_agent
from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(
    model=model,
    permissions=[
        # Pause for approval before writing anything under /secrets.
        FilesystemPermission(
            operations=["write"],
            paths=["/secrets/**"],
            mode="interrupt",
        ),
    ],
    # Interrupt mode requires a checkpointer to pause and resume.
    checkpointer=InMemorySaver(),
)
```

中断模式规则会自动连接到智能体的人工参与中间件，并与您传递的任何 `interrupt_on` 合并，因此您以与工具调用中断相同的方式处理和恢复它们。参见 [人工参与](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/human-in-the-loop.md) 以了解恢复流程。

> [!NOTE]
>
> 删除目录是全有或全无操作：`delete` 检查目标及其所有后代路径的 `write` 权限，如果其中任何一个是拒绝的，则拒绝整个操作，而不是删除部分树。`delete` 对现有空目录也应用相同的保守检查，因为它仍然是目录而不是确认的叶目标。
>
> 删除普通文件是一个精确匹配的情况：`delete`以与`write_file`和`edit_file`相同的方式解析目标，使用先匹配胜出的评估方式，因此一个更早、更窄的`allow`规则会胜过一个较晚的通用`deny`规则。`deepagents>=0.7.3`对此精确匹配行为是必需的。

> [!TIP]
>
> 使用字面量前缀锚定中断模式（例如，`/secrets/**`或`/projects/*/secrets/**`）。批量工具（`ls`、`glob`、`grep`以及在目录上的`delete`）在其搜索子树可能与规则的锚定前缀重叠时触发中断，因此一个完全未锚定的模式如`/**/secrets`会保守地过度触发。

:::

## 示例

:::python

### 隔离到工作区目录

仅允许在`/workspace/`下读写，并拒绝其他所有操作：

```python theme={null}
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
```

### 保护特定文件

```python theme={null}
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/.env", "/workspace/examples/**"],
            mode="deny",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
```

### 只读内存

允许智能体读取内存文件，但阻止其修改它们。这对于需要仅由应用代码更新的组织级策略或共享知识库很有用。参见[只读与可写内存](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/memory.md#只读与可写记忆)以获取更多背景。

```python theme={null}
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

agent = create_deep_agent(
    model=model,
    backend=CompositeBackend(
        default=StateBackend(),
        routes={
            "/memories/": StoreBackend(
                namespace=lambda rt: (rt.server_info.user.identity,),
            ),
            "/policies/": StoreBackend(
                namespace=lambda rt: (rt.context.org_id,),
            ),
        },
    ),
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/memories/**", "/policies/**"],
            mode="deny",
        ),
    ],
)
```

### 拒绝所有访问

阻止所有读写。这是一个限制性的基线，你可以在其上叠加更具体的允许规则：

```python theme={null}
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
)
```

### 规则顺序

由于先匹配胜出，规则顺序很重要。将更具体的规则放在更广泛的规则之前：

```python theme={null}
# Correct: deny .env, allow workspace, deny everything else
correct_permissions = [
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env"],
        mode="deny",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

# Bug: /workspace/** matches .env first, so the deny never triggers
incorrect_permissions = [
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env"],
        mode="deny",  # never reached
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]
```

:::

:::js

### 隔离到工作区目录

仅允许在`/workspace/`下读写，并拒绝其他所有操作：

```ts theme={null}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("isolate-workspace: agent not created");
```

### 保护特定文件

```ts theme={null}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/.env", "/workspace/examples/**"],
      mode: "deny",
    },
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("protect-files: agent not created");
```

### 只读内存

允许智能体读取内存文件，但阻止其修改它们。这对于需要仅由应用代码更新的组织级策略或共享知识库很有用。参见[只读与可写内存](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/memory.md#只读与可写记忆)以获取更多背景。

```ts theme={null}
const store = new InMemoryStore();
const agent = createDeepAgent({
  model,
  backend: new CompositeBackend(new StateBackend(), {
    "/memories/": new StoreBackend({
      namespace: (rt) => [rt.serverInfo.user.identity],
    }),
    "/policies/": new StoreBackend({
      namespace: (rt) => [rt.context.orgId],
    }),
  }),
  permissions: [
    {
      operations: ["write"],
      paths: ["/memories/**", "/policies/**"],
      mode: "deny",
    },
  ],
  store,
});
if (!agent) throw new Error("read-only-memory: agent not created");
```

### 拒绝所有访问

阻止所有读写。这是一个限制性的基线，你可以在其上叠加更具体的允许规则：

```ts theme={null}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});
if (!agent) throw new Error("deny-all: agent not created");
```

### 规则顺序

由于先匹配胜出，规则顺序很重要。将更具体的规则放在更广泛的规则之前：

```ts theme={null}
const correctPermissions: FilesystemPermission[] = [
  { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

const incorrectPermissions: FilesystemPermission[] = [
  {
    operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  {
    operations: ["read", "write"],
    paths: ["/workspace/.env"],
    mode: "deny",
  },
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];
```

:::

## 子智能体权限

:::python

[子智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/subagents.md)默认继承父智能体的权限。要给子智能体不同的权限，在其规范中设置`permissions`字段。这**完全替换**了父智能体的规则。

```python theme={null}
agent = create_deep_agent(
    model=model,
    backend=backend,
    permissions=[
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/workspace/**"],
            mode="allow",
        ),
        FilesystemPermission(
            operations=["read", "write"],
            paths=["/**"],
            mode="deny",
        ),
    ],
    subagents=[
        {
            "name": "auditor",
            "description": "Read-only code reviewer",
            "system_prompt": "Review the code for issues.",
            "permissions": [
                FilesystemPermission(
                    operations=["write"],
                    paths=["/**"],
                    mode="deny",
                ),
                FilesystemPermission(
                    operations=["read"],
                    paths=["/workspace/**"],
                    mode="allow",
                ),
                FilesystemPermission(
                    operations=["read"],
                    paths=["/**"],
                    mode="deny",
                ),
            ],
        }
    ],
)
```

:::

:::js

[子智能体](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/subagents.md)默认继承父智能体的权限。要给子智能体不同的权限，在其规范中设置`permissions`字段。这**完全替换**了父智能体的规则。

```ts theme={null}
const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  subagents: [
    {
      name: "auditor",
      description: "Read-only code reviewer",
      systemPrompt: "Review the code for issues.",
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
    },
  ],
});
if (!agent) throw new Error("subagent: agent not created");
```

要显式授予子智能体无限制访问，设置`permissions: []`。空数组用无限制覆盖父规则。省略`permissions`则继承自父智能体。

:::

## 组合后端

:::python

在使用带有沙盒默认值的 @\[`CompositeBackend`]时，每个权限路径都必须限定在已知路由前缀下。沙盒支持任意命令执行，因此仅基于路径的权限无法阻止通过 shell 命令的文件系统访问。将权限限定在路由特定的[后端](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/backends.md)可避免此冲突。

```python theme={null}
from deepagents.backends import CompositeBackend


composite = CompositeBackend(
    default=sandbox,
    routes={"/memories/": memories_backend},
)

# Works: permissions are scoped to the /memories/ route
agent = create_deep_agent(
    model=model,
    backend=composite,
    permissions=[
        FilesystemPermission(
            operations=["write"],
            paths=["/memories/**"],
            mode="deny",
        ),
    ],
)
```

包含任何路由外路径的权限会引发`NotImplementedError`：

```python theme={null}
# Raises NotImplementedError: /workspace/** hits the sandbox default
try:
    create_deep_agent(
        model=model,
        backend=composite,
        permissions=[
            FilesystemPermission(
                operations=["write"],
                paths=["/workspace/**"],
                mode="deny",
            ),
        ],
    )
except NotImplementedError:
    pass

# Also raises: /** covers both routes and the default
try:
    create_deep_agent(
        model=model,
        backend=composite,
        permissions=[
            FilesystemPermission(
                operations=["read"],
                paths=["/**"],
                mode="deny",
            ),
        ],
    )
except NotImplementedError:
    pass
```

:::

:::js

在使用`CompositeBackend`带有沙盒默认值时，每个权限路径都必须限定在已知路由前缀下。沙盒支持任意命令执行，因此仅基于路径的权限无法阻止通过 shell 命令的文件系统访问。将权限限定在路由特定的[后端](https://langchain-docs-zh.mintlify.site/langchain/oss/deepagents/backends.md)可避免此冲突。

```ts theme={null}
const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});
const agent = createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/memories/**"], mode: "deny" },
  ],
});
if (!agent) throw new Error("composite-backend: agent not created");
```

包含任何路由外路径的权限在构建时抛出：

```ts theme={null}
const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/workspace/**"], mode: "deny" },
  ],
});

createDeepAgent({
  model,
  backend: composite,
  permissions: [{ operations: ["read"], paths: ["/**"], mode: "deny" }],
});
```

:::

***

> 官方原文：[src/oss/deepagents/permissions.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/deepagents/permissions.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.