DeepSeek Harness Python SDK 快速上手（附完整代码）

Web UI 适合人机交互，但很多场景需要一个能在代码里调用的入口：CI 流水线里让 agent 跑测试修复、批处理脚本里处理一串仓库、自研工具里嵌入 agent 能力。这时候就用 Python SDK——它和 Web UI 底层是同一套 API，界面能做的事，代码都能做。

什么时候用 SDK，什么时候用 Web UI

场景	选择
探索性任务、看 agent 一步步干活	Web UI（有轨迹、有审批弹窗）
CI/自动化/批量任务	Python SDK（`harness.run()` 拿结果）
在自己的程序里嵌入 agent	Python SDK

前置条件

Python 3.10+ 与 Git（克隆仓库用示例）
系统：Linux x64 / Linux arm64 / macOS 14+ arm64
一个 DeepSeek 兼容的 API 端点与密钥
一个隔离的 workspace 目录——专门给 agent 折腾，别用真实项目练手

装好 SDK 后，内置运行时不需要系统有 Node.js——这点对 CI 环境很友好。

安装

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 本身，venv + pip 两步就够。

先跑通内置示例

设置凭据后直接跑仓库自带的示例脚本，先验证整条链路：

export DEEPSEEK_API_KEY=sk-your-key-here
# 走 OpenAI 兼容代理时才需要下一行
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1

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 的最终回复
--session-root 目录下出现 JSONL 日志——组装后的模型请求和每次工具调用都在里面，排查问题非常有价值

在自己的代码里调用

示例脚本本质上是下面这段的包装，核心只有一个类：

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` / `model`	模型路由：哪家提供商、哪个模型
`cwd`	工作区目录——agent 读写文件、执行命令都发生在这里
`session_root`	会话落盘目录（JSONL 日志、会话状态）
`cordis`	组合配置文件——决定这个 agent 挂哪些工具、用什么系统提示词。这就是"一切皆插件"的入口，先照用，机制见 2.3 配置层与 patch：叠加规则详解
`session_id`	会话身份，直接决定"新对话"还是"接着聊"（见下）

最容易被忽略的一点：session_id 的复用语义

session_id 不只是个日志文件名，它决定了状态是否延续：

复用同一个 DeepSeekHarness 实例 + 同一个 session_id → 该会话的 Bash 进程被保留：工作目录、export 过的变量、定义的 shell 函数全都还在
换新的 session_id → 全新会话，环境归零

所以两条纪律：

独立任务用新 id——批处理循环里每单一个 id，任务之间不串味
只有"接着上一段对话"才复用 id——比如第一步改代码、第二步让 agent 继续跑测试，必须同 id 才能看到第一步的改动

反例：跑了一批任务都用同一个 id，第二个任务会"继承"第一个任务的 shell 状态，轻则困惑重则事故。

常见坑

现象	处理
`FileNotFoundError` 指向 cordis 文件	`cordis` 参数必须指向真实存在的 yml，示例里用 `.resolve()` 转绝对路径
agent 改了不该改的文件	`cwd` 没设对。始终指到隔离 workspace，别用 home 目录
复用 id 但环境"没继承"	确认是同一个`DeepSeekHarness` 实例；新实例 + 旧 id 不保证 shell 进程延续