前言¶

在 DeepSeek Harness（DSH）里接 LLM 时，模型列表往往来自安装目录里的 pi-ai 静态 catalog。上游 pi-ai 发布新版本后，新模型不会自动出现在你的路由里；若手工改安装树或 ASAR，升级 DSH 或 pi-ai 时容易冲突，也难以回滚。

下面介绍社区插件 dsh-model-refresh（维护者 KouzakiUmi，分类：模型推理）。它把「从 pi-ai 上游补缺、按 provider 管控、安全写入与回滚」做成可独立升级的 DSH bundle，目标不是把网上所有模型名塞进选择器，而是补齐当前 provider 真正可用、且能正确物化的新模型。插件当前版本 v0.7.2，MIT 许可证；手动模型相关能力对照本机 DSH core 0.2.1-alpha.1 的 configEditor 与 pi-ai 接口开发，其它核心版本需自行核对兼容性。

这是什么¶

dsh-model-refresh 是带 dsh.bundle.patch 的 DSH 插件包，displayName 为「模型目录刷新（pi-ai 上游 → 路由）」。主数据源是 npm 上最新发布的 pi-ai 模型目录；models.dev 仅作可选备份源，默认关闭。自动发现与「是否写入安装目录」分离：首次加载默认不写安装目录，也默认不启用各 provider 的 catalog 写入，需在设置页显式打开。

运行时状态默认位于 ~/.dsh/model-refresh/state.json。真实 API 密钥只应放在环境变量或 DSH credentials 服务中，配置里只填凭据名称。

核心功能¶

自动发现与证据规划¶

1. pi-ai 为主源：启动、定时或手动刷新时查询 npm 最新 pi-ai 版本；仅版本变化时下载并校验官方包完整性与 provider 文件散列。完整 catalog 缓存在状态目录；上游故障时保留旧缓存。
2. 模型与服务可用性分开核对：上游决定候选 ID、协议与能力；可选的 provider 官方清单只提供本套餐「正向存在」证据。GET /models 成功不能证明套餐完整或推理已测通。
3. 不猜字段：协议、上下文容量、输出容量和聊天用途缺少证据的新模型进入待确认，不用邻居数据猜测。
4. 不污染原生目录：已有模型的原生容量、image/reasoning 等不被外部旧数据覆盖；只同步 pi-ai 中同一 provider、同一 model ID 的记录。
5. 删除需负向证据：仅在你明确确认当前套餐为权威全量清单（complete: true）、响应无分页/不完整迹象，且连续缺失确认并过宽限期（默认 24 小时 + 2 次）后，才计划移除。失败、缺 key、部分页会中断连续观察。
6. 写入可选且可审计：catalog 写入默认关闭；启用后使用协调锁、写前 journal、修订指纹和内容所有权校验。回滚需证明当前内容与目录修订均匹配台账记录。

设置页与监控¶

设置页展示发现、已应用、待确认、冲突、是否需要重启消费进程，以及写入权限状态。可按 provider 开关、配置 keep / exclude 名单，并查看代理与全局开关。授权说明在独立弹窗中，插件不代你执行提权命令。

手动增加模型与 DSH 配置编辑¶

在设置页可手动增加模型，配置协议、端点、推理档位与协议兼容参数，通过官方 configEditor 预览、应用和撤销，无需为了试用新模型而改安装目录里的 catalog。

当前可选协议包括 openai-completions、openai-responses、anthropic-messages。同一 provider 须使用相同协议与端点；覆盖已有 provider 时保留原有模型、凭据及其它配置，并将 modelOverrides 合并进模型列表。声明保存在 settings.manualModels，自动发现不会覆盖。

简要流程：

1. 填写 provider 名称、模型 ID、显示名、推理协议、根 URL、上下文与输出容量等，点击 保存模型声明。
2. 选择 DSH 配置入口与目标 provider；凭据栏只填环境变量或 credentials 的名称。
3. 点击 预览配置变更，核对后 应用到 DSH；需要恢复时用 撤销此 provider 的插件变更。

应用只表示配置通过了 DSH 的编辑与加载流程，不表示端点、权限、工具调用或远端推理已经验证。

产物格式¶

启用目录写入后，会在状态目录（或你配置的路径）输出 <route>.models.json、<route>.models.yml、<route>.diff.json，保留原文件名与 models 数组结构。catalog 是 pi-ai 的静态 import，写盘后需重启消费 DSH 的进程才会生效；插件不会自动重启 DSH。

安装与接入¶

仓库是 bundle，推荐通过当前 DSH 版本支持的插件管理入口安装；不要手工改 DSH 核心、ASAR 或包管理器维护的依赖。cordis.patch.yml 只插入 dsh-model-refresh，不会替用户修改 provider 路由。

若从源码做本地链接开发，README 给出的步骤是安装依赖、构建客户端并跑测试，再由目标 profile 的官方插件/本地链接流程加载该目录（详见 GitHub 仓库）。Host 或 bundle 源码变更后通常需要重载对应 DSH 消费进程。

快速配置¶

首次可复制 config.example.json 为本地 config.json，或直接在设置页保存。示例种子配置：

{
  "intervalMinutes": 360,
  "routes": [
    {
      "route": "opencode-go",
      "enabled": false,
      "keep": [],
      "exclude": []
    }
  ]
}

intervalMinutes 控制定时刷新间隔（示例为 360 分钟）。每个 route 可单独 enabled，并用 keep / exclude 约束同步范围。

环境变量¶

目录优先从真实 DSH 消费入口解析 pi-ai；找不到时可设 DSH_PI_AI_DATA_DIR。

每 provider 官方清单（高级）¶

在设置页或 settings.officialRoutes 中配置，例如：

{
  "officialRoutes": {
    "kimi-coding": {
      "endpoint": "https://api.kimi.com/coding/v1/models",
      "apiKeyEnv": "KIMI_CODING_API_KEY",
      "auth": "bearer",
      "protocol": "anthropic-messages",
      "complete": false
    }
  }
}

要点：endpoint 是完整清单 URL，baseUrl 是推理根 URL；complete: false 时可用于正向发现，但不能据此删模型。assumeChat 默认 false，无明确聊天类型元数据的官方新 ID 会进入待确认。

Host 提供 loopback Web API，例如 GET /plugins/dsh-model-refresh/status，以及 POST .../refresh、.../config、.../route（需同源、JSON，请求体有界）。

典型用法（建议顺序）¶

1. 通过 DSH 插件管理入口安装 dsh-model-refresh，重载消费进程使 bundle 生效。
2. 在设置页为需要的 route 启用 provider，按需配置 keep / exclude 与官方清单；确认是否开启 catalog 写入（首次默认关闭）。
3. 执行手动刷新或等待定时任务，在界面查看待确认项并完成人工确认。
4. 若写入安装目录或产物文件，按设置页提示重启加载 pi-ai catalog 的 DSH 进程。
5. 若只需改 DSH 运行时 provider 配置而不动 catalog，使用手动增加模型流程预览并应用；验证失败时先撤销再调整声明。

适用场景与注意¶

适合：希望 pi-ai 上游新模型以可控方式进入 DSH 路由；需要按 provider 开关、待确认 gate、可回滚的目录写入；或希望通过 configEditor 安全地手工加模型而不改 ASAR/安装树。

务必注意：

• 插件以当前 DSH 进程权限运行；安装前请阅读 源码与 README 及 MIT 许可证，自行评估是否满足环境要求。
• 默认不写安装目录、默认停用自动发现的 provider，避免无意扩大写入范围。
• 状态从 v1/v2 迁移到 v3 时会备份旧文件；旧版台账不能证明所有权的历史新增会进入保护列表，不会自动删除。
• 同一安装目录建议只由一个状态实例管理 catalog；更新 pi-ai 时宜停止插件消费者，避免竞态。
• 社区目录页 skillhub.cn 上的条目 与 GitHub 仓库由维护者发布；DSH 生态强调「一切皆插件」，该目录为社区站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-model-refresh 把 pi-ai 静态目录的补缺从「改安装树」拆成可升级的插件：上游以 pi-ai 为准、写入可关、删除有宽限与证据链、手动模型走官方配置编辑。若你正在维护多 provider 的 DSH 部署，可以从设置页的刷新与待确认流程开始，再按需打开 catalog 写入或手动应用配置。

• 目录页：https://www.skillhub.cn/plugins/KouzakiUmi/dsh-model-refresh
• GitHub：https://github.com/KouzakiUmi/dsh-model-refresh