dsh-workbuddy2api-hub：把本地 workbuddy2api-hub 接进 DSH

前言¶

DSH（DeepSeek Harness）采用「一切皆插件」的理念，本地智能体开发者经常需要把跑在本地的模型网关接入桌面端。hima6652/dsh-workbuddy2api-hub 就是这样一个插件，它的作用是把本地运行的 workbuddy2api-hub 接进 DSH 桌面端，让 hub 上的模型出现在 DSH 的模型列表里，并在侧边栏显示积分余额和用量。

在此之前，如果要接本地 hub，需要手动配置 provider、复制凭据、手动同步模型，流程繁琐且容易出错。这个插件把整个流程自动化：配置一次连接，之后模型自动同步、余额自动刷新、用量自动统计。

安装¶

前置条件：

Node.js ≥ 20
本地 workbuddy2api-hub 已经跑起来，浏览器能打开 http://127.0.0.1:8788
DSH 桌面端能正常打开

最快的方式是从 npm 安装（装进 profile，不用 clone）：

cd ~/.dsh/profiles/desktop
npm i dsh-workbuddy2api-hub

重启 DSH 桌面端。

也可以使用仓库里的安装脚本（会同时登记 dsh.profile.bundles）：

# 1. 克隆到任意目录
git clone https://github.com/HimA6652/dsh-workbuddy2api-hub.git
cd dsh-workbuddy2api-hub

# 2. 先确认 hub 通不通（只读，不改任何东西）
node scripts/smoke-live.mjs

# 3. 挂进桌面端 profile（默认 ~/.dsh/profiles/desktop）
node scripts/install-local.mjs

# 4. 重启 DSH 桌面端

DSH CLI 机器上也可以直接从 GitHub 拉：

dsh plugin --profile desktop add github:HimA6652/dsh-workbuddy2api-hub

配置与连接¶

改 profile 的 cordis.patch.yml（或本仓库的 cordis.patch.yml 作为默认值）。只改配置就能换地址/密码，不用改代码：

- id: workbuddy-hub
  name: dsh-workbuddy2api-hub
  config:
    baseUrl: http://127.0.0.1:8788   # 换机器就改成 http://192.168.1.10:8788
    pwd: admin                        # 面板密码
    tab: gateway                      # 打开看板时落在哪个页签

配置项说明：

配置	默认	说明
baseUrl	http://127.0.0.1:8788	服务地址。从浏览器地址栏整条粘进来也行（?pwd=…&tab=… 会被剥掉），缺协议自动补 http://
pwd	admin	面板密码。只用于换 Token，不会被当成 API Key
tab	gateway	深链页签，白名单外的值退回 gateway
apiKey	空	可选。写了就存进 DSH 凭据库（引用名见 apiKeyEnv），不落状态文件
apiKeyEnv	WORKBUDDY2API_HUB_API_KEY	DSH 凭据库里的引用名
providerEntry	llm-pi-ai	写到哪个 settings 的 ns 下
routeKey	workbuddy2api-hub	写进 providers.。故意不叫 wb，免得覆盖你已有的路由
maxKeys	10	最多同步几条网关 key（1–50）。超出的只读不写，避免一次刷出几十个 provider
intervalSeconds	120	轮询间隔，下限 30、上限 3600；连续失败会指数退避到 30 分钟
sync	true	关掉就只看数据、不写模型
autoApiKey	true	缺 Key 时是否允许从面板 /settings/reveal 自动取
newModelPolicy	select	hub 上新出的模型默认勾选还是先不写
retireHours	24	模型下架后的宽限期
thresholds.lowCredits	100	余额低于它就告警；0 关掉
thresholds.unreachablePolls	5	连续失败几次才报「连不上」
stateDir	空	状态文件目录。默认跟 profile 同级（workbuddy2api-hub.json）

重启后：设置 → workbuddy2api-hub → 确认地址/密码 → 「测试连接」→「立即同步」→ 模型出现在设置 → 模型里，provider 名 workbuddy2api-hub。

模型同步与多 key 管理¶

插件会把 /v1/models 写进 llm-pi-ai 的 providers.workbuddy2api-hub，每个模型带上 contextWindow / maxTokens / 图片输入 / 思考档位。模型名后面直接带网关的倍率（如 GLM-5.1 ×0.79），免费模型标 Free——倍率写不进名字，选择器里就看不见。

网关里有几条 API Key 就同步几条 provider（一 key 一条路由、一条凭据）。主 key 固定 workbuddy2api-hub，其余 workbuddy2api-hub-<名字>。每条 key 每轮都拉模型清单（实测与绑定账号数无关），设置页里各自一份模型开关，模型多的那几条默认收起，点卡片头上那行「账号 N · 模型 6/19」展开。

一个 key ↔ 一条 provider 路由 ↔ 一条凭据引用。路由键建好就不再变（主 key 恒 workbuddy2api-hub，其余 workbuddy2api-hub-<名字>），所以网关里改 key 的名字、换倍率，都不会让会话里已经选中的模型消失。网关里删掉某条 key → 那条路由自动撤掉；删掉的是主 key → 徽标显示「主 key 已删除」、会话提示重新选模型，不会拿别的 key 偷偷顶替。

余额与用量¶

余额与用量来自 /v1/balance-summary 的 credit 余额，以及 /usage?range=today 的请求数 / 失败数 / tokens / credit / API 等价花费 / 缓存命中。每条 key 的余额由后端拿 /accounts 里这条 key 绑定的账号 credits.remain 求和得出（纯内存，不额外发请求）；账号没出现在 /accounts 里时该 key 的余额是 null，不报 0。

侧边栏徽标展开态三行——第一行「当前会话那条 key 的名字 + 该 key 余额 / 整域余额」，第二行今日，第三行本周，右半边是 tokens / 积分 / 等价三列、等宽右对齐。收起态是一个 36×36 圆形图标。数字跟着当前会话用的那条 key 走：会话选的是 key-c 的模型，第一行的名字、余额和第二、三行的用量就都换成 key-c 的，切会话自动切，且不为此多发一个请求（余额是后端拿 /accounts 在本地按 key 绑定的账号求和）；会话用的不是网关模型时回落到主 key。

点一下徽标出副窗：贴着徽标上沿弹出，内容是「各 key 用量」表（列标题 tokens / 积分 / 等价，每条 key 一段「名字 + 账号 N」再跟今日、本周两行，末尾总计），上面两个格子是「这条 key 的余额」与「全部账号」，底部「打开面板」「关闭」，点遮罩或右上角 × 关闭。所有数字两位小数（72.30M、¥10.39、2841.06），数字全是网关原样给的——每条 key 的用量来自 /usage/analytics 的按 API Key 分组，总计来自 /usage 的整域汇总。

错误处理与容错¶

插件对各种失败都有处理：

情况	面板上看到的	处理方式
服务没开 / 端口不通	连不上 hub（fetch failed）：确认本地服务已启动（默认 http://127.0.0.1:8788）	冷启动 60 秒内每 15 秒重试，之后指数退避
8 秒没响应	连不上 hub（请求超时）	同上
密码错	面板密码不对	出 auth 告警，不反复猛撞
60 秒内错 5 次	面板登录被限流，N 秒后再试	轮询间隔抬到 hub 建议的等待时间以上
404	服务版本可能与本插件不匹配（HTTP 404）	—
5xx	hub 内部错误（HTTP 500）	—
返回 HTML	返回了非 JSON 内容	—
缺 API Key	还没有可用的 hub API Key，暂不写入模型	出 api-key 告警，不写注定 401 的路由

模型下架先进宽限期（默认 24 小时，可一键立即移除），回来能复活；内容没变就不写配置，避免每次轮询都触发一次配置更新；配置冲突自动重取 revision 重试。/state 永远返回 200，前端永远有东西可渲染。

安全与隐私¶

API Key 只进 DSH 凭据库和内存，绝不写状态文件，也绝不出现在 /state 里（连掩码都不给）。面板密码会存进 profile 的状态文件 workbuddy2api-hub.json（明文，重启后要靠它继续登录）。它只是 hub 的面板密码，不等于 API Key；如果你的 hub 用了别的重要密码，建议给面板单独设一个。

写接口有三道闸：只接受本机来源（127.0.0.1 / ::1 / ::ffff:127.0.0.1）、sec-fetch-site 必须是 same-origin 或 none 且 Origin 与 Host 一致、content-type 必须是 JSON。响应不带任何 CORS 头——这样同机网页用 no-cors 的简单请求也打不进写接口。

插件接口¶

宿主侧注册一个前缀路由 /workbuddy2api-hub/api：

方法	路径	说明
GET	/state	全量快照（带 ETag，前端用 If-None-Match 拿 304）
GET	/usage?range=today	只刷用量（range 取 today / week / month / all）
GET	/accounts	只刷账号
GET	/dashboard-url	看板深链（只带 tab，密码永远不进 URL），只给本机
POST	/config	改地址 / 密码 / 页签 / 间隔 / API Key
POST	/selection /bulk /enable-new	勾选模型、全选/全不选、新模型默认策略（带 hubKeyId 就只作用于那条 key）
POST	/keys/pull	立刻重拉某条 key 的模型（排障用，60 秒节流）
POST	/keys/selection /keys/sync-selection	单独改某条 key 的勾选 / 把一条 key 的勾选同步到别的 key
POST	/keys/main	指定哪条 key 是主 key（只换身份，不改它已有的路由键）
POST	/refresh /test /policy /dismiss /retire /clear	同步、探测、策略、消警、立即移除、清空同步

适用场景¶

这个插件适合需要在 DSH 中使用本地 workbuddy2api-hub 的开发者。使用前应检查源码与许可证，确保符合你的使用场景。