按报错查，不按章节读
报错原文 → 可能原因 → 处理方向 → 怎么验证。
插件被版本门拒绝，留在列表里但不运行
可能原因：插件声明的engines.dsh宿主范围与当前版本不匹配，社区插件常见做法是只开放某个0.2.x代际。
处理方向：先看插件仓库的CHANGELOG与README，找到它支持的宿主版本；要么换到受支持的宿主版本，要么装该插件面向旧宿主的旧版本，不要装 @latest。
怎么验证：重启后看插件状态是否为已启用，再跑一个最小任务确认工具可用。
公开资料整理 来源： 社区插件CHANGELOG
裸地址 127.0.0.1:3080 打开提示 authentication required
可能原因：Web启动命令会在终端打印一个带一次性token的完整访问地址；直接用不带token的裸地址会被拒。
处理方向：回到启动dsh web的终端，复制打印出来的完整URL；重启过服务就重新取一次，旧token会失效。
怎么验证：用完整URL能打开会话页，且不需要再填token。
公开资料整理 来源： 本机使用经验 / 官方文档口径
打开设置页返回 HTTP 403
可能原因：社区反馈多与浏览器扩展拦截本地请求有关，例如Page Assist一类插件。
处理方向：先禁用这类扩展再刷新；仍不行就看Host日志确认请求是否到达。
怎么验证：设置页能打开并保存一次配置。
待复现 来源： 社区教程
UNKNOWN_TOOL / HTTP 400，接第三方 OpenAI 兼容网关时
可能原因：英文社区把这类报错归到网关对developer role、工具名与工具调用格式的兼容差异上。
处理方向：先核对网关是否支持所用模型的工具调用格式，再检查Base URL与模型ID；把原始报错和请求体留下来便于比对。
怎么验证：用最小的一次工具调用测试，看是否还报同名错误。
待复现 来源： findharness排障文章（英文）
插件安装成功，但启用失败或重启后不见了
可能原因：0.2.2-alpha.3起官方把「安装失败」与「安装后启用失败」分开诊断；另外升级有覆盖配置的社区报告。
处理方向：看Host日志区分是哪一步失败；涉及升级的，先拿升级前备份还原配置，再单独重装。
怎么验证：重启后插件仍在已装列表且状态为已启用。
待复现 来源： 社区生态报道
dsh-cost-meter 费用明细弹窗报 Ne.async is not a function
可能原因：社区实测反馈：新版插件与当前内核没对上，点会话顶部「费用明细」弹窗时界面未渲染，但底栏实时统计与设置页正常。
处理方向：先以底栏 / 设置页的费用统计为准；关注插件更新或在兼容的宿主版本上重装；不要因此判定插件完全失效。
怎么验证：升级插件或换到其支持的宿主版本后，费用明细弹窗能否正常打开。
待复现 来源： 社区实测文章
插件市场发现页加载超时 / 索引源 15 秒超时
可能原因：社区反馈dsh-market的发现页给索引源的时间只有15秒，GitHub Pages上的索引在部分网络下会超过；导致搜不到插件。
处理方向：改用更快的索引源：在发现页索引源填入jsDelivr的https://cdn.jsdelivr.net/npm/dsh-plugin-catalog/index.json，或dshmarket.com的索引；或在dsh-market内直接搜。
怎么验证：打开插件 → 发现，能正常搜到并安装插件。
待复现 来源： 社区插件市场说明
升级后插件配置条目骤减（如 34 项变 2 项）且首次启动失败
可能原因：社区事故报道：某Windows用户从0.2.1-rc.5升级后，配置文件里插件条目从34缩到2，且因本地化插件不兼容导致首次启动失败；当时客户端无升级前自动备份与回滚。
处理方向：用升级前的profile配置备份还原；手工恢复约数小时。今后升级前务必先备份 $DSH_HOME下的配置与profile目录。
怎么验证：还原后插件条目数量恢复，且能正常启动。
待复现 来源： 社区事故报道（未经本站复现）
billion-context 压缩后内容疑似丢失 / 节省数值异常
可能原因：压缩插件会把早起对话折叠成摘要；若设置里的增量解析灰度或缓存开关没配对，可能出现召回异常或节省数值不可信。
处理方向：进插件的「bili设置」，确认缓存 / 增量解析开关与你的上游（是否按prompt_cache_key做缓存）一致；怀疑丢失时关掉增量解析灰度再比。
怎么验证：对比压缩前后对同一早期事实的追问召回，数值是否合理（节省与净节省同号且量级相符）。
待复现 来源： 社区插件说明
dsh-vision-router 识图无响应 / 返回 429
可能原因：免Key视觉通道会把图片发到云端视觉服务，可能受区域、配额或限流影响返回429；也可能通道临时不可用。
处理方向：先看是否区域 / 配额限流；若持续，按插件说明配置自备视觉模型Key走自有通道；敏感截图不要走免Key通道。
怎么验证：粘贴一张普通截图，能否被解析并回答；自备Key后重试是否稳定。
待复现 来源： 社区插件说明