dsh-catalog-refresh：在 DSH 中重建模型目录

DSH 默认使用 @earendil-works/pi-ai 包中的静态模型列表。当 OpenRouter、Fireworks 等提供商发布新模型后，这些新模型不会立即出现在 DSH 的模型选择器和发现探针中，必须等待 pi-ai 包的版本更新。

dsh-catalog-refresh 插件在 DSH 启动时（以及按计划周期）从各提供商的 API 获取实时模型列表，将其转换为 pi-ai 的 Model 条目，并直接修补 harness 的 MODELS 注册表。同时，它通过写入头部触发 dsh-llm-pi-ai 重新解析路由，使模型选择器实时更新，无需重启。

功能¶

自动重建 DSH 运行时的模型目录。
从 OpenRouter、OpenCode Zen、Fireworks、Groq、Together 和 DeepSeek 获取实时模型列表。
修补 DSH 的 pi-ai MODELS 注册表。
通过写入头部使模型选择器实时更新。
支持推理努力级别（CATALOG_REFRESH_EFFORTS）。
处理 Fireworks 推理预算验证。

安装与启用¶

使用官方命令安装插件：

dsh plugin --profile <profile> add dsh-catalog-refresh

配置与环境变量¶

安装后，可通过环境变量控制插件行为：

刷新间隔
设置重新获取列表的时间间隔。

  CATALOG_REFRESH_INTERVAL_HOURS=24

默认值为 12 小时。

推理努力级别
指定重建模型时提供的推理级别，逗号分隔。例如提供 off,low,medium,high。

  CATALOG_REFRESH_EFFORTS=off,low,medium,high

默认值为 off,high,max。

缓存目录
指定获取的列表缓存位置。

  CATALOG_REFRESH_HOME=/path/to/cache

默认为 $DSH_HOME 或 ~/.dsh。

禁用插件
设置为 1 可完全禁用插件。

  CATALOG_REFRESH_DISABLE=1

工作原理与合并规则¶

插件启动时会定位 dsh CLI 进程引用的 @deepseek-ai/dsh-llm-pi-ai 包，进而定位到 @earendil-works/pi-ai 包的 dist/models.generated.js 文件，直接替换其中的 MODELS[provider] 映射，并写入头部触发重新解析。

数据源与认证¶

插件支持以下数据源：
- OpenRouter：完整详情（定价、上下文、最大令牌等）。
- OpenCode Zen、Fireworks、Groq、Together、DeepSeek：仅返回 ID 列表。

认证方式使用环境变量（如 FIREWORKS_API_KEY、GROQ_API_KEY）或 DSH 模型页面存储的凭证记录（llm-pi-ai/<provider>）。如果缺少密钥，该源将被跳过，安装的目录保持不变。

合并策略¶

OpenRouter：实时条目获胜（价格、上下文、最大令牌等），精选字段（兼容性、成本、协议）保留安装条目中的值。
ID 列表源：保留安装条目的精选字段（兼容性、成本、协议、协议），更新结构字段（上下文窗口、最大令牌、名称）。未知 ID 会添加默认值。非聊天条目会被丢弃。

获取的列表会被缓存在 $DSH_HOME/catalog-refresh/ 下，重启即使无网络也能应用上次有效的刷新。

推理努力级别支持¶

dsh-llm-pi-ai 仅在模型声明 effort 元数据时显示推理努力选择器。此插件通过 CATALOG_REFRESH_EFFORTS 配置，为重建的推理模型默认注入 thinkingLevelMap。默认情况下，推理模型提供 Off/High/Max 级别，非推理模型不提供。

对于 ID 列表源，已知 ID 保持安装条目的能力标志，未知 ID 默认视为具有推理能力。Fireworks 的推理模型会通过原生端点路由以避免预算验证错误。

适用场景与注意事项¶

此插件适合需要立即访问最新模型列表的 DSH 用户。

插件以当前 DSH 进程的权限运行，请确保已检查源码与许可证。
插件依赖 @deepseek-ai/cordis 依赖项。

更多信息请参考 GitHub 仓库。