DeepSeek Harness，简称 dsh，是 DeepSeek AI 的开源 AI 代理工具。如果模型回答了问题，那么该工具就会为她提供帮助：读取和编辑文件、运行命令、保持会话、显示执行轨迹并允许使用插件进行扩展。该项目根据 MIT 许可证分发，并处于公共预览状态。
DeepSeek Harness 的主要思想被表述为“一切都是插件”——字面意思是“一切都是插件”。整个产品都是建立在这个之上的：模型适配器、工具注册表、会话日志、接口，甚至代理周期本身。它基于 Cordis 框架，因此开发人员不仅可以添加新命令，还可以在不分叉内核的情况下替换代理的整个行为。
您可以通过多种方式使用 dsh：通过本地 Web 界面、通过桌面应用程序、从无头模式下的命令行或从 Python SDK。以下是安装、首次启动和功能概述。
你需要什么
Web 界面和 CLI 需要 Node.js。该项目有严格的要求：
- 22.x 系列中的 Node.js 22.19.0 或更高版本。
- 24.x 行中的 Node.js 24.0.0 或更高版本。
- 任何补丁都不支持 Node.js 23.x：该产品线不是 LTS，并且已停止使用。
除了 Node.js 之外，您还需要 DeepSeek API 密钥。它是在 platform.deepseek.com 上的您的个人帐户中创建的。桌面应用程序不需要 Node.js – 环境已经打包在那里。
您可以使用以下命令检查版本：
node -v
通过 npx 安装
了解该项目的最快方法是根本不全局安装任何东西。只需运行：
npx @deepseek-ai/dsh web
该命令将从 npm 下载 @deepseek-ai/dsh 包，设置本地 Web 服务器并在浏览器中打开界面。默认情况下它监听地址：
如果您不需要打开浏览器（例如在远程计算机上），请添加 –no-open 标志：
npx @deepseek-ai/dsh web --no-open
通过 SSH 启动时，dsh 会打印地址，但不会尝试打开浏览器：本地地址由 SSH 客户端或编辑器拥有。
全局安装
如果您经常需要某个工具，那么全局安装会更方便。该软件包提供了 dsh 二进制文件：
npm install -g @deepseek-ai/dsh
dsh web
此后，可以从任何目录使用 dsh 命令。更新以通常的方式执行：
npm install -g @deepseek-ai/dsh@latest
桌面应用程序
对于那些不想持有终端和 Node.js 的人，DeepSeek 发布了桌面版本。它们可以在官方下载页面上找到：
- macOS – Apple Silicon、macOS 13 或更高版本，DMG 格式。
- Windows – 64 位程序集，EXE 格式。
该应用程序使用相同的本地文件，可以在后台执行任务，并以与网络版本相同的方式存储会话。当您不想每次都手动升起服务器时，这对于日常工作来说是一个方便的选择。
从源代码构建
如果您需要完全控制代码、您自己的补丁或插件开发，可以从存储库中收集项目。您将需要 pnpm，并且存储库修复了特定版本，因此您应该首先启用 Corepack：
corepack enable
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
pnpm run build 命令准备包和前端工件，pnpm dsh web 运行已构建的版本而不重建。对于开发，有一种模式 pnpm run dev:web：它会在源更改时构建、启动服务器并重建客户端捆绑包。
首次启动
启动Web界面后，流程如下。
首先，打开设置 → 模型并输入 DeepSeek API 密钥。该密钥保存在文件 $DSH_HOME/.credentials.yaml 中，并且设置中仅保留指向它的链接。设置页面收到已屏蔽的秘密描述，因此无法从界面读回密钥。模型更改从下一个请求开始应用；无需重新启动服务器。
然后通过选择工作区选择您的工作文件夹。当未选择工作区时，任务输入字段将保持灰显状态。这是有意这样做的：代理必须了解允许读取和更改文件的边界。
之后，您可以提交第一个任务。例如：
Summarize this repository and identify its main packages.
代理将阅读项目、制定计划、调用必要的工具并显示结果。对于需要根据当前访问策略进行确认的操作，dsh 会在执行前进行询问。
模型和提供商
DeepSeek 一步连接：设置中的提供商卡仅包含 API 密钥字段。此外，您可以添加第三方服务。内置目录知道诸如 anthropic、openai、moonshotai（Kimi）和 zai（GLM）之类的标识符。
对于您自己的网关、公司代理或本地服务器，有一种自定义模型 API 模式。它问：
- 永久提供商标识符；
- 显示名称；
- API基地址；
- 协议：OpenAI 聊天完成、OpenAI 响应或人择消息；
- 密钥和型号列表。
协议很重要：一个提供商讲一种协议。如果网关同时支持 OpenAI 和 Anthropic，则必须由两个提供商对其进行描述。对于模型，您可以指定上下文窗口的大小、输出标记的最大数量以及支持的输入数据类型（包括图像）。
DeepSeek 模型具有关闭、低、高和最大推理级别。在模型旁边的Effort菜单中选择级别。对于存储库中的例行任务，快速模型就足够了，但对于复杂的架构任务，增加工作量或采用更高级别的模型是有意义的。
插件和创建者模式
插件是 DeepSeek Harness 的主要功能。通过它们，可以添加工具、技能、界面元素和整个应用程序。该界面有一个插件管理器，包含官方和实验集：代理命令、自动确认、计划任务、语音输入、终端、子代理。
创作者模式单独脱颖而出。在这种模式下，你可以直接在聊天中要求客服人员编写插件。它将下载 Cordis 插件开发技能，创建包结构，编写代码，安装插件并检查其状态。官方项目页面上有一个例子，浮动番茄计时器就是这样组装的。
插件也可以从命令行安装。对于 Web 配置文件，命令如下所示：
dsh plugin --profile web add some-dsh-plugin
支持 Npm 包、github:owner/repo 等链接、本地目录和 tgz 存档。安装后，检查插件层是否确实包含在配置中非常有用：
dsh --profile web --dump-config
该命令在不启动服务器的情况下打印组装的插件树。如果没有新层，则捆绑包很可能没有声明 dsh.bundle 清单并作为常规库安装，而不是作为包含的插件安装。
实验设置包括自定义插件市场。这是一个索引 JSON 文件，其中包含插件列表、版本、图标和来源。通过启用该集，您可以在插件页面上获得发现选项卡以及连接第三方市场的能力。与任何第三方来源一样，只有当您信任其作者时才应添加这样的市场。
轨迹和审核
对于每个会话，dsh 都会写入一个仅附加事件日志 – Trajectory。它存储系统提示、推理、工具调用及其结果、子代理调度和上下文插入。会话恢复、分叉、搜索和重放都建立在该日志之上。
实际的好处是对话不再是一个黑匣子。在界面中，您可以打开轨迹并查看调用了哪些工具、每个步骤花费了多长时间、更改了哪些文件以及请求花费了多少令牌。如果客服人员行为异常，原因通常可以在此处看到，而不是在聊天中的简短回答中。
会话以 JSONL 日志的形式位于 ~/.dsh/sessions 中。您可以阅读它们、搜索它们并构建您自己的分析。这也使得准确计算常规 API 账单中不可见的费用和缓存命中成为可能。
后台任务和时间表
DeepSeek Harness 不仅可以在“询问并接收答案”模式下工作。任务可以在后台启动并计划。例如，要求代理商每周五 17:00 从项目笔记中收集周报。在界面中，此类任务是单独可见的：您可以检查状态、查看历史记录和打开执行详细信息。
有一个用于自动化的无头配置文件。它启动一个会话，打印最终响应，然后退出：
dsh --profile headless "run the tests"
此模式对于不需要 Web 界面的 CI、cron 和脚本来说很方便。除了 headless 之外，还提供 sdk 和 acp 配置文件：第一个通过 JSON-RPC 为 SDK 客户端提供服务，第二个通过 ACP stdio 为自动化客户端提供服务。
子代理、MCP 和技能
复杂的任务可以分解为子代理。主要代理负责规划工作，各个子代理则在各自的领域内工作。这有助于保持上下文紧凑，而不是将整个历史记录拖到每个请求中。
外部工具和数据源通过 MCP 连接。该文档包括内存 MCP 的单独指南，以及 GitHub 审查会议等集成。技能描述了代理根据需要加载的可重复过程，而不是始终将所有指令保留在系统提示中。
配置文件、捆绑包和补丁
dsh 配置由三层组装而成。 Bundle 是一组配置行和插件代码，即一个现成的功能。 Profile 是捆绑包的命名组合，存储在 $DSH_HOME/profiles/
应用程序的顺序如下：首先是配置文件顺序中的捆绑包，然后是配置文件补丁，然后是常规补丁$DSH_HOME/cordis.patch.yml，最后是通过–patch传输的覆盖层。这意味着几乎任何设置都可以被覆盖，而无需触及捆绑包源。您可以使用以下命令查看生成的树：
dsh --profile web --dump-config
标准 Web 配置文件称为 web，无服务器配置文件称为 headless。它们的设置文件位于 $DSH_HOME/profiles/web/cordis.patch.yml 和 $DSH_HOME/profiles/headless/cordis.patch.yml 中。这是 dsh 写入通过设置界面所做的更改的位置。
Python SDK
Python 项目有一个官方 SDK。它安装在虚拟环境中，并自带原生运行时，因此正常工作不需要系统 Node.js：
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install deepseek-harness-sdk
一个最小的启动示例如下所示：
from pathlib import Path
from deepseek_harness import DeepSeekHarness
workspace = Path("C:/work/disposable-workspace").resolve()
dsh_home = Path("C:/work/example-dsh-home").resolve()
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
max_tokens=49_152,
cwd=str(workspace),
dsh_home=str(dsh_home),
profile="sdk-minimal",
) as harness:
result = harness.run(
"Inspect the repository and fix the failing tests.",
session_id="example-001",
)
print(result.final_response)
SDK 使用 sdk-minimal 配置文件启动捆绑的 dsh 进程，并在退出上下文管理器之前重用它。最小配置文件是有意限制的：它具有 bash 或 pwsh、图像读取和工作目录，但没有 Web 工具、子代理或某些文件工具。对于一次性任务来说，这是一个优点：需要控制的表面更少。
需要注意什么
DeepSeek Harness 是开发者预览版本 0.1.0-rc.x。自述文件明确警告兼容性将被破坏。对于实验、个人项目和自动化来说，这很好，但对于现在赚钱的流程来说，值得权衡风险并保留备用计划。
第二点是Node.js。如果您使用的是 22.18 或 23.x，安装将崩溃或行为不可预测。提前检查版本：该项目使用node:sqlite和TypeScript内置的需要新分支的类型擦除。
第三点是沙箱和权限。默认情况下，代理以接近工作区写入的策略运行：它可以更改所选文件夹中的文件，并且潜在危险的操作需要确认。危险全通模式给予了更多的自由，但风险也更高。在尝试真正的存储库之前，进行提交或备份很有用。
第四点是成本。 DSH 本身是免费的，但为了推断，您需要向提供商支付代币费用。对于长会话，前缀缓存很重要：dsh 组合请求，以便历史记录和工具架构尽可能长时间保持不变。如果分数高于预期，不仅要查看每个代币的价格，还要查看轨迹中现金命中的份额。
值得尝试吗
DeepSeek Harness 主要是那些不仅想要“与模特再次聊天”，而且想要为代理提供受控环境的人感兴趣的人。有一个透明的轨迹、文件和命令的正常工作、后台任务、子代理以及通过插件的真正深度扩展。用自己的代理循环替换代理循环的能力很少见，并且对于研究和自定义编排可能非常有用。
如果您需要一个稳定的工具来进行日常有偿工作，那么现在更明智的做法是将 dsh 视为主要代理旁边的第二个代理：在个人项目上尝试它，比较任务的成本和质量，然后才将其转移到工作流程中。
链接
https://www.deepseek.com/harness/
https://www.deepseek.com/download/
https://github.com/deepseek-ai/deepseek-harness
https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart
https://deepseek-harness.github.io/deepseek-harness/en/guide/providers
https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk
https://platform.deepseek.com/
来源
https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md
https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.md
https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart
https://deepseek-harness.github.io/deepseek-harness/en/guide/providers
https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk
https://deepseek-harness.github.io/deepseek-harness/en/guide/plugin-market
https://dshdocs.com/getting-started/installation/
https://dshdocs.com/concepts/profiles-bundles-patches/
https://dshdocs.com/guides/dsh-vs-claude-code/
Leave a Reply