ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 第一条任务搬进 Python SDK:三处参数必须显式传

配置与使用发布于 2026-11-18作者: DeepSeek Plugin 插件市场
DeepSeek HarnessDSH pluginPython SDKworkspacedsh_home
DeepSeek Harness 的 Web UI 与 Python SDK 不共享隐式配置,SDK 不会静默读取 ~/.dsh。本文讲从 Web 第一条任务迁移到 SDK 时,workspace、dsh_home、session_id 三处必须显式传,以及 sdk-minimal 的能力边界。

把 Web UI 里的第一条任务搬进 Python SDK,最容易犯的错是「以为配置会自动带过去」。 官方说明:SDK 与随附示例绝不静默读取 ~/.dsh;你传入的 dsh_home 才是唯一来源,所选 home 会保存生成的 sdk-minimal profile、已安装插件,以及 sessions/ 下的会话日志(来源)。迁移不是复制一句话,而是显式传三样东西。

DeepSeek Harness 先分清 Web 的 profile、home、workspace

Web 与 SDK 都有 profile、home、workspace,但它们不是同一份。 迁移前先把三个概念对齐,否则你会以为「同一个东西」,实际各用各的。(来源)

概念Web UI 里的表现SDK 里的表现
profileweb profile,界面与插件组合sdk-minimal 或 sdk profile
home默认 $DSH_HOME你显式传入的 dsh_home
workspace界面里选中的目录构造 SDK 时传入的 cwd / workspace

对齐之后就能看出:Web 里配好的模型、插件、工作区,不会自动出现在 SDK 里。SDK 用的是另一套 home,另一套 profile,另一个显式 workspace。

这不是缺陷,而是隔离设计。SDK 常用于自动化、测试和一次性任务,需要一个可清理、可复现的 home;如果它偷偷读你的日常 ~/.dsh,测试就可能污染真实配置。

DeepSeek Harness 三处显式参数:workspace、dsh_home、session_id

SDK 迁移的核心就是三处显式参数,缺一处就会得到不同的运行环境。 官方示例的运行方式是:minimal.py --workspace ... --dsh-home ... --session-id ... "任务内容"(来源)。

三处分别负责什么:

  1. workspace — agent 能读写的目录。Web 里是界面选中,SDK 里必须传绝对路径;
  2. dsh_home — profile、插件、凭据、会话日志的落脚点。不传就没有隔离的配置来源;
  3. session_id — 这次任务的会话标识。独立任务用新 id,继续同一段对话才复用。

在 Python 代码里,这三处对应 DeepSeekHarness(cwd=..., dsh_home=..., profile=...) 与 harness.run(..., session_id=...)。参数名可能因版本略有差异,但三件事不变:工作目录、home、会话 id。

一个实用原则:workspace 和 dsh_home 都用绝对路径,不要用相对路径或当前目录简写。SDK 可能在不同于你 shell 的工作目录里启动,相对路径会指向意外位置。

session_id 的复用规则也要记清:独立任务用新 id,避免旧日志干扰;只有继续同一段持久对话和会话资源时,才同时复用 harness、home 与 id。换 home 却复用 id,会在新 home 里创建一条同名但内容不同的会话,排查时很容易误判。

DeepSeek Harness 凭据从哪来:不继承 Web 的隐式状态

SDK 不继承 Web 的凭据状态,凭据要么来自环境变量,要么来自你传入的 home。 官方示例在运行前导出 DEEPSEEK_API_KEY,需要兼容代理时再设置 DEEPSEEK_BASE_URL(来源)。

两条来源的差别:

  • 环境变量 — 适合一次性运行、CI、容器;不需要把凭据写进 home;
  • SDK 的 home — 适合需要持久保存提供商配置与凭据引用的场景;home 里保存 profile 与凭据。

不要指望「Web 里保存的密钥」自动出现在 SDK 里。Web 的凭据在它自己的 home,SDK 用另一个 home,除非你显式指向同一个 home,否则两者互不相通。

如果 SDK 报凭据缺失,先看环境变量是否存在,再看 home 里是否有对应凭据;不要先去 Web 设置页反复保存。Web 的设置不会跨 home 生效。

DeepSeek Harness sdk-minimal 的能力边界

sdk-minimal 是刻意精简的 profile,能力比 Web 少,不要拿 Web 的预期套它。 官方说明:它不应用 dsh-base,因此没有文本文件工具、settings、托管凭据、OTel 遥测、Web 工具、subagent 与本地指令发现;保留的是持久 bash 或 pwsh、read_image 和 working_directory 等基础能力(来源)。

这意味着三件事:

  1. 没有 str_replace_editor — 需要文本编辑时,要么用 shell,要么显式加 editor patch;
  2. 没有 Team 与 subagent — 需要 Agent Teams 时选标准 sdk profile,并加 team patch;
  3. 固定 danger-full-access — 持久 shell 可以修改运行时可见的任何路径,应使用一次性 checkout 或容器。

sdk-minimal 适合「跑一条任务、拿结果」的极简场景;需要接近 Web 的能力时,选 sdk profile 并叠加插件与 patch,而不是在 sdk-minimal 上硬加。

DeepSeek Harness 同一条任务的 Web 版与 SDK 版对照

同一条任务在两边的写法不同,但目标可以一致。 以「总结当前仓库的主要包」为例(来源):

环节Web 版SDK 版
工作区界面选中目录传 cwd / workspace 绝对路径
模型设置页选模型传 provider 与 model,或依赖 home 配置
凭据设置页保存密钥环境变量或 home 凭据
会话界面新建会话传 session_id
运行输入框发送harness.run(prompt, session_id=...)

对照之后可以看到:Web 把配置放在界面状态里,SDK 把配置放在参数与 home 里。迁移的动作,就是把这些「界面状态」翻译成「显式参数」。

翻译完再跑,不要一边跑一边改。SDK 的报错通常比 Web 更直接,但前提是你传对了三处;三处传错时,报错会指向错误的方向。

DeepSeek Harness 验证:输出、会话日志、profile 三处对得上

SDK 跑通的标准不是「打印了一句话」,而是三处都对得上。 推荐三步(来源):

  1. 输出 — result.final_response 有内容,且覆盖了你点名的对象与产出;
  2. 会话日志 — 你传入的 dsh_home 下 sessions/ 出现对应 id 的 JSONL;
  3. profile — home 下有生成的 sdk-minimal profile,插件与配置符合预期。

三处都对,说明 workspace、home、session id 传对了;只有输出对、日志不在预期位置,通常是 home 传错;日志在但输出不对,回到任务描述与模型配置。

如果 SDK 读不到你预期的配置,先看它是不是用了另一个 home,而不是先怀疑插件。完整安装与 API 用法见《DeepSeek Harness 怎么用 Python 调用》;读不到 ~/.dsh 的排查见《DeepSeek Harness Python SDK 读不到 ~/.dsh》。

迁移的最后一条经验:先在 Web 里把任务跑通,再把「能跑通的那句话」原样搬进 SDK。Web 没跑通的任务,不要指望 SDK 能跑通;SDK 只是换了一个执行入口,不会替你补上缺失的工作区、模型或凭据。

三处显式参数、一个隔离 home、一份精简 profile,这三件事想清楚,Web 到 SDK 的迁移就只剩翻译工作。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 的 Python SDK 会自动读取 Web UI 里配好的模型和工作区吗?

DeepSeek Harness 不会这样。DeepSeek Harness 的 SDK 与随附示例绝不静默读取 ~/.dsh,Web 的隐式配置也不会自动继承。workspace、dsh_home、session_id 三处都要显式传入。

DeepSeek Harness 的 SDK 为什么必须传 dsh_home,不能直接用默认目录?

因为 DeepSeek Harness 的 SDK 只用你显式传入的 home。该 home 会保存生成的 sdk-minimal profile、已安装插件和 sessions 下的会话日志;不传就没有隔离的配置与凭据来源。

DeepSeek Harness 的 sdk-minimal profile 和 Web 的 profile 能力一样吗?

DeepSeek Harness 里,不一样。DeepSeek Harness 的 sdk-minimal 不应用 dsh-base,没有文本文件工具、settings、托管凭据、Web 工具和子代理,只保留 bash 或 pwsh、read_image 和 working_directory 等基础能力。

DeepSeek Harness 的 Web UI 和 Python SDK 能共用同一个会话吗?

DeepSeek Harness 里,不能直接共用。DeepSeek Harness 的 web 是独立 CLI 应用,不能为 Python SDK client 提供服务;Web 与 SDK 各有自己的 profile 与 home,继续同一段对话要同时复用 harness、home 与 session id。

相关术语

dsh_home
dsh_home 是 DeepSeek Harness 的隔离 home 目录,保存 profile、已安装插件、凭据、设置与会话日志;SDK 只使用显式传入的这个 home。— DeepSeek Harness 官方文档 - Python SDK 入门
sdk-minimal
sdk-minimal 是 DeepSeek Harness Python SDK 随附的极简 profile,不应用 dsh-base,只包含 SDK 协议、模型适配器、本地执行与持久化等基础能力。— DeepSeek Harness 官方文档 - Python SDK 入门
workspace
workspace 是 DeepSeek Harness 会话可读写的文件系统位置;在 SDK 里必须通过显式参数传入,不能依赖 Web UI 的选中状态。— DeepSeek Harness 官方文档 - Python SDK 入门
session_id
session_id 是 DeepSeek Harness 会话的标识;SDK 用它区分独立任务,继续同一段对话时需要复用同一个 id 与 home。— DeepSeek Harness 官方文档 - Python SDK 入门

来源