DeepSeek Harness 桌面端安装教程：官网下载、4种模式与安全边界

DeepSeek 官方在 2026 年 8 月开源的智能体框架叫 Harness（命令行简写 dsh）。本文围绕 deepseek.com/harness 上的这个官方工具，写一份从下载、安装、配置到插件、自动化、安全边界和报错排查的完整攻略，主线是桌面端——也就是那个可以双击安装、不用装 Node.js、不用开终端的官方客户端。

这篇攻略里的版本号、安装包体积、系统要求和仓库数据，都在 2026 年 11 月 9 日回到官方页面、npm registry 和 GitHub 仓库逐个核过。所有结论都标明出处与核对口径，方便你自己复算。

一句话前提：Harness 目前是开发者预览版，官方 README 用加粗写着「未来将出现破坏兼容性的变更」。想拿来干长期稳定的活，请先读文末的版本与安全两节。

一、Harness 到底是什么

按官网里的自我介绍：DeepSeek Harness 是 DeepSeek 开源的 harness 架构，基于 Cordis 的「一切皆插件」架构构建，既可以是桌面应用，也可以通过代码启动为网页。它不是聊天机器人，也不是某个模型的网页壳，而是一个让 Agent 能读写文件、跑命令、装插件、定时干活的运行时框架。

官网把它能做的事归成五类：辅助日常工作（整理资料、分析表格、撰写文档、制作汇报）、写代码改仓库（理解项目、修复问题、开发功能、运行测试）、查资料核对信息（搜索、交叉查证、标注来源）、处理耗时任务（脚本、批量处理、后台执行并随时查看进度）、安装插件扩展能力。

首页给的示例任务很能说明定位：「生成 Q3 数据汇总 PPT」「准备明天评审会的议题清单」「给销售报表补上同比/环比列」「数据分析项目」「DSH 插件开发」——都是要动文件、动工具的多步任务，不是问答。

二、三条上手路径怎么选

官网把入口分成两条（下载桌面端、命令启动），加上仓库里的源码安装，实际有三条路。它们跑的是同一套 dsh，区别只在宿主形态。

🔺 Node 版本是变化最快的一项。截至 2026-11-09，npm 上 @deepseek-ai/dsh 的 latest 指向 0.2.2-rc.1，其 engines.node 要求 >=24.9.0。旧教程里写的「^22.19.0 或 >=24.0.0」是 10 月的口径，照抄会直接装不上。装之前用 node -v 确认，或直接走桌面端绕开这一整条依赖链。

三条路径的能力基本一致，桌面端没有功能阉割。桌面应用本质是完整 dsh Web 应用外面的一层 Electron 壳：Electron 以 RunAsNode 子进程启动共享的 profile runner，再从 dsh-app://app/ 加载打包好的 Web 入口。真正要纠结的只有「要不要装 Node」「要不要开终端」「要不要自己管浏览器」这三点。

三、官网下载：两个安装包与架构限制

官方预览页目前只放出两个桌面包，地址都在 download.deepseek.com/desktop/ 下。2026-11-09 用 HTTP HEAD 实测（响应头 content-length 与 last-modified）：

文件名里的 latest 会随版本滚动，不必去记具体版本号，也别从第三方站下旧包。两个包都在 270–295 MB 上下，原因不是安装器臃肿，而是内置了完整的 Node 运行时和一份 pnpm 分发包——这正是它不需要你预装 Node.js 的代价。

架构限制要看清楚：macOS 只有 arm64（M1 及之后的 M 系列），Intel Mac 没有对应包；Windows 只有 x64，ARM 版 Windows 不在支持范围。仓库文档还提到，在 win32-arm64 宿主上未打包启动虽然能成功，但载荷仍是 x64，工作区依赖工具可能因架构校验被拒。这两类机器建议直接走 npx 或源码路径。

四、安装与首次启动：逐步走

macOS：双击 .dmg，把应用拖进「应用程序」文件夹即可。Windows：运行 .exe，按安装向导走完，安装器会在应用仍在运行时提示先从系统托盘退出。

首次启动会走一段引导：欢迎页、介绍可用额度、让你选用途（偏编程还是偏日常办公）、以及选择工作过程的展示方式。中途退出可以继续，不会从头再来。引导结束后进入工作区，主界面按「新会话 / 插件 / 自动化任务 / 工作区」组织，默认工作区叫「默认工作区」。

几个桌面端特有的行为，提前知道能省掉不少困惑：

• 不占 3080。桌面端默认监听系统分配的端口，不会和 npx 起的 Web UI 或系统保留端口冲突；需要固定端口时可以在 profile 里 patch webserver.config.port。
• 关窗口不等于退出。macOS 点关闭按钮或按 ⌘W、Windows 点 × 都只是隐藏窗口，页面与 Host 继续运行，正在跑的任务不受影响；macOS 从 Dock 图标或 dsh://open 找回，Windows 从托盘找回。Windows 首次隐藏前会弹一次确认。
• 退出前会查任务。走正常退出流程时，应用会先问 Host 有没有运行中的 Agent、排队消息、后台任务或已挂的定时提醒，有就弹框确认。所以别在长任务中途强退。
• 命令行是可选加装的。应用菜单里的「管理 dsh 命令…」提供安装 / 修复 / 移除，复用桌面端自带的运行时。macOS 会建 /usr/local/bin/dsh，Windows 注册到当前用户 PATH；装完开一个新终端跑 dsh --version 验证。卸载桌面端之前，先在这里点「移除」，卸载程序不会替你清掉这条注册。

五、npx 与源码：另两条路径

想快速试、且机器上有 Node，官网给的命令只有一行：

npx @deepseek-ai/dsh web

这条命令默认在 http://127.0.0.1:3080 启动 Web UI，本机启动时会自动用默认浏览器打开；通过 SSH 启动时只打印宿主机 URL（本地转发地址由 SSH 客户端或编辑器持有）；加 --no-open 可以只跑服务不开浏览器。仓库 README 里的源码路径是四步：

git clone https://github.com/deepseek-ai/deepseek-harness.git → cd deepseek-harness → pnpm install → pnpm run build → pnpm dsh web。其中 pnpm run build 负责准备仓库产物，pnpm dsh web 直接用这些产物、不会重新构建。

更细的模型配置、反向代理发布、Python SDK 和 CLI 模式，官方文档站有单独页面；站内另有一篇专门拆过 npx 与源码构建这两条 Web 路径，本文不重复展开。

六、首次配置：模型、密钥与凭据

首次进入 Web UI，官方快速开始给的顺序是三步：配置模型 → 选择工作区 → 运行任务。模型这步在设置 → 模型里完成，改动在下一次请求时生效，不需要重启服务。

密钥是只写的：保存后页面只会拿到脱敏描述符，永远拿不到明文。它实际存在 $DSH_HOME/.credentials.yaml，设置页只保留一个凭据引用。用默认端点时，DeepSeek 的模型列表跟随官方 API 发布，首次需要模型时加载、使用期间约每十分钟后台刷新，加载失败回退内置模型；在「自定义设置」里改了「模型目录」就不再跟随，点「恢复默认模型」可重新跟随。

不想用 DeepSeek 自家模型也可以。添加模型提供商里可选内置的第三方提供商，列表显示的是提供商 ID，例如 anthropic、openai、Kimi 对应的 moonshotai、GLM 对应的 zai，填密钥保存即可；密钥留空时会用已保存凭据，或尝试读环境变量，页面会用绿色/黄色提示标明检测状态（检测只查变量是否存在，不验证凭据、不测连接）。

中转站、公司网关或自建服务器走自定义模型 API：填小写 Provider ID、基础 URL、API 协议和至少一个模型。协议必须选网关实际在用的那一种，共三种——OpenAI Chat Completions（存为 openai-completions）、OpenAI Responses（openai-responses）、Anthropic Messages（anthropic-messages）；一个提供商只能一种协议，网关同时提供两种就建两个提供商。Provider ID 是永久的，请求、已保存会话、模型默认值和凭据引用都在用它，改名字只能新建一个再删旧的。

关于账号登录：桌面端文档把「原生账号登录尚未接入、登录按钮禁用」列在已知限制里，同时又描述了走系统浏览器的 PKCE 登录流程——这类能力在预览期是逐版本放开的。遇到登录不可用或按钮是灰的，直接用 API Key 这条路，不影响后续功能。另外，网页搜索的凭据规则在 0.2.2-alpha.2 改过：Search / Fetch 现在跟随 DeepSeek 模型路由取端点，旧的 baseURL、apiKeyEnv、apiKey 字段已移除（已保存的值能加载但被忽略），要固定端点得在 YAML 里设 searchBaseURL 与 searchApiKeyEnv（Fetch 对应 fetchBaseURL / fetchApiKeyEnv）。升级后网页搜索突然失效，先查这里。

七、工作区：新手最常卡住的一步

这一条值得单列。dsh 进程会把启动时所在的目录作为默认文件系统位置，而全新的 Web UI 在选中工作区之前不会有任何工作区，会话输入框直接不可用。点「选择工作区」，把你想让 Agent 操作的目录加进来并选中，输入框才会解锁。

桌面端是图形入口，不受「从哪个目录启动」的限制，但选工作区这一步照样要做。之后 Agent 可以读写工作区文件、运行命令、委派任务、维护计划；按当前权限策略需要审批的操作，Web UI 会先弹询问。官方给的第一条示例提示词是 Summarize this repository and identify its main packages.——先拿它验证工作区是否真的挂上了。

如果 Agent 反复说找不到文件，九成是工作区选错或没选，先回这里查，而不是去改模型配置。

八、四种会话模式与「一切皆插件」

dsh 的会话可以跑在几种不同的预设里，区别主要是给智能体多少自主权、用什么样的执行循环：

预览期这些预设的命名和入口会随客户端版本调整，以你眼前界面显示的为准；仓库里能看到 minimal-preset 快照、PTC 运行时与 Creator 插件管理各自的独立实现，说明它们是并存的几套运行配置，而不是四个营销标签。

「一切皆插件」是理解这个产品的钥匙，也是最容易被宣传话术盖过去的部分。架构文档写得很直白：产品里没有任何东西是特权内核，模型适配器、工具注册表、会话日志，以及 agent loop（智能体循环）本身，全部都是插件，每一个都能从配置里替换掉。扩展方式是插件挂到插件旁边，各项注册都是副作用、卸载时撤销，没有需要打补丁的地方。

运行中的 dsh 是一棵启动时按序叠加出来的插件树。profile 是存放在 Harness home 里的具名组装，列出自己叠放哪些 bundle，并保留用户自己的 cordis.patch.yml；随发行版交付的模板有 web、headless、sdk、sdk-minimal、acp 五个，其中 desktop 名称保留给 Electron 持有，CLI 会拒绝对它的启动和配置 dump 请求。想看自己这台机器实际启动了什么，跑 dsh --profile web --dump-config，打印出的每一行都能用自己的 patch 覆盖。

这套设计的直接后果是：dsh 不绑定 DeepSeek 的模型，它同时也是 DeepSeek 自己跑 Code Agent 评测的底座。换模型、换工具、换循环，都是配置层的事。

九、插件与「创造模式」

官网把「一切皆插件」放在能力列表第一条：安装现有插件，或在创造模式中通过对话创建插件，扩展工具、技能和界面。界面上能看到的插件类别包括官方、智能体团队、自动授权审查、自动化任务、语音输入、终端、Agent 循环、子智能体等，其中多项被标为「实验性」。

官网给了一个完整的创造模式演示：一句「帮我写一个番茄时钟插件」之后，Agent 加载 cordis-plugin-development 技能、读取 SKILL.md、判断悬浮层该用 shell.overlay、查询运行时 Slot 列表、写出 package.json 和 client.js、调用 plugin_manager · install_bundle 安装、再检查插件运行状态并修了一处代码，全程 5 分 24 秒，最后交付一个带「专注 / 短休息」界面的悬浮时钟。这是「用对话造工具」最直观的一个例子，也说明为什么插件权限必须认真对待。

插件来源要注意两点。第一，首次装插件且未配置源时，程序会优先寻找最优可访问的 npm 源，同时保留手动选择和私有源配置。第二，社区插件通过 GitHub 的 dsh-plugin topic 收录——这个话题标签只代表可发现，不代表经过安全审查。Creator 模式从 v0.2.1-alpha.1 起可以先存草稿、进入创造模式、发送需求后才开始生成，桌面端菜单栏也能直接管理插件，但「能装上」和「可以放心跑」是两回事。

十、自动化任务与开发者工具

官网对「适应你的工作方式」的解释是：随时发起任务，让重复工作按计划执行，掌握关键进展，按需展开工具调用详情。示例是「每周五 17:00（北京时间），整理本周项目记录，生成周报」——Agent 调用 schedule_create，传入 prompt、title 和 weekly（time: 17:00:00、time_zone: Asia/Shanghai、weekdays: [5]），返回一个状态为「等待触发」的定时任务。这类计划任务是挂在会话里的：桌面端退出前的检查会考虑已挂的定时提醒，定时器说明也只在该功能开启后出现。

开发者工具面板则用于排查：可以看执行轨迹与详细运行信息，展开每一轮的时长、调用、搜索、输入、模型、工具、初始系统提示词，以及每次工具调用的参数与返回。官方演示里就靠它核对「先 bash 再两次 read」这类多步调用是否按顺序执行。遇到 Agent 行为反常，先来这里看它到底调了什么，比反复改提示词有效。

任务成果也可以在界面里直接预览并继续用对话改：官网展示的产物类型包括 Word 文档、Excel 表格、HTML 页面、TypeScript 代码、Python 脚本、PDF 和 Markdown 文档，界面里能看到逐轮 diff。

十一、安全边界：上线前必须读完

仓库里的 SAFETY.md 写得毫不委婉，这里按原意完整转述，因为它直接决定你能不能把 Harness 放进生产环境：

• 它是实验性的开发者预览软件，未经安全审计，不能当作安全或生产可用的软件对待。
• 它能执行模型生成的代码和命令、加载第三方插件、访问网络、进程、凭据和文件。模型输出出错、缺陷、配置不当、恶意输入或不可信插件，都可能损坏主机、修改或删除文件、泄露数据或凭据。
• 沙箱、审批提示和权限控制能降低风险，但不保证隔离；即使限制被正确执行，也无法保护项目本身有权访问的资源。不要把 Harness 当作处理不可信工作负载的唯一安全防线。

官方给的负责任使用建议有五条：以完成工作所需的最小权限运行；优先用一次性虚拟机、容器或专用环境；给项目能访问的文件做备份；不接受风险就不要暴露敏感凭据和数据；允许插件、配置和待执行命令运行之前先审查一遍。软件按 MIT 许可提供、不附带任何担保，作者与版权方在法律允许范围内不对主机损坏、数据或文件损失负责。

落到实操上：拿它处理重要目录时先复制一份，第三方插件先看源码再装，Creator 模式生成的插件尤其要检查它申请了哪些工具权限。这一点和「功能很方便」并不冲突，只是代价要说在前面。

十二、版本、升级与破坏性变更

2026-11-09 从 npm registry 读到的 dist-tags：latest 与 next 都是 0.2.2-rc.1（发布于 2026-11-04），alpha 是 0.2.2-alpha.3（2026-11-03）。这个包一共发过 42 个版本，全部是预发布版。同期 GitHub 仓库 star 276,550、fork 33,869，建于 2026-08-13，最近一次推送 2026-11-04，语言 TypeScript，MIT 许可，仓库描述就是那句「Everything is a Plugin」。

版本迭代快到什么程度？举两个已经发生的破坏性变更：v0.2.1-alpha.1 删掉了运行时不变插件（runtime invariant plugins），会直接让部分现有扩展升级后失效；v0.2.2-alpha.2 改了网页搜索与获取凭据的字段，旧配置虽然能加载但被忽略。README 顶部那句加粗「会有破坏兼容性的变更」不是免责套话。

桌面端还内置了更新机制：安装更新会在锁定 API 准入后停止 Host 进程，需要时重启应用。所以生产环境用 dsh，务必先读对应版本的升级指南并固定版本，别让 latest 和 npx 帮你「自动升级」。仓库为每个破坏性变更提供了 docs/upgrade-guide/ 下的迁移说明，升级前值得花两分钟翻一下。

十三、常见问题排查

十四、与站内另外两篇的分工

站内还有两篇讲 dsh 的文章，角度不同：DeepSeek Harness 正式发布 讲的是项目本身和名字之辨（确实不是 Hermes），DeepSeek Harness 安装教程 讲的是 npx 和源码构建这两条 Web 路径。本文以桌面端为主线，把配置、模式、插件、自动化和安全边界补齐，三篇合起来才是完整链路。

怎么选：只是想试试、且机器上有 Node，用 npx 最省事；要长期用、或者不想碰命令行，装桌面端；想读代码、写插件、参与贡献，从源码跑。

十五、版本信息速查

官方来源：DeepSeek Harness 官方预览页 · GitHub 仓库（含 README、SAFETY.md、架构文档） · 官方文档站

延伸阅读

Harness 只是 DeepSeek 工具链的一部分。下面几篇补上工具之外的部分：谁在做、资金从哪来、以及同期的开源动作。

• DeepSeek 创始人梁文锋密集接触具身智能：自建团队还是投资入局
• DeepSeek 领投 Winverse AI：4亿美元估值入局具身智能机器人
• DeepSeek 启动 IPO 准备：已向监管机构提交上市前一轮融资申请
• Kimi K2.5 技术报告：Visual Agentic Intelligence 是什么