DeepSeek Harness 报 CLIENT_UPGRADE_REQUIRED 怎么升级？模型版本门控

CLIENT_UPGRADE_REQUIRED 不是密钥问题，也不是网络问题，而是模型目录在说“这个模型需要更新版 DeepSeek Harness”。 报错通常会写明需要安装的版本。正确的处理顺序是：读版本要求 → 确认当前运行的是哪套安装 → 升级 → 重启 → 重新选择模型。反过来先去改 API key 或换模型名，只会把问题拖长。

DeepSeek Harness：报错怎么读

这条错误的关键信息是“所需版本”，不是“凭据无效”。 读法：（来源）

1. 看错误码 — 是否确实是 CLIENT_UPGRADE_REQUIRED，而不是 MISSING_CREDENTIAL 或 UNKNOWN_MODEL。预期：不会把三类错误混为一谈。
2. 看所需版本 — 报错会写明需要安装的版本。预期：知道升级目标，而不是盲目装最新。
3. 看触发模型 — 是哪个模型要求更高版本。预期：可以先换一个当前版本支持的模型继续工作。

这条门控来自模型目录，不是 provider 的鉴权层。登录 DeepSeek 账号时，模型列表来自账号服务；某个模型要求更高客户端版本时，就会以此失败。

DeepSeek Harness：三条升级路径

按你当前的安装方式升级，不要混用。 三种：（来源）

1. 全局 npm 安装 — 升级全局包到报错要求的版本。预期：dsh -V 显示新版本。
2. npx 运行 — 用带版本或 latest 的 npx 命令启动。预期：注意 npx 缓存，旧版本可能被复用。
3. 桌面端或源码构建 — 走各自的更新入口或重新构建。预期：桌面端与 CLI 的版本边界要分别确认。

如果报错要求的是具体版本，优先装那个版本，而不是直接 latest；latest 可能已经越过兼容窗口，也可能还没包含所需能力。

DeepSeek Harness：升级后的验证

升级不是“装完就算”，要确认运行中的进程真的换了版本。 步骤：（来源）

1. 确认版本 — dsh -V，并与 which -a dsh 对照。预期：当前进程来自你刚升级的那套。
2. 重启进程 — 关闭旧的 dsh web 或 SDK 宿主，再启动。预期：新进程加载新运行时。
3. 重新选模型 — 在模型选择器里选之前报错的模型。预期：不再出现 CLIENT_UPGRADE_REQUIRED。
4. 新建会话验证 — 旧会话可能保留旧模型记录。预期：新会话用新默认模型并正常返回。

如果第 1 步就发现版本不对，先解决多安装冲突，不要继续在应用层排查。

DeepSeek Harness：三种多版本冲突

同一个错误反复出现，通常是因为“升级的”和“运行的”不是同一套。 三种冲突：（来源）

1. 全局 vs npx — PATH 上的全局 dsh 与 npx 缓存各有一套。预期：用 which -a dsh 与启动命令对照。
2. 桌面端 vs CLI — 桌面端有自己的更新单元，CLI 单独升级不会改它。预期：分别确认版本。
3. venv vs 全局 — Python SDK 的 wheel 带内置运行时，升级全局 dsh 不会换 SDK 的运行时。预期：在 SDK 的 venv 里单独确认。

多安装不是错，但排查时必须先确定“当前进程是谁启动的”。

DeepSeek Harness：不要做的事

版本门控不能用配置技巧绕过，绕过去只会换一种失败方式。 三件不要做：（来源）

1. 不要改模型名硬套 — 请求结构可能不匹配。预期：升级或换支持模型。
2. 不要删会话重试 — 会话日志不是版本门控的原因。预期：保留日志用于对照。
3. 不要乱改 compat 开关 — 那是请求形状适配，不是客户端版本升级。预期：先读报错，再决定是否动 compat。

如果确实暂时不能升级，就在模型选择器里换一个当前版本支持的模型，把工作继续下去；等维护窗口再升级。

DeepSeek Harness：三种临时应对与代价

不能立刻升级时，可以临时绕过，但要清楚代价。 三种：（来源）

1. 换兼容模型 — 选一个当前版本支持的模型。预期：工作继续，但能力可能不同。
2. 换 provider — 用第三方或自建 provider 的等价模型。预期：请求形状与额度口径可能变化。
3. 降级使用 — 暂时不用触发门控的模型。预期：最稳，但功能受限。

不要用改模型名或伪造版本号的方式绕过；那会让错误从“明确门控”变成“请求结构不匹配”。

升级前的备份

升级 dsh 本体前，先备份 profile 与会话，避免回滚时丢配置。 三步：

1. 备份 $DSH_HOME — 至少复制 profiles 与 sessions。预期：回滚有依据。
2. 记录版本 — 当前 dsh -V、安装方式与包管理器版本。预期：知道从哪来、回哪去。
3. 记录模型 — 当前默认模型与会话里用过的模型。预期：升级后能对照行为差异。

升级完成后，用一次普通对话与一次模型选择验证，不要只看到界面打开就认为完成。

一条真实诊断链

从报错到定位，按“版本、安装来源、模型”三列对照。 诊断链：

1. 记下报错里的所需版本 — 例如报错要求某个具体版本。预期：知道目标版本，不盲目装 latest。
2. 查当前版本 — dsh -V。预期：与报错要求对比，确认差多少。
3. 查安装来源 — which -a dsh、npm ls -g --depth=0 或 venv 的 pip show。预期：知道当前进程来自哪套安装。
4. 查模型来源 — 是 DeepSeek 账号目录还是自定义 provider。预期：确认门控确实来自账号模型列表。

四步做完，通常只剩“升级正确的那套安装”一个动作；如果还有问题，再查模型目录缓存与重启。

DeepSeek Harness 常见问题

Q：升级后模型列表还是旧的，怎么办？ 重启进程，并在模型页重新打开 provider；模型目录可能在启动时加载。仍不对时，确认账号服务返回的列表是否已包含该模型。

Q：这条错误会影响所有模型吗？ 不会。它是按模型触发的；同一 provider 下其他模型可能仍可用。

Q：桌面端没提示更新，但 CLI 报错，怎么办？ 说明两者版本不同。按桌面端自己的更新入口处理，或先用 CLI 选一个兼容模型，不要假设桌面端会自动跟随。

一句话收束： CLIENT_UPGRADE_REQUIRED 是版本门控，不是凭据故障；先读所需版本，再确认运行的是哪套安装。