DeepSeek Harness Python SDK 怎么升级？wheel 与内置 dsh 运行时

DeepSeek Harness Python SDK 的升级不是“换一个 Python 依赖”，而是“换一整套运行时”：wheel 里同时包含匹配的原生运行时与 dsh 命令，SDK 在运行时再延迟启动内置的 dsh --profile sdk-minimal 进程。 所以升级动作必须包含“装新 wheel + 重启进程 + 核对 profile patch”，只做第一步，旧进程还会继续用旧运行时。

DeepSeek Harness：升级的其实是三件套

一次 wheel 升级会同时改变 Python API、内置 dsh 运行时与随包 profile 模板。 三件套分别影响：（来源）

官方特别说明：sdk-minimal 不含 dsh-base，是在空根上插入的完整配置树。这意味着基础 profile 以后新增的工具不会隐式出现在 sdk-minimal 里；升级后如果发现“少了一个工具”，先查这个边界，而不是怀疑安装失败。

另外，wheel 仍然打包完整 web profile 与前端产物，dsh web 是独立 CLI 应用，不能拿来给 Python SDK client 提供服务。升级时要区分“SDK 内置运行时”和“你另外全局安装的 dsh”。

DeepSeek Harness：升级前记录什么

先把版本和配置基线记下来，升级后才有对照物。 三项：（来源）

1. Python 包版本 — python -m pip show deepseek-harness-sdk。预期：记下当前版本号。
2. 内置 dsh 版本 — 在同一个 venv 里执行 dsh -V。预期：确认它来自当前 venv，而不是 PATH 上另一个全局安装。
3. sdk-minimal 配置 — dsh --profile sdk-minimal --dump-config（如果 profile 已存在）。预期：保存升级前的有效配置，便于升级后 diff。

如果当前 profile 还没初始化，先跑一次 dsh --profile sdk-minimal --dump-default-config >/dev/null，让 profile 文件落盘。

DeepSeek Harness：升级步骤

在同一个 venv 里安装目标版本，然后重启 Python 进程，最后用最小任务验证。 步骤：（来源）

# 1. 进入 SDK 所在虚拟环境
. .venv/bin/activate

# 2. 安装目标版本（示例：固定版本，避免漂到未知版本）
python -m pip install --upgrade "deepseek-harness-sdk==<目标版本>"

# 3. 核对内置运行时
dsh -V

1. 固定版本安装 — 生产环境不要直接装“最新”，先固定到验证过的版本。预期：pip show 显示目标版本。
2. 重启宿主程序 — 关闭所有使用 DeepSeekHarness 的进程，再重新启动。预期：新进程启动时才会加载新运行时。
3. 跑最小任务 — 用 minimal.py 或一个只读任务验证。预期：能正常返回 final_response。
4. 核对 profile patch — 重新 dump 配置，和升级前基线 diff。预期：没有字段被静默删除或改写。

第 2 步最容易被忽略：SDK 会把内置 dsh 进程复用到上下文管理器退出，运行中的进程不会因为磁盘上 wheel 变了就切换运行时。

DeepSeek Harness：三种升级策略

就地升级、并行环境、版本锁定，适合不同的风险承受能力。 对比如下：（来源）

1. 就地升级 venv — 直接在原 venv 里装新版本。预期：最省空间，但回滚要靠重装旧版本。
2. 并行 venv — 新建 .venv-next 装新版本，验证通过后再切。预期：回滚只需切回旧 venv，适合生产。
3. 版本锁定 + 镜像 — 在依赖文件里固定 SDK 版本，用内部镜像安装。预期：多机一致，不受上游最新版波动影响。

无论哪种，DSH_HOME 都不要在升级时删除；profile、插件与会话都在里面。

升级完成后，把 pip freeze 的输出与 dsh -V 的结果一起记进变更记录。下次排查“为什么这台机器和那台行为不同”时，这两个版本号比任何猜测都快。如果团队用镜像源，也把镜像地址记上，避免“版本号相同但构建来源不同”的争论。

这份记录不需要很正式，一张表写清机器、Python 版本、SDK 版本、dsh 版本、镜像来源即可。出问题时，它往往比日志更早给出方向。

DeepSeek Harness：升级后常见不兼容

升级后的问题多数不是“装坏了”，而是旧 patch 与新配置树不再匹配。 四类：（来源）

1. patch 指向已移除的插件 — 启动时报无法解析。预期：从 cordis.patch.yml 删掉对应 insert 行。
2. str_replace_editor patch 失效 — 工具包名或挂载方式变化。预期：按新版本重新生成 editor.patch.yml。
3. sdk-minimal 少工具 — 它不含 dsh-base，不会自动获得基础 profile 的新工具。预期：需要时用 patch 显式加回。
4. 会话格式提示迁移 — 新版本要求迁移旧 JSONL。预期：按启动提示处理，不要直接删日志。

如果启动直接失败，先看报错是“缺 server 配置”“插件无法解析”还是“patch 非法”；这三类都不会回退到其他组合。

DeepSeek Harness：回滚与验证命令

升级前把旧版本号写下来，回滚时才不用猜。 一组可直接用的命令：（来源）

python -m pip show deepseek-harness-sdk | grep ^Version
dsh -V
# 回滚：装回记录的旧版本
python -m pip install "deepseek-harness-sdk==<旧版本>"
dsh --profile sdk-minimal --dump-config > /tmp/sdk-config-after.yml

1. 记录旧版本 — pip show 与 dsh -V 各一条。预期：知道回滚目标。
2. 装回旧版本 — 在同一个 venv 里固定版本安装。预期：不回退到其他 profile。
3. 重启并验证 — 重跑最小任务，确认 final_response 正常。预期：运行时与 Python 包版本一致。
4. 比对配置 — 用 dump 对照升级前后的 profile。预期：没有字段被静默删除。

回滚只换 wheel，不动 DSH_HOME；会话与插件仍在，但旧版本可能不认新格式，必要时按启动提示处理。

DeepSeek Harness 常见问题

Q：升级后需要重装插件吗？ 不一定。插件在 DSH_HOME 里，升级 wheel 不会删除；但如果插件与新运行时版本不兼容，需要按插件说明更新或重装。

Q：能不能用全局 dsh 升级 SDK 的运行时？ 不能。SDK 用自己 wheel 里的运行时；全局 dsh 是另一套安装。两者版本可以不同，但要分别记录，避免排查时看错版本。

Q：升级失败怎么回滚？ 并行 venv 直接切回旧环境；就地升级则重新安装旧版本 wheel 并重启进程。DSH_HOME 不动，会话与配置仍在。

一句话收束： SDK 升级要按“三件套”处理：换 wheel、重启进程、核对 profile；只换包不重启，等于没升级。