DeepSeek Harness Python SDK 启动失败？profile、插件与 patch 报错

DeepSeek Harness Python SDK 在启动期是“快速失败”的：profile 缺 JSON-RPC server 配置、插件无法解析、patch 非法，三类问题都会直接终止启动，不会回退到其他组合。 这和“模型请求失败还能重试”不一样，配置层的问题必须先修到能启动。排查顺序也很固定：先确认 profile 结构，再看插件解析，最后看 patch。

DeepSeek Harness：三类启动失败的对照

同样是“SDK 起不来”，报错位置不同，修法完全不同。 对照如下：（来源）

先看报错里点名的是 profile、包名还是 patch 文件，再决定从哪一层动手。不要一上来就重装 SDK。

DeepSeek Harness：缺 server 配置怎么修

SDK 不是“任意 profile 都能跑”，它要求 profile 里有一个 JSON-RPC server 配置项。 修法：（来源）

1. 换回随附 profile — 先用 profile="sdk-minimal" 或 profile="sdk" 验证 SDK 本身可用。预期：最小任务能跑通。
2. 检查自定义 profile — 打开 $DSH_HOME/profiles/<name>/package.json，确认 bundles 含 SDK 相关组合包。预期：不是只抄了 web 的配置。
3. 补 server 配置 — 在 profile patch 里加入 @deepseek-ai/dsh-sdk-app 或等价的 JSON-RPC server 条目。预期：启动时不再报缺 server。

如果你只是想要一个隔离环境，最稳的做法是用 --from-default-profile 从 sdk-minimal 模板新建，而不是手写一个空 profile。

DeepSeek Harness：插件无法解析怎么修

解析失败通常不是“插件坏了”，而是“这个 profile 里没有它”。 排查：（来源）

1. 确认当前 profile — SDK 构造时传的 profile 是哪个，就去哪个 profile 目录找。预期：不会在 web profile 里找 sdk-minimal 的插件。
2. 看依赖是否安装 — dsh plugin --profile <name> list 或用 pnpm 查看。预期：包名与 patch 里引用的一致。
3. 看 patch 引用 — patch 里的 name 是否是绝对路径或完整包名。预期：不是相对路径错位。
4. 重装缺失包 — 用 dsh plugin --profile <name> add <package>。预期：解析恢复。

如果包在另一个 home 里，复制 patch 过来也不会自动带依赖；要么在新 home 重装，要么把 patch 与依赖一起迁移。

DeepSeek Harness：非法 patch 怎么修

DeepSeek Harness 的 patch 会替换目标行的整个 config，不是深度合并；这是最常见的“非法”来源。 排查：（来源）

1. 先备份 patch — 复制 cordis.patch.yml 与本次传入的 patch 文件。预期：改坏时可以回退。
2. 只保留一个 patch — 暂时去掉构造时的 patches 元组，只留 profile 持久 patch。预期：排除多文件叠加导致的冲突。
3. 逐段恢复 — 每次只加回一个 insert 或一个 config 块。预期：能定位到具体哪一段导致失败。
4. 用 dump 验证 — dsh --profile <name> --dump-config。预期：dump 成功后再启动 SDK。

常见错误包括：YAML 缩进不一致、insert 目标 id 不存在、只写了半个配置对象、把数组写成了对象。patch 不是“补丁越短越安全”，而是要满足目标 schema。

DeepSeek Harness：用 dump 做二分定位

dump 是启动前最便宜的验证：它不启动应用，但会走配置组合、patch 解析与插件解析。 三种用法：（来源）

1. 先 dump 默认配置 — --dump-default-config。预期：模板本身没问题。
2. 再 dump 有效配置 — --dump-config，带上同样的 --patch。预期：能复现失败就说明在配置层。
3. 最后 dump schema — --dump-config-schema。预期：确认字段名与类型没写错。

如果 dump 成功而 SDK 仍失败，重点回到 profile 的 server 配置；如果 dump 失败，按 stderr 里点名的文件与目标修 patch。

DeepSeek Harness：三种失败的最小复现实验

不要一次改三处；每次只引入一个变量，才能知道是哪类失败。 三个实验：（来源）

1. 只换 profile — 用随附 sdk-minimal 跑同一段 Python 代码。预期：能跑通就说明 SDK 本身与环境没问题，问题在自定义 profile。
2. 只去掉 patches — 保留 profile，去掉构造时的 patches 元组。预期：能启动就说明本次传入的 patch 非法。
3. 只留一个插件 — 在 profile patch 里逐段注释，只保留最小 insert。预期：能定位到导致解析失败的包或行。

每次实验前备份 cordis.patch.yml 与 package.json，实验后恢复。三次实验做完，基本能锁定是 profile、patch 还是插件依赖。

最后再看一遍启动日志的末尾：真正的原因通常在最后一条“无法解析/无法校验”的报错里，前面的加载信息只是背景。

修复后按这四项复查：

1. 同一 profile 能稳定启动三次。
2. 最小任务能返回最终文本。
3. dump 的层来源与预期一致。
4. 会话日志仍写在原 home。

profile 最小结构长什么样

先确认 profile 不是只建了一个空目录。 一个可启动的 SDK profile 至少要有：

• package.json — 含 dsh.profile 与 bundles 列表，且引用 SDK 相关组合包。
• cordis.patch.yml — 可以为空，但文件本身要能被 YAML 解析。
• 可解析的依赖 — bundles 里点名的包必须在该 profile 的 node_modules 或内置安装里存在。

可以用 dump 快速验证结构：

dsh --profile sdk-minimal --dump-config >/tmp/sdk.yml

dump 成功说明配置层能组合；dump 失败先修 patch 或依赖，不要继续改 Python 代码。

DeepSeek Harness 常见问题

Q：能不能让 SDK 在启动失败时自动退回 sdk-minimal？ 不能。官方明确说缺失 server 配置、无法解析的插件和非法 patch 会在启动时失败，不会回退。要兜底就在应用层捕获异常并显式换 profile。

Q：删掉整个 home 能最快恢复吗？ 能恢复，但会丢会话、插件与配置。更稳的做法是备份后只重建 profile，或先用一个新 home 验证 SDK 本身。

Q：patch 写对了，为什么换台机器就启动失败？ 依赖没有跟着 patch 走。patch 只描述配置，不携带包；新机器需要在对应 profile 里重新安装插件。

一句话收束： SDK 启动失败先分三类：profile 缺 server、插件解析不到、patch 非法；三类都不会自愈，只能按 dump 结果逐项修。