DeepSeek-Harness Python SDK：无需 Node.js 编程式驱动智能体

deepseek-harness-sdk 是 DeepSeek-Harness 官方提供的 Python 包，用于编程式驱动 dsh 智能体，不需要你自己安装 Node.js——它内部打包了一份运行时。用 pip install deepseek-harness-sdk 安装后，就可以通过 DeepSeekHarness 类驱动一个会话，而不是走 Web UI 或 CLI。

环境要求与平台支持

python -m pip install deepseek-harness-sdk

SDK 要求 Python 3.10+。按照官方文档，平台支持范围比 Node.js CLI 窄：

平台	是否支持
Linux x64	支持
Linux arm64	支持
macOS 14+（arm64）	支持
Windows	文档未记录为支持
较老的 macOS（Intel，或 macOS <14）	文档未记录为支持

如果你需要在 Windows 上用 dsh，走常规的基于 npm 的 CLI 路径——参见在 macOS、Windows、Linux 上安装 DeepSeek-Harness——而不是 Python SDK。

一个最小示例

from deepseek_harness import DeepSeekHarness

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)

DeepSeekHarness 是一个上下文管理器：进入 with 块会启动内置的运行时，.run() 向一个会话提交任务（如果 session_id 还不存在会自动创建），退出代码块时运行时被关停。cwd 设置工作区根目录，用法和 CLI 一致；session_root 控制会话状态落盘的位置；cordis 指向一个配置文件——配置指南里讲的那套 cordis.patch.yml 层叠概念在这里同样适用。

为什么一个 Python 包里会打包一份用 Node.js 构建的运行时

dsh 真正的智能体循环、工具执行、插件系统都是用 TypeScript 实现的，跑在和 CLI 一样的运行时上——Python SDK 并没有用 Python 把这些重新实现一遍。相反，它把一份预构建好的 dsh 运行时和 Python 绑定打包在一起，所以 pip install 装完就能直接得到一个能跑的智能体，不需要额外的 npm install -g 步骤，也不需要自己管理系统级 Node.js 版本。这也是为什么上面的平台矩阵比 CLI 窄的原因：SDK 必须为每一种受支持的操作系统/架构组合都打包一份能跑的预构建运行时，截至 2026 年 8 月这份名单是 Linux x64、Linux arm64，以及 arm64 架构的 macOS 14+——Windows 支持取决于这份矩阵能否扩大，而不是任何 Python 特有的限制。

拆解构造函数参数

上面示例里 DeepSeekHarness 的构造函数接受几个值得单独理解的参数，它们直接对应本系列指南其他文章里讲到的概念：

参数	控制什么
`provider` / `model`	请求路由到哪个模型 provider 和具体模型 ID——和你通过 Settings → Models 在 `$DSH_HOME/settings.yaml` 里配置的是同一套 provider ID
`max_tokens`	单次模型响应的输出 token 上限
`cwd`	智能体在 `workspace-write` 下当作文件系统边界的工作区根目录，或在 `danger-full-access` 下不受限制的起始目录
`session_root`	会话状态落盘的位置——类似 CLI 和 Web UI 使用的、以 profile 为作用域的会话存储
`cordis`	一个配置文件的路径，其层叠方式和 CLI 的 `--patch` 层叠方式一样（参见配置指南）

因为 cordis 接受任意配置文件路径，所有关于 patch 层叠、插件 bundle、MCP 服务器配置的文档，无论你是通过 CLI 启动还是通过 Python SDK 驱动一个会话，都同样适用——SDK 并没有一套单独的、被削减过的配置能力面。

底层到底在跑什么

Python SDK 不是 dsh 的一套独立重新实现——它是对同一套 stdio JSON-RPC 协议（@deepseek-ai/dsh-sdk-protocol）的 Python 语言绑定，官方 TypeScript SDK（dsh-sdk-client、dsh-sdk-server）用的也是这套协议。两个 SDK 都是把 dsh 运行时当作一个子进程驱动，通过 stdio 交换 JSON-RPC 消息——Python 包只是把这个运行时预先打包好了，让你不需要单独装 Node.js 就能让这个子进程跑起来。

这与 dsh 另一个基于 stdio 的 JSON-RPC 接口 ACP（Agent Client Protocol）是不同的集成面。ACP（dsh-acp）被明确定位为"仅供自动化"，面向想通用地驱动 dsh 的外部 GUI 客户端和编排系统；而 SDK（Python 和 TypeScript）是把 dsh 的智能体循环直接嵌入你自己应用代码的路径，提供类型化、语言原生的 API。目前没有面向第三方集成的、有公开文档的 HTTP REST API——通过 SDK 或 ACP 走 stdio JSON-RPC 是官方支持的路线。

danger-full-access 警告

上面这个官方示例把 SDK 和 danger-full-access 搭配使用——完全不做沙箱隔离。文档对这意味着什么、什么场景下适用说得非常明确：

……只应该在一次性 checkout 或容器里运行。

这不是一句可以忽略的建议。danger-full-access 会彻底关闭 read-only/workspace-write 的沙箱边界——智能体的 Bash 和文件系统访问不再被限制在工作区根目录或平台临时目录内。如果你要用 SDK 驱动一个机器上真实存在、需要长期保留的 checkout，应该改用 dsh 的 workspace-write 权限预设（也是 Web UI 和 CLI 里新会话的默认值）——各沙箱模式具体限制了什么，完整拆解见我们的权限与沙箱指南。

SDK vs headless CLI vs ACP：什么时候用哪个

接口	适合场景
Headless CLI（`dsh --profile headless "任务文本"`）	一次性 shell 脚本、CI 步骤——不用写代码，只看进程退出码
Python 或 TypeScript SDK	把智能体循环嵌入自己的应用程序，对会话和结果做结构化的编程式控制
ACP（`dsh-acp`）	构建或接入一个想通用地驱动 dsh、不绑定特定语言运行时的外部 GUI/编辑器客户端

如果你的场景是"跑一个任务，从脚本里读最终答案"，headless 模式更简单，不需要写任何 SDK 代码。当你需要多个会话、结构化的 result 对象，或者需要在一个更大的 Python（或 TypeScript）程序内部对智能体生命周期做更紧密的控制时，再考虑用 SDK。

DeepSeek-Harness Python SDK：无需 Node.js 编程式驱动智能体

环境要求与平台支持

一个最小示例

为什么一个 Python 包里会打包一份用 Node.js 构建的运行时

拆解构造函数参数

底层到底在跑什么

danger-full-access 警告

SDK vs headless CLI vs ACP：什么时候用哪个

FAQ

Python SDK 需要装 Node.js 吗？

可以在 Windows 上用 Python SDK 吗？

Python SDK 和 TypeScript SDK 功能对等吗？

应该原样照抄示例里的 `danger-full-access` 配置吗？

SDK 和 ACP 有什么不同？

Next steps