鸿蒙客户端 xiaogouyo/dsh-harmonyos

DeepSeek Harness 鸿蒙客户端（DSH for HarmonyOS）

⚠️ v1.0.2 起采用「纯 ArkTS 原生壳」方案（entry 模块，不依赖 Electron 运行时）： Web 组件直接加载 DSH UI（127.0.0.1:3080）+ 服务状态检测 + 启动引导。
原因：Electron 运行时（libelectron.so）在目标设备上初始化白屏，换路绕开。
产物：release/entry-default-unsigned.hap（131KB，未签名，需用开发者证书签名后安装）

📦 GitHub：https://github.com/xiaogouyo/dsh-harmonyos（代码 + 已签名 HAP，LFS 存储）

把原版 DeepSeek Harness（DSH）封装成鸿蒙原生安装包（HAP），运行在鸿蒙 PC / 2in1 设备上。
形态：Electron 壳应用（自动拉起 dsh web 服务 + 内嵌 DSH Web UI）+ ohos_electron_hap 打包链路。

1. 为什么是 Electron → HAP，而不是纯 ArkUI？

- 原版 DSH 是 Node.js 程序（@deepseek-ai/dsh），本身没有鸿蒙原生版，教程（hu60.cn/q.php/bbs.topic.107504.html）的做法是在鸿蒙 PC 上用 Harmonybrew 跑 Node + dsh web，再用浏览器访问 http://127.0.0.1:3080。
- 本方案把「浏览器」替换为一个独立的鸿蒙 App：它负责自动拉起 DSH 服务、检测服务状态、内嵌 DSH 界面——体验接近 Electron 桌面应用，但以标准 HAP 分发，可安装、可卸载、有独立图标。
- 打包使用 ohosvscode/ohos_electron_hap（华为官方论坛同名《Electron框架HarmonyOS开发指导》验证过的方案）：鸿蒙侧提供 Chromium + Electron 运行时（libelectron.so 等），Electron 应用代码零改动放入 HAP 的 resfile 资源即可运行，BrowserWindow 等 API 桥接到鸿蒙多窗口能力。

2. 架构

┌──────────────────────────── 鸿蒙 PC / 2in1 ────────────────────────────┐ │ │ │ HAP（本工程产物） │ │ ┌─────────────────────────────┐ ┌────────────────────────┐ │ │ │ Electron 运行时（骨架提供） │ │ Harmonybrew Node.js │ │ │ │ libelectron.so / libffmpeg.so│ │ ~/.npm-global 全局安装 │ │ │ └─────────────┬───────────────┘ │ @deepseek-ai/dsh │ │ │ │ 主进程 main.js └────────────┬───────────┘ │ │ ┌─────────────▼───────────────┐ spawn / 检测 │ dsh web │ │ │ ① 探测 127.0.0.1:3080 │ ───────────────► │ 监听 3080 │ │ │ ② 离线 → 自动拉起 dsh │ └────────▲──────────┘ │ │ ③ 在线 → 窗口切到 DSH UI │ │ │ │ ④ 失败 → UI 展示教程 10 步引导 │ │ │ └─────────────┬───────────────┘ │ │ │ loadURL │ │ ┌─────────────▼───────────────┐ ┌─────────────────┴────────┐ │ │ 启动页（本地 HTML） │ 在线后 │ DSH Web UI │ │ │ 状态卡片/端口/指引/日志 │ ──────► │ http://127.0.0.1:3080 │ │ └─────────────────────────────┘ └──────────────────────────┘ └────────────────────────────────────────────────────────────────────────┘

三档启动策略（按可用性自动降级）：

| 档位 | 触发 | 行为 |
| A 自动拉起 | 服务离线 | 主进程探测 dsh 可执行文件 → spawn dsh web（失败回退 node --expose-internals <dsh>/lib/bin.js web）→ 轮询端口 40s |
| B 轮询接管 | 拉起后 | 每秒探测端口，就绪后窗口自动 loadURL 到 DSH UI |
| C 手动降级 | spawn 被鸿蒙沙箱拦截（EACCES 等） | UI 折叠面板展示教程 10 步引导；用户手动 dsh web 后点击「重新检测」自动进入 |

3. 目录结构

Deepseek_Harness/
├── dsh-app/ # ★ Electron 应用（本方案核心交付物） │ ├── package.json # 应用定义（无运行时依赖，产物干净） │ ├── main.js # 主进程：服务检测/拉起/轮询/窗口/IPC │ ├── preload.js # contextBridge 安全桥 │ └── renderer/ # 启动页 UI（状态/端口/指引/日志） │ ├── index.html │ ├── styles.css │ └── renderer.js ├── build-config/ │ └── ohos/ │ └── build-hap.js # ★ 一键打包脚本（骨架拉取+产物拷贝+assembleHap） ├── ohos_hap/ # ohos_electron_hap 骨架（脚本自动克隆） │ └── web_engine/src/main/resources/resfile/resources/app/ ← dsh-app 产物拷贝处 ├── entry/ AppScope/ … # 原有 ArkTS 模板工程（与本方案无冲突，可保留或删除） └── README.md

4. 环境准备

4.1 鸿蒙 PC / 2in1（运行端）—— 安装 DSH（教程摘要）

1. 安装 Harmonybrew：https://harmonybrew.atomgit.com/
brew install -y ohos-sdk devel-base llvm-gcc-compat cmake uname-is-linux
重开终端，确认 uname -a 显示 Linux

2. 安装 Node + DSH 到独立目录
brew install python3 node
npm config set prefix "$HOME/.npm-global"
export LD_PRELOAD=$HOME/.harmonybrew/opt/uname-is-linux/lib/libuname.so
npm install -g @deepseek-ai/dsh --verbose

3. koffi 签名（否则 Permission denied）
f="$HOME/.npm-global/lib/node_modules/@deepseek-ai/dsh/node_modules/koffi/build/koffi/openharmony_arm64/koffi.node"
binary-sign-tool sign -inFile "$f" -outFile "$f" -selfSign 1

4. 补 sharp + --expose-internals + 硬链接补丁 + ~/.dsh 目录迁移完整步骤见附录 A（或帖子原文）

4.2 开发机 —— 打包 HAP

| 依赖 | 版本 | 用途 |
| DevEco Studio | 4.0+（推荐 5.x/26） | 构建 HAP、自动签名 |
| HarmonyOS SDK | API 10+ | 编译 |
| Node.js | 16+ | 运行打包脚本 |
| 华为开发者账号 | — | 自动签名 |
| git | — | 克隆骨架 |

5. 使用

5.1 本地调试（普通桌面环境）

cd dsh-app
npm install # 安装 electron（仅开发期）
npm start # 桌面模式运行，验证主进程/UI 逻辑

5.2 打包 HAP

一键：自动克隆骨架 + 拷贝产物 + 构建（需已安装 DevEco/鸿蒙 SDK）
node build-config/ohos/build-hap.js

或分步：
node build-config/ohos/build-hap.js --pack-only # 只拷贝产物
然后用 DevEco Studio 打开 ohos_hap/ 目录 → Build > Build Hap(s)/APP(s) > Build Hap(s)

产物位置：ohos_hap/electron/build/default/outputs/default/electron-default-signed.hap

首次构建必须签名：DevEco Studio 中 File > Project Structure > Signing Configs > Automatically generate signature（登录华为账号）。若改过 bundleName（ohos_hap/AppScope/app.json5），必须重新生成签名。

5.3 安装到鸿蒙 PC

hdc app install electron-default-signed.hap

6. 鸿蒙适配要点（已内置）

| 项目 | 处理 |
| 平台检测 | process.platform 在鸿蒙 Electron 可能为 ohos（LX Music 实录实测不稳定），main.js 同时兼容 ohos + linux + 沙箱路径 /data/storage/el2/base/files 探测 |
| 硬件加速 | 鸿蒙下自动 app.disableHardwareAcceleration()（避免渲染冲突） |
| 用户数据目录 | 由鸿蒙 Electron 运行时自动映射到 /data/storage/el2/base/files |
| 权限声明 | 骨架 web_engine/src/main/module.json5 的 requestPermissions 需含：ohos.permission.INTERNET（访问 3080）、ohos.permission.RUNNING_LOCK（保持服务进程）、ohos.permission.GET_NETWORK_INFO |
| 多窗口 | 可选改 windowInfo: { type: 'floatWindow' } 变悬浮窗形态 |

7. 验证状态（2026-08-15 本机实测）

✅ 已在鸿蒙 2in1 真机验证：

| 项目 | 结果 |
| DSH 本体（Harmonybrew node 26.7 + koffi 签名 + bin.js shebang） | ✅ dsh web 启动成功，http://127.0.0.1:3080 返回 HTTP 200，完整 DSH Web UI 正常输出 |
| ~/.dsh 目录 | ⚠️ 曾失效（软链目标被清），已重建 /data/storage/el2/base/files/dsh 后恢复正常 |
| ohos_electron_hap 骨架 | ✅ gitcode 克隆成功，git-lfs 拉取 5 个运行时库（libelectron.so 160MB 等） |
| 打包脚本 --pack-only | ✅ 真机跑通，dsh-app 产物已拷贝进骨架 resfile |
| 权限声明 | ✅ 骨架自带 INTERNET / GET_NETWORK_INFO / RUNNING_LOCK / PREPARE_APP_TERMINATE |
| HAP 构建 | ✅ 完整打通：hvigor 6.26.2 + SDK 26 包装层 → ArkTS 编译通过 → ELF 打包工具产出 unsigned HAP → OpenHarmony 调试证书签名 → electron-default-signed.hap（186MB） |
| HAP 签名 | ✅ 使用 SDK 内置 OpenHarmony 调试证书（profile 生成 + sign-app），签名成功 |

❓ 仍待验证（需 DevEco 构建链）：

1. HAP 构建：本机未安装 DevEco Studio / hvigorw / hdc，assembleHap 无法执行。需在装有 DevEco Studio（4.0+）的机器打开 ohos_hap/ 构建并签名。
2. HAP 内 child_process.spawn 可用性：鸿蒙 Electron 兼容层未文档化。若 spawn 被沙箱拦截（EACCES/EPERM），自动降级到「手动启动指引」模式，功能不受影响。
3. 平台标记：DSH 内部若有 process.platform 判断，需确认兼容 ohos（LX Music 采用注入 platform 标记的方案，见附录 B）。

8. 常见问题

| 现象 | 处理 |
| App 提示「服务离线」且自动拉起失败 | 按启动页折叠指引操作，或直接终端跑 dsh web，再点「重新检测」 |
| 日志出现 Permission denied（koffi） | 按教程第 4 步签名 koffi.node |
| 启动页卡「正在拉起」超时 | 查看日志面板；常见为 node 不在 PATH / bin.js 缺 --expose-internals |
| HAP 构建报 SysCap / .so 缺失 | 骨架需完整 clone；确认 electron/libs/arm64-v8a 下 4 个 .so（libelectron/libffmpeg/libadapter/libc++_shared）齐全 |
| 海泰浏览器 403（非本应用场景） | 本应用内嵌 Web 组件无此问题（教程该问题仅影响普通浏览器） |

附录 A：DSH 在鸿蒙 PC 安装的完整补丁步骤（教程第 5-9 步）

5. sharp
cd "$HOME/.npm-global/lib/node_modules/@deepseek-ai/dsh"
npm install --no-save --no-package-lock --no-audit --no-fund @img/sharp-wasm32@0.35.3

6. bin.js 首行加 --expose-internals
sed -i 's@^#!/usr/bin/env node$@#!'"$HOME"'/.harmonybrew/bin/node --expose-internals@' \
"$HOME/.npm-global/lib/node_modules/@deepseek-ai/dsh/lib/bin.js"

7. 硬链接失败回退 rename（node 脚本打补丁，见帖子原文，约 30 行）

8. ~/.dsh 迁移到 f2fs 分区
rm -rf ~/.dsh && mkdir -p /data/storage/el2/base/files/dsh
ln -s /data/storage/el2/base/files/dsh ~/.dsh

9-10. 链接 dsh 到 harmonybrew bin 并启动 ln -s ~/.npm-global/bin/dsh ~/.harmonybrew/bin
dsh web # → http://127.0.0.1:3080

附录 B：注入鸿蒙平台标记（可选）

若 DSH 内部对 process.platform 有 win32/darwin/linux 分支判断，可在 main.js 拉起的子进程 env 中注入：

env: { ...process.env, PLATFORM_OHOS: '1' }

并排查 DSH 源码中对应分支；或参考 LX Music 实录：在鸿蒙 Electron 主进程入口统一改写 process.platform 判断逻辑。