Python SDK 入门

English | 中文

本教程安装已发布的 Python SDK，运行随附的独立极简 profile，并说明如何从自己的程序自定义同一个 dsh profile。

前置条件

• Python 3.10 或更高版本
• Git
• Linux x64、Linux arm64、arm64 上的 macOS 14 或更高版本，或 Windows x64
• DeepSeek 兼容的 API endpoint 与凭据
• 隔离的 workspace 与隔离的 Harness home

安装 SDK

::: code-group

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

git clone https://github.com/deepseek-ai/deepseek-harness.git
Set-Location deepseek-harness
py -3.10 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install deepseek-harness-sdk

:::

安装内容包含匹配的原生运行时 wheel 与 dsh 命令。普通 SDK 运行不需要系统 Node.js。需要构建产物的仓库贡献者应使用 Python 贡献者工作流。

运行检入示例

导出凭据；使用兼容代理时再设置 endpoint：

::: code-group

export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1

$env:DEEPSEEK_API_KEY = "sk-your-key-here"
# $env:DEEPSEEK_BASE_URL = "http://127.0.0.1:8000/v1"

:::

使用显式 workspace 与 home 路径运行一个任务：

::: code-group

python python/sdk/examples/minimal.py \
  --workspace /absolute/path/to/disposable-workspace \
  --dsh-home /absolute/path/to/example-dsh-home \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

python python/sdk/examples/minimal.py `
  --workspace C:\work\disposable-workspace `
  --dsh-home C:\work\example-dsh-home `
  --session-id example-001 `
  "Inspect the repository and fix the failing tests."

:::

脚本会打印最终 assistant 响应。所选 home 会保存生成的 sdk-minimal profile、已安装插件，以及 sessions/ 下的未压缩 JSONL 会话日志。示例与 SDK 绝不会静默读取 ~/.dsh。

在程序中使用 SDK

from pathlib import Path

from deepseek_harness import DeepSeekHarness

workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),
    profile="sdk-minimal",
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

SDK 会延迟启动内置的 dsh --profile sdk-minimal 进程，并复用到上下文管理器退出。Profile、其持久 patch、home patch 与任何有序 patches tuple 共同组成应用配置。不存在独立 Python 运行时 bin 或完整配置选项。

安装或定义插件

需要在该 home 中持久保存依赖与 bundle 层时，使用 dsh plugin：

::: code-group

export DSH_HOME=/absolute/path/to/example-dsh-home
dsh --profile sdk-minimal --dump-default-config >/dev/null
dsh plugin --profile sdk-minimal add file:/absolute/path/to/my-plugin-bundle

$env:DSH_HOME = "C:\work\example-dsh-home"
dsh --profile sdk-minimal --dump-default-config | Out-Null
dsh plugin --profile sdk-minimal add file:C:/work/my-plugin-bundle

:::

第一个命令初始化随附的独立 profile。第二个命令把包管理转发给 pnpm，然后记录所有导出 dsh.bundle 层的已安装包。只有执行此管理命令时才需要安装 pnpm；启动已安装 SDK 不需要它。持久配置项变更应编辑 $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml；单次启动变更则从 Python 传入 patch 文件。

另一个 profile 只有包含 @deepseek-ai/dsh-sdk-app 或另一个 JSON-RPC server 配置项时才有效。缺失 server 配置项、无法解析的插件和非法 patch 会在启动时失败，不会回退到其他组合。

显式启用 str_replace_editor

随附运行时包含 str_replace_editor，但 sdk-minimal 的默认 Cordis tree 不挂载它。要使用该工具，请将以下配置保存为 editor.patch.yml；insert 会添加 editor，以及极简 profile 缺少的文件系统后端：

- insert:
    - id: fs-local
      name: '@deepseek-ai/dsh-fs-local'
      config:
        cwd: !!js process.cwd()
    - id: tool-str-replace-editor
      name: '@deepseek-ai/dsh-tool-str-replace-editor'

构造 DeepSeekHarness(profile="sdk-minimal", ...) 时传入 patches=("/absolute/path/to/editor.patch.yml",)，或将 patch 写入 $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml 以持久保存配置。下次运行时启动后，模型请求会在持久 shell 之外包含 str_replace_editor。本地文件系统后端以运行时工作目录解析相对路径；与极简 shell 一样，它不会将访问限制在该目录内。对于标准 sdk profile，只插入 editor 配置项，让它使用已有的文件系统后端与策略。

理解极简 profile

该 profile 的唯一组合包会在空根之上插入完整配置树，且不包含 dsh-base，因此基础 profile 以后新增的工具不会隐式出现。它包含 SDK 协议、一个由环境配置的 DeepSeek 适配器、本地执行与持久化；文件系统工具、settings、托管凭据、OTel 遥测、Web 工具、subagent、本地指令发现和 compaction 均不存在。DeepSeek 会话日志贡献器默认随 DeepSeek 请求上传未接受的日志事件，每次请求最多 maxBytes（8 MiB）；在 profile patch 中设置 session-log-deepseek.enabled: false 可将其关闭。它固定使用 danger-full-access，因此按平台选择的持久 shell 可以修改运行时可见的任何路径；应使用一次性 checkout 或容器。

已安装 wheel 仍会打包完整 web profile 与前端产物。如果 Python SDK 部署还需要浏览器应用，请针对显式 DSH_HOME 运行 dsh web；web 是独立 CLI 应用，不能为 Python SDK client 提供服务。

需要隔离 profile、插件、凭据、设置与会话时，应使用新的 home。独立工作应使用新的 session id；只有继续同一段持久对话和会话资源时，才同时复用 harness、home 与 id。

组合包参考定义确切配置树，示例参考定义可运行程序。Python SDK 参考介绍生命周期、结果、通知与底层行为；dsh CLI 参考介绍 profile 分层。