前言¶
在 DSH 里选 provider、换模型时，列表里经常出现和路由 ID 几乎一样的字符串：分组标题、设置页里的「配置提供方」、模型下拉项都混在一起，可读性很差。若在 Cordis patch 或 config 里逐条改显示名，还要面对 llm-pi-ai 里 models 整体替换、modelOverrides 与 models 互斥、以及部分内置路由 provider 名硬编码等限制，维护成本偏高。
下面介绍社区插件 dsh-model-names（维护者 KouzakiUmi，分类：客户端）。它用一份全量命名数据库，在载入时按当前环境里实际存在的 provider 与模型改写 UI 上的展示字符串，不动模型 ID、路由、凭据与请求体。
这是什么¶
dsh-model-names 是 DSH 客户端侧插件：内置 provider / 模型显示名的映射数据，运行时包装 ctx.llm 的目录读取方法，只影响用户看到的名称。
- 改的是「用户看到的」provider / 模型显示名。
- 不改 config、不改 patch 里的路由与模型定义、不改发出的 LLM 请求。
社区目录页：KouzakiUmi/dsh-model-names。源码与说明：GitHub - KouzakiUmi/dsh-model-names。
核心机制¶
插件主要由三部分组成（见仓库 README）：
data/model-names.json：全量命名数据库。由scripts/build-catalog.mjs从宿主内置的 pi-ai provider / model 目录生成，并合并 DSH 自带路由；sourceVersion记录上游目录版本。条目是模型 ID 与可读显示名的映射，随上游目录更新，文档不固定数量。lib/index.js：载入时包装ctx.llm的目录读取，仅对当前环境里已有的 provider 与模型做映射：
| 被包装的方法 | 改写的展示字段 | 影响面 |
|---|---|---|
listProviders() |
provider.name |
模型选择器里的 provider 分组标题 |
listConfigurableProviders() |
displayName |
设置页「配置提供方」 |
listModels(provider) |
model.name |
模型选择器 / 设置页的模型列表 |
数据库里没有的 id 原样返回；未启用的 provider 不会被激活（本来就不在目录里）。路由 id、凭据、模型集合、请求与会话记录都不受影响。
cordis.patch.yml：只insert本插件自己一行，不写任何 provider / 模型配置。
为什么不在 patch 里改名¶
README 说明：llm-pi-ai 的 models 是整体替换（会收窄模型集合、丢掉未照抄的默认值）；modelOverrides 只对已在 config 里声明的路由生效，且与 models 互斥；内置 DeepSeek 两条路由的 provider 显示名更是硬编码，config schema 里没有对应字段。显示层映射绕开这些限制，也免去为每条路由单独维护 config。
边界与行为¶
dsh-codex-connect的模型名、内置 DeepSeek 两条路由的 provider 名：若数据库有对应条目会被映射。codex 若走自己 RPC 报告的目录、且不经过ctx.llm.listModels，则此处覆盖不到。- 搜索、选择、提交仍按 id 进行，只改展示字符串。
命名数据库如何更新¶
仓库 .github/workflows/update-catalog.yml 每周一 02:13 UTC 检查 npm 上最新的 @earendil-works/pi-ai，也可在 Actions 里手动运行并指定精确版本。工作流下载该版本包、读取 provider / model 目录；对新增且上游缺名或名称仍等于 ID 的条目，可调用配置的 OpenAI-compatible Chat Completions API 生成候选名。已有人工命名会在上游仍缺名或名称仍为 ID 时保留。
工作流只创建 automation/update-provider-model-catalog 分支和 PR，不直接改主分支或发 Release。除配置变量与 Secret 外，需在仓库 Settings → Actions → General 允许 GitHub Actions 创建 Pull Request。
| 名称 | 类型 | 内容 |
|---|---|---|
MODEL_API_URL |
Variable | 完整 Chat Completions URL，例如 https://api.example/v1/chat/completions |
MODEL_API_MODEL |
Variable | 服务商支持的模型 ID |
MODEL_API_KEY |
Secret | 模型 API 密钥 |
API 需返回 OpenAI-compatible 格式，且在 choices[0].message.content 中为 JSON：{"items":[{"key":"provider:example","name":"Example Provider"}]}。工作流会拒绝缺失、重复、额外或仍等于 ID 的结果；API 失败时不创建更新 PR。若某次上游更新没有未命名条目，构建不需要模型 API；首次运行会处理数据库里仍等于 ID 的条目，因此应先配好上述三项。
手动改字与本地重建¶
- 在
scripts/build-catalog.mjs维护PROVIDER_DISPLAY_NAMES/EXCEPTIONS，避免直接改自动生成的data/model-names.json。 - 本地重建：
node scripts/build-catalog.mjs --pi-ai <pi-ai 包目录>
--enrich 会用环境变量里的模型 API 为未命名条目生成候选名；--check 比较并在过期时以非零状态退出。
- 审核生成结果后再提交。插件数据库变更后需重启 DSH NEXT（Host 插件代码/数据变更不热加载）。
安装与启用¶
从 npm 安装（命令来自仓库 README）：
dsh plugin --profile <profile> add dsh-model-names
版本标签触发的发布 CI 会校验并构建安装包，同时发布到 GitHub Release 和 npm。
若使用本地插件目录，README 还给出了：
dsh plugin add <插件目录绝对路径>
安装前建议自行查看源码与许可证（package.json 中为 MIT）。插件在当前 dsh 进程权限下运行，与任何社区插件一样，启用前应确认其只做 UI 层展示映射、符合你的安全预期。
典型用法¶
对最终用户而言，安装并重启 DSH NEXT 后无需额外配置：打开模型选择器或设置里的 provider / 模型列表，即可看到数据库覆盖后的可读名称；未在库中的 id 仍显示原样，行为与 README 描述一致。
维护者或贡献者若需修正显示名或跟进上游 pi-ai，按上一节在 build-catalog.mjs 里维护例外并重建 catalog，或通过仓库 Actions 与 PR 流程更新 model-names.json。
适用场景¶
- 希望模型选择器、设置页 provider 分组与模型列表统一、可读，又不想动路由与请求。
- 接受「只改展示、id 不变」的边界，且了解 codex 等特殊路径可能不完全走同一套
listModels包装。
不适合指望通过本插件改模型 ID、增删路由、改凭据或 patch 里模型集合的场景——这些都不在插件设计范围内。
结尾¶
dsh-model-names 用全量映射 + 运行时包装 ctx.llm 目录 API，在 DSH 客户端侧统一 provider / 模型的显示名，避开 patch/config 改名的结构性限制，且明确不动路由与请求。需要安装命令与边界说明时，以 README 为准。
