安卓本地 Agent Soodok/Deepseek-Harness-Local-Android

DSH Mobile · 面向 Android 的 DeepSeek Harness

把完整的 Node.js 智能体引擎，以 Android 原生二进制打进 APK。
不套容器、不装发行版、不要 Root、不要 Termux、不要电脑。
装完即用，冷启动 3 秒级。

为什么快 ·架构 ·能力全景 ·路线对比 ·安装 · English ·

⚡ 为什么快

这是本项目最核心的一条，值得单独讲。

Android 上的智能体方案快不了，原因通常是架构性的。 它们要么在手机上现搭 Linux 环境（Termux + apt），要么跑一层 proot 容器（glibc rootfs 500 MB～2 GB），要么打包一个冻结的 Termux 快照。这三条路的共同点是——启动时要做的准备工作太多：解压 rootfs、挂载伪文件系统、初始化软件源、装载环境变量。

DSH Mobile 走的是另一条路：没有中间层。

| 方案 | 跟引擎之间隔了什么 | 冷启动 |
| Termux 手动配置 | Perl/bash 启动链 + apt + 环境初始化 | 分钟级 |
| proot + Ubuntu | 内核 → proot 用户态 → glibc → 发行版 → Node | 十几秒起 |
| 冻结快照 | 解压 rootfs → 修补路径 → 启动 | 数十秒 |
| DSH Mobile（本项目） | — 直接 execve bionic Node | 3 秒级 |

关键在于：我们把 dsh 需要的整套运行时，编译成 Android 原生（bionic）二进制，直接塞进 APK。 运行时不需要「启动」，它本来就在那儿。冷启动真正做的事只有三件——解压（仅首启一次）、起 Node、等回环端口就绪。

实测数字

| 场景 | 设备 | 冷启动到引擎就绪 |
| 旗舰真机 | 一加 15T（Android 16） | 3.4 秒 |
| 主流机型 | 各品牌中端 Android | 5 ~ 6 秒 |
| 极端低端 | 紫光展锐手表（3 GB 内存） | 13 秒 |
| 模拟器 | x86_64 / 2.5 GB 内存 | 2.2 ~ 2.7 秒 |

作为参照：proot 系方案在不少中低端设备上直接起不来，主流机型上平均也要十几秒；Termux 手动配置首次需数分钟。

一台 3 GB 内存的紫光展锐手表能跑起来，本身就是架构的证明——同样的内存，proot + glibc 连 rootfs 都铺不开。

这些数字是怎么来的

不是调参调出来的，是几个设计决策叠加的结果：

| 设计决策 | 换来了什么 |
| bionic 原生运行时，不走 glibc、不套容器 | 省掉 proot 那层用户态翻译，也省掉 rootfs 解压与挂载 |
| 运行时预置进 APK（125 MB 压缩 / 404 MB 解压 / 14572 个文件） | 首次使用无需额外下载，装完即用，离线可启动 |
| targetSdk = 28（sideload 策略，与 Termux 同款） | 豁免 Android 10+ 的 W^X 限制，可直接 execve 私有目录下的二进制 |
| CI 收集 + SONAME 去重 + SHA 校验的运行时流水线 | 每次发布都是可复现产物，不是「我这台机器上能跑」 |
| 全部 .so 按 16 KB 页对齐 | Android 15+ 的 16 KB 页内核设备直接可用 |
| 前端注入 polyfill（14 个现代 API） | WebView API 门槛从 Chrome 126 拉回到 85，国产 ROM 常见的 96 实测可用 |

🧱 架构

graph LR
A["APKassets/runtime.zip"] --> B["bionic Node.jsdsh 引擎 + 工具链"]
B -->|"execve 直接启动"| C["dsh 引擎进程127.0.0.1:3080"]
C --> D["WebView原生 App 壳"]
C --> E["Agent 工具链文件 / 终端 / 无障碍"]
D -.->|"localhost"| C

分层职责很清晰：

- 运行层（本项目负责）：bionic Node 运行时、前台服务保活、三级权限、扩展中心、原生化 UI
- 引擎层（上游负责）：插件体系、WebUI、工具调用链、会话持久化 —— 全部来自官方 dsh，原样保留

这不是自研 Agent 框架。 桌面上 dsh 能做的事，这里都能做；插件生态通用，能力上限跟着上游走。

✨ 能力全景

下面这些不是「功能列表」，而是为了让桌面级引擎在 Android 上真正跑通，逐项啃下来的硬骨头。每一项都对应真实的失败现场。

🖥️ 真 PTY 终端：原生 C 写出来的

Web 终端看起来简单，实际是全项目最难的一层。上游 @deepseek-ai/dsh-subprocess-local 有两处完全不认识 Android：

1. 进程探测器拒收该平台。createProcessInspector() 只认 linux / darwin / win32，其它平台直接抛 terminal inspection is unsupported on platform android。Termux 构建的 node 报告的是 process.platform === "android"——不是 linux。所以任何终端的 spawn 在第一步就死了。而 Android 有完整 procfs，上游那个 Linux 实现本来就是对的，只是没被选上。

2. node-pty 是空壳。它没有 Android 预编译产物，官方收集脚本只能塞进一个「一调用就抛错」的占位实现。

我们的做法：

- 补丁让探测器把 android 当作 linux 语义（patch-node-pty-android.py）
- 自己写了 581 行 C：dsh_pty.c + dsh_pty_exec.c，通过 posix_spawn + openpty 提供真实的 PTY 能力
- node-pty 替换成转发到该原生助手的兼容实现

结果是真有 bash 的终端：能跑 top、能开 vim、能接需要 tty 的交互式命令。不是管道模拟。

细节见 scripts/patch-node-pty-android.py 头部注释。

🔧 14 个 Android 适配补丁：把桌面引擎掰到手机上

这是本项目最不显眼、也最费工的部分。上游引擎默认假设自己跑在 Linux 桌面，每一个「想当然」在 Android 上都是崩溃点：

| 补丁 | 解决的问题 |
| patch-node-pty-android | PTY 探测器拒收 android 平台；node-pty 空壳 → 桥到原生 C 助手 |
| patch-ptc-runtime-android | PTC 子进程清空环境变量 → libz.so.1 not found（Android 没有 ldconfig，只能靠 LD_LIBRARY_PATH）；外加 bootstrap 路径映射兜底 |
| patch-webview-polyfill | 前端用了 14 个现代 Web API，旧 WebView 全没有 → 注入 polyfill，门槛从 Chrome 126 降到 85 |
| patch-fs-local-android | 文件系统的路径语义、权限检查假设 Linux 桌面 |
| patch-apiproxy | openPath / openTextFile 调 xdg-open / open / start，Android 全无 |
| patch-attachment-local | 附件本地存储的路径与 URI 处理 |
| patch-bash-sysbashrc | 装了 Termux 的设备上，bash 去读 /data/data/com.termux/... → Permission denied |
| patch-curl-wrapper | bin/curl 缺 LD_LIBRARY_PATH，依赖库找不到 |
| patch-ptc-runtime-android | 扩展工具链变量（Python/Perl/Git/ImageMagick/Rust…）全部缺失 → 在 PTC 里静默失效 |

每个补丁都 fail-fast：上游重构导致锚点没命中就中止构建，而不是 WARN 之后假装成功——漏打一个补丁，就意味着某个功能对用户直接不可用，宁可发不出来，也不能悄悄坏掉。

🔄 运行时换装：两阶段提交，不怕中途被杀

换运行时不能「先删再解压」——那会留下「删完就没」的致命窗口。也不能简单「解压到新目录再换名」：换名要逐个顶层条目做，任何一次之后被杀，磁盘上就是新旧混合态。

更阴险的是：混合态不一定被完整性检查判为不完整。检查只查「锚点文件在不在 + node 架构对不对」，新 bin/ 配旧 lib/ 完全通得过。所以「反正不完整会重装」这条兜底不可靠——最坏情况是带着错配的运行时启动，然后各种诡异崩溃。

我们的做法（v1.4.26 起）：

1. 解压到 engine.staging，engine/ 全程不动
2. 校验 staging（锚点文件 + node 可执行位 + ELF 架构）
3. 写一份 .runtime-swap 意图日志（记录「我要开始换了」）
4. 逐个顶层条目换名
5. 保留 engine.old 直到引擎首次进入 Healthy
6. 下次启动若发现意图日志存在但没完成 → 知道是混合态，走恢复

这是数据库领域的两阶段提交思路，搬到文件系统换装上。低内存被 OEM 杀后台是 Android 常态，没有这套机制，运行时更新就是一场赌博。

完整设计与失败矩阵见 docs/RUNTIME_SWAP.md。

🔌 扩展中心：把手机变成工作站

21 项环境扩展一键安装：Python、OpenJDK 17、Go、Rust、Ruby、PHP、Lua、Perl、Clang、CMake、Git、SQLite、FFmpeg、ImageMagick、OpenSSH、Vim、ADB 等。

难点不在下载，在让装完的东西真的能用：

- 国内镜像自动切换（清华 TUNA → 中科大 → 北外 → Termux 官方），任何一条挂了自动顺延
- 依赖闭包递归解析，逐包 SHA-256 校验，原子发布——不会留下半套环境
- shebang 自动修复：Termux 包里的脚本写死 #!/data/data/com.termux/files/usr/bin/python，在我们这儿不存在 → 装完自动改写，env python3 直接可用
- ELF 架构校验：解压前断言二进制架构与设备匹配，避免装了个 arm64 包到 x86_64 上
- Agent 也能自己装：Root 模式下已实测自装 Android SDK 命令行工具，AI 缺什么补什么

🧩 社区插件：整个 dsh 生态搬过来

内置 3540 个社区插件目录（23 个分类，中英双语），搜索、看详情、一键装卸，全程不离开 App。

真正的工作量在判断哪些插件能装：

- 兼容性三级分类：纯 JS（能跑）/ 需要原生模块（多半不行）/ 引擎 fork（设计上不兼容），用静态分析 package.json 与源码特征判定
- 3540 条不能一次渲染：早期版本把全部结果塞进 ScrollView，两万多个 View 直接把主线程压死 → OOM/ANR → 进程被杀 → 引擎看门狗误判重启。现在改增量分页（首屏 30 条 + 滚动追加），并加了 12 项回归探针锁住
- pnpm 锁自愈：store 锁目录属主损坏（Root 残留 000 权限）时删不动，改用 rename 绕开——rename 只改父目录条目，不进入目录内部，属主正常就必成功

📱 原生竖屏 UI：不是把桌面缩小

三个客户端插件协同：侧栏全宽、设置面板重构、右侧面板全屏。信息密度、触控热区、字号层级全部重排。

这不是「响应式 CSS」级别的适配——是重新设计了手机上的信息架构：什么该藏进二级、什么该常驻、单手握持时拇指能够到哪里。

🫧 悬浮窗 · 保活 · 无障碍：手机端真正的增量价值

桌面版给不了的三件事：

1. 系统级悬浮窗（桌宠） 插件驱动的独立 overlay，资源包制（多套素材可换、云端下载、后台服务下载不怕退出页面）、动画链（加权随机动作 / 翻面 / 动画驱动位移）、气泡台词库（六档语义，可自定义措辞）。

2. 无障碍控制：给 AI 装眼睛和手

读屏 / 点击 / 输入 / 滑动 / 长按 / 拖拽等 21 种原语，实测约 1.45 秒/步。

三条铁律是踩血换来的：

- 验证必须是目标状态，不是动作描述。「点了按钮」没有意义，「页面出现了 X」才有意义。AI 自报成功是最不可信的信号——实测它会对着错误页面的通用标记自认成功
- 失败要回退到「认得的状态」再重试，同一步骤连续失败不超过 2 次就换打法
- 感知分层兜底：无障碍树 → OCR → 帧差。任何一层都可能缺失（ColorOS 浏览器 / WebView / 游戏拿不到节点树），只有分层才可靠

这份经验已整理成 完整的交接手册，包含场景分级、原语清单与坑位记录。

3. 后台不被杀 specialUse 前台服务 + 指数退避监督器。Android 的 OEM 后台清理是敌对环境，dataSync 类型有 6 小时上限，specialUse 没有——这个类型选择本身就是研究出来的。

🔐 三级权限：渐进式提权

| 模式 | 能力 | 说明 |
| 普通 | 沙箱内运行 | 安全默认，AI 碰不到系统 |
| Shizuku | adb 级操作 | 免 Root，跑命令、保活、杀进程 |
| Root | 完整系统权限 | su 闸门管控，每次提权可见 |

双身份共存是个真实的坑：Root 模式下引擎以 uid 0 跑，App 主进程是普通 uid，两者共用 dsh-home。我们踩过的一次：每次启动引擎都会递归 chown 整棵树，把 root 身份的 pnpm 按 uid 分后缀的锁目录也改错了属主 → 插件装卸全失败、每次重启复发。修法是 chown 之后按目录名的数字后缀把属主还原回去。

🌐 内置 SSH 远程工作区

手机连服务器改代码：远端工作区、Web 终端、隧道与 ssh_ 工具，全部内置。SSH 私钥可以在应用内生成或从文件管理器手动放入，Agent 直接可用。

🎙️ 语音输入

双通道识别（离线 PocketSphinx + 云端），发送去重、面板停靠。离线引擎在体积与识别率之间做了取舍，云端作为补足。

⚙️ 工程化：CI 一手包办

- 双架构矩阵构建（arm64-v8a / x86_64 × full / noruntime = 8 个 APK 变体）
- 运行时流水线：从 Termux 仓库收集 → zod 嵌套去重 → SONAME 别名去重（省 37 MB）→ 打 14 个补丁 → 写 BUILD.json → SHA 校验
- 签名索引：runtime-index.json 用 EC P-256 detached 签名，私钥只放在 CI secrets，App 端验签失败直接拒绝（不降级）
- 15 项回归探针：每个都对应一次真实事故，PR 阶段就能拦住回归
- git 卫生门禁：推送前自动检查工作区脏、远端有新提交、CRLF 污染、探针目录误加

🆚 路线对比

| | Termux 手动配置 | proot + Ubuntu | 冻结快照打包 | DSH Mobile |
| 冷启动 | 分钟级 | 十几秒起，部分设备起不来 | 数十秒 | 3 秒级 |
| 最弱设备 | 需自行折腾 | 3 GB 内存设备基本无望 | 看快照体积 | 3 GB 手表 13 秒 |
| 安装体验 | 装 Termux、配环境、装依赖 | 装容器与发行版 | 装即用 | 装即用 |
| 首次可用需下载 | 手动配置 | rootfs 500 MB～2 GB | 无 | 无 |
| 运行时 | 活环境（可扩展） | 容器内 glibc | 死快照，随包冻结 | 自建 bionic 闭包，CI 收集校验 |
| 许可证合规 | — | — | ⚠️ 快照打包 GPL 组件，合规存疑 | 仅含 MIT/BSD/ISC/Zlib 组件 |
| 权限分级 | 无 | 无 | 无 | 三级模式 + su 闸门 + Shizuku adb 桥 |
| 环境扩展 | 手动装 | apt | 死快照，不可扩展 | 21 项一键装 + AI 自助安装 |
| Termux 依赖 | 需要 Termux App | 需要 | 快照即 Termux | 零依赖（硬编码路径已重定位） |

路线之间不是替代关系：Termux 系是在 Android 上搭一个 Linux 环境再跑 dsh；本项目把 dsh 需要的运行时打进 APK。两条路线跑的是同一个 dsh，差别在启动路径的长度。

📄 完整路线剖析见 docs/android-agent-routes.zh.md（English）。

📦 安装

从 Release 下载（推荐）：前往 Releases 下载 APK，允许安装未知来源应用后安装。手机选 arm64-v8a。

⚠️ 先认架构，再选包

发布页里同一个版本有多个 APK，先看架构再看形态。装错架构会装不上。

手机装 arm64-v8a，x86_64 只给电脑上的模拟器。

| 你的设备 | 装哪个 | 说明 |
| 手机（绝大多数） | arm64-v8a | 64 位 ARM，正常在售机型都是这个 |
| 模拟器 | x86_64 | Android Studio / 蓝叠等电脑模拟器 |
| 32 位 ARM 老机 | — | 本项目不提供 32 位产物，无法安装 |
| 32 位 x86 老模拟器 | — | 同上 |

不确定自己的架构？开启 USB 调试后执行：

adb shell getprop ro.product.cpu.abi

装错时的典型报错是「应用与手机 CPU 不兼容」，Android 安装器原文为 INSTALL_FAILED_NO_MATCHING_ABIS。这不是应用坏了，换一个架构的包即可。曾有约 7% 的下载量误取了模拟器包，所以这里单独列出来。

两种包怎么选：

| 包 | 体积 | 适合 |
| 完整包（-release.apk） | ~150 MB | 绝大多数人。运行时预置，装完即用，离线也能启动 |
| 简单包（-release-noruntime.apk） | ~24 MB | 空间紧张，或想走云端更新运行时。首启需联网下载约 125 MB |

两种包功能完全相同，只差运行时是否内置。共用一个签名，可互相覆盖升级。

环境要求

- Android 8.0 ~ 16（minSdk 26）
- WebView ≥ Chrome 85（国产 ROM 常见的 96 实测可用；构建时注入 polyfill，把 API 门槛从 126 拉回 85）
- 存储：约 720 MB（APK + 解压后运行时）

🚀 快速上手

1. 安装 APK，首次启动走引导（语言 / 朝向 / 主题 / 权限模式）
2. 等引擎就绪（状态栏显示 Engine ready）
3. 在设置里填入模型 API Key，或登录 DeepSeek 账号
4. 选一个工作区，开始对话

想做开发任务：设置 → 扩展中心，装 Python / Git / Node 等；然后告诉 AI 要做什么。

🔧 从源码构建

前置：JDK 17+、Android SDK 36、Node 22、Python 3

1) 收集运行时（从 Termux 仓库拉 bionic 包 + 打 Android 补丁） ./scripts/build-runtime.sh --abi arm64-v8a --out _runtime_bak/rt-arm64.zip

2) 构建 APK
gradle :app:assembleDebug -Pabi=arm64-v8a -Ppackage=full \
-PruntimeZip=$PWD/_runtime_bak/rt-arm64.zip

输出：app/build/outputs/apk/debug/app-debug.apk 流水线细节（去重、PTC 补丁、polyfill 注入、BUILD.json、索引签名、发布流程）见 docs/git-workflow.md 与 docs/RELEASE.md。

📚 深度文档

每项能力都有独立文档（设计取舍、实测数据、排障清单）：

| 文档 | 内容 |
| 无障碍控制 | 21 种原语；多层视觉兜底、每步验证；实测 ~1.45 s/步 |
| SSH 远程工作区 | 内置 @xiaopb/dsh-hardssh：远端工作区、Web 终端、隧道与 ssh_ 工具 |
| 闭环设计笔记 | 端侧决策引擎的设计与演进记录 |
| 竖屏 UI 插件 | 侧栏全宽 / 设置面板重构 / 右侧面板全屏 |
| 局域网 WebUI | 反向代理、6 位验证码、常驻提醒与关闭链路 |
| 语音输入 | 双通道识别、发送去重、面板停靠与已知问题 |
| 桌宠 | 系统级悬浮窗：安装与限制（使用）、桥插件与内部逻辑（架构）、路线图 |
| 通知与后台行为 | AI 操作进度、任务完成、局域网提醒、退出彻底化 |
| 复杂场景实测 | 噪声页面、跨应用任务、失败恢复的实测记录 |
| 快速路径选择 | 端侧 UI 元素选择与判别 |
| Git 工作流 | 合并原则、推送通道、发版与验证清单、历史事故教训 |
| 发布与签名 | 正式 key 保管与备份、GitHub Secrets、debug+release 构建、edge / tag 发布 |
| 版本发布说明归档 | 各版本 RELEASE_NOTES_*.md（v1.3.0 起）集中存档 |

⛔ 边界（请知悉）

- 不是端侧大模型：模型走你配置的 API，本 App 负责 Agent 运行时
- 不是手机自动化 App：读屏点击只是 AI 可用的工具之一，不是产品定位
- 不做金融类应用（合规红线）
- 无障碍能力有明确边界：不注入不可检测的输入 —— 自动化与欺诈之间那条线我们不动
- 插件生态跟着上游走：dsh 引擎锁 0.2.1-rc.5，上游插件 API 变更我们需要跟进

❓ FAQ

Q：为什么 APK 这么大？ A：完整包里塞了整套 Node 运行时 + 工具链（125 MB 压缩、404 MB 解压后）。换来的是「装完即用、离线可启动、冷启动 3 秒」。不想这样可以用 24 MB 的简单包。

Q：为什么不走 proot？为什么用 targetSdk 28？ A：proot 要多一层用户态翻译和 rootfs 解压，直接吃掉启动速度——也就吃掉了低端设备的可用性。targetSdk 28 是 sideload 分发策略，与 Termux 同款：豁免 Android 10+ 的 W^X，允许直接 execve 私有目录下的二进制。这是冷启动能压到 3 秒的前提之一。

Q：Android 15 / 16 能用吗？ A：能。全部 .so 按 16 KB 页对齐，适配 16 KB 页内核；界面依赖系统 WebView（需 Chrome 85+）。

Q：数据存在哪？卸载会丢吗？ A：引擎、凭证、工作区默认在应用私有目录（files/dsh-home），并自动外置到共享存储（Documents/dshdata，需「所有文件访问」权限）。授权后卸载重装不丢；未授权则随应用卸载删除。

Q：需要 Root 吗？ A：不需要。默认普通模式即可完整使用；Shizuku 提供 adb 级能力；Root 是可选增强。

Q：和 DSHA / 其他移植版的区别？ A：都能跑 dsh。差别在运行层架构与启动路径——见上方路线对比，以及 docs/android-agent-routes.zh.md。

⚠️ 免责声明

本项目为社区移植，与 DeepSeek 官方无隶属关系。使用本软件产生的任何后果由使用者自行承担；请遵守当地法律法规与所接入模型服务的条款。

反馈

- Issue：提交问题（请附设备型号、Android 版本、App 版本与复现步骤）
- QQ 群：1128769016
- Telegram：https://t.me/+4VN3pYyH6i8yNDA1
- Pull Request：欢迎。合并用 --no-ff 保留提交线路，规范见 docs/git-workflow.md

🙏 贡献者

感谢每一位提交 Issue、PR 与反馈的贡献者 —— 尤其是那些把复现时间线、/proc 证据、ctime 对比一起附上的报告，它们直接促成了多个架构级修复。

许可证

MIT · 第三方组件许可见 NOTICE