前言¶
在 DeepSeek Harness Web 中使用非 DeepSeek 模型族时，开发者常遇到网关兼容性错误、会话死锁（连续失败）以及权限状态管理混乱的问题。dsh-tool-adapt 插件提供了一层兼容性与安全适配机制，旨在解决这些痛点，确保非官方模型在 DSH Web 环境下能更稳定地运行。
插件简介¶
这是一个面向 DeepSeek Harness Web 非 DeepSeek 模型族的兼容与安全适配层。它由 YrracOwl 维护，采用 MIT 许可证。
核心功能¶
该插件主要包含以下能力：
- 死会话防护：当会话处于“死”状态（例如沙盒权限已为
danger-full-access或审批策略为never）时，插件会从模型侧的工具架构中移除sandbox_permissions和justification字段，或对这些字段进行剥离，避免无限循环。 - 模型族惯例注入：根据模型族特性注入特定的调用约定。
- 熔断机制：对连续的失败请求进行熔断处理，防止网络或网关层面的抖动导致会话卡死。
- 生命周期安全的设置卡片：提供一种安全的配置管理方式，支持在设置面板中修改配置。
- 网关兼容性诊断与自动修复：检测并尝试修复因网关拒绝
developer角色（supportsDeveloperRole）导致的 HTTP 422 错误。该诊断是被动报告的，除非开启自动修复开关，否则不会直接修改配置。 - Surface 超限恢复：将网关返回的
INVALID_REQUEST错误重命名为CONTEXT_WINDOW_EXCEEDED，以便dsh-compaction-basic插件能正确识别并执行恢复逻辑。
安装与启用¶
在终端执行以下命令安装插件：
dsh plugin --profile web add dsh-tool-adapt
安装后必须重启 DSH Web 进程。主机端在启动时扫描插件列表，重启后设置卡片和可选的状态胶囊才会出现。
启用方式取决于 DSH 版本：
* ≤ 0.1.5：在 设置 → 插件 中找到 ADAPT 卡片。
* ≥ 0.1.7-rc.2：在侧边栏的 插件 面板中找到 dsh-tool-adapt，点击其下的 tool-adapt 行的配置控件。
典型用法¶
插件支持热配置，修改后立即生效。
1. 显示状态胶囊
默认情况下，状态胶囊是隐藏的。在 ADAPT 卡片中，找到「显示状态胶囊」开关并开启，或在配置中设置 ui.pill 为 true。胶囊会出现在聊天输入框的四个角落之一，支持拖拽切换锚点。
2. 修复网关角色拒绝
如果遇到网关返回 HTTP 422 invalid_request_error，通常是因为网关不支持 developer 角色。在插件面板或配置中，针对对应路由修改以下配置：
providers:
<route>:
compat:
supportsDeveloperRole: false
开启「网关 compat 自动修复」开关后，插件会在诊断时自动写入此配置。
3. 配置管理
完整的配置项可以在设置卡片中修改，或者在旧版 RC 环境中使用 settings.plugin.item 路径，在新版环境中使用 plugins.row.config 路径。
注意事项¶
- 胶囊默认隐藏：状态胶囊默认不显示，需手动开启。
- 配置热加载：通过设置卡片修改的配置会立即应用。
- 旧版回退：DSH 0.1.2+ 使用
remote.settings路径，旧版 RC 主机如果没有remote.settings，会自动回退到 connection API。 - 诊断被动性：网关兼容性诊断默认为被动模式（仅报告），不会自动修改配置，除非手动开启自动修复功能。
- 依赖要求：需要依赖
@deepseek-ai/schemastery版本 ≥ 3.18.4。
总结¶
dsh-tool-adapt 专注于解决非官方模型在 DSH Web 中的边缘兼容性问题。通过防护死会话、注入模型惯例和提供诊断修复工具，它降低了非官方网关集成的维护成本。更多细节可参考插件目录或GitHub 仓库。
