前言¶
DeepSeek Harness (DSH) 采用插件化架构，旨在通过扩展功能提升开发与调试效率。dsh-ark-balance 是一款挂件类插件，解决在 Web 界面查看火山方舟协作奖励计划免费资源包余量的痛点。它直接复用官方 CLI 的数据源，无需额外登录或配置 Key，常驻显示在浏览器中。
插件信息¶
- 名称：dsh-ark-balance
- 维护者：key8023lala
- 许可证：MIT
- Star 数：1
- 仓库：https://github.com/key8023lala/dsh-ark-balance
前置条件¶
在安装插件前，需确保本地已安装官方 CLI 并完成登录。插件会调用 CLI 获取数据。
# 安装 CLI
npm i -g @volcengine/ark-cli@latest
# 登录授权（建议使用 volc-sso 扫码）
arkcli auth login volc-sso
# 验证登录状态
arkcli auth status
# 验证数据获取（能看到 JSON 即表示就绪）
arkcli usage balance --type free-quota
安装与启用¶
DSH 的插件通过命令行安装。安装后需重启 Web 服务使挂件生效。
# 安装插件
dsh plugin --profile web add dsh-ark-balance
# 重启 dsh web 服务
# 然后在浏览器中刷新页面（F5）
核心功能¶
- 官方视觉风格：悬浮图标与标题栏使用火山方舟官方图标（console.volcengine.com/ark 的 favicon），保持纯白底色，无多余特效。
- 可拖拽与位置记忆：折叠态可拖拽图标，展开态可拖拽卡片头部。位置自动保存至
localStorage，并自动避让视口边缘。 - 模型分类与筛选：每个模型自动分类（文本、多模态、图片、视频、3D、代码、翻译、角色、向量）并显示彩色徽标。支持按类型和厂商进行多选筛选，厂商名自动简称。
- 排序与发布日期：支持按剩余量、发布日期（新→旧）、名称排序。发布日期从
primary_version解析，目录缓存 6 小时。 - 叠加口径展示：显示总量与剩余量，该数值为「免费推理 + 数据权限」两类资源包的叠加值。meta 行会显示两类拆分详情。
- 固定高度与防抖动：卡片高度固定为
min(560px, 70vh)，筛选操作不会导致窗口跳动。 - 刷新机制：支持 60 秒自动刷新与手动刷新（右上角 ↻）。宿主侧缓存机制避免重复调用 API。
- 低余量提醒：
- 悬浮图标角标实时计数。
- 模型叠加剩余跌破阈值（默认 20 万 token）时弹出「余量 / 耗尽」提醒卡片。
- 仅状态跃迁触发提醒，回升自动重置，不会频繁轰炸。
- 支持一键只看告警，并在设置中调整阈值。 - 优雅降级：如果未安装 CLI 或未登录，界面会显示安装与登录引导。
- 零依赖：纯 Node ESM 模块，无任何运行时依赖。
- 凭据零接触：完全复用 CLI 登录态，插件不读取、不存储、不上传任何 Key。
使用方法¶
- 启动与显示：重启
dsh web后，浏览器左下角会出现火山方舟图标（折叠态）。 - 拖拽布局：按住图标或展开后的卡片头部，将其拖拽至屏幕任意位置。位置会被自动记住。
- 查看详情：点击图标展开卡片。卡片顶部显示工具栏（类型多选、厂商多选、排序下拉）。列表每行展示模型名、类型徽标、剩余/总量、进度条、发布日期及已用拆分（免费推理 / 数据权限）。
- 刷新数据：点击右上角的 ↻ 按钮手动刷新；系统每 60 秒自动刷新一次。
- 管理提醒：
- 点击卡片头部左侧的 ⚠ 按钮，可筛选出低余量模型。
- 点击 ⚙ 按钮，可开启/关闭提醒、调整阈值（万 token）、预览或清除已提醒记录。
- 当模型剩余跌破阈值时，右下角弹出提醒卡片，点击「查看」可跳转至告警列表。
数据来源¶
数据来源于 @volcengine/ark-cli 的内部命令。
# 数据获取命令
arkcli usage balance --type free-quota --format json --page-size 200
资源包按 type 分为两类：
- FreeInference：免费推理额度（协作奖励）。
- DataPermission：数据权限额度（如声音复刻）。
发布日期信息通过 models search 目录拉取并缓存 6 小时。
注意事项¶
- 权限：插件以当前 DSH 进程的权限运行，请确保已安装并登录
arkcli。 - 刷新延迟：数据刷新延迟由
arkcli上游控制，控制台通常存在 5–30 分钟的延迟。 - 验证安装：可通过以下命令验证插件是否正确加载：
dsh --profile web --dump-config | Select-String "ark-balance"
- 生态说明：此插件托管于独立社区目录，与 DeepSeek 或火山引擎无官方隶属关系，数据以官方控制台为准。
