权限

最后更新：2026-11-04 10:10:15

TinyMCE AI 使用基于权限的访问控制系统来管理用户对 AI 功能的访问。权限在 JWT 令牌中指定，并控制用户可以访问哪些功能、模型和能力。

有关 JWT 认证设置和必需声明的信息，请参阅 JWT Authentication。

快速参考

类别	权限
管理	`ai:admin`
模型	`ai:models:`, `ai:models:<provider>:`, `ai:models:<provider>:<model-name>`, `ai:models:agent`
对话	`ai:conversations:*`, `ai:conversations:read`, `ai:conversations:write`, `ai:conversations:websearch`, `ai:conversations:reasoning`
上下文	`ai:conversations:context:`, `ai:conversations:context:files:`, `ai:conversations:context:files:<format>`, `ai:conversations:context:urls`
操作	`ai:actions:`, `ai:actions:custom`, `ai:actions:system:`, `ai:actions:system:<action-name>`
审查	`ai:reviews:`, `ai:reviews:custom`, `ai:reviews:system:`, `ai:reviews:system:<review-name>`

使用场景

基于角色的访问：不同的用户角色具有不同的 AI 能力
成本控制：限制对昂贵模型或功能的访问
功能门控：为高级用户启用特定的 AI 功能
安全性：限制对敏感 AI 操作的访问

权限格式

权限是 JWT 中 auth.ai.permissions 声明的字符串数组。每个字符串的格式为 ai:<permission-type>:<permission-value>，其中 <permission-type> 是 models、conversations、actions、reviews 或 admin 之一。<permission-value> 可以包含 * 通配符。服务会忽略任何不匹配此格式的字符串。

管理权限

权限	描述
`ai:admin`	授予对所有 TinyMCE AI 功能、模型和能力的完全访问权限。在生产环境中谨慎使用。

模型权限

权限	描述
`ai:models:*`	访问所有可用的 AI 模型。谨慎使用，因为这包括访问可能更昂贵的新模型。
`ai:models:<provider>:*`	访问特定提供商的所有模型（例如，`ai:models:openai:`，`ai:models:anthropic:`）。
`ai:models:<provider>:<model-name>`	访问特定模型（例如，`ai:models:openai:gpt-4o`，`ai:models:anthropic:claude-3-sonnet`）。
`ai:models:agent` ⭐ 推荐	访问代理模型，该模型会自动为每个请求选择最佳模型。这是大多数使用场景的推荐权限。

对话消息、自定义操作和自定义审查也需要请求所使用的模型的权限。系统操作和系统审查仅需要其自身的权限。

对话权限

权限	描述
`ai:conversations:*`	完全访问所有对话功能，包括读取、写入、网络搜索和推理。
`ai:conversations:read`	能够读取和列出对话、消息和附件。
`ai:conversations:write`	能够创建、更新和删除对话，并发送消息。还需要 `ai:conversations:read` 权限。
`ai:conversations:websearch`	能够在对话中使用网络搜索功能。
`ai:conversations:reasoning`	能够在对话中使用推理功能。

上下文权限

权限	描述
`ai:conversations:context:*`	访问所有上下文类型（文件和 URL）。
`ai:conversations:context:files:*`	访问所有上下文文件类型。
`ai:conversations:context:files:<format>`	访问特定文件格式（例如，`ai:conversations:context:files:pdf`，`ai:conversations:context:files:docx`）。
`ai:conversations:context:urls`	能够使用网络 URL 作为上下文来源。

上传文件还需要 ai:conversations:write 权限。

操作权限

权限	描述
`ai:actions:*`	访问所有操作类型，包括自定义和系统操作。
`ai:actions:custom`	访问自定义操作。
`ai:actions:system:*`	访问所有系统操作。
`ai:actions:system:<action-name>`	访问特定系统操作。

审查权限

权限	描述
`ai:reviews:*`	访问所有审查类型，包括自定义和系统审查。
`ai:reviews:custom`	访问自定义审查。
`ai:reviews:system:*`	访问所有系统审查。
`ai:reviews:system:<review-name>`	访问特定系统审查。

ai:actions:custom

能够使用自由格式的提示运行自定义操作。

ai:actions:system:*

访问所有预定义的系统操作。

ai:actions:system:<action-name>

访问特定的系统操作。示例：ai:actions:system:improve-writing，ai:actions:system:fix-grammar，ai:actions:system:translate

在 Chat 中打开的 Quick Actions（如Explain、Summarize和Highlight key points）以及带有type: 'chat'的自定义 Quick Actions 会发送对话消息。它们需要对话权限和所选模型的权限。

Reviews permissions

权限	描述
`ai:reviews:*`	访问所有审查类型，包括自定义审查和系统审查。
`ai:reviews:custom`	能够使用自由格式的提示运行自定义审查，包括集成商定义的审查。
`ai:reviews:system:*`	访问所有预定义的系统审查。
`ai:reviews:system:<review-name>`	访问特定的系统审查。示例：`ai:reviews:system:correctness`，`ai:reviews:system:clarity`，`ai:reviews:system:make-tone-professional`

权限示例

基本用户

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:read",
        "ai:conversations:write",
        "ai:models:agent",
        "ai:conversations:context:files:pdf",
        "ai:conversations:context:files:docx"
      ]
    }
  }
}

所有 `tinymceai` 插件功能

此集合涵盖了具有网络搜索、推理和附件功能的 Chat，以及系统和自定义 Quick Actions 和审查，使用 Agent 模型。如果自定义 Quick Action 或自定义审查使用特定模型，请添加该模型的权限。

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:read",
        "ai:conversations:write",
        "ai:conversations:websearch",
        "ai:conversations:reasoning",
        "ai:conversations:context:*",
        "ai:models:agent",
        "ai:actions:*",
        "ai:reviews:*"
      ]
    }
  }
}

高级用户

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:*",
        "ai:models:*",
        "ai:actions:system:*",
        "ai:reviews:system:*"
      ]
    }
  }
}

企业管理员

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:admin"
      ]
    }
  }
}

受限用户（仅限审查）

系统审查不需要模型权限。

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:reviews:system:correctness",
        "ai:reviews:system:clarity"
      ]
    }
  }
}

最佳实践

权限设计

根据实际需求从最小、特定的权限开始。仅在测试环境和需要全面访问的高级用户中使用通配符。根据用户需求和使用模式逐步扩展权限。

避免在生产中使用ai:models:*，以防止意外访问新的昂贵模型。使用特定于提供商的权限（如ai:models:openai:*）以更好地控制，或指定确切的模型以实现最大程度的控制。从常见格式（PDF、DOCX、TXT、PNG、JPEG）开始，仅在需要时添加专业格式。

错误处理

当用户缺少所需权限时，API 返回403 Forbidden错误，代码为missing-permissions。data.missingPermissions数组列出了令牌缺少的权限。有关响应体，请参阅错误响应。常见问题包括缺少模型权限、文件类型限制、无权限访问功能以及无权限访问操作/审查。

权限