权限控制

为什么需要它

你敢让 Agent 直接操作整个文件系统吗？

开始之前

基本用法

用几行代码禁止 Agent 写入任何文件

将 FilesystemPermission 规则列表传递给 createDeepAgent 的 permissions 参数。规则按声明顺序评估，第一条匹配的规则生效。如果没有任何规则匹配，操作被允许。

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["write"],    // 只限制写操作（read 不受影响）
      paths: ["/**"],           // /** 匹配所有路径
      mode: "deny",             // 拒绝该操作
    },
  ],
});
// Agent 现在只能读取文件，不能写入或修改任何文件

规则结构

每条 FilesystemPermission 包含三个字段

隔离工作区

只允许 Agent 在指定目录下读写

最常见的场景：把 Agent 限制在一个工作区目录内，拒绝所有外部访问。这是"白名单 + 兜底拒绝"的经典模式。

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    // 第 1 条：允许在 /workspace/ 目录下读写（具体允许在前）
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],      // ** 匹配任意层级的子目录
      mode: "allow",
    },
    // 第 2 条：拒绝所有其他路径的读写（兜底规则）
    {
      operations: ["read", "write"],
      paths: ["/**"],              // 捕获所有未被前面规则匹配的路径
      mode: "deny",
    },
  ],
});

保护敏感文件

拒绝访问特定文件，允许其余工作区操作

实际开发中，工作区里总有几个敏感文件：.env、密钥目录、示例数据等。你需要允许 Agent 读写工作区，但排除这些危险路径。

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    // 第 1 条：拒绝访问 .env 和 examples 目录（具体拒绝在前）
    {
      operations: ["read", "write"],
      paths: ["/workspace/.env", "/workspace/examples/**"],  // 精确匹配敏感路径
      mode: "deny",
    },
    // 第 2 条：允许工作区其余部分的读写
    {
      operations: ["read", "write"],
      paths: ["/workspace/**"],
      mode: "allow",
    },
    // 第 3 条：拒绝所有工作区以外的访问
    {
      operations: ["read", "write"],
      paths: ["/**"],
      mode: "deny",
    },
  ],
});

// 先允许 /workspace/**
// 再拒绝 /workspace/.env
// → .env 的拒绝永远不会被评估
// 因为 /workspace/** 先匹配了！

// 先拒绝 /workspace/.env
// 再允许 /workspace/**
// → .env 被拒绝，其余被允许

规则顺序对比

顺序决定一切——用一个完整的正反例来说明

// ✅ 正确：具体规则在前，宽泛规则在后
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[] = [
  // 先允许工作区——.env 也被匹配了！
  { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
  // 这条拒绝永远不会对 .env 生效
  { operations: ["read", "write"], paths: ["/workspace/.env"], mode: "deny" },
  // 兜底拒绝
  { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
];

只读记忆

让 Agent 读取记忆但不能修改——组织级策略的典型场景

想象一下：公司维护了一个共享知识库，所有 Agent 可以查阅，但只允许应用代码更新。用权限规则轻松实现：

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,
});
// Agent 可以读取 /memories/ 和 /policies/ 下的内容
// 但不能修改它们

完全禁止访问

阻止所有读写——最严格的基线配置

某些场景下你需要一个"什么都做不了"的 Agent 作为起点，然后根据需要逐步放开权限。

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    {
      operations: ["read", "write"],  // 同时限制读和写
      paths: ["/**"],          // /** 匹配所有路径
      mode: "deny",            // 拒绝所有读写操作
    },
  ],
});
// Agent 的文件系统工具完全不可用
// 可以在此基础上叠加 allow 规则逐步放开

permissions: [
  // 在 deny all 之前
  // 插入具体的 allow 规则
  {
    operations: ["read"],
    paths: ["/workspace/**"],
    mode: "allow",
  },
  // 兜底拒绝
  {
    operations: ["read", "write"],
    paths: ["/**"],
    mode: "deny",
  },
]

子 Agent 权限

子 Agent 默认继承父 Agent 权限，但可以完全替换

子 Agent 的权限机制有三个要点：

const agent = createDeepAgent({
  model,
  backend,
  permissions: [
    { operations: ["read", "write"], paths: ["/workspace/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
  subagents: [
    {
      name: "auditor",
      description: "只读代码审查员",
      systemPrompt: "Review the code for issues.",
      // 完全替换父级权限——只允许读取工作区
      permissions: [
        { operations: ["write"], paths: ["/**"], mode: "deny" },
        { operations: ["read"], paths: ["/workspace/**"], mode: "allow" },
        { operations: ["read"], paths: ["/**"], mode: "deny" },
      ],
    },
  ],
});

组合后端权限

使用 CompositeBackend 时，权限路径必须限定在路由前缀内

CompositeBackend 把不同的路径路由到不同的后端。权限路径必须限定在已注册的路由前缀之下，否则会在构建时抛出错误。

const sandbox = new StateBackend();
const memoriesBackend = new StateBackend();
const composite = new CompositeBackend(sandbox, {
  "/memories/": memoriesBackend,  // 只注册了 /memories/ 路由
});

// ✅ 正确：路径限定在路由前缀内
const agent = createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/memories/**"], mode: "deny" },
  ],
});

// ❌ 错误：/workspace/ 不在路由范围内
createDeepAgent({
  model,
  backend: composite,
  permissions: [
    { operations: ["write"], paths: ["/workspace/**"], mode: "deny" },
  ],
  // → 构建时报错！
});

// ❌ 错误：/** 匹配所有路径，包含超出路由范围的路径
createDeepAgent({
  model,
  backend: composite,
  permissions: [{ operations: ["read"], paths: ["/**"], mode: "deny" }],
  // → 构建时报错！
});

权限与策略钩子

知道何时用权限规则、何时用后端策略钩子

速查清单

5 个常用权限模式——直接复制使用

permissions: [
  { operations: ["write"],
    paths: ["/**"], mode: "deny" },
]

permissions: [
  { operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow" },
  { operations: ["read", "write"],
    paths: ["/**"], mode: "deny" },
]

permissions: [
  { operations: ["read", "write"],
    paths: ["/workspace/.env"],
    mode: "deny" },
  { operations: ["read", "write"],
    paths: ["/workspace/**"],
    mode: "allow" },
  { operations: ["read", "write"],
    paths: ["/**"], mode: "deny" },
]

permissions: [
  { operations: ["write"],
    paths: ["/memories/**"],
    mode: "deny" },
]

本章回顾

权限控制是 Agent 安全的最后一道防线

延伸阅读