模型能力实测xiaomao49/dsh-model-probe

dsh-model-probe

英文 | 中文

CI
npm version
License: MIT
DeepSeek Harness
dsh-plugin

审计并修正 DeepSeek Harness 中 llm-pi-ai 提供方的模型能力声明——通过直接询问端点本身，而不是信任某个知识库。

它是什么

一个 DeepSeek Harness 插件，用于实测 llm-pi-ai 端点实际接受什么，将实测结果与你声明的模型配置进行对比，并且只重写有证据证明是错误的内容。

- 先审计，再填充。 已有值的字段会对照证据进行检查，而不是被跳过——这是配置填充工具无法察觉的一种失败模式。
- 四个字段——contextWindow、maxTokens、reasoningEfforts、input（图像支持）。
- 两个界面——设置页面 模型配置实测，带有按提供方的开关、只读扫描，以及写入前的显式确认；以及 agent 工具 model_probe_status、model_probe_scan、model_probe_apply。
- 两种协议——openai-completions 和 anthropic-messages。
- 一个自包含的包——纯 JavaScript，无构建步骤，无运行时依赖；连探测图像都是在进程内合成的。

为什么

模型声明错误会让你在不知不觉中付出代价。这个插件正是基于两个真实案例构建的：

- maxTokens 超出端点限制。 一个模型声明了 maxTokens: 384000，而某个网关的合法范围是 [1, 131072]。没有任何东西会拒绝这个配置——插件能加载，模型会出现在选择器中——但每个携带该上限的请求都会以 HTTP 400 失败。
- 从目录中猜测的能力。 内置的 pi-ai 目录将 DeepSeek V4 系列列为仅支持文本。探测实际网关后发现，这两个模型都能正确读取图像，包括数出生成的测试图像中的形状。

填充缺失字段是简单的那一半。注意到某个字段已经有一个错误的值，才是真正重要的那一半——填充工具会跳过任何已有值的字段。

它如何得到答案

三种证据来源，按强度从高到低排列，外加一条针对它们未能确立之事的规则。每个结论都带有其来源和置信度标签。

| # | 方法 | 字段 | 成本 |
| --- | --- | --- | --- |
| 1 | GET /models——端点对自身的说明 | contextWindow，有时还有模态 | 1 次请求 |
| 2 | 约束探测 — 发送一个故意非法的值，从错误中读出合法范围 | maxTokens、reasoningEfforts | 0 个输出 token |
| 3 | 行为探测 — 随机生成一张图像，数出形状数量 | input（图像支持） | 约 50 个输出 token |
| — | 无可读信息 → 报告 unknown 并不写入 | — | 0 |

第 2 层是其他插件都不做的部分。它解析的两个真实错误响应体：

Invalid max_tokens value, the valid range of max_tokens is [1, 393216]
The max_tokens parameter is illegal.：限制数值范围[1,131072]
Invalid option: expected one of "low"|"medium"|"high"|"xhigh"|"max"

请求被拒绝，因此不会生成任何 token——端点只是直接告诉你它自己的限制。第 3 层之所以存在，是因为 OCR 式网关会在没有任何真正视觉能力的情况下回答“这张图里是什么词”；而数彩色形状无法用那种方式伪造。当 /models 已经报告支持图像时，它会跳过，以节省一次计费请求，并且它的结果优先于该自我报告——列表信息可能已过时。

安装

传入你的 DSH 实际启动时使用的 profile 名称。 安装到任何其他名称都会成功、以 0 退出、写入其依赖以及其 dsh.profile.bundles 条目，并且永远不会被加载。没有任何东西会报告这一点：唯一的痕迹是一行 stderr 输出
dsh: initialized profile web at …，而这是一个你从未要求创建的 profile。

在安装之前先读取活动 profile：

| 宿主 | 活动 profile |
| --- | --- |
| DSH Desktop（Electron） | 应用用户数据目录下 profile-selection/state.json 中的 "active"——在 Windows 上是 %APPDATA%\DSH Desktop\profile-selection\state.json |
| dsh CLI / web | 你传给 dsh --profile  的名称（dsh web 对应随附的 web profile） |

在 DSH Desktop 上答案不是 web。 该应用拥有名为 desktop 的 profile，其应用内插件市场会安装到该 profile 并热挂载它——因此 dsh plugin --profile web … 构建的是一个应用永远不会启动的独立 profile。当前的 dsh 构建拒绝从命令行管理 Electron 拥有的 profile（profile "desktop" is managed exclusively by the Electron application），因此在那些构建上，请从应用内部安装。那些仍然接受 --profile desktop 的旧构建，才是该名称正确的构建。

然后安装——从 npm 安装（预构建，因此安装会跳过 allowBuilds 构建批准步骤）：

dsh plugin --profile web add dsh-model-probe

或从 GitHub 安装：

dsh plugin --profile web add github:xiaomao49/dsh-model-probe

检查该层落在哪里——只有当 profile 既已安装又已启动时，它才会出现在组合树中：

dsh --profile web --dump-config | grep model-probe      # macOS / Linux
dsh --profile web --dump-config | findstr model-probe   # Windows

- id: model-probe 表示该层已就位。没有输出意味着你检查的 profile 与你安装到的 profile 不同——而如果该名称不是活动的
配置文件也一样，永远不会有任何东西加载它。

然后完全退出并重启 DSH。应用内市场会热挂载，并将
{"event":"hot-mount"} 记录到 /.dsh-market/log.ndjson；而 CLI 不会——它
只会协调配置文件的依赖项和 dsh.profile.bundles，并且不会告诉你
需要重启，所以插件会在重启后出现。该包是纯
JavaScript，没有构建步骤，因此无论走哪条路径都能安装，无需构建审批。

对等依赖警告（0.1.2 及更早版本）

旧版本会让 pnpm 在安装期间打印以下内容：

[WARN] Issues with peer dependencies found. Run "pnpm peers check" to list them.

随后 pnpm peers check 会以退出码 1 退出，将 @deepseek-ai/dsh-tools、
@deepseek-ai/schemastery 和 react 列为缺失——第一次看到它的人会将其理解为“安装
坏了”。其实从来都不是。配置文件运行时使用
autoInstallPeers: false，而这些包由 DSH
安装本身在运行时提供，从不由配置文件提供：一个正常工作的配置文件中的每个插件都会报告
同样的情况。0.1.3 将它们标记为 peerDependenciesMeta..optional，因此全新安装是
静默的，并且 pnpm peers check 以退出码 0 退出。如果你仍然看到该警告——可能是较旧的固定
版本，或者尚未重新解析的配置文件——它仍然只是提示信息。

如果你在 0.1.3 之前安装

0.1.2 及更早版本无法区分“一切匹配”和“什么都没测量到”：当
每个请求都失败时（fetch failed——DNS、拒绝、重置、TLS），设置页面仍然
显示绿色的配置与实测一致，无需改动*
（配置与实测一致，无需改动）。完全失败却呈现为健康状态，是这个插件可能有的
最糟糕的 bug。0.1.3 添加了 verification 块、按模型的
N 个未验证行，以及 fetch failed 背后的真实原因。使用以下命令升级：

dsh plugin --profile web add dsh-model-probe@latest

使用

设置 → 模型配置实测——“模型配置探测”。该界面仅提供中文标签，
所以这就是要查找的字符串；下面的解释是翻译，不是 UI 文本。

1. 为某个提供商打开允许探测（“允许探测”）。探测默认关闭，
并按提供商启用，因为它会向该端点发送真实请求。
2. 扫描（“扫描”）——只读。显示每个字段的当前值、实测值、
证据来源和置信度。
3. 确认写入（“应用”）——备份 settings.yaml，然后通过
settings.mutate 以乐观锁写入。

写入使用你刚刚审查过的扫描结果。只要配置自那以后没有变化，
该扫描就会按原样复用——不会有第二轮探测请求，因此落盘的内容
就是屏幕上显示的内容。行为探测（图像测试）第二次可能会给出不同
结果，而证据仅对其采集时所针对的配置有效，
因此变更后的修订会使缓存按设计失效。如果完全没有已审查的扫描——一个
全新进程，或 agent 自行调用 model_probe_apply——都会先运行一次完整扫描，
包括图像探测。响应会报告实际使用的是哪种：
evidence: reviewed-scan | fresh-scan。

还为 agent 注册了三个工具：model_probe_status、
model_probe_scan、model_probe_apply。

配置

这些默认值随 bundle patch 一起提供，位于 settings.yaml 中的
model-probe 设置命名空间下。页面上的开关和 agent 工具都会写入 enabledProviders，
因此该文件很少需要手动编辑。

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| enabledProviders | [] | 可被探测的提供方。为空表示所有地方都关闭探测。 |
| maxRequestsPerScan | 60 | 每次扫描的请求上限，这样一次误点不会变成大量计费调用。 |
| visionProbe | true | 运行图像探测——这是唯一会生成输出 token 的步骤。 |
| toleranceRatio | 0.05 | 数值字段的比较容差（见下文）。上限为 0.5。 |
| probeHeaders | {} | 仅用于探测请求的额外请求头，按提供方指定：{ providerId: { header: value } }。 |

探测的额外请求头

有些网关需要 API key 之外的请求头。实测案例：
https://opencode.ai/zen/go/v1（Console Go）在没有
x-opencode-session 时会拒绝每个请求。该请求头只能来自两个地方，而且它们
不可互换：

| 位置 | 效果 |
| --- | --- |
| llm-pi-ai.providers..headers | 每次 DSH 模型调用也会发送。如果某个插件已经按会话派生该请求头，这里的静态条目会胜出并静默禁用它——把每个会话都压缩进同一个路由/缓存亲和性桶。 |
| model-probe.probeHeaders. | 仅由本插件的探测请求发送。DSH 自身的调用不受影响。 |

model-probe:
probeHeaders:
opencode-go:
x-opencode-session: dsh-model-probe

同名优先级：这里的条目优先于 llm-pi-ai 的条目，因为这是你为探测指定的值。
值可能包含凭据，因此它们绝不会通过设置 API 返回，也不会写入任何日志——
设置页面只会报告哪些提供方拥有这些值。

比较容差

数值字段使用 5% 比较容差：当配置值已存在且与测量值相差在 5% 以内时，
保持不变；超出该范围时，会用测量值覆盖。这样可以避免因单位约定
（1M 与 1MiB）和有意保留的安全余量而产生的反复变动。

容差绝不会放宽越界检查：超过端点硬限制的值无论差距多小都会被修正，
因为此类请求会被直接拒绝。

安全规则

- 探测默认关闭；当前状态会在设置页面上说明。
- 扫描是只读的。写入需要显式确认，并会检查两次。
- 每次写入前都会备份 settings.yaml；被拒绝的写入会移除自己的
- 备份，因此失败的尝试不会留下任何杂乱内容。
- 凭据通过凭据接缝按请求解析——从不缓存、从不记录日志、从不通过设置 API 返回。来自你的 llm-pi-ai 配置的提供商级 headers 会随每个探测请求发送，且仅在此处发送。
- 写入读取原始用户层（settings.describe().user），而非解析后的值，因此 schema 默认值绝不会被写入你的配置文件。
- 没有证据的字段会报告为 unknown 并保持原样。

说明

- 提供商路由从 llm-pi-ai 设置命名空间读取。
- 提供商自身的 headers 会转发到每个探测请求，与 DSH 发送它们的方式完全一致。某些网关需要 API 密钥之外的请求头——opencode.ai/zen/go/v1 会拒绝任何不带 x-opencode-session 的请求——没有这一点，整个提供商会显示为不可测量，而非配置错误。
- 探测支持 openai-completions 和 anthropic-messages。
- 图像探测使用运行时合成的 PNG（Node 的 zlib 加一个小型 CRC32），因此该包没有图像依赖。
- 端点错误措辞各不相同。当约束无法解析时，该字段会报告为 unknown，而非猜测。

测试

npm test

140 个测试，包括固定报告规则的回归测试：全部失败的运行绝不能渲染为“无需更改”，部分验证的运行必须说明实际测量了多少个字段。测试夹具包含从真实网关捕获的逐字错误响应体，以及设置路径操作语义的字节级重新实现，因此写入在被视为正确之前会针对真实 schema 进行验证。

许可证

MIT

中文说明

向端点本身取证，审计并修正 llm-pi-ai 供应商的模型能力声明。

这是什么

一个 DeepSeek Harness 插件：实测 llm-pi-ai 端点真正接受什么，把实测结果与你声明的模型
配置逐字段比对，只改有证据证明是错的那部分。

- 先审计，再补全。 已经有值的字段会被拿去和证据核对，而不是被跳过——这正是配置填充器
看不见的那类问题。
- 四个字段 —— contextWindow、maxTokens、reasoningEfforts、input（图像支持）。
- 两个入口 —— 设置页「模型配置实测」：逐 provider 开关、只读扫描、写入前显式确认；以及
Agent 工具 model_probe_status、model_probe_scan、model_probe_apply。
- 两种协议 —— openai-completions 与 anthropic-messages。
- 自包含的包 —— 纯 JavaScript，无构建步骤、无运行时依赖；连探针图片都在进程内合成。

为什么需要它

配错的模型不会报错，只会静默地失败。两个真实案例：

- maxTokens 超过端点上限。 某模型声明 maxTokens: 384000，而网关的合法范围是
[1, 131072]。配置能加载、模型在选择器里正常显示，但每个带上这个上限的请求都会
被 HTTP 400 拒绝。
- 能力来自目录的猜测。 pi-ai 内置目录把 DeepSeek V4 系列标为纯文本，实测该网关
下两个模型都能正确读图——包括数出生成图片里的图形数量。

补全缺失字段是容易的一半；发现某个字段已经有值但是错的才是关键——填充器看到字段
有值就跳过了。

取证方式

三个取证来源，证据强的优先；它们都没能确立的字段，统一按最后一条规则处理。每个结论都带
来源与置信度。

| 层级 | 手段 | 字段 | 成本 |
| --- | --- | --- | --- |
| 1 | GET /models，端点自述 | contextWindow，有时含模态 | 1 次请求 |
| 2 | 约束取证：故意发非法值，从报错里读出合法范围 | maxTokens、reasoningEfforts | 0 输出 token |
| 3 | 行为实证：随机生成图片，数图形 | input（图像能力） | 约 50 个输出 token |
| — | 都读不出 → 标 unknown，不写入 | — | 0 |

第 2 层是其它插件没做的部分。它能解析的真实错误体：

无效的 max_tokens 值，max_tokens 的有效范围是 [1, 393216]
max_tokens 参数不合法。：限制数值范围[1,131072]
无效选项：应为 "low"|"medium"|"high"|"xhigh"|"max" 之一

请求被拒绝，因此没有 token 被生成——端点只是告诉了你它自己的限制。第 3 层存在的原因：
OCR 型网关能答对「图里是什么字」却没有真正的视觉能力，而数彩色图形无法这样蒙对。当
/models 自述已含图像支持时这一层会被跳过，以省下一次计费请求；而一旦真跑了实证，它的
结论优先于端点自述——自述可能过时。

第 3 层的判定分两步，因为「数错」与「看不到」必须分开：

1. 计数：随机生成一张图，只认模型显式声明的那个数。模型有时会按序描述图片
（1. A yellow circle 2. A blue square …），所以解析取声明值（TOTAL=、
"the answer is"、"there are"），不取「第一个数字」——后者会读到列表序号，把一个
正确的回答读成错答。读不出数字按「本次无结论」处理，换一张新图重试。
2. 差异核对（计数连续三次没读出正确答案时）：再生成两张只在目标图形数量上不同的
图，要求分别报出 IMAGE_1= 与 IMAGE_2=。两次读数不同就说明回答确实
来自像素；两次读数相同则报「未确认」，而不是报「不支持图像」。

只有否定性证据才会给出 input: text：端点明确拒绝图像输入、模型主动声明看不到图，
或答案恒为 0（生成的图里目标图形恒有 2~5 个，0 在结构上不可能）。

安装

--profile 必须写你的 DSH 实际启动的那个档位。 装进别的名字一样会成功：退出码 0、
依赖与 dsh.profile.bundles 都写好了，然后永远不会被加载。全程没有任何报错可查——唯一
的痕迹是 stderr 上一行 dsh: initialized profile web at …，替你去创建一个你从没打算
要的档位。

安装前先确认当前活动的档位：

| 宿主 | 活动档位怎么看 |
| --- | --- |
| DSH Desktop（Electron） | 应用 user-data 目录下 profile-selection/state.json 的 "active"（Windows 为 %APPDATA%\DSH Desktop\profile-selection\state.json） |
| dsh CLI / web | 你 dsh --profile  里传的那个名字（dsh web 即内置的 web 档位） |

在 DSH Desktop 上，答案不是 web。 应用独占名为 desktop 的档位，它内置的插件市集
就是装进这个档位并热挂载的——所以 dsh plugin --profile web … 建出的是应用永远不会启动
的另一个档位。较新的 dsh 直接从命令行拒绝管理这个 Electron 档位——profile "desktop" is
managed exclusively by the Electron application——这类版本请改在应用内（插件市集）安装；
仍然是老版本、接受 --profile desktop 的，那个名字才是对的。

然后安装——从 npm 装（预构建，免去 allowBuilds 构建授权）：

dsh plugin --profile web add dsh-model-probe

或从 GitHub 装：

dsh plugin --profile web add github:xiaomao49/dsh-model-probe

确认这一层落在哪个档位上——只有「装好且会被启动」的档位，组合树里才看得到它：

dsh --profile web --dump-config | grep model-probe      # macOS / Linux
dsh --profile web --dump-config | findstr model-probe   # Windows

出现 - id: model-probe 说明层已就位；没有任何输出，说明你查的档位和你装进去的档位不是
同一个——而只要它不是活动档位，这个插件就永远不会被加载。

然后完全退出并重启 DSH。应用内市集是热挂载的，会在
/.dsh-market/log.ndjson 里记 {"event":"hot-mount"}；CLI 不热挂载——它只负责
协调档位的依赖与 dsh.profile.bundles，也完全不提示需要重启，所以插件要重启后才
出现。包是纯 JavaScript、无构建步骤，两种方式都不需要构建授权。

那条 peer 警告（0.1.2 及更早）

老版本安装时 pnpm 会打印：

[WARN] Issues with peer dependencies found. Run "pnpm peers check" to list them.

随后 pnpm peers check 退出码为 1，列出 @deepseek-ai/dsh-tools、
@deepseek-ai/schemastery、react 缺失——第一次看到的人很容易当成装坏了。其实从来不是。
profile 跑在 autoInstallPeers: false 下，而这些包由 DSH 本体在运行时供给，profile 层
本就不该安装它们：任何一个能正常工作的 profile 报的都是同一批。0.1.3 已把它们标为
peerDependenciesMeta..optional，因此全新安装不会再打印警告，pnpm peers check 退出
码为 0。如果你仍然看到这条警告——装的是被 pin 住的老版本，或者 profile 还没重新解析——
它依然只是信息性的。

如果你装的是 0.1.3 之前的版本

0.1.2 及更早无法区分「全都一致」和「什么都没测到」：所有请求都失败（fetch failed——
DNS、连接被拒、连接重置、TLS）时，设置页依然显示绿色的「配置与实测一致，无需改动」。
把彻底失败展示成一张健康证明，正是这个插件最不该犯的错。0.1.3 增加了 verification
区块、逐模型的「N 个未取证」提示，以及 fetch failed 背后的真实原因。升级：

dsh plugin --profile web add dsh-model-probe@latest

使用

设置 → 模型配置实测

1. 为某个 provider 打开「允许探测」。探测默认关闭、逐 provider 开启，因为它会向该端点
发真实请求。
2. 扫描——只读。列出每个字段的当前值、实测值、证据来源与置信度。
3. 确认写入——先备份 settings.yaml，再通过 settings.mutate 带乐观锁写入。

写入用的是你刚看过的那次扫描。配置在扫描之后没动过，就直接复用它——不再发第二轮
探测请求，于是落盘的就是屏幕上显示的那一份。行为型探针（图像实证）第二次可能给出不同
答案，而证据只对它取证时的那份配置有效，所以修订号一变缓存即失效，这是刻意的。完全
没有可复用的扫描时（新进程、或 Agent 直接调 model_probe_apply），会先完整取证，包含
图像实证。返回值会说明用的是哪一次：evidence: reviewed-scan | fresh-scan。

同时为 Agent 注册了三个工具：model_probe_status、model_probe_scan、
model_probe_apply。

配置项

以下默认值随 bundle 补丁发布，位于 settings.yaml 的 model-probe 命名空间下。设置页的
开关与 Agent 工具会写 enabledProviders，所以基本不需要手工改这个文件。

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| enabledProviders | [] | 允许探测的 provider。空数组表示全部关闭。 |
| maxRequestsPerScan | 60 | 单次扫描的请求数上限，避免一次误点变成一批计费请求。 |
| visionProbe | true | 是否做图像实证——唯一产生输出 token 的环节。 |
| toleranceRatio | 0.05 | 数值字段的比较容差（见下）。上限 0.5。 |
| probeHeaders | {} | 只用于探测请求的额外头，按 provider 分组：{ providerId: { header: value } }。 |

探测专属请求头

有些网关除 API key 外还强制要求别的头。实测案例：https://opencode.ai/zen/go/v1
（Console Go）缺 x-opencode-session 就一律拒绝。这个头只有两个地方可配，而它们不
可互换*：

| 配置位置 | 影响 |
| --- | --- |
| llm-pi-ai.providers..headers | DSH 的每一次模型调用也会带上。若有插件正在按会话动态推导这个头，这里的静态值会胜出并静默废掉它——所有会话塌缩成同一个路由/缓存亲和桶。 |
| model-probe.probeHeaders. | 只随本插件的探测请求发出，DSH 自身的调用完全不受影响。 |

model-probe:
probeHeaders:
opencode-go:
x-opencode-session: dsh-model-probe

同名时这里的值优先于 llm-pi-ai 的——那是你为探测显式指定的值。这些值可能含凭据，
因此绝不经设置 API 返回、也绝不写进任何日志：设置页只报告哪些 provider 配了它们。

比较容差

数值字段采用 5% 比较容差：当前值已有值且与实测值差距在 5% 以内时保持不动，超过
才覆盖为实测值。这样可避免为单位约定（1M 与 1MiB）或刻意留出的安全余量制造无谓改动。

容差不会放松越界判定：越过端点硬约束的值无论差距多小都必须修正，因为那种请求会被直接
拒绝。

安全守则

- 探测默认关闭，设置页上如实显示当前状态。
- 扫描只读；写入需要显式确认，且校验两次。
- 每次写入前备份 settings.yaml；写入被拒时删除自己的备份，失败的尝试不留垃圾。
- 凭据按次通过凭据 seam 解析——不缓存、不写日志、不经设置页 API 返回。provider 自己配的
headers 只会随探测请求发出，不会用于别处。
- 写入读取原始用户层（settings.describe().user）而非解析值，schema 默认值绝不会
被固化进你的配置文件。
- 没有证据的字段报告为 unknown 并保持不动。

说明

- provider 路由读自 llm-pi-ai 设置命名空间。
- provider 自己配的 headers 会随每个探测请求照发，与 DSH 的行为一致。有些网关除 API key
外还强制要求别的头（opencode.ai/zen/go/v1 缺 x-opencode-session 就一律拒绝），不转发
的话整个 provider 看起来像"测不出来"，而实际只是配置少了一个头。
- 支持 openai-completions 与 anthropic-messages 两种协议的探测。
- 图像探针用的 PNG 在运行时合成（Node 自带 zlib 加自实现的 CRC32），因此本包没有任何
图像依赖。
- 端点的报错措辞并不统一。约束读不出来时字段报告为 unknown，不做猜测。

测试

npm test

140 项。其中含专门钉住「报告口径」的回归：全部取证失败时绝不能渲染成「无需改动」；部分
取证成功时必须说明究竟量到了几个字段。测试夹具里有从真实网关逐字抓下来的错误体，还有一份
对设置路径操作语义的逐字节复刻，因此写入在通过之前就已经过真实 schema 校验。

许可

MIT