这份详细的部署教程将指引您在 HarmonyOS (鸿蒙) 设备上完整运行 DeepSeek Harness (dsh)。这是一套完整的适配方案，解决了在鸿蒙系统上运行 dsh 时遇到的原生模块不兼容、文件系统限制、启动崩溃等核心问题。

整个部署流程分为几个关键步骤：安装 dsh、部署优化预设、应用关键补丁、安装可选依赖插件，以及启动与更新。

⚠️ 重要前提与声明

  • 适用环境：本方案针对 HarmonyOS 设备（特别是鸿蒙PC/2in1设备）设计，在标准 Linux/macOS/Windows 上不需要也不应使用这些补丁。
  • 安全声明：本仓库全部内容为纯文本/纯JavaScript配置与脚本，不删除、不加密、不外传你的数据，不注册系统服务、不要求 root 权限。所有写入操作仅发生在 dsh 安装目录与 ~/.dsh 用户配置目录内，完全可审阅、可逆卸载。
  • 交流与支持：项目交流 QQ 群：930088487。新手可查看在线安装教程。

📥 第一步：安装 dsh

在鸿蒙设备的终端中，选择一个工作目录（如 ~/dsh-test）并安装 dsh 核心包。

1
2
cd ~/dsh-test
npm install @deepseek-ai/dsh

安装位置可通过 DSH_DIR 环境变量覆盖。

⚙️ 第二步：部署“鸿蒙对话模式”预设

这些预设经过专门优化，能大幅提升 DeepSeek 的前缀缓存命中率（最高可达98%），从而显著降低成本和提高响应速度。同时，它们针对鸿蒙环境设计了特定的工作流。

  1. 复制预设文件：将本仓库的 presets/ 目录下的全部预设（共七套模式）复制到 dsh 的用户预设目录。

    1
    2
    mkdir -p ~/.dsh/.agent-presets
    cp -r presets/* ~/.dsh/.agent-presets/

  2. 设置默认预设（可选）：编辑 ~/.dsh/settings.yaml 文件，将默认对话模式设为您喜欢的预设（例如最强的 harmony-chat-promax）。

    1
    2
    agent-presets:
      default: harmony-chat-promax

    七套预设简介：

    • harmony-chat：基础极简模式。
    • harmony-chat-pro：缓存命中率极致优化。
    • harmony-chat-promax：六边形战士，在缓存、成本、交付能力、测试验证、集成闭环、共存防御间取得最佳平衡（最推荐日常使用）。
    • harmony-chat-ops：常驻后台任务管家，适合定时任务、目录整理。
    • harmony-chat-rampagemax：狂暴质量模式，不省token，只求极致质量，慎用（高消耗）。
    • harmony-kb：知识库专家，将工作区变为知识库，支持Obsidian双链笔记。
    • harmony-deveco：鸿蒙DevEco全链路开发大师，可驱动hvigor/ohpm/hdc完成编译安装闭环。

🩹 第三步：应用关键补丁

这是让 dsh 在鸿蒙上跑起来最关键的一步。补丁解决了原生模块加载、文件权限、硬链接等致命问题。

A. 启动补丁 (Startup Patch)
启动 dsh 时必须应用补丁文件，以禁用导致崩溃的原生依赖插件行。

  • Web 界面模式：使用 harmony.patch.yml。
  • Headless (无头/基准测试) 模式：使用 harmony-headless.patch.yml。

B. node_modules 源码补丁 (Source Patches)
这些补丁修改 dsh 核心代码，以绕开鸿蒙文件系统的特定限制。每次升级或重装 dsh 后，都需要重新运行此命令。

1
2
# 在仓库根目录下执行
node scripts/dsh-update.mjs patch

此命令会自动应用五个补丁，解决以下问题：

  • 凭据文件权限检查失败 (chmod 600 被拒)。
  • 会话持久化硬链接失败 (EPERM link)。
  • 权限预设下拉菜单消失 (sandboxMode 读取错误)。
  • 图片附件保存失败 (link 改 copy)。
  • 视觉模型未配置错误 (回退到主视觉模型)。

🔌 第四步：安装可选依赖插件（部分预设需要）

仅当您计划使用 harmony-chat-ops、harmony-kb 或 harmony-deveco 预设时，才需要安装对应的自定义插件。 这些插件需手动放置到两个位置（源码目录和profile软链目录），缺一不可。

A. 为 ops / kb 模式安装 dsh-tool-list (目录枚举工具)

1
2
3
4
# ① 复制源码到 dsh 基础 node_modules
cp -r plugins/@deepseek-ai/dsh-tool-list ~/dsh-test/node_modules/@deepseek-ai/
# ② 建立软链到 profile 层依赖树
ln -s ~/dsh-test/node_modules/@deepseek-ai/dsh-tool-list ~/.dsh/profiles/node_modules/@deepseek-ai/

B. 为 deveco 模式安装 dsh-deveco-bridge (DevEco工具桥接)

1
2
3
4
# ① 复制源码
cp -r plugins/@deepseek-ai/dsh-deveco-bridge ~/dsh-test/node_modules/@deepseek-ai/
# ② 建立软链
ln -s ~/dsh-test/node_modules/@deepseek-ai/dsh-deveco-bridge ~/.dsh/profiles/node_modules/@deepseek-ai/

dev_code 工具依赖本机运行的 DevEco Code 代理（默认 127.0.0.1:4096），使用前请确保已启动并配置好模型。

🚀 第五步：启动 dsh 服务

A. 启动 Web 界面 (推荐)
使用提供的脚本启动，它会自动处理补丁和探活。

1
sh scripts/dsh-web.sh

启动后，在浏览器中访问 http://127.0.0.1:3080。

手动启动等价命令（可放在 ~/.zshrc 中用于开机恢复）：

1
cd ~/dsh-test && node --expose-internals node_modules/@deepseek-ai/dsh/lib/bin.js --profile web --patch /path/to/harmony.patch.yml

B. 启动 Headless 模式（无人值守）

1
2
cd ~/dsh-test && node --expose-internals node_modules/@deepseek-ai/dsh/lib/bin.js \
  --profile headless --patch /path/to/harmony-headless.patch.yml "你的任务描述"

🔄 第六步：一键更新（推荐）

本仓库提供了一键更新脚本，能自动同步官方 dsh 更新、本仓库的预设/插件/补丁，并自动重启服务。

1
2
3
# 在仓库目录下执行
sh scripts/dsh-hm-update.sh          # 检查更新并执行
sh scripts/dsh-hm-update.sh check    # 仅检查状态，不更新

📱 可选：鸿蒙桌面客户端

项目在 client/ 目录下提供了一个基于 HarmonyOS NEXT ArkTS/ArkUI 构建的桌面客户端。您可以使用 DevEco Studio 打开 client/ 目录，构建并安装 entry-default-unsigned.hap 包，获得原生鸿蒙应用体验。

⚠️ 已知限制

  • 鸿蒙无 systemd/cron 等开机自启服务。推荐在鸿蒙设置中将“终端”App设为开机自启，并在 shell 配置文件中加入探活脚本（如 dsh-web.sh）实现自动恢复。
  • Agent 无法真正执行 Shell 命令（bash被禁用），只能通过文件编辑、网页检索等方式工作。
  • 无法切回官方的 standard/code 预设，因为它们依赖被禁用的原生能力。
  • 依赖原生二进制（如 node-pty、koffi）或 WASM 运行时的插件无法运行。

总结：核心就是 npm安装dsh → 部署预设 → 运行补丁脚本 → 用带补丁的方式启动。如果主要用AI编程和知识管理，推荐默认使用 harmony-chat-promax 预设。