dsh-ark-balance

Readme

# dsh-ark-balance

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

[![npm version](https://img.shields.io/npm/v/dsh-ark-balance)](https://www.npmjs.com/package/dsh-ark-balance)
[![license](https://img.shields.io/npm/l/dsh-ark-balance)](https://github.com/key8023lala/dsh-ark-balance/blob/main/LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/key8023lala/dsh-ark-balance)](https://github.com/key8023lala/dsh-ark-balance)

## 特性

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

## 截图

<img width="613" height="998" alt="image" src="https://github.com/user-attachments/assets/859c2cb0-8300-4d63-830f-ffc857607ff2" />


## 前置条件

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

```powershell
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 安装（推荐）

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

### 本地开发安装

```powershell
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

## 卸载

```powershell
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 分钟）。

## 验证

```powershell
# 插件在配置树中
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
```

## 目录结构

```text
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](LICENSE)

---

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