在 Android 手机上跑 OpenMinis(Minis)里的 DeepSeek Harness,并把手机文件目录挂成它的工作区 —— 不用 root、不用 Termux X11、不编译 Chromium;PRoot + Alpine(musl / aarch64)四个坑已经填平。
大部分人听到"手机上跑 dsh",会以为是在浏览器里打开一个网页版——能聊,但碰不到任何文件。差别就在这里:
| 跑在哪 | 它能动的文件 | 要上传 / 同步吗 | 设备能力 |
|---|---|---|---|
| 浏览器里打开一个托管好的 dsh | 没有文件系统 | — | 无 |
| 电脑上跑 dsh | 电脑的文件 | 生成的东西要传回手机 | 无 |
| 云服务器 / 云 IDE 跑 dsh | 云上的文件 | 要传,文件离开设备 | 无 |
| 这个:Minis 里跑 dsh | 你手机的 Documents / Download | 不需要,全程不出设备 | 相册 / 日历 / 通知 / 剪贴板 |
界面看起来完全一样(都是 http://127.0.0.1:3080)。差别不在界面,在它坐在哪个文件系统上。
一句话:别人的 Agent,跑在你手机的文件上。
拿 DeepSeek-R1 论文的读书笔记做了个最小验证:让 dsh 改写 dsh-workspace/读书笔记.md,然后去手机文件管理器里看同一个路径。
左边的路径和右边的文件是同一份东西。我在这台机器的 shell 里也核对过一次:
$ ls -l /var/minis/mounts/Documents/dsh-workspace/
-rw-rw---- 1 ... 1797 Oct 22 23:30 读书笔记.md
$ head -3 读书笔记.md
# 读书笔记
## 第一章2 KB、时间 23:30、内容是 dsh 改写的版本 —— 不是转账式复制,是同一个 inode:dsh 写进去的那一刻,手机文件管理器里就变了。
git clone https://github.com/maple564/dsh-on-android.git && cd dsh-on-android
sh install.sh # 依赖 → dsh → 重编译 node-pty → 固化到 /opt/dsh-harness
export DEEPSEEK_API_KEY=sk-xxxxxxxx # 或写进 ~/.dsh/.env(只放这一行)
dsh-go # 打开 http://127.0.0.1:3080首次进 web UI:点「继续」→ 选一个可写目录做工作区 → 顶部显示 DeepSeek-V4-Flash 即接通。
Android 16 手机,Chrome 打开 http://127.0.0.1:3080,实拍没有任何后期:
左边是进入后的工作区界面(底部 DeepSeek-V4-Flash 说明模型已接通),右边是一次真实会话:对话 / 轨迹 双视图、产物 +1个文件、任务 4 已完成、1 轮 · 31 步。
这张是 dsh-go --status 的输出,也是这个仓库存在的理由 —— 进程行里那句 node --expose-internals /opt/dsh-harness/.../bin.js web,就是四堵墙里第二堵的解法。
首次跑通的环境是 OpenMinis(即 Minis,开源,GPLv3):它是一个把完整 Alpine Linux 沙箱塞进手机里的 Android / iOS AI Agent 应用,沙箱本身就是 PRoot + musl + aarch64 —— 也就是这个仓库要对付的那类环境。
所以:
- 在 OpenMinis 里:装好 App,打开任意会话,让 Agent 执行
sh install.sh即可;沙箱、android-*CLI、文件挂载都是现成的,本文档里的路径(/var/minis/mounts/...、/sdcard/Documents)就是它的挂载点。 - 不在 OpenMinis 里:Termux +
proot-distro install alpine、UserLAnd 等任何 PRoot 容器都适用,install.sh只依赖apk/npm/node-gyp。
为什么特意写这一节:光说「Android + PRoot」太抽象,两个报错(node-pty 的 glibc ABI、sandbox backend 缺失)都跟宿主进程怎么起容器有关,知道宿主是什么,排查时能少走一半弯路。
这不是"把 dsh 装进手机",是两层各干一件事:
| Minis(本地层) | dsh(执行层) | |
|---|---|---|
| 负责 | 挂载手机存储、PRoot/Alpine 沙箱、设备能力(相册/日历/通知/剪贴板)、API key 与权限、App 生命周期 | agent 循环、plan/todo 拆解、工具调用、长任务上下文、对话/轨迹双视图、模型与推理强度 |
| 不负责 | 怎么拆任务、跑多少步 | 文件最后躺在哪、设备权限从哪来 |
| 产出 | 文件是真的,设备是真的 | 任务是真的被干完了(1 轮 · 31 步 这种可数证据) |
两层之间只有一个契约:挂载目录。这个设计的四个好处:
- 各干擅长的:不用逼 Minis 去跑几十步的 agent 循环,也不用逼 dsh 去解决"怎么读手机相册"——后者它一辈子也解决不了。
- 文件就是接口:Minis 保证路径真实、设备可见;dsh 保证写进去的东西是对的。中间没有同步层、没有网盘、没有"再传一次"。
- 可观测:Minis 侧看 shell 进程和文件到底在哪,dsh 侧看对话、轨迹和步数。出问题能立刻定位在哪一层。
- 可替换:执行层换成别的本地服务(Gradio、Jupyter、你自己的 RAG)一样跑得通,因为契约只是「一个目录 + 一个端口」。
一句话:Minis 提供现实世界,dsh 提供执行力。
电脑上跑 dsh 谁都会。手机上跑 dsh 的价值不在 dsh,在于它坐在你的相册、下载、微信文件旁边。
OpenMinis 会把手机存储挂到沙箱里的固定路径:
| 手机侧 | 沙箱内路径 | 你平时用来干什么 |
|---|---|---|
/sdcard/Documents |
/var/minis/mounts/Documents/ |
文档、课件、下载的 PDF |
/sdcard/Download |
/var/minis/mounts/Download/ |
浏览器下载、微信保存的文件 |
| 跨会话共享目录 | /var/minis/shared/ |
多个会话共用的产物 |
于是 dsh 只要把工作区指向这些挂载目录,就变成「能读写手机的 Agent」:
- 产出直接落地手机:harness 生成的 PPTX / PDF / ICS / 脚本写进
Documents/dsh-workspace/,退出 App 后用文件管理器、微信、WPS 直接打开,不需要"再传一次到手机"。 - 反向读手机文件:把
2026暑期实践报告.docx、课表截图、发票 PDF 丢进 Documents,让 dsh 在会话里直接读、改、重新导出。 - 离线 + 私有:模型走你的 API,文件全程不出设备。
- 随时能用:地铁上、床上、旅行中,不用开机电脑。
dsh 默认工作区是 /root,在 PRoot 里写文件容易 Operation not permitted,而且手机根本看不到。改成挂载目录即可。
# 1. 建一个手机可见的工作区
mkdir -p /var/minis/mounts/Documents/dsh-workspace
# 2. 注册到 dsh(保留已有工作区,不覆盖)
cp ~/.dsh/storages/workspace.json ~/.dsh/storages/workspace.json.bak
python3 - <<'PY'
import json, uuid, datetime
p = json.load(open('/root/.dsh/storages/workspace.json'))
new = "/var/minis/mounts/Documents/dsh-workspace"
for ws in p["tables"]["workspaces"].values():
if ws.get("path") == new:
raise SystemExit("已注册,跳过")
now = datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", ".000Z")
wid = "ws-" + uuid.uuid4().hex[:12]
p["tables"]["workspaces"][wid] = {"path": new, "title": "dsh-workspace",
"sessionIds": [], "createdAt": now, "updatedAt": now}
p["global"]["workspaceIds"].append(wid)
json.dump(p, open('/root/.dsh/storages/workspace.json', 'w'), indent=2, ensure_ascii=False)
print("注册成功", wid)
PY
# 3. 重启 harness,UI 侧边栏里选 dsh-workspace 新建会话
pkill -f 'dsh/lib/bin.js'; sleep 2; dsh-go验证:在新会话里让 agent 写一个 hello.txt,然后用手机文件管理器打开 Documents/dsh-workspace/ —— 文件就在那儿。
这和「在电脑上跑一个本地 Agent」是两件事:电脑上的 Agent 要动手机文件得靠微信传、网盘同步、数据线;挂在 OpenMinis 挂载点上的 dsh,读写手机文件就是一次普通的
open()。
npx @deepseek-ai/dsh 在 glibc 桌面上是一行命令的事,但在 musl 环境里会连续撞四堵墙 —— 而且每一堵墙的报错都指向错误方向,能让人白折腾两天。
| # | 你会看到的报错 | 你以为的原因 | 真实原因 | 解法 |
|---|---|---|---|---|
| 1 | Error loading shared library ld-linux-aarch64.so.1 |
缺系统库 | node-pty 拿的是 glibc 预编译包,musl 加载不了 | node-gyp rebuild |
| 2 | --expose-internals is required for HMR |
参数没生效 | 该参数不允许出现在 NODE_OPTIONS 里 |
只能命令行传给 node |
| 3 | .env sets DSH_PERMISSION_MODE ... only the launching environment may set |
.env 格式写错 | 它是 bootstrap 变量,只认启动进程的环境 | 写进 wrapper 的 export |
| 4 | no sandbox backend is usable |
权限不够 | 容器内 workspace-write 无可用后端 | DSH_PERMISSION_MODE=danger-full-access |
这个仓库把四条解法固化成了 install.sh + 两个 wrapper,装完即用。
| 项 | 要求 |
|---|---|
| 宿主 | Android 10+(已在 Android 16 / aarch64 实测) |
| 容器 | 任意 PRoot Linux:OpenMinis / Minis 沙箱、proot-distro install alpine、UserLAnd 等 |
| 发行版 | Alpine 3.20+(musl)或任意 glibc 发行版(脚本会自动跳过重编译) |
| Node | ≥ 20(实测 22.23.2) |
| 磁盘 | 约 800 MB(依赖树较大) |
| Root | 不需要 |
1. node-pty 必须针对 musl 重编译
apk add --no-cache build-base linux-headers python3
cd <node_modules>/node-pty && npx --yes node-gyp rebuild # 看到 "gyp info ok" 即成功
# 自检
node -e "const pty=require('./lib/index.js');const p=pty.spawn('/bin/echo',['ok'],{});p.onExit(e=>{console.log('node-pty OK',e.exitCode);process.exit(0)})"prebuilds/linux-arm64/pty.node 是 glibc ABI 的,musl 下 ld-linux-aarch64.so.1 根本不存在,所以必然失败。
2. --expose-internals 只能走命令行
exec node --expose-internals /opt/dsh-harness/node_modules/@deepseek-ai/dsh/lib/bin.js "$@"- 放进
NODE_OPTIONS→ Node 直接拒绝(安全限制,不是 dsh 的问题) - 写进
.env→ 无效,.env只影响 dsh 自己的配置
3. DSH_PERMISSION_MODE 是 bootstrap 变量
export DSH_PERMISSION_MODE=danger-full-access # 必须在启动进程的环境里写进 ~/.dsh/.env 会让 dsh 拒绝启动(它故意这么设计,防止用配置文件悄悄提权)。
副作用要说清楚:full-access 模式下不再逐条审批 Bash 命令。手机本地自用可以接受,绝对不要把 3080 暴露到公网。
4. 固化安装:PRoot 下 cp -a 会失败,要用 tar 流
cd /root/.npm/_npx/<hash>/node_modules
tar cf - --exclude='node-pty/build' . | (cd /opt/dsh-harness && tar xf -)npx 缓存在 PRoot 里存在硬链接/权限视图不一致,cp -a 会报错;tar 流式复制是唯一稳的方式。
复制完要把铺平的目录再包一层 node_modules/,否则 require 解析不到 —— install.sh 里已经处理。
| 命令 | 作用 |
|---|---|
dsh --version |
检查安装是否成功 |
dsh-go |
启动 web UI 并打开浏览器 |
dsh-go --status |
只看是否在跑(不启动) |
dsh-go --browser |
用系统浏览器打开 |
pkill -f 'dsh/lib/bin.js' |
停止 |
~/.dsh-web.log |
日志 |
Q:装完 dsh --version 报 Cannot find module?
/opt/dsh-harness 目录层级不对。确认结构是 /opt/dsh-harness/node_modules/@deepseek-ai/dsh/lib/bin.js;install.sh 第 4 步如果中途失败会留下平铺结构。
Q:web UI 打开是白屏?
两种可能:① 用的浏览器内核不支持 Canvas/WebGL(部分 App 内置 WebView 会白屏,但 DOM 和交互其实正常,换 Chrome 即可);② 服务没起来 —— 先 curl -o /dev/null -w '%{http_code}' http://127.0.0.1:3080/,返回 000 就是没启动。
Q:在 /root 里写文件 Operation not permitted?
PRoot 视图问题,不是权限。把工作区换成挂载的共享目录(如 /sdcard/Documents/dsh-workspace)即可。
Q:App 退到后台就被杀了?
nohup 只防 SIGHUP,宿主进程死了沙箱一定跟着死。真保活要 Termux 前台服务 + 电池白名单(不同厂商设置路径不同)。
Q:能不能跑在 Termux 原生环境(不装 PRoot)?
能,而且更稳(bionic 有完整 syscall)。但 node-pty 仍需按 Termux 环境编译,install.sh 的编译段可以复用。
- 进程生命周期绑宿主:Android 杀 App/容器,dsh 一起消失,任务可能中断。建议把长任务拆成小步。
- 长时间会话会被回收:内存紧张时浏览器标签页销毁,前端与后端的连接断,需要刷新重连。
- 性能:PRoot 有 syscall 翻译开销,初次
npm install明显慢于桌面;跑起来后 web UI 交互基本无感。 - 不要在公网暴露 3080:默认 full-access,等于把 shell 交出去。
踩到新的坑 / 换机型跑通 / 适配别的 PRoot 发行版,都欢迎提 PR。
提 issue 请带上:uname -a、node -v、dsh --version、完整报错原文。
想聊"手机上到底值得这样跑什么"(Jupyter?本地 RAG?别的 harness?)→ 去 Discussions。
改完 install.sh 想验证固化逻辑,不用重新 npm install 一遍:
DSH_SRC=/path/to/any/node_modules DSH_SKIP_BUILD=1 DSH_BIN_DIR=/tmp/bin \
sh install.sh /tmp/opt-test # 只跑 tar 固化 + wrapper 生成
/tmp/bin/dsh --version # 应该打出被固化那一份的版本号dsh-on-android documents and scripts a working DeepSeek Harness setup on Android via PRoot + Alpine (musl / aarch64) — no root, no Chromium build. First brought up inside OpenMinis (the open-source mobile AI-agent app that ships an on-device Alpine sandbox); any PRoot container works too. It encodes fixes for four misleading failures: glibc-prebuilt node-pty, --expose-internals being rejected inside NODE_OPTIONS, DSH_PERMISSION_MODE being a bootstrap-only variable, and the missing sandbox backend in containers. Run sh install.sh && dsh-go.




