兼容性探测卡 jwilson411/dsh-compat-probe

dsh-compat-probe

一个 DeepSeek Harness 插件，只包含一个工具。compat_probe 会向一个 OpenAI 兼容服务器发送五个微型 fixture 请求，并返回一张协议卡片：一组固定的布尔值，说明该服务器实际实现了什么，而不是它的文档声称实现了什么。

这张卡片回答的是那些会在运行时让 harness 崩溃的问题。服务器是否在线？GET /models 是否有响应？stream: true 返回的是 Server-Sent Events，还是因为该构建忽略了该标志而返回一个非流式的 JSON completion？它接受 max_tokens、max_completion_tokens、两者都接受，还是都不接受？

它与 dsh-llamacpp 搭配使用，后者负责实际的服务。这个包只负责提问。

这不是什么

- 它不附带 GGUF 权重，也不下载任何权重。
- 它不启动 llama-server 或任何其他进程。请把它指向你已经在运行的服务器。
- 它不是 Ollama，也不使用 Ollama API。
- 它不是负载测试器。当模型调用该工具时，只发送五个请求，仅此一次。
- 它不是 GPU 基准测试。它不测量任何关于吞吐量、延迟或硬件的内容。
- 它不是托管版 OpenAI 或托管版 Anthropic 的客户端。默认目标是回环地址，除非部署方明确选择启用，否则非回环目标会被拒绝。

安装

dsh plugin --profile web add github:jwilson411/dsh-compat-probe

安装程序会从 package.json 读取 dsh.bundle.patch，并将 cordis.patch.yml 追加到该 profile 的有序 bundle 列表中。该 bundle 会插入一行 compat-probe，指向回环地址。

固定 harness 包版本

请显式安装 0.1.1-rc.2 版本的 @deepseek-ai/dsh-*。这些包上的 latest dist-tag 比本插件所针对构建的版本更旧，因此未固定版本的安装会解析到更旧的版本，defineTool 将不具备这里使用的输出 schema 结构。

npm install @deepseek-ai/dsh-tools@0.1.1-rc.2

配置

在 profile 的 cordis.patch.yml 中，或在 --patch 覆盖层中，在带有 id: compat-probe 的那一行上设置这些项。以 id 为目标的 patch 会替换该行的整个 config，因此请重新声明你希望保留的每个字段。

| 键 | 默认值 | 环境变量回退 | 备注 |
| baseURL | http://127.0.0.1:8080/v1 | DSH_COMPAT_PROBE_BASE_URL | 包含 API 前缀，因此 /v1 绝不会被追加两次。这是 llama-server --port 8080 监听的位置。 |
| apiKey | 未设置 | DSH_COMPAT_PROBE_API_KEY | 设置后以 Authorization: Bearer 发送，且绝不记录到日志。优先使用环境变量，而不是把凭据写入 profile。绝不作为工具参数。 |
| allowRemote | false | 故意不提供 | 允许非回环的 baseURL。没有环境变量回退：扩大 harness 发送请求的目标范围，应当通过编辑 profile 来实现，而不是通过导出的 shell 变量。 |
| model | probe | DSH_COMPAT_PROBE_MODEL | fixture 请求中指定的模型 id。单模型服务器会忽略它。 |
| timeoutMs | 3000 | DSH_COMPAT_PROBE_TIMEOUT_MS | 每个请求的预算，以毫秒为单位。 |

该工具本身不声明任何参数。探测哪里以及发送哪个凭据属于部署决策，因此模型无法将测试装置指向操作员未指定的主机，也没有参数槽可用于夹带密钥。

结果卡片

| 字段 | 类型 | 含义 |
| reachable | boolean | 任一测试请求收到了 HTTP 响应。 |
| models_ok | boolean | GET {baseURL}/models 返回了 2xx。 |
| stream_sse | boolean | 一个 stream: true 的聊天补全以 Server-Sent Events 形式返回（text/event-stream，或 data: 帧）。 |
| stream_ignored_json | boolean | 一个 stream: true 的聊天补全以单个非流式 JSON chat.completion 返回，意味着服务器忽略了 stream。 |
| honors_max_tokens | boolean | 携带 max_tokens: 1 的 POST 未返回 4xx 或 5xx。 |
| honors_max_completion_tokens | boolean | 携带 max_completion_tokens: 1 的 POST 未返回 4xx 或 5xx。 |
| http_status | integer 或 null | 按探测顺序看到的第一个非 2xx 状态码，否则为最后一个成功状态码，若未建立任何连接则为 null。 |
| error_code | string 或 null | 当每个测试请求都返回 2xx 时为 null。当请求未收到应答时为 UNREACHABLE，当返回非 2xx 时为 HTTP_ERROR。 |

失败是字段，而不是异常。连接被拒绝、DNS 失败、超时以及 500 都会落入卡片中，因此无论服务器是健康还是已死，模型读到的都是同一种形态。

对非回环目标的默认拒绝

仅探测回环主机（localhost、::1、127.0.0.0/8 中的任何地址）上的 http: 和 https:。其他任何目标都会在打开套接字之前被拒绝，并且该拒绝是抛出而非返回，因此不会因忘记读取布尔值而被忽略。要探测另一台主机上的服务器，请在插件行上设置 allowRemote: true。

回环按书写形式判断，而非按解析结果判断。一个恰好解析为 127.0.0.1 的主机名对此检查而言仍属远程。

拒绝会携带稳定的 reason：INVALID_URL、SCHEME_DENIED 或 NOT_LOOPBACK。

测试

npm test

该测试套件是离线的。它探测的每个服务器都是绑定到 127.0.0.1:0 的 node:http 模拟服务器，因此内核会选择一个空闲端口，不会联系本机之外的任何东西。没有 GGUF 权重，没有 llama.cpp 进程，没有 GPU，没有凭据。不可达性通过绑定一个端口再释放它来产生，而不是通过等待超时。

主题

dsh-plugin、deepseek-harness、llama-cpp

许可证

MIT。参见 LICENSE。