PokeClaw安全Guard机制全解析：AI如何不误发邮件、不误点按钮

• AI Agent
• 人工智能
• 大模型
• 本地部署
• 移动开发
• 自主智能体
• GUI 自动化

让 AI 直接操作手机，最大的风险就是"失控"——它可能替你按下发送键、误点陌生按钮、或者谎称任务已完成。PokeClaw（PocketClaw）是一款运行在 Android 本地的 AI 手机助手，它通过一套安全 Guard 机制给 AI 行为"上保险"：在执行前注入约束提示、在执行中记录真实操作、在收尾时拦截"假完成"，从而防止 AI 误发邮件、误点按钮。本文带你完整看懂这套三层防御是如何运作的。

为什么 AI 手机助手需要 Guard 安全机制

想象一下这个场景：你对 AI 说"帮我写封邮件"，结果它不仅写好了正文，还直接点了发送——这显然是不可接受的。

AI 操作手机时存在三类典型风险：

PokeClaw 的解法不是简单"禁止 AI 操作"，而是引入Guard（守卫）——一组按任务类型精准激活的规则哨兵。它只在特定任务下生效，对其他任务零干扰，源码集中在 agent/ 目录下。

Guard 机制整体架构：三层防御

PokeClaw 的 Guard 体系在任务执行主循环 DefaultAgentService.kt 中组装，分为三层：

1. 提示词层（事前预防）：任务开始时，系统根据用户请求判断是否命中某类敏感任务，若命中就把对应的"任务守卫规则"注入到 System Prompt 中，提前告诉 AI"必须怎么做、绝不能怎么做"。
2. 执行记录层（事中追踪）：AI 每调用一个工具（打开 App、点击、输入文本等），Guard 都会记录在案，判断 AI 是否真的执行了操作，而不是光说不做。
3. 拦截层（事后兜底）：当 AI 试图调用finish（结束任务）或只输出文字就想收工时，Guard 会检查关键步骤是否完成——未完成则直接拦截，并向 AI 下发纠正指令，强制它继续执行。

三层环环相扣：事前约束 → 事中留痕 → 事后拦截，即使模型"想偷懒"或"想越权"，也过不了 Guard 这一关。

第一道哨兵：EmailComposeGuard 防误发邮件

误发邮件是 AI 手机助手最危险的事故，因此 PokeClaw 为"写邮件"这类任务专门设计了 EmailComposeGuard.kt。

精准识别：只拦真正写邮件的任务

Guard 不会一看到"写"字就启动。它的激活条件（见 EmailComposeGuard.kt 中的fromTask）要求任务同时满足两个条件：

• 以写邮件的动词开头：write、compose、draft、send
• 内容涉及 email

所以Write an email saying I will be late today会触发守卫，而Write a short apology note（普通写作）不会。单元测试 EmailComposeGuardTest.kt 就专门验证了这个"精准不误伤"的行为。

注入约束：绝不允许 AI 擅自点"发送"

任务命中后，Guard 会向 System Prompt 注入一段硬性规则（见 EmailComposeGuard.kt 中的buildPromptSection），核心要求包括：

• 必须打开邮件 App（如 Gmail）并进入撰写界面
• 用input_text逐格填写收件人、主题、正文
• 用户没指定收件人时，收件人留空，但主题和正文照常填
• 检查撰写界面、确认草稿可见后才可结束
• 关键一条："Never press Send unless the user explicitly asked you to send the email"——除非用户明确要求发送，否则绝不按发送键

这意味着 AI 最多只能帮你把邮件草稿写好，最终发送权牢牢掌握在你手里。

拦截假完成：只输出文字不算数

最阴险的失误是"AI 在聊天框里贴出一段邮件正文，然后声称完成"。EmailComposeGuard 通过两个机制挡住这种行为：

• 文本完成拦截：shouldBlockTextOnlyCompletion()发现 AI 还没尝试任何 UI 操作就想用纯文字收工时，直接拒绝（见 DefaultAgentService.kt）。
• finish 拦截：AI 调用finish时，Guard 的maybeBlockFinish会拦截并返回纠正指令，甚至会根据当前屏幕信息提示 AI 相关的撰写控件节点 ID，帮它继续把活干完（见 EmailComposeGuard.kt）。

只有当 Guard 记录到 AI 真实调用过open_app、tap、input_text等 UI 操作工具后（recordToolAttempt，见 EmailComposeGuard.kt），才放行结束。

第二道哨兵：InAppSearchGuard 防"假搜索"

"在 App 里搜索"是 AI 最容易糊弄人的任务——它完全可以用记忆"脑补"一个搜索结果，声称"搜索成功"。

InAppSearchGuard.kt 专门盯住这类任务。它能识别两种句式（见 InAppSearchGuard.kt）：

• search [App] for [关键词]
• search for [关键词] on/in [App]

识别成功后，Guard 会解析出目标 App 并解析成真实的包名（resolvedPackage），这让它能精确校验 AI 的操作：

• 只有当 AI 用open_app打开的确实是目标 App 时，才记为"已打开"
• 只有当 AI 用input_text输入的文本确实包含搜索关键词时，才记为"已输入"

任何一步没做实，finish都会被拦截，AI 还会收到具体提示："你还需要用input_text输入搜索词、提交并查看结果"。注入的提示词中还有一句狠话："Never claim the search succeeded from memory alone"——禁止仅凭记忆谎称搜索成功。

第三道哨兵：DirectDeviceDataGuard 防"能力装死"

前两道 Guard 防 AI"乱来"，DirectDeviceDataGuard.kt 则防 AI"装死"——明明有能力，却说"我做不到"。

匹配与引导

当你问"我的剪贴板里有什么""现在有哪些通知""电量还剩多少""我装了什么 App""屏幕上现在是什么"这类问题时，Guard 会识别任务类型（见 DirectDeviceDataGuard.kt），并告诉 AI：

• 你被允许访问这些数据，不要用"无法访问"敷衍
• 必须先用指定工具（clipboard、get_notifications、get_device_info、get_installed_apps、get_screen_info）取数，再解释结果
• 空数据也是有效答案——剪贴板是空的、没有新通知，都应该如实报告，而不是当作失败

确定性工具调用：跳过模型直接执行

更硬核的是，对部分数据类请求，Guard 可以完全绕开大模型，直接确定性地下发工具调用（见deterministicToolCall，DirectDeviceDataGuard.kt）：

这种"确定性直通"既消除了模型幻觉的可能，又省掉了推理耗时——读数据这类任务，根本不需要 AI 发挥。

三道 Guard 如何在主循环中协同

三个 Guard 的协作全部发生在任务执行主循环 DefaultAgentService.kt 中，关键节点如下：

• 任务启动时（L455-L475）：InAppSearchGuard、EmailComposeGuard、DirectDeviceDataGuard三个守卫依次从用户请求中构建，并把各自的规则段落追加进 System Prompt。
• 纯文本收工时（L643-L660）：三个守卫依次检查shouldBlockTextOnlyCompletion()，任一命中就注入纠正指令，让 AI 回到执行轨道。
• 调用 finish 时（L695-L717）：系统实时抓取当前屏幕信息，让三个守卫依次调用maybeBlockFinish()，任何一道拦截都会把finish变成一次错误，并附上"你差哪一步"的说明。
• 每次工具执行后（L719-L729）：recordToolAttempt/recordSuccessfulTool记录 AI 的真实操作，作为后续放行finish的依据。

整个拦截过程都会写入日志（如 "Task guard blocked premature finish"），方便开发者回溯排查，相关行为有配套单测 DirectDeviceDataGuardTest.kt 保障。

配套机制：Playbook 给 AI 一条"标准路线"

Guard 负责"设卡"，而 PlaybookManager.kt 负责的"修路"——它加载 assets/playbooks/ 目录下的步骤化脚本，为本地模型提供确定的操作路线。

以发消息为例，send-message.md 明确规定：先调用send_message(contact=..., message=..., app=...)，成功后再finish，并清楚区分"给某人发消息"与"和我闲聊"的边界。配合 Guard 的拦截能力，AI 发消息不会乱点 UI，也不会把闲聊当发送任务。

其他内置 Playbook 包括 open-and-navigate.md、open-and-search.md、direct-device-data.md。

总结：安全不是限制能力，而是让能力可信

PokeClaw 的 Guard 机制设计思路值得借鉴：

1. 精准激活：Guard 只盯特定任务模式，日常对话与通用任务完全不受影响；
2. 分级防御：提示词约束、执行留痕、finish 拦截三层递进，AI 想"糊弄"必须连破三关；
3. 权限底线清晰：AI 可以帮你起草邮件，但"发送"这类不可逆操作，永远需要用户明确授权；
4. 空数据也是答案：如实报告"没有"，比假装失败或假装成功更可信；
5. 确定性优先：能直接调工具解决的数据读取，不经过模型猜测。

对于正在做 AI Agent 的开发者来说，这套"Guard + Playbook + 主循环拦截"的组合，是一个兼顾安全与灵活性的完整参考实现，相关设计思路也记录在 AI_AGENT_PLAYBOOK.md 与 ARCHITECTURE_DECISIONS.md 中。

💡安全提示：Guard 降低了 AI 误操作风险，但 AI 仍会操作你的真实设备。建议先在日常任务上试用 PokeClaw，熟悉其行为后再交给它处理重要流程，并在邮件、转账等敏感场景始终保持人工确认。

• AI Agent
• 人工智能
• 大模型
• 本地部署
• 移动开发
• 自主智能体
• GUI 自动化