@angelyeye/dsh-cost-tracker 1.8.12 → 1.8.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,84 @@
2
2
 
3
3
  本文件用中文记录 dsh-cost-tracker 的版本变更。
4
4
 
5
+ ## v1.8.14(2026-09-26)
6
+
7
+ **新增:火山方舟 Coding Plan 订阅支持(配额监控 + 等效费用);并修掉两个此前静默存在的缺陷**
8
+
9
+ ### 一、新增:火山方舟 Coding Plan 配额面板
10
+
11
+ - **设置页新增「订阅套餐用量 · 火山方舟 Coding Plan」面板**,与既有 Kimi 面板并列,显示 **5 小时 / 周 / 月** 三档窗口的已用百分比、绝对量与重置倒计时,附「刷新配额」按钮。
12
+ - **查询走方舟管控面 OpenAPI**,不是推理端点:
13
+ - 端点固定 `https://open.volcengineapi.com/`,`Service=ark`、`Region=cn-beijing`、`Version=2024-01-01`;
14
+ - 认证是 **HMAC-SHA256 签名**(`Credential=AK/日期/区域/服务/request`、`SignedHeaders=host;x-content-sha256;x-date`),**不是 Bearer** —— 这是与 Kimi 那条路径最大的差别;
15
+ - Action 按 `GetCodingPlanUsage → GetAFPUsage → GetUsageDetails → GetPersonalPlan` 顺序兜底。`GetCodingPlanUsage` 是官方 CodingPlan 用量接口,**无参即可返回三档窗口**;`GetAFPUsage` 实为 AgentPlan 接口,账号是 Agent Plan 时自动从它取数;
16
+ - 单个 Action 的 401/403 只表示「该 Action 不可用」(多 Action 变体权限语义不同),继续尝试下一个;200 但解析失败时**优先透出服务端业务信封**(`ResponseMetadata.Error.Code/Message`),因为它比末尾变体的 404 更有诊断价值。
17
+ - **凭据发现链**:插件配置卡片(`volcengineAccessKeyId` / `volcengineSecretAccessKey`)→ DSH 凭据库 → `.credentials.yaml` → 环境变量(`VOLC_ACCESSKEY` / `VOLC_SECRETKEY`,兼容 `VOLCENGINE_ACCESS_KEY_ID`、`ARK_ACCESS_KEY_ID` 等变体;也会从指向方舟 coding 端点的 provider 的 `apiKeyEnv` 反查)。
18
+ - 需要 IAM 子用户具备 **`ArkReadOnlyAccess` + `BillingCenterReadOnlyAccess`**。这与推理用的 **ARK API Key(UUID)是两套凭据**,混填只会得到 401/403。
19
+ - **密钥零外泄**:`volcengine-usage` / `volcengine-config` / `sync` 的响应里**永远不含 AK/SK**,只回 `keySource`(`config` / `credentials:…` / `file`)与候选变量名;卡片里的 Secret 字段标了 `role('secret')`。
20
+ - **失败一律软降级为中性提示**:无凭据、无订阅、权限不足、接口结构变化、网络异常都只回 `{ok:false, error:'中文原因'}`,HTTP 层仍是 200,**不抛异常、不影响其它路由**。
21
+ - **按需出现**:面板只在「存在火山订阅调用(宿主在 `summary` 里回传 `volcengineActive`)或已有窗口数据」时渲染。只跑 DeepSeek / Kimi 的用户界面**完全不变**。
22
+ - **百分比精度**:实测 `Percent` 是 0-100 的百分数但数值极小(`0.3938…` / `0.0997…` / `0.0498…`,即 0.39% / 0.1% / 0.05%),故保留**两位小数** —— 只留一位会把月度 0.05% 显示成「0%」,看上去像没统计到。同时**不套用「≤1 视为小数」的规则**(那会把 0.5% 放大成 50%)。`Cap`(实测恒为 100)用于折算绝对量。
23
+
24
+ ### 二、修掉订阅门卫缺陷:按量调用曾被错记成订阅(重要)
25
+
26
+ - **缺陷**:`priceFor()` 原先只按 **provider 名**判定订阅,对该 provider 的**所有模型**一律套订阅价。
27
+ - **为什么此前没暴露**:Kimi 的 provider 下每个模型都走订阅,所以「只看 provider」恰好成立。
28
+ - **为什么火山会踩**:同一个 provider 下**套餐内与套餐外的模型混在一起** —— 订阅调用被错记为 `subscription: true` 后,金额会从「真实花费」里消失(计入订阅等效而不是按量),且原始记录已被打标,**无法自动回滚**。这是典型的「静默少算」。
29
+ - **现在**:`subscriptionPlanFor(np, model)` 改为「provider 命中 + 模型白名单」双重限定,并区分两类 provider:
30
+ | provider | 判定 |
31
+ | --- | --- |
32
+ | baseURL 指向 `ark.cn-beijing.volces.com/api/coding/v3` 的专属订阅入口(`byteblus-coding-plan-cn`、`byteplus-coding-plan-cn`、`volcengine-coding` 等) | **整档计订阅**,不必追模型日期后缀 |
33
+ | 泛 `volcengine` | **仅白名单内模型计订阅**(豆包系 / GLM 系 / Kimi 系 / DeepSeek / MiniMax,以及 `ark-code-*` 前缀整族);**接入点 id(`ep-2026xxxx`)一律按量** |
34
+ | `kimi` / `kimi-coding` | `SUBSCRIPTION_MODELS` 登记为 `null` = 整档订阅,**行为逐字节不变** |
35
+ - **前缀刻意收窄**:只放行 `ark-code-*`(方舟自动调度名会滚动升级)。按 `deepseek` / `glm` 这类宽前缀整族放行会把套餐外的按量模型一并算成订阅 —— 那正是本门卫要防的方向;宁可漏配(可显式补清单)也不能错配。
36
+ - **等效单价口径**:套餐内各模型牌价差异很大,而套餐只有一个固定月费、官方并未给出「套餐内某次调用的等效单价」。故取**单一代表价**(3.0 / 12.0 / 缓存 0.6),与既有 Kimi 订阅(同样一个价位代表整档)口径一致,**仅用于横向比较订阅是否划算,不是真实扣费**;可核实到的第三方报价多为聚合站美元估价,与官方人民币牌价不可直接对照,按本仓库「不编造价格」的约定不收录。
37
+
38
+ ### 三、修掉凭据文件读取缺陷:`.credentials.yaml` 兜底一直静默失效(重要)
39
+
40
+ - **缺陷**:`readCredFile()` 的正则只匹配**行首无缩进**的键,而真实文件是把键**缩进**存放在 `refs:` 段下的:
41
+ ```yaml
42
+ version: 1
43
+ refs:
44
+ VOLC_ACCESSKEY: AKxxxx # ← 缩进两格,旧正则匹配不到
45
+ VOLC_SECRETKEY: xxxx
46
+ records:
47
+ ...
48
+ ```
49
+ 于是所有键都读不出来,这一路兜底**一直静默失效**(装了宿主凭据服务时被掩盖,没有时就直接报「未找到 Key」)。该缺陷同时影响原本的 Kimi / DeepSeek Key 兜底路径。
50
+ - **现在**:识别缩进、定位 `refs:` 段(避免误读 `records:` 段里的同名键),并保留对「无缩进的旧版平铺文件」的兼容(段内未命中时回落到段外同名键)。
51
+ - **顺带修掉路径硬编码**:原路径写死 `~/.dsh/.credentials.yaml`,`DSH_HOME` 被重定向的部署(含本仓库的沙箱测试)永远读不到;现改为跟随 `DSH_HOME`。
52
+
53
+ ### 四、测试
54
+
55
+ - 新增 `test/volcengine-plan.test.js`(113 条):**与火山官方 demo(`volc-openapi-demos/signature/nodejs/sign.js`)逐字节一致的固定签名向量**、查询串排序与严格 RFC3986 转义、四种响应形态(官方 `QuotaUsage[Level/Percent]`、`UsageDetails`、arkcli `items→periods`、AFP 扁平窗口)、**0.5% 不被放大成 50%**、负数百分比判非法而非钳成 0、`ResetTime=-1` 归一为「无重置」、凭据残缺判 null 且不发请求、403 换 Action、业务信封优先于末尾 404。
56
+ - 新增 `test/volcengine-host.test.js`(36 条):宿主面端到端(老配置 + 凭据文件 → 已签名请求 → 可渲染窗口)、**密钥零外泄**(响应 / sync / 卡片写入三处)、配置卡片凭据优先、真机响应形状(0.05% 不被抹成 0%)、五类失败路径软降级、120s 缓存 TTL 与 `force` 绕过。
57
+ - `test/pricing.test.js` 新增「订阅门卫 + 火山 Coding Plan」一节(覆盖两个方向:订阅**必须**识别、同 provider 的按量调用**必须不**识别),并钉住 Kimi 既有行为不变。
58
+ - `scripts/verify-volcengine-live.mjs`:一次性真机核验脚本(只读接口、不打印密钥)。**已实测通过**:`GetCodingPlanUsage` 返回 `Status: "Running"` 与 session / weekly / monthly 三档真实窗口。
59
+
60
+ ## v1.8.13(2026-09-25)
61
+
62
+ **新增:可以关掉插件在前端的显示(三个落点各自独立)**
63
+
64
+ - **背景**:插件的几个前端落点此前都是常驻的、没有开关 —— 输入框上方的「本会话花费」胶囊、侧边栏底部的峰谷时段条、设置页的「花费统计」看板。不想看的人只能忍,或者干脆卸载插件(连带失去记账与云端同步)。
65
+ - **现在**:设置 → 插件 → 插件配置 → 花费统计 → **界面显示**,三个开关**各自独立**、**勾选即刻生效**(不需要点上面的「保存」,也不需要重启 dsh):
66
+ | 开关 | 配置键 | 落点 |
67
+ | --- | --- | --- |
68
+ | 输入框上方的花费胶囊 | `uiDockEnabled` | `conversation.composer.dock` |
69
+ | 侧边栏峰谷时段条 | `uiPeakEnabled` | `sidebar.footer.action` |
70
+ | 设置页「花费统计」看板 | `uiDashboardEnabled` | `settings.section` |
71
+ 另有一键「全部显示」恢复默认。
72
+ - **只影响渲染**:关掉之后记账、落盘、云端同步与 Agent 工具(`cost_stats` 等)全部照常工作;关掉看板时,设置项仍在,页面里给出一句「如何重新打开」的提示,而不是留一个点不开的空白导航项。
73
+ - **插件配置卡片本身不受这三个开关控制** —— 否则关掉看板之后就再没有入口能打开了。
74
+ - **安全默认**:显隐的真值与 `peakEnabled` 相反,**只有显式 `false` 才隐藏**,缺省/非布尔一律按「可见」处理。老配置文件里没有这几个键,升级后界面与升级前逐像素一致。
75
+ - **实现要点**:
76
+ - 显隐在**渲染期**判定(`uiOn(ui, key)` = `ui[key] !== false`),不是注册期 —— 宿主不会重启插件、插槽注册也无法撤销,只有在渲染期判定才能做到「改完立刻生效」。
77
+ - 配置卡片保存后广播 `dsh-cost-tracker-ui` 事件,已挂载的胶囊 / 时段条 / 看板立刻跟手;另有 30 秒轮询兜底。
78
+ - 新增宿主路由 `ui-config`(写)与 `peak`/`sync` 快照里的 `ui` 字段(读),三个开关与峰谷、云端字段**同存一份配置文件**(`~/.dsh/storages/cost-tracker-config.json`),互不覆盖。
79
+ - 侧边栏时段条关闭时,峰谷切换弹窗与系统通知一并停用(同属一个落点);只想留提醒不要时段条,用「峰谷计价与提示 → 峰时高价时段显著提示」。
80
+ - **测试**:新增 `test/ui-display.test.js`(23 条断言,四层:宿主 HTTP 面读写、落盘不覆盖其它字段、重启后读回、客户端三处判定);`test/client-render.test.js` 新增 [8][9] 两节(关掉即渲染为空、重新打开即恢复、卡片三个开关各自提交自己的键、client.js 与 config.js 的开关清单逐项对齐);`test/config.test.js` 新增界面开关一节(默认可见 / 老配置可见 / 非布尔回退)。全量测试通过。
81
+ - **顺带修掉一处假红**:`cloud-view-e2e.test.js` 的「热力图不重不漏」用例在**本地兄弟目录 dsh-cost-cloud 还是旧版**(< v1.3.2,`byDay` 无 token 类型拆分)时会硬失败 —— 那与「跨仓库依赖检测不到就跳过」的既定原则不一致。现改为探测到旧云端就明确 skip 并提示升级兄弟目录,不再把一个环境问题伪装成发布闸门红灯(线上真连旧云端时热力图本就会退回本机并在卡片标注口径,属已声明的降级)。
82
+
5
83
  ## v1.8.12(2026-09-19)
6
84
 
7
85
  **修复:①「Token 用量统计」热力图不跟随三态视图(本机+云端下屏内自相矛盾)② `cost_stats scope=cloud|both` 崩溃**
package/README.en.md CHANGED
@@ -36,7 +36,7 @@
36
36
  | 🏷️ | **Official model-name alignment** | Billing recognises the official current name **`deepseek-flash`** (price-card note (1): "use the model name `deepseek-flash`"); older spellings such as `deepseek-v4.1-flash` normalize to the same rate, so an official rename can never silently drop usage into the fallback estimate |
37
37
  | 📊 | **Visual dashboard** | A new "Cost Statistics" page in Settings: overview cards, cost bar charts (by peak period / by model), per-model request & token charts — **all with hover tooltips** |
38
38
  | 🧭 | **Multi-machine aggregation (cloud sync)** | Point it at your own **self-hosted cloud service** (separate `dsh-cost-cloud` repo, zero runtime dependencies) to merge usage from several computers; the dashboard then offers a **This machine / This machine + cloud / Cloud only** switcher plus a **device × Agent matrix** (row totals = column totals = grand total). Only token counts, cost, timestamps and identifiers are uploaded, with optional session-id masking |
39
- | 📈 | **Subscription quota** | Kimi Coding Plan and similar subscriptions: weekly quota, 5-hour rolling window limit, pay-as-you-go-equivalent cost for reference |
39
+ | 📈 | **Subscription quota** | Kimi Coding Plan and **Volcengine Ark Coding Plan**: quota progress bars, reset countdowns and pay-as-you-go-equivalent cost for reference. Volcengine is queried through the Ark **control-plane OpenAPI** (HMAC-signed), requiring an AccessKeyID + SecretAccessKey pair |
40
40
  | 💳 | **Balance lookup** | One-click DeepSeek account balance (total / topped-up / granted / status) |
41
41
  | 🤖 | **Agent tools** | Ask in any chat: "how much have I spent today?" — the agent answers via `cost_stats` / `cost_prices` |
42
42
  | 🔻 | **Status line** | A live line under the chat input: **session cost** (segmented pills: session / subscription plan / per-model), split by the models actually used in the session; multi-model collapses to top2 by default, click to expand. Subscription shows the plan name; no quota or call-count clutter |
@@ -213,6 +213,21 @@ The dimension selector adds per-device / per-agent / per-model breakdowns and a
213
213
 
214
214
  **Privacy**: only token counts, cost, timestamps and identifiers are uploaded — never prompts, responses, file paths or code. The config card offers "mask session id" (irreversible hash) and "omit purpose".
215
215
 
216
+ ### Interface visibility (v1.8.12, optional)
217
+
218
+ Don't want the plugin in your face? **Settings → Plugins → Plugin configuration → Cost Tracker → Interface visibility** has three independent switches that apply **the moment you tick them** (no Save, no `dsh` restart):
219
+
220
+ | Switch | What turning it off does |
221
+ | --- | --- |
222
+ | Composer cost pill | the per-session cost / model breakdown above the chat input disappears |
223
+ | Sidebar peak bar | the phase / countdown strip at the bottom of the sidebar disappears (the peak-switch popup and web notifications go with it; if you only want the reminder without the strip, use the notice switch under "Peak/off-peak pricing & notices" instead) |
224
+ | Settings dashboard | the "Cost Tracker" entry disappears from the Settings nav (accounting and cloud sync keep running; the page then shows a one-line hint on how to bring it back) |
225
+
226
+ - **Display only**: accounting, persistence, cloud sync and the agent tools (`cost_stats` etc.) are unaffected;
227
+ - **The plugin configuration card itself is never hidden by these switches** — otherwise you would have no way to turn them back on;
228
+ - Truth value is "hidden only on an explicit `false`", so a missing key means visible: **an existing config file looks exactly the same after upgrading**;
229
+ - All three keys live in the same `~/.dsh/storages/cost-tracker-config.json` (`uiDockEnabled` / `uiPeakEnabled` / `uiDashboardEnabled`) and never overwrite the peak/cloud fields.
230
+
216
231
  ### HTTP API (for other tools)
217
232
 
218
233
  All endpoints are `POST` + JSON and listen on the loopback address:
@@ -221,14 +236,17 @@ All endpoints are `POST` + JSON and listen on the loopback address:
221
236
  POST /api/cost-tracker/summary Overview
222
237
  POST /api/cost-tracker/dashboard Dashboard data
223
238
  POST /api/cost-tracker/usage Usage heatmap (all-time totals + daily token aggregation)
224
- POST /api/cost-tracker/peak Peak-phase snapshot (current tier / next switch / config)
239
+ POST /api/cost-tracker/peak Peak-phase snapshot (current tier / next switch / config / interface visibility)
225
240
  POST /api/cost-tracker/peak-config Save peak-price notice config
226
- POST /api/cost-tracker/sync Cloud sync status (device id / watermark / pending / last error)
241
+ POST /api/cost-tracker/ui-config Save interface-visibility switches (pill / sidebar bar / dashboard; partial patches OK)
242
+ POST /api/cost-tracker/sync Cloud sync status (device id / watermark / pending / last error / interface visibility)
227
243
  POST /api/cost-tracker/sync-now Sync now ({"full":true} to re-send everything)
228
244
  POST /api/cost-tracker/sync-test Test the cloud connection
229
245
  POST /api/cost-tracker/sync-config Save cloud sync config
230
246
  POST /api/cost-tracker/cloud Read-only cloud aggregation (route/days/excludeSelf/devices/sources)
231
247
  POST /api/cost-tracker/kimi-usage Kimi subscription quota
248
+ POST /api/cost-tracker/volcengine-usage Volcengine Ark Coding Plan quota (5-hour / weekly / monthly windows)
249
+ POST /api/cost-tracker/volcengine-config Save Volcengine AK/SK (reports only whether keys are configured, never the keys)
232
250
  POST /api/cost-tracker/balance Account balance
233
251
  POST /api/cost-tracker/prices Price table (versioned by pricing era)
234
252
  POST /api/cost-tracker/recompute Re-price stored records by era (dry-run unless {"apply":true})
@@ -243,6 +261,26 @@ Example: `curl -X POST http://127.0.0.1:3080/api/cost-tracker/summary -d '{}'`
243
261
 
244
262
  > Highlights only — the full version-by-version history lives in [`CHANGELOG.md`](./CHANGELOG.md) (Chinese).
245
263
 
264
+ ### v1.8.14 (2026-09-26)
265
+
266
+ **New: Volcengine Ark Coding Plan support (quota monitoring + equivalent cost)**
267
+
268
+ - **Quota panel**: a new "Subscription usage · Volcengine Ark Coding Plan" panel in Settings pulls the **5-hour / weekly / monthly** windows from the Ark **control-plane OpenAPI** (`open.volcengineapi.com`, `Action=GetCodingPlanUsage`, HMAC-SHA256 signed), showing used percentage, absolute amounts (derived from `Cap`) and reset countdowns. Actions fall back in order `GetCodingPlanUsage → GetAFPUsage → GetUsageDetails → GetPersonalPlan`, so Agent Plan accounts automatically read from AFP;
269
+ - **Equivalent cost**: calls covered by the plan now count toward "subscription equivalent cost" instead of being mislabelled "pay-as-you-go · estimated price";
270
+ - **Fixed a subscription-gate defect (important)**: the gate used to match on provider name only, applying subscription rates to *every* model of that provider. Volcengine Ark mixes plan and non-plan models under one provider, so metered calls were mislabelled as subscription and their amounts vanished from "real spend". It is now gated on **provider + model allowlist**, and distinguishes **dedicated subscription endpoints** (baseURL pointing at `/api/coding/v3` — the whole provider counts as subscription) from a **generic `volcengine`** provider (only allowlisted models; endpoint ids `ep-*` are always metered). Kimi's existing behaviour is byte-for-byte unchanged;
271
+ - **Fixed a credential-file defect (important)**: `.credentials.yaml` actually stores keys **indented** under the `refs:` section, while the parser only matched unindented top-level keys — so that fallback had silently never worked (masked whenever a host credential service was present). Indentation and `refs` scoping are now handled, the path follows `DSH_HOME`, and the hard-coded `~/.dsh` that broke redirected deployments is gone;
272
+ - **Credential discovery chain**: plugin-config card → DSH credential store → `.credentials.yaml` (`VOLC_ACCESSKEY` / `VOLC_SECRETKEY` plus several variants) → environment variables. **Keys never appear in any response**; `volcengine-config` only reports whether keys are configured;
273
+ - **Every failure is a neutral notice**: missing credentials, no subscription, insufficient permission (needs `ArkReadOnlyAccess` + `BillingCenterReadOnlyAccess`) and changed API shapes all degrade to a neutral notice without affecting recording, sync or other features. Users who only run DeepSeek or Kimi see a **completely unchanged** UI (the panel appears only when relevant);
274
+ - Adds `volcengine.js` (signing / parsing / querying, pure and unit-testable) plus two test files covering fixed signature vectors that match Volcengine's official demo byte-for-byte, four response shapes, **0.5% not being scaled to 50%**, zero key leakage, cache TTL and soft-failure paths. Verified against the live API (`GetCodingPlanUsage` returning `Status: Running` and three windows).
275
+
276
+ ### v1.8.13 (2026-09-25)
277
+
278
+ **Added: the plugin's front-end surfaces can now be turned off (three independent switches)**
279
+
280
+ - **Settings → Plugins → Plugin configuration → Cost Tracker → Interface visibility**: the composer cost pill, the sidebar peak bar and the Settings "Cost Tracker" dashboard can each be switched off on their own, applied **immediately** (no Save, no `dsh` restart), plus a one-click "Show all".
281
+ - **Display only**: accounting, cloud sync and the agent tools keep working; the plugin configuration card itself is never hidden (otherwise there would be no way back).
282
+ - **Safe default**: hidden only on an explicit `false`, so missing keys mean visible — an existing config file looks identical after upgrading. See the "Interface visibility" section above.
283
+
246
284
  ### v1.8.12 (2026-09-19)
247
285
 
248
286
  **Fixed: the heatmap ignored the three-state switch (self-contradicting screen in "local + cloud"), and `cost_stats scope=cloud|both` crashed**
@@ -427,6 +465,23 @@ The plugin starts **silently by default**. Set the environment variable `DSH_COS
427
465
  **Q: What does "equivalent cost" mean for subscription models (kimi-coding)?**
428
466
  Subscriptions are not billed per token. The plugin estimates what those calls *would* cost at pay-as-you-go prices so you can judge whether your subscription pays off — **it is not a real charge**.
429
467
 
468
+ **Q: How do I connect a Volcengine Ark Coding Plan? Which credential does it need?**
469
+ Quota is read from the Ark **control-plane** OpenAPI (`open.volcengineapi.com`, HMAC-SHA256 signed), so it needs a **Volcengine access-key pair**:
470
+
471
+ 1. Volcengine console → **IAM → Users → Keys**, create an AccessKeyID / SecretAccessKey pair;
472
+ 2. Grant that sub-user **`ArkReadOnlyAccess`** and **`BillingCenterReadOnlyAccess`** (read-only is enough to query usage);
473
+ 3. Let the plugin obtain the pair (any one of these, in priority order):
474
+ - fill in **Volcengine AccessKeyID / SecretAccessKey** under **Settings → Plugins → Plugin config → Cost Tracker** (the secret is never echoed back); or
475
+ - put them in the `refs:` section of `~/.dsh/.credentials.yaml` under `VOLC_ACCESSKEY` / `VOLC_SECRETKEY` (variants such as `VOLCENGINE_ACCESS_KEY_ID` and `ARK_ACCESS_KEY_ID` also work); or
476
+ - export them as environment variables with the same names.
477
+
478
+ > ⚠️ This is a **completely different credential** from the **ARK inference API key** (a UUID configured as the provider's `apiKey` / `apiKeyEnv`). The inference key cannot query quota and will produce 401/403.
479
+
480
+ The panel shows the 5-hour / weekly / monthly windows with used percentage and reset countdown. Coding Plan usage is expressed as a **percentage** (observed in the 0.05%–0.4% range), so two decimals are kept to avoid displaying "0%". If the account is actually on an Agent Plan, the plugin automatically falls back to the `GetAFPUsage` action. Missing credentials, no subscription and insufficient permissions are all **neutral notices** that never affect recording, sync or other features.
481
+
482
+ **Q: Why are some Volcengine Ark models billed as "subscription" and others as "pay-as-you-go"?**
483
+ Plan and non-plan models can share one provider. Any provider whose **baseURL points at `ark.cn-beijing.volces.com/api/coding/v3`** is a dedicated subscription endpoint, so all of its calls count as subscription. Under a generic `volcengine` provider, only plan models (Doubao, GLM, Kimi, DeepSeek, MiniMax families and the `ark-code-*` names) count as subscription, while **endpoint ids (like `ep-2026xxxx`) are always pay-as-you-go** — so metered calls are never mislabelled as subscription and silently dropped from your real spend.
484
+
430
485
  **Q: The amounts don't exactly match my official bill?**
431
486
  Costs are estimated locally from a built-in price table and may differ slightly from the official bill (price updates, tiered pricing, etc.). Treat official billing as authoritative; the balance shown is fetched live from the official API.
432
487
 
@@ -446,8 +501,9 @@ Either way: if only the UI (`client.js`) changed, a **hard browser refresh** (Cm
446
501
  ```
447
502
  ├── index.js Host half: usage capture, aggregation, HTTP API, agent tools
448
503
  ├── store.js Storage layer: 180-day detail retention + permanent daily rollups + atomic writes (with lock retries; pure logic, unit-testable)
449
- ├── pricing.js Pricing & tokens: price tables, peak/off-peak billing, vision model, peak-phase math (pure logic, unit-testable)
450
- ├── config.js Config layer: defaults & normalization for the peak-price notice and cloud sync (pure logic, unit-testable)
504
+ ├── pricing.js Pricing & tokens: price tables, peak/off-peak billing, vision model, peak-phase math, subscription gate (pure logic, unit-testable)
505
+ ├── config.js Config layer: defaults & normalization for the peak-price notice, cloud sync, UI toggles and Volcengine credentials (pure logic, unit-testable)
506
+ ├── volcengine.js Volcengine Ark quota: HMAC-SHA256 signing, response parsing, credential normalization (pure logic, unit-testable)
451
507
  ├── sync.js Cloud sync engine: device identity, incremental watermark, idempotent batches, backoff
452
508
  ├── schema.js Host settings schema (the plugin-config card fields)
453
509
  ├── view.js Three-state view merge: normalizes This machine / + cloud / Cloud only (shared by browser and tests)
@@ -458,7 +514,7 @@ Either way: if only the UI (`client.js`) changed, a **hard browser refresh** (Cm
458
514
  ├── README.md Chinese documentation
459
515
  ├── README.en.md English documentation
460
516
  ├── CHANGELOG.md Changelog (Chinese)
461
- ├── test/ Unit tests (storage / pricing / config / recompute / render / cloud read; node test/*.test.js)
517
+ ├── test/ Unit tests (storage / pricing / volcengine / config / recompute / render / cloud read; node test/*.test.js)
462
518
  └── docs/ README screenshots and design notes
463
519
  ```
464
520
 
package/README.md CHANGED
@@ -37,10 +37,11 @@
37
37
  | 📊 | **可视化仪表盘** | 设置页新增「花费统计」:概览卡片、消费柱状图(按峰谷/按模型)、分模型的请求次数与 Tokens 图表,**全部支持鼠标悬停查看明细** |
38
38
  | 🧭 | **多机汇总(云端同步)** | 可对接**自建云端服务**(独立仓库 `dsh-cost-cloud`,零运行时依赖):多台电脑的用量汇总到一处,看板顶部出现 **本机 / 本机+云端 / 仅云端** 三态开关,并支持**设备 × Agent 矩阵**(行合计 = 列合计 = 总计);上报内容仅 token 数、费用、时间戳与标识符,可选会话脱敏 |
39
39
  | 🔥 | **用量热力图** | 设置页新增「Token 用量统计」:类 Codex 的 **26 周日用量方格热图**,按天着色(输入 / 缓存 / 输出 / 费用),悬停看当日明细、今天高亮描边,顶部显示全时段累计;**跟随三态视图**——「本机+云端 / 仅云端」下自动并入云端按天用量(卡片标题右侧标注当前口径) |
40
- | 📈 | **订阅配额监控** | Kimi Coding Plan 等订阅套餐:本周配额、5 小时滚动窗口限额、等效按量费用参考 |
40
+ | 📈 | **订阅配额监控** | Kimi Coding Plan、**火山方舟 Coding Plan** 等订阅套餐:配额进度条、重置倒计时、等效按量费用参考。火山方舟走管控面 OpenAPI(HMAC 签名),需 AccessKeyID + SecretAccessKey |
41
41
  | 💳 | **余额查询** | 一键查询 DeepSeek 官方账户余额(总余额 / 充值 / 赠送 / 状态) |
42
42
  | 🤖 | **Agent 工具** | 直接在对话里问:"我现在花了多少钱?"——Agent 会调用 `cost_stats` / `cost_prices` 等工具回答 |
43
43
  | 🔻 | **状态栏** | 聊天输入框下方实时显示:**本会话花费**(胶囊分段:本会话 / 订阅套餐 / 分模型),按会话实际用到的模型与订阅拆分,**多模型默认折叠只显示 top2,点击展开全部明细**;订阅显示具体套餐名,不再展示配额与调用次数 |
44
+ | 👁️ | **界面显示开关** | 输入框上方的花费胶囊、侧边栏峰谷时段条、设置页「花费统计」看板**三个落点各自可关**(设置 → 插件 → 插件配置 → 花费统计 → 界面显示),勾选即刻生效;**只影响显示**,记账、云端同步与 Agent 工具照常,配置卡片本身不受开关控制 |
44
45
  | 💾 | **本地持久化** | 数据存本机 `~/.dsh/storages/cost-tracker-records.json`,重启不丢、不上传;**明细保留最近 180 天,更早自动压缩为永久日汇总,全时段统计永远精确且内存/磁盘有界** |
45
46
  | 📤 | **CSV 导出** | 一键导出明细 + 日汇总(purpose=rollup),方便用 Excel / Numbers 做进一步分析 |
46
47
 
@@ -213,6 +214,21 @@ docker compose up -d # 打开 http://<服务器>:8787 ,在「设置」页
213
214
 
214
215
  **隐私**:只上报 token 数量、费用、时间戳与标识符(不涉及 prompt / 回复 / 文件内容);可在配置卡开启「会话脱敏」(`sessionId` 上报前替换为不可逆哈希)与「不含 purpose」。
215
216
 
217
+ ### 界面显示(v1.8.12,可选)
218
+
219
+ 不想在界面上看到插件?**设置 → 插件 → 插件配置 → 花费统计 → 界面显示**里三个开关**各自独立**、**勾选即刻生效**(无需点「保存」,也无需重启 dsh):
220
+
221
+ | 开关 | 关掉之后 |
222
+ | --- | --- |
223
+ | 输入框上方的花费胶囊 | 会话输入区不再显示本会话花费与模型明细 |
224
+ | 侧边栏峰谷时段条 | 侧边栏底部的档位 / 倒计时消失(峰谷切换弹窗与系统通知一并停用;只想留提醒不想要时段条,请改用「峰谷计价与提示」里的提示开关) |
225
+ | 设置页「花费统计」看板 | 设置页左侧不再出现该入口(记账与云端同步照常;关掉后该页只留一句重新打开的指引) |
226
+
227
+ - **只影响显示**:记账、落盘、云端同步与 Agent 工具(`cost_stats` 等)全部照常工作;
228
+ - **插件配置卡片本身不受这三个开关控制** —— 否则关掉之后就没有入口能再打开了;
229
+ - 取值为「只有显式 `false` 才隐藏」,缺省即显示。老配置文件里没有这几个键,**升级后界面与升级前一致**;
230
+ - 落盘在同一份 `~/.dsh/storages/cost-tracker-config.json`(键名 `uiDockEnabled` / `uiPeakEnabled` / `uiDashboardEnabled`),与峰谷、云端字段互不覆盖。
231
+
216
232
  ### HTTP API(供其他工具调用)
217
233
 
218
234
  全部为 `POST` + JSON,监听本机地址:
@@ -221,14 +237,17 @@ docker compose up -d # 打开 http://<服务器>:8787 ,在「设置」页
221
237
  POST /api/cost-tracker/summary 概览(含本会话按模型拆分 / 订阅)
222
238
  POST /api/cost-tracker/dashboard 仪表盘数据
223
239
  POST /api/cost-tracker/usage 用量热力图(全时段累计 + 按天 token 聚合)
224
- POST /api/cost-tracker/peak 峰谷相位快照(当前档位/下次切换/配置)
240
+ POST /api/cost-tracker/peak 峰谷相位快照(当前档位/下次切换/配置/界面显示开关)
225
241
  POST /api/cost-tracker/peak-config 保存峰谷计价提示配置
226
- POST /api/cost-tracker/sync 云端同步状态(设备 ID/水位/待上报/最近错误)
242
+ POST /api/cost-tracker/ui-config 保存界面显示开关(胶囊/时段条/看板,可只传要改的键)
243
+ POST /api/cost-tracker/sync 云端同步状态(设备 ID/水位/待上报/最近错误/界面显示开关)
227
244
  POST /api/cost-tracker/sync-now 立即同步(传 {"full":true} 全量补传)
228
245
  POST /api/cost-tracker/sync-test 测试云端连接
229
246
  POST /api/cost-tracker/sync-config 保存云端同步配置
230
247
  POST /api/cost-tracker/cloud 云端只读聚合(route/days/excludeSelf/devices/sources)
231
248
  POST /api/cost-tracker/kimi-usage Kimi 订阅配额
249
+ POST /api/cost-tracker/volcengine-usage 火山方舟 Coding Plan 配额(5 小时/周/月窗口)
250
+ POST /api/cost-tracker/volcengine-config 保存火山方舟 AK/SK(只回显「是否已配置」,不回显密钥)
232
251
  POST /api/cost-tracker/balance 账户余额
233
252
  POST /api/cost-tracker/prices 单价表(按计费时代分版)
234
253
  POST /api/cost-tracker/recompute 按计费时代重算已入库记录(默认只试算,传 {"apply":true} 落盘)
@@ -243,6 +262,26 @@ POST /api/cost-tracker/export 导出 CSV
243
262
 
244
263
  > 这里只列重要版本;逐版完整记录见 [`CHANGELOG.md`](./CHANGELOG.md)。
245
264
 
265
+ ### v1.8.14(2026-09-26)
266
+
267
+ **新增:火山方舟 Coding Plan 订阅支持(配额监控 + 等效费用)**
268
+
269
+ - **配额面板**:设置页新增「订阅套餐用量 · 火山方舟 Coding Plan」,经方舟**管控面 OpenAPI**(`open.volcengineapi.com`,`Action=GetCodingPlanUsage`,HMAC-SHA256 签名)拉取 **5 小时 / 周 / 月**三档窗口,显示已用百分比、绝对量(Cap 折算)与重置倒计时。Action 按 `GetCodingPlanUsage → GetAFPUsage → GetUsageDetails → GetPersonalPlan` 顺序兜底,Agent Plan 账号自动回落 AFP 取数;
270
+ - **等效费用**:火山套餐内的调用计入「订阅等效按量费用」,不再被误标为「按量计费 · 价格为估算」;
271
+ - **修掉订阅门卫缺陷(重要)**:原先只按 provider 名判定订阅,对该 provider 的**所有**模型一律套订阅价。火山方舟的套餐内 / 套餐外模型混在同一个 provider 下,这会把按量调用错记成订阅、使其金额从「真实花费」里消失。现改为「provider 命中 + 模型白名单」双重限定,并区分**专属订阅端点**(baseURL 指向 `/api/coding/v3`,整档计订阅)与**泛 `volcengine`**(仅白名单内模型计订阅,接入点 `ep-*` 一律按量)。Kimi 的既有行为逐字节不变;
272
+ - **修掉凭据文件读取缺陷(重要)**:`.credentials.yaml` 实际把键**缩进**存放在 `refs:` 段下,而原解析器只匹配行首无缩进的键 —— 这一路兜底一直静默失效(有宿主凭据服务时被掩盖)。现已支持缩进与 `refs` 段定位,并跟随 `DSH_HOME`;顺带修掉硬编码 `~/.dsh` 导致重定向部署下永远读不到的问题;
273
+ - **凭据发现链**:配置卡片 AK/SK → DSH 凭据库 → `.credentials.yaml`(`VOLC_ACCESSKEY` / `VOLC_SECRETKEY` 及多种变体名)→ 环境变量。**密钥永不出现在任何响应里**,`volcengine-config` 只回「是否已配置」;
274
+ - **失败一律中性提示**:无凭据、无订阅、权限不足(需 `ArkReadOnlyAccess` + `BillingCenterReadOnlyAccess`)、接口结构变化都只回中性提示,不影响记账 / 同步 / 其它功能;只跑 DeepSeek 或 Kimi 的用户界面**完全不变**(面板按需出现);
275
+ - 新增 `volcengine.js`(签名 / 解析 / 查询,纯函数可独立测试)与两个测试文件:签名与火山官方 demo 逐字节一致的固定向量、四种响应形态、**0.5% 不被放大成 50%**、密钥零外泄、缓存 TTL、失败路径软降级。真机核验通过(`GetCodingPlanUsage` 返回 `Status: Running` 与三档窗口)。
276
+
277
+ ### v1.8.13(2026-09-25)
278
+
279
+ **新增:可以关掉插件在前端的显示(三个落点各自独立)**
280
+
281
+ - 设置 → 插件 → 插件配置 → 花费统计 → **界面显示**:输入框上方的花费胶囊、侧边栏峰谷时段条、设置页「花费统计」看板三个落点**各自可关**,勾选即刻生效(无需点「保存」、无需重启 dsh),另有「全部显示」一键恢复。
282
+ - **只影响显示**:记账、云端同步与 Agent 工具照常;配置卡片本身不受这三个开关控制(否则关掉就没入口再打开)。
283
+ - **安全默认**:只有显式 `false` 才隐藏,缺省即显示 —— 老配置升级后界面与升级前一致。详见上方「界面显示」一节。
284
+
246
285
  ### v1.8.12(2026-09-19)
247
286
 
248
287
  **修复:热力图不跟随三态视图(本机+云端下屏内自相矛盾)+ `cost_stats scope=cloud|both` 崩溃**
@@ -429,6 +468,23 @@ POST /api/cost-tracker/export 导出 CSV
429
468
  **Q:订阅套餐(kimi-coding)的"等效费用"是什么意思?**
430
469
  订阅制不按量扣费。插件按内置单价估算出"如果这些调用走按量计费会花多少钱",仅供你评估订阅是否划算,**不是真实扣费**。
431
470
 
471
+ **Q:火山方舟 Coding Plan 的配额怎么接?需要哪种凭据?**
472
+ 配额查询走的是方舟**管控面** OpenAPI(`open.volcengineapi.com`,HMAC-SHA256 签名),需要的是一对**火山引擎访问密钥**:
473
+
474
+ 1. 火山引擎控制台 → **IAM → 用户 → 密钥**,创建 AccessKeyID / SecretAccessKey;
475
+ 2. 给该子用户授予 **`ArkReadOnlyAccess`** 与 **`BillingCenterReadOnlyAccess`**(只读,足够查询用量);
476
+ 3. 让插件拿到这对密钥(任选其一,按优先级):
477
+ - **设置 → 插件 → 插件配置 → 花费统计** 里填 `火山引擎 AccessKeyID` / `SecretAccessKey`(密钥不回显);或
478
+ - 写进 `~/.dsh/.credentials.yaml` 的 `refs:` 段,键名 `VOLC_ACCESSKEY` / `VOLC_SECRETKEY`(也兼容 `VOLCENGINE_ACCESS_KEY_ID`、`ARK_ACCESS_KEY_ID` 等写法);或
479
+ - 设为同名环境变量。
480
+
481
+ > ⚠️ 这与**推理用的 ARK API Key**(形如 UUID、配在 provider 的 `apiKey` / `apiKeyEnv`)是**两套完全不同的凭据**,不能混填。推理 Key 无法查询配额,会得到 401/403。
482
+
483
+ 面板显示 5 小时 / 周 / 月三档窗口的已用百分比与重置倒计时。Coding Plan 的用量口径是**百分比**(实测长期在 0.05%–0.4% 量级),所以数值保留两位小数,避免显示成 0%。若账号实际是 Agent Plan,插件会自动回落到 `GetAFPUsage` 接口取数。没有订阅、没有凭据、权限不足都属于**中性提示**,不影响记账、同步与其它功能。
484
+
485
+ **Q:为什么火山方舟的模型有的算「订阅」、有的算「按量」?**
486
+ 同一个 provider 下套餐内外模型可能混在一起:凡是 **baseURL 指向 `ark.cn-beijing.volces.com/api/coding/v3`** 的 provider(专属订阅入口),其全部调用都计为订阅;而泛 `volcengine` provider 下,只有套餐内模型(豆包系、GLM 系、Kimi 系、DeepSeek 系、MiniMax 系及各档 `ark-code-*`)算订阅,**接入点 id(形如 `ep-2026xxxx`)一律按量**。这样按量调用不会被误记成订阅而让真实花费缩水。
487
+
432
488
  **Q:金额和官方账单对不上?**
433
489
  插件在本地按内置单价表估算,可能与官方实际计费存在细微差异(如官方价格调整、阶梯定价)。精确金额请以官方账单为准。余额以「余额查询」实时拉取的官方数据为准。
434
490
 
@@ -448,8 +504,9 @@ POST /api/cost-tracker/export 导出 CSV
448
504
  ```
449
505
  ├── index.js Host 半端:用量采集、聚合、HTTP API、Agent 工具
450
506
  ├── store.js 存储层:明细保留 + 永久日汇总 + 原子落盘(含占用重试,纯逻辑可独立测试)
451
- ├── pricing.js 定价与 Token 层:单价表、峰谷计价、视觉模型、峰值相位(纯逻辑,可独立测试)
452
- ├── config.js 配置层:峰谷计价提示 + 云端同步的默认值与规范化(纯逻辑,可独立测试)
507
+ ├── pricing.js 定价与 Token 层:单价表、峰谷计价、视觉模型、峰值相位、订阅门卫(纯逻辑,可独立测试)
508
+ ├── config.js 配置层:峰谷计价提示 + 云端同步 + 界面显示 + 火山凭据的默认值与规范化(纯逻辑,可独立测试)
509
+ ├── volcengine.js 火山方舟配额查询:HMAC-SHA256 签名、响应解析、凭据归一(纯逻辑,可独立测试)
453
510
  ├── sync.js 云端同步引擎:设备身份、增量水位、幂等批次、退避重试
454
511
  ├── schema.js 宿主设置空间的 schema(插件配置卡片字段)
455
512
  ├── view.js 三态视图合并:本机 / 本机+云端 / 仅云端的口径归一化(浏览器与测试共用)
@@ -460,7 +517,7 @@ POST /api/cost-tracker/export 导出 CSV
460
517
  ├── README.md 中文说明文档
461
518
  ├── README.en.md 英文说明文档
462
519
  ├── CHANGELOG.md 更新记录(中文)
463
- ├── test/ 单元测试(storage / pricing / config / recompute / 渲染 / 云端读取,node test/*.test.js)
520
+ ├── test/ 单元测试(storage / pricing / volcengine / config / recompute / 渲染 / 云端读取,node test/*.test.js)
464
521
  └── docs/ README 截图与设计文档
465
522
  ```
466
523