NOirBRight/dsh-llm-providers-ui

English | 中文

DeepSeek Harness LLM Providers 设置页的挂载 owner。

兼容性

宿主 @deepseek-ai/dsh-* 不锁定发行号：peer 为 * 且 optional。devDependencies 钉编译目标（0.1.5-rc.1）。Cordis 保持 >=4.0.2 <5.0.0。

package.json#dsh.compatibility.dshReleases 里的已验证宿主是证据，不是允许列表。未知的新宿主告警一次后仍按正常路径挂载。只有复现过的故障才会加入 blocklist。

Ownership

• Host 拥有 llm-providers 设置命名空间 { order: string[] }（唯一写者）。卸载 owner 会删除该命名空间；重装后重建。各 provider 的 llm 路由相互独立，因此缺 owner 时 provider 在 Host 侧照常工作。
• Web（client）拥有 settings.section 的 id: providers（order 12）及子项 settings.provider.item（keyed、root）、locale settings.providers 和导航图标。section 与子项声明只在 Host 侧 llm-providers scope 就绪后挂载；provider 插件只通过 settings.provider.item 贡献自己 keyed 的卡片。

加载顺序无关紧要。卸载某个 provider 只移除它的卡片。卸载/重装 owner 不会损坏 provider 的 Host 服务；owner 回来后卡片经公共 slot 生命周期重新出现。

缺失 owner

• 无 owner 的 Headless/Host：模型路由照常工作。
• 无 owner 的 Web：Providers 页及其卡片被省略；provider Host 路由保持在线。开发期间浏览器控制台会打一条 owner-unavailable 警告；owner 就绪后，另一条 settings.section 警告用于标识缺失的 Web 设置壳。

导航图标

导航行上的 14px 地球 glyph 是隔离的临时适配器（src/client/nav-icon.ts）。DSH 的 settings.section 没有 icon 字段，因此该文件经 MutationObserver + rAF 给 DOM 打补丁。它幂等且只归这里所有——不要复制到 provider 插件里。DSH 暴露公共图标 seam 后替换该文件。

Exports

• dsh-llm-providers-ui（Host）：applySavedOrder、decodeProviderOrder、sortCatalogGroups、PROVIDER_ITEM_ORDER 等。构建产物：lib/index.js + lib/types。
• dsh-llm-providers-ui/order（纯函数，ESM）：同一套 order helper，供 dsh-model-switch 与 provider picker 使用的稳定构建产物。构建产物：lib/order.js + lib/types/order.d.ts。provider 插件 alwaysBundle 该构建产物；不要从 src import。
• dsh-llm-providers-ui/sortable（client 工具，ESM）：SortableList 拖拽排序实现。构建产物：lib/sortable.js + lib/types/sortable.d.ts。唯一实现在 src/client/SortableList.tsx，此处 re-export；provider 插件 alwaysBundle 该构建文件。不要从 src/client/SortableList.tsx import。
• dsh-llm-providers-ui/provider-ui（client 工具，ESM）：共享 ProviderCardHeader、ProviderQuotaMeter、normalizeQuotaRemaining、providerUiCss，以及卡片头部与共享额度缓存的绑定 useProviderQuotaCache（含 ProviderAuthState 判定）。构建产物：lib/provider-ui.js + lib/types/provider-ui.d.ts。唯一实现在 src/client/provider-ui.tsx，此处 re-export；provider 插件 alwaysBundle 该构建文件。不要从 src/client/provider-ui.tsx import。
• dsh-llm-providers-ui/client（Web）：owner 插件接线与 providerDirectory Cordis service 声明。构建产物：lib/client.js（ModuleLoader CJS）+ lib/types/client；只导出插件入口。不要 import ./src/*。
• dsh-llm-providers-ui/model-catalog（client 工具，ESM）：ModelCatalogEditor、ModelPickerDialog、applyCatalogPatch 与目录布局辅助。构建产物：lib/model-catalog.js + lib/types/model-catalog.d.ts。provider 插件应 alwaysBundle 此导出，不要从 src/client import。
• dsh-llm-providers-ui/usage-readers（纯 ESM）：供 provider client bundle 使用的 ProviderUsageReader 类型与各 vendor 的 create*UsageReader 工厂。构建产物：lib/usage-readers.js + lib/types/usage-readers.d.ts。provider 插件应 alwaysBundle 此导出。

本包只暴露上面列出的构建后 lib/ 入口；调用方应 import 这些包导出，而非源码路径。

安装

本包是必须显式安装的 bundle。在 DSH 第三方 bundle 支持传递自动挂载之前，profile 必须把 dsh-llm-providers-ui 和 provider 插件一起列出（例如 ~/.dsh-lab/profiles/web/package.json 的 dsh.profile.bundles 与 dependencies）。与 provider 之间没有严格的加载顺序要求。见 cordis.patch.yml。

Consumer contract

provider 插件以自己的 settingsNs key 在 settings.provider.item 下注册卡片，并在 effect 内向 ctx.providerDirectory 注册 { key, role, header, usage }； disposer 负责注销。需要 Usage 的 provider 从 dsh-llm-providers-ui/usage-readers 导入对应 reader 工厂。 已迁移的卡片使用 dsh-llm-providers-ui/provider-ui 的共享 header（ProviderCardHeader，role、调用方 status 与头条 quota；title/mark/summary/open/unsaved 保持旧 codex 布局），根节点标记 li[data-provider-card][data-provider-role]、header 按钮标记 data-provider-card-header、正文标记 data-provider-body，引入一份 <style>{providerUiCss}</style>，并声明 header: 'shared' 让外壳去掉兜底 badge。缺失额度不渲染 meter，绝不画成零；normalizeQuotaRemaining 保留精度，NaN/Infinity/越界一律视为不可用。 provider 插件用 import type {} 从 dsh-llm-providers-ui/client 导入 directory 与 slot 类型，不得在本地重复 module augmentation。退出登录或切换账户后，provider 调用 ctx.providerDirectory.invalidateUsage(key) 让侧栏丢弃缓存额度并重查；短暂读取失败仍把上次可用窗口标为过期展示。 dsh-model-switch 经构建产物 dsh-llm-providers-ui/order 复用 sortCatalogGroups。

在 npm 发布之前，lab checkout 在开发时可用 link:../dsh-llm-providers-ui，但工作区 package.json 不得提交 link: spec。

Release 安装（Latest）

共享的 LLM Providers 设置页、导航、卡片排序与 picker 排序 owner。发布包只含构建后的 Host/Client 文件，没有 sibling 仓库源码、工作站路径、link: 或 workspace: 依赖。打包夹具与编译目标 devDependencies 为 0.1.5-rc.1。

Latest 安装（URL 永不带版本号）：

dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.8.tgz

固定版本安装（v0.2.8）：

dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.8/dsh-llm-providers-ui-0.2.8.tgz

更新、卸载与验证：

# 更新到 Latest
dsh plugin --profile web add --force \
  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.8.tgz
# 验证加载与版本
dsh plugin --profile web list
dsh plugin --profile web doctor
# 只卸载本插件
dsh plugin --profile web remove dsh-llm-providers-ui

配置：Web UI 插件用 Settings 里的插件区，纯 Host 插件用 profile 的 dsh.profile.bundles 条目。从本 README 的最小 YAML/JSON 示例起步，凭据/后端地址显式给出。

回滚：重跑上面的固定 v0.2.8 命令（或之前记录的不可变 tarball），核对 profile 列表，然后重启一次 Web 服务。检查 journalctl --user -u dsh-web.service 与 dsh plugin --profile web doctor；绝不在生产 profile 里放源码 checkout。

Release 与完整性随 GitHub Release 发布，不锁定某一 Host 发行号。

Codex 额度读取会明确请求后台刷新；手动刷新与缓存过期轮询的缓存策略统一由界面存储层控制。

实验实例页面检查

在隔离 Chrome 中登录现有 3082 实验实例并开放 CDP 9229 后，运行 node scripts/check-lab-settings.mjs。检查覆盖七个真实 Provider、品牌和角色图标，以及 1280／390／320 宽度下的深浅色布局和展开的 Antigravity。检查会恢复原主题，不修改 Provider 认证或配置，截图写入 /tmp/lab-*.png；不会启动替代应用服务器。