安卓智能体环境 dphmoblie/deepseek-harness-android

DeepSeek Harness 安卓版

English · 繁體中文 · 한국어 · 日本語

面向 Android 的本地 AI 工作台。 把 DeepSeek Harness、Ubuntu 运行环境、会话、插件与文件管理整合到手机里；开启相应授权后，AI 还能通过 Shizuku 执行设备 Shell（命令行）任务，或通过无障碍服务操作指定应用。

无需 Root（超级用户权限）。Linux 环境通过 PRoot 在用户空间运行，控制台由内置网页视图展示；模型推理使用你配置的服务。

| 应用包名 | io.deepseekharness.mobile |
| 最低系统 | Android 8.0（API 26）及以上 |
| 目标应用副屏 | Android 10（API 29）及以上，需 Shizuku 与设备验证 |
| 支持架构 | 仅 arm64-v8a（64 位 ARM） |
| 内置运行时 | Ubuntu 24.04 ARM64 · Node.js 24.19 · @deepseek-ai/dsh 0.2.1-rc.1 |
| 应用许可证 | MIT（运行时组件沿用各自许可证，见许可证） |

目录

- 功能特性
- 工作原理
- 安装
- 模型供应商
- 可选的 Shizuku 集成
- 目标应用副屏（实验功能）
- 从源码构建
- 安全与隐私
- 参与贡献
- 项目数据
- 许可证
- 相关文档

功能特性

- 手机上的完整 Linux 智能体环境。 Ubuntu 24.04 完全在设备本地通过 PRoot 运行，不依赖云服务器或远程桌面；应用不要求注册自己的账号，也可按需在 Harness 内登录 DeepSeek 账号使用账号模型。
- 适配手机的 Harness 控制台。 壳内以首页、插件、设置三个底部入口组织功能，并为窄屏、横屏和安全区域提供适配；会话管理整合到首页。第三方网页插件的界面与依赖各不相同，兼容性需按插件和版本验证。
- 插件导入、更新与回滚。 支持从 npm 包名、HTTPS 压缩包链接或 git+https 仓库地址导入，管理包与子插件的启停；更新时按支持的目录规则保留数据，并可切回上一版。需要安装脚本、原生编译或不同核心 SDK 的包存在限制，详见插件管理。
- 文件与外观管理。 投递区支持文件夹分类；壳内可选图片或视频背景，调整卡片颜色、通透度、模糊程度、按钮与输入框不透明度及强调色；「DSH 主题」三级页可让 DSH 跟随当前主题、连背景一起同步，或恢复默认。
- 文件浏览、打开与分享。 「文件管理」页可浏览投递区与外部工作区，普通文件可以分享，也可以交给其它应用打开；官方文档预览顶栏也有「分享」按钮，点击直接调起系统分享面板。分享范围严格限制在内置工作区 root/1 下的普通文件，路径由原生重新解析，并逐层做 NoFollow 校验，工作区外的绝对路径、目录跳转和编码斜杠一律拒绝；找不到文件时提示「工作区里找不到这个文件」，与真正的读盘失败区分开。
- 外部浏览器打开。 诊断页的「外置浏览器」可把 Harness 交给已安装浏览器完整使用（不是只读预览），「打开方式」可选「每次询问（系统选择器）」或固定某个浏览器；固定的浏览器被卸载后自动回到每次询问。
- 设置自动保存与预启动。 设置页没有统一的底部保存条：离开页面或切到后台自动保存一次，并提示「设置已保存」；「模型与密钥」页另有「保存密钥」按钮，没有改动时置灰。可选的「打开应用时预启动服务」会在运行环境就绪且已保存模型凭据时先把本机服务拉起来，不替你跳转页面，默认关闭。
- 免 Root 运行。 在普通原厂设备上即可通过 PRoot 实现用户空间容器化。可选的 Shizuku 集成可在你主动授权后额外提供 Shell 级别的设备终端（/system/bin/sh）。Shizuku 提供的是安卓 Shell 权限，而非 Root 权限。
- 开箱即用、支持离线安装。 正式版 APK 内置经过校验的 rootfs.bundle 与清单文件，无网络环境也可完成运行时安装；同时也支持经摘要固定（digest-pinned）的远程运行时来源。
- 防篡改的运行时分发。 每份清单与根文件系统镜像在使用前均按精确长度与 SHA-256 校验；下载仅接受 HTTPS 目标地址，拒绝指向私有地址的 DNS 解析结果，支持 HTTP 范围请求断点续传，解压时具备路径穿越与设备节点防护。环境就绪后以原子方式切换生效。
- 内置与自定义模型服务商。 DeepSeek、OpenAI、Anthropic、Google Gemini、OpenRouter、Groq、xAI、Mistral 以及自建 OpenAI 兼容端点均可配置 API Key；DeepSeek 还支持官方账号授权。管理端密钥由 Android Keystore 保护，运行时使用 Harness 私有的 ~/.dsh/.credentials.yaml（权限 0600）或同等受保护的启动文件，绝不回传至 WebView。
- 本机控制台访问。 Harness 只绑定 127.0.0.1。每次启动都会生成全新的 256 位传输令牌，同时保护 HTTP 与 WebSocket 请求；令牌仅保存在进程内存中，不会持久化，也不会写入 URL。模型调用和你发起的下载、插件安装等仍可能访问网络。
- 集成终端。 可在同一界面中使用 PRoot 环境内的 Ubuntu 终端，以及（可选）由 Shizuku 支持的安卓设备终端。
- 应用内运行时自检（18 项）。 运行环境出问题时不必依赖 bash——自检按固定顺序探测 18 项：Shell（bash）、Node.js、沙箱启动器 landlock-run、内核 Landlock 支持、沙箱内命令执行、PTY 模块 node-pty 与沙箱内 PTY、访客数据目录、附件目录、硬链接（原子写入的前提）、ripgrep、C 编译器 / make / Python 3 三项编译能力，以及宿主侧四项设备事实（插件链接、无障碍服务、副屏悬浮窗权限、系统 WebView）。编译能力与可选功能缺失只标 warn，不参与整次失败判定；发现执行位缺失或附件目录缺失时可以就地修复，不修改任何文件内容；同时报告设备可用空间，低于 512 MB 时明确提示先清理空间。
- 日志按需查看与判读。 只含内部状态码与计数的诊断日志可直接在应用内阅读（尾部窗口 64 / 256 KB）；运行日志窗口可选 8 / 64 / 256 KB，并支持关键字过滤与级别着色。命中已确诊的错误特征（缺凭据、模块身份分裂、插件加载失败、端口占用等）时，界面给出结论与下一步，而不是丢一段原文让人猜。
- 后台保持与悬浮球（可选）。 前台服务可提高运行时进程在后台的存活优先级——但不能阻止系统在内存、电量或厂商策略下结束进程；短按悬浮球可展开二级球快捷菜单（对话、目标副屏、回到应用、隐藏球、关闭无障碍），长按直接展开可拖动的 AI 对话小窗，球的位置持久化，并在屏幕旋转后回到可视范围。
- 两步首次配置。 首次启动走「配模型 → 装运行环境」，顺序刻意把模型凭据放前面：运行时装不上也不影响先存好凭据；窗口只做两件事：配 API Key、装运行环境。首次配置的密钥输入不遮罩（遮罩会让输入法补字、折行、粘贴丢字都看不出来），下方实时显示字符数，并提示已自动清理的空白与 Bearer 前缀；保存成功才清空，失败原样保留可重试。本机没有检测到模型凭据时不会直接打开 Harness，保存 API Key 就能解除门禁。详见首次配置。

工作原理

应用分为三层：

1. 管理界面（Capacitor + React）。 原生安卓外壳，负责运行时安装、服务控制、模型服务商设置、终端、运行时来源与环境重置。
2. 原生运行时层（Kotlin）。 负责根文件系统的校验与解压、以原生库形式随包提供的 PRoot 运行器与加载器管理、Harness 进程与 PTY 会话监管，以及在你授权后连接 Shizuku UserService。
3. Ubuntu 运行时（PRoot）。 通过固定的白名单入口在 Ubuntu 24.04 内启动 dsh web 并仅监听回环地址。Node.js 预加载模块会在任何请求到达 Harness 之前校验当次启动令牌，内置 WebView 也被限制在同一回环源内。

完整架构与安全边界见 docs/ARCHITECTURE.md。

安装

1. 从 Releases 页面下载最新版 APK，并阅读该版本的发布说明。
2. 安装 APK（按系统提示允许来自可信来源的安装）。
3. 打开应用，跟着两步引导走完：配模型 → 装运行环境。
- 配模型：粘贴一份 DeepSeek API Key 点保存。首次配置不遮罩密钥，方便确认粘贴完整；这一页只填 Key。
- 装运行环境：官方 APK 已内置镜像，点「安装运行时」等进度走完即可，无需联网；自行构建的 APK 通常没有内置镜像，改走「安装失败？去在线下载其它版本」→「版本管理 → 在线可用版本 → 下载到版本库」→「切换至此版本」。
- 两步走完窗口就结束；凭据与运行环境都齐了，回主界面点「打开对话」开始。
4. 之后想改配置，用设置 → 模型与密钥；运行环境与版本在设置 → Ubuntu 运行时 / 版本管理。

逐步的操作与排错见 首次配置。

环境要求

- Android 8.0 及以上、arm64-v8a（64 位 ARM）处理器的设备。
- 数 GB 左右的可用存储空间，用于存放解压后的 Ubuntu 环境。
- 至少一个受支持模型服务商的 API Key、一个 DeepSeek 账号授权，或一个兼容的自定义端点。
- 官方 APK 内置运行时镜像，可全程离线安装；自行构建的 APK 若未打包镜像，首次安装需要联网下载一份经摘要校验的运行时。

模型服务商

内置服务商：DeepSeek、OpenAI、Anthropic、Google Gemini、OpenRouter、Groq、xAI、Mistral。

也可以将任意 OpenAI 兼容端点配置为自定义服务商（基础地址、API Key 与模型列表）。管理端 API Key 通过 Android Keystore 保护，并写入 Harness 私有的 ~/.dsh/.credentials.yaml（0600）；仅本次启动所需的临时令牌才会写入同样受保护的启动文件。保存配置时若 Harness 正在运行会自动重启，确保运行时状态始终与界面显示一致。

「模型与密钥」页和各服务商卡片提供「获取模型」：从上游拉取模型列表后，最靠前的一项自动填入默认模型，也可以点选其它项或直接手输；上游没有返回可用模型或返回 401 时保留原默认模型，只显示失败原因。自定义服务商获取时，上游首个置顶为该服务商的第一个模型，其余按 id 合并追加，已手动改过的模型条目与上下文长度不被覆盖。

DeepSeek 账号登录

在「设置 → 模型与密钥」点击「登录 DeepSeek 账号」会先打开 Harness；进入后从侧栏「更多」菜单选择官方登录。授权完成后返回设置页，应用会刷新账号授权状态并保留尚未保存的 API Key 草稿。退出账号后再次返回该页也会刷新为未登录状态；账号授权和 API Key 是两条独立的可用路径。

登录回调只精确放行 Harness 的 GET /oauth/callback，其余 Harness 页面和 WebSocket 仍需要本次启动的应用认证。Android 只会把 https://platform.deepseek.com[:443]/dsh/authorize?... 的用户触发导航交给系统浏览器；其他来源、路径、片段、userinfo 或非 HTTPS 地址均不会打开。应用不会读取或转交账号令牌。

可选的 Shizuku 集成

Shizuku 完全可选，且不会随应用捆绑安装：

1. 自行安装并启动 Shizuku（通过无线调试或 Shizuku 官方指引的方式）。
2. 在应用内授予权限。Shizuku 已运行且授权仍有效时，启动或返回启动器会自动连接；连接失败可点击连接 Shizuku重试。
3. 在「设置 → Shizuku 与设备自动化」中连接成功后，打开「允许 AI 调用 Shell」。一次开启会持续生效，直到你关闭开关；不需要每条命令逐次确认。

开启后，模型可调用设备 Shell 读取、写入、创建目录、上传、下载文件，也可查询指定应用的进程、服务和 Activity 摘要。Shell 使用 Shizuku 的实际 Android 权限，不等同于 Root；命令正文和输出不会写入诊断日志。请不要让模型读取或回显密钥、短信、通讯录、令牌等隐私数据。

无障碍自动化需要你另外在系统设置中手动开启服务，再在应用内从已安装应用列表选择目标包名并保存白名单。白名单数量不设上限；普通厂商应用可加入，系统设置、权限、支付、验证码和密码页面仍由原生服务拒绝。服务不能绕过锁屏，也不能保证厂商后台策略下的持续运行。

当 Shizuku 不可用、未授权或连接断开时，设备工具会明确报错；Ubuntu 运行时与 Harness 不受影响。

更新 Shizuku 应用之后，手机上可能仍在运行更新前启动的服务端，此时连接用户服务会超时。遇到这种情况请在 Shizuku 里停止服务再重新启动（或重启手机），然后回到本页重试——应用内没有重启 Shizuku 服务端的通路。界面上的「Shizuku 应用 13.6.0」是已安装的 Shizuku 应用版本，「服务端 API 13」是服务端上报的 API 版本，两者不是一回事。

0.3.5 及更早版本与 Shizuku 13.6.0 同时使用时，用户服务会在启动阶段直接退出，界面表现为「Shizuku 连接未就绪」或连接超时，已在两台 Android 16 设备上确认。原因是随包的网络安全配置触发了 Android 的按域名规则冲突检查，而 Shizuku 13.6.0 起会在这条链路里创建目标应用的 Application，正好走到该检查。0.3.6 起已修复：升级应用即可，不需要降低 Shizuku 版本；暂时无法升级时，可临时改用 Shizuku 13.5.4。

目标应用副屏（实验功能）

在 设置 → AI Shell → 目标应用副屏（实验功能） 中选择目标应用，可尝试将其运行到独立虚拟显示，并通过原生预览页或可拖动小窗查看和操作。此处展示的是目标应用界面；AI 对话悬浮窗是另一项功能。

入口要求 Android 10 及以上、已授权并连接 Shizuku，且用户已开启 AI Shell。锁屏或熄屏时，该副屏通道暂停读取与输入。AI 工具已覆盖副屏状态与性能读数（目标帧率、画面年龄、输入后首帧间隔估计）、PNG 截图、副屏专用无障碍节点树、点击、滑动、返回、中文文本写入（经无障碍聚焦写入，失败时回退系统剪贴板粘贴）、15/30/60 fps 档位和结束会话；画面仍是逐帧取 PNG，不是视频编码通道。

截至 2026-10-02，已在 MuMu Android 15 中以普通 Shell 权限验证测试应用的横竖屏截图、定向点击和会话回收，并检查 363×800 dp 与 800×363 dp 的原生选择页布局；此后各版本另有 HONOR AAP-AN00 真机回执，逐条列在目标应用副屏说明里，本段不重复。尚未验证完整 Shizuku 授权与绑定链路、真实第三方应用、小窗互切、长期后台与锁屏恢复；上述新增能力多数也只有单元测试与编译检查，模拟器探针结果不能视为所有手机或所有应用的兼容保证。

已有运行环境还需要更新或重新打包 dsh-mobile-shizuku 插件，才能使用新增 AI 工具；仅安装新 APK 不会改写现有插件数据。机制、工具接口与完整验证范围见目标应用副屏说明。

从源码构建

构建依赖

- Node.js ^22.19.0 或 >=24.0.0，以及 pnpm 11
- Android SDK 35、NDK、CMake 3.22.1、JDK 21、Gradle 8.11.1
- 来自 Operit2 安卓运行时工具链的 ARM64 PRoot 运行器与加载器（libdsh_proot.so、libdsh_proot_loader.so），版本与发布版固定对应——准确的上游版本号与哈希见 THIRD_PARTY_NOTICES.md
- 自包含构建还需 runtime-manifest.json 与 rootfs.bundle，两者都从同一源码版本生成

Web 与安卓构建

pnpm install --frozen-lockfile
pnpm run build # TypeScript 检查 + Vite 生产构建
pnpm run android:sync # 构建并同步到安卓工程
pnpm run android:open # 在 Android Studio 中打开，或直接使用 Gradle 构建

开发版构建可以不内置运行时，改为同时设置 DSH_RUNTIME_MANIFEST_URL 与 DSH_RUNTIME_MANIFEST_SHA256 以固定远程清单。完整构建说明与签名策略见 android/README.md。

检查与测试

pnpm test # Vitest 单元测试
pnpm --dir scripts/runtime-profile install --frozen-lockfile --ignore-scripts # 插件测试依赖
pnpm run test:scripts
pnpm lint # ESLint，零警告通过

安全与隐私

- 模型数据去向。 本机控制台不等于离线模型。对话、AI 工具返回的文件内容及截图可能进入当前会话并发送至配置的模型服务；本地副屏预览本身不上传图像。只授权与当前任务相关的应用和数据。
- 仅监听回环地址。 Harness 不会绑定任何非回环网络接口；内置 WebView 阻止访问回环源之外的导航与 HTTP 资源。
- 临时传输凭据。 每次启动 Harness 都会通过 SecureRandom 生成全新的 256 位令牌。令牌不会持久化、不会写入日志或 URL，也不会返回给 JavaScript。
- 凭据存储。 管理端 API Key 由 Android Keystore 保护，并由 Harness 从私有 ~/.dsh/.credentials.yaml（0600）读取；账号授权记录也由 Harness 以同样的私有文件权限管理。每次启动生成的临时传输令牌只在受保护的启动文件与进程内存在。
- 可验证的运行时供应链。 清单与根文件系统镜像均经过 schema 校验与摘要固定，解压时执行严格的归档边界检查；断点续传遇到非法范围或异常响应时按失败即关闭（fail-closed）处理。
- 审计记录。 原生审计日志存放在应用私有的禁备份目录中，文件仅所有者可读写，按 UTC 日期轮转并保留 90 天。记录只包含固定的事件/结果枚举，绝不包含 URL、命令、令牌或终端数据。
- 无应用账号与追踪。 应用不设自己的账号系统、不含广告、不采集遥测数据；DeepSeek 官方账号登录仅由 Harness 官方模块处理。

参与贡献

欢迎在 <https://github.com/dphmoblie/deepseek-harness-android> 提交 Issue 与 Pull Request。

提交前请保持改动聚焦、为新行为补充测试，并运行 pnpm lint 与 pnpm test。
涉及安全的改动必须维护 docs/ARCHITECTURE.md 所述边界，尤其不得削弱回环访问控制、摘要校验、入口白名单或 Shizuku UserService 契约。

贡献者

贡献者

欢迎更多开发者参与，你的名字也可以出现在这里。

交流社区

- QQ 交流群：1108895375——欢迎入群提问、反馈建议、获取版本发布通知。

项目数据

星标与下载量累计折线图

黄线是 GitHub 星标累计数（按加星时间计入）；蓝线是各 Release 资产的总下载次数—— GitHub 只提供当前累计值，所以按发布日计入、逐日累加成阶梯线。图由 pnpm run chart:stats 重新生成，抓取日期会写进图内；仓库里的 stats-chart 工作流每天自动跑一次，数据变了就自己提交新图。

许可证

本仓库中的应用代码基于 MIT 许可证发布。

正式版 APK 还以各自许可证再分发了第三方运行时组件，包括 PRoot （GPL-2.0-or-later）、Operit2 运行时工具链（AGPL-3.0）、Ubuntu 24.04 软件包、Node.js，以及采用 MIT 许可证的 DeepSeek Harness 运行时与前端。
组件来源、确切上游版本、制品哈希及相应许可证文本记录于 THIRD_PARTY_NOTICES.md，并随 APK 内 assets/legal/ 目录一并提供。

相关文档

- 首次配置（两步走完并开始对话）
- 目标应用副屏与验证范围
- 应用读取与无障碍自动化
- 插件导入、数据保留与回滚
- 投递区与存储权限
- 架构与安全边界
- 移动端插件兼容设计
- 项目状态登记册（已完成、未完成与真机读数）
- 发布检查清单
- 安卓平台构建说明
- 第三方声明