以下人物、公司与数字均为教学假设,不构成对任何真实产品的评价。
上一节把系统拆成了读、写、触发三类接口。这一节要往下走一层:同样是写接口,它能写哪些字段?同样是读接口,它能读哪些数据?这些问题的答案如果只存在于配置文件和运维脚本里,产品团队就无法在评审会上判断它是否越界。
权限面就是这份答案的产品化表达。它把「Agent 能碰什么」写成一张人能读、能核对、能审计的清单,而不是散落在 API key、角色和数据库视图里的默认值。
权限面为什么必须写在产品文档里
权限是产品行为的一部分。用户看到的「它帮我改了价格」,背后是「它有改价权限」;用户没看到的「它读了我的合同金额」,背后是「它有读合同字段的权限」。只把权限当技术配置,会带来三个后果。
第一,产品评审无法判断风险。评审会上大家讨论交互、话术和准确率,没有人讨论「它到底能读多少客户数据」。等到上线后安全团队来问,才发现 Agent 的账号权限比任务需要的大得多。
第二,权限变更没有产品记录。运维为了排查问题临时加了一个读权限,后来忘了收回。产品文档里没有这条权限,就没人知道它曾经存在。
第三,出事后无法划清责任。是模型判断错了,还是权限本来就给多了?如果权限面没有写清楚,复盘只能停在「模型不稳定」这种无法整改的结论上。
权限面不需要写成安全规范,它只需要回答四个问题:能读什么、能写什么、能触发什么、这些权限什么时候收回。四个问题都能用清单回答,就不需要靠口头约定。
三级权限:只读、受限写、完全写
把权限压成三级,是为了让产品、技术和业务用同一套语言讨论。级别不是按系统重要性分,而是按副作用的可逆性分。
| 级别 | 能做什么 | 不能做什么 | 典型例子 | 回收难度 |
|---|---|---|---|---|
| 只读 | 读取任务所需字段 | 修改任何状态 | 读工单、读商品、读数据包 | 低 |
| 受限写 | 在限定对象和字段内写入 | 跨对象写入、批量写入 | 改队列、改价格、写草稿 | 中 |
| 完全写 | 写入任意允许对象,含不可逆动作 | 超出授权范围的操作 | 发布报告、下架商品、发通知 | 高 |
只读的边界是「任务需要的字段」。A Relay 分诊需要工单正文、客户等级和历史工单,不需要客户的合同金额和付款记录。只读权限要按字段开,不是按表开。
受限写的边界是「对象 + 字段 + 条件」。C Runner 改价格,限定在单个 SKU 的价格字段,且必须带前值、后值、原因和回滚句柄。它不能批量改价,不能改成本字段,也不能在没有前值的情况下写入。
完全写不是「更高级的受限写」,而是另一类责任。发布报告、下架商品、发通知,这些动作一旦发生,外部世界已经改变。完全写权限应该尽量少给,给了就要配审计和人工复核。
三级之外还有一个常见误区:把「管理员权限」当成「完全写」。管理员权限能改权限本身,比完全写更危险。Agent 不应该拥有修改自己权限的能力,这条边界没有例外。
最小权限原则的产品表达
最小权限原则在工程里常被写成「只授予完成任务所需的最小权限」。这句话在产品上要再具体一步:最小权限不是「少给几个按钮」,而是每条权限都能对应到一个任务步骤。
可以用三个问题检查一条权限是否必要:
- 这个任务步骤不做会怎样? 如果跳过它,任务仍然能完成,这条权限就不必要。
- 有没有更小的范围? 能读单条工单,就不要读整个队列;能改一个字段,就不要给整行写权限。
- 这个权限什么时候失效? 临时权限要有到期时间,项目结束要回收,人员变动要重审。
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 份报告上,暴露规模完全不同。权限面不能只看级别,还要看它被调用的频次。
权限回收与定期复核
权限面不是一次画完就结束。权限会过期、人员会变动、任务会调整,任何一个变化都可能让原来的最小权限变成过度权限。
回收机制至少要有三条:
- 到期回收。 临时权限写到期时间,到期自动失效,不依赖人记得。
- 项目回收。 试点结束、系统下线、任务迁移时,权限清单要跟着关闭,而不是留在账号里。
- 定期复核。 按上表的复核周期重看每一行:动作还需要吗?数据范围还能缩小吗?触发条件还准确吗?
复核要有人签字。不是形式上的审批,而是让业务负责人确认「这条权限现在仍然是完成任务的必要条件」。没有人签字的权限,默认应该收回。
权限回收还要考虑 Agent 的特殊性:它的权限通常挂在一个服务账号上,不像人账号那样有入职离职流程。服务账号的权限一旦加上,很容易一直留着。所以权限清单里要有「授权人」和「复核周期」两列,把人的责任重新挂回去。
小结
- 权限面是产品文档的一部分,不是藏在配置里的默认值。
- 三级权限按副作用可逆性分:只读、受限写、完全写。
- 最小权限的产品表达是「每条权限对应一个任务步骤」,不是「少给几个按钮」。
- 受限写的边界是对象、字段和条件三件事,缺一件就可能越界。
- C Runner 的改价必须带 SKU、前值、后值、原因、回滚句柄和执行者标识。
- 权限面和自主档相关但不等同:权限按任务步骤设计,不按档位一刀切。
- 权限要能到期回收、随项目关闭、定期复核,并且有人签字。
- 不授予的权限也要写进清单,否则会在下一次需求里被顺手加回来。
阅读导航:上一节:8.1 能接什么:系统集成的产品地图 · 下一节:8.3 接不了的时候怎么办 。
常见错误与边界
- 把权限当运维细节。 权限决定 Agent 能造成多大的影响,属于产品边界;只让运维管,产品评审就无法判断风险。
- 按系统给权限,而不是按字段给。 「工单系统读写」这种授权粒度太粗,会把任务不需要的字段一起打开。
- 把管理员权限当成完全写。 管理员能改权限本身,比任何业务写操作都危险;Agent 不应拥有修改自身权限的能力。
- 用审计替代权限限制。 审计是事后发现,权限是事前限制;没有权限面,审计只能告诉你错了很多,不能阻止它错。
- 权限只加不减。 临时权限没有到期时间、项目结束不回收,权限面会随着版本越来越宽。
- 让自主档决定权限。 执行档不等于全权限,建议档也不等于只读;权限要按任务步骤逐条论证。
这一节写的是「它能碰什么」。下一节处理一个更常见的情况:有些系统就是接不了,产品应该怎么把「做不到」说清楚。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。