前言¶

用 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 里查看额度与用量¶

1. 确认 Magpie 托盘程序已启动且 DSH 能访问本机网关（默认 127.0.0.1:3425）。
2. 打开 DSH，点击输入框右侧徽章，展开双栏面板。
3. 在左栏切换 当天 / 7 天 / 30 天 / 全部，查看模型花费榜与汇总 KPI。
4. 在右栏查看各订阅窗口剩余百分比、预充值余额行，以及重置卡说明；对红色「读取失败」条目按提示到 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。

• 社区目录：https://www.skillhub.cn/plugins/Hongcheng-LI/dsh-magpie
• 源码与文档：https://github.com/Hongcheng-LI/dsh-magpie-quota