前言¶

在 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 與端口映射。