argent-settings-permissions

此工具的用途

settings-permissions 可直接修改平台的权限存储——iOS 模拟器的 TCC 数据库，或 Android 的软件包管理器权限标记。它取代了测试设置过程中手动操作设置 → 隐私的繁琐步骤：预先授权某项服务，让应用无需请求权限；提前拒绝权限，以测试拒绝路径；或重置权限，以便应用下次启动时再次显示首次运行对话框。

这是一个用于测试设置／带外操作的工具，并非通用的权限切换工具。更改权限的默认方式仍然是通过应用操作——只有在应用无法触及这些场景时，才使用此工具。

何时使用——何时不使用

按以下顺序判断。匹配的第一行优先。

情况	操作	原因
应用有用于设置该权限的应用内控件（例如其自身设置页面中的开关）	在应用中点击（describe → gesture-tap）——请勿使用此工具	这符合真实用户的操作，也能测试你正在验证的流程。请参阅 argent-device-interact。
应用即将请求权限（或刚刚请求），且系统权限对话框正显示在屏幕上	点击对话框（Allow / Don't Allow / Allow While Using App）——请勿使用此工具	应用触发的提示是自然的操作路径；用户会直接作出选择。describe 会显示对话框按钮；仅当它未显示按钮时，才使用 screenshot。
你需要在应用运行前就预先授予/拒绝权限，这样流程中就不会出现对话框	在 launch-app 之前使用此工具（grant / deny）	应用无法预先设置自己的权限；真实用户会在“设置”中操作。这是此工具的核心用途。（deny 仅在 iOS 上抑制提示——见“注意事项”。）
用户已经拒绝该权限，而你需要重新开启它	使用此工具（grant）	iOS 上拒绝权限后，系统不会再次显示对话框——设备上唯一的操作路径是“设置”应用。此工具可作为捷径。
你需要再次显示首次运行对话框（测试提示本身，或重置残留状态）	使用此工具（reset）	将权限恢复为“尚未询问”，以便应用下次使用时再次请求。
目标平台不支持此工具管理该权限（见支持表）	请勿使用此工具	工具会返回“unsupported”错误。如果应用会触发对话框，请使用应用对话框；也可以前往系统“设置”应用。
该设置不属于以下 11 种运行时权限（例如 Wi-Fi、蜂窝数据、深色模式、VPN、专注模式）	请勿使用此工具	不在适用范围内——请改用“设置”应用或应用自身的界面。

经验法则：如果人工测试人员可以在_应用内_切换该设置，就在应用内操作。只有当人工用户通常会在系统“设置”应用中进行更改时，才使用 settings-permissions。

支持的权限与平台覆盖范围

permission	iOS 模拟器（TCC 服务）	Android（android.permission.*）
camera	camera - 仅当目标模拟器的运行时支持此权限时才可用（取决于 simruntime，而非已安装的 Xcode；模拟器没有摄像头硬件）	CAMERA
microphone	microphone	RECORD_AUDIO
photos	photos + photos-add（仅添加访问权限是单独的 TCC 服务；photos-add 尽力而为 - 检查 applied，确认两者是否都已更改）	READ_MEDIA_IMAGES + READ_MEDIA_VIDEO + READ_MEDIA_VISUAL_USER_SELECTED + READ_EXTERNAL_STORAGE
contacts	contacts	READ_CONTACTS + WRITE_CONTACTS
notifications	不支持 - 没有对应的 iOS 权限；请在应用的对话框中作答	POST_NOTIFICATIONS
calendar	calendar	READ_CALENDAR + WRITE_CALENDAR
location	location	ACCESS_FINE_LOCATION + ACCESS_COARSE_LOCATION
location-always	location-always	ACCESS_BACKGROUND_LOCATION（授予此权限也会添加精确位置和粗略位置权限 - 仅有后台权限无法读取位置）
media-library	media-library	READ_MEDIA_AUDIO + READ_EXTERNAL_STORAGE
motion	motion	ACTIVITY_RECOGNITION
reminders	reminders	不支持 - Android 没有对应的运行时权限

一个抽象权限可以映射到多个具体的 Android 权限；实际存在的权限取决于应用的清单和设备的 API 级别（例如，API 33 及以上使用 READ_MEDIA_*，更低版本使用 READ_EXTERNAL_STORAGE）。

操作

• grant - 预先授权。需要 bundleId。
• deny - 拒绝授权。需要 bundleId。用于测试应用的“权限被拒绝”处理路径。
• reset - 恢复到尚未询问的状态，以便下次使用时重新显示对话框。始终针对单个应用（需要 bundleId）：
  • iOS：移除该应用的 TCC 记录。不提供针对整个设备的重置（不带 bundleId）——在较新的 iOS 运行时中，这种操作会报告成功，但不会影响现有的单个应用授权，因此会报告发生了实际并未发生的更改。
  • Android：撤销授权，然后尽力清除用户设置／用户固定标记（清除标记的功能从 Android 13 / API 33 开始提供；撤销授权才计入成功条件）。在低于 API 33 的版本（即 API 23-32，在这些版本中可能存在用户固定状态）中，无法清除标记，因此在那里执行 reset 会撤销授权，但无法清除“不要再询问”（用户固定）状态——在这些较旧的设备上，对话框可能仍会被隐藏。

参数

{
  "udid": "<UDID-or-serial>",
  "action": "grant",
  "permission": "camera",
  "bundleId": "com.example.app"
}

• udid - list-devices 中的目标设备（iOS 模拟器 UDID 或 Android 序列号）。请参阅 argent-ios-simulator-setup / argent-android-emulator-setup 获取一个。
• action - grant | deny | reset。
• permission - 上述 11 个名称之一。
• bundleId - iOS 包 ID 或 Android 软件包名称。每种操作都必须提供。

平台行为

仅限 iOS 模拟器。 修改模拟器的 TCC 存储——始终针对单个应用（需要 bundleId）。实体 iPhone 上没有主机端的 TCC 开关，因此此工具不适用于真实 iOS 设备。必须先启动模拟器（boot-device），否则工具会失败并显示“current state: Shutdown”错误，同时提供启动提示。

Android 模拟器和实体设备。 通过 adb 更改应用的 android.permission.* 运行时权限（对于 reset，还会尽力清除用户设置／用户固定标记——撤销授权决定是否成功；清除标记需要 Android 13 / API 33+）。要求：

• 必须已安装应用——工具会先检查软件包是否存在，若不存在则明确报错（如果是传输／超时故障，则会显示 adb 的实际原因，而不会误报为“未安装”）。
• 应用的清单必须声明该权限。软件包管理器会拒绝清单中未请求的任何映射权限；这些权限会列在结果的 skipped 列表中。只要至少一个映射权限生效，操作就会成功；只有当所有映射权限都被拒绝时才会报错。

注意事项

• 更改权限可能会终止正在运行的应用（这是两个平台上的系统行为）。建议在 launch-app 之前设置权限；如果应用运行时更改了权限，请随后调用 restart-app。
• 两个平台上的重置都是针对单个应用的——传入 bundleId；没有可靠的设备级重置方式。
• Android 返回部分结果是正常的。 applied 列出实际发生更改的项目；skipped 列出包管理器拒绝的映射权限（通常是因为权限未在清单中声明，或受 API 级别限制）。两者结合即可了解实际情况。
• 预启动时执行 deny 只会在 iOS 上抑制提示。 在 iOS 上，TCC 拒绝会响应应用的权限请求，因此不会显示对话框。在 Android 上，deny 会清除授权，但不会设置“用户已固定”标记，因此应用下次请求时仍会显示系统对话框——在 Android 上，预启动时执行 deny 测试的是权限的_已撤销_状态，而不是被抑制的提示。
• iOS 上的 camera 可能会被未对该服务建模的模拟器运行时拒绝（这取决于 simruntime，而非已安装的 Xcode——即使平台自身的服务列表未列出 camera，某个运行时仍可能接受它）。拒绝时会显示通用的 CoreSimulator 错误，因此 camera 失败时（模拟器已关机的情况除外；该情况会显示启动提示），会附带有关运行时支持的服务的提示。
• grant location 需要先安装应用（iOS）。 位置授权不会存储在 TCC 中，且只有应用存在后才会应用于对应的 bundle id，因此安装前执行 grant location / grant location-always 不会记录任何内容。在本地模拟器上，工具会检查安装状态并明确报错，而不会误报成功；在远程模拟器上，工具无法检查安装状态，因此安装前授权会报告成功，但不会记录任何内容——请确保先安装应用，再远程授予位置权限。（camera / photos 等由 TCC 管理的服务可以在安装前授权；授权会保留，并在安装时生效。）

结果

返回 { action, permission, bundleId, applied, skipped? }：

• applied - 实际更改的平台级服务／权限（iOS 上的 TCC 服务；Android 上的 android.permission.* 名称）。
• skipped - 仅限 Android；当某些映射权限被拒绝、但其他权限已成功时会出现。

如果无法应用任何内容，此调用会失败——请查看错误信息，其中会说明原因：平台不支持该权限（iOS 上的 notifications、Android 上的 reminders）、应用尚未安装（包括 iOS 上安装前执行 grant location）、模拟器已关机（iOS），或所有映射权限均被拒绝（通常是清单中缺少权限声明）。非关机状态下的 camera 失败还会提示模拟器运行时支持的服务（模拟器关机导致的失败则会显示启动提示）。

示例

在启动前预先授予相机权限，这样应用就不会显示提示：

{ "udid": "<UDID>", "action": "grant", "permission": "camera", "bundleId": "com.example.app" }

测试拒绝权限的情况——拒绝位置权限，然后启动应用并观察回退行为：

{ "udid": "<serial>", "action": "deny", "permission": "location", "bundleId": "com.example.app" }

在 Android 上重置通知权限，让下次启动时再次显示首次运行提示：

{
  "udid": "<serial>",
  "action": "reset",
  "permission": "notifications",
  "bundleId": "com.example.app"
}

在 Android 上授予始终开启的位置权限（会自动同时授予后台和前台权限）：

{
  "udid": "<serial>",
  "action": "grant",
  "permission": "location-always",
  "bundleId": "com.example.app"
}