DeepSeek Harness安卓版架构全解:原生壳+DSH内核+5大插件如何协同工作
DeepSeek Harness安卓版架构全解:原生壳+DSH内核+5大插件如何协同工作
DeepSeek Harness 安卓版是一款可直接安装的 Android APK:内置完整 DSH 内核与 node 运行时,装上就能用,还能让 AI 免 Root 真正操作手机——读屏、点击、装应用、开网页;文件编辑只需「所有文件访问」权限,并支持前台保活与 AI 通知。这篇文章带你完整看懂它的架构:原生壳负责"接管手机",DSH 内核负责"大脑",5 大插件负责"手脚"。
一、整体架构:三层结构,各司其职 🏗️
整个 APK 可以拆成三层,自上而下职责清晰:
| 层 | 组成 | 职责 |
|---|---|---|
| 原生壳层 | MainActivity.java + 多个前台服务 | 权限引导、控制台、引擎启停、悬浮球、虚拟屏桥 |
| DSH 内核层 | node v26 运行时 + @deepseek-ai/dsh(0.2.1-rc.2) |
模型调度、会话管理、工具调用、插件加载 |
| 前端层 | DSH 原生界面 + mobile-patch/ 移动端适配 | 用户在手机上看到的聊天 / 轨迹 / 设置界面 |
原生壳启动内核后,前端通过 WebView 访问本机服务,各端口分工如下:
| 端口 | 用途 |
|---|---|
| 3080 | DSH 引擎(node web) |
| 3081 | AI 通知通道 |
| 8999 | 虚拟屏桥(插件 / 预览窗访问) |
| 8998 | 虚拟屏特权核心(Shizuku shell 身份) |
关键设计:所有本地服务一律绑定
127.0.0.1并要求随机令牌鉴权,拿不到令牌直接拒绝,安全边界收敛在一台手机内。
二、原生壳层:MainActivity 与四大常驻服务 🐋
原生壳是整个 App 的"管家",核心代码都在 android-app/src/com/deepseek/harness/ 下:
- MainActivity:首次启动的权限引导页(9 项权限一站式配置)→ 原生控制台(解压 / 权限 / 插件开关 / 日志四页)→ WebView 加载 DSH 界面,并负责状态栏沉浸与深浅色主题切换
- OverlayService.java:桌面上的"小鲸鱼"悬浮球,单击 / 长按 / 双击动作可配置(展开面板 / 打开应用 / 建虚拟屏)
- VsreenBridgeService.java:虚拟屏桥,把 8999 端口请求转发到 8998 特权核心,并渲染右上角实时预览悬浮窗
- AccessibilityService.java:系统无障碍服务,AI 读屏与模拟操作的"眼睛和手"
三、DSH 内核:完整移植 + 移动端适配 🧠
内核并非阉割版,而是完整携带 插件生态 + RPC API 的 @deepseek-ai/dsh。为了在 Android 上跑起来,项目做了三类"移植手术":
- 源码补丁:dsh-patches/ 归档了适配补丁——
node-pty换成child_process、图片库sharp换成纯 JS 实现、原子写从link改rename等;升级内核后执行 apply.sh 即可重放 - 组合配置:config/cordis.patch.yml 负责"禁用 + 插入"——禁用 Android 上无用的模块(PowerShell 沙箱、遥测),同时把 5 大手机端插件逐一注入内核
- 前端注入:mobile-patch/inject.sh 在不覆盖原生代码的前提下注入触摸优化 CSS 与软键盘适配脚本 mobile.js(回车换行、Ctrl+回车发送、禁双指缩放)
原则:非必要不动内核——壳层与配置能解决的,就不改内核源码,避免每次升级内核都要重放补丁。
四、5大插件协同:AI 如何真正"上手"操作手机 🛠️
这是本项目与纯聊天 App 的核心区别。5 个插件按"权限通道"互补,源码归档在 plugins/ 目录:
| 插件 | 权限通道 | 核心能力 |
|---|---|---|
| dsh-tool-shizuku | Shizuku / root | 特权 shell:pm / am / settings / dumpsys 任意系统命令,异步执行 + 环境消毒 |
| dsh-tool-android | Shizuku / root | 结构化系统操作:包管理 / 应用管理 / 设置读写 / 截图 / 模拟输入 |
| dsh-tool-accessibility | 无障碍服务(免 Root) | 读控件树、点击、输入、滚动、截图理解 |
| dsh-tool-vscreen | Shizuku / root | 虚拟屏:建屏 / 启动 App / 看画面 / 点击滑动 / 关屏(8 个工具) |
| dsh-tool-browser | 无需特权 | AI 浏览器:DOM 语义快照 + 稳定 ref + 多页签(10 个工具) |
互补策略很清晰:无障碍通道不需要任何授权、擅长读屏点击;Shizuku/root 通道负责系统级操作(装应用 / 改设置);虚拟屏让 AI 在独立于主屏的屏里干活;浏览器通道让它真的能打开网页、点进去、读完正文。不装 Shizuku、不 Root 也完全能用——未授权时 AI 不会反复尝试系统操作,而会在需要时引导你授权。
每个插件都能在控制台的「插件」页随时开关,这也是 DSH 原生插件生态带来的好处:
五、完整链路:一条指令的"旅行" 🔄
以"帮我把某应用启动到虚拟屏"为例,整条链路是这样的:
- 你在 WebView 界面发出消息,请求发到
http://127.0.0.1:3080(带令牌鉴权) - DSH 内核解析意图,决定调用
dsh-tool-vscreen的launch工具 - 插件经 App 进程内的 Shizuku API 执行系统命令(
am start --display ...),不再走引擎内子进程,规避连接超时问题 - 执行结果带回内核,模型核对后回复你;任务耗时较长时,前台保活机制保证挂后台 / 锁屏不被杀,完成即推通知
六、新手上手路径:3 步跑通第一条指令 🚀
- 安装 APK:下载
DeepSeekHarness.apk(Lite 共存版与兼容版可并行安装,互不干扰),按首次启动的权限引导页完成 9 项权限 - 启动引擎:原生控制台点「启动引擎」后进入主界面,在设置页填写 API Key——只存本机,绝不打包进 APK
- 从免授权指令开始:先让 AI 用无障碍读屏(
android_screen)体验最顺滑;需要装应用、改系统设置时再按需授权 Shizuku
遇到问题时:
- 打不开 / 白屏 / 连接失败 → 先查 docs/启动排查.md
- 控制台「日志」页可一键分享
dsh-web.log,无需 root 也能取 - 架构细节与构建环境见 docs/开发指南.md,版本演进见 CHANGES.md
一句话总结:DeepSeek Harness 安卓版 = 一层轻薄的 Android 原生壳 + 完整可插拔的 DSH 内核 + 5 个按权限通道分工的手机插件。理解了这个"壳—脑—手"结构,你就能明白它为什么既能免 Root 起步、又能随授权逐步解锁完整的手机操作能力。





