DeepSeek Harness怎么用?npx一行命令本地跑Agent框架教程

想本地跑一个对标 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 条主流路径

2.2 DeepSeek Harness 的核心公式

Model + Harness = Agent

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

2.3 当前主流模型

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

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 场景：

切换方式：在 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. 常见问题（报错速查）

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 兼容路由，但工具调用格式 / 推理行为 / 上下文限制需针对每条路由自测

以上就是DeepSeek Harness怎么用?npx一行命令本地跑Agent框架教程的详细内容，更多关于DeepSeek Harness教学的资料请关注脚本之家其它相关文章！

最新评论