安卓移植补丁 Yessssman/dsh-android-compat

DSH on Android/Termux —— 安卓兼容方案

把 DeepSeek Harness（DSH）移植到 aarch64 Android / Termux 上运行的完整方案：固化的升级流程、精确锚点补丁脚本、原生件构建、原生语音输入，以及一套自动验收脚本。

兼容层只有 patches/。 DSH 的 checkout 直接跟上游（origin = deepseek-ai/deepseek-harness），不维护 fork：升级就是「fetch 上游 → 用补丁把改动静默重放到新 tag 上」。移植分支只是补丁的产物，随时可由 recreate-android-branch.mjs 从任意 tag 重建。
（2026-10-18 起取消 fork，理由见 UPGRADE-RUNBOOK.md Phase J。）

入口

| 文档 | 内容 |
| UPGRADE-RUNBOOK.md | 固化升级方案（主入口）：A 检查上游 → B 冲突预判 → C rebase 与冲突处置 → D 同步移植 → E 安装 → F 构建 → G 验收 → H 提交 → I 用户重启；含已知故障模式表与回滚 |
| REPORT.md | 移植原理与历史（§9 之后为源码树移植的有效部分） |
| REPORT-upgrade-.md | 历次升级的完整记录（从 0.1.7-alpha.1 到 0.2.1-rc.2） |
| sherpa-android/ | 本地 SenseVoice 语音识别的 Node-API 绑定（源码、编译脚本、真机证据） |
| voice-conversation/ | 朗读插件（本地 VITS）的适配与启停脚本 |
| attachment-check/ | 附件存储的安卓修复与复验 |

工具链（patches/）

| 脚本 | 作用 |
| recreate-android-branch.mjs | 从任意上游 tag 重建移植分支：切基线、应用锚点、校验、提交；补丁无法生成锁文件，安装后 amend |
| apply-source-patches.mjs | 46 条精确锚点补丁，幂等；--check 只校验不写 |
| sync-android-port.mjs | 一条命令跑完重建 / pnpm install 之后必须做的机械步骤（清孤儿产物 → 锚点 → Codex payload → node-pty 绑定），失败即停 |
| verify-android-port.mjs | 12 项隔离验收：版本、锚点、客户端产物、原生件、三种启动方式、语音绑定、可证只读、进程清理 |
| prune-stale-builds.mjs | 清理上游改名后遗留的孤儿 lib/（会毒化 tsdown 的构建） |
| install-codex-payload.mjs | 安装 pnpm 因 os: ["linux"] 跳过的 Codex arm64 payload |
| install-node-pty-binding.mjs | 在设备上 node-gyp rebuild 出 node-pty 的 android 绑定（持久化终端需要） |

快速开始

git clone https://github.com/Yessssman/dsh-android-compat ~/android-dsh
git clone https://github.com/deepseek-ai/deepseek-harness ~/deepseek-harness

用补丁把移植重放到当前上游 tag 上（建本地分支 + 应用锚点 + 提交）
node ~/android-dsh/patches/recreate-android-branch.mjs --root ~/deepseek-harness --from dsh-v0.2.1-rc.2

完整流程（装依赖、构建、验收）见下面的「在 Termux 上从零跑起来」

本方案假定端口工具链放在 ~/android-dsh、DSH checkout 在 ~/deepseek-harness （文档里的路径都按这个约定书写）。

上游更新后怎么跟

不维护 fork，也不依赖移植分支的历史——兼容层就是补丁：

cd ~/deepseek-harness
git fetch origin --tags # origin 直接指上游
node ~/android-dsh/patches/recreate-android-branch.mjs --root . --from <新 tag>

锚点若与上游正文漂移，脚本会在对应文件上失败（而不是悄悄跳过），按 UPGRADE-RUNBOOK.md Phase C 改锚点字面量后重建即可。
完整判据与备选方案（保留历史的 rebase）也在那里。

--from 接受任何 ref，所以也能直接落在未发版的 master 上：

node ~/android-dsh/patches/recreate-android-branch.mjs --root . --from origin/master --dry-run
node ~/android-dsh/patches/recreate-android-branch.mjs --root . --from origin/master

脚本会检测目标有没有 dsh-v tag 指向它：非发版目标会打印 base NOT a release commit: includes unreleased upstream work，并把解析到的短 SHA 写进提交信息 （origin/master 是会动的 ref，事后得能查到基于哪个提交）。代价是可复现性不如 tag、锚点更容易漂移，所以打 master 之后安装与构建仍然照做。

在 Termux 上从零跑起来

以下步骤在一台全新的 Termux（aarch64）上从零到能打开 Web UI。实测设备：Android 16、 kernel 5.15、Node v26.4.0、pnpm 11.28.5。

0. 前置

- 磁盘 ~3 GB：.git 约 315 MB，node_modules 约 1.7 GB，Web 产物约 22 MB，再加构建临时目录。
- 内存：全量构建的观察峰值约 10 GB。设备内存小的话务必串行构建并留足 swap，否则容易被 OOM 杀掉。

1. 装 Termux 包

pkg update -y
pkg install -y git nodejs clang make python ripgrep
npm install -g pnpm@11.28.5 # 与根 package.json 的 packageManager 一致，避免再下载一份

各包的作用：

| 包 | 为什么需要 |
| nodejs | 运行时（engines 要求 ^22.19.0 \|\| >=24），并带 Node-API 头文件 $PREFIX/include/node/node_api.h |
| clang | native/system 的原生件用 cc 编译；node-pty 与 sherpa 绑定也用它 |
| make + python | node-gyp rebuild（node-pty 的 android 绑定必须在本机编） |
| ripgrep | 搜索的兜底：@vscode/ripgrep 没有 android 包，移植版会退到 PATH 上的 rg |
| git / curl | 克隆与下载 |

2. 克隆两个仓库并应用补丁

cd ~
git clone https://github.com/deepseek-ai/deepseek-harness deepseek-harness # 直接跟上游
git clone https://github.com/Yessssman/dsh-android-compat android-dsh

用补丁把移植重放到选定的上游 tag 上：建分支、应用 46 条锚点、校验、提交
node ~/android-dsh/patches/recreate-android-branch.mjs --root ~/deepseek-harness --from dsh-v0.2.1-rc.2

补丁是移植的唯一真源，分支只是产物。脚本会要求工作树干净、锚点全部应用成功（46 applied, 0 failed）才提交；跑完会打印锁文件由安装生成、以及下一步命令。

3. 装依赖

cd ~/deepseek-harness
pnpm install --ignore-scripts

--ignore-scripts 不能省：不跳过的话 lefthook 的 postinstall 会因为找不到 lefthook-android-arm64 而失败，而构建并不需要它。

4. 补齐设备内必须先做的两件事

node ~/android-dsh/patches/sync-android-port.mjs --root ~/deepseek-harness

这一条命令依次做四步，任一步失败就停：

1. 清理上游改名遗留的孤儿 lib/（会毒化 tsdown 构建）
2. 校验 46 条锚点（already-present: 46, failed: 0）
3. 装 Codex 的 arm64 payload（pnpm 因 os: ["linux"] 永远跳过它）
4. 编译并安装 node-pty 的 android 绑定（持久化终端需要）

5. 构建

cd ~/deepseek-harness
NODE_OPTIONS=--max-old-space-size=3072 pnpm build
NODE_OPTIONS=--max-old-space-size=3072 pnpm build:native-system

成果：客户端产物约 331 件；native/system/packages/android-arm64/bin/bionic/system.node 约 11,504 B。
首次全量构建大约 6–10 分钟（这台设备上 9 个构建门禁并行，实测 275–557 秒不等）。

6. 本地语音输入绑定（可选，但影响下一步验收）

bash ~/android-dsh/sherpa-android/setup.sh

下载并校验 sherpa-onnx 的 Termux aarch64 产物、编译 Node-API 绑定、安装到 ~/.dsh/speech-to-text/sensevoice/native/，再冒烟测试。约 27 MB + 模型文件。

这一步决定验收是全过还是少两项：内置语音识别（SenseVoice）依赖这个绑定和模型。
不做语音也用，但跳过它时下面的 sherpa native 与 voice preparation 两项会失败——那是预期的，不是构建坏了。

朗读（TTS）插件是另一件事，见 voice-conversation/；默认不启用，需要时用它的 voice-mode-toggle.sh enable/disable/status。

7. 验收（强烈建议）

node ~/android-dsh/patches/verify-android-port.mjs --root ~/deepseek-harness

做完了第 6 步时期望最后一行 PASS verify-android-port (12/12; failed=0)、退出码 0；没做第 6 步则是 10/12，并且失败的正好是那两项语音检查。

它会用隔离的 DSH_HOME 起三次服务（构建产物、源码、真实 profile 副本）、加载原生绑定、校验语音准备链路，并证明整个过程中 checkout 只读、自己起的进程都清干净。

8. 跑起来

cd ~/deepseek-harness
pnpm dsh web

终端会打印一行带 token 的地址，形如 http://127.0.0.1:3080/?token=…，在手机浏览器打开即可。
直接访问 / 会 401，必须带这个 token（首次打开后会用 cookie 记住）。
首次使用要到设置里配置模型凭据：先在界面里登录 DeepSeek 账号，或在 Models 页填入 API key。
数据落在 ~/.dsh。

⚠️ pnpm dsh web 跑在前台，重启服务要你自己在同一个 shell 里 Ctrl+C 再起；任何脚本/自动化都不应该去杀它。

9. 升级到新上游版本

见 UPGRADE-RUNBOOK.md（A→I），完成后按 Phase J 推回 GitHub。

当前状态

- 上游基线 dsh-v0.2.1-rc.2（687f282e86），版本 0.2.1-rc.2
- 移植 10 个提交、相对基线 31 个文件；其中 30 个源文件可由 46 条锚点逐字节复现，剩下 pnpm-lock.yaml 由 pnpm install 生成
- 锚点 46/46；客户端产物 331 件；原生件 android-arm64/bin/bionic/system.node 11,504 B
- 验收 12/12

设备与环境

| 项 | 值 |
| 设备 | Android 16，kernel 5.15，aarch64 (arm64-v8a) |
| 运行时 | Termux，Node v26.4.0 |
| 交互方式 | pnpm dsh web（源码启动），浏览器访问 |

移植了什么（要点）

- 原生件：上游没有 android 目标，新增 native/system/packages/android-arm64，按 bionic libc 构建 system.node（flock 等）。
- 启动：app-boot 的原生 requireBuiltin 在缺少 android 二进制时回退到 Node 的 --expose-internals；dsh 脚本与 bin.ts shebang 都带上该 flag。这是 pnpm dsh web 能起来的关键。
- 文件发布：Android 沙箱拒绝 link(2)，会话日志与附件改用 rename / COPYFILE_EXCL 发布，保留 no-replace 语义。
- shell / 搜索：默认 shell 与 PATH 走 Termux 前缀；ripgrep 先看 DSH_RIPGREP_PATH，再退到 PATH 上的 rg。
- 语音输入：sherpa-onnx 没有 android 包，自带 Node-API 绑定；worker 需显式带 LD_LIBRARY_PATH 指向绑定目录（Termux 的 onnxruntime 包会用同名 .so 遮蔽兄弟库）。
- 持久化终端：process-inspector 让 android 复用 Linux /proc 实现（systemd scope 仍仅限 Linux）；node-pty 需在设备上编译。
- 图片：sharp 无 android binding，走 @img/sharp-wasm32 兜底。

已知限制

- 本地沙箱不可用：该内核 landlock 返回 ENOSYS、bwrap 缺失，命令执行需 Full Access 或人工审批；这是上游 fail-closed 的正确表现。
- Codex 子智能体：只能跑 dangerously-bypass-approvals-and-sandbox 模式（安卓拦掉 bwrap/landlock），即无沙箱全权限，只应交给可信任务。
- 每次 pnpm install 后都要重跑 sync-android-port.mjs（会冲掉 Codex payload 与 node-pty 绑定）。
- 只在一台 aarch64 设备上验证；其他设备/架构未测。

许可

本仓库的文档与脚本按移植工作需要编写，随上游 DSH 一并遵循其许可； patches/*.patch 与 sherpa-android/ 中的第三方代码遵循各自来源的许可。