前言¶

給智能體做界面時，常會遇到一件小事：想在自己的插件 UI 上顯示當前 DeepSeek 賬戶還剩多少額度，但餘額查詢依賴 API key，而 key 通常只在服務端配置裏，不想暴露給瀏覽器。一種做法是自己開一個後端接口，在另一個進程裏讀 key、再通過接口轉發出去；這會把 key 多存一份，也多一個攻擊面。

下面介紹的插件把這個功能收進 DSH 宿主進程：它只在宿主內部解析 key，對外暴露一個受鑑權的路由，瀏覽器拿到的只有餘額的十進制字符串。

這是什麼¶

victorcastro55/dsh-matrix-terminal-balance，由 victorcastro55 維護，分類「模型推理」。它是 dsh-matrix-terminal 的宿主側插件，爲 dsh-matrix-terminal 的 prompt line 提供 DeepSeek 賬戶餘額，key 不離開宿主進程。

它解決的問題是：插件想顯示餘額時，不必自己持有或轉發 API key，也不需要額外部署後端。

核心功能¶

先看清楚它實際做了什麼，以下能力邊界來自 README。

1、解析憑證。每次請求通過 credential service 解析 DEEPSEEK_API_KEY，與模型提供方讀取的是同一個引用，所以界面上顯示的數字就是實際在花的數字。

2、調用平臺餘額接口。向 https://api.deepseek.com/user/balance 發起一次請求，超時 8 秒。

3、緩存與合併請求。緩存最近一次成功應答 30 秒，並把併發請求合併成一次在途讀取，避免界面因焦點變化觸發的刷新各自消耗一次請求。

4、失敗不報錯。請求失敗時返回 { ok: false, reason }，reason 取值爲 no-key、network、http-<status> 或 protocol；皮膚端把所有失敗都當作「無餘額」，保留上一次已知金額。

5、不泄露 key。除了插件 id 之外不寫日誌，key 不會寫進任何應答、緩存文件或日誌行。

路由安全約束：走的是宿主已有的鑑權 /api 通道，未認證請求返回 401，帶外部 Origin 的請求返回 403，因此餘額只有你自己的 harness 服務給你的頁面能讀到。

安裝與啓用¶

該插件尚未發佈到 npm，需要直接從倉庫安裝。命令來自 README 原文：

dsh plugin --profile web add github:victorcastro55/dsh-matrix-terminal-balance

事前條件：DeepSeek Harness 0.2.1-rc.5 或兼容版本，宿主需帶 connection 和 credentials 兩個服務（兩者都是 stock host 標配）；併爲 DeepSeek provider 配置好 API key。沒有 key 時路由返回 no-key，prompt line 就停在光標處。

需要注意它和 dsh-matrix-terminal 的搭配關係：只裝餘額插件不會有問題，路由存在但沒人讀它；只裝皮膚也沒問題，prompt line 只是不顯示金額。

典型用法¶

裝好後，路由是帶命名空間、owner 鑑權且穩定可用的，頁面上的任何腳本都能讀取：

const res = await fetch('/api/matrix-terminal.balance', { headers: { accept: 'application/json' } });
const body = await res.json(); // { ok, available?, wallets: [{ currency, total, granted?, toppedUp? }] }

返回示例：

{
  "ok": true,
  "available": true,
  "wallets": [
    { "currency": "USD", "total": "0.00", "granted": "0.00", "toppedUp": "0.00" }
  ]
}

total 是平臺給出的十進制字符串，不是數值，這樣格式轉換才能保持精確。皮膚端按以下方式渲染：不足一美分顯示爲 <$0.01，千位分組，多個錢包用 + 連接。

在自己的插件裏讀取這個路由時，注意失敗應答的結構：ok 爲 false 時帶 reason，讀取方應按「餘額不可用」處理，而不是當作異常拋出。

適用場景與注意¶

適合兩類用法。一是裝了 dsh-matrix-terminal 皮膚、想在 prompt line 上看餘額的開發者；二是想在 DSH 頁面裏自己展示餘額、又不想自己管理 key 的插件作者。

幾個使用上的注意點：

1、插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（項目爲 MIT，聲明與 DeepSeek 無關）。

2、餘額接口是平臺文檔接口，調用不消耗 token，但它會真實讀取賬戶狀態，不要把它放進高頻輪詢；插件自帶的 30 秒緩存只是工程保護，不是帶寬承諾。

3、no-key 意味着 DeepSeek provider 沒配 key，此時界面沒有餘額是預期行爲，不是插件故障。

4、社區目錄 SkillHub 是獨立站點，與 DeepSeek / 幻方無官方從屬關係，插件信息以倉庫 README 爲準。

結尾¶

總體看，這個插件的價值不在於功能多，而在於把「讀餘額」這件事的 key 處理固定在宿主進程內：接口簽名簡單、失敗語義清晰（ok: false 加 reason），適合直接接入現有 DSH 頁面。需要進一步確認實現細節，可以讀倉庫源碼：GitHub 上 victorcastro55/dsh-matrix-terminal-balance，目錄頁見 SkillHub 對應條目。

資料覈對¶

本文事實取自 GitHub README 與 package.json（version 1.0.1，license MIT，作者 Victor Castro Solalto），未編造案例與數據。