安卓一键安装 cokelaoshi1/android-termux-dsh

android-termux-dsh

One-click installer for DeepSeek Harness (@deepseek-ai/dsh) on Android / Termux
在 Android / Termux 上一键安装 DeepSeek Harness（@deepseek-ai/dsh）的脚本

简介

在 Android Termux 上从零一键安装 DeepSeek Harness（@deepseek-ai/dsh）。适用于全新安装的 Termux：跑完 install.sh 一条命令，pkg 更新、工具链、Node、原生模块编译、运行时修补、存储权限全部自动完成，无需任何手动步骤。解决官方 npm i -g 在 Android/arm64 上无法完成的一连串原生编译与运行时问题。无需 root（有 root 也不影响），已在 Android 16 / aarch64 / Termux 实测通过。

功能特性

- ✅ 一站式：全新 Termux 一条命令装到底，装完即用
- ✅ 幂等：任何一步失败，直接重跑即可续上；不重复下载已装好的部分
- ✅ 网络自适应：npm 官方源 8 秒连不通自动切 npmmirror；失败自动换源重试；下载超时/重试已调优
- ✅ 防 OOM：koffi 编译限制并行度，低内存机型不易被系统杀掉
- ✅ 默认工作区 = sdcard：网页版直接读写手机存储，无需手动配置
- ✅ 自动验证：装完逐项检查 dsh / koffi / node-pty / sharp / sdcard，失败即红字报错，不再静默
- ✅ 中国大陆友好：--cn 参数一键切换国内 npm 镜像

为什么需要它

@deepseek-ai/dsh 依赖多个没有 android-arm64 预编译产物的原生模块，逐个排查非常痛苦：

| # | 模块 | 报错 | 脚本的处理 |
| 1 | koffi | CMake does not seem to be available | 安装 cmake clang make python binutils pkg-config libandroid-spawn |
| 2 | koffi | statx 编译错误（bionic 头文件问题） | 编译目标提升到 API 30：-target aarch64-linux-android30 |
| 3 | node-pty | gyp: Undefined variable android_ndk_path | 修补 node-gyp 缓存中的 common.gypi |
| 4 | 全部原生模块 | npm install-scripts 警告（构建脚本被静默跳过） | npm config set allow-scripts=... 放行 |
| 5 | sharp | Could not load the "sharp" module using the android-arm64 runtime | 安装 @img/sharp-wasm32 WebAssembly 兜底 |
| 6 | cordis-plugin-hmr | --expose-internals is required | 用启动包装器替换 npm 生成的 dsh 软链 |

环境要求

- Android 11+（API 30+，statx 运行时可用）
- Termux（必须 F-Droid 版，Play 商店版已废弃）
- 建议 4GB+ 内存、2GB+ 空闲存储、稳定网络
- 架构：arm64（主流）/ armv7 / x86_64 / i686（脚本自动适配）

快速开始

在 Termux 里执行（免 clone，一行流）：

bash -c "$(curl -fsSL https://raw.githubusercontent.com/cokelaoshi1/android-termux-dsh/main/install.sh)"

或克隆后执行：

pkg install -y git
git clone https://github.com/cokelaoshi1/android-termux-dsh.git
cd android-termux-dsh
bash install.sh

- 脚本会执行 pkg upgrade，务必等它跑完（Termux 不支持部分升级）。想跳过系统更新：bash install.sh --skip-upgrade
- 🇨🇳 中国大陆网络：建议直接 bash install.sh --cn 使用 npmmirror 镜像；不传也会自动检测（官方源连不通自动切换）
- 安装中最耗时的一步是 npm install（下载数百个包 + koffi 源码编译，约 5~15 分钟），下载阶段长时间无输出属正常，请保持屏幕常亮、不要关闭 Termux

安装完成后

dsh web

- 手机浏览器打开 http://127.0.0.1:3080，或在 Termux 里执行 termux-open-url http://127.0.0.1:3080
- 电脑访问：dsh web --host 0.0.0.0，浏览器打开 http://手机局域网IP:3080
- 首次使用请在 Web UI 的 设置 → 模型 里配置 LLM API Key

默认工作区 = sdcard（直接读写手机存储）

安装脚本默认做两件事，让网页版能直接读写手机存储：

1. 授权存储权限：执行 termux-setup-storage，Android 11+ 会跳转「所有文件访问」设置页，允许后生成 ~/storage/shared 等链接；
2. 固定工作区：往 ~/.dsh/profiles/web/cordis.patch.yml 写入：

- id: fs-sandbox
config:
cwd: /data/data/com.termux/files/home/storage/shared

这样 Web UI 的文件树、工作区根目录就是 sdcard（~/storage/shared），不再局限于启动 dsh web 时的目录。

- 安装时自定义工作区：DSH_WORKSPACE=/path/to/dir bash install.sh；跳过：DSH_WORKSPACE="" bash install.sh
- 想改默认值：编辑上面那个 cordis.patch.yml 的 cwd，重启 dsh web 生效
- 若提示「未找到 ~/storage/shared」：到 系统设置 → 应用 → Termux → 权限，手动允许「文件和媒体」后重跑脚本

手机端适配（可选）

dsh 网页版在窄视口下会自动把侧栏折叠成图标栏，但右侧面板（预览/文件变更）不会自动收起，手机上聊天区会被挤占。仓库提供一套移动端样式（mobile/ 目录），三种注入方式任选：

| 方式 | 适用 | 说明 |
| mobile/dsh-mobile.user.js | 支持扩展的浏览器（Kiwi / Firefox + Tampermonkey/Violentmonkey） | 打开页面自动注入，无需手动 |
| mobile/bookmarklet.txt | 任意浏览器 | 把 javascript: 代码存成书签，打开页面后点一下 |
| mobile/mobile.css | 手动 | 控制台 fetch 注入，或配合 Stylus 扩展 |

效果：窄屏强制单列布局、右侧面板自动隐藏（聊天区占满）、弹窗近全屏、触控目标加大、放开页面缩放。

脚本做了什么（全新 Termux 一站式）

1. 环境预检（Termux / 架构自动适配）
2. pkg update && pkg upgrade（必须先完整升级）
3. 安装基础工具与编译链：git curl cmake clang make python binutils pkg-config libandroid-spawn
4. 安装/检查 Node >= 22.12（dsh 的硬性要求）
5. 配置 npm：放行 install-scripts、加大下载超时与重试、--cn 切换 npmmirror
6. 预下载 Node 头文件并修补 node-gyp common.gypi（android_ndk_path）
7. 网络预检 → npm i -g @deepseek-ai/dsh（API 30 编译参数；koffi 源码编译，限并行防 OOM；失败自动换源重试；装完硬检查 dsh 命令）
8. 安装 sharp WebAssembly 兜底（@img/sharp-wasm32，失败自动换源，幂等跳过）
9. 应用 link() → rename() 补丁（部分定制 ROM 禁用 link() 系统调用）
10. 安装 --expose-internals 启动包装器 + pnpm
11. sdcard 存储授权 + 默认工作区配置（fs-sandbox.cwd → ~/storage/shared）
12. 逐项验证（dsh / koffi / node-pty / sharp / sdcard）并输出启动指引

脚本幂等：任何一步失败直接重跑即可续上；重新执行过 npm i -g @deepseek-ai/dsh 后，也建议重跑一次恢复第 8、9、10 步。

参数与环境变量

| 参数 / 变量 | 说明 |
| --skip-upgrade | 跳过 pkg update && pkg upgrade |
| --cn | 强制使用 npmmirror 镜像源（中国大陆网络推荐） |
| DSH_WORKSPACE=/path | 安装时自定义默认工作区 |
| DSH_WORKSPACE="" | 跳过 sdcard 工作区配置 |
| CMAKE_BUILD_PARALLEL_LEVEL=N | 自定义 koffi 编译并行度（默认 2，内存小的手机可设 1） |

故障排查

| 现象 | 处理 |
| node 启动报 OpenSSL 符号错误 / error while loading shared libraries | 先 pkg update && pkg upgrade -y（Termux 不支持部分升级） |
| npm error 'allow-scripts' is not a valid npm option | 无害：旧版 npm 没有该安全门，默认就会执行构建脚本，忽略即可 |
| CMake does not seem to be available | 重跑脚本（会自动补装工具链） |
| node-pty 报 android_ndk_path | 重跑脚本（common.gypi 补丁幂等） |
| 安装后 No command dsh found | npm 安装失败。脚本会在失败点红字提示（网络/磁盘/编译/OOM），按提示处理；也可加 --cn 重跑 |
| npm install 那步超过 15 分钟无任何输出 | 网络黑洞，Ctrl+C 后用 --cn 重跑，或检查代理/VPN |
| 安装中途无报错就退出（旧版本脚本） | 已修复：所有步骤现在失败必红字。若仍遇到，把停住前后 10 行发 issue |
| 网页版读不了 sdcard / 看不到手机存储 | 运行 termux-setup-storage 并允许权限（Android 11+ 需开启「所有文件访问」）；再确认 cordis.patch.yml 里 fs-sandbox.cwd 指向 ~/storage/shared |
| 会话保存报 EACCES: permission denied, link ... | 部分定制 ROM 全局禁用 link()。脚本第 9 步已自动应用 link() → rename() 补丁，重跑脚本即可修复；见 discussion #248 |
| 命令执行报 [timed out after Xms] / [killed by signal: SIGTERM] | bash 工具超时。慢设备上耗时命令请用 run_in_background: true；若每次都超时，确认内核 >= 5.13（Landlock），老内核的沙箱兜底会拖慢每次执行 |
| Tool call Error unknown tool "" | 模型/API 返回了畸形工具调用（流式 tool_calls 里 name 缺失或后到）。改用官方 api.deepseek.com + 模型 deepseek-chat（不要用 deepseek-reasoner 或工具支持差的第三方中转），新建会话重试 |
| bash 工具报 SANDBOX_UNAVAILABLE | 沙箱需要 Landlock（内核 >= 5.13）。老内核机型需自建 proot runner，见 discussion #136 |

原理简述

- Termux 的 clang 默认 target API 24，而 bionic 的 statx() 声明要 API >= 30 才可见，编译必须加 -target aarch64-linux-android30；
- Termux 的 Node 把 process.platform 报成 android，node-gyp 会解析引用 android_ndk_path 的 common.gypi，而该变量只在用 NDK 编译 Node 时才定义；
- npm 11.19+ 默认拦截 install-scripts，导致 koffi/node-pty 的构建脚本静默不执行（旧版 npm 无此行为，会正常执行）；
- sharp 只提供 linux/darwin/win 预编译，Android 需用其 WebAssembly 版本 @img/sharp-wasm32；
- HMR 插件需要 --expose-internals，该参数无法通过 NODE_OPTIONS 传入，只能改启动命令行。

参考

- [deepseek-ai/deepseek-harness discussion #136 — Could not run in Android/Termux [SOLVED]](https://github.com/deepseek-ai/deepseek-harness/discussions/136)
- deepseek-ai/deepseek-harness discussion #248 — link() fallback 提案
- sharp 安装文档

关于

一条命令就能在 Android 上通过 Termux 安装 DeepSeek Harness（@deepseek-ai/dsh）——从全新安装的 Termux 到完整可用的 web UI。修掉了一连串原生构建与运行时问题，正是这些问题让官方 npm i -g 在 Android/arm64 上失败。不需要 root。 已在 Android 16 / aarch64 / Termux 上验证。

特性

- ✅ 一站式：全新 Termux 上一条命令，装完即用
- ✅ 幂等：任何失败后重跑都能接着装；已装好的部分直接复用
- ✅ 网络自适应：官方 npm registry 连不上时自动切到 npmmirror 镜像（探测 8s）；失败后自动用镜像重试；调优了 fetch 超时与重试
- ✅ 防 OOM：限制 koffi 构建并行度，低内存手机更不容易被杀
- ✅ 默认工作区 = sdcard：web UI 开箱即读写手机存储
- ✅ 自校验：最后检查 dsh / koffi / node-pty / sharp / sdcard；任何失败都打印红色错误——不再有静默死亡
- ✅ 对中国大陆友好：--cn 参数切到 npmmirror registry

为什么需要它

@deepseek-ai/dsh 依赖的原生模块没有 android-arm64 预编译包：

| # | 模块 | 报错 | 处理方式 |
| 1 | koffi | CMake does not seem to be available | 安装 cmake clang make python binutils pkg-config libandroid-spawn |
| 2 | koffi | statx 编译报错（bionic 头文件问题） | 用 -target aarch64-linux-android30（API 30）构建 |
| 3 | node-pty | gyp: Undefined variable android_ndk_path | 给 node-gyp 缓存的 common.gypi 打补丁 |
| 4 | all | npm install-scripts 警告（脚本被静默跳过） | npm config set allow-scripts=... |
| 5 | sharp | Could not load the "sharp" module using the android-arm64 runtime | 安装 @img/sharp-wasm32 WebAssembly 回退方案 |
| 6 | cordis-plugin-hmr | --expose-internals is required | 用启动器包装脚本替换 npm 的 dsh 符号链接 |

环境要求

- Android 11+（API 30+，运行时需要 statx）
- 从 F-Droid 安装 Termux（Play Store 版本已停止维护）
- 内存 4GB 以上，可用存储 2GB 以上，网络稳定
- arm64（主流）/ armv7 / x86_64 / i686（自动检测）

快速开始

一行命令（无需 clone）——在 Termux 里运行：

bash -c "$(curl -fsSL https://raw.githubusercontent.com/cokelaoshi1/android-termux-dsh/main/install.sh)"

或者 clone 后运行：

pkg install -y git
git clone https://github.com/cokelaoshi1/android-termux-dsh.git
cd android-termux-dsh
bash install.sh

- 脚本会执行 pkg upgrade——让它跑完（不支持部分升级）。想跳过就用 bash install.sh --skip-upgrade
- 🇨🇳 中国大陆网络：用 bash install.sh --cn 走 npmmirror 镜像源；否则脚本会自动检测（官方源连不上就切换）
- npm install 这一步最耗时（几百个包 + koffi 源码构建，约 5–15 分钟）。下载期间一段时间没有输出是正常的——保持屏幕常亮，别关掉 Termux

安装之后

dsh web

- 在手机上：打开 http://127.0.0.1:3080（或运行 termux-open-url http://127.0.0.1:3080）
- 从 PC 访问：dsh web --host 0.0.0.0，然后打开 http://<手机局域网 IP>:3080
- 在 Web UI 的 Settings → Models 里配置你的 LLM API key

默认工作区 = sdcard（读写手机存储）

安装器默认做两件事，让 Web UI 能读写手机存储：

1. 存储权限：运行 termux-setup-storage（在 Android 11+ 上会打开「所有文件访问权限」设置页）；这会创建 ~/storage/shared 链接。
2. 固定工作区：写入 ~/.dsh/profiles/web/cordis.patch.yml：

- id: fs-sandbox
config:
cwd: /data/data/com.termux/files/home/storage/shared

这样 Web UI 的文件树 / 工作区根目录就是 sdcard（~/storage/shared），不管 dsh web 从哪里启动。

- 安装时自定义工作区：DSH_WORKSPACE=/path/to/dir bash install.sh；跳过：DSH_WORKSPACE="" bash install.sh
- 改默认值：编辑上面 cordis.patch.yml 里的 cwd，然后重启 dsh web
- 如果看到「~/storage/shared not found」：手动给 Termux 授予存储权限（Settings → Apps → Termux → Permissions → Files and media），然后重新运行脚本

移动端适配（可选）

在窄视口下，dsh web UI 会自动把侧边栏折叠成一条窄栏，但右侧面板（预览 / 文件变更）仍然展开，在手机上挤压聊天区域。本仓库在 mobile/ 里附带了一份移动端样式表，有三种注入方式：

| 方式 | 浏览器 | 说明 |
| mobile/dsh-mobile.user.js | 支持扩展的浏览器（Kiwi / Firefox + Tampermonkey/Violentmonkey） | 页面加载时自动注入 |
| mobile/bookmarklet.txt | 任意浏览器 | 把 javascript: 片段存成书签，加载后点一下 |
| mobile/mobile.css | 手动 | 从控制台 fetch 注入，或配合 Stylus 扩展使用 |

效果：窄屏下变成单列布局，右侧面板隐藏（聊天区占满宽度），模态框接近全屏，触控目标更大，缩放重新启用。

脚本做什么（一体化，全新 Termux）

1. 预检（Termux / 架构，自动检测）
2. pkg update && pkg upgrade（必须先跑完）
3. 安装基础工具 + 构建链：git curl cmake clang make python binutils pkg-config libandroid-spawn
4. 安装 / 检查 Node >= 22.12（硬性要求）
5. npm 设置：允许 install-scripts，调整 fetch 超时/重试，--cn 走 npmmirror
6. 预下载 Node headers，给 node-gyp 的 common.gypi 打补丁（android_ndk_path）
7. 网络探测 → npm i -g @deepseek-ai/dsh（目标 API 30；koffi 从源码构建并限制并行度；自动用镜像重试；之后硬校验 dsh 命令）
8. 安装 sharp 的 WebAssembly 回退（@img/sharp-wasm32；镜像重试；幂等跳过）
9. 应用 link() → rename() 补丁（部分定制 ROM 会拦截 link() 系统调用）
10. 安装 --expose-internals 启动器包装 + pnpm
11. 授予 sdcard 存储权限并固定工作区（fs-sandbox.cwd → ~/storage/shared）
12. 逐项验证（dsh / koffi / node-pty / sharp / sdcard）并打印启动说明

脚本是幂等的：任何一步失败后重跑即可继续；用 npm 重装 dsh 之后也要重跑，以恢复第 8–10 步。

参数与环境变量

| 参数 / 变量 | 含义 |
| --skip-upgrade | 跳过 pkg update && pkg upgrade |
| --cn | 强制使用 npmmirror 源（中国大陆推荐） |
| DSH_WORKSPACE=/path | 安装时自定义默认工作区 |
| DSH_WORKSPACE="" | 跳过 sdcard 工作区设置 |
| CMAKE_BUILD_PARALLEL_LEVEL=N | koffi 构建并行度（默认 2；低内存手机设为 1） |

故障排查

| 现象 | 修复 |
| Node 报 OpenSSL 符号错误 / error while loading shared libraries | 先运行 pkg update && pkg upgrade -y（不支持部分升级） |
| npm error 'allow-scripts' is not a valid npm option | 无害：旧版 npm 没有脚本门禁，默认就会跑构建脚本 —— 忽略即可 |
| CMake does not seem to be available | 重新跑一遍脚本（工具链会自动安装） |
| node-pty: android_ndk_path | 重新跑一遍脚本（common.gypi 补丁是幂等的） |
| 安装后提示 No command dsh found | npm 这一步失败了；脚本现在会当场中止并给出提示（网络 / 磁盘 / 构建 / OOM）；加上 --cn 再跑一遍 |
| npm install 这一步超过 15 分钟没动静 | 网络黑洞 —— Ctrl+C，加 --cn 重跑，或者检查你的代理 / VPN |
| 脚本跑到一半直接退出，没有任何报错（旧版本） | 已修复：现在每一步失败都会大声报错。如果还是这样，把中止位置前后 10 行贴进 issue |
| Web UI 读不到 sdcard / 手机存储 | 运行 termux-setup-storage 并授予权限（Android 11+ 需要在系统设置里开「所有文件访问权限」）；确认 cordis.patch.yml 把 fs-sandbox.cwd 固定到 ~/storage/shared |
| 保存会话时报 EACCES: permission denied, link ... | 部分定制 ROM 会拦截 link()。脚本第 9 步已经打了 link() → rename() 补丁 —— 重跑一遍即可修复；见 discussion #248 |
| 命令报 [timed out after Xms] / [killed by signal: SIGTERM] | bash 工具超时。在慢设备上跑长命令请用 run_in_background: true；如果每次调用都超时，确认内核 >= 5.13（Landlock）—— 旧内核上的沙箱回退会拖慢每次调用 |
| Tool call Error unknown tool "" | 模型 / API 返回了格式错误的工具调用（流式 tool_calls 里的 name 缺失或来得太晚）。请用官方 api.deepseek.com 端点搭配模型 deepseek-chat（别用 deepseek-reasoner，也别用工具能力差的第三方中转），然后开一个新会话 |
| bash 工具：SANDBOX_UNAVAILABLE | 沙箱需要 Landlock（内核 >= 5.13）。旧内核需要自定义 proot runner —— 见 discussion #136 |

工作原理（简版）

- Termux clang 默认以 API 24 为目标；bionic 只在 API >= 30 才暴露 statx()，所以需要 -target aarch64-linux-android30 这个标志。
- Termux Node 报告 process.platform === 'android'，于是 node-gyp 会去求值一个 common.gypi，其中引用了 android_ndk_path，而这个变量只有在 Node 本身用 NDK 构建时才有定义。
- npm 11.19+ 默认跳过安装脚本，会悄悄丢掉 koffi/node-pty 的构建（旧版 npm 会正常执行）。
- sharp 只提供 linux/darwin/win 的预构建；Android 用的是 WebAssembly 构建 @img/sharp-wasm32。
- HMR 插件硬性要求 --expose-internals，这个参数没法通过 NODE_OPTIONS 设置 —— 只能在命令行上加。

参考

- [deepseek-ai/deepseek-harness discussion #136 — Could not run in Android/Termux [SOLVED]](https://github.com/deepseek-ai/deepseek-harness/discussions/136)
- deepseek-ai/deepseek-harness 讨论 #248 —— link() 回退方案
- sharp 安装文档

许可证

MIT