DeepSeek Harness plugins directoryDSH Pluginsdsh 插件市场
返回指南

DeepSeek Harness 插件排错：安装报错、Patch 冲突、版本回滚与 Profile 失效（2026）

DeepSeek Harness（dsh）插件问题逐步排查：pnpm workspace 白名单报错、cordis.patch.yml 覆盖顺序、Profile 不生效、插件装了不加载、升级后变慢——以及升级把插件弄坏时怎么锁版本与回滚。

最近更新: 2026-10-09

何时使用本指南

在「找到插件」与「插件正常运行」之间出问题时使用本页：dsh plugin add 失败、monorepo 里奇怪的 pnpm-workspace allowlist 报错、cordis.patch.yml 改了没反应、Profile 加载了错误的插件组合。每个小节都按同一结构展开——症状、原因、修复命令。

还没走到安装步骤？先读安全安装插件指南；不确定自己在改哪一层配置？先看配置详解。

动手之前先记住一条铁律：每次修改配置后都要重启 dsh。插件树在启动时由 Cordis 容器组装，「什么都没发生」的案例里一半只是改了配置忘了重启。

一、安装时提示找不到插件（Plugin not found）

症状：dsh plugin add dsh-some-tool 报解析错误，或者安装成功但插件始终没有出现。

原因：CLI 按精确包名从 npm registry 解析。常见原因：包名拼写错误、少了 @scope/ 前缀、插件只通过 GitHub 分发（npm 上没有条目）、或 --profile <name> 与之后启动的 Profile 不一致——条目加进了你从未启用的 Profile。

修复步骤：

  1. 先用 npm view dsh-some-tool 核对包的确切名称。插件的详情页与仓库 README 会给出可用的安装命令——社区插件的安装方式由插件自己维护。
  2. 插件只在 GitHub 分发时，用源码地址安装并锁定分支：dsh plugin add github:owner/repo#main。
  3. 让参数与启动方式一致：用 dsh plugin --profile web add <package> 安装的，就用 dsh --profile web 启动，不要裸执行 dsh。
  4. 本地开发时直接链接目录：dsh plugin add ./path/to/my-dsh-plugin。

二、安装卡住或失败：pnpm workspace allowlist

症状：在 pnpm monorepo 中安装插件时卡住，或报 pnpm-workspace allowlist、module not found、ESM & CJS 解析错误——尤其是从 git 或本地构建安装时。

原因：pnpm 严格限制依赖边界。从 GitHub 安装的插件实际上进入了工作区，如果包没有在边界内声明，pnpm 不会链接它，运行时就无法解析插件或其依赖。

修复步骤：

  1. 把包声明进边界：在根目录 package.json 的 dependencies（或 pnpm-workspace.yaml 的允许清单/目录）中加入该插件，然后在工作区根目录执行 pnpm install。
  2. 重新安装并重启：dsh plugin add <package>，再启动 dsh 让重建后的插件树生效。
  3. 有 npm 发布版时优先使用发布版：发布包自带依赖，天然绕开工作区边界问题。
  4. 确认运行环境：node -v 应输出 20.0.0 及以上。

还卡着？2026 年「安装卡住」的两个新收据（#9178、#9261）

官方讨论区新增的两种形态，正对应「dsh 安装卡住」这个搜索：

  1. Windows 上 dsh plugin add 挂起不退出（#9261）。 命令停着不返回，profile 的 bundles 一直不 reconcile。重跑 add 命令——瞬时网络中断是最常见诱因——并检查到 registry 的网络链路，直连慢就换镜像。
  2. 插件悄悄装了旧版本，随后被判不兼容（#9178）。 pnpm 11 起 minimumReleaseAge 默认 24 小时：今天发布的版本对解析器不可见，安装静默降级到旧版本——旧版本又可能过不了兼容检查。装明确 package@version，或确要追新就调整 minimumReleaseAge。

三、cordis.patch.yml 冲突（覆盖顺序问题）

症状：两个插件功能重叠——两个侧边栏、两个 OCR 引擎、同一个服务的两套实现——其中一个的设置被静默忽略；dsh 可能提示 Profile patch collision / Override order issue。

原因：patch 是覆盖层，叠加在 bundle 与 profile 之上，后写的条目胜出。当两个条目注册同一服务或同一 UI 面板时，声明顺序决定结果。YAML 里重复的键或缩进错误，也可能悄悄改写条目。

修复步骤：

  1. 打开你实际使用的文件：cat ~/.dsh/profiles/<name>/cordis.patch.yml，工作区内则是 <项目根>/.dsh/cordis.patch.yml。
  2. 调整顺序：把希望生效的插件移到 plugins: 列表末尾——后面的条目覆盖前面的。
  3. 或者保留两者、解除冲突：把其中一个条目的 enabled 设为 false。
  4. 最干净的长线方案：把冲突插件拆进不同 Profile，用 dsh --profile <name> 分别启动。
  5. 重启前先校验 YAML——一次缩进错误就会改变条目的含义：yq eval . cordis.patch.yml。

四、dsh bundle 格式错误

症状：dsh 能启动，但插件组合与文档描述完全不同；或者从别处复制来的配置文件不断报冲突、加载失败。

原因：三个配置层各有分工：bundle 是随 dsh 分发的官方插件集合，profile 是你自定义的「bundle + 插件」组合，patch 只针对单个插件条目做外科手术式覆盖。如果 cordis.patch.yml 把整套 bundle 重新声明了一遍——几十条插件外加本应属于 profile 层的设置——格式就混了，这些覆盖项开始与 bundle 自带内容互相打架。

修复步骤：

  1. 让 patch 保持精简——每个插件一个条目，只有 enabled 与 options：
# ~/.dsh/profiles/default/cordis.patch.yml
plugins:
  dsh-vision-toolkit:
    enabled: true
    options:
      ocrEngine: 'default'
  1. 想一次启用整套插件？那是 profile 层的职责：在 profile 里配置组合，而不是把每条插件都粘进 patch。
  2. 删掉重复条目、保存并重启 dsh。此时插件的工具/面板应当正常加载，不再打印冲突信息。

五、Profile 不生效

症状：改了 cordis.patch.yml，重启后没有任何变化；或者为某个 Profile 安装的插件无处可寻。

原因：三选一的经典失误：改错了文件（配置文件有两处，且项目级覆盖全局级）、启动时用的 Profile 名与修改的目录不一致、或者压根没重启。

修复步骤：

  1. 先看两处文件是否都存在：ls ~/.dsh/profiles/*/cordis.patch.yml 2>/dev/null，以及项目根目录下 ls .dsh/cordis.patch.yml 2>/dev/null。
  2. 记住优先级：两者都存在时 <项目根>/.dsh/cordis.patch.yml 覆盖 ~/.dsh/profiles/<name>/cordis.patch.yml。
  3. 让参数与目录一致：改了 ~/.dsh/profiles/web/cordis.patch.yml，就用 dsh --profile web 启动——不是 dsh，也不是 dsh --profile headless。
  4. 重启验证：dsh --profile web，检查插件的工具或面板是否出现。还是没有？看下一节。

六、插件装上却加载不了（failed to register）

症状：安装成功、配置看着没问题，但启动时 dsh 报 Plugin failed to register / Lifecycle timeout——或者插件无声无息地没加载。

原因：通常是运行时太旧（Node.js 低于 20）、依赖缺失（git 安装需要自己构建）、声明顺序与别的插件冲突，或条目被留成了 enabled: false。还有一个相关的失败模式是沙箱：dsh 默认 read-only 运行，需要读写磁盘或访问网络的插件可能在加载时就被拦下，报 Permission denied / Sandbox security policy violation。

修复步骤：

  1. 检查运行时：node -v——升级到 20.0.0 及以上（推荐 Node 22 LTS）。
  2. 源码安装需要构建：进入插件目录执行 pnpm install && pnpm build，然后重启。
  3. 干净重装：dsh plugin remove <package>，确认 cordis.patch.yml 中的条目，再 dsh plugin add <package>。
  4. 确认条目处于启用状态：dsh plugin add 会写入 enabled: true；如果手改过 YAML，检查它还在不在。
  5. 如果报错与沙箱有关且插件可信，启动时放行：dsh --sandbox workspace-write（详见安全沙箱指南）。
  6. 通过 dsh-market Web UI 安装的？去 Settings → Plugin Market 看插件状态——后台会应用配置并热重载，失败状态会显示在那里。

七、升级后变慢 / 性能回退

症状：升级 dsh 之后，打开旧会话、恢复会话或持续对话时明显变卡，会话越长越明显；或对比旧版本，整体感觉性能回退。

原因：多半不是你装坏了插件。长会话卡顿是旧版本的已知问题——早期版本的会话数据存储格式偏重，消息一多，打开、恢复与每一轮对话都要付出额外的内存与解析成本。

修复步骤：

  1. 先升级到当前稳定线再下结论：长会话卡顿在 v0.1.5 已修复（优化存储格式、降低内存占用），且截至 2026-09-29，npm latest 是 0.2.0-rc.2。执行 npm install -g @deepseek-ai/dsh@latest，重启后用同一段长会话对比验证。多数「升级后变慢」其实是旧版本的已知问题，升级即解。实验通道已与 latest 持平——next 同样指向 0.2.0-rc.2，alpha 指向 0.1.7-alpha.2——但排查性能问题不该从 alpha 通道起步。
  2. 升级后仍慢？超长上下文场景改用 Minimal profile 启动（见 GitHub 讨论 #5485）：dsh --profile minimal 只加载持久终端等基础工具，减少随会话注入的内容——日常用 Standard，超长会话用 Minimal。
  3. 仍有问题：收集日志反馈——附上 dsh --version、启动命令、会话规模（消息条数/文件大小）、控制台报错与你的对比结果，到官方仓库开 issue。数据越全，定位越快。

八、升级后插件挂了（锁版本 / 回滚）

症状：dsh 自更新，或你执行了 npm install -g @deepseek-ai/dsh@latest，昨天还能用的插件今天加载失败、面板消失、报注册错误——有时只在某一个 profile 下复现。

原因：升级会坏在两件事上。其一是 harness 换了对外挂的契约：v0.1.6-alpha.2 的官方发布说明把「插件依赖解析」改为运行时解析，并新增运行时卸载，同时点名要求插件开发者复查加载与卸载逻辑——旧契约下正常的插件，在作者适配前就可能失败。其二是你自己的配置错位：条目留在你不再启动的 profile 里，或重排后两条相互覆盖。版本节奏也是现实变量：0.1.6 线两天连发两个 alpha（09-15、09-17），稳定线在 0.1.5-rc.3 停到 09-28 的 0.1.7-rc.2 翻转——同日的 0.2.0-rc.1 又重做了插件管理界面，所以 0.2.0 预览版带着真实的兼容性成本（见下一节）。

修复步骤：

  1. 先定位是 dsh 还是插件：用精简档启动 dsh --profile minimal，它只加载持久终端等基础工具。若问题在这里消失，锅在插件。动手改任何东西之前，先记下 dsh --version 与完整启动命令（含 --profile <name>）。
  2. 读启动诊断：0.1.6-alpha.2（alpha 通道）起，启动失败会分类显示错误与等待中的服务，并把完整诊断写入日志文件——先读它，再决定卸什么。
  3. 整体不稳就锁 harness：npm install -g @deepseek-ai/dsh@0.1.5-rc.2——写死版本号，绝不用 @latest。这就是回滚：退回去的目标就是上次可用的稳定线版本。
  4. 只有单个插件坏就锁插件：dsh plugin remove <package>，再用标签安装 dsh plugin add github:owner/repo#v1.2.3（#ref 位置可写 tag 或分支）。若该插件没有可用标签，别删配置，把它在 cordis.patch.yml 里的条目设成 enabled: false 并重启，等修好再打开。
  5. 动手前先备份：cp ~/.dsh/profiles/<name>/cordis.patch.yml ~/dsh-profile-backup.yml。一次回滚顺带丢掉整套插件配置，比原问题更糟。
  6. 排查多实例冲突：如果 dsh 提示会话被其他 DSH 实例占用，官方做法是退出那个实例再重试——服务器常驻实例与本机实例共用同一个 profile 时很常见（见 服务器部署与多人共用）。
  7. 改完必须重启验证。插件树在启动时装配，没重启之前上面每一步都算不上验证过。

如果你是有意停在 alpha 线，就要接受这件事：发布说明把适配责任交给了插件作者，生态是一支一支插件在追。社区插件对你构成关键路径时，留在 latest，等 alpha 线沉淀。

九、Windows 沙箱权限：0xC0000142 与访问被拒

症状：Windows 上沙箱命令全部报 0xC0000142 (STATUS_DLL_INIT_FAILED)，或受限模式下子进程输出无法捕获（Access is denied），或桌面端启动沙箱 PTY 直接失败，或供给阶段直接报 SetNamedSecurityInfoW failed (Win32 5)——报告多集中在升级 dsh 之后，且整个 0.2.0-rc 线期间讨论区的新帖仍在持续增加。

原因：内置 Windows 沙箱在启动时为目录配置 ACL，官方讨论区已记录的故障形态可以分成三族。0xC0000142 族：非管理员启动时 workspace-write 供给失败并留下无法自愈的损坏 ACL（#8115）；桌面端连 pwsh/cmd echo 这类无害命令都报 0xC0000142（#8208、#8295）；0.2.0-rc.1 的 Electron 宿主下沙箱子进程一个都起不来（#8193）；加上更早记录的桌面端全灭（#8142、#8130）、CLI/Web（npx）形态的 stdio 捕获确定性失败 + 间歇 0xC0000142（#8143、#8141）、minimal 预设 PTY 退出码 127（#8158），以及 10 月初的一波高峰——24 小时内连出四份新报告：Win10 LTSC 启动（#8877）、无控制台启动（#8878）、confined pwsh 内 DLL 初始化失败（#8890）、workspace-write 供给在 pwsh 中失败（#8897）。WRITE_OWNER 族：工作区放在数据盘（比如 D:\...）时，盘符默认继承 ACL 只隐式给 WRITE_DAC，而 grantWrite 要以 WRITE_DAC | WRITE_OWNER 打开工作区根目录，于是报 Win32 5 失败——此后该会话内所有经沙箱的命令全部不可用，连只读命令也一样，而文件读写工具不受影响（#8232、#8272、#8275、#8282，以及 10 月新增的 WRITE_OWNER Win32 5 报告 #8886）。回归族：0.1.5 → 0.1.7-rc.2 让受限子进程掉进 ConstrainedLanguage、所有授权写入被拒（#8219）；workspace-write 还顺带搞坏了 git for Windows——MSYS 二进制起不来、schannel 够不到证书库（#8209）。而第四波在 10 月 6–7 日两天内就到齐：打包版桌面端所有 workspace-write 命令一律以 3221225794/0xC0000142 退出（#9031）、confined pwsh 的每条命令都死于同一错误（#8991）、Win11 的 pwsh 工具调用同样失败（#8990），外加 #8971 给出的有用对照——同一台机器跑 0.1.5-rc.2 的 workspace-write 沙箱一切正常。

修复步骤：

  1. 先定性再动手：记下故障形态（每条命令都失败还是偶发、桌面端还是 npx、系统盘还是数据盘），收集 dsh --version 与启动诊断日志。
  2. 升级到 0.2.0-rc.2 或更新版本，跑官方一键诊断修复：rc.2 发布说明把 Windows 沙箱权限脚本改为「经授权后一次完成诊断与修复，保留修改前备份和恢复命令」。在会话里让 agent 诊断沙箱权限，先跑它再考虑手工处理（rc.1 时代的诊断与修复是分开的两步，#8272 记录了当时的痛点）。
  3. 针对 WRITE_OWNER 形态：把工作区挪回用户目录，或给你的账户在数据盘根目录上显式补 WRITE_OWNER 授权——升级后的一键修复做的正是这件事，且带备份。退而求其次，先用管理员终端启动一次让 provisioning 干净跑完，再回普通（非管理员）终端复测。
  4. 若损坏的 ACL 仍在：删掉上次失败 provisioning 留下的沙箱 profile 目录，让下次启动从头重建（动手前先备份 cordis.patch.yml——见第八节）。
  5. 仍然失败：带着诊断文件去上面的讨论帖簇里补充你的报告——正是这些细节在帮助区分不同故障形态。

十、网络与认证报错：代理配置与「API key is invalid」

症状：公司代理环境下请求超时或卡死，但浏览器一切正常；或会话直接回 API key is invalid（401）、Insufficient Balance（402）、403 类权限错误。

原因：dsh 走的是你所在环境的网络：npm 认的代理而 dsh 进程不认（或反过来），表现就是卡住和超时，而不是干净报错。至于 key 无效，多数是低级原因——粘贴时带了空白字符、key 绑错了服务商、填进了错误 profile 的设置里，以及著名的「登录密码被自动填进 API Key 输入框」（0.1.7-rc.2 专门缓解过这个）。

修复步骤：

  1. 先管代理：给启动 dsh 的进程设置标准变量 HTTP_PROXY / HTTPS_PROXY / NO_PROXY，重启 dsh 再试。插件下载慢是另一条路径，用安装指南的镜像源一节解决。
  2. 想要图形界面？kanneiren/dsh-network-settings（★107）能诊断 dsh 进程的真实网络路径、DNS 与首个失败点；kriskite/dsh-network-proxy（★8）在设置页里管理系统/手动/直连三种代理模式。
  3. 遇到 API key is invalid：去服务商后台重新生成 key，干净粘贴（不带空格换行），确认它属于设置里实际选中的服务商。
  4. 重试前先读状态码：401 是 key 本身错了（换 key），402 是账户没余额了（充值——见余额指南），403 是 key 有效但无权用这个模型或地区（换模型或账号）。

十一、dsh: command not found（命令不存在）

症状：终端报 dsh: command not found（命令不存在/找不到）；或者桌面端在 PATH 上找不到 dsh 启动器（#8268）；或者昨天还能用的启动命令升级后突然「失效」（#8242）。

原因：CLI 装在 npm 全局目录里，所以问题几乎总是三种之一：全局目录不在 PATH 上（用 nvm/fnm/volta 等版本管理器或自定义 prefix 时最常见）、安装根本没完成、或者从图形界面启动的桌面应用继承不到你 shell 里的 PATH 追加项。web 变体——敲 dsh web 只得到 zsh: command not found: dsh——是同一个毛病从 Web UI 门口看过去的样子：CLI 压根没启动，轮不到 Web 部分出错。

修复步骤：

  1. 先定位可执行文件：npm prefix -g 打印全局 prefix，dsh 可执行文件就在它下面的 bin 目录里。拿这个目录和 echo $PATH 对一下。
  2. 重装并开一个新终端（新 shell 会重新读 PATH）：npm install -g @deepseek-ai/dsh。
  3. macOS / Windows 桌面端：用 0.2.0-rc.2 菜单栏新增的 「Manage dsh command」——官方代你安装和管理 dsh 命令（含插件），不需要另装 Node.js 或 pnpm；从 GUI 启动、看不到 shell 环境的场景也一并解决。
  4. 应急方案：npx @deepseek-ai/dsh web 不做全局安装也能跑当前版本。

十二、桌面端所有命令零输出报 0xC0000142（已解决案例）

症状：桌面端里每条命令都返回 0xC0000142，而且没有任何输出——不打印错误文本，什么都不出。同一台机器上，把同样的命令放进普通终端跑就一切正常。把这个形态钉死的报告（#8395）已标记为已解决。

原因：0xC0000142 是 STATUS_DLL_INIT_FAILED——沙箱子进程在创建阶段就死了，根本轮不到输出任何东西。danger-full-access 模式不套受限令牌，同一条命令自然能跑——所以「命令行里正常」正是这个形态的签名，而不是矛盾。#8336 的受控实验把矩阵钉死了：受限令牌（WRITE_RESTRICTED + Low 完整性）只要与任一控制台隔离标志（CREATE_NO_WINDOW / CREATE_NEW_CONSOLE）同现，子进程必死；单独任何一个都还能活。已解决案例里的变量是安装位置——桌面端被装到了自选目录，而不是默认位置。

修复步骤：

  1. 先对形态：CLI 正常、桌面端静默死 → 就是本节。动手前记下 dsh --version。
  2. 已验证的解法（#8395）：卸载桌面端，装回默认安装位置——安装时不要自选目录。
  3. 被卡住时的官方绕开方案：把 DSH_HOME 指到你的 harness 主目录，再用 ELECTRON_RUN_AS_NODE=1 启动同一入口——这是 #8395 里记录的官方临时办法。
  4. 验证：在 workspace-write 下跑一条无害命令，输出应当回来。还是死？回第九节跑一键修复。

十三、workspace-write 授权总不生效：ACL 三缺陷（以及 ERROR_NONE_MAPPED 1332）

症状：workspace-write 已授权，但往工作区子目录里写文件照样被拒；桌面端对同一个工作区反复失败，直到重启才好；标准（非管理员）用户的工作区放在非系统盘上，grantWrite 报 Win32 5；想手工清理 ACL 时，icacls /remove 回你一个 ERROR_NONE_MAPPED (1332)。

原因：讨论 #8409 记录了 Windows ACL 沙箱的三个独立授权缺陷。其一，受保护 DACL 之下的子目录永远不会拿到授权，所以根目录授权成功后，子目录写入照样被拒。其二，桌面端对根目录授权只评估一次并缓存结果、之后不复核——一次失败的评估会一直失败下去，重启桌面端会重新评估、自愈。其三，标准用户在非系统盘上对盘根缺少 WRITE_OWNER，grantWrite 因此报 Win32 5——即第九节的 WRITE_OWNER 族。1332 则是另一回事：能力 SID（capability SID）没有映射到任何账户，icacls 无法按名字删除它——这个报错的意思是「没有可映射的对象」，不是「你的 ACL 损坏了」。

修复步骤：

  1. 先跑官方一键修复（第九节第 2 步）——这是受支持的路径，而且自带备份。
  2. 桌面端对明明该工作的区反复失败？重启一次桌面端，让缓存的根授权重新评估——#8409 记录的自愈路径。
  3. 标准用户 + 数据盘：把工作区挪回用户目录下（或者给你的账户在盘根补 WRITE_OWNER——一键修复自动做的就是这件事）。
  4. 别跟 icacls 的 ERROR_NONE_MAPPED 1332 较劲：未映射的能力 SID 无法按名字删除，把 ACL 交给官方修复脚本处理——手工剥离可能把沙箱 profile 弄得比缺陷本身更糟。
  5. 验证：让 agent 在工作区的子目录里创建一个文件（缺陷一发生在根目录之下），然后重启一次桌面端再复测。

十四、dsh 直接起不来：Smart App Control 与杀软 TLS 拦截

症状：两种「看着像 dsh 的锅、其实不是」的主机级拦截。Windows 11 开启 Smart App Control 的机器上 dsh 无法启动（#8377）；桌面端（0.2.0-rc.2）装了某些杀软后，宿主进程的所有 HTTPS 请求全部失败，界面上只有一个通用错误——登录永远完不成（#8448）。

原因：Smart App Control 会拦截未签名的原生模块，而 dsh 恰好带了一些——启动在我们自己的任何日志之前就失败了；事件查看器的 CodeIntegrity 日志里会留下 3077/3033 事件作为凭证。杀软这种形态是 TLS 换证：卡巴斯基类的「加密连接扫描」拦截 HTTPS 并用杀软自己的证书重新签名，宿主进程不认这条证书链，所有 HTTPS 流量死在一个通用错误背后。

修复步骤：

  1. Smart App Control：先去事件查看器确认 CodeIntegrity 3077/3033——这是该形态的指纹。然后关闭 Smart App Control，启动即恢复（#8377）。SAC 没有按应用放行的名单，没法单独给 dsh 开白。
  2. 杀软 TLS：把 dsh 相关域名加入杀软的排除名单，或关闭「加密连接扫描」类功能——任一操作都能恢复宿主的 HTTPS（#8448）。
  3. 验证：改完后启动一次（SAC）或登录一次（杀软）。还是通用错误？收集宿主日志和 dsh --version，先和第十节的代理形态对照一遍再上报。

十五、Web UI 提示 authentication required（或端口被占用）

症状：dsh web（或 npx @deepseek-ai/dsh web）启动了，页面却报认证错误（authentication required）；或者端口被占用；或者敲 dsh web 只得到 zsh: command not found: dsh。搜索引擎把这三句话当同一个问题——它们有三个不同的答案。

原因：Web UI 的访问地址由命令自己打印，其中带着本次启动的上下文——官方文档原话是「命令会打印它的 URL」。所以徒手敲裸地址 127.0.0.1:3080 可能撞上认证门，而不是控制台。端口被占说明另一个 dsh 实例（或残留进程）已经占着 3080——即第八节的多实例冲突。command not found 则是第十一节的 PATH 问题，和 Web UI 无关。而且这道门是内置设计：讨论 #5936（标题就是 dsh web authentication required）请求把强制 token 认证做成可选——至今没有落地，所以内网部署撞上的也是同一道墙。

修复步骤：

  1. 重新打开 dsh web 打印的那个完整 URL——或者干脆重跑一次命令让它自己打开——不要手敲裸地址。
  2. 从 SSH 启动的只打印主机 URL 是预期行为；去持有端口转发的机器上的浏览器里打开它。
  3. 端口被占：退出占用会话的另一个实例（第八节的多实例处理），或者换个端口启动：dsh --profile web --port 8080。
  4. command not found：先把安装修好（第十一节——npm 全局路径，或桌面端的「Manage dsh command」）。
  5. 真心要把控制台暴露到回环之外（反向代理、共用内网服务器）？token 门照样在——它不可选。社区路线是 hxy91819/dsh-auth（★6，2026-10-03 经 GitHub API 复核）：用受管的 Caddy forward_auth 边车加 Argon2id 管理员登录，dsh 本体保持只听回环（展示帖是 #3231）。能用但早期：要求 Linux x64/ARM64 + systemd + Node 24.7+，star 数这个量级意味着用户基数还小——放到公网 URL 前面之前，先读它的 README。
  6. 继续深入：Web UI 图文详解逐帧讲过整个界面；远程与手机访问合集收了 dsh-pocket、dsh-web 等手机/远程客户端；远程访问指南讲怎么从外网穿透回来。
  7. 验证：打印出来的 URL 能打开控制台，选好工作区后输入框可用。

十六、API key is invalid（401）——钥匙不一定真的是问题

症状：会话或任务直接死于 API key is invalid 这个原样报错（通常带 401），或 403 一类的权限错误。搜到这里的人敲的是完整错误短语——而在已记录的案例里，钥匙有时是好的：同一把 key 在一个界面能用、换个界面就被拒，或者 key 明明没问题却一直报错。

原因：三种常见低级问题覆盖大多数命中：key 粘贴时带了首尾空白或换行；key 属于另一个 provider，与 Settings → Models 里实际选中的不一致；或者 key 存进了另一个 profile 的设置，与你启动的 profile 不同。再往外，讨论 #5794 记录了两例「界面不一致」形态——Web UI 与 headless 运行读取的并不是同一份凭据，一边能用、另一边被拒。还有两份报告（#3073、#3222）显示 provider 适配层把非认证失败也包装成 API key is invalid 抛出——所以单凭报错文字，不能断定 key 坏了。

修复步骤：

  1. 重试之前先读状态码（第十节的分诊口径）：401 = key 本身被拒，修 key；402 = 账户余额不足，充值；403 = key 有效但没有该模型/地区的权限，换模型或换账号。
  2. 去 provider 重新生成 key，干净粘贴（不带空白/换行），并确认它属于 Settings → Models 里实际选中的那个 provider。
  3. 界面不一致（#5794）：如果 Web UI 能用而 dsh --profile headless 失败（或反过来），把 key 放到失败一侧读取的位置——headless 运行读 DEEPSEEK_API_KEY 环境变量或仓库根 .env——然后重跑同一条命令。
  4. key 确认无误、报错却跨界面持续？按「疑似误分类」处理：抓全完整报错输出加 dsh --version，先对照 #3073/#3222，再决定要不要再次轮换凭据。
  5. 挂着代理？第十节的代理形态产生的是挂起和超时，不是干净的 401——先在那里排除，再怪 key。
  6. 在平台误删了 key，dsh 却设不进新 key？这是在案记录的缺口（#8988，同此前被关闭的 #7625）：桌面端与 Web UI 目前对已存凭据没有「更新」或「删除重设」的入口。过渡方案：headless 运行可以从 DEEPSEEK_API_KEY 环境变量读新 key（即上面第 3 步的路子）；Web/桌面界面暂时没有产品内重设——去 #8988 补一份你的案例并关注线程。品牌形搜索 deepseek harness api key is invalid 落到的就是这一节。

十七、Output token limit reached——两道天花板，两套修法

症状：回答中途停下，报输出 token 上限错误，或长回合被截断——大家搜索的原句是 output token limit reached（未解决讨论：#1166、#5970）。带品牌前缀的搜索形——deepseek harness token limit、deepseek harness output token limit——落到的也是同一处。一个相关但不同的失败：压缩过后立刻报 CONTEXT_WINDOW_EXCEEDED。

原因：两道天花板经常被混为一谈。输出上限：每个模型行都带一个 Max output tokens 值（自定义模型行的占位是 32K）——单条回复跑过它就被截断。上下文上限：整个会话耗尽窗口，本应由压缩在到达之前折叠历史——但 #8498 记录了压缩空转、随后把会话误判为 CONTEXT_WINDOW_EXCEEDED，#8494 记录了余量在大 headroom 值之后塌缩。所以你看到的「上限已到」，可能是压缩机制失灵，而不是会话真的太大。

修复步骤：

  1. 限的是回复，不是会话：在 Settings → Models 里设置模型行的 Max output tokens（自定义模型行直接暴露这个字段；占位 256K/32K；留空则继承 provider 默认）——爱截断长回答的模型就把它调大。
  2. 会话确实大到失控就拆分：开新会话、带一份摘要过去——上下文压缩指南讲过 dsh 怎么折叠历史、三个压缩触发点是什么。
  3. 压缩刚跑完（或正在跑）就报 CONTEXT_WINDOW_EXCEEDED？这就是 #8498 形态：记下 dsh --version 和会话大小，重启后重试一次，然后把报告连同诊断信息贴进讨论区。
  4. 小任务也反复在回答中途被切——指向 provider 而非 dsh：先去 provider 自己的用量页查你套餐的长度/频率上限，再动 dsh 的任何设置。
  5. 仍然复现：带上 dsh --version、启动命令和完整报错，进讨论串（#1166、#5970）——这个形态正在那里被逐例区分。

十八、内存溢出 OOM——被杀的是进程，不是会话

症状：Linux 上跑 dsh，进程中途直接消失，终端只剩一句 Killed（或退出码 137）；dsh web 跑一段时间后被系统杀掉，日志里能找到 OOM（Out of Memory）字样。大家搜的原句是 dsh oom——先提醒一句：搜索结果里铺天盖地的 DSH 医疗内容（Disproportionate Share Hospital，美国医保术语）与本工具无关，真正的同类案例在 GitHub 讨论区。

原因：OOM 是操作系统层面的内存耗尽——dsh 进程（或它所在的容器/cgroup）申请的内存超过限额，内核直接杀进程保命。它和第十七节的「上限」是两回事：上下文窗口耗尽报的是 CONTEXT_WINDOW_EXCEEDED 这类模型侧错误，会话还在；OOM 则是整个进程没了。已记录的两个真实形态：一是用 npx 临时运行时更容易触发（GitHub 报告「Linux: OOM when running dsh via npx — use global install」，官方给的办法就是改全局安装）；二是 #8639 记录的 dsh web 常驻场景——RSS 随会话量增长，最后被 1GiB 的 cgroup 限额 OOM-kill。

修复步骤：

  1. 别拿 npx 长期跑，改全局安装：npm install -g @deepseek-ai/dsh 之后用 dsh 直启——这是官方对该报告的处置方式，顺便也解决第十一节的 command not found。
  2. dsh web 常驻被杀（#8639 形态）：先查它所在的 systemd/cgroup 是不是卡着 1GiB 一类的硬限额——把 MemoryMax 调大或取消，再观察 RSS 是否随会话数持续增长；会话吃内存就定期重启 dsh web。
  3. 先分诊再动手：报错文字里有 CONTEXT_WINDOW_EXCEEDED / token limit → 走第十七节和上下文压缩指南；终端只有一句 Killed、dmesg 里出现 Out of memory: Killed process → 才是本节的 OOM。
  4. 容器与小内存 VPS：给 dsh 所在容器加 swap 或调高内存限额；Web UI 和多个会话同时跑时，预留 2GiB 以上的余量更稳。
  5. 仍然复现：带上 dsh --version、部署方式（npx / 全局 / Docker / cgroup 限额值）和 dmesg 相关行进讨论区——#8639 那条线正在收集这类案例。

十九、桌面端起不来：9 月底那一轮启动灾难

症状：2026 年 9 月底到 10 月初，官方讨论区密集出现四类桌面端启动失败：Windows 11 上应用在加载 V8 启动快照时直接死掉（#8776）；以管理员身份启动以退出码 18 告终（#8787）；宿主进程崩溃报 'prepare' is undefined——一次出在插件 id 冲突之后（#8822），一次出在 profile 的 package.json 被 BOM 写坏、恢复会话时（#8837）；还有老熟人 0xC0000142 以三份报告的规模回归（#8771、#8772，#8775 分析了背后 DACL capability-SID 机制）。

分形态的原因与修法：

  1. V8 启动快照加载失败（#8776）：桌面二进制的快照载入失败，多半发生在更新中断或半途而废的安装之后。别沿用旧安装目录，重新下载安装包重装；先在 CLI 跑 dsh --version，确认内核本身是健康的。
  2. 管理员启动退出码 18（#8787）：提权改变了应用预期的环境（用户目录被重定向、PATH 不同）。先用普通用户跑一次；确实需要提权时，从一个已经提权的终端用干净环境启动，别去右键那个旧快捷方式。
  3. 'prepare' is undefined（#8822、#8837）：这是宿主侧崩溃，不是插件内的错误。#8822 里两个插件注册了冲突的 id，一次查找落空；#8837 里带 BOM 保存的 package.json 弄坏了 profile 解析，恢复会话时同一错误再次出现。移除肇事插件，或把文件另存为无 BOM 的 UTF-8，然后先冷启动一次再恢复会话。10 月还出现了第三种形态（#8924）：web profile 里自带一份 @deepseek-ai/dsh-tools（本地开发插件时的 dual-package 结构）时，所有工具调用都死于同一个 reading 'prepare' 错误，而纯文本轮次存活——移除 profile 内的重复副本，让 dsh-tools 只解析到一份。
  4. 0xC0000142 第三次出现（#8771、#8772、#8775）：与第九、十二节同族的 STATUS_DLL_INIT_FAILED，这次中英文报告都有。#8775 的分析指向子进程 DACL 里的 capability SID。先跑第九节的一次性修复——它仍是这一族错误的受支持路径。

二十、升级后旧会话打不开：session format 编解码器

症状：升级到新版 dsh 之后，以前正常的会话打不开，报 SessionFormatError 一类的错误。已记录两种形态：v0→v1 编解码器拒绝 0.1.0-rc.6 / 0.1.1-rc.2 写下的会话，因为其中 subagent/descriptor 事件带的是 version: 2，而迁移代码要求 version: 3（#8868）——历史里有子代理会话的部署因此卡在升级前；v3→v4 编解码器则在 system/message 不是整个日志第一个 surface 节点时，拒绝本来合法的日志（#8888）。

原因：会话日志是带版本的，每次迁移都做严格校验：v0→v1 把事件版本钉死在单一取值，v3→v4 的 foldSurface 守卫假设 system/message 必须是第一个 surface 节点——两个假设都误伤了旧版本合法写出的日志。

修法：

  1. 先记下完整报错文本和 dsh --version——靠"哪一步迁移在报错"区分两种形态。
  2. 如果这些会话升级前一直能打开，最快的可用路径是第 8 节的版本回滚：把 dsh 钉回写下这些日志的版本（npm install -g @deepseek-ai/dsh@<版本号>），打开会话把需要的内容导出。
  3. 绝不要为了通过校验手改会话文件——改坏一处日志就永久读不出来了。先备份文件，再带着报错文本去 #8868 / #8888 追报告，后续修复都会落在这两条线程里。

二十一、安全公告：经本地控制面的沙箱逃逸披露（#8887）

发生了什么。官方讨论区的公开披露（#8887，严重级别：high）描述了一条从 dsh 本地控制面 127.0.0.1:3080 触发的链路：只要能在任意一个沙箱会话里执行一条命令（哪怕文件策略是 read-only），受限代理就能逃逸沙箱、绕过审批策略，以你的用户身份任意写文件、全程无审批弹窗。已在 dsh 0.2.0-rc.2（Linux/WSL2）上验证，披露者认为与平台无关。

现在就做：

  1. 让 Web UI 保持默认的仅回环绑定——攻击链的起点是"任何能碰到 127.0.0.1:3080 的东西"，所以不要把绑定改宽，更不要把 3080 端口隧道到不完全可信的网络（安全暴露长什么样见远程访问指南）。
  2. 在修复版发布之前，把"沙箱"理解为"加固手段，不是安全边界"：别让沙箱会话去碰不可信仓库或易被注入的内容，尤其在那台机器上存着重要东西的时候。
  3. 修复落地后尽快升级 dsh，并持续关注 #8887——披露帖是官方回应与修复版本的权威出处。

二十二、安全公告：根目录为 / 的工作区会让沙箱失效（#9026）

发生了什么。继 #8887 控制面逃逸（第二十一节）三周后，第二份沙箱披露落地：根为 / 的会话或工作区可以通过 resolveWorkspaceRoot() 的唯一检查——isAbsolute()——原样进入 writableRoots()，可写集合变成 ['/', '/tmp', tmpdir()]。于是每个强制后端都放行整个文件系统的读写：bwrap 靠 --bind / /，Landlock 因为 RW 规则压过只读规则，sandbox-exec 靠 / 的可写前缀。两个入口都不做校验：session.create({ cwd: '/' }) 与 workspace.create({ path: '/' })。

现在就做：

  1. 修复发布之前，绝不运行根为 / 的会话或工作区——也审计一遍替你创建会话的工具链。眼下这就是全部防御。
  2. 第二十一节的每一条继续有效：Web UI 只绑回环、不隧道 3080 端口、把沙箱当加固手段而非安全边界。
  3. 修复落地后及时更新 dsh，并持续关注 #9026——披露帖是官方回应的权威出处。

二十三、桌面端稳定性风暴：崩溃循环、被清空的插件依赖、Electron 44（2026 年 10 月）

症状。一周之内讨论区挤进了四种桌面端形态：应用每次启动都崩、只有全量禁用插件才能救回（#8995）；桌面端升级后某支插件静默失效、任何地方都不报错（#9030）；宿主进程报 0xC0000409、renderer 在 Electron 44 / Chromium 152 上反复崩（#8972），还有 renderer OOM 崩溃的姊妹帖（#8932）；以及一位重度用户发布的 22 条可复现稳定性清单，横跨插件加载、依赖树、会话文件与配置（#8951）。

逐形态的原因与修法。

  1. 启动崩溃循环（#8995）。某支第三方插件里的未处理 rejection 被宿主的 fail-loud 处理器按致命错误对待，于是每次启动都重复同一失败——有记录的案例三分钟连崩六次。目前没有自动安全模式，恢复靠手动：把 ~/.dsh/cordis.patch.yml 里可疑插件的 enabled 改为 false（或把文件挪开），重新启动，再逐支恢复以定位元凶。
  2. 升级后插件静默死亡（#9030）。有记录的案例：桌面端升级把一支插件的运行时依赖目录清空了，而包管理器的状态文件仍然在册——内容没了、哪儿都不报错。如果升级后某支插件的面板凭空消失且看不到任何报错，重装它（dsh plugin remove + dsh plugin add，或桌面端插件管理器），让依赖重新落地。
  3. 0.2.0-rc.2 上反复的宿主/renderer 崩溃（#8972、#8932）。宿主退出码 0xC0000409，renderer 在 Electron 44 / Chromium 152 上反复崩、间隔还在缩短；姊妹帖记录了 renderer 的 OOM 崩溃。附上桌面端导出的诊断包，注明 dsh --version，去线程里补你的案例——这些形态正靠「崩溃频率 + 死的是哪个进程」来区分。
  4. 22 条稳定性清单（#8951）。一份跑了 30 天、100+ 会话的记录把三条修复排在所有之前：注册了却既不加载也不报错的插件；挂载失败就连带整个客户端起不来的 fail-closed；以及没有官方校验/修复工具的会话文件——最后这条就是第二十节的编解码器地盘。调试前值得先读一遍：你遇到的形态可能已经在 P-01 到 P-22 里。

还是没解决？

  • 安全安装插件指南——安装方式、Profile 与 CLI 速查
  • 配置详解——bundle、profile、patch：你改的到底是哪一层？
  • dsh 命令行速查表 — 常用命令、flag 与启动模式一页打尽
  • DeepSeek Harness 回滚后悔药 — 用 dsh-undo-savepoint 的存档点与崩溃救援，先试着回滚而不是重装
  • 提交插件——如果插件 README 描述的行为与你的实际情况不符，去它的仓库开 issue，附上你的 dsh --profile 命令和完整报错，维护者解决得最快；若是你维护的插件，修正 README 后把它提交进目录。
广告

DSH Plugins 是独立的 DeepSeek Harness 插件市场，与 DeepSeek 官方无关，也不代表官方背书。第三方插件未经安全审计，安装前请审查源码。

每周获取最新的 DeepSeek Harness 插件，绝不滥发。