《AI Agent 产品开发·任务定义与能力边界》8.2 权限面:它能碰哪些数据与动作

权限面不是配置项,而是产品文档的一部分。本节把权限分成只读、受限写、完全写三级,给出可核对的权限清单模板,用 C Runner 的改价动作拆解最小权限,说明权限回收与自主档之间的关系,并把权限面写成可运行的检查模型,帮助团队在评审会上发现过度授权。

以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。

上一节把系统拆成了读、写、触发三类接口。这一节要往下走一层:同样是写接口,它能写哪些字段?同样是读接口,它能读哪些数据?这些问题的答案如果只存在于配置文件和运维脚本里,产品团队就无法在评审会上判断它是否越界。

权限面就是这份答案的产品化表达。它把「Agent 能碰什么」写成一张人能读、能核对、能审计的清单,而不是散落在 API key、角色和数据库视图里的默认值。

权限面为什么必须写在产品文档里

权限是产品行为的一部分。用户看到的「它帮我改了价格」,背后是「它有改价权限」;用户没看到的「它读了我的合同金额」,背后是「它有读合同字段的权限」。只把权限当技术配置,会带来三个后果。

第一,产品评审无法判断风险。评审会上大家讨论交互、话术和准确率,没有人讨论「它到底能读多少客户数据」。等到上线后安全团队来问,才发现 Agent 的账号权限比任务需要的大得多。

第二,权限变更没有产品记录。运维为了排查问题临时加了一个读权限,后来忘了收回。产品文档里没有这条权限,就没人知道它曾经存在。

第三,出事后无法划清责任。是模型判断错了,还是权限本来就给多了?如果权限面没有写清楚,复盘只能停在「模型不稳定」这种无法整改的结论上。

权限面不需要写成安全规范,它只需要回答四个问题:能读什么、能写什么、能触发什么、这些权限什么时候收回。四个问题都能用清单回答,就不需要靠口头约定。

三级权限:只读、受限写、完全写

把权限压成三级,是为了让产品、技术和业务用同一套语言讨论。级别不是按系统重要性分,而是按副作用的可逆性分。

级别能做什么不能做什么典型例子回收难度
只读读取任务所需字段修改任何状态读工单、读商品、读数据包低
受限写在限定对象和字段内写入跨对象写入、批量写入改队列、改价格、写草稿中
完全写写入任意允许对象,含不可逆动作超出授权范围的操作发布报告、下架商品、发通知高

只读的边界是「任务需要的字段」。A Relay 分诊需要工单正文、客户等级和历史工单,不需要客户的合同金额和付款记录。只读权限要按字段开,不是按表开。

受限写的边界是「对象 + 字段 + 条件」。C Runner 改价格,限定在单个 SKU 的价格字段,且必须带前值、后值、原因和回滚句柄。它不能批量改价,不能改成本字段,也不能在没有前值的情况下写入。

完全写不是「更高级的受限写」,而是另一类责任。发布报告、下架商品、发通知,这些动作一旦发生,外部世界已经改变。完全写权限应该尽量少给,给了就要配审计和人工复核。

三级之外还有一个常见误区:把「管理员权限」当成「完全写」。管理员权限能改权限本身,比完全写更危险。Agent 不应该拥有修改自己权限的能力,这条边界没有例外。

最小权限原则的产品表达

最小权限原则在工程里常被写成「只授予完成任务所需的最小权限」。这句话在产品上要再具体一步:最小权限不是「少给几个按钮」,而是每条权限都能对应到一个任务步骤。

可以用三个问题检查一条权限是否必要:

  1. 这个任务步骤不做会怎样? 如果跳过它,任务仍然能完成,这条权限就不必要。
  2. 有没有更小的范围? 能读单条工单,就不要读整个队列;能改一个字段,就不要给整行写权限。
  3. 这个权限什么时候失效? 临时权限要有到期时间,项目结束要回收,人员变动要重审。

A Relay 的例子:它需要读工单来分诊,需要写队列和优先级来给出建议,需要读模板编号来生成首响建议。它不需要读客户合同,不需要写工单状态为「已解决」,也不需要直接给客户发消息。把这三条不需要的权限去掉,权限面就从「工单系统读写」缩小到「读当前工单、写队列与优先级、读模板」。

B Quill 的例子:它需要读客户数据包和上月报告,需要写图表和 Markdown 初稿。它不需要发布到客户门户,也不需要读其他客户的报告。写权限限定在草稿目录,是一个产品级的最小权限设计。

最小权限的收益不只是安全。权限越小,失败后的影响面越小,回滚越容易,审计越简单。一个只能写草稿的 Agent,出错时最坏结果是重写;一个能直接发布的 Agent,出错时最坏结果是客户已经看到。

C Runner 的改价动作拆解

改价是执行档 Agent 最典型也最危险的动作。它同时涉及读、写和外部影响,适合用来检查权限面是否写全。

一次合规的改价至少包含六个要素:

要素作用缺失后果
SKU限定改哪个商品可能改错商品
前值证明改之前是什么无法回滚、无法核对
后值明确改成什么执行结果不可验证
原因解释为什么改审计时无法判断合理性
回滚句柄出事时怎么撤回只能人工翻日志
执行人/Agent 标识谁发起的责任无法归属

C Runner 月任务量 13,200 个,任务类型里价格异常占 30%。按这个比例,价格相关任务是它最高频的写动作之一。自动完成率 78%,其余 22% 转人工;审计抽检比例 8%,单次复核 12 分钟。这组数字说明:C 并不是「改完就完」,它有一层事后审计在兜底。

但审计不能替代权限面。审计是事后发现,权限是事前限制。如果 C 的改价权限没有限定字段和对象,审计只能告诉你「它改了很多」,不能阻止它改错。正确的顺序是:先用权限面缩小它能改的范围,再用审计检查它改得对不对。

改价权限还应该带条件。比如只允许在任务类型为「价格异常」时触发,只允许改单个 SKU,只允许在有前值和回滚句柄时写入。这些条件不是技术细节,而是产品规则:它们决定用户在什么情况下会看到「Agent 改了价格」,什么情况下会看到「需要人工确认」。

权限清单模板

一张权限清单不需要很长,但每一行都要能被核对。推荐用下面这张表:

动作级别数据范围触发条件可逆授权人复核周期
读工单只读当前工单 + 客户等级新工单进入是支持主管每季度
写队列受限写当前工单的队列与优先级生成分诊建议后是支持主管每季度
改价格受限写单个 SKU 的价格字段价格异常任务是运营主管每月
发通知完全写供应商联系人库存异常且人工确认否运营主管每月

这张表里最重要的两列是「触发条件」和「可逆」。触发条件把权限和任务步骤绑定,防止权限被用在任务之外;可逆决定这条权限需不需要额外的审计和回滚设计。

清单还要写「不授予」的部分。比如「不授予批量改价」「不授予修改权限」「不授予读取合同金额」。不授予的权限同样要有人负责,否则下一次需求评审时,它会以「顺便开一下」的方式被加回来。

权限与自主档的关系

权限面回答「能碰什么」,自主档回答「谁做决定」。两者相关,但不是一回事。

案例自主档权限面特征人在哪里
A Relay建议读工单、写队列、读模板人确认每一条建议
B Quill草稿读数据包、写草稿目录人审改后发布
C Runner执行读商品、改价格库存、发通知人事后审计,22% 转人工

A 的权限面可以写队列,但它不直接发消息;B 的权限面可以写初稿,但它不发布;C 的权限面可以改价格,但它有审计和转人工。三家的权限面都比「系统支持的最大权限」小,小出来的部分就是责任边界。

一个常见的错误是「权限跟着自主档一起放大」:既然 C 是执行档,就给它全部写权限;既然 A 是建议档,就只给它读权限。前者会让 C 的风险超出审计能力,后者会让 A 的建议无法落地。权限面要按任务步骤设计,不是按档位一刀切。

反过来,权限面也能约束自主档。如果一条动作找不到可回滚方案,它就不应该进入执行档,哪怕模型准确率很高。C 的错误中 86% 可回滚,剩下 14% 不可回滚,对应不可回滚错误率 0.238%。这个数字之所以能接受,是因为权限面和审计一起把不可回滚的动作限制在很小的范围里。

把权限面写成可运行的模型

下面这个模型把三级权限、动作清单和改价检查写在一起。canPerform 判断授予级别是否覆盖动作,isLeastPrivilege 判断是否恰好等于所需级别,checkPriceChange 检查改价六要素是否齐全。

// file: src/task/08-2-permission-surface.ts
// tier: L2
// verify: node --test test/task/08-2-permission-surface.test.ts

// 权限面:把「能碰什么数据、能做什么动作」写成可核对的清单。
// 三级权限按副作用递增,产品文档里必须逐项列出,而不是藏在配置里。

import { byKey, type Profile } from "../cases.ts";

export type Level = "read-only" | "restricted-write" | "full-write";

export const LEVEL_ORDER: readonly Level[] = [
  "read-only",
  "restricted-write",
  "full-write",
];

export type Action = {
  readonly name: string;
  readonly level: Level;
  readonly data: readonly string[];
  readonly reversible: boolean;
};

export type PermissionList = {
  readonly caseKey: Profile["key"];
  readonly actions: readonly Action[];
};

export function levelOf(
  list: PermissionList,
  actionName: string,
): Level | null {
  const found = list.actions.find((action) => action.name === actionName);
  return found ? found.level : null;
}

export function canPerform(
  list: PermissionList,
  actionName: string,
  granted: Level,
): boolean {
  const required = levelOf(list, actionName);
  if (required === null) return false;
  return LEVEL_ORDER.indexOf(granted) >= LEVEL_ORDER.indexOf(required);
}

// 最小权限:授予级别恰好等于动作所需级别,不多给一档。
export function isLeastPrivilege(
  list: PermissionList,
  actionName: string,
  granted: Level,
): boolean {
  return levelOf(list, actionName) === granted;
}

export const PERMISSIONS: Record<Profile["key"], PermissionList> = {
  A: {
    caseKey: "A",
    actions: [
      {
        name: "read-ticket",
        level: "read-only",
        data: ["工单正文", "客户等级", "历史工单"],
        reversible: true,
      },
      {
        name: "write-queue",
        level: "restricted-write",
        data: ["队列归属", "优先级"],
        reversible: true,
      },
      {
        name: "send-reply",
        level: "full-write",
        data: ["首响正文"],
        reversible: false,
      },
    ],
  },
  B: {
    caseKey: "B",
    actions: [
      {
        name: "read-data-pack",
        level: "read-only",
        data: ["客户数据包", "上月报告"],
        reversible: true,
      },
      {
        name: "write-draft",
        level: "restricted-write",
        data: ["草稿目录"],
        reversible: true,
      },
      {
        name: "publish-report",
        level: "full-write",
        data: ["客户门户"],
        reversible: false,
      },
    ],
  },
  C: {
    caseKey: "C",
    actions: [
      {
        name: "read-catalog",
        level: "read-only",
        data: ["价格", "库存", "上下架状态"],
        reversible: true,
      },
      {
        name: "change-price",
        level: "restricted-write",
        data: ["价格"],
        reversible: true,
      },
      {
        name: "change-stock",
        level: "restricted-write",
        data: ["库存"],
        reversible: true,
      },
      {
        name: "take-down",
        level: "full-write",
        data: ["上下架状态"],
        reversible: true,
      },
      {
        name: "notify",
        level: "full-write",
        data: ["供应商联系方式"],
        reversible: false,
      },
    ],
  },
};

// C 的改价动作:必须同时带前值、后值、原因与回滚句柄,缺一项就不允许执行。
export type PriceChange = {
  readonly sku: string;
  readonly beforeCents: number;
  readonly afterCents: number;
  readonly reason: string;
  readonly rollbackHandle: string;
};

export type PriceChangeCheck =
  | { ok: true; change: PriceChange }
  | { ok: false; missing: readonly string[] };

export function checkPriceChange(
  input: Partial<PriceChange>,
): PriceChangeCheck {
  const missing: string[] = [];
  if (!input.sku) missing.push("sku");
  if (typeof input.beforeCents !== "number") missing.push("beforeCents");
  if (typeof input.afterCents !== "number") missing.push("afterCents");
  if (!input.reason) missing.push("reason");
  if (!input.rollbackHandle) missing.push("rollbackHandle");
  if (missing.length > 0) return { ok: false, missing };
  return { ok: true, change: input as PriceChange };
}

// 权限面的规模由任务量决定:同样一级权限,落在 13,200 个任务上就是另一种风险。
export function monthlyExposure(caseKey: Profile["key"]): number {
  return byKey(caseKey).monthlyTasks;
}

模型里最值得看的是 isLeastPrivilege。canPerform 只回答「能不能做」,管理员权限对任何动作都返回 true;isLeastPrivilege 回答「是不是给多了」,它要求授予级别恰好等于动作所需级别。产品评审时,后者比前者更有用,因为它能发现「能读工单却给了完全写」这种过度授权。

checkPriceChange 把改价的前值、后值、原因和回滚句柄做成必填项。缺任何一项,函数返回缺失字段列表,而不是静默通过。这是一个很小的设计,但它把「改价必须可回滚」从口号变成了调用方无法绕过的约束。

monthlyExposure 把案例的任务量带进权限讨论。同样是「改价格」这一级权限,落在 13,200 个任务上和落在 606 份报告上,暴露规模完全不同。权限面不能只看级别,还要看它被调用的频次。

权限回收与定期复核

权限面不是一次画完就结束。权限会过期、人员会变动、任务会调整,任何一个变化都可能让原来的最小权限变成过度权限。

回收机制至少要有三条:

  1. 到期回收。 临时权限写到期时间,到期自动失效,不依赖人记得。
  2. 项目回收。 试点结束、系统下线、任务迁移时,权限清单要跟着关闭,而不是留在账号里。
  3. 定期复核。 按上表的复核周期重看每一行:动作还需要吗?数据范围还能缩小吗?触发条件还准确吗?

复核要有人签字。不是形式上的审批,而是让业务负责人确认「这条权限现在仍然是完成任务的必要条件」。没有人签字的权限,默认应该收回。

权限回收还要考虑 Agent 的特殊性:它的权限通常挂在一个服务账号上,不像人账号那样有入职离职流程。服务账号的权限一旦加上,很容易一直留着。所以权限清单里要有「授权人」和「复核周期」两列,把人的责任重新挂回去。

小结

  • 权限面是产品文档的一部分,不是藏在配置里的默认值。
  • 三级权限按副作用可逆性分:只读、受限写、完全写。
  • 最小权限的产品表达是「每条权限对应一个任务步骤」,不是「少给几个按钮」。
  • 受限写的边界是对象、字段和条件三件事,缺一件就可能越界。
  • C Runner 的改价必须带 SKU、前值、后值、原因、回滚句柄和执行者标识。
  • 权限面和自主档相关但不等同:权限按任务步骤设计,不按档位一刀切。
  • 权限要能到期回收、随项目关闭、定期复核,并且有人签字。
  • 不授予的权限也要写进清单,否则会在下一次需求里被顺手加回来。

阅读导航:上一节:8.1 能接什么:系统集成的产品地图 · 下一节:8.3 接不了的时候怎么办 。

常见错误与边界

  1. 把权限当运维细节。 权限决定 Agent 能造成多大的影响,属于产品边界;只让运维管,产品评审就无法判断风险。
  2. 按系统给权限,而不是按字段给。 「工单系统读写」这种授权粒度太粗,会把任务不需要的字段一起打开。
  3. 把管理员权限当成完全写。 管理员能改权限本身,比任何业务写操作都危险;Agent 不应拥有修改自身权限的能力。
  4. 用审计替代权限限制。 审计是事后发现,权限是事前限制;没有权限面,审计只能告诉你错了很多,不能阻止它错。
  5. 权限只加不减。 临时权限没有到期时间、项目结束不回收,权限面会随着版本越来越宽。
  6. 让自主档决定权限。 执行档不等于全权限,建议档也不等于只读;权限要按任务步骤逐条论证。

这一节写的是「它能碰什么」。下一节处理一个更常见的情况:有些系统就是接不了,产品应该怎么把「做不到」说清楚。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图