第 5 章 Python SDK：把 Harness 嵌进你自己的程序
命令行适合"跑一次"，Python SDK 适合"在程序里编排"。它让你在自己的 Python 代码里创建 harness、跑任务、拿结果，就像调用一个普通库。
5.1 环境要求（先看这条！）
•
Python 3.10 或更高；
•
Git；
•
Linux x64 / Linux arm64，或 macOS 14+（arm64）；
•
一个 DeepSeek 兼容的 API 端点与凭据；
•
一个 agent 可以修改的隔离工作区。
特别注意：官方明确说明 Python SDK 暂不支持 Windows agent——因为底层持久化 PTY 后端需要 POSIX 终端环境。Windows 用户请用 WSL、Linux 服务器或容器来跑 SDK 示例。
5.2 安装
克隆仓库（拿内置示例），建虚拟环境，安装 SDK：
代码块
Plain Text
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
好消息：安装后的运行时不需要系统再装 Node.js，SDK 自带同版本内置运行时。
5.3 设置环境变量
代码块
Plain Text
export DEEPSEEK_API_KEY=sk-your-key-here
# 如果走 OpenAI 兼容代理，而不是默认官方端点：
# 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.'
如果模型不是默认 DeepSeek 官方端点提供的，务必设置 DEEPSEEK_BASE_URL。
5.4 跑官方内置示例
仓库自带的 examples/jsonrpc-agent/minimal.py 是对 SDK 的轻量包装，针对隔离的工作区和会话目录跑一个任务：
代码块
Plain Text
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."
脚本会打印 agent 的最终回复。同时，会话目录会收到 JSONL 格式的日志——里面完整记录了组装后的模型请求和工具调用。这对调试和审计非常有用。
5.5 在自己的代码里用 SDK
代码块
Plain Text
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,
几个关键点：
•
DeepSeekHarness 会延迟启动内置运行时并持续复用，直到退出上下文管理器；
•
复用同一个 harness 和 session id，会保留该会话拥有的 Bash 进程（工作目录、导出的变量、shell 函数都在）；
•
独立任务请用新的 session id；只有确定要延续同一段对话和 shell 状态时，才复用原有 id；
•
cwd 决定 agent 可访问的工作区，session_root 决定会话日志存哪。
5.6 这个示例组合的"配方"
看明白 minimal 组合里有什么，你就知道"最小 harness"长什么样：
注意最后一行的警告：这个最小组合没有任何沙箱限制，Bash 和编辑器能改运行时进程可见的任何路径。生产环境请换上更严格的策略。
5.7 一个批量任务小例子
把上面的模式套进循环，就是一个最简单的批量自动化：
代码块
Plain Text
from pathlib import Path
from deepseek_harness import DeepSeekHarness
tasks = {
"repo-a": "Run the test suite and fix failures.",
"repo-b": "Find TODO comments and turn them into issues.",
"repo-c": "Update the dependency versions in package.json.",
}
with DeepSeekHarness(
provider="deepseek-official",
model="deepseek-v4-flash",
cwd="/work",
session_root="/sessions",
cordis=Path("minimal.cordis.yml").resolve(),
) as harness:
for repo, task in tasks.items():
result = harness.run(task, session_id=repo)
print(f"--- {repo}: {result.final_response[:200]}")
每个 repo 用独立 session id，彼此状态互不污染；/sessions 下留下每次任务的完整 JSONL 日志，方便事后排查。
5.8 本章小结
•
Python SDK：pip install deepseek-harness-sdk，自带运行时，Python 3.10+；
•
平台注意：官方示例暂不支持 Windows agent，用 WSL/容器/Linux；
•
DeepSeekHarness 上下文管理器 + harness.run(task, session_id) 是最小 API；
•
session id 是状态边界：独立任务用新 id，延续对话才复用；
•
最小组合默认 danger-full-access，批量任务务必用隔离环境。
下一章进入重头戏：插件开发。