DeepSeek Harness Python SDK

DeepSeek Harness Python SDK

Web UI 适合人盯着看，但要在程序里调用 dsh，就需要 SDK。Python SDK 把 dsh 变成程序里的一行调用：核心类 DeepSeekHarness 用上下文管理器管理运行时生命周期——进入 with 块时延迟启动内置运行时，退出时自动释放，中间可反复调用 run。适合批处理任务、把 dsh 集成进自己的产品、在测试里驱动 Agent。SDK 装好后运行时不依赖系统 Node.js，Python 进程自带一份。

前置要求

依赖	要求
Python	3.10 或更高版本
Git	已安装
操作系统	Linux x64、Linux arm64、macOS 14+（Apple 芯片）、Windows x64
API 端点	DeepSeek 兼容的 API 端点与凭据
工作区	agent 可以修改的隔离 workspace 与隔离的 dsh home

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

Windows PowerShell 用 py -3.10 -m venv .venv 创建环境，再用 .venv\Scripts\Activate.ps1 激活。注意：示例与 SDK 绝不会静默读取 ~/.dsh，必须显式传入 home 路径。

运行仓库内置示例

仓库自带 minimal.py（位于 python/sdk/examples/），跑通它等于验证整条 SDK 链路。先设置凭据：

$ 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.'

模型若由 OpenAI 兼容代理而非默认 DeepSeek 端点提供，还需设置 DEEPSEEK_BASE_URL。随后针对隔离的 workspace 和 dsh home 运行任务：

$ python python/sdk/examples/minimal.py \
  --workspace /absolute/path/to/disposable-workspace \
  --dsh-home /absolute/path/to/example-dsh-home \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

脚本会打印 assistant 的最终回复；指定的 home 下会保存生成的 sdk-minimal profile、已安装插件，以及 sessions/ 目录下的未压缩 JSONL 会话日志。

在自己的程序中使用

内置示例其实是下面这段调用的轻量包装：

from pathlib import Path

from deepseek_harness import DeepSeekHarness

# agent 可访问的 workspace，必须是绝对路径
workspace = Path("/absolute/path/to/disposable-workspace").resolve()

# 隔离的 dsh home：保存 profile、插件与会话日志，必须是绝对路径
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()

# 上下文管理器：进入时延迟启动内置运行时，退出时自动释放
with DeepSeekHarness(
    provider="deepseek-official",   # 使用 DeepSeek 官方提供方
    model="deepseek-v4-flash",      # 模型名，SDK 默认也是它
    max_tokens=49_152,              # 单次回复的最大 token 数
    cwd=str(workspace),             # 把 workspace 设为 agent 的工作目录
    dsh_home=str(dsh_home),         # 隔离的 dsh home
    profile="sdk-minimal",          # 随附的极简 profile
) as harness:
    # 发送一个任务；session_id 用于标识这段持久化对话
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

# 打印 assistant 的最终回复
print(result.final_response)

DeepSeekHarness 会延迟启动内置的 dsh --profile sdk-minimal 进程并持续复用，同一 harness 可在 with 块里多次调用 run，运行时只启动一次。若换自定义 profile，配置里必须包含一个 JSON-RPC server 插件（如 @deepseek-ai/dsh-sdk-app），否则启动失败。

复用 session id：保留 Bash 进程

这是 SDK 最容易被忽略、也最有用的规则：复用同一个 harness 与 session id，会保留该会话拥有的 Bash 进程——包括工作目录、已导出的变量与 shell 函数，全部延续到下一次调用。

# 第一次调用：在 izzi-workspace 里导出一个变量
result = harness.run(
    "Run `cd /repo && export IZZI_MODE=dev` and confirm.",
    session_id="izzi-session",
)
print(result.final_response)

# 第二次调用：复用同一个 session id，那个导出的变量还在
result = harness.run(
    "Print the value of IZZI_MODE.",
    session_id="izzi-session",
)
print(result.final_response)

独立任务应使用新的 session id；只有需要延续同一段持久化对话时才复用原有 id。

sdk-minimal 组合一览

属性	值
系统提示词	DSH_SYSTEM_PROMPT；未设置时用 "You are a helpful software engineer assistant."
模型	--model 参数优先，其次 DSH_MODEL，最后 deepseek-v4-flash
面向模型的工具	持久 bash（Windows 为 pwsh）、read_image 与 working_directory
Bash 超时	300 秒
上下文压缩	自动执行：达到阈值时通过额外模型请求生成较早历史摘要
持久化检查点	已启用：模型请求前等待历史刷盘，保证崩溃后恢复一致
会话持久化	<dsh_home>/sessions 下未压缩的 JSONL
权限	固定 danger-full-access，只能在可丢弃环境中运行

该组合在空根之上插入完整配置树，不包含 dsh-base，因此基础 profile 以后新增的工具不会隐式出现。

显式启用 str_replace_editor

随附运行时包含 str_replace_editor，但 sdk-minimal 默认配置树不挂载它。需要文件编辑工具时，把下面的配置存成 editor.patch.yml：

# 文件路径：editor.patch.yml
# insert 会添加编辑器工具，并复用已有的文件系统后端
- insert:
    - id: tool-str-replace-editor
      name: '@deepseek-ai/dsh-tool-str-replace-editor'

构造 DeepSeekHarness 时传入 patches 参数即可单次生效：

with DeepSeekHarness(
    profile="sdk-minimal",
    patches=("/absolute/path/to/editor.patch.yml",),  # 单次启动追加的 patch
    # ...其余参数同上
) as harness:
    ...

想持久生效就把这段 patch 写进 $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml；该 patch 同样适用于标准 sdk profile。插件管理用 dsh plugin 命令：先设置 DSH_HOME 并执行一次 dsh --profile sdk-minimal --dump-default-config 初始化 profile，再用 dsh plugin --profile sdk-minimal add file:/path/to/my-plugin-bundle 安装——只有管理命令需要 pnpm，启动 SDK 本身不需要。

会话日志上传与 danger-full-access 边界

sdk-minimal 默认带一个会话日志贡献器：每次 DeepSeek 请求会随请求上传未落定的事件（每次最多 8 MiB），用于平台侧诊断，不增加模型输入 token。不希望上传时在 profile patch 中关闭：

# 文件路径：$DSH_HOME/profiles/sdk-minimal/cordis.patch.yml
# 按 id 覆盖该行配置，关闭会话日志上传
- id: session-log-deepseek
  config:
    enabled: false

另外必须清楚 danger-full-access 的边界：它只能在可丢弃的 checkout 或容器内运行，Bash 与文件访问可以修改运行时进程有权访问的任何路径，没有沙箱兜底；Windows 上持久 shell 使用 pwsh，同样无路径限制。拿它跑真实项目前，先确认这个环境弄坏了也不心疼。