前言¶
在 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 倉庫。
