dsh-model-parameters
中文 | English
DSH 插件：当 provider 的模型同步（或任何设置写入）留下缺失能力字段的模型条目时，自动从 models.dev 目录补全——显示名称（display name）、上下文窗口（context window）、最大输出 token、推理档位（reasoning efforts）和输入模态（input modalities）。
大多数 provider 的 /v1/models 列表只披露一个 id，别无其他。本插件用本地缓存的目录补全这些同步模型的元数据，让它们立即可用，并报告补全了什么、哪些无法匹配。
工作原理
- 插件监听
llm-pi-ai 设置命名空间（settings/document-updated）。任何已提交的变更——新同步的 provider、编辑过的 provider 卡片、手动编辑的 profile 补丁——都会触发一次 reconcile。
- 插件启动时还会对现有配置执行一次全量回填。
- 对每个缺少
name / contextWindow / maxTokens / reasoningEfforts / input 任一字段的模型条目，解析出最佳目录条目，只补全缺失字段（fill-only：已有值绝不覆盖）。
- 写入走设置接缝（
ctx.settings.mutate），即落到当前 profile 的补丁文件（~/.dsh/profiles/<profile>/cordis.patch.yml）——与你手动编辑的是同一个文件。
reconcile 天然是 fill-only 的，因此它自己的写入不会造成循环：下一次 settings/document-updated 看到字段已存在，不会产生任何操作。
匹配逻辑
models.dev 把同一模型挂在许多 provider 名下（deepseek-v4-flash 出现在 57 个 provider 下）。解析是确定性的、且 provider 感知：
- Provider 匹配 —— 为 dsh provider 映射的 models.dev provider（显式
providerMap 覆盖，其次同 id）。你的 opencode-go 路由本身也是 models.dev provider，所以它的条目优先。
- 完整 id 精确匹配 —— 已带
vendor/ 前缀的 dsh 模型 id 与完全相同的 models.dev key 匹配。
- 官方 vendor 优先 ——
officialProviders（deepseek、openai、anthropic、google、xai……）在冲突时偏向厂商自己的条目。
- 完整性 —— 两个 limit 都已知的条目优于部分已知的。
- provider id 字母序 —— 稳定的兜底。
裸 id 对最后一段路径段做大小写不敏感匹配，所以 qwen3.7-max 解析到 Qwen/Qwen3.7-Max，kimi-k2.7-code 解析到 Kimi-K2.7-Code。
补全字段
| dsh 字段 | models.dev 来源 | 说明 |
|---|
name | name | 显示名称 |
contextWindow | limit.context | token 数 |
maxTokens | limit.output | token 数 |
reasoningEfforts | reasoning_options[type=effort].values | 恒等字典 {high:"high", max:"max"}；pi-ai 档位之外的取值（default/none/……）被过滤；toggle/budget_tokens 选项忽略 |
input | modalities.input | 过滤到 text/image（pi-ai 仅接受这两种模态；pdf/audio/video 丢弃） |
目录中无匹配的模型（例如本地网关模型 hy3-paid）保持原样，并在补全报告中列为 unmatched。
目录缓存与更新
- 目录从
https://models.dev/api.json 拉取，缓存在 ~/.dsh/model-parameters/catalog.json（约 4 MB）。
- 缓存超过
ttlDays（默认 7 天）后，在下一次 reconcile 时惰性刷新。
- 拉取失败则保留上次成功的缓存；完全没有缓存时插件什么都不补，直到刷新成功。
- 设置卡片有 立即更新目录并补全 按钮可强制刷新，并显示上次更新时间与新鲜度。
系统代理
目录下载遵循代理设置（包括 Windows）：
- 设置了
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY（大小写均可）时，沿用 DSH 宿主的全局代理策略——与插件其他出站请求走同一条路由。
- 没有设置这些变量时，自动读取操作系统代理：Windows 的 Internet 选项（注册表
Internet Settings 中的 ProxyEnable / ProxyServer / ProxyOverride），macOS 网络设置里的手动 HTTP/HTTPS 代理与排除列表。
- 两者都没有时直连。
- 设置页「模型目录」会显示最近一次下载的 下载经由：直连 / 环境变量代理 / Windows 系统代理 / macOS 系统代理（代理地址已脱敏）；下载失败时一并显示错误。
- 限制：SOCKS 代理与 PAC 脚本不会被求值（只配置了 PAC 时保持直连并告警，可改用
HTTPS_PROXY 显式指定）；CIDR 形式的绕过条目（如 10.0.0.0/8）不匹配；系统凭据管理器保存的代理密码不会发送。
设置卡片
在 DSH 设置 → 插件 → 插件配置 中会出现一张 "模型参数补全 / Model Parameters" 可展开卡片（样式与内置插件卡片一致，默认折叠）：
模型参数补全设置卡片
- 总开关 + 逐字段开关（
fillName、fillContext、fillMaxTokens、fillReasoning、fillInput）；
- 目录 TTL（天）；
- 可选的
provider → models.dev provider 映射覆盖；
- 目录新鲜度（条目数、provider 数、上次更新）；
- 上次补全报告：补全的字段、涉及的 provider、未匹配的模型 id 列表。
插件配置就是它自己的 loader entry config——当前 profile 补丁文件里的 model-parameters 条目，例如：
- id: model-parameters
config:
enabled: true
ttlDays: 7
fillName: true
fillContext: true
fillMaxTokens: true
fillReasoning: true
fillInput: true
providerMap: {}
officialProviders:
- deepseek
- openai
- anthropic
- google
- xai
安装
通过 dsh plugin 命令安装（web 换成你的 profile 名）：
从 npm 安装：
dsh plugin --profile web add @fonlan/dsh-model-parameters
直接从 GitHub 安装：
dsh plugin --profile web add github:fonlan/dsh-model-parameters
卸载：
dsh plugin --profile web remove @fonlan/dsh-model-parameters
开发
pnpm install
pnpm build # tsc 类型 + tsdown host 与 client bundle
pnpm typecheck
pnpm test # 构建后校验系统代理探测、路由选择与 CONNECT 隧道（scripts/verify-proxy.mjs）
node scripts/verify-catalog.mjs # 用 models.dev dump 校验匹配逻辑
发布
打 tag 自动发布到 npm（GitHub Actions Publish to npm，校验 tag 与 package.json 版本一致后执行 npm publish，需仓库配置 NPM_TOKEN secret）：
npm run release:patch # npm version patch && git push && git push --tags
npm run release:minor
npm run release:major
License
MIT
