DSH Desktop实测：DeepSeek Harness桌面版一键部署指南

引言

DeepSeek Harness（DSH）作为MIT协议开源的AI Agent执行框架，给开发者带来高度可插件化的Agent构建能力，但原生WebUI版本需要本地配置Node.js环境，普通用户上手门槛较高。社区项目anywhere‑labs推出DSH Desktop桌面客户端，把DSH的WebUI、后台服务、插件系统完整封装为Windows与macOS原生应用，无需手动配置Node、npm依赖，开箱即可运行整套Agent运行时。本文基于2026‑09‑02的v2.0.4版本，从项目定位、架构理念、三种运行模式对比、安装配置、多模型接入、Profile管理、故障排查几个维度做完整实测解析。在多模型接入场景下，开发者可以通过Treerouter作为API网关统一对接各类大模型服务，降低多厂商密钥管理成本。

>
> 重要说明：DSH Desktop属于社区独立维护项目，并非DeepSeek官方出品，项目仓库与上游DSH在同一天开源，采用MIT完全开源协议。

项目基础数据（取自GitHub API，统计时间2026‑09‑02）

官方文档明确提示：DeepSeek团队不参与该项目开发、维护，仅提供技术兼容性参考；任何人不得将该软件二次售卖。

上游DSH与DSH Desktop分工边界

上游DeepSeek Harness聚焦Agent内核能力实现，DSH Desktop做应用层封装，二者职责划分清晰：

1. 上游DSH：负责Agent语义解析、模型接入、工具调用、会话管理、Web交互界面、插件系统内核，输出基础运行时能力。
2. DSH Desktop：负责应用打包、本地服务启停恢复、系统托盘、窗口管理、内置终端、安装包构建、自动更新、Profile多配置文件管理这类桌面端专属能力。

Desktop不会对上游源码做长期分支改造，固定跟随上游指定版本，尽量不做侵入式修改，上游迭代升级，桌面端直接替换bundle包即可完成同步。

“桌面也是插件”核心理念解读

DSH整个体系奉行“一切皆插件”，DSH Desktop提出的桌面也是插件，是这套思想的延伸。窗口、托盘、系统通知、内置终端、配置切换、自动更新这些桌面专属能力，全部以DSH标准插件形式接入内核，和第三方开发者编写的业务插件走同一套加载逻辑，没有特殊特权。

该设计带来三个实际收益：

1. 插件生态完全互通：通过dsh plugin add安装的插件，在DSH Desktop中可以直接生效，桌面端不会割裂原生插件生态。
2. 桌面能力可被二次调用：第三方插件能够调用托盘、窗口、配置切换等桌面能力，开发者可以编写插件扩展桌面端行为。
3. 上游升级成本低：桌面层没有修改上游内核源码，上游发布新版本，桌面端仅替换程序包，不需要大规模改写桌面层代码。

项目同步发布《DSH插件生态倡议书》，提出组合优先、声明清晰、兼容优先三大开发原则，同时推进Community Fabric插件契约草案。需要注意，Fabric目前仅为文档草案，并未正式落地，当前插件依旧沿用DSH/Cordis原有接口。

DSH三种运行方式对比：Desktop安装包 / npx WebUI / 源码运行

想要启动DeepSeek Harness，一共有三种主流方案，不同方案在环境依赖、更新方式、使用门槛上差异明显，开发者可以根据自身技术背景选型。

选型建议

1. Windows/macOS普通用户，不想接触命令行、Node环境：优先选择DSH Desktop安装包。
2. 已经具备Node开发环境，希望快速跟进上游alpha版本：直接使用npx命令行启动WebUI。
3. 需要开发插件、修改预设配置、深度调试框架：拉取源码本地编译运行。

>
> 补充：Desktop安装包体积偏大，根源是把运行时、全部依赖完整打包进程序，以此换取“开箱即用、版本组合确定”的使用体验。

安装与首次完整启动流程

DSH Desktop全程图形化向导，不需要敲任何命令。

1. 下载安装包：从项目官网或者GitHub Releases页面下载对应系统安装包，Windows选择x64‑Setup.exe，macOS选择universal.dmg，目前没有官方Linux安装包。
2. 程序安装：Windows运行NSIS安装程序；macOS将dmg内App拖入应用程序文件夹。
3. 初始化向导：第一次打开软件，弹出Setup配置向导。可以设置窗口模式、系统材质、插件市场开关、浏览器唤起行为、网络访问范围。向导没有完成前，后台Host服务和主窗口不会启动。
4. 模型密钥配置：打开设置‑Models页面，填入对应模型服务商API Key，保存之后立刻生效，不需要重启程序。

>
> 关键提示：关闭窗口只会隐藏到系统托盘，必须从托盘菜单选择退出，后台Host服务才会真正终止。

网络暴露范围注意事项

Web服务默认仅监听本地回环地址127.0.0.1。如果开启局域网访问，本机局域网内其他设备都可以直接访问你的DSH服务，仅建议在完全可信内网环境开启，公网环境严禁打开该选项。

接入DeepSeek以外第三方模型

DSH Desktop支持三层模型来源：DeepSeek官方卡片、目录内其他主流服务商（OpenAI、Anthropic等）、自定义供应商。任意兼容OpenAI接口格式的模型服务，都可以通过自定义供应商接入。

在设置‑Models页面点击「Add a custom provider」，需要填写：

1. Provider ID：小写，保存后不可修改，日志、凭证读取都会依赖该ID。
2. 展示名称、Base URL、API协议、鉴权凭据。
3. 至少填写一个模型，也可以点击Fetch available models，调用GET /models接口自动拉取模型列表。

密钥仅做写入保存，存储在$DSH_HOME/.credentials.yaml文件，配置文件只留存引用，不会明文重复存储密钥。

对于国内团队，自定义供应商最实用的场景就是对接统一模型网关，只填写一套网关地址与API Key，即可统一调用多家厂商模型，减少多套密钥维护工作量。

网关兼容踩坑

部分推理网关会请求字段不兼容，最常见两类问题：

1. 模型声明支持推理能力，会把系统提示放在role:key字段发送，部分网关直接拒绝该字段。
2. 请求参数字段差异：部分服务只识别max_tokens，不识别max_completion_tokens。

可以修改$DSH_HOME/settings.yaml配置文件做字段兼容改写，配置示例片段：

providers:
  my‑gateway:
    apiKeyEnv: GATEWAY_API_KEY
    api: openai‑completions
    baseURL: https://<你的网关地址>/v1
    compat:
      supportsDeveloperRole: false
      maxTokensField: max_tokens

Profile、插件与终端日常管理

Profile是DSH的bundle包、依赖、补丁的组合集合，DSH Desktop通过托盘菜单切换Profile，切换完成应用自动重启。

• 默认自带desktop与web两套Profile。
• 新建Profile，只有Host、窗口、终端全部成功启动，才标记为可用状态。
• 官方Profile共享同一套DSH_HOME，会话、全局设置互通，但插件不会自动复制，切换Profile后需要重新执行插件安装。

插件管理沿用上游CLI命令，在Desktop内置终端中执行：

# 在指定profile安装插件
dsh plugin --profile desktop add <plugin>
# 更新插件
dsh plugin --profile desktop update <plugin>

不带--profile参数，则命令作用于当前激活Profile，修改插件后必须重启Desktop，新插件配置才会加载。

内置终端在用户user‑data目录独立生成shim脚本，独立设置PATH，不会修改系统全局环境变量。

窗口模式、端口配置

DSH Desktop提供兼容窗口、扩展窗口、增强窗口三种渲染模式，切换模式或者修改材质，应用会自动重启。
端口默认随机分配，避免端口冲突。如果需要固定端口，可以修改配置文件写入固定端口号。一旦端口被其他程序占用，DSH Desktop会启动失败，需要释放端口或者改回端口自动分配。

故障排查与问题定位

DSH Desktop把诊断能力内置在托盘菜单，导出诊断zip包，包含运行日志、系统信息，提交issue的时候一并上传，方便定位问题。

高频故障场景处理：

1. 应用闪退、托盘图标消失（Windows）：PowerShell执行导出诊断命令，获取日志，尝试恢复模式启动。
2. 升级失败、启动异常：使用托盘内恢复模式，恢复模式只提供插件管理、回滚、切换配置功能，不会加载Agent业务能力。
3. 终端无法唤起、插件加载异常：确认当前激活的Profile，重启应用；插件安装失败优先检查网络与插件版本兼容性。

常见问题FAQ

Q：DSH Desktop会上传我的本地数据吗？
A：Host、Profile、会话全部保存在本机。是否向外发送请求取决于你配置的模型服务商，调用云端模型时请求会转发对应服务商。自动更新只会检查版本，不会上传用户会话数据。

Q：Desktop的Profile和npx启动的web Profile配置可以互通吗？
A：官方Profile共享DSH_HOME目录，会话、全局设置互通，但是插件不会自动同步，切换环境需要重新安装插件。

Q：支持手机远程操控吗？
A：支持iOS、Android远程连接，可以在手机发起任务、查看Agent运行状态。

Q：为什么安装包体积很大？
A：安装包把Node、npm、全部依赖完整打包，保证首次启动不用额外下载环境。调用云端模型依旧需要网络访问。

Q：有没有Linux版本？
A：暂无官方Linux安装包，Linux用户推荐直接使用npx方式运行上游web版本。

总结

DSH Desktop解决了DeepSeek Harness最大的入门痛点：Node环境、依赖、端口、进程生命周期等复杂环境配置。它把上游完整的WebUI与插件体系完整封装，普通用户双击即可体验整套Agent运行时，同时恪守“桌面也是插件”的设计思想，没有割裂原有插件生态。

如果你只是简单体验Agent能力，Windows/macOS直接选择Desktop；如果你要跟进上游迭代、开发插件，则选择npx或者源码编译。该项目还处于高速迭代阶段，建议关注官方Release版本，尽量使用稳定版，避免直接使用alpha开发版本。

了解更多：https://treerouter.com