> 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.

# 系统权限授权接入（服务端）

> 本文面向负责 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 配置规范](/apps-plugin/docs/core-concepts/manifest.md) 鉴权与索权章节；
3. 用户触发工具后，平台同时检查应用插件维度授权状态和宿主系统权限状态；
4. 任一强依赖权限未满足时，平台下发索权卡片，暂不调用工具；
5. 全部强依赖权限满足后，平台调用 MCP 工具；如果存在可透传的授权数据，则写入 `arguments._miniapp_permitted_data`；
6. 业务服务端读取并校验当前 Tool Call 中的授权数据，完成业务处理。

系统权限授权与登录鉴权是两套独立能力。工具同时需要登录时，还应按 [登录接入（服务端）](/apps-plugin/docs/backend-development/login.md) 完成登录配置；仅需要系统权限时，不要为了索权额外开启登录。

## 名词解释

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

```yaml
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_need` | `true` 表示强关联，缺失则工具不可用；`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，业务参数仍保持原有结构。

```json
{
  "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` 启动调试环境，并按 [本地调试与预览](/apps-plugin/docs/development-tools/local-debugging.md) 打开 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 工具，通过后会正确透传授权数据。
