我先按 “同名产品先定位、开源版先查发版说明” 的口径核实 DeepSeek Harness 到底是什么，再查安装配置链路。
官网口径已锁定：dsh 是 DeepSeek 官方开源 Agent Harness。我再核对安装页的系统要求与插件清单。
DeepSeek Harness（简称 dsh）是 DeepSeek 官方开源的一套 Agent 运行框架，不是新模型，也不是聊天窗口，而是 “把模型、工具、工作区、权限和任务循环接起来” 的那层执行环境。它的安装其实只有三种走法：想省事就下桌面端，双击安装、登录即用，自带 Node 和 Python 运行时；想最快试一下就在装了 Node.js 的机器上跑一条 npx @deepseek-ai/dsh web，浏览器打开 http://127.0.0.1:3080 就能用；想改代码、自己写插件就克隆源码，按 pnpm install → pnpm run build → pnpm dsh web 三步走。配模型只有三要素：接口地址、API Key、模型名，改的是 $DSH_HOME/settings.yaml 或设置页里的模型卡片。装插件更简单，桌面端在插件管理页输入 npm 包名就能装，命令行则是 dsh plugin --profile web add <包名>。全程最容易踩的三个坑：npx 启动时系统里没有 dsh 命令、Windows 原生环境缺 POSIX 终端导致 Bash 工具链不完整、以及把 Key 写进会提交到 Git 的文件，这三条提前避开，基本一次就能跑通。
一、先分清它是什么
| 常见误解 | 实际情况 |
|---|---|
| 是新模型 | 不是。dsh 是运行框架，模型通过插件接入，可换 DeepSeek 官方模型，也可换第三方 |
| 是 DeepSeek 网页版的桌面壳 | 不完全。桌面端复用了 Web UI 与 Agent、会话、工具、插件逻辑，但补齐了本地工作区、后台常驻、定时任务 |
| 要写代码才能用 | 不用。桌面端开箱即用，四条模式里 “标准模式” 就是给日常任务用的 |
| 是字节跳动的产品 | 不是。由 DeepSeek AI（深度求索）开发，MIT 协议开源 |
架构上它基于 Cordis 插件内核，口号是「一切皆插件」：模型、工具、技能、会话、沙箱、存储、循环、调度、UI 全部是插件，内核只负责加载卸载与依赖关系。好处是换一个提供方插件，整个产品行为就跟着变，不用改源码。
四种模式的定位：
| 模式 | 能力 | 适合场景 |
|---|---|---|
| 标准模式 | 完整工具组合：文件编辑、Shell、文件与网页搜索、技能、规划、子 Agent、工作流 | 绝大多数日常任务 |
| PTC / Code 模式 | 工具通过 Code Mode SDK 暴露，模型写一段 TypeScript 程序编排多步调用 | 批量调用后再筛选汇总 |
| 极简模式 | 只保留持久 bash 与 str_replace_editor 两个工具 | 最小环境下的模型基准测试 |
| 创造模式 | 检查运行时、在内存里试验 Cordis 插件、组合新模式 | 自己写插件、定制专属模式 |
二、三条安装路径怎么选
| 路径 | 前提 | 一条命令 / 操作 | 适合谁 | 平台 |
|---|---|---|---|---|
| 桌面端 | 无 | 官网下载安装包，双击安装 | 不想碰命令行的人 | macOS（Apple silicon，macOS 13+）、Windows 10+ |
| npx 快速启动 | 已装 Node.js | npx @deepseek-ai/dsh web | 想 5 分钟先试试 | 跟随 Node 跨平台 |
| 源码安装 | Node + pnpm + Git | git clone → pnpm install → pnpm run build → pnpm dsh web | 要改代码、写插件、做定制 | 全平台，Windows 建议 WSL2 |
注意：官方桌面端目前只有 macOS 与 Windows，没有 Linux 桌面版；Linux 用户走 npx 或源码。
三、路径 A：桌面端（最省事）
- 打开官网 deepseek.com/harness，按系统点下载（macOS 选 Apple silicon 版本，Windows 选 64 位）。
- macOS 打开 DMG，把应用拖进 “应用程序”；Windows 运行安装包，按向导完成。
- 首次启动会做初始化：先选 “办公与创作” 或 “代码与开发”（可同时勾选），再选工作过程展示的详略（只看结果 / 关键细节 / 完整过程）。
- 登录 DeepSeek 账号，或填 API Key。两者不能混：登录账号就用账号模式，填 Key 就用 API 模式，选错会出现 “能输入任务但不执行” 的情况。
- 添加工作区：点工作区旁的添加按钮，选一个文件夹。第一次建议新建一个空目录试手，别直接选主目录或存放私人文件的目录。
- 新建会话时保持：Agent = 标准模式，权限 = Workspace Write，模型用默认。第一条任务让它 “列出当前目录文件”，能返回就说明通了。
桌面端还自带 Node 与 Python 运行时，首次用到 Python 时自动安装，并预置了 pandas、python-docx、python-pptx、openpyxl 等处理数据与 Office 文件的库，以及用于预览文档的 LibreOffice，所以做表格、写 PPT 不用自己配环境。
四、路径 B：npx 一步启动
1. 确认 Node.js 版本（建议直接用 LTS）
node -v
2. 启动 Web UI
npx @deepseek-ai/dsh web
3. 浏览器打开默认地址
http://127.0.0.1:3080
启动后在页面里点 “选择工作区”，添加你启动 dsh 时所在的项目目录，会话输入框才可用。
这一步必须知道的坑：用 npx 启动只是临时拉包运行，系统里不会出现 dsh 命令。后面你想用 dsh plugin add 装插件时会找不到命令，需要先全局安装：
npm install -g @deepseek-ai/dsh
dsh --version
五、路径 C：源码安装（可改可扩展）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build 关键步骤，生成运行所需产物，不能跳过
pnpm dsh web 默认监听 127.0.0.1:3080
顺序必须是 install → build → web，跳过 build 会出现启动异常。Windows 用户如果要完整的 Bash、PTY、Linux 权限与沙箱，建议不要在原生 Windows 上硬跑，而是走 WSL2。
| Windows 常见坑 | 表现 | 处理 |
|---|---|---|
| 缺少 make/gcc/g++ | node-pty 走 node-gyp 重编译时报 make: not found | WSL 里先装 build-essential、python3-dev |
| GCC 太旧 | g++: error: unrecognized command line option '-std=gnu++20' | 换较新 Ubuntu，或升级 GCC |
| 误用 Windows 的 dsh | 报 dsh: node not found，路径在 /mnt/c/Users/... | 在 WSL 内装 Node，从 WSL 环境运行 |
| 看到 “Unsupported platform” 警告 | 提示 arm64 包与 linux-x64 不匹配 | 正常警告，monorepo 含多平台组件，不影响安装 |
六、配置模型：只有三要素
无论哪种安装方式，模型配置的本质都是 接口地址 + API Key + 模型名。
方式 1：DeepSeek 官方
在设置页 “模型” 里找到 DeepSeek 卡片，选 “自定义设置”，填 API Key 和接口地址，再添加模型名。也可以直接在配置文件 $DSH_HOME/settings.yaml 里写。
方式 2：接火山方舟 Coding Plan
| 配置项 | 填什么 |
|---|---|
| 协议 openai-completions /openai-responses | https://ark.cn-beijing.volces.com/api/coding/v3 |
| 协议 anthropic-messages | https://ark.cn-beijing.volces.com/api/coding |
| API Key | Coding Plan 的 API Key |
| 模型名 | 例如 deepseek-v4.1-flash、deepseek-v4-pro、doubao-seed-2.1-pro 等（以控制台开通列表为准） |
官方文档特别提醒：不要用 .../api/v3，那个地址不消耗 Coding Plan 额度，会产生额外费用。
配置文件示例（注意 input 一行是可选项，要让模型支持图片输入才需要加）：
llm-pi-ai:
providers:
ark-plan:
displayName: ark-plan
apiKeyEnv: CODING_PLAN_API_KEY
api: openai-responses
baseURL: https://ark.cn-beijing.volces.com/api/coding/v3
models:
- id: doubao-seed-2.1-pro
name: doubao-seed-2.1-pro
input: [text, image]
方式 3：第三方兼容端点
在 “添加自定义提供方” 里填 Provider ID（自定义）、显示名称、API 地址与 API 协议、API Key、模型名。Provider ID 一旦创建，改名字要新建提供方再删旧的，所以起名别随手。
安全习惯：配置 Key 时不要截图，不要把 Key 写进会提交到 Git 的文件或脚本；用 apiKeyEnv 引环境变量比明文写进配置更稳妥。
七、装插件：官方四个 + 社区一整套
官方插件（在插件页里手动开启，均标注 “实验性”、默认关闭）：
| 插件 | 作用 | 启用注意 |
|---|---|---|
| 自动化任务 | 把重复工作设成按计划执行的定时任务，可查看每次运行记录、调整频率 | 关闭桌面端后定时任务不会被注销 |
| 智能体团队 | 多 Agent 协作，共享任务板，可配置角色分工 | 实验性，效果仍在打磨 |
| 自动授权审查 | 每次工具调用前先由同款模型审查，被拒的再交给你决定 | 不使用沙箱，开启前需确认风险提示 |
| 语音输入 | 本地语音识别输入 | 需下载约 1GB 的本地识别包（SenseVoiceSmall） |
社区插件（数量大得多，按 npm 包名或 GitHub 仓库安装）：
前提：已全局安装 dsh
npm install -g @deepseek-ai/dsh
按 npm 包名安装
dsh plugin --profile web add <包名>
从 GitHub 仓库安装（可能需要允许构建脚本）
dsh plugin --profile web add github:/
卸载
dsh plugin --profile web remove <包名>
按官方口径，以模型 API 用户统计，约 60% 的 dsh 用户用过第三方插件，团队也在建设官方插件市场。社区侧目前已出现多个第三方市场站点，做法是给 dsh 加一个 “自定义索引源”，在 “发现” 页浏览并一键安装：
全量索引：https://cdn.dsh.so/market/index.json
精选榜单：https://cdn.dsh.so/market/top-rank.json
操作路径：插件页启用实验插件「自定义插件索引」→ 发现页添加索引源 → 搜索并安装。
社区里比较有代表性的方向（按用途分类，装之前先看仓库说明和更新日期）：
| 用途 | 代表插件（包名 / 仓库） | 说明 |
|---|---|---|
| 插件市场 | dsh-market、dsh-plugin-hub | 在设置页里浏览、搜索、一键安装社区插件 |
| 上下文可视化 | dsh-context | 上下文组成、演进、压缩、多 Agent 查看 |
| 成本与用量 | dsh-cost-meter、dsh-usage | 会话与当日费用、Token 用量、预算与余额 |
| 侧边栏增强 | dsh-better-sidebar | 文件渲染编辑、终端、Git、子 Agent 页面 |
| 视觉能力 | @liustack/modlens | 给纯文本模型外挂识图，粘贴图片得到结构化 JSON |
| 记忆 | dsh-memento、MemOS 类 | 跨会话长期记忆（注意有的项目已标注冻结维护） |
| 定时 / 自动化 | dsh-cron-scheduler 类 | 系统级 cron 定时，进程外执行 headless 任务 |
| IM 接入 | @xmanrui/dsh-im、dsh-im-connect | 把飞书、微信、钉钉、QQ 接进来给 agent 派活 |
插件安全三原则（必须看）：
- 第三方插件以你自己的权限运行，能读文件、用凭据、连网络，工具审批并不等于沙箱隔离。
- 从 GitHub 安装会在安装阶段执行构建脚本，pnpm 默认拦截，需要你手动允许；允许构建就是一个信任决策，只装你信得过的源，能固定 commit 就固定。
- 装完 bundle 类插件要重启 dsh 才生效；skill 类在新会话可用；preset 类要在新会话的预设列表里选。
说明一句：本教程没法给你一个 “打包好的插件压缩包” 下载，因为插件是按包名从 npm/GitHub 拉取的，来源和版本随时在变；按上面的包名和命令自行安装，比拿一个来源不明的压缩包安全得多。
八、第一次跑通的验收清单
- node -v 正常，npx @deepseek-ai/dsh web 或桌面端能启动
- 浏览器 / 客户端能打开 127.0.0.1:3080 或进入主界面
- 已选中一个空目录作为工作区，输入框可用
- 模型卡片里 API Key、接口地址、模型名三项都填对，能正常回复
- 账号模式 / API 模式选择与登录方式一致（否则出现 “不干活”）
- 第一条任务能读写工作区文件（例如 “列出当前目录并总结”）
- 切到 “轨迹” 页签，能看到系统提示、工具调用与返回记录
- 需要插件时再进插件页开启，装完记得重启
九、常见报错速查
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 能输入任务但不动 | 账号模式与 API 模式选错 | 按登录方式切换模式 |
| dsh: command not found | 只用过 npx，没全局安装 | npm install -g @deepseek-ai/dsh |
| 插件装了不生效 | bundle 插件未重启；skill 需新会话 | 重启 dsh / 开新会话 |
| GitHub 插件安装中断 | pnpm 拦截构建脚本 | 按提示在 profile 的 pnpm-workspace.yaml 加 allowBuilds 后重试 |
| 定时任务没触发 | 插件未开启或任务已注销 | 插件页确认 “自动化任务” 已启用，检查任务列表 |
| 模型列表里没有想要的模型 | Model Name 写错或控制台未开通 | 用控制台里的模型名，或改用 ark-code-latest 由控制台切换 |
【常见问题】
问题 1：DeepSeek Harness 到底是什么，和 DeepSeek 聊天助手有什么区别？
回答 1：DeepSeek Harness（dsh）是 DeepSeek 官方开源的 Agent 运行框架，负责把模型、工具、工作区、权限和任务循环连起来，让模型能在真实环境里读写文件、跑命令、查资料。DeepSeek 聊天助手是开箱即用的对话产品；DeepSeek Harness 则是拿来搭自己智能体的底座，模型、工具、沙箱、UI 都能通过插件替换。目前它是开发者预览版、MIT 协议开源，官方提示后续可能出现破坏兼容性的变更，别把生产数据直接放进去。
问题 2：DeepSeek Harness 怎么下载安装，最快的方式是哪条？
回答 2：最快是 npx：装好 Node.js 后执行 npx @deepseek-ai/dsh web，浏览器打开 http://127.0.0.1:3080。最省事是桌面端：在官网 deepseek.com/harness 下载 macOS（Apple silicon，macOS 13+）或 Windows 10+ 安装包，双击安装、登录即用，自带 Node 与 Python 运行时。要改代码就源码安装：git clone 官方仓库后依次 pnpm install、pnpm run build、pnpm dsh web。三条路径里，源码安装多了 build 这一步，跳过就会启动异常。
问题 3：DeepSeek Harness 的模型怎么配置，需要准备什么？
回答 3：只需要三要素：接口地址、API Key、模型名。官方模型在设置页 “模型” 里选 DeepSeek 卡片填；接火山方舟 Coding Plan 时，openai 协议用 https://ark.cn-beijing.volces.com/api/coding/v3，anthropic 协议用 https://ark.cn-beijing.volces.com/api/coding，别用 /api/v3（不消耗套餐额度还会额外计费）；第三方兼容端点走 “添加自定义提供方”。配置文件在 $DSH_HOME/settings.yaml，用 apiKeyEnv 引环境变量比明文写 Key 安全。
问题 4：DeepSeek Harness 的插件包怎么装，有没有现成的常用插件清单？
回答 4：没有官方打包的 “插件包” 可下载，插件是按 npm 包名或 GitHub 仓库分发的，装法是 dsh plugin --profile web add <包名>，前提是已全局安装 dsh。常用方向可以按需挑：插件市场（dsh-market、dsh-plugin-hub）、上下文可视化（dsh-context）、成本统计（dsh-cost-meter）、侧边栏增强（dsh-better-sidebar）、外挂识图（@liustack/modlens）、IM 接入（@xmanrui/dsh-im）。官方自带四个实验性插件：自动化任务、智能体团队、自动授权审查、语音输入，默认关闭需手动开启。
问题 5：DeepSeek Harness 装插件安全吗，要注意什么？
回答 5：第三方插件以你自己的权限运行，能读文件、用凭据、访问网络，工具审批不等于沙箱隔离，这是最需要警惕的一点。具体三条：GitHub 来源的插件安装阶段会执行构建脚本，pnpm 默认拦截，手动允许就是一次信任决策，能固定 commit 就固定；装完 bundle 类插件必须重启 dsh 才生效；优先选有安全扫描与安装实测标记的市场条目，并看一眼最近更新时间，长期不维护的插件兼容风险高。
问题 6：Windows 上跑 DeepSeek Harness 一直报错，怎么解决？
回答 6：多数是环境问题，不是软件问题。常见三类：报 make: not found 说明缺 build-essential 等编译工具链，node-pty 需要现场编译；报 unrecognized command line option '-std=gnu++20' 说明 GCC 太旧，换较新 Ubuntu 或升级编译器；报 dsh: node not found 且路径是 /mnt/c/Users/...，说明你调用了 Windows 侧安装的 dsh，应在 WSL 内装 Node 并从 WSL 运行。想要完整的 Bash、PTY 与 Linux 沙箱，直接走 WSL2 比在原生 Windows 上折腾更省时间。
【参考资料】
[2026-11-10]（DSH 插件市场 — 安全扫描 + 沙盒安装实测）DSH Plugin Registry
[2026-11-06]（Plugin Markets & Managers — DeepSeek Harness Plugins）DSH Marketplace
[2026-10-24]（DeepSeek Harness（接入 AI 工具，含 Coding Plan 配置与 settings.yaml 示例））火山引擎文档中心
[2026-10-15]（DSH 插件市场 — 在 DSH 插件市场发现与比较插件）DSH Plugin Registry
[2026-09-30]（DeepSeek Harness 桌面端正式发布，一手体验（含四种模式、插件管理与自动化任务））人人都是产品经理
[2026-09-30]（DeepSeek Harness 桌面版实测：更像「个人助理」）爱范儿
[2026-09-26]（DeepSeek 桌面预览版上线，将 TierFlow 接入即可体验（含桌面端下载与配置步骤））新浪财经
[2026-08-20]（Windows 下通过 WSL2 + pnpm 从源码运行 DeepSeek Harness：从零开始的完整教程）稀土掘金
[2026-08-16]（最新！DeepSeek Harness 桌面版和 CLI 来了（社区桌面端与 TUI 保姆教程））Datawhale（搜狐）
[2026-08-01]（DeepSeek Harness 官网：快速开始、源码安装与常见问题）DeepSeek
【免责声明】
本文依据 DeepSeek 官网（deepseek.com/harness）、火山引擎官方文档、GitHub 开源仓库说明，以及新浪财经、爱范儿、人人都是产品经理、Datawhale、稀土掘金等公开报道整理，截至 2026 年 11 月 10 日。DeepSeek Harness 目前为开发者预览版（v0.1 起，社区可见版本已迭代至 0.2.x 的 rc/alpha 通道），官方明确提示仍在快速迭代、可能出现破坏兼容性的变更，命令、配置字段、插件接口与页面路径均可能随版本变化，请以你安装版本的官方说明为准；文中版本号、插件包名、市场收录数量来自不同来源，存在时效差异。官网页面无明确发布日期，参考资料中按其上线月份标注。插件安装涉及第三方代码执行与构建脚本放行，属用户自主信任决策，本文不构成对任何第三方插件的安全性背书；操作前请备份数据，并在独立目录或沙盒环境试跑。本文为安装配置类信息整理，不构成购买、采购或商业使用建议。