跳到主要内容
开发者文档
文档目录

主体、能力、Space 角色、读写根路径和 API Key 的限制如何共同决定一次请求。

请求的判定

一次请求必须同时满足以下条件,任一条件不满足即被拒绝:

text
allowed = capability in (principal.capabilities ∩ key.capabilities)
        and space in key.allowed_space_ids   (when set)
        and the Space role is sufficient
        and the path is under the member's read_root / write_root   (when set)

主体

类型说明
人kind: human,可以具备 tenant_admin 角色
Agentkind: agent,有自己的权限、记忆和审计身份
API Key凭据,不是主体,只能收窄所属主体

主体没有显示名,请自行按 id 记录名称。POST /v2/principals 只能创建 human 和 agent,tenant_admin 角色不能通过 API 授予。

能力

能力是对一类操作的许可,例如 knowledge:read、knowledge:write、knowledge:manage、knowledge:answer 和 memory:confirm。一个 API Key 的有效能力是主体能力和 Key 能力的交集。GET /v2/whoami 的 effective_capabilities 给出这个交集。

每种能力允许的操作见参考页的 DevCapability;每个操作需要的能力写在参考页该操作的条目里。

Space 角色

成员在每个 Space 中有一个角色:owner、editor 或 viewer。一次操作既要求能力,也要求最低角色。各角色可执行的操作见 DevSpaceRole;每个操作需要的能力和更严格的规则,见 API 参考 中该操作的说明。

Space 所有者用 PUT /v2/spaces/{space_id}/members/{principal_id} 设置成员的角色、write_mode、write_root 和 read_root。

Agent 的写入模式

write_mode 只对 Agent 生效,且只针对不属于它的文件。新成员默认为 proposal:修改他人的文件返回 403 proposal_required,移动和删除也一样,不会创建任何内容。设为 direct 后可以直接写入。Space 所有者始终是 direct。

proposal 模式的 Agent 可以带 Prefer: handling=proposal 把这类写入变成提案,由审核人批准,见 提案。

写入根路径和读取根路径

Space 所有者可以在设置成员时把它限制在一棵子树内。两种根路径都只会收窄:角色、能力和 API Key 的限制照常生效,没有拒绝规则。取值规则见 write_root 和 read_root。

curl
# The Agent reads /projects/acme and writes only under /projects/acme/drafts.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor", "write_mode": "direct",
       "read_root": "/projects/acme", "write_root": "/projects/acme/drafts"}'
根路径范围内范围外
write_root在该目录下写入,不能重命名、移动或删除目录本身403 outside_write_root,读取不受影响
read_root读取该目录及其下所有内容;没有 write_root 时也在此写入404,与不存在相同;检索、上下文、记忆和变更流都不包含范围外的内容
  • 没有路径的 Entry(ingest、项目记忆、提炼的事实)在两种范围之外,成员自己的 Agent 记忆除外。
  • 读取根路径和写入根路径在目录重命名或移动后仍然有效。删除某个成员的读取根路径或写入根路径,或包含这些路径的目录时,服务返回 409 directory_is_write_root 或 directory_is_read_root,Space 所有者执行此操作时也是如此。
  • write_root 不限制分支;合并写入主线时逐个路径检查,全部通过或全部不生效。
  • GET /v2/spaces 和 GET /v2/spaces/{space_id} 返回你自己的 read_root 和 write_root,从那里开始读 tree。

为 Agent 配置权限

为 Agent 创建独立的主体,不要共用人的 API Key。这样它的写入、记忆和审计都有自己的身份,吊销时不影响他人。

curl
# 1. Create the Agent. Without grant_capabilities it gets knowledge:read.
curl -X POST https://api.mirabase.dev/v2/principals \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "agent", "grant_capabilities": ["knowledge:read", "knowledge:write"]}'

# 2. Make it a member of one Space. write_mode direct lets it change files it does not own.
curl -X PUT "https://api.mirabase.dev/v2/spaces/$SPACE_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "editor", "write_mode": "direct"}'

# 3. Issue its key, narrowed to that Space.
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$AGENT_ID'", "name": "docs-agent",
       "grant_capabilities": ["knowledge:read", "knowledge:write"],
       "allowed_space_ids": ["'$SPACE_ID'"]}'

按 Space 限定 API Key

  • 访问收窄范围外的 Space 时,服务返回 404,与 Space 不存在时的响应相同。
  • 受范围限制的 API Key 不能访问账户级和租户级功能:账户记忆、GET /v2/principals、GET /v2/api-keys、GET /v2/audit/events。
  • 比所属主体窄的 Key 只能为该主体签发 Key,因此切换身份也无法绕过限制。

不可见即不存在

看不见的资源和不存在的资源返回同一个 404。收到 403 时查看 GET /v2/whoami,收到 404 时检查 id、Key 的 Space 范围和成员关系。

审计

GET /v2/audit/events 返回治理和访问事件。事件只含标识符,不含用户内容。治理动作与它所做的修改在同一事务里记录,失败时一起回滚。

权限变更在下一条语句立即生效,API Key 吊销也是如此,没有缓存窗口。

下一步