dsh-ark-balance

DeepSeek Harness（DSH）插件：在 Web 界面以常驻挂件展示火山方舟协作奖励计划各模型的免费资源包余量（总量 / 已用 / 剩余 / 发布日期），数据来自官方 @volcengine/ark-cli。

特性

• 🌋 官方 logo：悬浮图标与标题栏使用火山方舟官方图标（console.volcengine.com/ark 的 favicon），纯白底、无多余特效
• 🖱️ 可自由拖拽：折叠态拖悬浮图标、展开态拖卡片头部，位置记忆在 localStorage，卡片自动避让视口边缘
• 🏷️ 类型徽标：每个模型自动分类（文本 / 多模态 / 图片 / 视频 / 3D / 代码 / 翻译 / 角色 / 向量）并显示彩色徽标
• 🔎 多选筛选：类型 + 厂商两个多选下拉（选中项带 ✓ 对号），支持叠加过滤；厂商名自动简称
• 📈 排序：按剩余量 ↑↓ / 发布日期新→旧 / 名称
• 📅 发布日期：每个模型显示发布时间（从 primary_version 解析，目录缓存 6 小时）
• 🪙 叠加口径：剩余/总量为「免费推理 + 数据权限」两类资源包叠加值，meta 行显示两类拆分
• 📐 固定高度：卡片高度固定（min(560px, 70vh)），筛选时窗口不跳变
• 🔄 60 秒自动刷新 + 手动刷新；宿主侧缓存避免重复调用
• 🔔 低余量提醒：悬浮图标角标实时计数；模型叠加剩余跌破阈值（默认 20 万 token，⚙ 可调）时弹「余量 / 耗尽」两档提醒卡片，仅状态跃迁触发、回升自动重置不轰炸；⚠ 一键只看告警，支持弹窗预览
• 🧯 优雅降级：未装/未登录 ArkCLI 时显示安装与登录引导
• 🪶 零依赖：纯 Node ESM，无任何 runtime 依赖
• 🔐 凭据零接触：完全复用 ArkCLI 登录态，插件不读、不存、不上传任何 Key

截图

前置条件

需要先在本机安装官方 CLI 并登录一次：

npm i -g @volcengine/ark-cli@latest
arkcli auth login volc-sso   # 浏览器扫码授权（或 arkcli auth login --no-browser 跨设备登录）
arkcli auth status
arkcli usage balance --type free-quota   # 能看到 JSON 即就绪

安装

从 npm 安装（推荐）

dsh plugin --profile web add dsh-ark-balance

本地开发安装

git clone https://github.com/key8023lala/dsh-ark-balance.git
cd dsh-ark-balance
dsh plugin --profile web add link:.

• link: 会把 profile 的 node_modules/dsh-ark-balance 链接到源码目录，方便改代码
• 安装后 dsh-ark-balance 自动进入 dsh.profile.bundles，重启 dsh web 后浏览器 F5

卸载

dsh plugin --profile web remove dsh-ark-balance

使用说明

1. 重启 dsh web 后，浏览器左下角出现火山方舟图标（折叠态）
2. 拖拽：按住图标/卡片头部拖到任意位置（位置自动记忆）
3. 点击图标展开，卡片显示模型列表：
   • 每行：模型名 + 类型徽标 + 剩余/总量 + 进度条 + 发布日期 + 已用拆分（免费推理 / 数据权限）
   • 顶部工具栏：类型（多选）、厂商（多选）、排序（下拉）
4. 点右上角 ↻ 手动刷新；60 秒自动刷新
5. 余量提醒：头部 ⚠ 只看告警（按钮带数量）；⚙ 打开提醒设置（启用、阈值「万 token」、预览、清除已提醒）；某模型叠加剩余跌破阈值时右下角弹提醒卡片，「查看」跳转告警列表

数据来源

• 命令：arkcli usage balance --type free-quota --format json --page-size 200
• 底层 OpenAPI：ListModelChargeItems（火山方舟控制台「模型广场 → 免费额度」）
• 资源包按 type 分两类：
  • FreeInference（免费推理）：协作奖励计划赠送的 token 额度，主进度条
  • DataPermission（数据权限）：声音复刻等数据授权额度，meta 行拆分展示
• 发布日期：models search 目录一次拉取并缓存 6 小时，从 primary_version（YYMMDD）解析，缺失模型 models get 兜底

刷新延迟由 arkcli 上游决定（控制台通常 5–30 分钟）。

验证

# 插件在配置树中
dsh --profile web --dump-config | Select-String "ark-balance"

# 宿主路由
curl http://127.0.0.1:3080/dsh-ark/status.json
curl http://127.0.0.1:3080/dsh-ark/balance.json

目录结构

dsh-ark-balance/
├── package.json          # DSH bundle 元数据 + dshhub 市场信息
├── cordis.patch.yml      # 挂载声明
├── README.md
├── LICENSE               # MIT
├── assets/               # 官方图标源文件
└── lib/
    ├── index.js          # 宿主：spawn arkcli、缓存、日期富化、HTTP 路由
    └── widget.js         # 前端挂件（拖拽 / 筛选 / 排序 / 列表渲染）

开发

改 lib/widget.js（挂件）后浏览器 F5 即可生效；改 lib/index.js（宿主）后需重启 dsh web。

常见问题

• 挂件不出现：确认 dsh plugin add 成功、dsh --profile web --dump-config 里有 ark-balance、重启后 F5
• 显示「未检测到 arkcli」：执行 npm i -g @volcengine/ark-cli@latest
• 显示「未登录」：执行 arkcli auth login volc-sso
• 模型只有部分：确认 arkcli 已登录，usage balance --type free-quota 正常（插件会一次拉全 49 个已开通模型）
• 日期不显示：目录缓存 6 小时过期后自动重建，首次加载多花几秒

贡献

欢迎提交 Issue 与 PR：

1. Fork 本仓库
2. 创建特性分支（git checkout -b feat/xxx）
3. 提交改动（遵循语义化提交信息）
4. 推送并提交 Pull Request

许可证

MIT

本项目与火山引擎无隶属关系，插件展示的数据以火山方舟控制台为准。