DeepSeek Harness 是什么：安装、插件配置与使用教程（2026 实测）

DeepSeek Harness（命令名 dsh）是深度求索在 2026 年 8 月开源的 Agent 智能体运行框架，采用 MIT 协议、完全免费，核心理念是「一切皆插件」——模型、工具、会话、沙箱、存储、调度乃至 Agent 循环本身都是可插拔、可替换的插件。装好 Node.js 后，一行命令 npx @deepseek-ai/dsh web 就能在本机跑起来。本文基于 v0.1.1-rc.2 版本的完整实测，覆盖安装、模型配置、插件配置、四种运行模式、报错排查和 Python SDK，并把踩过的坑全部写清楚。

先给赶时间的读者一份 30 秒结论：

• 它是什么：开源 Agent 框架（agent harness），不是聊天产品；类比的话，Claude Code 是「一体机」，它是「组装机」；
• 免费吗：框架本身 MIT 协议免费，花的钱只在模型 API 调用上（想省钱的看这篇 DeepSeek V4 Pro 白嫖指南）；
• 怎么装：Node.js ≥ 22.19，然后 npx @deepseek-ai/dsh web，浏览器打开 http://127.0.0.1:3080；
• 最大亮点：换模型、换沙箱、删工具、甚至换掉 Agent 循环，都只改配置不动源码；每次运行全量留痕，可回放可分叉；
• 最大坑：Node 版本低于 22.19 会直接启动报错（实测报错信息见下文）；企业内网 npm 镜像可能装不上。

DeepSeek Harness 是什么？

DeepSeek Harness 是 DeepSeek AI 于 2026 年 8 月 13 日随 DeepSeek V4 Pro 模型一起发布的开源 Agent 框架，GitHub 仓库为 deepseek-ai/deepseek-harness，开源两天星标数突破 9.5 万，截至本文更新已超过 19 万，增速超过了当初 R1 开源时的水平。

它的官方口号是 Everything is a plugin（一切皆插件）。要理解这句话，先要理解一个公式：

Agent = Model + Harness

模型（Model）是 Agent 的大脑，负责「想」；Harness（运行框架）负责让 Agent 在真实环境里持续「做」——读写文件、执行命令、调用工具、维护计划、控制权限、保存状态。同一个模型放进不同的 Harness，表现可能天差地别。

用官网的话说：模型是 Agent 的灵魂，而 Harness 让 Agent 理解环境、使用工具、持续工作。

为什么它一发布就火了？

三个数字能说明热度：开源当天 GitHub 星标半小时破万，两天 9.5 万，截至本文更新超过 19 万，增速比当初 R1 开源时还猛；内测招募在 X（Twitter）上引发开发者路演，964 人报名提交了 897 个项目；开源后社区精选列表 awesome-deepseek-harness 和大量第三方插件迅速冒出来。

两个细节值得玩味：从 commit 历史能看到不少代码是通过 Codex worktree 提交的（DeepSeek V4 原生支持 Responses API，团队直接用竞品工具开发自己的产品）；官方目前不接受外部 PR，反馈走 GitHub Discussions，但明确表态「不认为官方仓库中的包比社区创建的包更重要」——插件生态是奔着社区共建去的。

它和 Claude Code、Codex 有什么区别？

一句话总结：Claude Code 和 Codex 是「一体机」，DeepSeek Harness 是「组装机」。

对比细节可以参考我们之前写的 Claude Code 替代品怎么选。需要说明的是：DSH 目前的 UI 成熟度和使用顺滑度「还差得远」（官方自己也承认这是开发者预览版），它赌的是 Agent 范式还没收敛时，把所有选择权留给开发者的路线。

支撑「一切皆插件」的是 Cordis 内核，它只负责三件事：插件的加载、卸载、依赖管理。这套设计来自北京大学与 DeepSeek 联合发表的论文《A Programming Paradigm for Spatiotemporal Composability》，用数学证明（confluence 定理）保证：无论以什么顺序装卸插件，最终状态都等价于把最终配置从头加载一次——也就是运行时换插件不会把系统搞挂。

DeepSeek Harness 免费吗？

框架本身完全免费。 DeepSeek Harness 采用 MIT 协议开源，个人使用、商用、二次开发都不需要付费，只需保留版权声明。

真正要花钱的是模型 API：

• 用官方 DeepSeek API 时，按 token 计费，2026 年 8 月 16 日起执行「峰值/错峰」双档定价，错峰时段（工作日 12:00–14:00、18:00–次日 09:00 及周末）约半价；
• 免费额度方面，官方网页版和 App 的对话不花钱但用不了 Harness；想在 Harness 里零成本试用，可以关注各平台新用户额度（详见 DeepSeek V4 Pro 白嫖指南）；
• 接其他厂商模型（Anthropic、OpenAI 或公司网关）时，费用按对应平台算。

一句话：框架 0 元，成本全看你调多少模型。

另外提醒一句：DSH 本身不内置任何模型，不配 API Key 它什么都干不了——它只是「底盘」，发动机（模型）要自己装。

DeepSeek Harness 安装教程

环境要求

安装前先确认这三项：

• Node.js ≥ 22.19（实测 v22.12.0 会启动失败，具体报错见下一节，建议直接装 22.x 最新版或 24 LTS）；
• 能访问 npm 公网源（国内网络或公司内网源有坑，下文详述）；
• 一个 DeepSeek API Key（从 platform.deepseek.com 创建）。

方式一：npx 一行命令安装（推荐）

npx @deepseek-ai/dsh web

首次运行会自动下载全部依赖并启动，成功后终端会打印：

dsh web: http://127.0.0.1:3080

本机启动时会自动用默认浏览器打开页面；通过 SSH 远程启动时只打印地址。加 --no-open 参数可以只启动服务器不开浏览器。

实测数据（macOS arm64、Node v22.23.2、官方 npm 源）：

• 依赖包总数：1923 个 npm 包（DSH 本体是 60 多个 @deepseek-ai/dsh-* 微插件包，每个能力一个包）；
• 首次安装耗时：npm 官方源约 2 分钟；用 npx 下载完成后启动是秒级，Web UI 首页响应仅 4ms；
• 版本号：dsh --version 输出 0.1.1-rc.2；
• 二次启动：依赖已缓存，启动在 10 秒内。

打开 http://127.0.0.1:3080 就能看到主界面。首屏会提示你先配置模型密钥、再选择工作区（Agent 允许操作的目录），之后输入框才能使用。

方式二：从源码安装

适合想改源码或做插件开发的用户：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

注意 pnpm dsh web 会直接使用已构建产物，不会重新构建。

Windows 用户注意

Web UI 服务端本身可以跑，但官方 Python SDK 目前明确要求 Linux x64/arm64 或 macOS 14+ 的 arm64，持久 PTY 后端不支持 Windows agent；沙箱机制在 Linux 上是 Landlock、macOS 上是 sandbox-exec，Windows 的沙箱能力不完整。Windows 用户建议在 WSL2 里安装使用。

安装报错排查：三个实测踩过的坑

这部分是网上教程最少讲透的地方，以下报错全部来自实测。

坑一：Node 版本过低，启动直接报错

报错现象（Node v22.12.0 实测）：

SyntaxError: The requested module 'node:zlib' does not provide an export named 'createZstdDecompress'
SyntaxError: The requested module 'node:module' does not provide an export named 'stripTypeScriptTypes'

原因：DSH 的会话日志模块用到了 Node 的 Zstd 压缩 API 和 TypeScript 类型剥离 API，前者 v22.15+ 才提供、后者 v22.13+ 才提供。低于 22.19 的 Node 都可能踩中。

解决：

nvm install 22        # 安装 22.x 最新版
nvm use 22
node --version        # 确认 ≥ 22.19

坑二：公司内网 npm 镜像装不上

报错现象：使用企业内网 npm 源（或同步不完整的镜像）时：

error: GET http://内网源/@deepseek-ai/dsh-authorization - 404
error: @deepseek-ai/dsh-tool-pwsh-persistent@^0.1.1-rc.2 failed to resolve

原因：DSH 发布很新，内网镜像还没同步全部 @deepseek-ai 系列包。实测公网 npmjs 官方源和 npmmirror 镜像的包元数据都齐全。

解决：临时切换 registry：

npx --registry=https://registry.npmmirror.com -y @deepseek-ai/dsh web

坑三：npx 卡住十几分钟不动

现象：npx @deepseek-ai/dsh web 长时间无输出、CPU 占用极高。

原因：npx 要在内存里解析全部 1900+ 个包的依赖树，npm 的解析器在这类「一个能力一个包」的微包结构上非常吃力，实测卡了 5 分钟以上仍没装完。

解决：两个思路任选——

1. 先用 npm 全局装一次：npm install -g @deepseek-ai/dsh，之后直接运行 dsh web；
2. 用包管理器安装再运行（bun 装完只需 1–2 分钟）：bunx --registry=https://registry.npmjs.org @deepseek-ai/dsh web。

装好之后记得验证：浏览器访问 http://127.0.0.1:3080 能打开即成功。

DeepSeek Harness 配置模型

第一步：配置 DeepSeek 官方 API Key

打开 Web UI 的设置 → 模型页，在 DeepSeek 卡片里粘贴 platform.deepseek.com 创建的 API Key 并保存。

两个安全细节值得肯定：密钥是只写的，保存后页面只会收到脱敏描述符；密钥存在本机 $DSH_HOME/.credentials.yaml，settings 里只保留凭据引用。

模型配置变更在下一次请求就生效，不需要重启服务器。

第二步（可选）：接入第三方模型

DSH 是模型无关的。在设置 → 模型页选择「添加提供方」，可以接入 Anthropic、OpenAI、Bedrock、Vertex、Azure 等；选「添加自定义提供方」则可以接任意 OpenAI 兼容端点——公司网关、vLLM 自建服务都行，填 Provider ID、基础 URL、API 协议、密钥和至少一个模型即可。

注意：Provider ID 保存后不可改（请求、会话、凭据都引用它），要重命名只能新建再删旧。

settings.yaml 进阶配置

视觉模型和兼容性开关需要直接编辑 $DSH_HOME/settings.yaml。两个最典型的场景：

场景一：自定义提供方挂了视觉模型，要在模型上声明 input 模态，否则发图会在发送前就被拒绝：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: vision-preview
          input: [text, image]

场景二：OpenAI 兼容网关拒绝推理模型的请求，多半是网关不认 developer 角色或 max_completion_tokens 字段，加一段 compat：

      compat:
        supportsDeveloperRole: false
        maxTokensField: max_tokens

模型配置报错速查表

DeepSeek Harness 插件配置详解

「插件」是 DSH 的核心概念，也是它和所有同类产品拉开差距的地方。官方仓库里整个项目由 50 多个独立的 Cordis 插件组成，官方原话是「There is no privileged core to patch」——所有插件地位平等，没有谁是不可替换的核心。

四种运行模式：插件组合的预设

DSH 内置四种 Agent 预设（Agent Preset），本质是四种不同的插件组合：

对入门用户来说标准模式够用；玩熟了想针对特定场景定制，切到创造模式让 Agent 帮你组装。

运行时换插件为什么不会把系统搞挂？

「一切皆插件」带来一个必须回答的问题：Agent 正在跑的时候，插上/拔下一个插件，其他插件会不会被搞挂？Cordis 的答案是两个维度的保障：

• 时间维度：插件卸载时所有副作用必须可撤销。每个注册的事件监听器、服务、工具 schema 都通过 ctx.effect() 安装，运行时追踪逆操作，卸载时反序执行；
• 空间维度：插件间依赖自动管理。通过 inject 声明需要哪些服务，框架等依赖就绪再激活；被依赖的服务卸了，依赖它的插件自动暂停，恢复后自动接回。

所以你可以在 Agent 跑着的时候换模型、加工具、改沙箱，不丢上下文、不丢会话。这套机制有论文级的数学证明背书，也是 DSH 和普通「插件系统」（比如 VS Code 卸插件要重启）最本质的区别。

用 dsh plugin 管理插件

给某个 profile 安装社区插件（GitHub 上搜 dsh-plugin 话题）：

dsh plugin --profile web add <插件包名>

实测发现这个命令本质是把参数转发给 profile 目录下的 pnpm（实测输出了 pnpm 10.33.0 的帮助信息），所以 pnpm 支持的 add/remove/update 操作这里都能用。web 和 headless 两个 profile 首次使用会自动初始化，其他 profile 必须通过 dsh plugin 创建。

cordis.yml 与 --patch：加载自己的插件

本地插件不用改框架源码，写一个覆盖层文件（cordis.yml）即可：

- insert:
    - id: hello
      name: '/absolute/path/to/my-plugin.ts'

然后带上参数启动：

dsh web --patch ./cordis.yml

插件本身就是一个导出 apply 函数的 TypeScript 模块，最小示例：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

通过 ctx 注册的事件监听、工具、定时器在插件卸载时会被框架自动清理；有手动清理需求的资源（比如网络连接）用 ctx.effect() 注册清理函数。插件还支持对象形式和类形式（需要向其他插件提供服务时用类形式），并可通过 inject 声明对 tools、llm 等服务的依赖，框架保证依赖就绪后才加载。

想看当前配置树到底叠了哪些层，用：

dsh --dump-config           # 查看组合后的完整配置树
dsh --dump-default-config   # 查看不含用户覆盖层的默认树

配置树的叠加顺序是：profile 组合包 → profile 自己的 cordis.patch.yml → home 级 $DSH_HOME/cordis.patch.yml → --patch 指定的覆盖层。

一个细节：AGENTS.md 的支持

DSH 对面向 Agent 的仓库规范友好，仓库根目录的 AGENTS.md 会被 Agent 读取作为项目上下文，和 Claude Code、Codex 的行为一致。

DeepSeek Harness 使用教程

Web UI：跑通第一个任务

三步：

1. 配置模型（上文已完成）；
2. 选择工作区：点「选择工作区」添加想让 Agent 操作的项目目录并选中——不选工作区输入框不可用，这是刻意的安全设计，Agent 只能碰你明确授权的目录；
3. 发送任务：比如输入「总结此代码库并识别其主要工作原理」。实测让 Agent 总结 deepseek-harness 自己的源码仓库，它读了 AGENTS.md、扫了 packages 目录、翻了设计文档，一分钟左右给出架构概览，核心包和职责列得相当清楚。

Agent 可以读写工作区文件、执行命令、委派子任务、维护计划。按当前权限策略需要审批的操作（比如执行 shell 命令），Web UI 会先弹窗询问你，点确认才继续——这点对不敢直接放权的用户很友好。

体感上响应速度和工具调用的周转都很快（官方默认模型 deepseek-v4-flash 本身推理就快，DSH 端的开销控制也做得不错），任务中断后会话可以恢复，也可以从任意节点分叉出新会话重新试。

轨迹视图：每一次运行都可回放

这是 DSH 最有辨识度的功能。模型看到的一切——系统提示词、推理过程、工具调用与结果、子 Agent 调度、每次上下文注入——全部写入只追加（append-only）的会话日志。在「轨迹」（Trajectory）标签页可以按来源逐层展开检查；会话的恢复、分叉、搜索、回放都基于同一套事件流。

对排查「Agent 为什么这么干」和做模型评测来说，这种「模型可见即已记录」的设计比截图日志实用得多。比如你怀疑模型在某一步被错误的上下文误导，直接展开那一步的注入内容就能验证；想对比两次执行的差异，把两条会话的轨迹并排看即可。

headless 模式：命令行跑任务

不想开浏览器，直接跑一次性任务：

dsh --profile headless "run the tests"

会新建持久化会话，打印最终答案后退出，适合接 CI 或脚本。

Python SDK：程序化调用

需要在自己程序里嵌 Agent 时用 Python SDK（Python 3.10+）：

pip install deepseek-harness-sdk

核心用法：

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    cwd="/path/to/workspace",
    session_root="/path/to/sessions",
) as harness:
    result = harness.run("Inspect the repository and fix the failing tests.",
                         session_id="example-001")
    print(result.final_response)

两个要点：独立任务用新的 session id，只有要延续同一段持久化对话时才复用旧 id（同一个 session 会保留 Bash 进程的工作目录、导出变量和 shell 函数）；默认组合使用 danger-full-access 权限，只应在可丢弃的目录或容器里运行。

DeepSeek Harness 适合谁用？

现在就适合：

• 想做 Agent 框架选型或二次开发的工程师——MIT 协议加全插件化架构，自定义空间目前同类最大；
• 做模型评测的团队——极简模式就是为基准测试设计的；
• 想低成本实验「换模型/换沙箱/换循环」效果的研究者。

暂时不适合：

• 只想找个顺手的日常编程助手的用户——UI 和体验成熟度不如 Claude Code（可以看 OpenAI Codex 使用指南和 Claude Code 充值订阅攻略）；
• 要上生产环境的团队——官方明确处于开发者预览阶段，未来会有破坏性变更，且已有研究者披露了沙箱相关的安全漏洞（read-only 沙箱对读操作不设防、动态插件的 vm 沙箱存在逃逸路径），敏感环境务必容器隔离运行；
• 纯小白用户——它需要你理解工作区、密钥、插件这些概念，不适合「装完即用」的期待（小白先看 AI Agent 是什么）。

总结

DeepSeek Harness 用「一切皆插件」把 Agent 框架做成了乐高：模型、工具、会话、沙箱、循环、UI 全部可替换，配置即生效、运行可回放，加上 MIT 协议，是 2026 年 Agent 基建层最值得跟进的开源项目。对开发者来说，门槛不高——Node ≥ 22.19 加一行 npx @deepseek-ai/dsh web；对观望者来说，不妨先用标准模式跑通第一个任务，再决定要不要深入插件体系。它现在的体验确实不如 Claude Code 顺滑，但它给出的可组合性上限，是目前任何一体化产品都给不了的。

最后更新：2026 年 8 月（基于 DeepSeek Harness v0.1.1-rc.2 实测；项目迭代很快，重大变更时本文会同步更新）