在 Android 上构建本地端 AI 手机…

需要无云、无 API Key 地在 Android 设备上运行 Gemma 4，并通过工具调用与 Accessibility 完成点击、滑动、输入、打开应用、发消息等多步手机自动化时使用。

适用场景

解决思路

1. 按架构分层实现：User prompt → TaskOrchestrator → LLMEngine(LiteRT-LM) → tool_calls[] → ToolDispatcher → AccessibilityTool/AppLaunchTool/ScreenReaderTool/MessagingTool/FinishTool → Android Accessibility Service/UI Automator。
2. 克隆仓库：git clone https://github.com/agents-io/PokeClaw.git && cd PokeClaw。
3. 用 Android Studio Hedgehog 或更高版本打开项目；使用 SDK Android 9+（API 28），target API 34+，Kotlin 1.9+。
4. 在 app/build.gradle.kts 添加依赖：com.google.ai.edge.litert:litert-lm:1.0.0、org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3、org.json:json:20231013。
5. 在 AndroidManifest.xml 声明 BIND_ACCESSIBILITY_SERVICE、BIND_NOTIFICATION_LISTENER_SERVICE，以及可选的 FOREGROUND_SERVICE、FOREGROUND_SERVICE_DATA_SYNC。
6. 在 AndroidManifest.xml 声明 .accessibility.PokeAccessibilityService，设置 android:permission=android.permission.BIND_ACCESSIBILITY_SERVICE、android:exported=false，intent-filter action=android.accessibilityservice.AccessibilityService，meta-data 指向 @xml/accessibility_service_config。
7. 配置 res/xml/accessibility_service_config.xml：accessibilityEventTypes=typeAllMask，accessibilityFeedbackType=feedbackGeneric，accessibilityFlags=flagDefault|flagRetrieveInteractiveWindows|flagRequestEnhancedWebAccessibility，canRetrieveWindowContent=true，canPerformGestures=true，notificationTimeout=100，description=@string/accessibility_service_description。
8. 构建并安装：./gradlew assembleDebug，然后 adb install app/build/outputs/apk/debug/app-debug.apk；也可下载 latest release APK。
9. 定义 ToolDefinition、ToolParameters、ToolProperty 数据结构，用 JSON schema 描述工具名、描述、参数类型、properties、required、enum。
10. 初始化 LLMEngine：调用 LiteRtLm.create(context, modelPath, InferenceOptions.builder().setMaxTokens(2048).setTemperature(0.1f).setTopK(40).build())；低 temperature 提高工具调用可靠性。
11. 构建 ToolConfig 列表：对每个工具 JSON 调用 ToolConfig.fromJson，注册 tap、input_text、open_app、get_screen_info、send_message、finish。
12. 为 tap 写 JSON schema：name=tap，description 说明按 resource ID/content description/坐标点击，parameters 包含 target 必需、x/y 可选。
13. 为 input_text 写 JSON schema：name=input_text，parameters 包含 text 必需、target 可选。
14. 为 open_app 写 JSON schema：name=open_app，parameters 包含 app_name 必需、package_name 可选。
15. 为 get_screen_info 写 JSON schema：name=get_screen_info，parameters 为空对象，required 为空数组。
16. 为 send_message 写 JSON schema：name=send_message，parameters 包含 app、contact、message 均必需。
17. 为 finish 写 JSON schema：name=finish，parameters 包含 summary 必需。
18. 实现 PokeAccessibilityService：继承 AccessibilityService，用 companion object 保存 instance，在 onServiceConnected 赋值，实现 onAccessibilityEvent 和 onInterrupt。
19. 实现 getScreenInfo：从 rootInActiveWindow 开始递归 appendNode，输出 class、viewIdResourceName、text、contentDescription、isClickable、isEditable，缩进表示层级。
20. 实现 tap：若提供 x/y 则 performTapGesture；否则 findNode 按 text、viewIdResourceName、content-desc 查找并 performAction(ACTION_CLICK)。
21. 实现 performTapGesture：Path.moveTo(x,y)，GestureDescription.StrokeDescription(path,0,50)，GestureDescription.Builder().addStroke，dispatchGesture。
22. 实现 findNode/findByContentDesc：先 findAccessibilityNodeInfosByText，再 findAccessibilityNodeInfosByViewId，再递归比较 contentDescription。
23. 实现 swipe：Path.moveTo(startX,startY)、lineTo(endX,endY)，StrokeDescription 持续时间 durationMs=300，dispatchGesture。
24. 实现 inputText：按 targetResId 查找或 findFocusedEditText 找可编辑节点；performAction(ACTION_FOCUS)，Bundle putString ACTION_ARGUMENT_SET_TEXT_CHARSEQUENCE，performAction(ACTION_SET_TEXT,args)。
25. 实现 TaskOrchestrator：维护 history 和 maxSteps=20；runTask 清空历史，加入 system prompt 和 user prompt。
26. 在 TaskOrchestrator 循环中调用 llmEngine.chat(history, toolConfigs=llmEngine.buildToolConfigs())；若无 toolCalls 返回文本；若调用 finish 返回 summary。
27. 对每个 toolCall 调用 toolDispatcher.dispatch(call.name, call.arguments)，记录 Tool name → result；把 assistant 文本和 tool 结果加入 history，继续循环直到完成或 maxSteps。
28. 写 system prompt：你是 PokeClaw，控制 Android 手机；工具包括 tap、swipe、input_text、open_app、get_screen_info、send_message、finish；流程是先 get_screen_info，再选直接工具，必要时动作后验证，完成调 finish；规则是不猜坐标、优先 ID/文本、失败读屏适配、同一元素不超 3 次、回复简洁。
29. 实现 ToolDispatcher：try/catch 内按 toolName switch，分发 tap、swipe、input_text、open_app、get_screen_info、send_message、finish；未知工具返回 Unknown tool。
30. 实现 handleTap：读取 target、x、y，调 accessibilityService.tap，返回成功/失败信息。
31. 实现 handleSwipe：读取 start_x、start_y、end_x、end_y，调 accessibilityService.swipe。
32. 实现 handleInputText：读取 text、target，调 accessibilityService.inputText。
33. 实现 handleOpenApp：读取 app_name、package_name；若无 package_name 则 resolvePackageName 遍历 getInstalledApplications 比较应用 label；用 getLaunchIntentForPackage 获取 intent，addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)，startActivity。
34. 实现 handleSendMessage：读取 app、contact、message，委托 MessagingSkill(accessibilityService, context).sendMessage。
35. 实现 finish 分支：返回 FINISH: summary。
36. 用 Kotlin class 或 .skill 文本写 Skills：内置 AutoReplySkill 在收到通知后 open_app、delay(1500)、getScreenInfo、llmEngine.generateReply(systemPrompt, context, instruction)、send_message。
37. 文本 .skill 格式：写 name、description、steps，例如 morning-briefing.skill 依次 open_app(app_name=Weather)、get_screen_info、open_app(Calendar)、get_screen_info、open_app(Gmail)、get_screen_info、finish(summary=...)。
38. 可选 Cloud Mode：实现 CloudLLMEngine : LLMBackend，从 POKECLAW_CLOUD_API_KEY 和 POKECLAW_CLOUD_ENDPOINT 读取配置，默认 https://api.openai.com/v1；在 DI 切换后端，ToolDispatcher 和 orchestrator 不变。
39. 实现 ModelManager：默认模型 URL https://huggingface.co/google/gemma-4-e2b-it-litert/resolve/main/model.litertlm，文件 context.filesDir/gemma4_e2b.litertlm；isDownloaded 检查存在且 >1_000_000_000L。
40. 实现 downloadModel：HttpURLConnection 打开 URL，读取 contentLengthLong，用 8192 字节 buffer 流式写入 modelFile，累计 downloaded 并调用 onProgress；提供 getModelPath。
41. 自定义模型：把 .litertlm 放入 context.filesDir，并调用 llmEngine.initialize(customPath)。
42. 集成 ViewModel：用 @HiltViewModel 注入 TaskOrchestrator；用 MutableStateFlow 暴露 messages 和 isRunning；submitTask 在 viewModelScope 中运行 orchestrator.runTask，追加 user/agent 消息并处理异常。
43. 实现 Quick-Task Cards：定义 quickTasks 列表，包括 Summarize notifications、Battery report、Storage analysis、Installed apps、Bluetooth state；用 LazyRow 和 AssistChip 展示并传入 prompt。
44. 采用 Read screen → act → verify 模式：navigateToContact 先 getScreenInfo，若已包含 contact 返回 true；否则 tap search、delay(500)、inputText(contact)、delay(1000)，再 getScreenInfo 验证。
45. 采用 Retry with backoff：retryWithBackoff(times=3, initialDelay=500) 循环尝试 block，失败后 delay(currentDelay) 并 currentDelay *= 2，最后再执行一次并让异常抛出。
46. 采用 Wait for UI element：waitForElement(target, timeoutMs=5000, pollMs=200) 在 deadline 前轮询 getScreenInfo().contains(target)。
47. 排查常见问题：getScreenInfo 返回 Screen unavailable 时检查设置→无障碍→PokeClaw 已启用；点击无效先 getScreenInfo 并滚动；模型 OOM 关闭后台应用并确认设备 RAM ≥8 GB；模型下载需检查网络和存储。

适用边界 · 注意事项

• 没有 Android 真机/模拟器、无法启用无障碍服务或设备 RAM 低于约 8 GB 时不要用本地 Gemma 4 方案。
• 只需要简单 ADB/UI Automator 脚本，或已有成熟云端手机 Agent 且不在意云依赖时，不必引入本地 LiteRT-LM 与模型下载。
• 不允许使用无障碍权限、不能分发开源 PokeClaw 或不能下载约 2.6 GB 模型/许可证不匹配的场景不适用。