前言¶
DeepSeek Harness (DSH) 是一個插件化架構的智能體開發框架。在使用 Web Profile 進行 LLM 調用開發時，開發者常面臨上游 Provider 限流導致請求失敗、重試邏輯難以管理、以及模型清單混亂等問題。leaves615/dsh-llm-ctl 旨在解決這些痛點，它通過接管 llm/stream 和 agent/request-error 接縫，在請求發出前進行准入管制，並提供獨立的請求恢復與模型管理能力。
核心功能¶
該插件主要包含以下四個方面的能力：
1. 限流排隊¶
所有 llm/stream 調用（包括 Agent 主循環、標題生成等）在發出前會先獲取 Provider 的併發槽位。
* 嚴格 FIFO：按照先進先出順序放行請求。
* 冷卻機制：當遇到上游 429 錯誤時，插件會根據 Retry-After 響應頭或本地指數退避策略，讓整個 Provider 進入冷卻期。排隊中的請求會等待冷卻結束再執行，而不是直接報錯。
* 等待預算：設置了 maxWaitMs 等待預算，若超過預算會直接報 QUEUE_TIMEOUT，避免長時間無效等待。
2. 獨立自愈¶
在 agent/request-error 接縫上，插件會先登記冷卻狀態，再詢問下游。
* 兜底重試：如果未安裝 dsh-llm-retry 插件，該插件會啓用有界預算重試（默認 3 次）。這意味着即使沒有重試插件，第一個 429 錯誤也不會導致任務直接失敗。
* 資源隔離：只有當下遊沒有接管重試邏輯時，本插件纔會介入重試。
3. 模型隱藏¶
提供 Provider 和單模型兩級開關，持久化到 llm-ctl 配置中。
* 持久化與恢復：配置保存在 DSH 的設置中，支持一鍵恢復所有隱藏。
* 過濾與回退：隱藏默認模型時，系統會自動回退到第一個可見模型。
* 菜單集成：在模型設置頁顯示開關，並在模型菜單中支持按 p: 前綴過濾。
4. 上游發現¶
提供對 Provider 模型清單的刷新能力。
* 重發現：在 Provider 卡片上點擊刷新按鈕，可重新獲取上游模型列表。
* 安全機制：發現請求在服務端進行，使用保存的 Credential，不經過瀏覽器通道，避免了密鑰泄露風險。
安裝與啓用¶
前置條件：DSH web profile，Node.js >= 22。插件在 @deepseek-ai/dsh-llm 0.1.2-rc.1 上測試通過。
1、執行以下命令安裝插件：
dsh plugin --profile web add -w @leaves615/dsh-llm-ctl
2、重啓 DSH Web 服務以加載插件：
dsh web
典型用法¶
安裝完成後，使用默認配置即可直接運行。
* 查看開關：進入模型設置頁，每個 Provider 會多出一張控制卡片。
* 排隊控制：進入設置導航的 LLM 排隊控制 分區，在此處調整併發上限、隊列深度和等待預算。
* 菜單過濾：在模型菜單中輸入 p:provider_name 可按 Provider 過濾模型。
注意事項¶
- 權限與限制：本插件以當前 DSH 進程權限運行。插件本身不做計費統計、不做 Token 級限流、不做跨進程分佈式隊列，也不修改 Adapter 的協議邏輯。
- 已知問題：服務端
session.modelCatalog目前攔截不到隱藏規則（過濾僅在瀏覽器側生效），且不寫入自定義會話日誌事件。 - 生態關係：本插件定位爲“門衛”，與負責執行重試的
dsh-llm-retry插件互不衝突，與只搜索不隱藏的dsh-model-search-plugin協作共存。
結語¶
leaves615/dsh-llm-ctl 通過在 DSH 的關鍵接縫處增加邏輯，解決了 Provider 限流管理和模型可見性控制的問題，適合需要精細控制 LLM 調用流程和資源使用的開發者使用。
