shizhonggang/dsh-harmonyos

dsh-harmonyos

在鸿蒙 HarmonyOS PC 上安装 DeepSeek Harness（AI 助手）的傻瓜教程 + 全部补丁。
不需要懂 git、不需要懂“补丁”，跟着下面三步走就行。

| 你的情况 | 是否适用 |
|---|---|
| 鸿蒙 PC（HarmonyOS / OpenHarmony），想装上 AI 助手 dsh | ✅ 就是为你写的 |
| Windows / macOS / 普通 Linux 电脑 | ❌ 官方直接装即可，不需要本教程 |
| 已经装好 dsh，只是报错 | ✅ 直接看 报错排查表 |

🛠️ 第 0 步：准备环境（先查缺不缺，30 秒搞定）

装 dsh 之前，机器需要：Node.js ≥ 22（自带 npm）、clang 编译器、外网。先照抄下面的命令查一遍：

node --version && npm --version && clang --version

- 三个都显示了版本号 → 环境齐了，直接进入 第一步安装
- 有报 command not found → 缺东西了，打开 环境准备教程，
照着装（写了鸿蒙上怎么装 node / clang / git、怎么配 PATH、怎么验证）

跳过这步硬装，会在安装到一半时报“缺 node / 缺 clang”，到时候再回来补也行（安装脚本可反复跑）。

🚀 第一步：安装（复制一行命令）

首选（零门槛，不需要 git）：在终端里粘贴下面这一行，回车：

curl -fsSL https://raw.githubusercontent.com/shizhonggang/dsh-harmonyos/main/scripts/bootstrap.sh | sh

它会自动完成：下载本仓库 → 解压 → 7 步全自动安装（下载 dsh → 编译终端组件 → 打补丁 → 装启动器）。
每完成一步会打印 ==> 1/7、==> 2/7…… 到 ==> 6/7。

换版本：DSH_VERSION=0.1.0-rc.7 curl -fsSL https://raw.githubusercontent.com/shizhonggang/dsh-harmonyos/main/scripts/bootstrap.sh | sh

备选（想自己看看里面有什么）：

git clone https://github.com/shizhonggang/dsh-harmonyos.git
cd dsh-harmonyos
DSH_VERSION=0.1.0-rc.7 ./scripts/install.sh

方式 C：Homebrew 安装（装完自带安装/升级/补丁/启动命令）

标准 Homebrew（macOS / Linux，tap 在 GitHub）：
brew tap shizhonggang/dsh-harmonyos
brew install dsh-harmonyos

harmonybrew（鸿蒙版 Homebrew）：tap 已镜像到华为 AtomGit（国内直连快）：
brew tap m0_72197678/dsh-harmonyos
brew install dsh-harmonyos

说明：formula 自 v0.1.1 起从 AtomGit 国内直链下载安装包（不再走 GitHub），国内用户无需梯子。

harmonybrew 装 formula 前要让它能看到编译器（它只认 /usr/bin 或 ~/.harmonybrew/bin 下的 clang）：
ln -sf /data/service/hnp/bin/clang ~/.harmonybrew/bin/clang
ln -sf /data/service/hnp/bin/clang++ ~/.harmonybrew/bin/clang++
（你的 clang 路径可能不同，command -v clang 查看；有 /usr/bin/clang 则跳过）

装完直接用：dsh-install（首次安装）→ dsh-web / dsh-tui（启动），
升级用 dsh-upgrade，裸 npm install 后补丁被清就用 dsh-patch 一键重打。

安装中如果卡住或报错，先看下面的 安装详解 对应步骤，再查 报错排查表。

✅ 第二步：确认装好了

装完后你的系统里多了两个命令：

图形界面 dsh-web
sh
dsh-web

然后浏览器打开 http://127.0.0.1:3080。能看到网页 = 成功。
（也可以验证：另开一个终端敲 curl http://127.0.0.1:3080，返回网页内容就是成功）

终端界面 dsh-tui
sh
dsh-tui

能进入交互界面、能正常输入中文 = 成功。

两个至少有一个能开就算装好。都没开？去 报错排查表。

👋 第三步：开始用

- 图形界面：浏览器里新建对话，和 AI 聊天、让它执行命令。模型设置不了的话检查配置（详见本仓库 docs/）。
- 终端界面：输入 /help 看命令；TUI 没装的按提示执行：
dsh plugin --profile dsh-tui add @deepseek-harness-tui/dsh-tui@latest
- 重启：改完配置或升级完，先停掉旧进程再启（报 EADDRINUSE 端口占用时同理）。

📖 保姆级安装详解（每步在干什么）

上面的安装帮你自动跑完了 7 步。这一节是写给“想搞明白/出问题了”的你——每一步是什么、失败了怎么办：

| 步骤 | 在干什么（大白话） | 失败了看这里 |
|---|---|---|
| 0/7 环境预检 | 检查有没有 node / npm / clang。没有会直接告诉你 | 按提示装对应软件，再重跑（脚本可反复跑） |
| 1/7 下载 dsh 本体 | 从官方源下载 dsh 程序（指定官方源是为了避开可能滞后的镜像） | 网络不通？检查外网；提示“装到旧版”→ 确认命令里带 --registry=https://registry.npmjs.org |
| 2/7 编译 node-pty | dsh 执行命令需要的“模拟终端”组件，鸿蒙没现成的，现场用 clang 编译 | 报编译错基本是缺 clang：clang --version 看有没有 |
| 3/7 装 sharp 备用版 | 图片处理组件换 WASM 版（鸿蒙没原生版，功能一样、稍慢） | 一般不会失败；失败直接跳到步骤 4 不影响核心 |
| 4/7 打补丁 | 修改 dsh 里 4 处“不认鸿蒙”的代码（自动、幂等、可重跑） | 报 [fail] 未匹配到目标行 = 你的 dsh 版本和补丁基线（0.1.0-rc.7）不一致，去 GitHub 提 issue |
| 5/7 装启动器 | 生成 dsh-web / dsh-tui 两个命令 | 检查 ~/.local/bin 是否在你的 PATH 里 |
| 6/7 验证 | 打印验证方法（就是上面第二步） | — |

🆘 报错排查表（照表抄）

| 报错 / 现象 | 原因 | 解决办法 |
|---|---|---|
| Error loading shared library ... Permission denied | 预编译模块在鸿蒙上加载被拒（缺签名） | 用 binary-sign-tool sign -selfSign 1 补签，见 docs/install-issues.md |
| EACCES: permission denied, link ... | 鸿蒙禁止硬链接 | 跑 patches/apply-patches.sh（补丁③ 把他换成 rename） |
| PTY shell exited during startup | 找不到 /bin/bash | 跑 patches/patch-terminal-bash.sh（补丁② 换成鸿蒙真实 bash 路径） |
| terminal inspection is unsupported on platform openharmony | 上游不认鸿蒙平台 | 跑 patches/patch-subprocess-local.sh（补丁①） |
| --expose-internals is required for HMR service | 启动参数缺了 | 用本仓库的 dsh-web / dsh-tui 启动器（已自动带上） |
| Cannot find the native Koffi module | koffi 组件缺原生模块 | 跑 patches/apply-patches.sh（补丁④ 打替身） |
| sharp 报 Could not load using openharmony-arm64 runtime | sharp 无鸿蒙版 | 装 @img/sharp-wasm32（安装脚本第 3 步已处理） |
| EADDRINUSE 127.0.0.1:3080 | 端口被旧实例占用 | 停掉旧进程再启动；或用 --patch 换端口 |
| 装到的总是旧版本 | 华为 npm 镜像滞后 | 命令里加 --registry=https://registry.npmjs.org |
| 升级后补丁全没了 | npm 重装会清掉补丁（正常现象） | 重跑 patches/apply-patches.sh，或直接用 scripts/upgrade.sh 升级 |
| 不会用 git / 不想 clone | — | 用零门槛命令：curl -fsSL https://raw.githubusercontent.com/shizhonggang/dsh-harmonyos/main/scripts/bootstrap.sh \| sh |
| brew 报 cannot be installed from bottle... Install Clang | harmonybrew 只认 /usr/bin/clang 或 ~/.harmonybrew/bin/clang 两处编译器 | 软链：ln -sf  ~/.harmonybrew/bin/clang（+ clang++）；或 brew install gcc |
| brew 装的时候下载很慢/卡住（老版本 formula） | 旧 formula 从 GitHub 拉包，国内可能不通 | 重新 tap 拿到新 formula：brew untap m0_72197678/dsh-harmonyos && brew tap m0_72197678/dsh-harmonyos && brew reinstall dsh-harmonyos（v0.1.1 起已改 AtomGit 国内直链） |

上面的命令都在仓库的 patches/、scripts/ 目录里，全部幂等——想跑几次跑几次，不会打坏。

🔄 升级 dsh
sh
DSH_VERSION= ./scripts/upgrade.sh

upgrade.sh 会自动：备份旧版 → 装新版 → 重编 node-pty → 重装 sharp 备用版 → 重新打全部补丁 → 提示验证。

怎么查最新版本号：npm view @deepseek-ai/dsh dist-tags --registry=https://registry.npmjs.org
看 next 标签（官方先发 next、后发 latest）。

📌 已知小坑（小 bug 记录）

| 小坑 | 状态 |
|---|---|
| harmonybrew 编译器检测太死板（只认 /usr/bin 或 ~/.harmonybrew/bin 的 clang） | ✅ 已绕过：软链即可，见方式 C |
| v0.1.0 的 formula 下载源在 GitHub（国内慢/不通） | ✅ 已修复：v0.1.1 起改为 AtomGit 国内直链，真机 3 秒装完 |
| TUI 流式输出向上翻页有残影（上游 dsh-TUI 已知问题，非本仓库） | ⏳ 等上游修，不影响使用 |
| sharp 走 WASM 兜底，比原生略慢 | ⏳ 平台限制，无原生鸿蒙版 |
| 官方 deepseek-harness 暂不收外部 PR、Issues 已关闭 | ⏳ 反馈走 Discussions（草稿见 docs/upstream-feedback.md） |

📚 附录（写给想搞懂的人）

它适配了什么

通俗版：鸿蒙不认 dsh 的进程管理 → 告诉它“鸿蒙按 Linux 处理”；鸿蒙没有 /bin/bash → 改路径；
鸿蒙禁止硬链接 → 改成重命名；几个原生组件没鸿蒙版 → 能编的现场编、不能编的打替身。

技术版：

| 补丁/适配 | 目标文件 | 脚本 |
|---|---|---|
| openharmony 平台分支 | @deepseek-ai/dsh-subprocess-local/lib/index.js | patches/patch-subprocess-local.sh |
| shellPath 默认值 | @deepseek-ai/dsh-terminal-bash/lib/index.js | patches/patch-terminal-bash.sh |
| link→rename | dsh-session-persistence-jsonl / dsh-attachment-local | patches/patch-link-rename.py |
| koffi 3.1.5 stub | koffi/src/koffi/index.js | patches/koffi-index-stub.js |
| lightningcss 降级（源码 build 场景） | 源码仓库 | patches/patch_lightningcss.py |
| node-pty 现编 / sharp-wasm32 / --expose-internals | npm 安装层 | scripts/install.sh |

平台硬约束（给二次开发的人）

process.platform === 'openharmony'；全盘禁硬链接（原子写用 rename）；/tmp 只读（用 $TMPDIR）；
无 glibc（musl only）；无 gcc（clang 15）；预编译 .node dlopen 被拒（需 .codesign 补签或现编）；
fork 慢约 14 倍；沙箱无后端 → 必须 DSH_PERMISSION_MODE=danger-full-access。
详见 docs/platform-notes.md。

目录结构

dsh-harmonyos/
├── README.md               ← 本文件（教程）
├── LICENSE                 MIT（含上游归属声明）
├── docs/
│   ├── environment-setup.md   环境准备教程（node / clang / git 怎么装）★小白先看
│   ├── install-issues.md      极详细的技术排障全记录（含 rc.7 升级记录）
│   ├── platform-notes.md      平台硬约束速记
│   └── upstream-feedback.md   给上游的反馈帖草稿（中英双语）
├── patches/               幂等补丁套件（见上表）
└── scripts/
├── bootstrap.sh       零门槛一键安装（curl | sh 用的就是它）
├── install.sh         全新安装（7 步，带环境预检）
├── upgrade.sh         升级 + 自动重打补丁
└── launchers/         dsh-web.sh / dsh-tui.sh 启动器

上游贡献现状（2026-08-18 核实）

官方 deepseek-ai/deepseek-harness 暂不接受外部 PR，官方 Issues 已关闭，只有 GitHub Discussions 可反馈。
本仓库 docs/upstream-feedback.md 是整理好的双语反馈帖草稿；源码级适配已放在
fork 的 harmonyos 分支（github.com/shizhonggang/deepseek-harness），等上游开放 PR 后使用。

许可

本仓库 MIT；补丁对象 DeepSeek Harness 为 MIT（© DeepSeek）；TUI 插件来自社区项目
@deepseek-harness-tui/dsh-tui（github.com/ccch1mneyyy/dsh-TUI）。

_卡住了？看排查表；排查表没有的，去 https://github.com/shizhonggang/dsh-harmonyos/issues 提 issue（带上报错原文）。_