想本地跑一个对标 Claude Code / Cursor 的 Agent 框架，但不想被厂商锁定？DeepSeek 官方在 2026 年 8 月开源的 Harness（dsh） 用 npx 一行命令就能起 Web UI，3 步跑通——本文把官方仓库的「Everything is a Plugin」架构、4 种运行模式、11 张实测截图 + 报错速查一次给齐。

摘要：DeepSeek Harness（dsh）是 DeepSeek AI 开源的 Agent 运行时框架，基于 Cordis 插件系统，主打「Model + Harness = Agent」理念——一切皆插件，模型 / 工具 / 会话 / 沙箱 / UI 都能在配置层自由替换。本文实测 npx @deepseek-ai/dsh web 一键启动 Web UI（端口 3080），覆盖 GitHub 170.8k stars 项目的核心架构 + 3 种使用方式 + 7 条报错速查，适合需要定制 Agent 基础设施（对标 Claude Code / Cursor / Manus）的工程师。

在这里插入图片描述

1. 前置环境

  • Node.js：≥ 18.x（npx 命令依赖）
  • 包管理器：npm ≥ 9.x（Node 自带）
  • 浏览器：Chrome / Edge / Safari 最新版（Web UI 渲染）
  • 网络：能访问 npm 仓库（首次启动会下载包）
  • 操作系统：macOS / Linux / Windows 均可
  • 可选模型 API Key：DeepSeek-V4-Flash / V4-Pro（默认推荐）/ 或自定义 OpenAI 兼容 endpoint

检查环境命令（复制粘贴到终端）：

node -v    # 应输出 v18.x 或更高
npm -v     # 应输出 9.x 或更高
which npx  # 应输出 npx 路径（确认已安装）

2. 痛点 + 背景

2.1 Agent 框架选型的 3 条主流路径

路径 代表项目 优势 劣势
云端托管 Agent Claude Code / Cursor / Manus 零部署、即开即用 厂商锁定、按 token 付费、数据出境
自建轻量 Agent 框架 LangChain / AutoGen 灵活、可控 需自配工具 / 沙箱 / 记忆系统，工作量大
DeepSeek Harness dsh（dsh = DeepSeek Harness） 插件化 + 4 种模式 + 官方维护 开发者预览阶段，会破坏性更新

2.2 DeepSeek Harness 的核心公式

Model + Harness = Agent

模型负责预测下一个 token；Harness 决定模型能看到哪些上下文、调用哪些工具、记录什么会话事件、管理哪些文件与子进程——把这些「决策权」做成可插拔的插件，就是 dsh 的核心价值。

2.3 当前主流模型

DeepSeek V4 系列是当前主推（V3 / R1 已于 2026-07-24 退役）：

模型 总参数 激活参数 上下文 定位
deepseek-v4-flash 284B 13B 1M token 轻量快速、Agent 优化
deepseek-v4-pro 1.6T 49B 1M token 顶配推理、长上下文
deepseek-v4-pro-max — — 1M token Pro 的极限推理模式

dsh 不必绑定 DeepSeek 模型——支持目录供应商 / 自定义 OpenAI 兼容路由，可灵活切换 Claude / GPT / 本地模型。

3. 核心方案：3 步跑通

3.1 第 1 步：理解「Everything is a Plugin」架构

dsh 基于 Cordis 插件框架（论文 A Programming Paradigm for Spatiotemporal Composability），所有 Agent 能力都是插件：

  • 模型插件：决定模型适配器（V4-Flash / V4-Pro / OpenAI / Claude / 本地）
  • 工具插件：注册可调用工具（读文件 / 跑命令 / 调 API）
  • 会话插件：管理多轮对话 + 上下文窗口
  • 沙箱插件：隔离文件系统 + 网络 + 进程
  • UI 插件：Web UI / CLI / Headless 3 种使用方式

启动时，dsh 通过有序插件树组合这些能力，并叠加 profile / bundle / patch——无需改源码，即可在配置层定制自己的 Agent。

3.2 第 2 步：一键启动 Web UI（核心命令）

npx @deepseek-ai/dsh web

首次运行会自动下载 @deepseek-ai/dsh 包到 npx 缓存目录，约 30-60 秒。看到类似下面的输出即启动成功：

✔ DSH Web UI ready at http://127.0.0.1:3080
✔ Opening browser...

默认端口 3080（注意：不是 3000），自动打开默认浏览器。SSH 远程启动时只打印 URL，不自动开浏览器——传 --no-open 可关闭自动打开。

3.3 第 3 步：浏览器访问

打开 Chrome / Edge，访问：

http://127.0.0.1:3080

进入 Web Agent 界面，按提示选择模型 + 任务 + 工具即可开始对话。

3.4 可选：从源码启动

如果想跑最新 master 分支或贡献代码：

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

4. 4 种运行模式

dsh 预置 4 种运行模式，对应不同 Agent 场景：

模式 适用 说明
Standard 通用对话 / 问答 默认模式，平衡速度与能力
PTC（Programmatic Tool Calling） 让模型用 TypeScript 组合多步工具调用 复杂工作流、跨工具编排
Minimal 极简、纯模型对话 关闭大部分插件，最轻量
Creator 自定义 Agent 给开发者最大自由度配置插件

切换方式：在 Web UI 设置面板选择，或 CLI 参数 --mode=ptc。

5. 实操截图（11 张实测）

下面是官方仓库 README + 实操过程中的关键截图：

5.1 仓库主页

在这里插入图片描述

GitHub 仓库首页——README 包含快速启动指南

5.2 启动 Web UI 过程

在这里插入图片描述

执行 npx @deepseek-ai/dsh web 后的终端输出——包下载与初始化

Web 服务就绪——提示访问 127.0.0.1:3080

在这里插入图片描述
在这里插入图片描述

5.3 Web UI 界面

页面通用设置，设置Agent 模式、会话访问权限、显示语言、页面背景

在这里插入图片描述

Web UI 首页——模型选择面板（V4-Flash / V4-Pro 等）

在这里插入图片描述

自定义模型供应商——接入 OpenAI / Claude / 本地 vLLM 服务
在这里插入图片描述

插件管理界面——启用 / 禁用 / 配置 dsh-plugin

在这里插入图片描述

任务配置界面——选择 Agent 模式

在这里插入图片描述

5.4 进阶配置

创建项目文件后，创建对话，会话页面展示

在这里插入图片描述

会话结果页面——含 Trajectory 轨迹回放

在这里插入图片描述

6. 常见问题（报错速查）⭐

报错信息 原因 解决方法
npx: command not found Node.js 未安装 安装 Node.js 18+：brew install node（macOS）/ 官网下载 LTS
EACCES: permission denied npx 全局缓存目录无写权限 sudo chown -R $USER:$(id -gn $USER) ~/.npm
EADDRINUSE: address already in use :::3080 3080 端口被占用 lsof -ti:3080 | xargs kill -9，或指定端口 npx @deepseek-ai/dsh web --port 9080
Cannot find module '@deepseek-ai/dsh' npx 缓存损坏 npm cache clean --force 后重试
connect ETIMEDOUT 网络无法访问 npm 仓库 npm config set registry https://registry.npmmirror.com
浏览器打开 127.0.0.1:3080 显示「无法访问」 Web 服务未真正启动 / 防火墙拦截 检查终端 ready 日志；macOS 允许 Node 接受网络连接
Model provider not configured 未配置 API Key 在 Web UI「设置」填入 DeepSeek API Key 或自定义 OpenAI 兼容 endpoint
Sandbox violation: network access denied 沙箱策略禁止网络 在插件配置中启用 network: true（生产环境慎用）

7. 适用场景 + 不适用场景

✅ 适用

  • 本地搭建可定制 Agent——对标 Claude Code / Cursor，但不被厂商锁定
  • 企业内网部署——MIT 开源 + 无遥测 + 无云端锁定，数据完全自主可控
  • Agent 框架研究——Cordis 插件系统 + 论文支撑，适合学术研究
  • 插件生态开发——TypeScript 写一个 dsh-plugin 就能被社区发现（GitHub topic: dsh-plugin）
  • 需要可观测 Agent——每次运行写入仅追加会话日志，Trajectory 视图可查看系统提示词 / 思维链 / 工具调用 / 子 Agent 调度

❌ 不适用

  • 生产环境关键业务——官方明确标注「开发者预览阶段，未来会有破坏性更新」
  • 需要 0 部署的团队——dsh 是本地工具，纯云端场景直接用 Claude Code / Cursor 更划算
  • 沙箱要求极严的金融 / 医疗场景——官方文档明确：「filesystem sandbox 不覆盖网络访问和进程可见性」，需自建加固层
  • 非 DeepSeek 模型深度集成——虽然支持 OpenAI 兼容路由，但工具调用格式 / 推理行为 / 上下文限制需针对每条路由自测

外部资源

  • 官方仓库：https://github.com/deepseek-ai/deepseek-harness（170.8k stars / 18.4k forks / MIT）
  • 官网：https://deepseek.com/harness
  • 官方文档 · 快速入门：https://deepseek-harness.github.io/deepseek-harness/guide/quickstart
  • Cordis 框架：https://github.com/cordiverse/cordis
  • 论文：A Programming Paradigm for Spatiotemporal Composability
  • 社区：GitHub Discussions / Discord（https://discord.gg/Ycq5dCaS4）/ 插件 topic dsh-plugin
  • DeepSeek API 文档：https://api-docs.deepseek.com/zh-cn/quick_start/pricing

下一篇文章预告

  • 《DeepSeek Harness + vLLM 本地大模型接入实战》——把自部署的 V4-Flash 接入 dsh 当 Agent 后端
  • 《从零写一个 dsh-plugin》——Cordis 插件开发教程
# DeepSeek
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

Kubernetes CoreDNS 解析超时排查（ndots 与 NodeLocal DNSCache）

CoreDNS 超时先用 ClusterIP 直连排除数据面，再读 Pod的ndots 与 search。默认 ndots:5 让短名查询放大数倍，AAAA 再乘一倍。指标上区分 NXDOMAIN 瀑布和真正的 SERVFAIL/p99。NodeLocal DNSCache 降 RTT、不消灭放大；根上仍是 FQDN 或谨慎的 dnsConfig。改 DNS 全局配置必须可回滚，禁止先停 Core

avatar 2048 AI社区
cover

AIGC课程为什么从99元到数万元都有：先把“买工具”与“买结果”分开

avatar 2048 AI社区

AI视频总结工具有哪些？2026年5款热门工具横向评测

本文从客观角度介绍5款常见的AI视频总结工具：Ai好记、NoteAi、BibiGPT、通义听悟、NotebookLM。每款工具按同一套维度说明：支持的内容来源、转写与总结能力、操作方式、页面呈现，以及适用场景。文末附功能对比表和常见问题，供读者按需选择。

avatar 2048 AI社区