DeepSeek Harness 使用指南：从安装到跑通你的第一个 agent

本文基于 DeepSeek Harness（dsh）当前开发者预览版整理，命令与配置以官方文档为准。它正处于快速迭代阶段，未来会出现破坏兼容性的变更。

DeepSeek Harness 是什么？

DeepSeek Harness（简称 dsh） 是由 DeepSeek AI 开发的开源 agent harness（智能体框架）。

它不是又一个大模型，而是一套”让大模型动起来干活”的运行时：给它一个工作区、一段目标、一组工具，它就能自主地读文件、写代码、跑命令、委派子任务、维护计划，直到完成目标。

它的几个关键特点：

一切皆插件：核心能力（LLM 接入、工具、Web UI、headless、持久化……）都拆成插件，通过组合包自由拼装。
由 Cordis 驱动：底层用 Cordis 插件容器实现插件生命周期与组合，设计思想见论文 A Programming Paradigm for Spatiotemporal Composability。
多形态入口：网页端（Web UI）、命令行（CLI / headless）、Python SDK 都能用。
配置分层叠加：内置组合包 → 配置文件 → 用户覆盖层，逐层叠加出最终行为。

快速开始

1. 环境要求

Node.js（npx 需要）。从源码跑时要求 node ^22.19.0 || >=24.0.0，且用 pnpm@11.7.0。
一个 DeepSeek API Key（或任意 OpenAI 兼容端点 / 其他提供方密钥）。
一个隔离的工作区目录（agent 会在上面读写文件、跑命令）。

2. 一行启动 Web UI

无需克隆源码，Node.js 装好后直接：

1	`npx @deepseek-ai/dsh web`

启动后访问 http://127.0.0.1:3080 即可。

3. 从源码运行（推荐给想深入/开发的用户）

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

使用 Web UI 跑通第一个任务

第一步：配置模型

打开 设置 → 模型：

DeepSeek 卡片：直接填入你的 DeepSeek API 密钥并保存，模型路由立即可用，不需要重启服务器。
其他提供方（Anthropic / OpenAI 等）：点”添加提供方”输入密钥。
自定义端点 / 公司网关：点”添加自定义提供方”，填 Provider ID、基础 URL、API 协议、凭据和至少一个模型。

几点说明：

密钥是只写的：保存后页面只显示脱敏描述符，明文密钥存在 $DSH_HOME/.credentials.yaml。
Provider ID 一旦创建就是永久的（请求、会话、凭据引用都用它），重命名就走”新建+删除”。
模型变更在下一次请求生效，无需重启。

第二步：选择工作区

点击选择工作区，添加你启动 dsh 时的项目目录并选中。选中工作区前，会话输入框不可用。

第三步：发任务

启动一个会话，发送一句话，例如：

Summarize this repository and identify its main packages.

agent 会读取/编辑工作区文件、运行命令、委派子任务并维护计划；当操作超出当前权限策略需要审批时，Web UI 会先询问你，而不是擅自执行。

常见排错

MISSING_CREDENTIAL：去模型页存密钥，或提供被引用的环境变量。
UNKNOWN_MODEL：在模型选择器里选一个已配置的模型。
获取可用模型 返回 401：检查密钥；该功能调用 OpenAI 兼容的 GET /models，不提供该端点的服务请手动输入模型。

其他调用方式

CLI / headless 模式

dsh 是启动 profile 用的命令，不同 profile 对应不同形态：

命令	用途
`dsh web`	启动 Web UI（`--profile web` 的别名）
`dsh --profile headless "job"`	运行一个全新的持久化会话，打印最终答案并退出
`dsh --profile <name>`	启动指定 profile
`dsh plugin --profile <name> <pnpm args>`	通过 pnpm 管理该 profile 的插件

运行命令时的当前目录就是默认 workspace 根目录。头尾部 flag 约定：

1
2
3

dsh --profile web --port 8080        # --port 是 web app 的参数
dsh --profile headless "run the tests"   # 引号里是任务
dsh --help                           # 启动器自身的帮助

Python SDK

装 SDK：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

设置凭据后跑一个任务：

export DEEPSEEK_API_KEY=sk-your-key-here

python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

或在自己的程序里直接用：

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

用好 session id 的两条经验：

复用同一个 harness + session id 会保留该会话的 Bash 进程（工作目录、已导出的变量、shell 函数都在）。
独立任务用新的 session id；只有下次调用需要延续同一段对话时才复用旧 id。

SDK 组合默认是 danger-full-access，agent 能改运行时进程有权访问的任何路径。请只在可丢弃的 checkout 或容器内运行，别在重要目录上跑。

插件开发：扩展 dsh

dsh 的核心能力几乎都是插件。文档里把插件开发分成两块：

基础插件（basic）

config：声明自己的配置项，暴露给用户覆盖。
tool：给 agent 新增工具（比如自定义的查询接口）。
publish：把你的插件作为 npm 包发布，供他人 dsh plugin 安装；为你的插件仓库加上 dsh-plugin topic 便于被发现。

框架机制（framework）

service：定义可注入的服务。
events：订阅/发布事件。
组合语法基于 Cordis，入门可看 Cordis primer。

配置与目录结构速览

$DSH_HOME：用户级配置与凭据目录，密钥、settings 都在这里。
profile 目录：包含 package.json（插件依赖）、dsh.profile（metadata 清单 + bundles）、cordis.patch.yml（用户 patch 层）。
配置叠加顺序：内置组合包 patch → profile 的 cordis.patch.yml → home 级 $DSH_HOME/cordis.patch.yml → --patch 覆盖层。
用 --dump-default-config / --dump-config 可以在不启动的情况下查看组合后的配置树。

小结

DeepSeek Harness 把”让大模型真正干活”这件事拆成了可插拔、可自由组合的运行时。对普通用户来说，npx @deepseek-ai/dsh web + 填一个 API Key + 选一个工作区 + 发一句话 就能跑通第一个 agent；对开发者而言，CLI、Python SDK 和插件体系提供了更深的扩展空间。

需要踩稳的三件事：

工作区要隔离：别在重要目录上让 agent 全权读写。
API Key 只写不读：存好后看不到明文。
预览版变化快：跟随官方 README 与 Discussions 迭代。

参考资料

AI大模型

#DeepSeek #AI #agent #大模型

DeepSeek Harness 使用指南：从安装到跑通你的第一个 agent

https://zhengcookie.github.io/zhengcookie/DeepSeek-Harness使用指南/

作者

zhengcookie

发布于

2026年1月20日

许可协议

大模型企业级业务场景落地方案实践下一篇