前言¶
DeepSeek Harness 生态采用“一切皆插件”的理念。在开发智能体或使用 DSH 时，开发者常遇到这样一个问题：文档声称服务器支持某项 OpenAI 兼容协议特性，但在实际调用时却因参数错误或流式处理异常而中断。dsh-compat-probe 专门解决这一问题。
插件介绍¶
这是一个 DeepSeek Harness 插件，名为 compat_probe。它发送五个微型 fixture 请求到目标 OpenAI 兼容服务器，并返回一个“协议卡”。这张卡由一组布尔值组成，精确描述服务器实际实现了哪些功能，而非文档声称的内容。它主要用于回答那些会在 Harness 运行时导致崩溃的问题：服务器是否在线？GET /models 是否有响应？stream: true 是否返回 Server-Sent Events？服务器是接受 max_tokens、max_completion_tokens 还是两者都拒绝？
核心功能¶
- 协议兼容性探测：兼容 OpenAI 服务器协议。
- Fixture 测试：发送五个微型请求并返回协议卡。
- 细节检查：检查协议实现细节，包括流式传输类型、
max_tokens、max_completion_tokens等。 - 无额外依赖：不包含 GGUF 权重，不启动
llama-server或任何其他进程。 - 离线测试：支持离线测试（使用
node:httpmock）。
安装与启用¶
使用官方安装命令进行添加：
dsh plugin --profile web add github:jwilson411/dsh-compat-probe
安装器会读取 dsh.bundle.patch 并将 cordis.patch.yml 追加到配置中。安装后，需确保依赖版本正确，否则可能导致输出格式不匹配：
npm install @deepseek-ai/dsh-tools@0.1.1-rc.2
配置¶
在插件的 cordis.patch.yml 中设置以下字段：
baseURL：目标服务器的地址，包含 API 前缀（如/v1），例如http://127.0.0.1:8080/v1。apiKey：认证密钥。发送为Authorization: Bearer，建议使用环境变量DSH_COMPAT_PROBE_API_KEY而非直接写入配置。allowRemote：是否允许探测非回环地址。默认为false，必须显式设为true才能探测其他主机。model：fixture 请求中使用的模型 ID。timeoutMs：每个请求的超时时间（毫秒），默认为 3000。
探测卡¶
工具返回一个对象，包含以下字段：
reachable：是否收到任何 HTTP 响应。models_ok：GET {baseURL}/models是否返回 2xx 状态码。stream_sse：stream: true是否返回 Server-Sent Events（text/event-stream或data:帧）。stream_ignored_json：stream: true是否被忽略，返回了一个非流式的 JSON 完成对象。honors_max_tokens：服务器是否接受max_tokens参数。honors_max_completion_tokens：服务器是否接受max_completion_tokens参数。http_status：第一个非 2xx 状态码，或最后一个成功状态码，或null（无连接）。error_code：错误代码（UNREACHABLE,HTTP_ERROR），仅在失败时存在。
注意事项¶
- 安全默认值：默认仅探测回环地址（
localhost,127.0.0.1,::1）。拒绝非回环目标直到显式允许。回环判断基于写入的地址，而非解析结果。 - 非测试工具：不是 Ollama、负载测试器或 GPU 基准测试工具。
- 非客户端：不是托管 OpenAI 或 Anthropic 的客户端。
- 无权重/进程：不包含 GGUF 权重或下载功能，不启动
llama-server或任何其他进程。
结语¶
该工具专注于协议验证与兼容性确认，而非性能测试。它通过结构化数据回答“服务器实际上能做什么”，帮助开发者避免运行时错误。相关资源请参考目录页与 GitHub 仓库。
