AgentSpace权限控制平面深度剖析:如何用资源树与Actor反查治理AI权限边界
AgentSpace权限控制平面深度剖析:如何用资源树与Actor反查治理AI权限边界
AgentSpace 的权限控制平面(Permission Center)是这套 human + agent 协作工作空间的核心治理能力:它把工作区里的成员角色、频道、Agent、Runtime、文档、OAuth 凭据等全部授权关系,组织成一棵可遍历的资源树,并支持按 Actor 反查任何一个真人或 Agent 到底持有哪些权限。管理员可以在 /settings/permissions 页面一键撤销授权、批准访问申请,并依靠内置的权限诊断机制提前发现"孤儿授权""凭据失效"等漂移问题,从而把 AI 的权限边界牢牢控制在治理范围内。
为什么 Agent 权限治理需要一个"控制平面"
在 AgentSpace 中,Agent 是有 owner、有岗位、有技能与知识绑定的数字员工,它可能:
- 被频道成员直接调用;
- 绑定到某台远程 Runtime(执行机器);
- 持有 Google Workspace 的 scoped OAuth 委托;
- 对特定文档拥有 viewer/editor/forwarder 权限;
- 通过 daemon token 注册远程 daemon。
这些授权分散在不同的模块里,如果逐处检查,很容易漏掉某条"隐蔽授权"。AgentSpace 的答案是把所有授权关系收敛到一个统一模型里——在 permissions.ts 中,核心由四个概念构成:
| 概念 | 说明 | 源码位置 |
|---|---|---|
| Subject(授权主体) | human / agent / daemon_token / oauth_credential / external_guest / system 六类 |
permissions.ts#L44-L50 |
| Resource(资源节点) | workspace、channel、agent、runtime、daemon、document、skill、knowledge_page 等 | permissions.ts#L52-L69 |
| Source(授权来源) | workspace_role、direct_grant、channel_participant、oauth_delegation 等 17 种 | permissions.ts#L71-L88 |
| Binding(绑定关系) | "谁、在哪个资源上、拥有什么权限、来自哪里、可否撤销" 的一条完整记录 | permissions.ts#L95-L108 |
入口函数是 getWorkspacePermissionCenterSync,它一次性产出 PermissionCenterData:资源树 tree、Actor 摘要 actors、诊断 diagnostics 和用于下拉选择的 catalog(成员、Agent、技能、知识页清单)。
如何进入权限控制平面:资源树与 Actor 反查双视图
在 Web 端进入 设置 → 权限(路径 /settings/permissions,见 settings-sections.ts#L40)即可打开权限控制平面。界面由 PermissionsCenterSection 实现,顶部提供两个标签页和一个全局筛选框:
- 资源树(Resources):以 workspace 为根节点,逐级展开频道、Agent、Runtime、daemon、文档、技能、知识页、外部授权策略等。每个节点旁显示授权绑定数量和状态点(有效 / 待处理 / 已撤销 / 异常)。
- Actor 反查(Actors):反向视角——列出每个真人、Agent、daemon token、外部访客,它持有哪些资源上的哪些权限、来自哪个 source。这是审计场景的关键能力:想知道"某个 Agent 到底能碰什么",切到该视图即可得到完整清单。
两种视图的数据由同一棵树换算而来。Actor 反查的核心逻辑在 getWorkspaceActorPermissionSummarySync:递归遍历整棵资源树,把每个 binding 按 subjectType:subjectId 聚合到对应 Actor 名下,再经 dedupeActorPermissions 去重,并按 human → agent → daemon_token → oauth_credential → external_guest → system 的固定顺序排序(见 subjectTypeRank),最终形成一份可读、可检索的"权限账单"。
选中任意节点后,右侧检查器会展示三部分内容:节点专属的操作面板(如授予 Runtime use、创建/吊销 daemon token、调整文档角色)、该节点的授权关系卡片(BindingCard,含来源、状态与撤销按钮),以及挂在节点上的诊断项。
关键设计:最小可见性与"继承"标记
权限树并非对所有角色展示相同内容。构建上下文时(buildPermissionContext),非 manager 成员只能看到:
- 自己是参与者的频道(含直接会话的隐私规则);
- 自己拥有的、或在可见频道中被启用的 Agent;
- 自己持有 grant 的 Runtime。
诊断信息同样按可见性过滤(isDiagnosticVisibleToActor)。而 owner/admin 的权限则以 inherited(继承)状态出现在各资源节点上,由 buildWorkspaceManagerInheritedBindings 生成,并通过 inheritedFromNodeId 指回 workspace 根节点——这意味着"管理员为什么能看到一切"也在树里一目了然,而不是一条隐式规则。
权限诊断:让 AI 权限漂移在发生前被看见
除了"看得全",控制平面还要"查得早"。buildPermissionDiagnostics 内置了一组巡检规则,覆盖最常见的治理盲区:
| 诊断场景 | 严重级别 | 含义 |
|---|---|---|
| Agent 的 Google 委托指向缺失/已撤销的 OAuth 凭据 | critical | Agent 的 Google Workspace 能力会静默失效 |
外部文档标记为 permission_error / missing |
critical | Google Drive 权限同步失败,需重新同步 |
| 文档 collaborator 不是活跃工作区成员 | warning | 存在"孤儿授权",人员离职后仍残留 |
| Agent owner 缺少对应 Runtime 的直接 grant | warning | 数字员工的执行链与授权链不一致 |
| daemon token 超过 90 天未使用 | warning | 闲置凭据建议吊销 |
| 频道遗留成员快照与参与者记录不一致 | warning | 数据迁移残留,需核对 |
诊断项会按节点挂回资源树(attachDiagnostics),只要存在 critical 级别诊断,对应节点状态直接置为 error,在 UI 上以红色状态点突出,帮助管理员优先处理高风险授权。
常用治理操作清单
在权限控制平面内可以完成的典型操作(UI 操作面板 + Server Actions 实现):
- 成员与邀请:创建工作区邀请、重新签发、撤销邀请、更新成员角色、移除成员。
- 频道访问:批准/拒绝访问申请、撤销频道邀请、添加/移除频道成员。
- Agent 治理:设置"频道成员可调用"开关、绑定/解绑 Runtime、分配技能与知识页、批准/拒绝 Agent 访问申请。
- 文档权限:添加/移除文档 collaborator、调整 viewer/editor/forwarder/owner 角色、授予或撤销 Agent 的显式文档权限、处理 Agent 发起的文档权限请求。
- 外部授权:撤销 Agent 的 Google Workspace 委托、断开 Google OAuth、同步 Google Drive 权限。
- daemon 安全:创建(一次性显示)与吊销 daemon token。
每次变更都会触发 revalidatePermissions 联动刷新 /settings/permissions、/agents、/knowledge 等页面,保证控制平面、Agent 展板与知识页看到的状态始终一致。
延伸阅读:核心源码路径
- 权限模型与树构建(含资源树、Actor 反查、诊断):packages/services/src/permissions/permissions.ts
- 权限单元测试:packages/services/src/permissions/permissions.test.ts
- Web 端权限中心 UI(双视图 + 操作面板 + 诊断卡片):apps/web/features/permissions/permissions-center-section.tsx
- 全部权限变更 Server Actions:apps/web/features/permissions/actions.ts
- 设置分区定义(
/settings/permissions路由):apps/web/features/settings/settings-sections.ts - 产品文档中的权限控制面能力表:README_ZH.md#L383-L398
小结
AgentSpace 的权限控制平面用"资源树 + Actor 反查 + 权限诊断"三板斧,把 AI 团队的授权治理从散落各处的配置项变成了单一事实来源:
- 资源树回答"这个资源上都有谁、什么权限";
- Actor 反查回答"这个真人或 Agent 能碰哪些资源";
- 诊断回答"哪些授权正在漂移、哪些凭据即将失效"。
配合最小可见性过滤与继承标记,管理员和成员各看到与自己相符的视图,而 owner/admin 的每个操作都有明确入口与撤销路径——这正是让 Agent 团队能够规模化使用、又始终可控的关键所在。
