想本地跑一个对标 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
检查环境命令（复制粘贴到终端）：
bash
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（核心命令）
bash
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 分支或贡献代码：
bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web4. 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 |
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 插件开发教程