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，仅展示其元数据。