For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/backend-development/system-permissions.md.

系统权限授权接入(服务端)

本文面向负责 MCP Server、业务服务端和联调验收的开发者,说明如何为工具声明系统权限、理解平台的授权判定,并在 Tool Call 中安全读取用户已授权的数据。

系统权限接入采用“双层授权”模型:工具配置的应用插件 Scope 与宿主系统权限必须同时满足。只有应用插件授权记录成功,并且当前设备的系统权限可用时,平台才会调用强依赖该权限的工具。

接入目标

当 MCP 工具需要定位、麦克风、摄像头、蓝牙或日历等系统能力时,开发者只需在应用版本和工具配置中声明对应 Scope。平台负责在调用工具前完成授权判断、拉起索权交互,并把可透传的授权数据(当前只涉及地理位置权限)注入当前 Tool Call。

标准链路为:

  1. 在 Manifest 顶层的 permissions 权限字典中声明 Scope 的 scope_name、description 和 type;
  2. 在 tools.<tool_name>.tool_permissions 中引用所需 Scope,并通过 is_must_need 标记强弱关联、通过 priority 设置优先级,详见 Manifest 配置规范 鉴权与索权章节;
  3. 用户触发工具后,平台同时检查应用插件维度授权状态和宿主系统权限状态;
  4. 任一强依赖权限未满足时,平台下发索权卡片,暂不调用工具;
  5. 全部强依赖权限满足后,平台调用 MCP 工具;如果存在可透传的授权数据,则写入 arguments._miniapp_permitted_data;
  6. 业务服务端读取并校验当前 Tool Call 中的授权数据,完成业务处理。

系统权限授权与登录鉴权是两套独立能力。工具同时需要登录时,还应按 登录接入(服务端) 完成登录配置;仅需要系统权限时,不要为了索权额外开启登录。

名词解释

对象作用关键规则
应用插件 Scope用户对当前应用、当前能力的授权记录按应用和用户隔离;与宿主系统权限不是同一份状态
宿主系统权限操作系统授予豆包客户端的定位、麦克风、摄像头等权限由当前设备和系统设置决定;被关闭或无法确认时,强依赖工具不能直接调用
is_must_need声明工具是否强关联某个 Scopetrue 时必须授权后才调用;false 时工具必须能够在没有该数据时降级
_miniapp_permitted_data平台在当前 Tool Call 中注入的授权数据集合以 Scope 名为 key(当前只涉及位置权限);仅在存在可透传数据时出现,不应由客户端或模型自行构造
Sandbox SessionWeb 模拟器中的独立调试会话权限和定位调试数据按 Session 隔离;重建调试会话后不会继续读取旧 Session 的定位数据

接入前准备

顺序开发者要完成的动作关键产出
1确认工具实际使用的系统能力和无权限时的降级方式Scope 清单和强弱依赖策略
2使用当前平台支持的 Scope有效的 scope_name
3在 Manifest 顶层的 permissions 权限字典中声明 Scope,并在 tools.<tool_name>.tool_permissions 中关联到具体工具符合 Manifest 规范的权限字典与工具级权限关联
4在 MCP Server 中读取平台保留字段并实现空值、缺字段和非法值处理安全的 Tool Call 入参解析
5使用 Sandbox 和真机分别调试平台授权后透传数据的链路可上线的授权闭环

工具权限声明

权限需先在 Manifest 顶层的 permissions 权限字典中定义,再由 tools.<tool_name>.tool_permissions 关联到具体工具。以下示例声明精确定位 Scope,并将其配置为强关联权限:

permissions:
  - scope_name: scope.userLocation
    description: 精确定位权限
    type: Tool

tools:
  search_routes:
    tool_permissions:
      - scope_name: scope.userLocation
        priority: 1
        is_must_need: true
字段说明
permissions[].scope_name权限字典中的 Scope 名称;工具通过同名 scope_name 引用
permissions[].description权限用途描述,用于向用户展示索权理由
permissions[].type权限类型:JSB 表示通过端能力 JSBridge 调用,Tool 表示通过工具调用
tools.<tool_name>tools 下以工具名作为键;必须与 MCP Server 暴露的工具名完全一致,区分大小写
tools.<tool_name>.tool_permissions[].scope_name引用 permissions 权限字典中已声明的 Scope
tools.<tool_name>.tool_permissions[].priority权限优先级,数值越小优先级越高
tools.<tool_name>.tool_permissions[].is_must_needtrue 表示强关联,缺失则工具不可用;false 表示弱关联,缺失时工具仍可降级运行

以下 Scope 列表与 Manifest 配置规范的 scope_name 枚举保持一致;未列入该枚举的值(如 scope.addPhoneContact)不得写入配置。

Scope系统能力宿主系统权限标识
scope.userLocation精确位置ACCESS_FINE_LOCATION
scope.userFuzzyLocation模糊位置ACCESS_COARSE_LOCATION
scope.userLocationBackground后台位置ACCESS_BACKGROUND_LOCATION
scope.record麦克风RECORD_AUDIO
scope.bluetooth蓝牙BLUETOOTH
scope.addPhoneCalendar写入系统日历CALENDAR
scope.camera摄像头CAMERA

位置权限互斥:scope.userLocation、scope.userFuzzyLocation 和 scope.userLocationBackground 在同一个工具中只能选择一个。需要不同精度或前后台语义时,应拆分工具或重新设计调用边界。

运行时授权判断

对于 is_must_need: true 的 Scope,平台会同时检查两层状态。应用插件维度授权成功只表示用户同意当前应用使用该能力,不代表设备上的系统权限仍然可用。

应用插件 Scope宿主系统权限平台行为工具是否调用
已授权已授权授权通过;存在可透传数据时注入当前 Tool Call是
已授权未授权、未确定或已关闭将本次有效状态视为待授权并再次拉起索权否
未授权、拒绝或撤销任意按当前 Scope 状态展示索权或拒绝结果否(强依赖)
弱依赖且用户已操作未获得可用数据允许继续业务链路,工具自行降级是

位置权限特殊说明:对于一方(豆包同主体)应用插件,以及三方应用插件中用户未登录 && 当前工具本身不依赖登录的场景,无需触发应用插件维度的位置权限索权。平台仍会根据宿主系统权限和当前是否取得可用位置完成后续处理,其他权限的授权规则不受影响。

服务端接收授权数据

授权检查通过后,如果平台拿到了当前 Scope 可透传的数据,会在调用 MCP 工具前把数据写入 arguments._miniapp_permitted_data。该字段以 Scope 名为 key,业务参数仍保持原有结构。

{
  "name": "***",
  "arguments": {
    "_miniapp_permitted_data": {
      "scope.userLocation": {
        "longitude": ***,
        "latitude": ***,
        "city": "",
        "country": "",
        "province": "",
        "district": "",
        "town": "",
        "country_code": "",
        "region": "",
        "impr_time": ""
      }
    },
    "from_mcp_call": true
  },
  "_meta": {
    "app_key": "db_xxxxxxxx",
  }
}

_miniapp_permitted_data 是平台保留字段,具有以下行为:

  • 只有当前调用存在可透传数据时才出现;业务服务端必须允许字段缺失;
  • 数据按 Scope 分组,一个工具声明多个 Scope 时不要假设每个 Scope 都会产生数据对象(当前仅精确位置权限会产生明确数据透传对象);
  • 平台只会把授权检查结果用于当前 Tool Call,历史消息中的同名字段不能代表当前权限仍有效;
  • 客户端、模型和普通业务参数不得自行伪造该字段;服务端只读取平台实际发起的 MCP 请求;
  • 工具同时需要登录时,登录身份和 Token 仍通过对应 Header 传递,不能从该字段推断用户身份。

位置数据处理规则

精确位置属于敏感信息。只为当前明确业务目的使用,仅用于当前本次工具调用的结果封装中,日志中不得记录完整经纬度、地址或整段 _miniapp_permitted_data;如确需保存,应执行最小化留存、访问控制和到期删除。

调试与验收

Web 模拟器调试

使用 dbx dev 启动调试环境,并按 本地调试与预览 打开 Web 模拟器。当前 Sandbox 链路会从本次 Session 的业务信息中读取系统权限和定位信息

  1. 确认当前 Manifest 顶层的 permissions 权限字典已声明目标 Scope,且正在调试的工具已通过 tool_permissions 引用该 Scope;
  2. 模拟器链路弹起对话链路索权卡片时点击允许,即上传应用插件维度授权数据;
  3. 模拟器链路弹起Web定位弹窗时点击允许(模拟系统权限弹窗),即上传当前获取的真实位置信息;
  4. 位置场景确认 latitude、longitude 均存在且非 0;模拟器会以当前上报时间生成 impr_time;
  5. 重新触发对话,观察是否先出现索权卡片,以及授权后是否真正发起 Tool Call;
  6. 检查当前 Tool Call 的 arguments._miniapp_permitted_data,不要用历史消息中的旧参数判断本次结果。

如果当前 Session 取不到定位信息,或者经纬度缺失、解析失败或为 0,模拟器会把定位系统权限视为“未确定”,不向授权下游传递位置数据。对于强依赖位置的工具,这会再次触发索权卡片。

验收矩阵

场景预期授权行为预期 Tool Call验收重点
首次使用,尚未授权展示索权卡片强依赖工具不调用卡片 Scope、文案和顺序正确
应用插件与系统权限均已授权,位置有效直接放行正常调用存在对应 Scope 的 _miniapp_permitted_data
应用插件已授权,系统权限未确定或已关闭再次索权强依赖工具不调用不能只依据应用插件授权记录判断成功
位置缺失或经纬度为 0按系统定位权限不可用处理不透传位置不会使用旧位置或固定兜底位置
用户拒绝强依赖权限保留拒绝结果不调用页面可恢复,不绕过授权
用户拒绝弱依赖权限不反复阻塞允许调用服务端无权限数据时能正确降级
重建调试会话按新 Session 重新判断不读取旧 Session 的位置历史消息可能仍展示旧参数,但本次调用不得使用

Sandbox 日志判断口径

位置强依赖场景的成功链路应同时满足:

  • 应用插件授权记录中 scope.userLocation 为已授权;
  • 本次授权请求携带的 ACCESS_FINE_LOCATION 系统权限为已授权;
  • 本次 Session 能读取到非 0 的经纬度;
  • 最终有效权限映射中 scope.userLocation 为已授权;
  • Tool Call 的 arguments._miniapp_permitted_data.scope.userLocation 存在。

常见问题

应用插件授权已经成功,为什么仍然重复出现索权卡片

优先检查宿主系统权限和本次 Session 的定位数据。对于强依赖 Scope,两层状态必须同时成功;只写入 user_miniapp_permission 并不足以放行。位置缺失、经纬度为 0 或系统权限状态为未确定,都会让本次有效 Scope 回到待授权状态。

授权通过后为什么没有 _miniapp_permitted_data

先确认工具声明的 Scope 与返回数据的 key 完全一致,再检查当前调用是否确实产生了可透传数据。摄像头、麦克风等权限通过并不意味着平台会自动生成媒体数据;_miniapp_permitted_data 只承载平台在当前调用中实际取得并允许透传的数据。

撤销后为什么历史消息里还能看到旧经纬度

历史消息保存的是当时 Tool Call 的参数快照,不是当前 Session 的权限来源。撤销后,新 Session 不会关联旧 Session 保存的定位信息;判断当前状态只能查看本次授权请求和本次 Tool Call,不能从历史消息反推当前权限。

为什么位置权限不能同时声明精确、模糊和后台定位

三个位置 Scope 的精度、系统权限和用户授权语义不同,平台在一个工具中只接受其中一个。需要不同语义时应拆分工具,并让每个工具声明最小必要权限。

上线检查

  • 每个工具在 tool_permissions 中引用的 Scope 都已在 Manifest 顶层的 permissions 权限字典中声明;
  • tools 下的工具键名与 MCP Server 暴露的名称完全一致;
  • 强依赖与弱依赖配置符合真实业务,弱依赖缺数据时已有降级逻辑;
  • 同一工具没有同时声明多个位置 Scope;
  • 服务端只读取当前 Tool Call 中的平台保留字段,不信任客户端或历史消息中的同名数据;
  • 位置经纬度、范围和新鲜度均有校验,缺失或非法时不会使用固定值兜底;
  • 日志、监控和错误响应不包含完整经纬度、地址或整段授权数据;
  • Sandbox 已覆盖授权、拒绝、系统权限关闭、无定位、零坐标和撤销重建 Session;
  • 真机已覆盖首次索权、系统设置中关闭权限、重新开启权限和重复调用;
  • 已确认强依赖权限未通过时不会调用 MCP 工具,通过后会正确透传授权数据。