Andee 是一个跑在 Android 上的 agent。他没有 Activity 主界面,能力全部以工具的形式注册给模型:给 Hub 的走 socket,本机大脑直接调。这些工具里有一批专门读设备数据——短信、通话记录、通讯录、日历、位置、步数。按 Android 的规矩,它们全部要运行时授权,而且要按次查。
工具契约里最少人看的一段,是失败路径的措辞。这批工具的函数签名清一色只返回 JSONObject:没有 Result、没有异常、没有布尔。也就是说,"用户拒绝了"必须是函数正常返回的一种值,不能是抛出去让人接的东西。91 个工具里,带这条闸门的有 9 个。我把这 9 个的返回值、谁有权去问用户、以及系统那边三种失败怎么区分,按代码过了一遍,下面是结果。
读完能拿走三样:一个可以直接抄的四态返回约定,一张"谁来问"的白名单,以及一个只能在 Activity 里读到的判据。最后有一处我自己还没堵上的静默失败,也写进去。
先给结论
- 闸门放在调用入口,不放在拿到空结果之后的猜测里;失败以
error+hint两个字段返回。 - 权限申请必须回四态:
granted/denied/no_dialog/waiting。前两个是不同的事实,第三个是"再问也没用"。 - "谁去问"由设备按 id 白名单决定,不由模型判断。混着问的一律整体交给人。
一、失败是一种返回值
device/DeviceCommsController.kt 里,七个入口的第一行是同一个形状:
fun readSms(box: String, limit: Int = 15): JSONObject {
if (!ensurePermission(Manifest.permission.READ_SMS)) return denied("sms")
...
}
private fun denied(what: String, hint: String = "Ask the user to grant it once (Settings → Apps → Permissions), then retry.") =
JSONObject().put("error", "permission denied: $what").put("hint", hint)
ensurePermission 只有一行 checkSelfPermission。这七个入口是:通讯录、直接拨号、通话记录、读短信、发短信、读日历、写日历。device/DeviceInfoController.kt 里另外两个是位置和步数,写法一样,只是那个文件里把辅助函数叫 permissionDenied,多带了一个必填的 guidance。
顺着这条线看会碰到一个不该存在的数字:checkSelfPermission(...) == PERMISSION_GRANTED 这一行,在这个仓库里写了三遍——DeviceCommsController:215、DeviceInfoController:188、PermissionsController:216(那边叫 isGranted)。三份都只有一行,所以我没抽公共函数;但这正是那种"只有一行所以抄一下"的东西,将来改判定条件(比如加 shouldShowRequestPermissionRationale 的判断)会漏掉一处。
hint 这个字段是给模型看的,不是给用户看的。它的措辞决定下一步:写"去设置里开一次再重试",模型就会请用户去开;写"权限不足",模型就会自己找别的路。工具描述的写法在这里是有后果的,不是文案问题。
还有一个细节:写日历的闸门比读日历的更重要。addCalendarEvent 在 contentResolver.insert 之前查 WRITE_CALENDAR。两件事是独立权限,只给读的时候列表能看、加一条失败;不做这个前置检查,失败会以 insert returned null 出现,模型会把它读成"日历写不进去",然后尝试第三次。
二、denied 和 no_dialog 是两条相反指令
系统对这两种情况给的是同一个值:PERMISSION_DENIED。但它们要求的反应完全相反——一个是"他看过并拒绝了,别再提",另一个是"系统已经不再画弹窗了,再发也是被静默忽略"。
分开它们的唯一信号是 shouldShowRequestPermissionRationale,而它是 Activity 的方法。这就是为什么这里必须有一个 PermissionRequestActivity:它不是"为了弹个框",是为了拿到只有 Activity 能读的那个判据。
它原来把 grantResults 直接丢了,于是上层永远只知道"发过一次"。现在的链路是 arm / await / settle:
override fun onRequestPermissionsResult(...) {
settle(verdict(permissions, grantResults))
finish()
}
private fun verdict(...): String {
if (grantResults.isNotEmpty() && grantResults.all { it == PERMISSION_GRANTED }) return GRANTED
val silent = permissions.indices.any { i ->
grantResults.getOrNull(i) != PERMISSION_GRANTED &&
!shouldShowRequestPermissionRationale(permissions[i])
}
return if (silent) NO_DIALOG else DENIED
}
两个地方容易写错:
- "静默"只对没给的那几个判定。 已经给过的权限同样没有 rationale,把它算进来会把每一次部分授予都误判成静默屏蔽。
arm()必须在startActivity之前调。 弹窗可能在一毫秒内就给出答案,晚建 latch 就丢掉这次判决。
waiting 是第四态,代表"弹窗在屏幕上、还没人回答"。PermissionsController 等 DIALOG_GRACE_MS = 800 毫秒去拿判决,拿不到就报 waiting。这 800 毫秒是宽限期,不是等人。 真弹窗会一直挂着,而被系统封掉的权限会在毫秒级返回且什么都没画——这 800 毫秒只用来分开这两种情况。等人是别人的事:solo 模式下他自己看屏幕,handoff 模式下走 ask_user。
三、谁去问,是设备说了算
routeOf(ids) 是个纯函数,只吃 id 列表:
internal fun routeOf(ids: List<String>): String = when {
ids.any { it in SETTINGS_IDS } -> "settings"
ids.isNotEmpty() && ids.all { it in SOLO_IDS } -> "solo"
else -> "handoff"
}
SETTINGS_IDS 是 notifications、overlay——没有弹窗,只有设置里的一个开关。SOLO_IDS 是 location、steps、calendar、calendar_write、notify_post,都是关于用户自己的身体和自己日程的数据。其余一律 handoff。
两个设计决定值得说:
第一,SOLO_IDS 是白名单,注释里写明了理由:以后有人往权限目录里加一项、又没读这段代码,失败方向是"用户被多问了一次",而不是"他替用户答应了什么"。这个方向的取舍是对的,因为另一头不可撤销。
第二,请求里只要混进一个非 solo 的 id,整个请求交给用户。弹窗是叠着来的,一个个点过去就是答错的那个。
因为是纯函数,路由可以不用设备就测——PermissionsRouteTest 锁的就是这张表。工具契约里能拆成纯函数的部分,都该这么拆。
四、不存在的权限,系统也答 denied
POST_NOTIFICATIONS 是 API 33 才有的。PermissionsController 的目录项带一个 api 字段,status() 里先跳过:
if (p.api > 0 && Build.VERSION.SDK_INT < p.api) continue
不跳过的后果是每一台 Android 12 设备都永远缺一项、而且没有按钮能补——checkSelfPermission 对它不认识的权限一律返回 denied,这不是"没授权",是"这个权限在这里不存在"。整行跳过才是诚实的答案:那台设备上没有东西可授。
五、同一个错误,在 USB 那里又犯了一次
那只机器狗走 USB OTG,权限是按设备授权的,不是开关。dog/DogLink.kt 里同样要区分两件事,而且区分得很干净:
lastError = if (answered) {
"the user refused USB permission, so the dog cannot be reached"
} else {
"the USB permission dialog went unanswered for ${PERMISSION_WAIT_MS / 1000} s — ..."
}
答案是广播回来的,所以 receiver 必须先注册再发请求;等待上限 12 秒(PERMISSION_WAIT_MS),因为一个没人理的弹窗不能把工具调用永久挂住。拒绝和超时是两句话,因为对用户来说它们是两件事:一个是"你按了拒绝",一个是"框还在,去按一下允许"。
六、代价
弹窗读不到,所以永远不能替他点。 实测过:卡片收起来以后注入点击是有效的(READ_CONTACTS false→true,点"仅此一次"会产出带 ONE_TIME 标志的定位授权)。但 get_screen_element 在权限弹窗上返回空列表——看不见元素,任何点击都是猜,而屏幕最底下那颗是「禁止后不再提示」,按下去没有东西能撤销。规则因此是"读不到就不许瞄",不是"点了没用"。
这套诚实失败里还留着一处静默降级。 前台服务要提升类型,那段是 runCatching { startForeground(...) }.onFailure { Log.w(...) }。系统拒绝时只有一行日志,用户看不到,作者也看不到。这跟本文开头骂的硬编码 true 是同一个病,只是还没轮到它。
**历史欠账:POST_NOTIFICATIONS 从第一个版本就写在清单里,代码一次都没请求过,0.3.1 才补上。**在此之前 Android 13+ 上发出的每一条通知都被静默丢弃,包括到点提醒和那条接回屏幕操作的常驻通知——而权限表里那一行当时只写了"提醒不会到达",低估了它。
这套约定真正省掉的不是代码,是模型在权限上自由发挥的空间:四种结果、两张名单、一个只有 Activity 读得到的判据,全都放在设备侧。模型要做的只剩一件事——读到 denied 就停,读到 no_dialog 就请人去设置,别自己找路。