Mobile Jev：基于 Mobilerun 与 TypeSafe Jev 的独立 Android 手机代理
Mobile Jev 是一个独立的移动端 Agent 项目：由 TypeSafe 的 Jev 模型负责决策，通过 Mobilerun API 在真实 Android 手机上执行操作，无需 ADB 连接。项目自带 React 实时工作室、CLI、执行轨迹（trace）与请求级延迟测量，采用 MIT 许可证，面向需要在真机上跑自动化任务的开发者。
社区作者 · zZz
它解决什么问题
Mobile Jev 的核心主张是“一个目标、一台真实 Android 手机、由 Jev 做决策”。它是一个独立运行的移动端 Agent，建立在 Mobilerun（设备与服务）和 TypeSafe 的 Jev 模型之上，通过 Mobilerun API 观察并操作设备，全程不需要 ADB 连接。仓库同时提供实时 React 工作室（studio）、命令行工具（CLI）、执行轨迹记录以及请求级别的延迟测量。
页面给出的演示描述（配图 1）：Jev 打开 Uber，输入从旧金山机场到金门大桥的路线，并走到支付选择环节。录制的任务计时显示 9 个动作约 21 秒。演示并未展示完成下单，即未证明预订成功。
决策循环（README 中的流程图）：观察设备 → 索引控件与已安装应用 → 单次 Jev 请求（操作 + 候选目标）→ 校验所选分支与新鲜目标 → 通过 Mobilerun 执行 → 回到观察。Jev 可选择的操作包括 OPEN_APP、TAP、TYPE_TEXT、滚动、导航、WAIT、DONE、BLOCKED。操作问题与兼容目标问题合并为一次请求，未使用的目标答案不允许被执行。应用启动目标来自设备已安装应用 API：当目标中明确点名已安装应用时，用精确名称匹配缩小清单；否则最多提供 200 个应用，启动器始终可用。
执行器的行为约定：坐标由观察到的 bounds 解析；校验概率分布；拒绝过期目标；在传输失败不确定时不重试设备变更；在下一次观察前记录动作，因此读取失败不会抹掉已执行的动作。文本来自目标中的精确 span——Jev 选择 span，代码把文本复制进输入框；可用 --text "exact field value" 覆盖候选文本。该实现不会生成任意文案，也不会编造缺失的个人信息，因此不需要单独的文本生成模型。
文本替换在可回读聚焦字段时使用 API 更快的 accepted 完成模式，并在下一次观察中校验完整字段值后才继续；若值无法验证则停止运行而不重试输入。追加输入、密码字段以及无可读目标的字段仍使用服务端 committed 完成模式，也可用 MOBILERUN_TEXT_COMPLETION_MODE=committed 或 CLI --text-completion committed 强制全部使用该模式。
可信度方面：置信度可见，并提供可选的 --confidence 截断值。Jev 返回 DONE 并不构成成功的独立证据，需要检查设备实际状态，尤其是数值、日期和多步目标；demo runner 提供针对具体任务的验证。
速度与可复现性：模型传输复用 HTTPS 连接；设备就绪状态短暂缓存；循环在动作后立即观察，对状态切换做有界轮询，而不是每次交互后固定 sleep；策略中不存在预置的点击序列，每一步仍由 Jev 决定。请求计时把 DNS、TCP/TLS、响应等待和下载从总墙钟时间中拆分出来；响应等待包含网络、服务端与设备耗时，不只服务端处理。300 ms 的滑动也会包含其请求的手势时长。
相同提示词不保证得到相同轨迹：应用版本、语言环境、当前屏幕、账号状态、网络与模型版本都会影响结果；jev-latest 使用方便，做对比实验时应将 TYPESAFE_MODEL 设为受支持的固定版本，并把返回的模型名保存在轨迹中。
工作室（studio）能力：使用官方 @mobilerun/react 组件做实时设备画面串流；目标输入、已执行动作时间线、模型延迟，以及在完成、失败或取消时停止的任务计时器；停止控制、重连、全屏与最近运行记录；Clear 清除已结束的运行并重置计时器；同一时间一个任务独占所配置的设备；桌面工作区适配单屏，活动内容在面板内部滚动。账号 API Key 留在服务端，浏览器只收到设备范围的流式凭据；应用绑定 localhost、校验请求来源，定位为单一本地操作者使用，公开或多用户托管需要自行实现认证与设备授权；最近运行记录保存在内存中，服务重启即清空。
目录结构说明：scripts/mobile-agent/ 为设备适配器、Jev 策略、执行器、传输层、CLI 与测试；apps/jev-studio/ 为 Next.js 工作室、设备凭据路由、SSE 与任务生命周期；scripts/doctor.mjs 做配置与设备连通性检查；scripts/demo.mjs 为可重复演示与结果验证；artifacts/ 存放仅本地的轨迹、截图与测量数据。
— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。
安装 / 开始使用
前置条件（Requirements）：Node.js 24 推荐（最低支持 22.16+）、pnpm 10.30.1、curl 7.70+、一台已就绪的 Mobilerun Android 设备，以及 Mobilerun 与 TypeSafe 的 API Key。项目在 macOS 本地测试；CI 在 Linux 上运行离线测试与构建（CI 不需要 API Key，也不控制手机）。
一、克隆与安装
步骤 1
git clone https://github.com/droidrun/mobile-jev.git步骤 2
cd mobile-jev- corepack enable
步骤 4
pnpm install --frozen-lockfile步骤 5
cp .env.example .env.local二、配置密钥与设备
- 在 .env.local 中填入 MOBILERUN_API_KEY 和 TYPESAFE_API_KEY。
步骤 7 · 列出设备：
pnpm devices- 把 MOBILERUN_DEVICE_ID 设为你要控制的那台设备。
步骤 9 · 运行自检：
pnpm doctor密钥来源：Mobilerun key 从 Mobilerun 的 API keys 页面获取；TypeSafe key 从 TypeSafe 控制台获取。通过 Mobilerun 连接或开通你自己的 Android 设备，设备/服务费用与本项目分开计费。默认 API 端点为生产环境，如需自有环境可设置 MOBILERUN_BASE_URL；代码中不含固定的账号或设备 ID。
三、启动工作室（首次运行）
步骤 10
pnpm dev- 打开 http://127.0.0.1:3040，输入一个目标并点击 Run task。
环境变量优先级：已导出的变量 > .env.local > .env。已经在 shell 里 export 变量同样可用。
四、运行内置演示
pnpm demo dark-theme --reset该演示目标为“Turn on dark theme in Android Settings.”。Jev 会从设备已安装应用中找到 Settings，通过 Mobilerun API 打开它，选择相关控件并更改设置；demo runner 会再次读取屏幕，验证 Dark theme 开关确实处于打开状态，而不会把模型的 DONE 响应当作成功证据。--reset 会先让 Jev 建立并验证“关闭”的基线状态。安装、任务执行与验证分别计时，每次尝试（包括失败）都保留在本地。
五、使用 CLI
预览下一步决策但不执行：
pnpm agent run "Turn on dark theme in Android Settings."执行目标并保留真实模型决策：
pnpm agent run "Turn on dark theme in Android Settings." \--execute --steps 20 --trace artifacts/dark-theme.jsonl
观察手机或测量 API：
pnpm agent observepnpm agent screenshotpnpm agent profile --out artifacts/api-profile.json调试用直接控制：
pnpm agent tap 300 500pnpm agent type "San Francisco" --clearpnpm agent back用 --device ID 可覆盖已配置的设备；
pnpm agent --help 列出全部选项。轨迹与截图被 git 忽略，且不会覆盖已存在的文件。
六、生产构建与检查
pnpm check # 测试、lint、类型检查、格式化、生产构建pnpm buildpnpm start # 在 localhost:3040 运行生产工作室常见问题与注意事项：
- 实时命令（agent run --execute）与 demo 命令会发起真实的模型/设备请求；CI 不会。
- 文本输入默认只使用目标中的精确 span，可用 --text "exact field value" 覆盖候选文本；追加、密码字段或无回读目标的字段使用服务端 committed 完成模式，也可全局设置 MOBILERUN_TEXT_COMPLETION_MODE=committed 或 CLI --text-completion committed。
- 若字段值在下一次观察中无法验证，运行会停止而不是重试输入。
- 应用绑定 localhost 且校验请求来源，仅供单一本地操作者使用；公开或多用户托管需自行实现认证与设备授权。
- 最近运行记录存于内存，服务重启后清空。
- 同一提示词不保证得到相同轨迹，建议对比运行时把 TYPESAFE_MODEL 设为受支持的固定版本。
来源教程配图
