手机上的 AI Agent 启动台
一个 APK 装下完整的 DeepSeek Harness 与 OpenClaw 2.0 —— 免 ROOT，免 Termux，装完即用
English · 简体中文 · 更新记录 · 安全模型 · AGENTS.md（给 AI / 开发者）
🤖 接手的 AI 或新贡献者请先读 AGENTS.md —— 项目结构、启动契约、每一条踩过的坑都写在里面，不必全库扫描。
DeepSeek Harness（@deepseek-ai/dsh）是 DeepSeek 官方的 agent harness，定位类似 Claude Code。
它为 glibc Linux 而写，直接搬进安卓会撞上一整排墙：原生模块编译不过、link(2) 被 SELinux
拦下、沙箱起不来、前端按桌面排版。
AgentBox 把这堵墙整个砌进了 APK。 装上、填 key（或跳过）、点启动 —— 不装 Termux、
不 ROOT、不敲一行命令。APK 里是一个完整的 Ubuntu 24.04：apt 能用、交互式 PTY 能用、
需要编译的原生模块能装，和你在服务器上跑的是同一套东西。
除 DeepSeek Harness 外，AgentBox 还内置 OpenClaw 2.0（openclaw 2026.8.2，随离线
rootfs 一起打进 APK，全程离线可用）。启动页上有独立的 OpenClaw 卡片：一键拉起 gateway
（Web dashboard 在 http://127.0.0.1:18789）、停止、打开，与 dsh 各管各的、互不干扰。
首次使用在「终端」页跑一次 openclaw onboard 完成模型与渠道配置即可。
| 说明 | |
|---|---|
| 🚫 零命令行门槛 | 离线 Ubuntu rootfs 打进 APK，装完即用：不装 Termux、不配包管理、不敲命令 |
| 🐧 完整 glibc 环境 | 不是裁剪版：apt / PTY / 原生模块 / Python / git 全在，上游插件零改动就能跑 |
| ⚡ proroot 零 ptrace 开销 | 传统 proot 每个系统调用两次上下文切换；proroot 用 LD_PRELOAD + 二进制补丁在进程内做路径翻译。真机实测关键项合计 +58% |
| 🔌 ADB 免 Shizuku 直连 | 无线配对与保活内置，agent 可以直接操作这台手机：点击、截屏、装应用 |
| 💾 卸载重装数据不丢 | 对话与设置放 Documents/dshdata，文件管理器里可见可备份；API key 走 Android Keystore 加密 |
| 🩺 坏了能自己说清哪坏了 | 23 项自检 + 一键修补 + 一套自愈脚本；Web 起不来时直接点名是哪个插件 |
| 🦞 双 Agent 内置 | DeepSeek Harness 与 OpenClaw 2.0 都随 APK 离线内置，启动页各管各的启停 |
- 到 Releases 下载最新 APK 装上（仅 arm64）
- 首次启动自动解压内置环境（几分钟，仅此一次）
- 「配置」页填 DeepSeek API key →「启动」页点启动 → Web UI 自动打开
就这样。想看细节可以走「分步安装」，每一步都能单独重装、单独更新。
AgentBox 不只是「能跑起来」，下面每一项都是已实装的功能。
① 环境与装机
| 能力 | 说明 |
|---|---|
| 内置离线 rootfs | Ubuntu 24.04 arm64 打进 APK，无网也能完成整个环境部署 |
| 分步安装 | rootfs / 基础工具 / Node.js / harness 四步独立，可单独重装与更新，不重复下载 |
| 多源并行测速 | 清华、阿里云、华为云、腾讯云、南大、哈工大、npmmirror… 并发测速后弹窗自选 |
| 双装机路径 | 预构建包与源码构建都支持；源码路径自动处理 node-pty 等原生模块的编译 |
| 安装即校验 | 每步装完立刻验证产物，不把「装了一半」当成功 |
| 断点续装 | 中途失败或退出后回到该步继续，不从头再来 |
② 运行时与性能
| 能力 | 说明 |
|---|---|
| proroot / proot 双运行时 | 默认 proroot（零 ptrace 开销），「配置」页一键切回 proot |
| 实测提升 | vivo V2352A / Android 14：关键项合计 +58%；tar 打包 +94%（备份走这条），stat 密集 +82%（node 模块解析） |
| 三层兜底 | 运行时文件缺失自动降回 proot；连续 3 次启动失败强制切回并告知；装机路径始终用 proot |
| Node.js 24 + pnpm | 与上游一致的运行环境 |
| 前台服务常驻 | 通知栏可见运行状态，系统不会随手回收 |
| 看门狗 | Web 掉了自动拉起，不用手动重启 |
③ 数据安全与迁移
| 能力 | 说明 |
|---|---|
| 数据不随卸载消失 | 会话 / 设置 / 附件放 内部存储/Documents/dshdata，原位留私有软链 |
| API key 加密存储 | Android Keystore（AES/CBC），密钥不出 Keystore；备份里那份同样加密 |
| 全量备份 | 手动备份保留 10 份轮换，自动备份双槽交替（永远留着上一份完整的） |
| 分范围备份 | 可选全量 / 只对话 / 只插件。部分备份恢复时只覆盖对应内容 —— 拿只含对话的包恢复，配置与插件保持现状 |
| 换机不丢对话 | 热数据在手机上是指向公开目录的符号链接，tar 默认只存链接、换设备恢复就成了空的；备份会额外把它们解引用快照一份 |
| 备份自带说明 | 包里放 AgentBox-README.txt：里面有什么、怎么手动取数据、哪些东西换设备后用不了 |
| 恢复前体检 | 只读走一遍整个包，靠 gzip 的 CRC 发现截断与损坏，并预览「多少会话 / 多大 / 来自哪个版本」 |
| 恢复极宽容 | 老备份一律放行；缺失插件后台自动补装；跨设备的 link: 路径自动重写；本机路径插件的源码随包内联 |
| 恢复后自动适配 | 跑一遍版本迁移（下线已换掉的内置插件、补回新的）并重新对齐桥 token |
| 凭据不进备份 | 本机桥 token 排除在外 —— 备份落在公共目录，不该带走这台机器的凭据 |
| 会话损坏隔离 | 坏掉的会话文件挪进 corrupt-backup，随时可取回，不让一个坏文件卡住整个 Web |
④ 设备能力（让 agent 真正操作这台手机）
| 能力 | 说明 |
|---|---|
| ADB 无线直连 | 内置配对与保活，不需要 Shizuku：agent 可以点击、滑动、截屏、装应用、读日志 |
| Shizuku 通道 | 作为备用路径保留，已授权的用户可继续用 |
| App 桥（127.0.0.1:3090） | agent 可以发系统通知、读设备信息、请求用户确认 |
| 危险命令守门人 | 覆盖关键路径、递归删除这类命令会拦下来问你，三条渠道（通知 / 前台弹窗 / 悬浮条）任选其一批准 |
| 屏幕 snapshot/act | 一次 /app/ui/snapshot 读出全部可交互元素并编号（e1/e2…），按编号点击 / 输入 / 滚动 —— 不靠截图猜坐标，界面变了旧编号明确报 STALE |
| 流式悬浮条 | AI 输出像歌词一样实时贴在屏幕顶部；显示正在执行的命令原文，思考过程可选；底色 / 透明度 / 行数 / 停留时间可调，带预览 |
| 内置终端 | 直接进 Ubuntu shell，apt install 什么都行 |
| 免 ROOT 文件访问 | 注入文件提供器，在文件管理器里直接浏览、编辑 App 私有目录 |
⑤ 可靠性：坏了能自己说清哪坏了
| 能力 | 说明 |
|---|---|
| 23 项自检 + 一键修补 | 桥 / ADB / 插件 / 会话 / 备份 / 运行时 / 公开数据 / 守卫补丁 / Web 鉴权… 逐项体检，能自动修的当场修 |
| 插件故障人话诊断 | Web 起不来时直接说「是插件 X，它要的服务不存在，点这里修」，而不是甩一屏 Node 堆栈 |
| 一整套自愈与补丁脚本 | pnpm 空壳还原、bundle 解析修复、profile 引导修复、.l2s 链摊平、会话修复、依赖修复、写文件补丁…（见 app/src/main/assets/，全部幂等、失败不阻塞） |
| 脚本增量热更新 | 关键脚本可从 GitHub 增量更新并离线验签（公钥内置，签名不符整批拒绝），不必等新 APK |
| 失败原因落盘 | 备份、安装、启动的失败原因写进文件，自检直接读 —— 不让「没反应」变成无从排查 |
| CI 守门人 | 每次推送跑 Fast checks：清单一致性 + 离线验签 + 三百余条纯逻辑断言 + assets 脚本真编译；发布时证书指纹不符直接中止 |
⑥ 网络与访问
| 能力 | 说明 |
|---|---|
| 内嵌 WebView | GeckoView，不受系统 WebView 版本拖累 |
| 局域网访问 | 手机开着 dsh，电脑 / 平板直接在浏览器里用。token 鉴权 fail-closed，命中后回设 SameSite=Strict Cookie，不让 token 随外链泄漏 |
| 一键取地址 | 启动页可复制本机与局域网地址（带 token），随心跳刷新 |
| 老浏览器兼容 | 自动注入 AbortSignal.any/timeout 与 crypto.randomUUID polyfill —— 后者在局域网 HTTP（非 secure context）下是必需的 |
| 端口可配 | Web 端口自定义，冲突自动回退并说明 |
⑦ 插件生态
| 能力 | 说明 |
|---|---|
| 插件市场 | 浏览、安装、更新、启用/禁用、删除，全在 App 内完成；四级降级链：npm 直装 → Release 预构建包 → 授权后构建 → 容器内 clone + build |
| 内置移动端适配 | 集成 dsh-web-mobile（MIT）：窄屏单栏 + 目录抽屉、设置改底部 sheet、状态栏安全区、表格与气泡排版 |
| 内置设备技能引导 | 让 agent 知道这台手机上有哪些能力可用 |
| 硬依赖自动改造 | 插件写死的服务依赖会被就地改成运行时注入 —— 一个插件不该把整棵插件树拖挂 |
| 内置插件保护 | 内置插件不会被误删；用户手动禁用过的，升级后依然保持禁用 |
| 导入导出 | 插件配置可导出备份、可导入还原 |
⑧ 开发者 / Agent 友好
| 能力 | 说明 |
|---|---|
| AGENTS.md | 给 AI 与新贡献者的入口文档：结构、契约、踩过的坑，省掉全库扫描 |
| Agent Skills | agent-skills/ 提供 device-shell（ADB / Shizuku 桥）、screen-operator（无障碍 snapshot/act）与 screen-ocr-operator（OCR 兜底） |
| 纯逻辑测试集 | 三百余条断言不依赖 Android API，秒级跑完；另有两套端到端测试：解压往返（真代码解真 tar.gz，逐个比 sha256）与停止判据（造真进程与 pid 文件跑一遍 shell 片段） |
| 活动日志 | 关键动作与失败原因留痕，用户报问题时有据可查 |
| 全 CI 构建 | 不需要电脑：推 tag 即出签名 APK，arm64 runner 现场造 rootfs |
安卓上跑 dsh 目前有两条路，各有代价，说清楚比互相贴标签有用：
| 容器派（AgentBox 走这条） | Termux bootstrap 派 | |
|---|---|---|
| 做法 | proot/proroot + 完整 glibc rootfs | 用 Termux 的包在 Android bionic 上裸跑 |
| 装机 | 装 APK 就完事 | 装 Termux → 敲命令 → 装工具链 |
| 环境 | 完整 Ubuntu，apt 与原生模块随便用 |
需要为 bionic 逐个打补丁 / 重编 |
| 开销 | proroot 已无 ptrace 开销 | 无容器层，理论最快 |
| 沙箱 | 两边都受限 | 两边都受限 |
Termux 一侧值得点名：deepseek-harness-termux
用上游补丁编译 node-pty、拿 rename(2) 绕开 SELinux 的 link(2) 限制，
deepseek-harness-android 维护着
很有价值的兼容性矩阵。「Termux 方案功能残缺」是过时的说法。
AgentBox 的差异不在「他们跑不起来」，而在于：装机不需要命令行、环境是真正的 glibc 而不是补丁摞补丁的 bionic，以及应用层带上了脚本给不了的东西 —— ADB 直连、悬浮条、 备份恢复体系、自检自愈、插件市场。
诚实列出来，省得你装完才发现：
| 项目 | 状态 | 说明 |
|---|---|---|
| 架构 | 32 位与 x86 设备不支持 | |
| 系统 | ✅ Android 8.0+ | 更老的版本没测过 |
| 包体 | 内置完整 Ubuntu 环境的代价，换来的是免下载、免命令行 | |
| bash 工具 | ✅ 可用 | 完整 Ubuntu 的 bash，agent 跑 shell 命令没有限制 |
| bash 的沙箱隔离 | bubblewrap 要 unprivileged user namespace，Android sepolicy 不给 —— 容器派和 Termux 派都一样绕不过。所以没有内核级边界，约束靠 dsh 的权限档位：默认 danger-full-access，可在配置页改成 workspace-write 或 read-only。请自行判断风险 |
|
| 卓易通 / 鸿蒙 anco | ❓ 未验证 | 理论可行，尚无真机回归 |
| 悬浮条 | 用 TYPE_APPLICATION_OVERLAY 自绘；免 ROOT 拿不到真正的「状态栏歌词」接口 |
|
| 数据位置 | 「所有文件访问」被拒时数据留在私有目录，卸载即丢（自检会明确告知当前状态） |
👉 每项权限到底暴露了什么、agent 碰得到你手机的哪些部分，见 安全模型 —— 包括我们自己列出的已知弱点。
┌──────────────────────── APK ────────────────────────┐
│ 原生 Android（Java 17）· Material3 · GeckoView │
│ ├ 启动 / 安装 / 配置 / 工作区 / 插件 / 终端 / 设置 │
│ ├ 前台服务 + 看门狗 + 通知 │
│ ├ App 桥 :3090 局域网桥 :3081 │
│ └ 悬浮条（TYPE_APPLICATION_OVERLAY） │
├─────────────────────────────────────────────────────┤
│ proroot（默认，零 ptrace 开销）/ proot（兜底） │
├─────────────────────────────────────────────────────┤
│ Ubuntu 24.04 arm64 · Node.js 24 · pnpm │
│ ├ @deepseek-ai/dsh → Web UI :3080 │
│ └ openclaw → gateway :18789 │
└─────────────────────────────────────────────────────┘
数据：会话 / 设置 / 附件在 Documents/dshdata（公开可见可备份）；
DSH_HOME 本体与 .credentials.yaml 刻意留在私有目录。
配好之后 agent 就能直接操作这台手机，不需要 Shizuku。
首次配对（约 1 分钟）
- 系统设置 →「关于手机」→ 连点「版本号」7 次开启开发者选项
- 开发者选项 → 打开「无线调试」
- 进入「无线调试」→「使用配对码配对设备」，记下 IP:端口 与 6 位配对码
- 回到 AgentBox →「工作区」页 → ADB 区域 → 填入 → 配对
配对之后：AgentBox 自己维护连接（保活 + 重连），重启手机后也会自动恢复，不用再操作。
验证：内置终端里跑 adb shell id，输出 uid=2000(shell) 即成功。
让 agent 用起来：把技能包复制到 agent 的技能目录：
cp -r agent-skills/device-shell ~/.agents/skills/
cp -r agent-skills/screen-operator ~/.agents/skills/
cp -r agent-skills/screen-ocr-operator ~/.agents/skills/云端（推荐，不需要电脑）
git tag v1.0.0 && git push origin v1.0.0 # 触发 release 流水线，自动出签名 APK流水线分两段：ubuntu-24.04-arm 原生 arm64 现场造 rootfs（带 cache），
ubuntu-latest 把离线包打进 APK 并核对证书指纹。
推 main 也会跑一次 debug 构建与 Fast checks。
本地（需要 Gradle 8.5 + Android SDK + JDK 17）
./build.sh # 需要先有 app/src/main/assets/offline-rootfs.tar.gz
bash tools/pure-logic-test.sh # 三百余条纯逻辑断言，不需要设备详见 BUILD.md。
v1.0.0 为首个正式版。项目早期迭代很快，内部结构（包名、路径、备份格式）已完成向 AgentBox 身份的统一；已知取舍与后续方向见 ROADMAP， 欢迎开 issue 或直接来群里反馈。
- deepseek-ai/deepseek-harness —— DeepSeek Harness 本体
- openclaw/openclaw —— OpenClaw 2.0（双 Agent 内置）
- proot / proroot —— 免 ROOT 容器（见 THIRD_PARTY_NOTICES.md）
- dsh-web-mobile —— 内置移动端适配
- Shizuku —— 备用设备命令通道
QQ 群 975836806 —— 测试版发布、问题反馈、插件交流。
MIT。第三方组件许可见 THIRD_PARTY_NOTICES.md。
曲线由 tools/gen-star-history.py 每周自动生成（workflow）。
GitHub 从 2026-06-30 起把 stargazers API 限制成只有仓库 admin/collaborator 能读，
第三方实时嵌入图因此普遍失效，所以数据自己拉、图自己画。