📚 系列导航：上一篇 DeepSeek Harness 插件推荐与安装教程 已经完成社区插件的筛选、安装与验证；本篇使用 Python SDK 启动同一套运行时、执行最小示例并检查持久会话结果，也是当前系列的程序化入口。
DeepSeek Harness Python SDK 是 Web UI 的程序化替代方案：它会随 Python 包提供运行时，让你从 Python 代码启动 Harness、执行 Agent 任务并读取最终结果。 官方最小示例权限很高，必须放在可丢弃工作区或容器中运行。
DeepSeek Harness Python SDK 支持平台与准备条件
官方当前要求 Python 3.10 或更高、Git、DeepSeek 兼容 API 端点和凭证，以及允许 Agent 修改的隔离工作区。支持 Linux x64、Linux arm64，或 arm64 架构上 macOS 14 及更高版本。
官方最小组合依赖 POSIX 持久终端，因此不支持 Windows Agent。Windows 用户不要只看 Python 包能否安装，还要看示例所依赖的终端后端是否可用。
先检查本机环境：
python --version
git --version版本满足要求后，再准备一个独立测试仓库和单独的会话目录。不要把 SDK 示例直接指向主目录、生产仓库或存放凭证的父目录。
创建虚拟环境并安装 Python SDK
官方教程会克隆仓库以取得可运行示例，再在虚拟环境中安装 deepseek-harness-sdk。发布包带有同版本运行时，这条路线不要求系统安装 Node.js。
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。仓库贡献者如果要从源码构建运行时或 Wheel，应改走官方 Python 贡献流程，不要把发布包安装步骤当成源码构建步骤。
退出终端后虚拟环境不会自动保持激活。再次运行示例前先确认当前 python 和 pip 都指向 .venv，避免把依赖装进系统环境。
配置 API 凭证与模型参数
最小示例从环境变量读取 DeepSeek API 密钥。使用 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=your-model-id
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'真实密钥只放在当前安全环境中，示例值不要直接提交到 Shell 脚本或仓库。终端历史、CI 日志和报错截图都可能泄露环境变量，反馈问题前必须脱敏。
模型 ID 要与目标端点真实支持的名称一致。代理地址能访问不代表模型名正确，认证成功也不代表端点实现了示例依赖的全部协议。
运行 DeepSeek Harness Python SDK 最小示例
示例需要绝对工作区路径、会话存储路径和会话 ID。工作区是 Agent 执行文件与命令的环境，会话目录保存 JSONL 日志和状态，两者不要指向同一个位置。
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 summarize its main packages."成功时脚本会打印最终回答，会话目录会新增包含模型请求和工具调用的 JSONL 日志。先用只读总结任务验证链路，再尝试修改测试文件，能更快区分模型配置错误和工具执行错误。
不要照抄示例里的绝对路径占位符。路径不存在、不可写或指向错误目录时，Agent 可能无法启动，也可能在你没有预期的位置创建状态文件。
使用 DeepSeekHarness API 发起 Agent 任务
仓库示例本质上是对 DeepSeekHarness 的一层薄封装。你需要指定 Cordis 组合、工作区、会话根目录、提供方和模型，再在上下文管理器中调用 run()。
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="your-model-id",
cwd=str(workspace),
session_root=str(sessions),
cordis=str(config),
) as harness:
result = harness.run(
"Inspect the repository and summarize its main packages.",
session_id="example-001",
)
print(result.final_response)运行时会在需要时延迟启动，并在上下文管理器退出前复用。同一个 Harness 和会话 ID 会保留持久 Bash 进程的工作目录、导出变量和 Shell 函数；独立任务应使用新的会话 ID。
检查 Python SDK 会话日志与安全边界
cwd 决定 Agent 工作区，session_root 保存日志与状态。需要延续同一对话和 Shell 状态时才复用会话 ID；只是想跑另一个任务，就新建 ID，避免历史上下文串入。
官方最小组合使用 danger-full-access，Bash 和编辑器能够修改运行时进程可见的路径，而且没有上下文压缩等完整 Web 组合能力。它是学习 SDK 的最小示例，不是默认安全的生产模板。
运行后检查 JSONL 日志、工作区 Git 差异和终端输出。只要出现工作区外路径、无关文件修改或意外命令，就停止复用该会话，并在隔离环境中重新核对 Cordis 配置。完整限制以 DeepSeek Harness Python SDK 官方教程 为准。
常见问题
安装 Python SDK 还需要 Node.js 吗？
发布的 SDK 带有同版本运行时，官方教程说明不需要系统 Node.js。源码构建运行时则是另一条贡献流程。
为什么官方最小示例不支持 Windows Agent？
该组合使用需要 POSIX 终端基础的持久 PTY 后端，因此官方明确说明它不支持 Windows Agent。
什么时候应该复用 session ID？
只有下一次调用确实要延续同一持久对话和 Shell 状态时才复用。独立任务应使用新的 ID。