yuioi666/dsh-plugin-model-capability

dsh-plugin-model-capability

npm version
npm downloads
License
GitHub stars
dsh

模型能力管理器 — 在应用内设置的专属 模型能力 页面中管理 DeepSeek Harness（DSH Web）的 llm-pi-ai 提供商路由：按模型配置思考等级、上下文窗口、输出上限、输入模态、按路由默认值、网关兼容字段、一键预设，以及可切换 EN/中文 的界面。

简体中文说明 · 报告 Bug · 请求新功能

目录

- 为什么需要这个插件
- 截图
- 功能特性
- 安装
- 快速开始
- 卸载
- 常见问题 / 故障排查
- 工作原理
- 开发
- 发布
- 贡献
- 许可证

为什么需要这个插件

DSH 将提供商配置存储在 settings.yaml 中的 llm-pi-ai.providers 里。手动编辑容易出错，而且有两类问题经常困扰用户：

1. 网关不兼容 — 并非每个厂商都接受相同的协议方言。例如阿里云（DashScope）在 compatible-mode 下，以及 Moonshot/Kimi、智谱/BigModel、MiniMax、火山引擎方舟、SiliconFlow、百度千帆等网关，可能会拒绝 OpenAI/Anthropic 方言所期望的 developer 角色消息或 reasoning_effort 回显。对此类网关开启 compat.supportsDeveloperRole 会产生 400 类错误。
2. 思考等级接线 — 7 个等级（off / minimal / low / medium / high / xhigh / max）各自需要一个上游提供商能理解的接线值（例如 low 对某个厂商是 "low"，对另一个厂商是 "h3"）。最大思考配置和按模型的 reasoningEfforts 手动编写起来非常繁琐。

本插件为以上所有内容提供了图形界面，并附带一键预设，内置了方言安全的配置（参见预设）。

截图

| 设置入口 | 分区概览（EN） |
| --- | --- |
| 设置入口 | 分区概览 EN |
| 模型编辑器（英文） | 网关兼容性折叠（中文） | 章节概览（中文） |
| --- | --- | --- |
| 模型编辑器英文 | 兼容性编辑器中文 | 章节概览中文 |

功能特性

- 每个路由的逐模型编辑器：
- name、contextWindow、maxTokens —— 容量字段接受纯数字或 K/M 后缀（262144、256K、1M）。
- input 模态 —— text / image 复选框，并自动去重。
- 思考开关 —— 在整个模型范围内切换推理关闭与完整的 7 级矩阵（off/minimal/low/medium/high/xhigh/max），每一级都有自己的线上值。空的非 off 级别会被阻止（Host 会拒绝它们），并包含一个一键用相同值填充所有级别按钮。
- 将字段应用到该路由的所有模型（name / contextWindow / maxTokens / input / reasoningEfforts）。
- 逐模型的 compat 编辑器（默认折叠）。
- 逐路由编辑器：
- displayName、baseURL、api（openai-completions / openai-responses / anthropic-messages）。
- 默认值：defaultContextWindow、defaultMaxTokens、defaultInput、reasoning、thinkingBudgets（minimal/low/medium/high）、cacheRetention、transport。
- 路由级 compat 编辑器以及一个高级折叠区：超时、最大图像字节数 / 像素预算、headers，外加一个只读的原始 JSON 视图。
- 一键预设 —— 7 个内置配方加上你自己保存的预设：
| 预设 | 作用 |
| --- | --- |
| 安全网关 | compat.supportsDeveloperRole=false、supportsReasoningEffort=true —— 适用于拒绝 developer 角色消息的网关（DashScope 兼容模式、Kimi/Moonshot、智谱、MiniMax、方舟、硅基流动、千帆等） |
| OpenAI 原生 | developer 角色 + reasoning_effort + thinkingFormat=openai + maxTokensField=max_completion_tokens |
| DeepSeek 方言 | thinkingFormat=deepseek、开启 developer 角色、开启 reasoning_effort |
| Qwen 方言 | thinkingFormat=qwen、关闭 developer 角色、开启 reasoning_effort |
| 最大思考（7 级） | 每个模型都声明全部 7 个级别、reasoning=high、宽松的 thinkingBudgets |
| 仅文本 | defaultInput=['text'] 以及逐模型 input=['text'] |
| 图像就绪 | defaultInput=['text','image'] 以及逐模型 input=['text','image'] |
- 将任意预设应用到选定的路由子集。将当前配置保存为自定义预设；随时应用和删除它们。自定义预设存储在 settings.yaml 中的 model-capability.customPresets 下。
- 应用自定义预设会通过 settings.replace 替换整个 llm-pi-ai 用户区段，而不是合并。任何在预设保存之后添加到用户区段的路由都将被删除。这不是一个增量配方 —— 请将该预设视为完整快照。
- 请求头凭据保护 — 凭据形式的请求头名称（authorization、api-key 等）在请求头编辑器中会被阻止，并且在保存自定义预设时，headers 字典会从每个提供商路由中被剥离（凭据以 apiKeyEnv 引用名称的形式传递，绝不会作为字面请求头值）。在此保护措施之前保存的现有预设会在启动时被检测到，并在建议检查中报告。
- 建议检查 — 页面会显示关于你当前设置的诊断信息：带有 supportsDeveloperRole 开启的旧版网关相似 URL（提示：使用 Safe gateway）、映射不到任何线上值的推理级别、没有显式 contextWindow 的模型，以及没有模型的路由。
- 语言切换 — 页面会跟随 DSH UI 语言，页面头部的一个选择器可让你固定为 English / 中文 / 跟随 DSH。该选择会持久化到 settings.yaml（model-capability.language），而不仅仅是浏览器会话。

所有写入都通过 DSH 设置服务进行，并带有修订版本防护（expectedRevision），与内置 Models 页面使用的模式相同；冲突的并发编辑会通过实时镜像重试。如果页面从非回环源打开（不允许写入），所有控件都会被禁用并显示提示。

安装

需要带有 Web 应用的 DSH 安装（任何提供浏览器 UI 的 profile），DSH ≥ 0.1.1-rc.2。

安装最新版本

dsh plugin --profile web add dsh-plugin-model-capability   # latest stable, or pin @

然后重启 dsh --profile web（运行中的 Web UI 在安装插件时不会热重载）。Model Capability 条目会出现在 Settings 下。

对于其他 profile，请将 web 替换为你的 profile 名称。

在需要特定发布版本时固定确切版本 — 请参阅下方的获取最新版本。不指定版本安装可能会解析到本地缓存或注册表 CDN 上的较旧发布版本。

获取最新版本（缓存 / 发布延迟注意事项）

只有在所有三个缓存一致时，新发布版本才会被获取——npm 注册表
CDN 元数据、你的本地 pnpm store，以及 profile 的 lockfile。其中任何一个
过期，都意味着 dsh plugin add dsh-plugin-model-capability（不带版本）会继续
安装旧构建。要确保你获得最新版本：

1. 检查注册表当前拥有的版本：
npm view dsh-plugin-model-capability version

如果这里没有显示你期望的版本，说明注册表 CDN 仍在提供
过期的元数据——等待约 1–2 分钟并重试（npm 发布通常
几秒内即可见，但 packument 元数据会按 TTL 缓存）。

2. 先卸载任何先前安装的副本（请参阅下方的卸载）。
否则 profile lockfile（node_modules/.pnpm/lock.yaml /
pnpm-lock.yaml）会继续固定旧版本。

3. 使用确切版本安装——这会绕过元数据解析：
dsh plugin --profile web add dsh-plugin-model-capability@
e.g. dsh plugin --profile web add dsh-plugin-model-capability@1.1.1

4. 如果配置文件仍然报告旧版本，请清除过期的本地缓存：
pnpm store prune                 # 移除未被引用的存储包

或者，针对配置文件本身：
cd "$HOME/.dsh/profiles/web"
pnpm store prune

5. 验证实际安装的内容：
grep -A2 '"dependencies"' "$HOME/.dsh/profiles/web/package.json"

（Windows PowerShell：Select-String -Path "$HOME\.dsh\profiles\web\package.json" -Pattern "model-capability"）
dsh-plugin-model-capability 旁边显示的版本必须与你打算安装的版本一致。

6. 重启 Web UI —— 插件在启动时加载，从不热重载：
dsh --profile web

注册表说明：已发布的版本永远无法被覆盖。如果某个有问题的构建以 0.1.2 发布，修复方式是发布新版本（0.1.3、1.1.1……），而不是重新发布——这正是为什么“安装最新版”意味着锁定版本，而不是 npm update。

卸载

dsh plugin --profile web remove dsh-plugin-model-capability

如果命令报告 no such dependency found（一种损坏的安装，其依赖项条目在 package.json 中缺失），请直接在配置文件内移除它：

cd "$HOME/.dsh/profiles/web"
pnpm remove dsh-plugin-model-capability

无论执行哪一步，之后都要重启 dsh --profile web。

要验证插件已完全移除：

- "$HOME/.dsh/profiles/web/package.json" —— dependencies 下没有 dsh-plugin-model-capability 条目
- "$HOME/.dsh/profiles/web/node_modules/dsh-plugin-model-capability" —— 目录已不存在
- "$HOME/.dsh/profiles/web/pnpm-lock.yaml" —— 没有 dsh-plugin-model-capability 引用（0 处命中）

宿主端也可以无头加载（它会注册设置架构）；设置 UI 本身需要 Web 应用。

快速开始

安装插件并重启 DSH 后，侧边栏的设置下会出现模型能力页面。以下是如何通过三个步骤快速上手：

1. 打开页面

导航到设置 → 模型能力。你将看到所有已配置的提供商路由列表（例如 openai、anthropic、dashscope 等），每个路由下方都列出了其模型。

2. 应用预设（推荐的第一步）

获得可用配置的最快方式是使用一键预设：

1. 点击页面标题栏中的预设按钮。
2. 选择与你的网关类型匹配的预设（例如，DashScope/Moonshot/Zhipu 选择 Safe gateway，官方 OpenAI 选择 OpenAI native，DeepSeek API 选择 DeepSeek dialect）。
3. 选择要应用该预设的路由（或保持全选）。
4. 点击应用。

预设会自动填入推荐的 compat 字段、思考级别和默认值。
3. 微调单个模型

点击任意模型行以展开其编辑器。在此处你可以：

- 设置上下文窗口和最大 token 数（支持 K/M 后缀，例如 128K、1M）。
- 开启/关闭思考，并配置 7 个推理级别中的每一个。
- 更改输入模态（text / image）。
- 展开 compat 折叠项，以按模型调整网关特定的字段。

所有更改都会通过 DSH 设置服务立即保存，并带有修订围栏（revision fencing）——无需手动编辑 YAML。

提示： 如果页面顶部显示“Advisory checks”，请查看它们——它们会标记常见的错误配置，例如启用了 supportsDeveloperRole 的旧版网关。

工作原理

一个 npm 包，分为两半，通过 dsh plugin add 作为配置文件捆绑包（profile bundle）安装：

- lib/index.js —— 宿主端（host half）：使用 schemastery 注册 model-capability 设置命名空间（语言 + 自定义预设），以便宿主像处理任何原生设置一样对其进行往返处理。
- lib/client.js —— Web 客户端端（web client half）：一个经典脚本捆绑包，通过 Web shell 的模块加载器（window.__ModuleLoader__.load({ id, factory })）注册，与每个随附的 @deepseek-ai 客户端捆绑包完全一样。它向 settings.section 槽位注入一个区块，绑定 llm-pi-ai 和 model-capability 两个设置作用域，并通过 api.settings.mutate 以路径操作和修订围栏驱动所有编辑。
- cordis.patch.yml —— 声明捆绑包行，因此 dsh plugin add 会自动接好整个流程（无需手动编辑补丁）。

llm-pi-ai schema 本身由 DSH 拥有——此插件只编辑其值，因此宿主会继续验证每一次写入（assertServiceable 等）。

开发

pnpm install
npm run build        # esbuild → lib/client.js (loader-wrapped) + lib/index.js

本地测试：创建一个开发配置文件（例如 web-dev），添加 Web 应用和该插件，然后在单独的端口上重启服务器：

dsh plugin --profile web-dev add @deepseek-ai/dsh-web-app@0.1.1-rc.2
add the local package, then note: file: dependencies are snapshotted —
re-add after every rebuild, or replace the installed copy with a junction:
dsh plugin --profile web-dev add file:D:/path/to/dsh-plugin-model-capability
dsh --profile web-dev --port 3091 --no-open

截图使用随附的脚本捕获（需要 playwright-core 和本地 Chrome/Edge）：

node scripts/screenshots.mjs [baseURL] [outDir]
node scripts/verify-dom.mjs  [baseURL]   # shadow-DOM-aware rendering checks
node scripts/e2e-write.mjs   [baseURL]   # end-to-end write smoke test (back up settings.yaml first!)

常见问题 / 故障排除

为什么我的更改没有保存？
DSH 设置服务仅接受来自回环来源的写入（即 http://127.0.0.1:3080 或 http://localhost:3080）。如果你从其他 IP 地址或通过反向代理访问 Web UI，页面上的所有控件都会自动禁用，并显示提示。请通过 localhost 连接以进行更改。

“Safe gateway”预设有什么作用？

它会设置 compat.supportsDeveloperRole=false 和 supportsReasoningEffort=true。这是中国云网关最安全的选择——DashScope（兼容模式）、Moonshot/Kimi、智谱/BigModel、MiniMax、火山引擎 Ark、SiliconFlow、百度千帆，以及其他不接受 OpenAI/Anthropic 方言所发送的 developer 角色消息的网关。

为什么我会看到凭据警告？

该插件会检测提供商路由的 headers 字段中形似凭据的请求头名称（例如 authorization、api-key）。这是一条安全提示，而非阻止——但凭据应以 apiKeyEnv 环境变量引用的形式存储，而不是字面量请求头值，尤其是在保存自定义预设时（预设系统会自动剥离 headers）。

我可以添加新的提供商路由吗？

该插件会编辑 llm-pi-ai 提供商部分中的现有路由。要添加全新的提供商，你仍然需要手动编辑 settings.yaml 或使用 DSH CLI。添加后，该插件会在下次页面加载时识别它。

如何将单个模型重置为默认值？

点击模型行以展开其编辑器，然后清空你想要重置的字段。当每个模型的值留空时，路由级默认值（在路由编辑器中设置）将作为回退值使用。

为什么“Language”设置无法持久保存？

语言选择（model-capability.language）存储在 settings.yaml 中，并且会在重启后保留。如果它不断被重置，请检查设置文件是否可写，以及是否有其他进程正在覆盖它。

为什么在有 6 个思考级别的情况下，thinkingBudgets 只有 minimal/low/medium/high？

这不是 bug——而是刻意的 schema 设计。DSH 的思考能力有两个独立的层级：

1. 思考级别（6 个级别）——由 pi-ai 核心定义：
minimal | low | medium | high | xhigh | max
所有 6 个级别都可以在每个模型的 reasoningEfforts 中配置为对应的线上值。

2. 思考预算（4 个级别）——由 dsh-llm-pi-ai schema 定义：
minimal | low | medium | high
没有 xhigh 或 max 预算字段。

thinkingBudgets 控制基于 token 的提供商（例如 Anthropic/Bedrock）的自定义 token 预算。在运行时，当使用 xhigh 或 max 级别时，系统会回退到默认预算：

const budget = options.thinkingBudgets?.[level] ?? defaultBudgets[options.reasoning];

因此，如果你设置了 thinkingBudgets.minimal/low/medium/high，这些级别会使用你的自定义值，而 xhigh 和 max 会使用提供商的默认 token 分配策略——这些级别不需要自定义预算。

发布
完整的分步说明（包括发布后检查清单）见
PUBLISHING.md。摘要：

- npm publish — 在 npm run build 之后运行（prepublishOnly 钩子会自动重新构建）。该包会发布 lib/、cordis.patch.yml、img/、许可证、英文 README 以及 docs/ 中的中文指南。
- GitHub — 仓库 + 发布；为版本打标签以匹配 package.json。

贡献

欢迎贡献！以下是你可以提供帮助的方式：

- 报告 bug — 提交一个 issue，并附上清晰的描述和复现步骤。
- 建议功能 — 使用功能请求模板。
- 提交拉取请求 — fork 仓库，进行修改，然后打开一个 PR。请遵循现有的代码风格，并在适用的情况下包含测试。

该插件使用 esbuild 构建；修改 src/ 文件后请运行 npm run build。本地测试说明见开发部分。

许可证

MIT