dsh-volc-coding-plan-usage
在 DeepSeek Harness(DSH)的会话标题栏实时显示火山方舟 Coding Plan的套餐用量:
- 标题栏常驻胶囊
● Coding 12%,颜色随用量变化(< 60% 绿、60–85% 黄、≥ 85% 红) - 点开面板看三档已用百分比:5 小时额度、本周额度、本月额度
- 每档的重置倒计时、套餐档位与到期日、最近一次刷新时间
- 首次使用在面板里填一对火山引擎 Access Key,密钥只落在本机 DSH 凭据存储
为什么需要 Access Key
方舟的用量接口属于火山引擎控制面 OpenAPI:
POST https://open.volcengineapi.com/?Action=GetCodingPlanUsage&Region=cn-beijing&Version=2024-01-01
它只接受火山引擎访问密钥(Access Key ID / Secret Access Key,HMAC-SHA256 签名),不接受方舟 API Key(ark-...)。实测用方舟 API Key 调该接口会返回 InvalidAuthorization,所以插件必须单独保存一对 AK/SK。
权限:AK/SK 属于一个有 ArkReadOnlyAccess 读权限的 IAM 用户即可(主账号密钥也行,但不建议)。密钥只落在本机 DSH 凭据存储($DSH_HOME/.credentials.yaml 的 refs,键名 VOLC_ACCESS_KEY_ID / VOLC_SECRET_ACCESS_KEY),插件把它读进 Host 进程内存用于签名,不写日志、不回传浏览器。
安装
DSH 的插件以 bundle 形式挂在 profile 上:profile 的 package.json 里既是依赖,也要出现在 dsh.profile.bundles 列表里。
1. 取代码
git clone https://github.com/lukysoda/dsh-volc-coding-plan-usage.git
2. 挂到 profile
编辑 $DSH_HOME/profiles/<profile>/package.json(默认 profile 是 desktop,即 ~/.dsh/profiles/desktop/package.json),在 dependencies 里加一条 link:,再把包名追加进 bundles:
{
"dependencies": {
"dsh-volc-coding-plan-usage": "link:/absolute/path/to/dsh-volc-coding-plan-usage"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-volc-coding-plan-usage"
]
}
}
}
路径用绝对路径;Windows 上写成 link:F:/path/to/dsh-volc-coding-plan-usage 也可以。
3. 让 pnpm 建立链接
dsh plugin --profile desktop install
4. 重启 DSH
插件随 bundle 加载。打开任意会话,标题栏右侧应出现 ● Coding 胶囊。
使用
- 第一次点胶囊,面板会提示「还没有配置火山引擎 Access Key」,填入 Access Key ID 与 Secret Access Key,保存即生效(
ArkReadOnlyAccess就够)。 - 面板里「立即刷新」会立刻拉一次;平时 Host 每 60 秒拉一次,页面每 30 秒读一次缓存。
- 胶囊颜色:< 60% 绿、60–85% 黄、≥ 85% 红;查询失败显示红色
!,面板里给出错误码。
工作原理
- Host 半(
index.js+ark-client.js):每 60 秒用 AK/SK 签名调用GetCodingPlanUsage,每 10 分钟补一次GetPersonalPlan(档位 / 到期)。结果缓存在内存,通过本机回环路由GET /dsh-volc-coding-plan/state暴露;路由返回百分比、重置时间、套餐档位和两个凭据名(VOLC_ACCESS_KEY_ID/VOLC_SECRET_ACCESS_KEY,只是键名,不是密钥)。同一进程一份缓存,多标签页不会各打一遍接口。 - Client 半(
client.js):只读该路由,负责胶囊与浮层面板的渲染,不接触密钥。 - 写密钥走 DSH 现有的
remote.credentials接口,与其它插件共用同一套凭据存储。
安全
- AK/SK 只进 Host 进程内存用于签名,不写日志、不回传浏览器;路由响应里只有百分比、重置时间、套餐档位和凭据名。
- 路由只监听本机回环,DSH 的 Web 服务本身也不对外。
- 建议单独建一个只带
ArkReadOnlyAccess的 IAM 子用户来签发密钥,别用主账号密钥。
已知限制
- 用量以火山引擎接口口径为准;该接口并非公开文档化接口,字段变化时面板显示「最近一次查询失败」并带错误码,而不是静默显示 0。
- 只有 Coding Plan 个人版有
GetCodingPlanUsage;Agent Plan 用的是GetAFPUsage,本插件不适用。 - 依赖 DSH 的
webServer、credentials、timer服务与conversation.session.header.utilities、shell.overlay两个插槽,版本差异过大时可能挂不上。
开发
npm test # node --test,覆盖签名、编码、解析与错误映射
代码结构:
| 文件 | 作用 |
|---|---|
index.js |
Host 半:轮询、内存缓存、注册用量路由 |
ark-client.js |
火山引擎 OpenAPI 客户端:HMAC-SHA256 签名、请求、解析 |
client.js |
Client 半:标题栏胶囊与浮层面板(React,走 window.__ModuleLoader__) |
cordis.patch.yml |
bundle 的加载补丁:把插件插进 profile |
locale/*.json |
插件列表里的标题与描述 |
License
English
A DeepSeek Harness plugin that shows live Volcengine Ark Coding Plan quota in the session header: a ● Coding 12% chip plus a panel with the 5-hour / weekly / monthly windows, reset countdowns, and plan tier. Credentials are a Volcengine access key pair (AK/SK) with ArkReadOnlyAccess — an Ark API key does not work on this control-plane endpoint. Keys stay in the local DSH credential store (VOLC_ACCESS_KEY_ID / VOLC_SECRET_ACCESS_KEY) and are only used in the host process for signing; the loopback route exposes percentages only.
Install: add the package to your profile's dependencies as a link: entry, append the name to dsh.profile.bundles, run dsh plugin --profile <name> install, then restart DSH. MIT licensed.
No comments yet. Be the first to write one.