安卓终端引擎 hazukieq/DSH-Mobile-with-Termux

DSH Mobile with Termux

DeepSeek Harness 的 Android 完整移植（分叉版）：官方 dsh 引擎原样跑在手机沙箱里，自带 Termux 用户态，无需 Root、无需电脑。

🌐 英文简介见文末 · English summary

⚠️ 这是分叉（Fork）

本项目是 Soodok/Deepseek-Harness-Local-Android 的分叉，遵循 MIT 许可（见 LICENSE）。

| 角色 | 仓库 |
| 本仓库（分叉） | hazukieq/DSH-Mobile-with-Termux |
| 上游 App 项目 | Soodok/Deepseek-Harness-Local-Android |
| 引擎上游 | deepseek-ai/deepseek-harness |

分叉保留上游完整 git 历史；原始版权归 Soodok，分叉修改版权归本仓库作者。

🍴 本分叉改了什么

| 方向 | 改动（可在 git log 中按前缀检索） |
| 浮窗进度 | 改为引擎事件驱动：host 侧插件订阅 agent/assistant-stream / session/event，推送 [思考]/[工具]/[结果]/[回复] 链路；不再抓 WebUI DOM |
| 浮窗交互 | 折叠球 → 展开圆角卡片；正文实时增长、自动滚底、内部滚动；贴左右边（拖动后吸附最近边、垂直位置保留）；无障碍/自动化状态走独立 notice 条 |
| 收尾可靠 | 监听 agent/status 的 idle 强制收尾「已完成」；运行中 2.5s 心跳；done/error 永不去重 |
| 文本完整 | 端到端上限 16000 字；思考 1400、工具行 420、回复保留末尾 4000；展开后正文可自由滚动 |
| 引擎重启 | 市场「立即重启」与 EngineService 抢 3080：supervisor 解析 /proc/net/tcp{,6} 清掉外来监听，spawn 前等端口释放；plugin-health.mjs 做 disposal 安全 |
| agent 文档 | AGENTS.md/DSH-MOBILE.md 写明分叉仓库、受控重启（dsh-update restart、POST /engine/restart）与禁用做法 |

相关提交：fix(overlay)、fix(engine)、docs(agents)、chore(release)。

✨ 针对性功能清单

1. 引擎与 Termux 运行时

- 官方 dsh 引擎（本分叉适配 0.2.1-rc.2）+ bionic 版 Node.js 全量打包进 APK；引擎只监听 127.0.0.1。
- 与 Termux 同包名 com.termux，<files>/usr 即 $PREFIX：pkg / apt / dpkg / 真 bash 原生可用。
- 内置终端：原生 VT100/xterm + 真实 PTY，多会话、回滚、CJK 宽字符、真彩、可调字号（docs/TERMINAL_AND_LINUX.md）。
- 可选 proot Linux（Alpine / Ubuntu Base，按需下载）：linux run/list/status/exec/shell，用于 glibc / apt 场景。

2. UI 适配（客户端插件，不改引擎源码）

- narrow-sidebar 侧栏全宽、narrow-settings 设置竖排、narrow-rightbar 右侧面板全屏、narrow-welcome 首启欢迎页断点。
- mobile-ui：平板（≥600 CSS px）只在竖屏启用移动布局，横屏回落到原生桌面 UI。
- 全部通过 dsh.client 机制部署，卸载即恢复（docs/NARROW_UI.md）。

3. 后台进度与悬浮窗（本分叉重点）

- 两种模式：通知（13+ 需通知权限）与 悬浮窗（SYSTEM_ALERT_WINDOW，默认）。
- 数据来自引擎官方插件事件，不是定时抓 DOM；链路带步骤标签与耗时心跳。
- 悬浮窗：展开卡片、贴边、独立 notice、长文本滚动；前台/后台都常驻（docs/PROGRESS_OVERLAY.md）。

4. Agent 的手机能力（原生层 + 能力桥）

- 21 种动作原语：tap / tap-id / tap_text / swipe / scroll / scroll_find / scroll_collect / repeat / repeat_until / double_tap / long_press / pinch / drag / back_to / input / key / launch / intent / set_switch / noop / collect。
- 多层视觉兜底：无障碍节点树 → OCR → 图标识别 → 帧差；逐步 PICK → ACT → VERIFY → RETRY（docs/ACCESSIBILITY.md）。
- 系统集成：打开/分享到指定 App、接收外部分享进当前会话、SAF DocumentsProvider（文件管理器可见 DSH Mobile）、原生 MediaPlayer 播放音频、trash 删除、通知与 TTS（say）。
- 能力桥只监听 127.0.0.1:3083，token 每次启动随机生成（docs/android-agent-routes.md）。

5. 语音（当前分叉状态）

- 语音面板与识别链路（系统 SpeechRecognizer / 云端 OpenAI 兼容 ASR）代码保留。
- 本分叉已从悬浮窗移除麦克风入口（v1.6.x），因此当前没有悬浮窗语音按钮；细节与后续计划见 docs/VOICE_INPUT.md。

6. 网络、调试与可观测性

- 局域网 WebUI：显式开关 + 随机 6 位验证码，电脑浏览器打开的是手机里的原生 UI（docs/LAN_WEBUI.md）。
- WebView CDP 默认开启，智能体可用 Playwright 连真实页面排查；pnpm/node 真机用法写进智能体文档。
- 通知体系：任务状态、长任务步数、局域网开启、完成/失败（docs/NOTIFICATIONS.md）。

7. 权限、保活与数据

- 三级权限：普通 / Shizuku / Root；普通模式有 su 闸门，防止沙箱内 Agent 提权。
- 保活：前台服务 + 电池优化白名单引导 + 后台任务 PARTIAL_WAKE_LOCK + 厂商限制说明；正常退出后绝不自动重启引擎。
- 数据：会话/工作区在 Android/data/.../dshdata（可见可备份），profiles/（含凭证）留在私有目录；卸载会清理外置数据。

8. 引擎重启与稳定性（分叉）

- 受控路径：dsh-update restart、POST /engine/restart；受管引擎由 supervisor 统一拉起。
- 市场「立即重启」的 detach spawn 会与受管引擎抢端口：已由 supervisor 清理外来监听 + 等端口释放修复；细节见 docs/ENGINE_RESTART.md。

文档索引

| 文档 | 内容 |
| docs/PROGRESS_OVERLAY.md | 通知/悬浮窗进度、事件来源、notice 布局、贴边与文本上限 |
| docs/ENGINE_RESTART.md | 重启路径、dshmarket 竞态修复、plugin-health 安全性 |
| docs/ACCESSIBILITY.md | 无障碍动作原语、视觉兜底、验证闭环 |
| docs/NARROW_UI.md | 竖屏/平板 UI 客户端插件 |
| docs/TERMINAL_AND_LINUX.md | 内置终端与可选 proot Linux |
| docs/LAN_WEBUI.md | 局域网访问原生 WebUI |
| docs/NOTIFICATIONS.md | 通知体系与后台行为 |
| docs/VOICE_INPUT.md | 语音输入链路（含分叉的入口变更说明） |
| docs/android-agent-routes.md | 能力桥路由（智能体视角） |

📦 安装

1. 从本仓库的 Releases 下载 arm64-v8a APK（或自行构建）。
2. 首次启动会解压内置运行时（引擎在 APK 内，无需另外下载）。
3. 在 WebUI 配置模型服务地址与 API Key；默认只监听回环地址。

🔧 构建

前置：JDK 17、Android SDK（ANDROID_HOME）、Gradle 8.9。

export ANDROID_HOME=$HOME/Android/Sdk
gradle -p . assembleRelease -Pabi=arm64-v8a
产物：app/build/outputs/apk/release/app-release.apk

🔄 同步上游

git remote add upstream https://github.com/Soodok/Deepseek-Harness-Local-Android.git
git fetch upstream
git merge upstream/<branch>

🔐 数据与隐私

- 引擎只监听 127.0.0.1；是否离开设备取决于你配置的模型服务地址。
- 能力桥 token 每次启动随机，只注入引擎环境。
- 卸载会清理 Android/data/ 下的外置数据，长期备份请自行导出。

📄 许可证与致谢

- MIT License — 原始版权 Copyright (c) 2026 Soodok，分叉修改版权归本仓库作者；分发请保留原版权声明。
- 感谢 Soodok 与所有上游贡献者的完整 Android 移植。
- 引擎与插件生态归 DeepSeek Harness 作者所有，遵循其仓库许可证。

English summary

DSH Mobile with Termux 是 Soodok/Deepseek-Harness-Local-Android（MIT）的 fork，在 Android 上运行官方 DeepSeek Harness 引擎，并内置一套 Termux userland。

这个 fork 新增了：由引擎事件驱动的悬浮窗进度（实时带标签链条、贴边停靠、独立无障碍提示、可靠完成、16000 字符文本预算）、针对 dshmarket 分离式 dsh web（端口 3080）的重启竞态修复、可安全销毁的 plugin-health 探针，以及写明 fork 仓库与受控重启路径的智能体文档。

继承自上游的功能包括：应用沙箱内的完整 dsh 引擎、Termux pkg/apt、内置原生终端、可选 proot Linux、客户端窄屏/移动端 UI 插件、社区插件、局域网 WebUI、带多层视觉回退的无障碍自动化、原生 intent/share/SAF/MediaPlayer 集成、三级权限与保活。

许可证：MIT（原始版权归 Soodok；fork 修改由本仓库作者完成）。