DeepSeek Harness 上手：Everything is a Plugin 的 AI 编程智能体

2026年8月13日，DeepSeek 开源了一个叫 deepseek-harness（命令行简称 dsh）的项目，一天冲到五万多 star。

点进去你会发现一件怪事：README 总共一千七百来字，没截图，没功能列表，连「这到底是个啥」都没讲明白，只甩出一句话——Everything is a Plugin（一切皆插件）。

但它的热度是真实的。原因也简单：它把「大模型」和「动手干活」之间缺失的那一层补上了。大模型是大脑，Harness 就是手脚和操作系统——读写文件、执行命令、调用工具、跑自动化流程，全在这一层完成。对标的就是 Claude Code、OpenAI Codex 那一类编程智能体。

本文基于官方 README 和 2026-08-19 前的社区实测教程整理。项目处于 developer preview，迭代很快，命令可能随版本变化，以官方仓库为准。

一、它到底是什么

一句话：Model + Harness = 完整智能体。

传统对话模型只能输出文本，你复制粘贴、自己动手。DeepSeek Harness 在模型外面套了一层运行框架：

• 直接读写本地文件
• 执行终端命令
• 按工作区（workspace）圈定操作范围
• 自带 Web UI，任务流程、工具调用、Token 消耗全程可视化
• 所有能力都是插件，可插拔、可替换、可自己写

架构上基于 Cordis 插件系统：文件编辑、命令执行、网页检索、模型适配……每个能力都是独立插件，加载哪些、不加载哪些，由你定。这就是「一切皆插件」的含义——不是营销口号，是它的真实架构。

二、环境准备

唯一硬性要求：Node.js。官方声明支持 ^22.19.0 || >=24.0.0，不确定就装 Node 24 LTS 系列。版本太低会直接启动失败，这是新手报错的第一大原因。

node -v   # 必须 v22.19+ 或 v24+
npm -v

国内网络建议先把 npm 切到镜像源，否则下载依赖会等到怀疑人生：

npm config set registry https://registry.npmmirror.com

三、安装：三种方式，按需选

方式一：npx 一键启动（最快体验）

npx @deepseek-ai/dsh web

首次运行会自动下载依赖，等待一到两分钟，然后启动本地 Web 服务，浏览器打开：

http://127.0.0.1:3080

方式二：全局安装（长期使用）

npm install -g @deepseek-ai/dsh
dsh web

之后任意目录直接 dsh web 启动，不用每次重新下载。

方式三：源码安装（开发插件/读源码）

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build    # 这步不能省，只装依赖没有构建产物，Web 页面会缺东西
pnpm dsh web

想在自己程序里调用 agent 的，官方还提供了 Python SDK（pip install deepseek-harness-sdk，自带运行时，不需要系统装 Node.js）。

四、首次配置

启动后浏览器打开 http://127.0.0.1:3080，按引导完成三步：

1. 配置模型 API：设置 → 模型，填入 DeepSeek API Key（platform.deepseek.com/api_keys 生成）。保存后模型路由立即可用，不用重启服务。

2. 添加工作区：选择你的项目目录。工作区就是 agent 的操作边界——它只能碰这个文件夹里的东西，这是文件安全的第一道闸。没选工作区之前，会话输入框是禁用的。

3. 选权限模式：三档可选。

英文界面看着费劲的话，左下角 Settings 里可以把界面语言切成中文。

五、四种运行模式

DSH 内置四个 agent 预设，本质是「加载哪些工具、怎么跑」的不同组合：

标准模式：全功能。文件编辑、Shell 命令、网页检索、子代理、工作流自动化，覆盖 90% 日常开发场景。新手上路用这个。

PTC 模式（Programmatic Tool Calling）：不再让模型一次点一个工具、来回五趟，而是让模型写一段 TypeScript，通过 Code Mode SDK 一次组合多步操作，系统用 run_code 一次执行。五次往返收成一次。适合高阶用户做批量自动化。

极简模式：只留两样——持久 bash 终端 + 按绝对路径改文件的 str_replace_editor。Token 消耗最低，适合简单改文件、跑命令。

创造模式：标准模式全部能力，外加改 Harness 自己的能力——检查运行时、试插件、写新的 agent 预设（自定义预设存到 ~/.dsh/.agent-presets/）。插件开发者用这个。

六、模型配置：不止 DeepSeek 一家

默认用 DeepSeek 官方 API，但 dsh 支持 OpenAI 兼容的自定义端点，这意味着别的模型也能塞进来。

官方预设的供应商：智谱 GLM（提供方选 zai-coding-cn）、阿里千问（qwen-token-plan-cn）、小米（xiaomi）——填 API Key 保存即可自动拉取模型列表。

自定义接入（以 OpenAI 兼容协议为例）：

设置 → 模型 → 添加自定义提供方
  Provider ID:  随便起个名
  API 地址:     https://your-endpoint.example.com/v1
  API Key:      你的密钥
  协议:         openai-completions（或 openai-responses）

填完点「获取可用模型」，能拉到列表就说明配置正确，勾选要用的；也可以手动填模型 ID（比如 deepseek-v4-pro、deepseek-v4-flash）。不同厂商的模型收进同一个界面，写代码时随手切换，不用来回换客户端。

七、Token 消耗为什么低

这是 dsh 社区实测反馈最集中的优势，两个机制：

1. 智能上下文缓存：重复读取的代码、配置、工具指令会命中缓存，缓存命中的输入 token 成本降 90% 以上，长会话越用越省。
2. 按需加载插件：不把几十个工具的 schema 一次性塞给模型，任务需要哪个才加载哪个，减少无效上下文占用。

社区实测参考：日常代码修改、接口调试，单次任务 50–300 token；完整项目重构、批量文件处理 1000–5000 token。

八、命令行与插件生态

headless 模式：不启动 Web UI，一次性跑完任务打印答案，适合脚本和 CI：

dsh --profile headless "Summarize this repository and identify its main packages."

插件管理：

dsh plugin --profile web add <插件包名>   # 安装插件
dsh --profile web --dump-config           # 查看实际配置树
dsh credentials set <KEY_NAME>            # 写入凭据

社区插件已经不少，比如 DSH Vision Toolkit（给纯文本模型补视觉能力：图片问答、OCR、定位、截图对比）和 DSH-better-sidebar（双工作台界面增强）。

写一个最小插件也不难，核心就是三步：建插件目录、用 defineTool 注册一个工具、在 cordis.yml 里声明加载。工具的结构就是四个字段——parameters 告诉模型该传什么、execute 真正执行、output 约定返回格式。官方文档有完整的最小示例。

九、常见坑

• Node 版本过低：启动直接失败。装 ^22.19.0 || >=24.0.0，别用 20。
• 3080 端口被占：npx @deepseek-ai/dsh web --port 8080，访问地址跟着变。
• npm 下载慢/超时：先切 https://registry.npmmirror.com。
• 源码安装后 Web 页面缺东西：pnpm run build 没执行或没执行完。这步不能省。
• 浏览器打不开界面：确认跑 dsh 的终端还开着，服务是前台进程，终端关了服务就没了。

十、和 Claude Code / Codex 怎么选

我的看法：dsh 现在最大的价值是低成本 + 可扩展 + Web UI 可视化。如果你主力用国产模型、想要 Token 花得明白、喜欢在浏览器里看 agent 干活的过程，它值得一试。如果你要的是生产环境里绝对稳定、文档完备的工具，等它再迭代几轮也不迟——反正开源，随时可以回来。

项目 2026-08-13 才开源，到这篇文章落笔只有六天，五万 star，社区教程一天一个样。写这种文章最有意思的地方是：等你看完这篇文章，它可能已经又变了一版。以官方仓库 README 为准。

On August 13, 2026, DeepSeek open-sourced a project called deepseek-harness (CLI: dsh). It hit 50,000+ GitHub stars in one day.

Click into the repo and you'll notice something odd: the README is roughly 1,700 characters, no screenshots, no feature list, doesn't even explain "what is this thing" — just one line: Everything is a Plugin.

But the buzz is real, for a simple reason: it fills the missing layer between "large model" and "getting work done." The model is the brain; the harness is the hands and the operating system — reading and writing files, running terminal commands, calling tools, executing automation flows. The comparison targets are Claude Code and OpenAI Codex.

This article is based on the official README and community hands-on tutorials published before 2026-08-19. The project is in developer preview and iterating fast; commands may change. The official repo is the source of truth.

I: What it actually is

One sentence: Model + Harness = a complete agent.

A chat model only outputs text; you copy, paste, and do the work yourself. DeepSeek Harness wraps a runtime framework around the model:

• Direct local file read/write
• Terminal command execution
• A workspace that bounds what the agent can touch
• Built-in Web UI showing task flow, tool calls, and token usage
• Every capability is a plugin — pluggable, replaceable, authorable

Under the hood it's built on the Cordis plugin system: file editing, command execution, web search, model adapters — each capability is an independent plugin, and which ones load is up to you. That's what "Everything is a Plugin" means: not a marketing slogan, the actual architecture.

II: Prerequisites

One hard requirement: Node.js. Officially ^22.19.0 || >=24.0.0 — when in doubt, install the Node 24 LTS line. A too-old Node fails at startup; it's the #1 beginner error.

node -v   # must be v22.19+ or v24+
npm -v

In China, switch npm to a mirror first or dependency downloads will test your patience:

npm config set registry https://registry.npmmirror.com

III: Installation — three paths

Fastest: npx

npx @deepseek-ai/dsh web

First run downloads dependencies (1–2 minutes), then starts a local web server. Open in your browser:

http://127.0.0.1:3080

Global install (daily use)

npm install -g @deepseek-ai/dsh
dsh web

From source (plugin dev / reading code)

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build    # don't skip this — deps alone won't produce the web assets
pnpm dsh web

There's also a Python SDK (pip install deepseek-harness-sdk) with a bundled runtime — no system Node.js needed if you want to drive the agent from your own programs.

IV: First-run setup

Open http://127.0.0.1:3080 and follow three steps:

1. Configure the model: Settings → Models, paste your DeepSeek API key (create one at platform.deepseek.com/api_keys). The model route works immediately — no server restart.

2. Add a workspace: pick your project directory. The workspace is the agent's operating boundary — it can only touch files inside it. This is the first line of file safety. The input box stays disabled until a workspace is selected.

3. Choose a permission mode:

If the English UI bothers you, Settings in the bottom-left corner can switch the interface to Chinese.

V: Four run modes

DSH ships four agent presets — really, different combinations of "which tools load and how the loop runs":

Standard: everything. File editing, shell, web search, subagents, workflow automation. Covers 90% of daily dev. Start here.

PTC (Programmatic Tool Calling): instead of the model clicking tools one at a time across five round-trips, the model writes a TypeScript program that composes multiple steps at once, executed via run_code. Five round-trips collapse into one. For power users and batch automation.

Minimal: just two tools — a persistent bash terminal and str_replace_editor for path-based edits. Lowest token usage. For quick edits and commands.

Create: everything in Standard plus the ability to modify the harness itself — inspect the runtime, test plugins, write new agent presets (they land in ~/.dsh/.agent-presets/). For plugin developers.

VI: Model configuration — not just DeepSeek

DeepSeek's official API is the default, but dsh accepts any OpenAI-compatible endpoint, so other models can be plugged in too.

Official presets: Zhipu GLM (provider zai-coding-cn), Alibaba Qwen (qwen-token-plan-cn), Xiaomi (xiaomi) — paste the API key and the model list is pulled automatically.

Custom endpoint (OpenAI-compatible):

Settings → Models → Add custom provider
  Provider ID:  anything you like
  API base:     https://your-endpoint.example.com/v1
  API key:      your key
  Protocol:     openai-completions (or openai-responses)

Click "fetch available models" — if a list comes back, the config is right. Pick what you need, or add model IDs manually (deepseek-v4-pro, deepseek-v4-flash, …). Vendors all live in one interface; switch models mid-task without swapping clients.

VII: Why token usage is low

The most consistently praised point in community testing, driven by two mechanisms:

1. Smart context caching: repeatedly-read code, configs, and tool instructions hit cache, cutting input token cost by 90%+ on hits. Long sessions get cheaper as they go.
2. On-demand plugin loading: instead of stuffing dozens of tool schemas into the context upfront, tools load only when a task needs them.

Community measurements: routine edits and API debugging run 50–300 tokens per task; full-project refactors and batch file processing run 1,000–5,000.

VIII: CLI and the plugin ecosystem

Headless mode — run a task once and print the answer, great for scripts and CI:

dsh --profile headless "Summarize this repository and identify its main packages."

Plugin management:

dsh plugin --profile web add <package>   # install a plugin
dsh --profile web --dump-config          # dump the effective config tree
dsh credentials set <KEY_NAME>           # store a credential

Community plugins are already multiplying — e.g. DSH Vision Toolkit (adds vision to a text-only model: image Q&A, OCR, localization, screenshot diffing) and DSH-better-sidebar (dual-panel UI enhancement).

Writing a minimal plugin is three steps: create a plugin directory, register a tool with defineTool, declare it in cordis.yml. A tool is just four fields — parameters tells the model what to pass, execute does the work, output defines the result shape. The official docs have a complete minimal example.

IX: Common pitfalls

• Node too old: fails at startup. Use ^22.19.0 || >=24.0.0, not 20.
• Port 3080 taken: npx @deepseek-ai/dsh web --port 8080, and the URL changes accordingly.
• npm slow/timeout: switch to https://registry.npmmirror.com first.
• Source install, web UI missing pieces: pnpm run build wasn't run or didn't finish. Don't skip it.
• Browser can't open the UI: the dsh terminal is still running, right? It's a foreground process — close the terminal, kill the service.

X: DeepSeek Harness vs Claude Code vs Codex

My take: right now dsh's real value is low cost + extensibility + a visible web UI. If your main models are domestic, you want token spending you can see, and you like watching the agent work in a browser — try it. If you need battle-tested stability and complete docs in production, let it iterate a few more rounds. It's open source; you can come back anytime.

The project shipped on August 13, 2026 — six days before this article, 50k stars, and the tutorial landscape changes daily. The fun part of writing about it: by the time you finish reading, it may already have changed again. Trust the repo README.