dsh-volcengine-usage

Readme

# dsh-volcengine-usage

一个用于 DeepSeek Harness Web 的火山引擎 Coding Plan 用量监控插件。

已提交至 [DSH Market（PR #3617）](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/pull/3617)，欢迎通过 GitHub 下载试用。当前状态是等待维护者审核，尚未声明为已收录。

插件在 DSH 页面显示可拖动的用量卡片，展示 5 小时、每周和每月用量百分比。卡片坐标保存在浏览器本地，刷新或重启后仍会保留。

<img width="373" height="188" alt="image" src="https://github.com/user-attachments/assets/f86036a1-9d00-4c59-98e4-764708b28209" />

## 为什么做这个

我是 Coding Plan 的个人轻度用户。火山引擎为 Agent Plan 提供了正式的套餐用量查询 API，但 Coding Plan 没有对应的公开余量 API；控制台只能看到整体百分比，也不能回溯单次请求或按模型拆分。

![Agent Plan 有正式的套餐用量查询 API](assets/agent-plan-api-docs.png)

GLM 模型计费倍率优惠结束后，我发现 Claude 或 DSH 使用 GLM-latest 处理任务时，5 小时额度有时不到一小时就会耗尽。奇妙的是，一些已经写好 usage skill 的任务，实际比较下来仍然是 DeepSeek V4 Flash 或 GLM 完成得更好，Minimax-M3 或豆包 2.1 Pro 并不能稳定替代。

因此我做了这个小部件：不改变自己的模型选择，只把 Coding Plan 的整体额度放到 DSH 页面里，让消耗速度随时可见。

这个插件使用登录后的控制台网页 Cookie 调用控制台内部页面请求，并非火山引擎承诺稳定的公开 Coding Plan API。Cookie 可能过期，接口也可能变化；使用、排障或二次开发时，请始终避免在聊天、日志、Issue 或代码中泄露 Cookie、Web ID、CSRF token 等会话信息。

## 与已有社区插件的关系

开发这个插件时，我曾以 `volcengine` 为关键词搜索 DSH 插件，但没有找到直接对应的结果。直到准备向 DSH Market 投稿、逐项检查官方目录时，才发现社区中已经存在相关项目：

- [YZz-S/dsh-billing-balance](https://github.com/YZz-S/dsh-billing-balance) 同时提供 DeepSeek API 余额与火山方舟 Coding/Agent Plan 套餐额度，并在设置页、输入区和悬浮按钮等位置展示信息；其 [DSH Market 条目](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/data/plugins/YZz-S__dsh-billing-balance.yml) 已经收录。
- [wenzetan/dsh-quota-panel](https://github.com/wenzetan/dsh-quota-panel) 是覆盖多个服务商的通用余额与套餐额度面板；其 [DSH Market 条目](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/data/plugins/wenzetan__dsh-quota-panel.yml) 也已经收录。

本项目不是上述项目的分叉。它保留了我最初需要的窄场景：仅显示火山 Coding Plan 的三个额度窗口，使用控制台登录态而不是要求用户配置火山控制面 AK/SK，并提供一个简单、可拖动的完整卡片。这个方案方便只在控制台查看额度的个人用户，但代价是 Cookie 会过期，而且内部接口可能变化。请根据自己的凭据条件和使用习惯选择更合适的插件。

## 功能

- 展示 5 小时、每周和每月用量百分比
- 点击 `↻` 手动刷新，每 5 分钟自动刷新
- 拖动标题栏移动卡片并记忆位置
- Cookie 和 Web ID 只在 DSH 服务端读取，不发送给浏览器
- 提供稳定的本机 JSON 接口，便于二次开发

## 安全说明

本仓库不包含、也不应提交任何 Cookie、API Key、Web ID 或 `.credentials.yaml` 文件。

插件服务端通过 DSH credentials 服务解析以下引用：

```text
VOLCENGINE_COOKIE
VOLCENGINE_WEB_ID
```

浏览器端只能访问经过整理的用量数据，无法读取原始凭据。服务端接口默认只接受本机环回连接。

## 让 Agent 帮你安装

把下面这段话连同本仓库链接发给你的 Agent：

```text
请先阅读这个仓库的 README.md 和 docs/AGENT_INSTALL.md，然后把该插件安装到我的 DeepSeek Harness web profile。安装前备份 profile/package.json、cordis.patch.yml 和凭据文件；不要输出或记录任何凭据值。检查 VOLCENGINE_COOKIE 与 VOLCENGINE_WEB_ID 是否存在，只报告键名和状态。安装后重启 dsh web，并验证主页和 /api/dsh-volcengine-usage/v1/usage 均能访问。不要修改无关文件。
```

## 安装方式

仓库发布到 GitHub 后：

```powershell
dsh plugin --profile web add github:helloworld1631/dsh-volcengine-usage
```

如果以后发布到 npm：

```powershell
dsh plugin --profile web add dsh-volcengine-usage
```

安装完成后重启：

```powershell
dsh web
```

## 凭据结构

当前 DSH credentials-local 使用 version 1 文档：

```yaml
version: 1
refs:
  VOLCENGINE_COOKIE: "完整 Cookie"
  VOLCENGINE_WEB_ID: "Web ID"
```

请使用 DSH 自带凭据管理能力或 YAML 序列化器写入，不建议手工拼接长 Cookie。

## 使用

- 按住“火山 Coding Plan”标题栏即可拖动卡片。
- 点击右上角 `↻` 立即刷新。
- 卡片每 5 分钟自动刷新。
- 火山会话过期时，更新本机凭据后重新刷新。

## 二次开发

接口契约、返回字段、扩展示例见 [docs/API.md](docs/API.md)。

## License

MIT