DeepSeek Harness 插件报错合集：DSH plugin 不加载、Web UI 异常与会话缓存修复

故障排查发布于 2026-08-26作者: DSH Plugin 插件中心
DeepSeek HarnessDSH plugin插件报错Web UI 异常ERR_REQUIRE_ESMFailed to fetch
DeepSeek Harness 插件报错、Web UI 异常与会话缓存问题合集：ERR_REQUIRE_ESM、缺失 inject、dsh-type-meta 改名、发送按钮灰色、crypto.randomUUID 报错与 History Failed to fetch 逐一修复，凭证/模型报错附速查指引。

DeepSeek Harness 的插件报错、Web UI 异常与会话缓存问题，几乎都落在三个区域：插件包本身的问题（ESM、inject、包改名）、Web 界面与运行时的坑（工作区、加密上下文、远程访问）、会话数据的损坏或失配（日志断档、缓存失效）。 报错原文对号入座，先按本文修复，没解决就先升级到 rc.7/rc.8——官方近期版本修复了大量这类缺陷，很多「界面异常」其实是旧版本 bug。

插件报错：不加载、ERR_REQUIRE_ESM、缺失 inject 与包改名

插件类报错集中在包的格式与依赖上：清单缺失、ESM 兼容、inject 声明、包改名、重复实例。 以下报错来自社区实跑汇总（来源）。

ERR_REQUIRE_ESM：CommonJS 依赖了 ESM-only 包

ERR_REQUIRE_ESM 表示 CommonJS 代码用 require 加载了一个只提供 ESM 导出的包。 常见于插件作者没处理好模块格式：

  1. 确认 Node 是 LTS（20+）：执行 node --version，建议输出 v20.x 以上，ESM 支持才完整；
  2. 重启 dsh web 让插件重新加载：Ctrl+C 停止，再执行 dsh web 启动；
  3. 仍报错说明是插件包本身的问题——反馈作者改成兼容导出（同时提供 CJS / ESM），或改装其他替代插件，可在 DSH Plugin Hub 插件页看更新记录。

cannot get property "systemPrompt" without inject

这条报错是说插件代码在声明依赖（inject）之前就读取了 systemPrompt 等服务，注入还没发生。 属于插件 bug：

  1. 确认是否装了插件的最新版（旧版常见此问题）——在「设置 → 插件中心」查看该插件是否有可更新版本，有就更新后重启 dsh web；
  2. 更新后仍报错，反馈插件作者补齐 inject 声明；
  3. 临时办法：按 《dsh 怎么关闭插件而不卸载》 禁用该插件后重启 dsh web——报错消失、其余功能正常，即可确认问题出在该插件。

@deepseek-ai/dsh-type-meta 找不到：包已改名

官方已把 @deepseek-ai/dsh-type-meta 改名为 @deepseek-ai/dsh-typert-protocol（2026-08-11 的官方改名台账，该包承载 Typert Remote 协议、装饰器、绑定与编解码器，现目录 packages/typert/protocol，来源）。老依赖名报错的原因不是「没发布」，而是改名后旧名字不再存在：

  1. 更新用到它的插件 / profile 依赖——在 profile 的 package.json 里把 @deepseek-ai/dsh-type-meta 替换为 @deepseek-ai/dsh-typert-protocol，然后重新安装：
    bash
    pnpm install
    预期：依赖解析不再报 Cannot find module '@deepseek-ai/dsh-type-meta'；
  2. 或直接更新 dsh 与相关插件到包含该改名的版本（rc.7 之后）：npm update -g @deepseek-ai/dsh；
  3. 装的是旧版 bundle 就重装一次，让依赖解析到新包名；
  4. 重启 dsh web，原报错消失即修复。

reading 'prepare' of undefined：工具包重复实例

reading 'prepare' of undefined 通常来自 dsh-tools 这类工具包被装出两份实例，peer 依赖没有单一化。 有用户实跑遇到：

  1. 在 profile 的 package.json 里确认 @deepseek-ai/dsh-tools 只出现一份：
    bash
    grep -c '"@deepseek-ai/dsh-tools"' <profile目录>/package.json
    输出为 1 才正常，大于 1 说明装了两份；
  2. 出现两份就在「设置 → 插件中心」卸载相关插件重装，让 pnpm 把 peer 依赖提升为单实例；
  3. 重启 dsh web（Ctrl+C 后重新 dsh web），不再报 reading 'prepare' of undefined 即修复。

duplicate loader entry id：bundle 重复提升

duplicate loader entry id 表示同一个插件层被重复声明（bundle 被提升出两份）。 有用户实跑遇到：

  1. 打开 profile 目录下的 package.json（或 dsh 配置文件），找到 dsh.profile.bundles，把重复的条目删掉，只保留一份；
  2. 确认编辑无误后保存，再执行 pnpm install 让依赖与声明同步；
  3. 重启 dsh web（Ctrl+C 后重新 dsh web），不再报 duplicate loader entry id 即修复。

插件装了不激活 / Failed to load plugins / allowBuilds 提示

这三条与其他教程重复，直接走对应专文：

dsh-plugin-hub · 插件中心
DSH Plugin Hub 插件中心：浏览、安装与管理插件的图形化入口

Web UI 与运行时异常：发送按钮灰色、crypto.randomUUID 与远程访问

Web UI 报错分两类：界面状态问题（工作区没选、输入框渲染崩）和运行环境问题（非安全上下文、远程访问受限）。 以下报错来自社区实跑汇总（来源）。

发送按钮一直灰色

发送按钮灰色最常见的原因是没选工作区——没有工作区，Agent 就没有可操作目录，发送被禁用。 处理：

  1. 在 Web UI 顶部选择或创建一个工作区目录；
  2. 选完后发送按钮应可点、输入框可输入文字；
  3. 仍灰色就刷新页面（F5）；
  4. 还不行就确认后台 dsh web 进程是新的——端口被旧进程占用时界面可能连的是旧实例，用 lsof -i :3080（macOS / Linux）检查并停掉旧进程后重启，方法见 《127.0.0.1:3080 打不开、访问被拒怎么办》。

技能 CLI 能用、Web UI 里不可用

有用户实跑遇到：命令行里技能正常，Web UI 里找不到或调不动。 官方 dsh-base 组合层默认包含 skill-filesystem、tool-skill 等技能插件（来源），但不同 agent preset 对技能集合的暴露范围不同（官方测试中存在 standard / minimal 两种技能装配），Web 与 CLI 用到的技能可能不一致：

  1. 在 Web UI 的技能管理（设置 → 技能）里检查目标技能是否已启用，未启用就打开开关；
  2. 核对当前 profile 用的 agent preset：执行 dsh --dump-config 查看 preset 字段，换成暴露更多技能的 preset 后重启 dsh web；
  3. 仍不可用则以 CLI 为准（直接执行 dsh 命令行调用），并把「Web UI 与 CLI 技能不一致」反馈到插件仓库。

crypto.randomUUID is not a function

浏览器在明文 http（非安全上下文）下会禁用 Web Crypto 相关能力，crypto.randomUUID 就不存在。 有用户实跑确认此报错与访问协议有关：

  1. 本机访问改用 http://localhost:3080（localhost 视为安全上下文），不要用 http://192.168.x.x 这类明文地址；
  2. 换地址后刷新页面，按 F12 打开开发者工具，在 Console 里执行 crypto.randomUUID()——能返回一段 UUID 即修复；
  3. 远程访问时通过带 TLS 的反向代理（如 Caddy / Nginx 配 HTTPS）暴露页面，浏览器进入安全上下文后该能力恢复；
  4. 本机直接用 localhost 即可绕开。

Composer 输入框消失

Composer（输入区）消失常见于历史消息里的 markdown 图片引用损坏，渲染流程抛错导致输入组件没挂载。 有用户实跑遇到：

  1. 先按 F5 刷新页面重载，看输入框是否恢复；
  2. 仍复现就清掉当前会话里损坏的图片引用消息（删除含失效图片引用的那条消息），或直接开新会话；
  3. 长期频繁出现，检查是否旧版本缺陷——更新到 rc.7+ 后重试（npm update -g @deepseek-ai/dsh）。

/api/commands/list 返回 404

新装插件后调用 /api/commands/list 返回 404，通常是插件注册的路由还没生效。 处理：

  1. 重启 dsh web：Ctrl+C 停止，再执行 dsh web 启动；
  2. 确认插件已正确激活（见上文「插件装了不激活」），未激活先处理激活问题；
  3. 重启后在浏览器访问 http://localhost:3080/api/commands/list，应返回 200 与 JSON 数据，而非 404。

技能菜单前缀匹配限制

技能菜单按前缀匹配技能名，输入长前缀或中英文混写时容易匹配不到。 有用户实跑遇到：

  1. 直接输入技能名最核心的几个字符（如技能名本身，而不是带版本号的全名）；
  2. 避免输入带版本号 / 长描述的完整文本；
  3. 匹配不到时就先在技能下拉里选中目标技能再对话，或用 CLI 调用 dsh 对应命令。

远程访问时「设置 → 插件」空白

通过远程浏览器访问时，插件管理面板空白——插件管理与本机文件系统绑定，dsh web 默认只监听 127.0.0.1。 有用户实跑遇到：

  1. 回到运行 dsh 的那台机器上，浏览器访问 127.0.0.1:3080，「设置 → 插件」应正常显示插件列表；
  2. 远程访问只适合查看与对话类操作，插件安装 / 卸载请在本机完成——远程看不到插件面板是设计如此，不是故障；
  3. 本机操作更省事的方式是「设置 → 插件中心」DSH Plugin Hub，图形化管理插件。
dsh-plugin-hub · 已安装插件
DSH Plugin Hub 已安装插件列表：集中管理已装插件、查看版本与更新

会话与缓存异常：日志损坏、KV 缓存下降与 Failed to fetch

会话恢复类报错源于数据本身的损坏或失配：日志断档、系统提示词顺序漂移、畸形增量数据。 以下报错来自社区实跑汇总（来源）。

恢复时会话日志损坏（序号断层）

恢复会话时提示日志损坏，表现为序号断层（中间缺了几条记录）。 有用户实跑遇到：

  1. 先导出当前会话数据留底（用 Web UI 的导出功能，或直接把会话文件复制到别处）；
  2. 开新会话继续，避免日志继续错位；
  3. 更新到 rc.7+（npm update -g @deepseek-ai/dsh），该版修复了大历史分页栈溢出等会话问题——更新后新会话不再提示日志损坏，即确认是旧版本写入缺陷。

恢复后 KV 缓存命中率骤降

恢复会话后 KV 缓存命中率明显下降，通常是系统提示词顺序漂移导致缓存键失配。 有用户实跑遇到：

  1. 让会话重新生成一次系统提示词（如切换模型再切回），重建缓存后命中率应回升；
  2. 或直接开新会话，缓存从零重建，命中率恢复正常；
  3. 频繁出现时检查是否有插件在会话中改写了系统提示词——临时禁用可疑插件再试。

History 报 Failed to fetch (internal)

History 面板报 Failed to fetch (internal)，多为流式工具增量数据畸形导致前端拉取失败。 处理：

  1. 先按 F5 刷新页面重试——偶发的畸形数据刷新即可恢复；
  2. 仍复现就先导出会话数据留底，再开新会话；
  3. 版本较旧先更新：npm update -g @deepseek-ai/dsh——rc.7 修复了持久 Bash 卡顿、max-tokens 截断等一批会导致增量数据异常的缺陷，更新后新会话不再复现即确认。

凭证与模型报错速查

凭证与模型类报错（MISSING_CREDENTIAL、UNKNOWN_MODEL、获取可用模型 401、maximum context length is 1048576 tokens）不属于插件问题，完整排查见《DeepSeek Harness 模型报错与凭证排查》。 这里只给最快入口：

报错最快动作
MISSING_CREDENTIAL在 ~/.dsh/.credentials.yaml 写入 DEEPSEEK_API_KEY
UNKNOWN_MODEL检查模型名与 provider 声明是否一致
获取可用模型 401base URL、key、模型名三者必须匹配
maximum context length is 1048576 tokens开新会话 / 缩系统提示词 / 调低 max_tokens

旧版本缺陷修复对照（更新即解决）

很多「插件 / Web UI 报错」其实是旧版本 bug——先更新，再排查。 官方近期修复记录（来源）：

  1. v0.1.0-rc.7：修复 max-tokens 截断（长回复被截）、持久 Bash 会话卡顿、大历史分页栈溢出（历史很多时页面卡死）、Safari 光标错位（输入框光标乱跳）。
  2. v0.1.0-rc.8：修复图片尺寸过大 / 历史图片累计载荷过高导致模型请求失败、自定义 OpenAI 兼容网关请求格式差异、dsh web 自动打开浏览器、改善下载依赖体积。
  3. 更新命令：全局安装 npm update -g @deepseek-ai/dsh；npx 方式 npx @deepseek-ai/dsh@latest web；源码方式 git pull 后重新构建。

注意事项

  1. 先对号入座找报错原文，别凭印象乱卸载。
  2. 插件类报错先确认「装的是最新版」「只装了一份」。
  3. Web UI 报错先确认访问的是 localhost 而非明文 http。
  4. 会话类报错先导出数据再动会话，避免数据二次损坏。
  5. 排查前先确认版本：版本过旧（rc.7 之前）的多数界面异常直接更新解决。

来源：dshbase 常见问题排错、v0.1.0-rc.7 / v0.1.0-rc.8 Release Notes、packages/typert/protocol、apps/cli/composition.md

常见问题

DeepSeek Harness 报 ERR_REQUIRE_ESM 错误怎么解决？

ERR_REQUIRE_ESM 表示 CommonJS 代码 require 了一个 ESM-only 包。把运行环境切到支持 ESM 的版本（Node 20+），或让插件作者发布同时兼容的构建；先重启 dsh web 并确认 Node 是 LTS，多数情况能绕过。

DSH plugin 装了但没激活、报缺 dsh.bundle 怎么办？

说明该包没有声明 dsh.bundle 清单，只会作为普通依赖装上而不激活配置层。需要作者补上 dsh.bundle 声明再发布；也可先在《DeepSeek Harness 怎么安全安装插件》里核对安装来源与验证步骤。

DeepSeek Harness Web UI 发送按钮一直灰色点不了怎么办？

发送按钮灰色最常见的原因是没选工作区——在 Web UI 顶部选择或创建一个工作区目录即可。若仍未解决，检查是否旧版本 bug：v0.1.0-rc.7 修复了 max-tokens 截断等一批问题，先更新版本。

dsh web 报 crypto.randomUUID is not a function 怎么解决？

浏览器在明文 http（非安全上下文）下会禁用 Web Crypto 能力。改用 https、localhost 访问，或通过反向代理提供安全上下文即可。有用户实跑确认此报错与访问协议有关。

DeepSeek Harness 会话恢复后 History 报 Failed to fetch (internal) 怎么办？

多为会话恢复时流式工具增量数据畸形导致前端拉取失败。先刷新页面，若复现就导出当前会话数据后开新会话；新版 v0.1.0-rc.7 修复了持久 Bash 卡顿与历史分页栈溢出等会话相关缺陷，更新版本后再试。

来源