前言¶

在 DSH（DeepSeek Harness）里用小鲸鱼挂件看各模型余额时，团队常用的 New API（或 One API 兼容）中转站往往不在默认注册表里。自己改 dsh-whale-widget 源码不现实——它是 npm 包，升级会被覆盖。另一种做法是手改 $DSH_HOME/.dshw-api.json 并自己找余额接口，端口和鉴权一换就要再维护一遍。

下面介绍社区插件 dsh-whale-newapi-bridge（维护者 zuaonew-ops）：在 DSH 设置页配置中转站，由宿主在本机提供余额桥，并自动维护挂件模型条目，让小鲸鱼里出现「团队中转站」余额与「今日已用」记账。

这是什么¶

dsh-whale-newapi-bridge 是 host-only 的 DSH bundle（当前版本 0.2.0，MIT 许可）。它不把逻辑塞进小鲸鱼包，而是使用挂件已文档化的扩展面：注册表条目 + 自定义余额 URL。

插件在宿主进程注册 6 条本机回环路由，在 DSH 设置 →「中转站」 增加配置页，并定期 upsert id = newapi_relay 的模型条目到 $DSH_HOME/.dshw-api.json。其它模型与 usage 账本原样保留；上游失败时不改写注册表。

分类上属于 DSH 社区目录的「联网工具」；与 DeepSeek / 幻方无官方从属，安装前请自行审阅 GitHub 源码 与许可证。插件以当前 DSH 宿主进程权限运行。

核心功能¶

设置页与热生效¶

在设置里填写中转站根地址、凭据引用名、挂件显示名、同步间隔等（共 16 项，保存时逐键校验）。保存后立即热生效，写入 $DSH_HOME/whale-newapi-bridge-settings.json（Windows 为 %USERPROFILE%\.dsh\whale-newapi-bridge-settings.json）。优先级为：设置文件 > cordis.patch.yml > 内置默认。

本机余额桥¶

GET /dsh-whale-newapi/balance 把上游余额归一化为稳定 JSON，供挂件拉取。鉴权要求 Authorization: Bearer <凭据值> 与 DSH 凭据服务解析结果一致；路由仅接受回环 Host，并拒绝跨站 Sec-Fetch-Site。

鉴权与余额模式¶

按 key 形态自动尝试两种上游：系统访问令牌（nap_ 等，走 /api/user/self，可显示数字余额）与 sk- 渠道 key（走 /v1/dashboard/billing/*，兼容旧站，多数情况为 events 模式、余额显示「—」）。authMode 可设为 auto / native / compat。

同步与诊断¶

启动时同步，之后按 syncIntervalSeconds（默认 300 秒）周期同步。GET /dsh-whale-newapi/status 可查看配置来源、脱敏凭据、上游响应与警告；设置页顶部约每 5 秒刷新状态摘要。

前置条件¶

1. DSH >= 0.2.0-rc.1（credentials 服务、Web 路由、settings.section 插槽）。
2. 小鲸鱼挂件 dsh-whale-widget >= 0.4.2 已安装并启用。
3. 可访问的 New API 站点；推荐在凭据里配置系统访问令牌（站点后台「个人设置 → 系统访问令牌」）。

安装与启用¶

1. 安装 bundle¶

dsh plugin --profile desktop add github:zuaonew-ops/dsh-whale-newapi-bridge

desktop 按实际 profile 替换。固定版本可钉住提交：github:zuaonew-ops/dsh-whale-newapi-bridge#<commit-sha>。卸载：

dsh plugin --profile desktop remove dsh-whale-newapi-bridge

安装会把声明了 dsh.bundle 的插件写入 profile 的 dsh.profile.bundles。安装或卸载后需重启宿主；仅改设置页配置则热生效，无需重启。

2. 写入凭据¶

在 %USERPROFILE%\.dsh\.credentials.yaml 的 refs: 段增加（缩进两个空格，值不加引号）：

refs:
  NEWAPI_RELAY_TOKEN: <你的系统访问令牌>

默认 credentialRef 为 NEWAPI_RELAY_TOKEN；解析不到时会按 credentialCandidates 顺序尝试。改凭据不需重启宿主。

3. 在设置页填中转站¶

重启宿主后打开 设置 →「中转站」：

1. 「中转站地址」填站点根 URL（例如 https://relay.example.com，不要带 /api 后缀）。
2. 按需调整币种、同步间隔、条目显示名等。
3. 点「保存」，提示「已保存并热生效」后即可使用。

无头或多机统一部署基线时，可在 <profile>/cordis.patch.yml 追加（id / name 与 bundle 声明一致）：

- id: whale-newapi-bridge
  name: dsh-whale-newapi-bridge
  config:
    baseUrl: https://relay.example.com
    currency: CNY
    autoSync: true
    syncIntervalSeconds: 300

设置页保存的同名字段会覆盖 yml 中的值。

4. 在挂件里添加余额模块¶

浏览器中刷新 DSH 页面（挂件泡泡配置仅在加载时读取一次）。在挂件面板 → 泡泡 → 添加「余额」→ 模型选 「团队中转站」。插件会在同步时按宿主实时端口写入该条目的 balance.url，不要手改端口。

典型配置要点¶

币种换算依赖站点 /api/status 的 quota_per_unit 与 usd_exchange_rate（配置为 0 时表示跟站点）。细节见仓库 README 的「币种口径」一节。

适用场景与注意¶

适合谁：已在 DSH 桌面或自建 profile 使用小鲸鱼挂件，且 API 流量走自建或团队 New API / One API 兼容中转站的开发者。

务必注意：

• 凭据明文只应放在 credentials.yaml；设置 JSON 不含密钥。
• /balance、/sync 的 Bearer 必须与本机解析的凭据一致；六条路由均仅回环可访问。
• enabled: false 时会删除插件写入的条目，余额与同步接口返回 503。
• 手工改坏 whale-newapi-bridge-settings.json 时插件会回退 yml 并在 /status.warnings 说明；修好或从设置页重新保存即可。

延伸阅读¶

• 社区目录：zuaonew-ops/dsh-whale-newapi-bridge
• 源码与完整 API、安全模型：GitHub README
• 挂件字段契约：仓库内 docs/WHALE-CONTRACT.md；上游协议：docs/PROTOCOL.md

经过上面的步骤，中转站余额会稳定出现在小鲸鱼里，配置集中在 DSH 设置页，无需再手搓 .dshw-api.json 与端口映射。