DeepSeek Harness Python SDK 上手

DeepSeek 官方开源的 agent 框架 DeepSeek Harness（命令行工具名为 dsh）此前主要靠 Web UI 交互使用，官方文档里的 Python SDK 教程则给出了另一条路：一切皆可编程。装上已发布的 deepseek-harness-sdk，先跑通仓库内置的示例组合，再把它嵌进自己的程序，调用的是同一套 API。本文把这条路径完整走一遍。

先看环境够不够

SDK 对系统的要求不高：Python 3.10 或更新版本，加上 Git。平台支持 Linux x64、Linux arm64，以及 macOS 14 及以上版本的 arm64 机器。另外需要准备两样东西：一个 DeepSeek 兼容的 API 端点与凭据，一个允许 agent 修改的隔离 workspace。

这个项目目前处于开发者预览阶段，以 MIT 协议开源。官方明确提示正在快速迭代，未来会出现破坏兼容性的变更，拿来做生产系统要有心理准备。

安装：克隆仓库，装 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

值得注意的一点是，SDK 自带同版本的内置运行时，装完即用，不依赖系统安装的 Node.js。只有需要从源码构建运行时或 wheel 包的仓库贡献者，才要走仓库的 Python 贡献者工作流。

安装与首次运行示例的完整终端流程

跑通内置示例

先在环境里设置凭据。默认走 DeepSeek 官方端点；如果模型由 OpenAI 兼容代理提供，还要设置 DEEPSEEK_BASE_URL。模型名与系统提示词分别由 DSH_MODEL 和 DSH_SYSTEM_PROMPT 两个环境变量控制，不设就落回默认值。

export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

然后针对隔离的 workspace 和会话目录跑一个任务：

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."

脚本会打印 assistant 的最终回复；会话目录里则落了一份 JSONL 日志，完整记录组装后的模型请求与每一次工具调用，事后排查全靠它。

嵌进自己的程序

内置示例 minimal.py 其实只是下面这次 SDK 调用的轻量包装：

python

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)

几个参数值得说明：provider 指定 deepseek-official；model 当前为 deepseek-v4-flash；max_tokens 上限 49152；cwd 传入 agent 可用 workspace 的绝对路径；session_root 指定会话日志与状态的存放目录；cordis 指向一份组合配置文件。

DeepSeekHarness 会延迟启动内置运行时，并在整个上下文管理器存续期间复用它。会话的持久性藏在 session id 里：复用同一个 harness 与 session id，会话拥有的 Bash 进程原样保留，工作目录、导出的环境变量、shell 函数都还在；独立任务就该换新的 session id，只有下一次调用要延续同一段持久对话时，才复用旧 id。

DeepSeekHarness 的调用链路与会话持久化要点

示例组合到底给了模型什么

这份内置组合刻意做得很薄，关键配置一目了然：

配置项	值
系统提示词	DSH_SYSTEM_PROMPT，未设置时回退到默认英文提示词
模型解析顺序	命令行 --model，其次 DSH_MODEL，最后 deepseek-v4-flash
面向模型的工具	仅持久 bash 与 str_replace_editor
Bash 超时	300 秒
编辑器输出上限	16000 字符
上下文压缩	关闭
文件系统	裸本地后端，编辑器用绝对路径，可访问运行时进程可见的任何路径
会话持久化	DSH_SESSION_ROOT 下未压缩的 JSONL

组合里没有 harness 身份、workspace 提示词文本、技能、一次性 Bash、任务工具，也没有上下文压缩，其余面向模型的插件一概省略。沙箱策略相关的事实只作为运行时用户上下文记录，不会追加进系统提示词。想要更完整的能力，方向是往组合配置里加插件，而不是改 SDK 调用方式。

workspace 与 session id 怎么选

职责划分很清楚：cwd 决定 agent 能看到哪个 workspace，session_root 决定会话日志和状态存在哪。独立任务用新 id，要延续对话与持久 shell 状态才复用旧 id，这条原则贯穿始终。

安全上要格外当心：示例组合用的是 danger-full-access 档位，Bash 与编辑器能改动运行时进程有权访问的任何路径，所以只能在可丢弃的 checkout 或容器里运行。另外，持久 PTY 后端依赖 POSIX 终端环境，这套组合不支持 Windows agent。

小结

对想把 agent 塞进自动化流水线的团队来说，这条 Python 路线比反复点 Web UI 现实得多：安装即用、会话可持久、每一步行为都在 JSONL 日志里可查。想再深入，仓库中的 jsonrpc-agent 示例说明覆盖了组合细节，Python SDK 参考文档讲透了生命周期、结果、通知、运行时选择与配置，Cordis 入门文档则解释了组合语法，可以按需延伸阅读。