前言¶

在使用 DeepSeek Harness (DSH) 时，大多数 provider 的 /v1/models 接口仅返回模型 ID，缺少 name、contextWindow、maxTokens、reasoningEfforts 和 input 等关键能力字段。这导致模型列表显示不完整，增加了手动配置的负担。本插件旨在解决这一痛点，通过读取本地缓存的 models.dev 目录，自动补全这些缺失字段。

介绍¶

dsh-model-parameters 是一个 DSH 插件，用于在设置写入（包括模型同步）时，检测并补全缺失的模型元数据。它由 fonlan 维护，遵循 MIT 许可证。

核心功能¶

• 自动补全元数据：自动从 models.dev 目录获取并填充显示名称、上下文窗口、最大输出 token、推理档位和输入模态。
• 智能触发机制：监听 settings/updated 命名空间。任何设置变更（如新同步 provider、编辑 provider 卡片、手动编辑 settings.yaml）都会触发 reconcile。插件启动时也会对现有配置执行一次全量回填。
• 确定性匹配逻辑：支持 Provider 映射（providerMap）、精确 ID 匹配、官方优先级（officialProviders）。对于裸 ID，支持对最后一段路径段做大小写不敏感匹配。
• 填充式更新：只补全缺失字段，绝不覆盖已有的值。reconcile 天然是 fill-only 的，不会造成循环写入。
• 设置卡片与刷新：提供可视化的配置界面，包括总开关、逐字段开关、TTL 配置、目录刷新按钮以及补全报告。

匹配逻辑¶

插件在匹配 models.dev 目录条目时，遵循以下优先级：
1. Provider 映射：优先使用显式的 providerMap，其次同 ID 匹配。
2. 完整 ID 精确匹配：已带 vendor/ 前缀的 dsh 模型 ID 与完全相同的 models.dev key 匹配。
3. 官方优先级：在冲突时，优先选择 officialProviders（如 deepseek、openai、anthropic 等）的条目。
4. 完整性：两个 limit 都已知的条目优于部分已知的。
5. Provider ID 字母序：作为稳定的兜底策略。
裸 ID（如 qwen3.7-max）会对最后一段路径段做大小写不敏感匹配（如 Qwen/Qwen3.7-Max）。

补全字段¶

插件会将 models.dev 的以下字段映射到 DSH 模型配置：
* name：对应 models.dev 的 name。
* contextWindow：对应 limit.context。
* maxTokens：对应 limit.output。
* reasoningEfforts：对应 reasoning_options[type=effort].values，过滤为恒等字典（如 {high:"high", max:"max"}）。
* input：对应 modalities.input，过滤为 text 或 image。

目录缓存与更新¶

• 缓存位置：~/.dsh/model-parameters/catalog.json（约 4 MB）。
• 更新机制：默认缓存 TTL 为 7 天。超过 TTL 后，下一次 reconcile 时惰性刷新。
• 容错策略：拉取失败时保留上次成功的缓存；完全没有缓存时插件不执行补全，直到刷新成功。
• 手动刷新：设置卡片提供“立即更新目录并补全”按钮，可强制刷新并显示上次更新时间与新鲜度。

安装与启用¶

通过 dsh plugin 命令安装（请将 --profile web 替换为你的实际 profile 名）：

dsh plugin --profile web add @fonlan/dsh-model-parameters

安装后，在 DSH 设置 → 插件 → 插件配置 中，展开“模型参数补全 / Model Parameters”卡片进行配置。

适用场景与注意¶

• 适用场景：provider 列表信息不全，需要依赖 models.dev 目录获取元数据的场景。
• 权限注意：插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证（MIT）。
• 行为注意：补全是填充式（fill-only），不会覆盖已存在的值；目录中无匹配的模型（如本地网关模型）保持原样，并在补全报告中列为 unmatched。

结语¶

该插件通过自动化元数据补全，降低了智能体开发的配置门槛。更多详情与源码可查看 GitHub 仓库。