用 Python SDK 跑通第一个 DSH 任务:工作区、home 与 `sdk-minimal` 的边界

简介: 安装 `deepseek-harness-sdk` 后跑第一个任务,最容易踩的不是 `pip install` 本身,而是把 Python 当成独立运行时、把 `--workspace` 当成沙箱边界、把 `dsh web` 当成 SDK 服务端,或者在多次测试之间混用 `--dsh-home` 和 `--session-id`。本文按「环境准备 → 最小示例 → Python 与 `sdk-minimal` 的分工 → 默认能力与补丁扩展 → 排障与安全边界」完整拆解第一次 SDK 调用。

pip install deepseek-harness-sdk 已经装好,脚本也能成功 import,但真正运行第一个任务时,常见的卡点有三个:

  1. 以为只要系统里已经启动 dsh web,Python SDK 就能直接连接;
  2. 以为传入 --workspace /path/to/repo 后,Agent 就只能访问这个目录中的文件;
  3. 换了任务再次运行,却沿用同一个 --dsh-home 和 --session-id,导致上次对话的上下文、持久补丁乃至日志混在一起。

想顺利跑通第一个任务,先要厘清 Python 客户端、sdk-minimal 进程、工作区(workspace)、Harness home 和会话(session) 这五者各自的边界。站内教程版可参考DeepSeek Harness Python SDK:运行第一个任务。

一、动手前先对齐五项前提

官方 Python SDK 指南明确列出了运行环境要求:

  1. Python 版本:Python 3.10 及更高版本;
  2. 基础工具:已安装 Git;
  3. 受支持的平台:Linux x64、Linux arm64、arm64 架构的 macOS 14 或更高版本,以及 Windows x64(其他平台是否支持,应先查看最新文档);
  4. 模型凭据:DeepSeek 兼容的 API endpoint 与对应凭据;
  5. 两个独立目录:隔离的工作区(workspace)路径,以及独立的 Harness home 路径。

其中最关键的一条边界,需要从一开始就明确:

工作区(--workspace)只是任务运行的当前目录,不是文件访问边界。

示例使用的 profile、已安装插件和会话数据会保存在所选的 Harness home 中;极简 profile(sdk-minimal)的 shell 则默认采用 danger-full-access。这意味着,要求 Agent 检查或修改仓库时,完全可能读取或修改 shell 按当前操作系统权限能够访问的其他文件。因此,首次运行示例务必使用用途明确的一次性路径(disposable checkout)或受控容器,不要直接指向存放敏感资料的日常开发目录。权限预设与工具暴露之间的对应关系,可参见权限预设怎样影响可用工具。

二、从零安装并跑通 minimal.py 示例

官方指南先让你克隆仓库,是因为随附的示例脚本 python/sdk/examples/minimal.py 就在该仓库的 checkout 中。

1. 创建虚拟环境并安装 SDK

在 Linux 或 macOS 上执行:

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

Windows 环境下的对应命令是 py -3.10 -m venv .venv 与 .venv\Scripts\Activate.ps1。

下面两点经常有人问到:

  • 需要提前安装系统级 Node.js 吗? 运行普通 SDK 任务不需要系统 Node.js:发布包已经包含配套的原生运行时 wheel 和 dsh 可执行文件。
  • 安装 SDK 和为仓库贡献代码是一回事吗? 不是。通过 pip install deepseek-harness-sdk 安装现成 wheel,与克隆仓库后从源码构建产物,是两条完全不同的流程。

2. 五步跑完第一次调用

  1. 在当前 shell 中设置 DEEPSEEK_API_KEY,切勿在日志、截图或命令行历史中泄露真实密钥。使用兼容代理时,也可以按指南设置 DEEPSEEK_BASE_URL(模型与提供商的详细字段参见配置模型与提供商)。
  2. 准备两个绝对路径:分别用于一次性工作区(--workspace)和独立的 Harness home(--dsh-home)。运行前,把下面命令中的占位路径替换为本机的真实绝对路径。
  3. 指定一个新的 --session-id 运行示例:
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."
  1. 检查最终回复和工作区中的实际文件变更。示例提示词要求「检查仓库并修复失败的测试」,任务本身就会修改文件;这也是前面强调使用一次性 checkout 或容器的原因。
  2. 为下一次运行规划 ID:如果下一个任务独立进行,就使用新的 --session-id;只有明确要延续同一段持久对话和会话资源时,才同时复用相同的 harness 配置、--dsh-home 与 --session-id。

3. --dsh-home 里到底落了什么数据?

运行后,指定的 --dsh-home 目录会保存三类内容:

  • 自动生成的 sdk-minimal profile;
  • 该 home 下安装的插件;
  • sessions/ 目录下未压缩的 JSONL 会话日志。

请注意:示例和 SDK 不会静默读取本机的 ~/.dsh。 官方会话参考将 Session 定义为追加式事件日志(append-only event log),模型可见的对话历史由这份日志派生。日志完整记录任务交互,因此可能包含敏感代码片段、路径或业务数据;保管和分享前,都应将其视为敏感材料。

三、Python 客户端与 sdk-minimal 进程是怎么配合的?

刚开始接入时,容易把 deepseek-harness-sdk 误认为纯 Python 实现的 Agent 循环。实际上,它的架构分工很清楚:

  1. 按需启动子进程:SDK 会等到首次真正执行任务时,才启动 dsh --profile sdk-minimal 进程;
  2. 在上下文管理器内复用:Python 的 with 上下文管理器退出前,后续调用都会复用同一个 dsh 进程;
  3. Python 是客户端,不是另一套配置系统:官方示例通过 DeepSeekHarness 构造器传入 provider、model、工作目录、home 和 profile,再调用 harness.run(...) 获取 final_response。

配置层是怎么叠加上去的?

dsh 进程启动后,最终生效的应用组合由以下几层共同决定:

profile 自身配置及持久补丁(cordis.patch.yml)
→ home 补丁
→ Python 构造器传入的有序 patches 元组

根据官方 CLI 参考:

  • 同一配置行以较后应用的层为准;
  • 补丁会替换该配置行的整个 config 值,不会逐键深度合并(deep merge)。

如果选择默认的 sdk-minimal 以外的自定义 profile,该 profile 必须包含 SDK app 或另一个 JSON-RPC server 配置项。缺少必需服务、插件无法解析或补丁格式非法,都会导致进程在启动阶段直接失败,不会静默回退到其他组合。

四、sdk-minimal 默认给模型开放了什么、省掉了什么?

在改配置或加插件之前,先看清 sdk-minimal 的出厂基线:

能力维度 文档中的 sdk-minimal 行为
面向模型的工具 Linux/macOS 上持久 bash(Windows 上为 pwsh),以及 read_image 和 working_directory
Shell 权限与超时 300 秒超时,固定使用 danger-full-access
上下文管理 自动压缩(auto-compaction),同时保留完整会话日志
会话持久化 所选 home 下未压缩的 JSONL 文件
默认不包含的能力 不包含 subagent、Web 工具、settings、托管凭据或本地指令发现

这张表还揭示了三个需要特别留意的工程事实:

1. 它不继承 dsh-base

指南将 sdk-minimal 描述为不含 dsh-base 的独立组合包。这样工具清单更精简、行为更可预期;与此同时,基础 profile(dsh-base)将来新增的工具不会自动出现在 sdk-minimal 中。

2. 默认没有挂载 editor 文件工具

运行时包虽然包含 editor 插件,sdk-minimal 默认却没有挂载它,模型仍通过 bash / pwsh 读写文件。若要使用结构化的文件读写与编辑工具,可以按指南提供的 patch 示例显式启用 editor。指南还特别提醒:本地文件系统后端会依据工作目录解析相对路径,但不会将访问范围限制在该目录内(工作区文件读写工具的行为边界,可参见Agent 怎样读写和编辑工作区文件)。

3. dsh web 不能当成 Python SDK 的后端

安装包也包含独立的 Web profile,可以通过 dsh web 启动浏览器应用。但官方指南明确指出:dsh web 不能为 Python SDK 客户端提供服务。浏览器界面正在运行,并不意味着 Python 脚本可以连接它并共用会话或 JSON-RPC 通道。

五、第一次运行后,怎么分段验收与排障?

命令运行后,不要只凭终端是否报错来判断成功与否。建议分四个阶段验收:

  1. 进程启动阶段:如果进程在任务开始前就退出,先检查所选 profile 和配置层。缺少 JSON-RPC server 配置项、插件解析失败或补丁非法,都会直接阻断启动。
  2. 模型请求阶段:如果 dsh 进程已启动,但模型请求卡住或报错,重点检查 DEEPSEEK_BASE_URL 和 DEEPSEEK_API_KEY(排查时切勿将真实密钥贴进日志或工单)。
  3. 任务执行阶段:示例提示词 "Inspect the repository and fix the failing tests." 远不只是一次「连通性 ping」。如果只是首次验证链路,可以先换成不要求修改文件的问题;但要记住:提示词写得温和,不等于系统强制了只读边界,极简 shell 的实际权限仍由操作系统运行环境决定。
  4. 结果核对阶段:SDK 返回的 final_response 只是最后一轮 assistant 的文本回复,不能代替你检查工作区中的实际文件变更(git status / git diff)和测试结果。

还应随手记录本次使用的 --dsh-home、--workspace 和 --session-id。记清这三项,下一次运行脚本时才能判断自己是在「接着上一轮聊」,还是「新开了一局」。

六、什么时候需要打补丁或装插件?

默认的 bash + read_image + working_directory 已能满足需求时,直接使用 sdk-minimal 最省心。确实需要额外工具(例如前面提到的 editor)或调整参数时,再根据影响范围选择修改方式:

1. 临时生效 vs 持久生效

  • 只影响当前这一次 Python 运行:通过 DeepSeekHarness 构造器传入有序的 patches 文件元组(tuple);
  • 需要对这个 profile 持久生效:修改所选 home 下该 profile 的 cordis.patch.yml。

无论选择哪种方式,都要记住 CLI 参考中的覆盖规则:patch 会整行替换目标条目的 config 对象,而不是逐键合并。编写 patch 时,必须一并写全该插件最终需要保留的其他字段。启用新工具前,先检查最终生效的配置树,以及该工具对文件系统的实际影响;不要仅凭工具名称判断权限。

2. 在选定 home 中安装第三方或随附插件

指南还介绍了如何在指定 home 下通过 dsh plugin 命令初始化随附 profile 并安装 bundle:

  • 插件管理操作需要使用 pnpm(普通 SDK 任务运行本身不需要系统 Node.js / pnpm);
  • 插件安装是对所选 --dsh-home 的持久变更;
  • 同一个 --dsh-home 若被多个项目的自动化任务共用,其中安装的插件和持久补丁会影响所有复用该 home 的运行。

因此,不同任务应使用不同的 --session-id;需要隔离插件、profile、凭据和设置时,也应改用新的 --dsh-home。

七、会话日志、自动压缩与数据外发边界

将 Python SDK 接入团队流水线或内部工具前,还应核实三项会话数据机制:

1. 自动压缩不会删除底层日志

对话变长后,sdk-minimal 会触发自动上下文压缩(auto-compaction),通过模型生成的摘要替代较早的历史消息,以缓解上下文窗口压力。但自动压缩只改变模型可见的上下文表示,sessions/ 下的完整 JSONL 事件日志仍然原样保留。因此,绝不能把「触发了压缩」当成「清理了历史敏感数据」。此外,通过 SDK 传入的普通提示词文本不会执行 /compact 这类交互式斜杠命令(压缩的触发方式与边界,详见上下文压缩与 /compact 命令)。

2. 默认的会话日志贡献器(Session Log Contributor)

官方指南特别说明:DeepSeek 会话日志贡献器默认会上传未接受的日志事件(unaccepted log events),并受文档所述的字节上限约束。如需关闭此行为,可通过 profile patch 显式禁用。将私有代码库、内部文档或敏感数据交给任务处理前,务必确认这项配置符合团队的数据合规要求。

3. 虚拟环境不是沙箱

Python 的 .venv 虚拟环境只隔离 Python 依赖包,完全不会限制子进程中的 bash / pwsh 读写宿主机文件系统。真正的隔离边界来自运行脚本所用的容器、虚拟机或操作系统账户权限。维护者应明确哪些宿主机路径对进程可见,以及谁有权读取 --dsh-home/sessions/ 下的 JSONL 日志。

八、边界说明

  • --workspace 不是安全沙箱:sdk-minimal 的 shell 固定使用 danger-full-access,可以读写运行时可见的任何路径。运行修改类任务前,请使用一次性 checkout 或受控容器,并自行核实容器的实际隔离能力。
  • 提示词措辞不等于只读限制:即使提示词只要求「查看」或「分析」,底层 shell 仍有写权限。验收结果时必须检查工作区文件变更,不能只看 final_response 文本。
  • 不同 --dsh-home 只是配置与数据的目录组织方式,不能单独证明进程无法访问宿主机上的其他目录。
  • 自动压缩不等于删除数据:完整会话事件仍保存在所选 home 的未压缩 JSONL 日志中。分享诊断材料前,请先检查其中是否包含代码、路径、提示词或凭据,并留意默认会话日志贡献器的上传行为(可通过 profile patch 关闭)。
  • 包能安装不代表经过安全背书:通过 dsh plugin 向 home 添加插件前,仍须自行核查源码、构建脚本和权限要求。

九、相关术语速查

  • SDK:启动并连接已配置 dsh 子进程的 Python 客户端库(deepseek-harness-sdk)。
  • Profile:选定的应用组合与配置层;SDK 默认启动 sdk-minimal。
  • Harness home(--dsh-home):保存所选 profile、已安装插件和 sessions/ 会话日志的独立目录,不会静默回退读取 ~/.dsh。
  • Session(--session-id):由会话 ID 标识的追加式事件日志,模型可见的消息历史由它派生。
  • 上下文压缩(Compaction):通过模型总结较早历史以应对上下文窗口压力的机制,不会删除底层完整日志。

相关阅读

本文依据 DeepSeek Harness 官方 Python SDK 指南、会话子系统参考与 CLI 参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog

目录
相关文章
|
4天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1811 4
|
6天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
6天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
4天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
3933 2
|
19天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
8936 58
|
14天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
3139 9
|
20天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5878 69
|
7天前
|
云安全 人工智能 安全
|
12天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1962 2