手机端 AI Agent 要从聊天式推理走向真实操作，首先得解决两个基础问题：怎样读取当前屏幕，怎样调用系统完成点击、输入和启动应用。一篇来自掘金的技术文章给出了一种工程化做法：在 APK 内运行 Python 内核，由 Kotlin 壳承接安卓侧能力，再通过桥接层把“看屏幕、点按钮”的原语交给 Agent。项目核心思路是：Python 只负责发指令，Kotlin 负责真机执行。
把安卓能力注入 Python，而不是让 Python 直接调安卓
该项目启动后，Kotlin 先拉起 Python 解释器，再通过 Chaquopy 的跨语言调用能力，把一个安卓侧派发器注入 Python 模块 hachimi_kernel.bridge。此后，Python 侧不需要 import 安卓 API，也不直接调用截图或控件树接口，而是调用 Kotlin 传入的派发器对象。
以“看屏幕”为例，Python 只需调用 _bridge.call(“observe”, json.dumps({…}))；指令传回 Kotlin 后，由 PrimitiveDispatcher 根据 observe、tap_by_id、tap_xy、type_text、launch_app 等名称分发到真正的安卓代码，例如读取无障碍树、按控件 ID 点击、按坐标点击、输入文本或打开应用。
这种注入式设计让 Python 内核保持相对纯净：它不依赖具体安卓细节，也便于在电脑端单独测试；代价是 Python 侧可用能力来自外部注入，需要提前约定接口。项目中，PrimitiveDispatcher 同时被调试桥和 Python 桥共用，保证不同入口调用的是同一套原语。
JSON 成为桥接层的通用协议
跨语言传数据时，项目没有直接传递复杂对象，而是统一使用 JSON 字符串。原因来自一个实际坑：Chaquopy 返回的 PyObject 如果直接 .toString()，得到的是 Python 的 repr 格式，带单引号，Kotlin 的 JSONObject 无法解析。因此，两侧约定进出都先用 json.dumps 和 json.loads 包一层。
这一选择不仅解决了桥接问题，也让整条链路的数据结构保持一致。Python 与 Kotlin 之间、模型与工具之间、Agent 本地轨迹落盘，都使用同一套 dict/JSON 结构。出现异常时，开发者可以更容易判断问题出在模型、工具参数还是桥接执行层。
在工具能力上，项目将一批基础动作注册为 Agent 可调用的工具：
- 屏幕感知：observe 用于读取当前界面 UI 树，screenshot/grab_frame 用于获取像素图作为视觉兜底。
- 界面操作：tap_by_id、tap_xy、type_text、gesture、launch_app、press。
- 辅助动作：wait 用于等待界面加载，look 用于显式查看屏幕。
另有 load_skill 和 search_skill 两个纯 Python 工具，用于调用此前沉淀的操作套路。
一次任务的完整闭环
文章以一次真实任务走查展示了桥接层的位置。用户在 App 内点击开始后，Kotlin 收到 HTTP 的 /task 请求，并调用 Python 的 start_task。Python 在后台线程拉起 MiniLoop 主循环，把目标和大模型配置传入。
每轮循环中，大模型根据当前上下文返回下一步动作，例如先调用 observe。Python 通过桥接把指令交给 Kotlin，Kotlin 读取无障碍树并将 JSON 结果传回。模型拿到屏幕信息后，再决定点击某个按钮，于是调用 tap_by_id，Kotlin 执行真实点击。若模型确认目标完成，则调用 task_done 结束循环。
为了避免 Agent 无序操作，MiniLoop 还设置了多道护栏：
- 连续 4 次调用完全相同的工具和参数，会判定为 stuck 并终止。
- 同一工具连续失败 3 次，系统会在上下文中加入“请更换执行方案”的提示。
- 启用完成判据时，模型调用 task_done 会被 verify 复核，未通过则继续执行。
- 默认最多 24 步、墙钟 600 秒，超限按未完成处理。
远程调用与工程化参考
除了让 Agent 在 App 内运行，桥接层还提供了本地回环 HTTP 服务，监听 8071 端口。电脑或脚本可以通过 /task 提交目标，触发手机 Agent 执行任务；/health 用于查看状态，/stop、/pause、/resume 用于控制流程。
这意味着手机端 Agent 不只依赖用户点击开始按钮，也可以成为被外部系统调用的执行能力。对开发者而言，这类设计把模型推理、系统操作和任务控制拆成了可调试的层次：Python 负责策略循环，Kotlin 负责安卓原语，JSON 负责统一通信，护栏负责约束边界。
相关项目仓库为 github.com/momo-null/hachifish。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/cong-hui-si-kao-dao-neng-dian-ji-kotlin-yu-python-qiao-jie
