DeepSeek Harness：给模型套上可执行的骨架

01

它是什么：官方开源的「模型底盘」

DeepSeek Harness（命令名 dsh）是 DeepSeek AI 官方开源的 agent harness，2026 年发布并全球公开预览。它解决的问题是：你手上有一个很会说话的模型，但模型本身只会生成文本——读文件、跑脚本、管进度、定时干活这些「手脚」，得靠 harness 来长出来。

官方对它的定位一句话：处理文档、分析表格、写代码、定时任务。它不是某个 IDE 里的补全插件，而是一个独立的任务运行环境——Web UI 或桌面应用，外加一组可组合的插件。仓库基于 Node.js，用 pnpm 管理的 monorepo，MIT 协议，README 同时提供中英文两版。

它最大的架构卖点写在仓库副标题里：Everything is a Plugin（一切皆插件）。模型适配器、工具注册表、界面组件，全部以插件形式挂载，底层是 Cordis 元框架。这意味着它的边界不是写死的——想接别的模型、加别的工具、改界面，走的都是同一套插件机制（详见第 04 节）。

模型来源上，它与 DeepSeek 自家模型天然配套——官网演示界面默认就是 DeepSeek 系模型档位（演示中显示 DeepSeek-V4.1-Flash 及思考强度选项）。接其他模型属于模型适配插件的范畴，预览期的支持范围以文档为准。也正因为它「什么都想干」，它和纯终端编码 agent（Claude Code、Pi 这类）不是竞品关系：前者是通用任务台，后者是代码工作流里的利器。

开发方

DeepSeek AI（官方开源）

命令名

dsh（npm 包 @deepseek-ai/dsh）

语言与运行时

Node.js · pnpm monorepo

协议

MIT

状态

开发者预览（破坏性变更会常态化）

接入端

Web UI · 桌面版（macOS Apple silicon / Windows 64-bit）

架构

Cordis 元框架 · 一切皆插件

仓库热度

27 万+ stars（2026-11）

如果你只有十分钟，按这个顺序读这页就够了：

• 第 02 节——一条命令跑起来，先看到东西再谈概念；
• 第 03 节——在 Web UI 里发第一条任务，学会看执行轨迹；
• 第 04 节——搞懂 harness、插件、Cordis 三个词，之后看任何资料都不迷路；
• 第 06 节——照着做一遍表格分析和定时任务，建立体感；
• 第 07 节——预览期的坑都在这，动手前扫一眼能省很多时间。

02

安装启动：唯一硬依赖是 Node.js

三条路：用 npx 免安装直跑，最省事；全局安装固定一个 dsh 命令；想读源码、改代码就从仓库构建。桌面版不想碰命令行的话，官网直接下载。

# 前提：装好 Node.js（官网明确要求先装 Node）
npx @deepseek-ai/dsh web

# 服务器 / SSH 环境只启动服务，不抢着开浏览器
npx @deepseek-ai/dsh web --no-open

# npx 用的缓存包不会自动更新，要拉最新版显式加 @latest
npx @deepseek-ai/dsh@latest web

# 全局安装，得到 dsh 命令
npm install -g @deepseek-ai/dsh

# 启动 Web UI
dsh web

# 预览期升级：重新全局安装一次即拉到最新版
npm install -g @deepseek-ai/dsh

# 卸载
npm uninstall -g @deepseek-ai/dsh

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

03

第一次任务：从「能打开」到「真干活」

DeepSeek Harness 的主入口是 Web UI，不是纯终端。启动之后的所有操作都在浏览器页面里完成：左边是会话，右边是工作区文件，顶部有插件面板。下面这段把它跑起来。

# 在一个专用目录里启动（别拿系统根目录练手）
mkdir ~/dsh-playground && cd ~/dsh-playground
dsh web

# 浏览器自动打开 http://127.0.0.1:3080
# 在对话框里发第一条任务，比如官网演示的这类：
> 读一下 ./brief.docx，把里面的需求要点整理成一页 Markdown

# 换个任务类型：读代码
> 梳理 ./src 的模块结构，指出最该重构的文件和理由

# 再换个：处理表格
> Data.xlsx 里哪个区域 Q3 环比下滑最大？给出数据依据

• 01

  选好目录再启动

  和其他 agent 一样，工作范围跟着启动目录走。开一个空的 playground 目录，把要处理的文件拖进去（或放好再启动），边界清楚，出错也好收拾。

• 02

  第一条任务从「只读」开始

  总结文档、解释表格、梳理代码结构——这类任务不改文件、不跑命令，最适合建立信任。确认它理解得对，再让它写东西。

• 03

  展开执行轨迹看看

  官网的 Developer tools 里有执行轨迹（trajectory）视图：每一轮的输入、模型、工具调用、耗时都能逐条展开。刚上手时多看轨迹，是理解 agent 怎么干活的最快途径。

• 04

  再让它动文件

  分析类任务跑顺了，换生成类：「按季度汇总销售额，输出一张图表」。它会读表格、算数、产出文件到工作区，你可以直接预览再让它改。

Turn 1 · USER       读一下 brief.docx，整理成一页 Markdown
Turn 1 · TOOL       read   { "file_path": "./brief.docx" }      → 文档全文
Turn 1 · ASSISTANT  需求要点共 6 条，按优先级排列如下…
Turn 2 · USER       把第 3 条展开成可验证的验收标准
Turn 2 · TOOL       write  { "file_path": "./summary.md" }      → 已写入工作区
Turn 2 · TOOL       bash   { "command": "ls -la" }              → 确认文件落盘

官网的轨迹视图里，每次工具调用还能进一步展开输入、结果、schema、耗时四张标签页。上面是按同一结构画的示意——实际界面以你装到的版本为准。

04

核心概念：引擎、底盘与插件

4.1 什么是 harness——引擎与底盘，和「Agent 框架」的关系

把汽车搬出来讲：模型是发动机，harness 是底盘和传动。发动机决定你跑多快，但方向盘、变速箱、轮子全在底盘上——没有底盘，发动机只能原地轰鸣。harness 做的就是这件事：把模型的文本输出解析成工具调用，替你执行（读文件、写文件、跑命令），把结果喂回模型，循环往复直到任务完成。这个循环叫 agent loop，在 DeepSeek Harness 里它本身就是一个插件。

它和「Agent 框架」（LangChain 这类）的区别也用汽车说：框架是造车工具箱——给你零件和图纸，你自己焊一辆；harness 是整车——装上就能开，但引擎盖可以打开，里面的零件（插件）能换能加。刚入门的同学先开整车，想造车了再拆开看，这个顺序比反过来省很多力气。

再往下拆一层，harness 的日常由三件事组成：喂上下文——把任务、文件、历史整理成模型能用的输入；执行工具——模型说要读哪个文件，harness 去读并把结果交回；守住边界——哪些操作直接做、哪些要问人、一切发生在哪个目录。以后评估任何 agent 产品，都可以拿这三件事去套，很快能看出它把力气花在了哪。

4.2 一切皆插件

仓库副标题就是这句。模型适配器（接哪家模型）、工具注册表（有哪些工具可调）、界面组件，全部是插件。你在插件面板里看到的官方插件有：Terminal（让智能体操作终端）、Agent loop（核心循环）、Subagents（子智能体）；实验区还有 Agent teams、Auto approval review、Scheduled tasks、Voice input。连「写插件」这件事本身也被做成了体验——官网演示的 Creator mode 里，用一句「帮我写个番茄钟插件」，它就自己加载插件开发技能、查运行时接口、写包、安装并验证。

# github.com/deepseek-ai/deepseek-harness 顶层目录（节选）
packages/   # 核心包：模型适配、工具、运行时
apps/       # Web UI 等应用
docs/       # 开发者文档
website/    # 官网
SAFETY.md   # 运行前必读的安全须知
README.zh.md # 中文版 README

注意：仓库迭代极快（提交数已过两万五），上面只是帮你建立方位感的节选，以实际仓库为准。

# 1. 反馈与求助
#    GitHub Discussions —— 官方指定的 bug / 建议渠道

# 2. 让插件被找到
#    给插件仓库加 GitHub topic：dsh-plugin

# 3. 日常交流
#    DeepSeek Harness Discord —— README「Community and support」一节有入口

4.3 Cordis：底下的那层元框架

DeepSeek Harness 构建在 Cordis 之上，官方称其设计来自论文《A Programming Paradigm for Spatiotemporal Composability》（时空可组合的编程范式）。你暂时不需要啃论文，概念层面抓住两点就够：第一，插件有统一的生命周期——装载、启动、停用、卸载都是框架管的，插件自己只写业务；第二，插件之间可发现、可组合——一个插件可以查询并调用另一个插件暴露的能力。官网演示里那个写番茄钟的会话，就通过运行时接口（inspect providers、查询 runtime slots）在检视其他插件的状态，这是「可组合」的直接体现。

写 Cordis 插件的具体 API 属于开发者文档的范畴，预览期变动快，本页只讲概念，写代码前以官方文档站为准。

4.4 界面上你每天会碰到的四个东西

打开 Web UI 之后，这四块界面会陪你度过大部分时间——先认脸，后文不再解释：

Workspace（工作区）

任务的读写边界。会话里的文件操作默认落在这里，生成的 xlsx、html、md 都能直接预览。

Plugins（插件面板）

启用/停用官方与第三方插件的地方，分 Official 与 Experimental 两区。

Creator mode（创作模式）

用对话让 harness 给你写插件——官网演示里从一句话到装好的番茄钟插件约五分钟。

Developer tools（开发者工具）

执行轨迹与运行时信息；工具调用展开后有输入、结果、schema、耗时四张标签页。

4.5 模型从哪来

官网演示界面默认搭载 DeepSeek 系模型（演示中显示 DeepSeek-V4.1-Flash 档位与思考强度选项）——自家的 harness 配自家的模型，这条路数和 Claude Code 配 Claude 模型一样。想接其他 provider，走的是模型适配插件：架构上完全支持（模型适配器本来就是插件之一），但预览期具体支持哪些 provider、怎么配置，以文档站当前版本为准，别照抄第三方攻略里的写法。

05

速查表：概念、命令与资源

下面这块表格能搜。项目处于预览期，命令与插件名可能随版本变化——以仓库 README 与文档站为准。忘了某个词，直接搜 插件、web、定时 之类的关键字。

06

实战：从分析一张表到挂上定时器

下面四个步骤串起它最典型的用法，场景与流程均出自官方页面演示过的能力。跟着做完，你对它的能力边界就有体感了。

文档类任务（docx / pdf / md）

总结、改写、格式转换——官网文件类型面板里有 Word、PDF、Markdown。从「只读总结」起步最稳。

表格类任务（xlsx / csv）

汇总、对比、画图——官网演示的招牌场景，见步骤二。

代码类任务（仓库 / 单文件）

梳理结构、修 bug、跑测试——把工作区当仓库用，官网演示含 label.ts 改动与 diff 预览。

周期类任务（周报 / 巡检）

Scheduled tasks 插件接管重复劳动，见步骤三。

步骤一：准备一个专属工作区

mkdir ~/reports && cd ~/reports
cp ~/Downloads/Data.xlsx .
dsh web          # 浏览器打开 127.0.0.1:3080

# 或用 npx 免安装起一个临时实例
# npx @deepseek-ai/dsh web

把要处理的文件放进工作区再启动，智能体的每次读写都发生在你能看见的地方。

步骤二：让它分析表格并产出文件

> 分析 Data.xlsx：按季度汇总各区域销售额，标注同比变化，输出一张柱状图

# 它会读表格 → 计算 → 生成文件到工作区，类似：
已生成 Q4-sales-summary.xlsx 与 chart.html，可在工作区预览

# 看完预览，用一句话继续迭代：
> 同比改成环比，图表配色换成深色，另存一份 PDF 版

已更新 Q4-sales-summary.xlsx，新增 chart.pdf

生成的东西直接预览，不满意就继续对话改。这比手写 Python 脚本快在：迭代是说话，不是改代码——改三版图表的成本是三句话，而不是三次调试。

步骤三：启用 Scheduled tasks，挂上周期任务

在插件面板启用实验性的 Scheduled tasks 插件，然后用一句自然语言约定周期。它解决的问题很具体：总有一类活儿是「每周都得做一遍」的——周报、数据汇总、定期备份检查，人容易忘，定时器不会。官网演示过这个流程——「每周五 17:00（北京时间），汇总本周项目笔记生成周报」——它通过工具生成了一条定时规则，结构大致如下（节选自官网演示界面）：

{
  "prompt": "Summarize this week's project notes in a weekly report.",
  "title": "Weekly project report",
  "weekly": { "time": "17:00:00", "time_zone": "Asia/Shanghai", "weekdays": [5] }
}

weekdays 数组里的 5 表示周五。字段结构以插件当前版本为准——这正是预览期该有的心态。

步骤四：Creator mode 写个小插件收尾

官网演示里最惊艳的一段：对它说「帮我写一个番茄钟插件」，它会自己走完整个开发流程。拆开看官网演示里它做了什么：

• 加载 cordis-plugin-development 技能，进入插件开发流程；
• 检视运行时：inspect providers、查询 runtime slots，确认界面挂载点；
• 写出插件包：package.json 与 client.js（演示中 600+ 行前端逻辑）；
• 调用插件管理器（plugin_manager · install_bundle）安装插件；
• 验证插件运行状态，交付一个悬浮在工作区的番茄钟计时器。

这件事的启示比功能本身重要：插件即产物。你不需要先学 Cordis API 才能动手——先让 Creator mode 生成一个能跑的插件，再读它的源码学结构，比从零啃文档快得多。演示全程约五分钟。

步骤五：验收与收尾

自动化挂上去之后别急着撒手。头两三周每天看一眼定时任务的产出，确认质量稳定再拉长检查间隔；执行轨迹是你验收的主要工具——每周打开轨迹视图，抽查它在计划时间到底执行了什么。建议的验收节奏：

# 每天：定时任务是否如期产出、内容是否可直接用
# 每周：Developer tools 里抽查 1-2 次执行的完整轨迹
# 每次升级 dsh 之后：手动重跑一遍核心任务，观察一周再谈依赖

# 产出文件建议纳入版本控制，变更可回溯
cd ~/reports && git init && git add -A && git commit -m "weekly report baseline"

07

避坑：预览期的四个典型误区

坑一：把它当稳定的 CLI 工具链来依赖

README 用大写字母警告「将有破坏性变更」。这意味着：你写的自动化脚本、依赖的输出格式、记住的界面布局，都可能在下次更新后失效。对策——升级前扫一眼 README 与 Discussions；核心流程在升级后先手动跑一遍；别把不可复现的一次性结果当成可长期依赖的产物。

# 本地装的版本
npm ls -g @deepseek-ai/dsh

# npm 上的最新版本（标准 npm 查询，任何发布的包都适用）
npm view @deepseek-ai/dsh version

# 不一致就升级；升级后先手动跑一遍核心任务再观察
npm install -g @deepseek-ai/dsh

坑二：以为它是纯终端编码 Agent

它和 Claude Code、Pi 那类终端编码工具不同：主入口是 Web UI 与桌面端，写代码只是「文档、表格、代码、定时任务」四类能力之一。如果你要的是轻量终端编码 agent，直接看本站的 Pi Agent 教程或 Hermes Agent 教程，别拿 dsh 硬套那个用法。

坑三：模型与 provider 想当然

官网演示界面默认搭载 DeepSeek 系模型（演示中显示 DeepSeek-V4.1-Flash 档位）。接其他模型走的是模型适配插件——具体怎么配、支持哪些 provider，以文档站当前版本为准。本页刻意没有固化任何配置文件名，因为你现在搜到的「攻略」很可能已经不是这个版本的写法。

坑四：忽略安全边界

它能执行 shell、写文件、装卸插件。仓库把 SAFETY.md 放在 README 里明确要求先读，这不是走过场：给它的目录要专用、要可控；第三方插件在生态早期鱼龙混杂，先读源码再安装；敏感数据（生产配置、客户数据）不要放进工作区。这一条在预览期比在成熟产品里更重要，因为审批与沙箱机制本身也在迭代。

# 1. 专用空目录，不碰系统与生产路径
mkdir ~/dsh-playground && cd ~/dsh-playground

# 2. 运行前先读安全须知
open https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md

# 3. 装第三方插件前，先到插件仓库读源码
#    （认准 dsh-plugin topic 只是发现渠道，不是安全认证）

08

进阶方向与资源

• 官方仓库：github.com/deepseek-ai/deepseek-harness —— README（中英双语）、SAFETY.md、开发指南，一切以这里为准。
• 开发者文档站：deepseek-harness.github.io/deepseek-harness/ —— 插件化 SDK 文档，写插件前必读。
• 官网：deepseek.com/en/harness —— 定位介绍、桌面版下载（macOS Apple silicon / Windows 64-bit）、Cordis 论文入口。
• GitHub Discussions：README 指定的反馈渠道——bug、建议、插件生态讨论都在这里。
• Discord 社区：README「Community and support」一节有入口，插件生态交流的主阵地。
• Cordis 论文：《A Programming Paradigm for Spatiotemporal Composability》——想深挖「一切皆插件」的理论根基再读。
• 中文版 README：仓库根目录的 README.zh.md —— 英文阅读吃力时从这里起步。
• 第三方报道：The New Stack 等技术媒体对其开源发布的报道——看社区怎么解读「一切皆插件」这个架构取向。

09

收尾：照着勾一遍

0 / 5