pip install deepseek-harness-sdk 已经装好,脚本也能成功 import,但真正运行第一个任务时,常见的卡点有三个:
- 以为只要系统里已经启动
dsh web,Python SDK 就能直接连接; - 以为传入
--workspace /path/to/repo后,Agent 就只能访问这个目录中的文件; - 换了任务再次运行,却沿用同一个
--dsh-home和--session-id,导致上次对话的上下文、持久补丁乃至日志混在一起。
想顺利跑通第一个任务,先要厘清 Python 客户端、sdk-minimal 进程、工作区(workspace)、Harness home 和会话(session) 这五者各自的边界。站内教程版可参考DeepSeek Harness Python SDK:运行第一个任务。
一、动手前先对齐五项前提
官方 Python SDK 指南明确列出了运行环境要求:
- Python 版本:Python 3.10 及更高版本;
- 基础工具:已安装 Git;
- 受支持的平台:Linux x64、Linux arm64、arm64 架构的 macOS 14 或更高版本,以及 Windows x64(其他平台是否支持,应先查看最新文档);
- 模型凭据:DeepSeek 兼容的 API endpoint 与对应凭据;
- 两个独立目录:隔离的工作区(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. 五步跑完第一次调用
- 在当前 shell 中设置
DEEPSEEK_API_KEY,切勿在日志、截图或命令行历史中泄露真实密钥。使用兼容代理时,也可以按指南设置DEEPSEEK_BASE_URL(模型与提供商的详细字段参见配置模型与提供商)。 - 准备两个绝对路径:分别用于一次性工作区(
--workspace)和独立的 Harness home(--dsh-home)。运行前,把下面命令中的占位路径替换为本机的真实绝对路径。 - 指定一个新的
--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."
- 检查最终回复和工作区中的实际文件变更。示例提示词要求「检查仓库并修复失败的测试」,任务本身就会修改文件;这也是前面强调使用一次性 checkout 或容器的原因。
- 为下一次运行规划 ID:如果下一个任务独立进行,就使用新的
--session-id;只有明确要延续同一段持久对话和会话资源时,才同时复用相同的 harness 配置、--dsh-home与--session-id。
3. --dsh-home 里到底落了什么数据?
运行后,指定的 --dsh-home 目录会保存三类内容:
- 自动生成的
sdk-minimalprofile; - 该 home 下安装的插件;
sessions/目录下未压缩的 JSONL 会话日志。
请注意:示例和 SDK 不会静默读取本机的 ~/.dsh。 官方会话参考将 Session 定义为追加式事件日志(append-only event log),模型可见的对话历史由这份日志派生。日志完整记录任务交互,因此可能包含敏感代码片段、路径或业务数据;保管和分享前,都应将其视为敏感材料。
三、Python 客户端与 sdk-minimal 进程是怎么配合的?
刚开始接入时,容易把 deepseek-harness-sdk 误认为纯 Python 实现的 Agent 循环。实际上,它的架构分工很清楚:
- 按需启动子进程:SDK 会等到首次真正执行任务时,才启动
dsh --profile sdk-minimal进程; - 在上下文管理器内复用:Python 的
with上下文管理器退出前,后续调用都会复用同一个dsh进程; - 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 通道。
五、第一次运行后,怎么分段验收与排障?
命令运行后,不要只凭终端是否报错来判断成功与否。建议分四个阶段验收:
- 进程启动阶段:如果进程在任务开始前就退出,先检查所选 profile 和配置层。缺少 JSON-RPC server 配置项、插件解析失败或补丁非法,都会直接阻断启动。
- 模型请求阶段:如果
dsh进程已启动,但模型请求卡住或报错,重点检查DEEPSEEK_BASE_URL和DEEPSEEK_API_KEY(排查时切勿将真实密钥贴进日志或工单)。 - 任务执行阶段:示例提示词
"Inspect the repository and fix the failing tests."远不只是一次「连通性 ping」。如果只是首次验证链路,可以先换成不要求修改文件的问题;但要记住:提示词写得温和,不等于系统强制了只读边界,极简 shell 的实际权限仍由操作系统运行环境决定。 - 结果核对阶段: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:运行第一个任务
- 权限预设怎样影响可用工具
- Agent 怎样读写和编辑工作区文件
- 上下文压缩与 /compact 命令
- 配置模型与提供商
- 更多 DSH 实践文章
本文依据 DeepSeek Harness 官方 Python SDK 指南、会话子系统参考与 CLI 参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog