前言¶
DeepSeek Harness 的核心設計理念是“一切皆插件”。當開發者需要接入非原生支持的模型或服務時，往往需要修改核心代碼。dsh-llm-openai-compatible 插件解決了這個問題，它作爲一個“萬能插頭”，通過 OpenAI 兼容協議，讓 Harness 能夠直接對接本地或遠程的任意 OpenAI 兼容端點。
插件概覽¶
名稱：dsh-llm-openai-compatible
維護者：cqnxnzg
類別：admin-security
許可證：MIT
該插件的核心價值在於解耦。安裝後，只需配置端點地址和模型目錄，即可讓 Harness 與 vLLM、LM Studio、llama.cpp、Ollama 的兼容層，或者 OpenRouter、Together、Moonshot 等遠程網關通信。它不需要安裝 Ollama，也不需要修改 DeepSeek Harness 的核心代碼。
安裝與啓用¶
安裝前請確保已安裝 DeepSeek Harness 0.1.0-rc.6 或更高版本。
dsh plugin --profile web add github:cqnxnzg/dsh-llm-openai-compatible
安裝完成後，插件會在 Settings -> Plugins 下生成一個名爲 llm-openai-compatible 的配置項。
核心功能¶
- 任意 OpenAI 兼容端點：支持本地服務器或遠程網關。
- API key 可選：本地端點支持匿名請求；遠程網關通常需要鑑權。
- 模型目錄聲明：通過
models數組聲明端點實際提供的模型及其屬性。 - Web 配置界面：通過 Settings -> Plugins ->
llm-openai-compatible進行可視化的配置修改，保存即生效。 - 模型發現功能：通過
discoverModels()讀取端點的GET <base>/v1/models接口，自動獲取模型列表。 - 免 allowlist 安裝：倉庫直接提交了構建產物
lib/，無需 pnpm 的 build-script 白名單即可直接安裝。
配置說明¶
進入 Settings → Plugins → llm-openai-compatible，所有配置項均爲可選。
主要配置字段¶
| 字段 | 默認值 | 說明 |
|---|---|---|
apiKeyEnv |
OPENAI_API_KEY |
憑據引用（環境變量名）；未配置或爲空時，本地端點可匿名請求 |
baseURL |
http://127.0.0.1:8000/v1 |
OpenAI 兼容端點；插件會自動將末尾的 /v1 歸一化 |
models |
4 個示例模型 | 端點實際服務的模型目錄；未列出則請求報 UNKNOWN_MODEL |
maxTokens |
— | 全局默認輸出上限；當模型行未聲明時作爲兜底值 |
defaultContextWindow |
131072 |
模型未聲明 contextWindow 時的上下文容量 |
streamIdleTimeoutMs |
300000 |
流式讀取空閒超時 |
retryPolicy |
正常默認 | 重試策略配置 |
模型目錄字段¶
models 數組中的每一項包含以下字段：
| 字段 | 說明 |
|---|---|
id |
端點接受的模型 id（必須與端點實際服務一致，否則報錯） |
name |
選擇器顯示名；省略時使用 id |
description |
選擇器裏的補充說明（可選） |
contextWindow |
該模型上下文容量（token） |
maxTokens |
該模型專屬輸出上限，優先級高於全局 maxTokens |
vision |
true 表示接受圖片輸入 |
thinking |
true 表示支持原生思考；需配合選擇器的思考等級使用 |
defaultEffort |
聊天選擇器的默認思考等級 |
tools |
遺留能力標誌，運行時忽略 |
重試策略配置¶
默認策略爲正常模式：最多重試 2 次，針對 EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT 等錯誤碼退避重試。
retryPolicy:
mode: normal # normal | always
maxRetries: 3 # normal 模式下的最大重試次數
retryableCodes: [RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
backoff:
initialDelayMs: 500
maxDelayMs: 10000
jitterRatio: 0.1
常見端點配置示例¶
| 服務 | baseURL 示例 | 備註 |
|---|---|---|
| vLLM | http://127.0.0.1:8000/v1 |
--served-model-name 指定的名字纔是請求 id |
| LM Studio | http://127.0.0.1:1234/v1 |
— |
| llama.cpp server | http://127.0.0.1:8080/v1 |
— |
| Ollama（兼容層） | http://127.0.0.1:11434/v1 |
必須走兼容層，模型 id 常帶 tag，如 qwen2.5:7b |
| OpenRouter | https://openrouter.ai/api/v1 |
網關，必須配 apiKeyEnv |
| Together | https://api.together.xyz/v1 |
網關，必須配 apiKeyEnv |
接入 DeepSeek 官方 API¶
DeepSeek 官方端點本身就是 OpenAI 兼容的。
llm-openai-compatible:
apiKeyEnv: DEEPSEEK_API_KEY # 環境變量名
baseURL: https://api.deepseek.com # 自動路由到 /v1
models:
- id: deepseek-chat # 通用對話
name: DeepSeek Chat
contextWindow: 65536
maxTokens: 8192
- id: deepseek-reasoner # 推理模型
name: DeepSeek Reasoner
contextWindow: 65536
maxTokens: 8192
thinking: true # 必須聲明支持思考
故障排查¶
UNKNOWN_MODEL：請求的模型 id 不在 models 目錄裏。請使用 curl http://127.0.0.1:8000/v1/models 獲取端點返回的真實模型 id，並修改配置。
401 Unauthorized：遠程網關通常需要鑑權。檢查 apiKeyEnv 是否配置正確，本地端點不需要 key 時可清空該字段。
404 / 連不上：baseURL 應只寫域名和端口，不要寫完整路徑（插件會自動補 /v1）。確保服務已啓動且端口正確。
/v1 寫兩遍：不要在 baseURL 中寫 .../v1/v1。
開發構建¶
插件基於 TypeScript 開發。提交的代碼包含編譯產物 lib/，因此無需 pnpm 的 prepare 腳本即可直接安裝。
pnpm install
pnpm run build # tsc + tsdown
