鸿蒙适配补丁 shenjackyuanjie/dsh-ohos-patch

dsh-ohos-patch

保存让 dsh（test-shenjackyuanjie monorepo，CLI 入口 bin/dsh）在 OpenHarmony (openharmony-arm64) 上能完成 pnpm install 并正常运行所需的全部 patch 与配置。

2026-08-11 实测结论：ohos 正常终端下 pnpm install 完整成功 + bin/dsh --help 可用（6 PASS / 0 FAIL），只需 1 个 patch（install-lefthook 跳过）。详见 docs/ohos-install.md。

⚠️ 注意事项（重要）

*本仓库是外部公开仓库（dsh-external/dsh-ohos-patch），只允许存放 patch、文档、脚本与配置，严禁包含任何 dsh 的源码——包括但不限于：

- 仓库内部的源文件（packages/、apps/、scripts/、src/ 等）
- 源码片段、关键实现逻辑、内部模块名/结构信息
- 内部工具脚本的完整内容（如 scripts/install-lefthook.mjs 等）

例外：patches/ 下的 patch 文件（diff）是允许的——它是针对第三方依赖/脚本的修改指令，必要的 diff 上下文不算源码泄漏（本仓库的 patches/install-lefthook-ohos-skip.patch 即为此类）。判断标准：凡是"被修改的对象"属于 dsh 仓库自身源码的完整文件/大段代码，一律不放入；仅作为修改指令存在的 diff 不受限。

对外沟通（工单/社区提问）时同样不得提及 dsh 项目名与内部实现，统一描述为 "一个 Node.js 项目"。

背景（环境约束，2026-08-11 实测）

- 平台：openharmony arm64，process.platform === 'openharmony'（不是 linux）。
- Node：v24.13.0（HarmonyOS 构建，/data/service/hnp/node.org/node_v24.13.0/bin/node）。
- 沙箱：任何 fork 出的子进程 无法分配 JIT 可执行内存，node 进程启动即崩（Check failed: 12 == (__errno_location()) / Signal 5）；只有"命令执行器直接启动的进程"可跑 node（详见 docs/ohos-sandbox-notes.md）。
- 全局 pnpm 已切换为 11.7.0（与仓库 package.json 声明一致，旧 11.20.0 备份于 /data/storage/el2/base/files/npm_global_modules/lib/node_modules/pnpm-11.20.0.bak）。

目录结构

dsh-ohos-patch/
├── README.md # 本文件 ├── docs/ │ ├── ohos-install.md # 安装配方（实测通过） │ └── ohos-sandbox-notes.md # 沙箱环境实测结论与工作流 ├── patches/ # 各依赖/仓库代码的 patch 文件（git format-patch / diff） ├── scripts/ │ └── ohos-install.sh # 安装+诊断脚本（用户 shell 执行） └── config/ # 需要落地的配置（.npmrc、pnpm-workspace 改动等）

已知 patch 点（跟踪清单）

| # | 优先级 | 目标 | 问题 | 状态 |
| 1 | P0 | 全局 pnpm | 11.20 engine 自切换验证报错 | ✅ 已解决（切到 11.7.0） |
| 2 | P0 | scripts/install-lefthook.mjs | probePairingMergeDriver spawn node 子进程必崩 + lefthook 无 ohos 二进制 | ✅ patches/install-lefthook-ohos-skip.patch，用户环境实测生效 |
| 3 | P0 | install 配方 | 沙箱内需 --ignore-scripts；真实 shell 可完整安装 | ✅ docs/ohos-install.md（实测 6 PASS） |
| 4 | P1 | esbuild | 平台映射缺失 | ✅ 无需 patch：npmmirror 版自带 openharmony arm64 LE 映射 + @esbuild/openharmony-arm64 WASM shim，transform 实测可用 |
| 5 | P1 | lefthook | lefthook-openharmony-arm64 不存在 | ✅ 由 #2 覆盖（git hooks 非必需） |
| 6 | P2 | node-pty | 无 linux-arm64 prebuild + 无 gcc 工具链 | ⏳ 未适配（PTY 运行时功能，install 不阻塞） |
| 7 | P2 | landlock-run | OpenHarmony 内核 Landlock LSM 可用性未验证 | ⏳ 运行时待验证（install WARN 可忽略） |
| 8 | P0+ | node 平台识别 | 若 node 报 linux 可免去逐包适配 | ⏳ 已不需要（esbuild/oxc 等已有 openharmony 变体） |

关键结论：CodeWhale 沙箱的"子进程 JIT 限制"是沙箱特有的，真实 ohos shell 无此问题； HarmonyOS 禁用户目录 exec ELF（ESBUILD_BINARY_PATH 原生方案不可行，WASM shim 不受影响）。

环境上下文（路径）

- 仓库：/storage/Users/currentUser/deepseek/test-shenjackyuanjie（同步副本 dsh/source/master）
- pnpm store：/storage/Users/currentUser/.local/share/pnpm/store/v11
- 全局 npm 模块：/data/storage/el2/base/files/npm_global_modules 方案记录（2026-08-11 更新）

lightningcss 在 OHOS 不可用 → 替换为 lightningcss-wasm

- 根因：lightningcss 无 openharmony 变体；借用 linux-arm64-gnu binding 后其动态依赖 libgcc_s.so.1 在 OHOS 缺失（musl libgcc 与 glibc binding ABI 不匹配 → transform 时 V8 崩溃）。
- 解决：仓库 packages/client/tsdown.client.ts 的 dsh-css-modules-inline 插件 import { transform } from "lightningcss" → "lightningcss-wasm"（API 完全兼容，进程内 WASM，无 dlopen/libgcc/ABI 问题）；root devDependencies 增加 lightningcss-wasm ^1.33.0。
- 验证：CodeWhale 特权进程里 tsdown --env.DSH_BUILD_FACE client 完整跑通，31 个 client.js bundle 生成；CSS modules transform 正常（LCWASM_OK）。

patch 资产清单（2026-08-11）

| 文件 | 作用 | 性质 |
| patches/install-lefthook-ohos-skip.patch | scripts/install-lefthook.mjs 在 ohos 跳过（lefthook 无 ohos 二进制 + probe 依赖 node 子进程） | 代码 patch |
| patches/ohos-build-fixes.patch | packages/client/tsdown.client.ts: lightningcss → lightningcss-wasm（CSS modules 修复）；package.json: +lightningcss-wasm devDep + @img/sharp-wasm32 dep（sharp WASM fallback） | 代码 patch |
| patches/bin-dsh-expose-internals.patch | bin/dsh 在 ohos 自动加 --expose-internals（HMR 服务必需；NODE_OPTIONS 不允许携带该 flag） | 代码 patch |
| patches/web-ohos-disabled.yml | dsh web 启动时禁用无 ohos 二进制的插件（subprocess/sandbox→node-pty/koffi、credentials→.credentials.yaml 660 权限、bash-sandbox/permission→依赖链缺失）；sharp 已由 wasm 修复，attachment 保留 | 运行时 patch（--patch 参数） |

安装流程（一站式，CodeArts/特权环境）: sh scripts/ohos-install.sh → apply patches → pnpm install --ignore-scripts → sign-native.sh（self-sign 全部 binding）→ build:lib:host/client → build:web → 验证

手动分步: 见 docs/ohos-install.md。

启动 web（生产模式）: bin/dsh web --patch ~/deepseek/dsh-ohos-patch/patches/web-ohos-disabled.yml --host 0.0.0.0 --port 8080 < /dev/null bin/dsh 已在 ohos 自动携带 --expose-internals（HMR 服务要求），无需手动加 flag。
降级说明：subprocess/sandbox（PTY/FFI）与 credentials 被禁用，agent 的 bash 执行与凭据加载暂不可用；后续 node-pty/koffi 有 ohos 版或正式签名后恢复。

致谢

- 感谢 codewhale 作者编写了 codewhale
- 感谢几个月前的我自己把 codewhale 移植到了鸿蒙上
- 感谢 DeepSeek 团队写了 dsh