DeepSeek Harness Python SDK 入门

DeepSeek Harness 是 DeepSeek AI 开源的智能体框架，采用一切皆插件的架构，由 Cordis 驱动，目前在 GitHub 上处于开发者预览阶段。多数用户的第一入口是 npx @deepseek-ai/dsh web 启动的 Web UI，但做批处理、CI 集成或后端服务时，更需要程序化的调用方式。官方为此提供了 Python SDK，本文整理它的上手路径：安装、跑通内置示例，再到在自己的代码里驱动同一个智能体运行时。

环境与前置要求

开始之前需要准备：

Python 3.10 或更高版本
Git
Linux x64、Linux arm64，或 macOS 14 及以上版本的 arm64
一个 DeepSeek 兼容的 API 端点与凭据
一个允许 agent 修改的隔离 workspace

值得说明的是，SDK 安装时会自带同版本的内置运行时，运行环境不需要装 Node.js，这对 CI 与容器场景很友好。

安装 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

deepseek-harness-sdk 是 PyPI 上的发行包，导入模块名是 deepseek_harness。安装时它会同时装上同版本的 deepseek-harness-runtime-bin 平台 wheel，运行时以单文件可执行程序的形式打包。只有想从源码构建运行时或 wheel 包的仓库贡献者，才需要走 Python 贡献者工作流。

运行内置示例

先设置凭据。如果模型不是由默认 DeepSeek 端点提供，而是走 OpenAI 兼容代理，还要设置 DEEPSEEK_BASE_URL：

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 日志，里面记录了组装后的模型请求与每一次工具调用，事后可以完整复盘 agent 的行为轨迹。

DeepSeek Harness Python SDK 快速上手流程

在自己的程序里调用

内置示例其实是一段 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)

有几个生命周期细节值得注意。DeepSeekHarness 会延迟启动内置运行时，并在整个上下文管理器期间持续复用这个子进程，退出时自动收尾，也可以在不用上下文管理器时显式调用 close()。run() 返回的结果对象携带 final_response、finish_reason、events、notifications 等字段，其中 finish_reason 描述这一轮结束的原因，例如正常完成、达到 token 上限或出错。复用同一个 harness 与同一个 session id，会保留该会话名下的持久 Bash 进程，包括它的工作目录、已导出的变量与 shell 函数；独立任务应当使用新的 session id，只有下一次调用确实要延续同一段持久化对话时，才复用原有 id。

DeepSeek Harness Python SDK 调用链与持久化

示例组合的能力边界

minimal.py 挂载的是一份刻意精简的组合，关键配置如下：

属性	值
系统提示词	`DSH_SYSTEM_PROMPT`，未设置时使用默认的软件工程助手提示词
模型	`--model` 参数优先，其次 `DSH_MODEL`，最后默认 `deepseek-v4-flash`
面向模型的工具	仅持久 `bash` 与 `str_replace_editor`
Bash 超时	300 秒
编辑器输出上限	16,000 个字符
上下文压缩	关闭
文件系统	裸本地后端，编辑器使用绝对路径
会话持久化	`DSH_SESSION_ROOT` 下未压缩的 JSONL

这份组合省略了 harness 身份、workspace 提示词文本、技能、一次性 Bash、任务工具、上下文压缩等其余面向模型的插件；沙箱策略事实会作为运行时用户上下文记录，而不会追加进系统提示词。换句话说，它贴近一个干净的最小编码智能体：模型手里只有 bash 和一个字符串替换编辑器，其余能力都要靠组合按需挂载。

workspace 与 session id 的选择

cwd 决定 agent 能访问的 workspace，session_root 决定会话日志和状态的存放位置。两者都应指向隔离目录；不要让多个无关任务共享同一个 session id，否则持久 shell 状态会互相影响。

安全方面必须强调：这个组合使用 danger-full-access 策略，Bash 与编辑器可以修改运行时进程有权访问的任何路径，因此只能在可丢弃的 checkout 或容器内运行。另外，持久 PTY 后端依赖 POSIX 终端环境，这个组合不支持 Windows agent。

小结

对想在脚本和后端服务里复用 DeepSeek Harness 的开发者来说，这条路径的价值在于：装一个 pip 包就能得到带完整运行时的智能体进程，用 session id 管理对话的延续与隔离，用 JSONL 日志拿到全程可审计的执行记录。项目仍处于开发者预览阶段，官方也明确提示未来会有破坏性变更，生产环境使用前建议锁定 SDK 版本。想深入的话，仓库中的 examples/jsonrpc-agent/README.md 拥有该组合的完整定义，python/sdk/README.md 覆盖生命周期、结果与通知语义，docs/cordis-primer.md 则介绍组合语法。