DeepSeek Harness in Depth

外观

Python SDK 是 DeepSeek Harness 的 Python 面孔：它以子进程方式、通过 stdio 上的换行分隔 JSON-RPC 驱动打包好的 harness 运行时，让 Python 代码无需系统 Node.js 即可运行 agent 轮次。它以两个 PyPI 包发布——客户端 deepseek-harness-sdk 与平台运行时载体 deepseek-harness-runtime-bin——它所讲的线协议与 TypeScript SDK 使用的是同一个。

包分发 / 模块角色
python/sdkdeepseek-harness-sdk / deepseek_harness高层轮次 API 与低层 JSON-RPC 客户端
python/sdk-runtimedeepseek-harness-runtime-bin / deepseek_harness_runtime打包的 dsh CLI 可执行文件与本地 sidecar（仅 wheel）

客户端包依赖当前平台上的同版本运行时 wheel（deepseek-harness-sdk 固定 deepseek-harness-runtime-bin 的版本），因此一次 pip install deepseek-harness-sdk 两者都会装好：

sh
python -m pip install deepseek-harness-sdk

如何启动运行时 ​

Python SDK 没有独立的应用程序入口。它用 --profile sdk 启动匹配的打包版 dsh CLI；所选 profile 拥有 JSON-RPC 服务器、agent 组合、凭据、持久化、工具与关闭行为。每次启动都要求显式选择 Harness home——传入 dsh_home，或在子进程环境中提供非空的 DSH_HOME。Python 从不静默读取 ~/.dsh；运行时 wheel 的 dsh 命令同样强制该规则，绝不回退到 ~/.dsh。

py
from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    dsh_home="/absolute/path/to/isolated-dsh-home",
    cwd="/absolute/path/to/workspace",
    provider="deepseek-official",
    model="deepseek-v4-flash",
    reasoning_effort="max",
    max_tokens=49_152,
) as harness:
    result = harness.run("Say hi.", session_id="example-001")

print(result.final_response)

DeepSeekHarness 惰性启动，并在 close() 或上下文管理器退出前复用其运行时。cwd 是 agent 工作区；runtime_cwd 独立选择子进程工作目录；两者在启动前都会转为绝对路径。provider、model、可选的 reasoning_effort 与可选的正数 max_tokens 在 JSON-RPC 初始化期间发送，而 base_url 与 api_key 显式覆盖子进程环境中的 DEEPSEEK_BASE_URL 与 DEEPSEEK_API_KEY。初始 profile 握手有独立的 30 秒默认上限（initialize_timeout_seconds）；普通轮次在设置 request_timeout_seconds 之前保持无界。

sdk profile 与其 bundle ​

使用 --profile sdk 启动会加载 @deepseek-ai/dsh-sdk-app（packages/bundle/sdk-app），即作为 dsh-base 之上的 profile bundle 的 SDK stdio 应用。它的 patch 设置编码 agent 人设、挂载一个应用自有的零选项命令提供方，并且只在那个提供方接受调用后才启动 dsh-sdk-jsonrpc-server——因此 dsh --profile sdk --help 会写出帮助并退出，而不占用 stdin 或 stdout。stdout 只保留给换行分隔的 JSON-RPC 帧。客户端选择的自定义 profile 必须保留 @deepseek-ai/dsh-sdk-app 或另一个 dsh-sdk-jsonrpc-server 行；省略了 SDK 服务器的 profile 会在没有 peer 应答时初始化失败。

随附的 sdk-minimal 变体（@deepseek-ai/dsh-sdk-minimal）是独立的显式树，而不是 dsh-base 之上的覆盖层。它提供持久 shell、字符串替换编辑器、本地执行与 JSONL 会话；settings、托管凭据、遥测、Web 工具与完整默认工具名册仍可通过独立的完整 sdk 与 web profile 获得。可运行的极简示例（python/sdk/examples/minimal.py）默认选择 sdk-minimal。

持久化定制属于 dsh profile——初始化随附 profile，并用运行时 wheel 的 dsh 命令安装外部 bundle；其 $DSH_HOME/profiles/sdk/cordis.patch.yml 是持久用户 patch。如需只对某次调用生效的变更，可传入一个或多个 patch 文件，它们会在 profile 与 home patch 层之后按顺序转发。

客户端模块 ​

deepseek_harness 包是导入表面（见 python/sdk/src/deepseek_harness/）：

模块内容
__init__.py再导出公共 API：DeepSeekHarness、DeepSeekHarnessConfig、Session、RunResult、HarnessClient、HarnessConfig
api.py高层轮次 API——启动、profiles、patches 与上下文管理的运行时
client.pyHarnessClient——低层换行分隔 JSON-RPC 客户端
models.py线类型，如 RunResult、Session 与事件/通知形状
errors.py协议与启动错误（例如畸形 turn/end 时的 SdkProtocolError）

Session.run() 拥有一个活动区间：从提示词的持久 inbox 回执到下一个整 agent idle，并返回 RunResult(session_id, final_response, finish_reason, events, notifications)。final_response 是该区间内最后一次已提交的根会话助手文本；finish_reason 是最后一次根会话 turn/end 的 kind，例如 completed、max-tokens 或 error，当没有轮次结束时为 None。协议就是 SDK 协议 文档中描述的同一个换行分隔 JSON-RPC；缺少字符串 data.reason.kind 的 turn/end 违反协议并抛出 SdkProtocolError。

运行时载体：deepseek-harness-runtime-bin ​

运行时 wheel 把常规的 dsh CLI 及其封闭的 Node 依赖树打包进一个原生可执行文件，因此 SDK 使用无需系统 Node.js；dev-only node 载体绝不会被自动选中，并被排除在 wheel 与 sdist 之外。wheel 安装一个 dsh 控制台命令（在 python/sdk-runtime/pyproject.toml 中为 dsh = "deepseek_harness_runtime:main"）以及 deepseek_harness_runtime Python 模块，其 API 定位打包好的可执行文件：

py
from deepseek_harness_runtime import (
    bundled_package_dir,      # 已安装的 module-data 根目录，校验发布元数据
    bundled_runtime_path,     # 当前平台可执行文件，校验必需 sidecar
    resolve_bundled_launch_args,  # 默认 argv；mode="node" 选择仅仓库载体
)

生产可执行文件以 deepseek-harness-sdk-runtime-<platform>-<arch> 命名，位于模块的 runtime/ 目录下；Windows 使用 .exe 后缀。Linux x64、Linux arm64、macOS arm64 与 Windows x64 是已发布目标。Linux 与 macOS wheel 包含目标原生的 -rg sidecar，Windows 包含 -rg.exe，macOS 还包含用于 node-pty 的 -spawn-helper。工作区清单是 python/sdk-runtime——python/sdk-runtime/package.json 中的 dsh-python-runtime-closure 部署根定义了打包的依赖闭包，其 pyproject.toml 定义了 deepseek-harness-runtime-bin。没有 Python 专属的 Node 应用，也没有签入的默认 cordis.yml。

外部 profile 管理使用 dsh plugin --profile <name> ...，该命令需要 PATH 上有 pnpm；普通 SDK/profile 执行不需要。

包 ​

包
deepseek-harness-sdk（PyPI）
deepseek-harness-runtime-bin（PyPI）

延伸阅读 ​

  • python/README.md——Python SDK 概览与双包拆分
  • python/sdk/README.md——运行时选择、profiles、patches 与插件管理
  • python/sdk-runtime/README.md——运行时 wheel、sidecars 与构建/分发
  • SDK 协议——共享的换行分隔 JSON-RPC 线协议
  • packages/bundle/sdk-app/README.md——sdk profile bundle
  • packages/bundle/sdk-minimal/README.md——独立的 sdk-minimal 树

DeepSeek Harness in Depth