在 Android/Termux 原生跑通 DSH：补齐 node-addon-require-builtin 的 android 编译与 bionic 补丁（附可复现步骤）

[lzx2322374600-coder]

TL;DR

在 Android / Termux 上原生跑通 DSH 的最后一块硬骨头：@deepseek-ai/dsh 启动时硬依赖的原生插件 node-addon-require-builtin 没有 android-arm64 预编译产物，会让 dsh web 直接致命退出。

本文给出在手机上现场编译该插件的完整方法（两处极小的源码补丁 + 一条构建命令），已在真机实测跑通。

社区的一键脚本（cokelaoshi1/android-termux-dsh、FunnelCakes/deepseek-harness-android）已经解决了 koffi / node-pty / sharp / HMR(--expose-internals) / link() 等一长串问题；本文补上它们目前还没覆盖的那一步。

---

环境（实测）

项	值
设备	REDMI K90 Pro Max（HyperOS OS4.0 / Android 17，arm64-v8a）
Termux	F-Droid v0.118.3
Node	v26.4.0（Termux 包；process.versions.modules = 147）
DSH	@deepseek-ai/dsh 0.2.0-rc.2（npm i -g，包装器带 --expose-internals）
触发点	node-addon-require-builtin@0.1.x（@deepseek-ai/dsh-app-boot 启动时 require）

现象

$ dsh web
dsh: fatal uncaught exception: Error: dsh: host preparation failed:
     No usable native binding found for node-addon-require-builtin-android-arm64 (auto)
    at boot (.../@deepseek-ai/dsh-app-boot/lib/index.js:4105:9)

加载器 node-addon-native-custom-loader 的查找顺序是：

1. optional 包 node-addon-require-builtin-android-arm64 → 官方未发布（只发布了 darwin-x64/arm64、linux-x64/arm64-gnu、linux--musl、win32-）；
2. 本地构建：node-addon-require-builtin/build/<backend>/<abi>-android-arm64/require_builtin.node。

根因（两处，都不大）

1. scripts/build.ts 的平台白名单只覆盖 darwin / linux / win32，android 直接抛
   Error: unsupported platform for direct build: android；
2. packages/native/src/{runtime_context,runtime_probe}/platform.cc 把
   __linux__ && __GLIBC__ 之外的一切 Linux 都判为"不支持"，
   于是 bionic(Android) 命中 Unsupported/no-context: unsupported linux libc current-context reader。
   —— 但被门禁挡住的实现（ReadDirectCurrentV8Context / DecodeGetterWithWideWindowRetry）
   本身是平台无关的，只是分支按 glibc 写死了。

解法

1) 两处源码补丁

packages/native/src/runtime_context/platform.cc：

 #elif defined(__linux__) && defined(__GLIBC__) && defined(__aarch64__)
   return ReadLinuxGlibcArm64CurrentV8Context(isolate, symbols);
+#elif defined(__linux__) && defined(__aarch64__)
+  // Android/bionic (Termux): the arm64 reader below is platform-neutral
+  // (it only calls resolved symbols), so bionic can use the same path.
+  return ReadLinuxGlibcArm64CurrentV8Context(isolate, symbols);
 #elif defined(__linux__) && defined(__GLIBC__) && defined(__x86_64__)

packages/native/src/runtime_probe/platform.cc：

 #elif defined(__linux__) && defined(__GLIBC__) && defined(__aarch64__)
   return ParseLinuxGlibcArm64BuiltinModuleRequireGetterOffset(getter);
+#elif defined(__linux__) && defined(__aarch64__)
+  // Android/bionic (Termux): reuse the AAPCS64 getter matcher.
+  return ParseLinuxGlibcArm64BuiltinModuleRequireGetterOffset(getter);
 #elif defined(__linux__) && defined(__GLIBC__) && defined(__x86_64__)

scripts/build.ts：把 android 当成 linux 的链接参数

   if (process.platform === 'linux') {
     return ['-shared', '-fPIC', '-pthread', ...args];
   }
-  throw new Error(`unsupported platform for direct build: ${process.platform}`);
+  // Android/bionic: same link flags as linux
+  return ['-shared', '-fPIC', '-pthread', ...args];

另外必须删掉源码 package.json 里的 "packageManager": "pnpm@9.15.9"：
该版本的 @pnpm/exe 没有 android-arm64 二进制，pnpm 会直接拒绝运行。

2) 构建与安装（就在手机上编译）

PREFIX=/data/data/com.termux/files/usr
WORK=$HOME/.cache/dsh-require-builtin && mkdir -p $WORK && cd $WORK
curl -fsSL -o narb.zip https://github.com/deepseek-ai/dsh-node-addon-require-builtin/archive/refs/heads/master.zip
rm -rf src && mkdir src && unzip -q -o narb.zip -d src && cd src/*/

sed -i '/"packageManager"/d' package.json
sed -i 's|throw new Error(`unsupported platform for direct build: ${process.platform}`);|return ["-shared", "-fPIC", "-pthread", ...args];|' scripts/build.ts
# 再按上面两个 diff 改好 platform.cc（或直接跑文末的一键脚本）

export NARB_PRODUCT=require-builtin
pnpm install --ignore-scripts --config.manage-package-manager-versions=false --config.pmOnFail=ignore
pnpm build

DEST="$PREFIX/lib/node_modules/@deepseek-ai/dsh/node_modules/node-addon-require-builtin"
mkdir -p "$DEST/build/napi/napi-v9-android-arm64"
cp packages/require-builtin/entry/build/napi/napi-v9-android-arm64/require_builtin.node \
   "$DEST/build/napi/napi-v9-android-arm64/"

3) 验证

$ cd $PREFIX/lib/node_modules/@deepseek-ai/dsh
$ node -e "const a=require('node-addon-require-builtin');console.log(a.getBindingInfo().bindingSource);
           const l=a.requireBuiltin('internal/modules/esm/loader');
           console.log(typeof l.getOrInitializeCascadedLoader)"
local-build
function

之后 dsh web 正常启动，浏览器访问 http://127.0.0.1:3080 即可（首次要用它打印的带 ?token= 的地址访问）。

给上游的两点建议

1. deepseek-ai/dsh-node-addon-require-builtin
   • scripts/build.ts 支持 android；
   • platform.cc 的 __linux__ && __aarch64__（bionic）走 arm64 reader；
   • 发布 node-addon-require-builtin-android-arm64（napi-v9）optional 包 —— 这样 Termux 用户 npm i -g 后即可直接用。
2. @deepseek-ai/dsh-app-boot：在缺少该插件时能否优雅降级（例如检测到已用 --expose-internals 启动时回退到内置通道），而不是致命退出？Android/Termux 属于社区长期存在的使用场景，一个可选依赖不该让整个 harness 无法启动。

附：一键修复脚本

fix-require-builtin-android.sh（可直接并入 Termux 安装脚本，幂等）

#!/data/data/com.termux/files/usr/bin/bash
# 为 Android/Termux 构建 DSH 硬依赖 node-addon-require-builtin（官方无 android-arm64 预编译）
set -e
PREFIX="${PREFIX:-/data/data/com.termux/files/usr}"
export PATH="$PREFIX/bin:$PATH" LD_LIBRARY_PATH="$PREFIX/lib" TMPDIR="$PREFIX/tmp"
WORK="${NARB_WORK:-$HOME/.cache/dsh-require-builtin}"; REF="${NARB_REF:-master}"

DSH_MODULES="$(node -e "console.log(require.resolve('@deepseek-ai/dsh/package.json').replace(/\/@deepseek-ai\/dsh\/package.json$/,''))")"
TARGET="$DSH_MODULES/node-addon-require-builtin"

mkdir -p "$WORK"; cd "$WORK"
[ -f narb.zip ] || curl -fsSL -o narb.zip \
  "https://github.com/deepseek-ai/dsh-node-addon-require-builtin/archive/refs/heads/$REF.zip"
rm -rf src; mkdir src; unzip -q -o narb.zip -d src; cd src/*/

sed -i '/"packageManager"/d' package.json
sed -i 's|throw new Error(`unsupported platform for direct build: ${process.platform}`);|return ["-shared", "-fPIC", "-pthread", ...args];|' scripts/build.ts

python3 - <<'PY'
import re, pathlib
ctx = pathlib.Path('packages/native/src/runtime_context/platform.cc')
s = ctx.read_text()
s = s.replace(
"""#elif defined(__linux__) && defined(__GLIBC__) && defined(__aarch64__)
  return ReadLinuxGlibcArm64CurrentV8Context(isolate, symbols);""",
"""#elif defined(__linux__) && defined(__GLIBC__) && defined(__aarch64__)
  return ReadLinuxGlibcArm64CurrentV8Context(isolate, symbols);
#elif defined(__linux__) && defined(__aarch64__)  // Android/bionic
  return ReadLinuxGlibcArm64CurrentV8Context(isolate, symbols);""")
ctx.write_text(s)

probe = pathlib.Path('packages/native/src/runtime_probe/platform.cc')
s = probe.read_text()
s = s.replace(
"""#elif defined(__linux__) && defined(__GLIBC__) && defined(__aarch64__)
  return ParseLinuxGlibcArm64BuiltinModuleRequireGetterOffset(getter);""",
"""#elif defined(__linux__) && defined(__GLIBC__) && defined(__aarch64__)
  return ParseLinuxGlibcArm64BuiltinModuleRequireGetterOffset(getter);
#elif defined(__linux__) && defined(__aarch64__)  // Android/bionic
  return ParseLinuxGlibcArm64BuiltinModuleRequireGetterOffset(getter);""")
probe.write_text(s)
PY

export NARB_PRODUCT=require-builtin
pnpm install --ignore-scripts --config.manage-package-manager-versions=false --config.pmOnFail=ignore
pnpm build

mkdir -p "$TARGET/build/napi/napi-v9-android-arm64"
cp packages/require-builtin/entry/build/napi/napi-v9-android-arm64/require_builtin.node \
   "$TARGET/build/napi/napi-v9-android-arm64/"

cd "$DSH_MODULES"
node -e "const a=require('node-addon-require-builtin');
         if(a.getBindingInfo().bindingSource!=='local-build')process.exit(1);
         if(typeof a.requireBuiltin('internal/modules/esm/loader').getOrInitializeCascadedLoader!=='function')process.exit(1);
         console.log('requireBuiltin OK')"

---

*本文形成于 2026-10-08，实测链路：Termux → Node v26.4.0 → @deepseek-ai/dsh 0.2.0-rc.2 → dsh web 在 127.0.0.1:3080 正常提供服务（同一台手机上还跑了 dsh-preset-mobile-use + agent-mobile-use 的副屏自动化，一并验证通过）。

[PerryLink]

你把一个平台缺口变成了可复现的移植手册——建议把诉求写在"缺口本身"上

1. 这一类的形态在本仓是有先例的

本仓的原生件是按平台分发的预编译产物（例如 @deepseek-ai/node-addon-system 就是按 darwin-*/linux-* 等分发预编译二进制）。因此：

• 缺某个平台的产物 ⇒ 该平台无法启动，这与你的观察（"node-addon-require-builtin 没有 android-arm64 预编译产物，会让 dsh web 直接致命退出"）形态一致；
• 同族报告也有过（例如 macOS arm64 的平台包里嵌了 x86）⇒ 说明"平台产物矩阵"这一层确实会出问题，你的报告不是孤例。

⚠️ 一处我核不到：我在 packages/subprocess/node-addon-require-builtin/package.json 里检索 android 没有命中。所以请补一句该包的实际路径与它的平台清单在哪里声明（optionalDependencies？os/cpu 字段？还是发布脚本的矩阵？）——否则维护者会先去找不到出处。

2. 你的贡献价值在于"在设备上现场编译跑通了"

这是移植手册式的产出，比"报个 bug"有用的多。建议把诉求写成两条：

1. 明确不支持平台的行为：目前是致命退出。请让它在不支持平台上给出指名缺失产物的可读错误（而不是让用户从退出码猜），并在文档里列出受支持平台；
2. 给出官方认可的移植路径：要么把 android-arm64 纳入发布矩阵，要么把你的现场编译步骤吸收进文档（你的两处小补丁 + 一条构建命令已经是可复制的形态）。

第 2 条比"请支持 Android"更容易被接受——因为它不要求维护者承诺新平台，只要求把已有的缺口写清楚。

3. 请补三样（让第 2 条能落地）

1. 那两处补丁的 diff（贴出来，不要只描述——本仓不接受外部 PR，讨论区贴 diff 就是唯一通道）；
2. 真机环境（Termux 版本、Android 版本、node -v、编译工具链版本）；
3. 启动成功后的验证方式（dsh web 起来之后做了什么才算"跑通"）。

4. 版本提醒（本轮基线）

HEAD = origin/master = 5badb15009 = dsh-v0.2.1-alpha.1
npm: alpha = 0.2.1-alpha.1    next = 0.2.0-rc.2    latest = 0.2.0-rc.2

⚠️ 注意 npm 的 latest 不再是旧的 0.1.5-rc.3（那是几周前的情况）。

一条边界

我确认的是**"按平台分发预编译产物"这一形态在本仓成立、且平台矩阵出过问题**（这支撑了你的归因）。该包是否真缺 android-arm64 产物以你的实测与第 1 节的路径为准——我没有核到该包的清单。