前言¶
用 DeepSeek Harness（DSH）寫智能體或日常對話時，模型往往來自本機 Magpie 網關：WorkBuddy、Trae、MiniMax、GLM、OpenCode Zen、Codex 等訂閱被統一成 OpenAI 兼容接口。額度分散在各廠商後臺或 Magpie 托盤裏，換模型前很難在 composer 裏一眼看清「哪家窗口快用完、預充值還剩多少、近幾天花在哪幾個模型上」。社區插件 dsh-magpie-quota（npm / GitHub 倉庫名；目錄頁常寫作 dsh-magpie，裸名 dsh-magpie 已被他人佔用）由 Hongcheng-LI 維護，分類爲客戶端，直接讀取 Magpie 自帶的 GET /v1/magpie/quotas 與用量接口，在輸入框右側展示徽章與雙欄面板，無需在插件裏填 API Key。
這是什麼¶
dsh-magpie-quota 是 DSH 的 Web 客戶端插件：瀏覽器側掛到 conversation.input.right，Host 側在 DSH Web Server 上註冊同源代理路由，由 Node 向本機 Magpie（默認 127.0.0.1:3425）拉取額度與用量，避免 Magpie API 無 CORS 頭導致頁面直連失敗。Magpie 側新增賬號後，配額列表會自動出現；插件本身零配置（端口可用環境變量 MAGPIE_URL 或 MAGPIE_BASE_URL 覆蓋）。當前 npm 版本 0.4.2，許可證 MIT，要求 Node ≥ 22。
核心功能¶
下面介紹面板與數據能力，均來自插件 README 與實現說明。
輸入框徽章與雙欄面板¶
- 徽章：顯示「用量 / 額度」摘要；懸停可見各賬號剩餘百分比與當前所選週期的花費。若賬號只有預充值餘額、沒有百分比窗口，徽章會退化爲例如
DeepSeek 餘額 ¥9.99（金額由 Magpie 格式化後原樣顯示，插件不做匯率或閾值着色）。 - 左欄「當前用量」：調用 Magpie
/v1/magpie/usage彙總，標題旁可切換 當天 / 7 天 / 30 天 / 全部（偏好鍵localStorage：magpie-quota-usage-period，默認 30 天）。展示折算消耗、調用次數、輸入/輸出 token，以及按花費排序的模型榜；每行第二行固定帶來源（如WorkBuddy · 542 次 · …），同名模型在不同賬號下可區分。 - 右欄「額度」：按 Codex 額度頁風格平鋪各賬號窗口行（標籤左、數值右），賬號名 16px 加粗；免費賬號帶灰色「（免費賬號）」後綴。窗口名會從 Magpie 英文措辭翻譯爲中文（如
5 hours→5 小時用量上限），短週期在上、長週期在下；重置卡按「種類 + 到期日」歸組顯示。詳細用量、重置倒計時等收進懸停提示；讀取失敗的賬號排在最前，並給出可執行原因（如 API key 無效 401）。
三種結算口徑與中轉站餘額¶
- 訂閱積分、按量估值（≈）、預充值實扣（DeepSeek 等
kind: "balance"）在左欄用量與右欄額度中分別按廠家單位展示。 - 第三方中轉（new-api / one-api 等）若在 Magpie 側配置了
balance探測，插件會在/v1/magpie/quotas裏看到kind: "balance"並自動顯示餘額；插件只讀 Magpie，不替 Magpie 配探測 URL。
刷新、主題與架構要點¶
- 60 秒自動刷新；打開面板時若緩存超過 15 秒會強制拉一次；底部可手動刷新。quota 緩存 15s，usage 緩存 20s。
- 面板配色可循環：跟隨 DSH → 淺色 → 深色（
localStorage鍵magpie-quota-card-theme）；視覺令牌取自 DSH 的--dsw-alias-*。 - 只修改
dsh/client.js時刷新 DSH 頁面即可；修改dsh/index.js（Host 代理）後需重啓 DSH。
安裝與啓用¶
先做環境準備：本機運行 Magpie（默認端口 3425）。再在 DSH 內或終端安裝插件（命令以倉庫 README 爲準）：
# npm（推薦，安裝最快）
dsh plugin --profile desktop add dsh-magpie-quota
# 或者直接從 GitHub 裝
dsh plugin --profile desktop add github:Hongcheng-LI/dsh-magpie-quota
安裝完成後刷新 DSH 頁面（或重啓 DSH），輸入框右側應出現 Magpie 額度徽章。
本地開發時可指向插件目錄絕對路徑：
dsh plugin --profile desktop add "<本目錄的絕對路徑>"
典型用法¶
在 composer 裏查看額度與用量¶
- 確認 Magpie 托盤程序已啓動且 DSH 能訪問本機網關（默認
127.0.0.1:3425）。 - 打開 DSH，點擊輸入框右側徽章，展開雙欄面板。
- 在左欄切換 當天 / 7 天 / 30 天 / 全部，查看模型花費榜與彙總 KPI。
- 在右欄查看各訂閱窗口剩餘百分比、預充值餘額行，以及重置卡說明；對紅色「讀取失敗」條目按提示到 Magpie 更新 Key 或檢查探測配置。
非默認端口¶
若 Magpie 不在 3425，在運行 DSH 的環境中設置例如：
# 示例：自定義 Magpie 基址
$env:MAGPIE_URL = "http://127.0.0.1:4000"
重啓 DSH 後再打開面板。
讓中轉站餘額出現在面板裏（Magpie 側配置）¶
插件不修改 Magpie 配置；餘額能否顯示取決於 Magpie provider 是否配置了 balance 等鍵。README 中的常見寫法示例：
# OpenAI 兼容中轉站
magpie provider add "My Relay" url=https://relay.example.com/v1 key=sk-... `
balance=https://relay.example.com/api/usage/token balance.path='$data.total_available / 500000'
# new-api / one-api
magpie provider set my-relay balance=https://relay.example.com/api/user/self `
balance.path='$data.quota / 500000' balance.token=<access token> header.New-Api-User=<user id>
配好後無需改插件代碼，刷新 DSH 面板即可。
自檢 Host 代理是否工作¶
Host 半邊不需要登錄 token；DSH 頁面地址欄端口每次重啓可能變化：
curl.exe --noproxy '*' http://127.0.0.1:<當前端口>/magpie/quotas
應返回 Magpie 額度 JSON 的代理結果；若 Magpie 離線，面板會顯示錯誤原因而非空白。
適用場景與注意¶
適合誰：本機已用 Magpie 聚合多路訂閱或中轉，希望在 DSH composer 裏統一看額度、用量和預充值餘額，減少切後臺或另開工具的頻率。
務必知曉：
- 插件以當前 DSH 進程權限運行，Host 半邊的 Node 會向本機 Magpie 發起 HTTP 請求；安裝前建議閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認符合你的安全策略。
- 插件不存儲 Magpie API Key；Key 僅在 Magpie 與本機 DSH 之間流轉，瀏覽器通過同源路徑
/magpie/quotas、/magpie/usage訪問。 - 社區目錄 SkillHub 插件頁 與 GitHub 爲獨立信息源，與 DeepSeek / 幻方無官方從屬關係；DSH 生態遵循「一切皆插件」，以你本機安裝的包版本與 README 爲準。
結尾¶
經過上面的步驟，你可以在 DSH 輸入框旁持續看到 Magpie 全部接入賬號的額度與可選週期用量，並在 Key 失效或網關不可達時得到明確提示。更多細節與離線預覽（node scripts/preview.mjs）、測試命令見倉庫 README。
