DeepSeek Harness 插件：dsh-openai-responses-bridge

前言¶

DeepSeek Harness (DSH) 的設計理念是“一切皆插件”。當需要接入非原生支持的模型提供商時，通常需要修改 DSH 的源碼或依賴複雜的配置。dsh-openai-responses-bridge 是一個獨立的插件，旨在通過 OpenAI Responses 協議或原生 Gemini Generative AI 協議，爲 DSH 提供第三方模型的連接能力。該插件不修改 DSH 的源碼樹，通過插件接口擴展功能。

核心功能¶

該插件主要解決第三方模型接入和協議適配的問題，具體包括：

1. 第三方模型接入：在不修改 DSH 原生提供者列表的前提下，添加支持 OpenAI Responses 協議的第三方提供商。
2. 原生 Gemini 支持：在同一橋接設置區域添加原生 Gemini 提供商。
3. 協議兼容與複用：複用 DSH/Pi 的原生消息轉換、推理處理、工具轉換、回放、使用量統計及流錯誤處理邏輯。
4. 託管搜索工具：啓用並展示遠程 Responses 的 web_search 工具，在對話卡片中顯示其生命週期、查詢內容、引用來源及錯誤信息。
5. 模型發現：從 OpenAI 兼容的 /models 端點發現模型列表，在保存提供商前進行選擇。
6. 模式共享：同一個提供者既可在原生模式使用，也可在 Code Mode/PTC 中使用，無需註冊第二個特定的搜索工具。
7. 安全憑證管理：通過 DSH 憑證存儲 API Key，保持配置文件（YAML）不包含明文密鑰。
8. 兼容性支持：包含 dsh-pwsh-sandbox-schem 的兼容行爲，無需額外安裝中間件插件。
9. 熱重載：支持在不修改宿主源碼的情況下熱重載提供者設置。

安裝與啓用¶

安裝前請確保 DeepSeek Harness 版本爲 0.1.2-alpha.2。

使用 DSH 插件管理器安裝指定版本的插件：

dsh plugin --profile web add 'github:DaoCaoRenH/dsh-openai-responses-bridge#<commit-sha>'

插件加載後，其內部 ID 爲 llm-openai-responses-bridge。在設置界面中，會出現“第三方模型”配置區域。

工作原理¶

協議路由¶

該插件在 llm-openai-responses-bridge 命名空間下提供路由支持，分爲兩種協議：

• OpenAI Responses (Bridge)：將請求轉換爲 OpenAI Responses POST /responses 接口。
• Google Generative AI：將請求轉換爲原生 Gemini generateContent 接口。

請求流程¶

對於 OpenAI Responses 路由，插件會執行以下操作：

1. DSH/Pi 構建包含對話、推理設置、本地工具和模型配置的標準請求。
2. 插件移除 max_output_tokens 字段，因爲部分第三方網關不接受該字段。
3. 如果啓用了託管搜索，插件會追加配置的 Responses 託管工具（默認爲 web_search），並在未設置 tool_choice 時將其設爲 auto，以請求搜索源。
4. 僅在託管搜索路徑下移除本地的 web_search Function Tool，其他本地工具保留。
5. Pi 繼續解析流式響應中的消息、推理、工具調用、使用量及錯誤數據。

Code Mode / PTC¶

在 Code Mode 或 PTC 中，插件不會註冊額外的 web_search_openai 工具。插件會觀察嵌套的 tools.web_search() 調度，對於啓用的 Bridge OpenAI Responses 路由，發送最小化的託管請求，並將結果返回爲 DSH 原生的 web_search 格式（content、sources、truncated），保持 SDK 契約不變。

憑證存儲¶

API Key 通過 DSH 的 credentials.set 接口寫入。在 YAML 配置中，使用 apiKeyEnv 作爲憑證引用，該字段本身不是密鑰值。

典型用法¶

OpenAI Responses 配置¶

對於 OpenAI Responses 路由，baseURL 必須是絕對 HTTP(S) URL，且不包含 /responses 後綴。插件會在請求時自動追加該後綴。

例如：

baseURL: https://api.example.com/v1

Gemini 配置¶

對於 Gemini 路由，需要包含原生 API 版本路徑。

例如：

baseURL: https://generativelanguage.googleapis.com/v1beta

注意事項¶

1. 版本依賴：當前版本嚴格依賴 DeepSeek Harness 0.1.2-alpha.2 的 API。
2. 字段處理：插件不會注入搜索系統提示詞，也不會重寫 max_tokens、text、reasoning、parallel_tool_calls、client_metadata 等原生請求字段。
3. 源碼修改：插件不會修改 DeepSeek Harness 的源碼樹。
4. 權限與安全性：託管搜索事件會被轉換爲 Bridge 會話事件，並在卡片中展示。插件不會實際抓取或執行搜索到的源 URL，僅展示其元數據。