Agent 资源授权（实时决策）

面向 Agent 平台（agent-manager / worker / model-gateway）的资源级授权：关系式授权模型 + 实时决策端点 + 决策审计 + 主体配额。

模型

资源标识

agent:<id>              # Agent 实例
skill:<id>              # 技能
mcp:<server>            # MCP server 整体
mcp:<server>:<tool>     # MCP 单个工具
collection:<id>         # 知识集合

动作	所需最低关系
`call` / `invoke`	caller
`read` / `get` / `list` / `view`	viewer
`write` / `create` / `update` / `delete` / `edit` / `publish` / `execute` / `run`	editor
`manage` / `admin` / `grant` / `share`	owner

主体四级

主体类型	subject_id	说明
`agent`	平台 agent 标识（如 agent_007）	数字员工工号直授，独立成立——不依赖委托人授权，无授权的 Agent 不是可执行任务的数字员工
`user`	user_id（= sub）	个人直授
`role`	role_id	角色内全体成员
`org`	org_id	组织内全体成员

判定顺序：平台 admin（admin:manage）直接放行 → agent → user → role → org，命中即停。 agent 是最具体的主体（精确到实例），命中后 reason=agent_grant:<relation>；撤销其授权后立即回退到委托人链路或 deny。

嵌套派生

mcp:<server> 级授权自动覆盖该 server 的全部工具（mcp:erp-read 授权 → mcp:erp-read:query_erp 放行）。collection → 文档的包含关系由平台侧计算后落授权记录。

决策端点

每次工具调用 / 装配判定实时请求，无 TTL 窗口，撤销立即生效。subject 必填（委托人 user，= OIDC sub）——Agent 代用户干活时的 org 隔离与委托人链路都锚定在它；context.agent_id 可选，填了才会参与 agent 直授判定与 agent 维度配额：

POST https://auth.ai-as.cc/api/authorize
Authorization: Bearer <sk_* API Key 或 client_credentials token>
Content-Type: application/json

{
  "subject": "<sub>",
  "resource": "mcp:erp-read:query_erp",
  "action": "call",
  "context": { "agent_id": "agent_007", "run_id": "r-123", "trace_id": "..." }
}

响应：

{
  "decision": "allow",
  "reason": "user_grant",
  "trace_id": "..."
}

字段	说明
`decision`	`allow` / `deny`
`reason`	`platform_admin` / `agent_grant:<relation>` / `user_grant:<relation>` / `role_grant:<relation>` / `org_grant:<relation>`（命中主体与关系，如 `agent_grant:caller`）/ `no_grant` / `insufficient_relation` / `unknown_action` / `quota_exceeded` / `resource_not_found`（资源未注册，fail-closed）/ `org_mismatch`（跨 org 资源）
`trace_id`	取 `context.trace_id` 透传（与平台 X-Trace-Id 贯通），缺省自动生成
`remaining_quota` / `quota_limit`	配置了主体配额时返回

调用方权限：API Key 或 M2M client 的 permissions 须包含 agent:authz:decide。

每次决策（含 deny）落决策审计表，可按 subject / agent_id / resource / decision / trace_id 检索（后台「Agent 授权 → 决策审计」，或 GET /api/admin/authz/decisions?subject=&agent_id=&resource=）。

标准契约（AuthZEN 1.0 · 业界对齐）

PEP-PDP 通信对齐 OpenID Authorization API 1.0（Keycloak / Janssen 同款端点），决策核心与 POST /api/authorize 完全同源；平台接入推荐用标准契约，未来更换 PDP 实现无需改调用方。

单点评估 POST /access/v1/evaluation（与 /api/authorize 全等：注册检查 + org 隔离 + 关系判定 + 配额消费 + 决策审计；decision 为布尔，扩展信息入 context）：

{
  "subject": { "type": "user", "id": "42" },
  "resource": { "type": "mcp", "id": "erp-read:query_erp" },
  "action": { "name": "call" },
  "context": { "agent_id": "agent_007", "trace_id": "..." }
}

{
  "decision": true,
  "context": { "reason": "user_grant:caller", "trace_id": "...", "remaining_quota": 9988, "quota_limit": 10000 }
}

批量评估 POST /access/v1/evaluations（单批 ≤ 50）：装配预检语义——不消费配额、不落决策审计；顶层 subject / resource / action 可被 evaluations 项逐项覆盖（context 项级优先），单项格式错只影响该项（decision=false + invalid_request:*）。响应 { "evaluations": [ { "decision": true, "context": { "reason": "..." } }, ... ] } 与请求一一对应。

List-accessible（对齐 OpenFGA ListObjects）

GET /api/authz/accessible?subject=<user_id>&resource_type=<type>&action=<action>&agent_id=<可选>

反向查询「这个主体能对哪些资源执行该动作」：平台装配 Agent 时一次拿全可用 MCP / Skill / 知识库清单，无需逐资源 check（N 次 RTT）。主体链与决策一致（agent 直授 > user > role > org），未注册 / 跨 org 的资源不出现；纯查询不消费配额、不落审计。响应项含 resource / display_name / relation / via（如 via=agent_grant 标记来自 agent 直授）。

管理接口

后台「Agent 授权 → 资源授权」页面操作，或服务间用持 agent:grant:manage 权限的 API Key 调用：

端点	用途
`POST /api/admin/authz/resources`	注册/更新资源（type + key + display_name + resource_uri）
`GET /api/admin/authz/resources`	资源列表
`DELETE /api/admin/authz/resources/:id`	删除资源注册
`POST /api/admin/authz/grants`	新增/续期授权关系
`GET /api/admin/authz/grants`	授权列表（subject_type / resource_type / relation 过滤）
`DELETE /api/admin/authz/grants/:id`	撤销授权（下一次决策立即 deny）

授权关系字段：

{
  "subject_type": "agent",
  "subject_id": "agent_007",
  "resource_type": "mcp",
  "resource_key": "erp-read:query_erp",
  "relation": "caller",
  "expires_at": null
}

subject_type 支持 agent | user | role | org；agent 的 subject_id 是平台侧 Agent 标识，不要求是 user_id。

expires_at 可选（北京时间 YYYY-MM-DD HH:MM:SS），到期自动失效。

org 资源隔离（方案 A）

决策路径强校验资源归属，与授权关系独立：

资源须先注册（POST /api/admin/authz/resources），未注册资源一律 deny（resource_not_found）——注册是授权的前置，与平台 Resource 注册中心闭环；
注册时填 org_id 即资源归属；org_id 缺省视为全局资源（所有组织可用，兼容平台级公共资源）；
委托人 org 与资源 org 不匹配即 deny（org_mismatch），即使持有该资源的 owner 授权也拒——org 墙优先于 grant；
平台 admin 跨组织直通不受影响。

授权域角色开放（三角色模板 + 归属护栏）

「谁能进授权域、进来能管到哪」分两层控制：角色答功能（拿到哪些权限码），归属护栏答范围（权限码能作用到哪些资源）。三角色由 seed 幂等注入（INSERT OR IGNORE，发版即生效）：

角色	data_scope	权限码	定位
Agent 管理员	all	`agent:resource:manage` / `agent:grant:manage` / `agent:grant:list` / `agent:decision:list`	组织内 Agent 体系负责人：本组织全部资源/授权/配额管理 + 全量决策审计
Agent 开发者	self	同管理员四码	数字员工主理人：本人名下资源注册/授权/审计（范围由归属护栏收窄到本人）
Agent 观察者	all	`agent:grant:list` / `agent:decision:list`	只读：本组织授权清单与决策审计（合规/排障）

agent:authz:decide 是 PDP 服务身份权限，只进平台侧决策 Key，不进任何人的角色。

归属护栏四条（非平台 admin）

资源注册：强制 org_id = 本人组织、owner = 本人——不能替别人注册资源；
授权管理：授权对象限本人/本组织，且资源须已注册——未注册资源不给授权（与方案 A 的 fail-closed 同口径）；
清单与审计：授权清单、决策审计按角色 data_scope 过滤（all=本组织、self=本人）；manage/list 分类判定，防「只有 list 权限却借 manage 入口」的组合越权；
资源删除与配额：删除限 owner 或组织管理员；配额管理同护栏规则。

平台 admin（admin:manage）不受护栏约束（跨组织直通）。

注册默认链

「Agent 开发者」已并入新用户默认角色链：注册 / 匿名转正 / SSO 登录 / 管理台建号四条路径自动获得该角色——新用户开箱即具备自助 Agent 授权能力，无需管理员手工派权。默认角色其余部分仍以管理台「系统设置 → 注册默认角色」配置优先（未配置回退 user 角色）。

主体配额

双维度工具调用配额，决策端点实时计数（allow 才计数，deny 不消耗），任一维度超限 decision=deny, reason=quota_exceeded：

user 维度：subject_type=user，subject_id=user_id——按委托人限
agent 维度：subject_type=agent，subject_id=agent_id（取决策请求 context.agent_id）——按 Agent 限

POST /api/admin/authz/quotas
{
  "subject_type": "agent",
  "subject_id": "agent_007",
  "resource_type": "mcp",
  "limit_count": 10000,
  "window_secs": 86400
}

resource_type 支持 *（全部类型）；无配额记录的维度不限量；平台 admin（admin:manage）的决策不计配额。

平台侧对接清单

后台注册 MCP server 资源（mcp:<server>，填 resource_uri 供 RFC 8707 映射）。
建 API Key（permissions 含 agent:authz:decide），平台 PDP 用它调 POST /api/authorize。决策类 Key 的默认限流自动放大为 600000/分（普通 Key 仍为 1000/分），显式传 rate_limit 时以传参为准。
平台 user_resource_grants / mcp_grants 同步为 IdP 授权记录（POST /api/admin/authz/grants，API Key 持 agent:grant:manage）。
worker 工具调用前把 context.trace_id 设为平台 X-Trace-Id，实现全链审计贯通。

Keyboard shortcuts

AuthKeystone 文档