@angelyeye/dsh-cost-tracker 1.8.13 → 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,61 @@
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
+
5
60
  ## v1.8.13(2026-09-25)
6
61
 
7
62
  **新增:可以关掉插件在前端的显示(三个落点各自独立)**
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 |
@@ -245,6 +245,8 @@ POST /api/cost-tracker/sync-test Test the cloud connection
245
245
  POST /api/cost-tracker/sync-config Save cloud sync config
246
246
  POST /api/cost-tracker/cloud Read-only cloud aggregation (route/days/excludeSelf/devices/sources)
247
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)
248
250
  POST /api/cost-tracker/balance Account balance
249
251
  POST /api/cost-tracker/prices Price table (versioned by pricing era)
250
252
  POST /api/cost-tracker/recompute Re-price stored records by era (dry-run unless {"apply":true})
@@ -259,6 +261,18 @@ Example: `curl -X POST http://127.0.0.1:3080/api/cost-tracker/summary -d '{}'`
259
261
 
260
262
  > Highlights only — the full version-by-version history lives in [`CHANGELOG.md`](./CHANGELOG.md) (Chinese).
261
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
+
262
276
  ### v1.8.13 (2026-09-25)
263
277
 
264
278
  **Added: the plugin's front-end surfaces can now be turned off (three independent switches)**
@@ -451,6 +465,23 @@ The plugin starts **silently by default**. Set the environment variable `DSH_COS
451
465
  **Q: What does "equivalent cost" mean for subscription models (kimi-coding)?**
452
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**.
453
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
+
454
485
  **Q: The amounts don't exactly match my official bill?**
455
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.
456
487
 
@@ -470,8 +501,9 @@ Either way: if only the UI (`client.js`) changed, a **hard browser refresh** (Cm
470
501
  ```
471
502
  ├── index.js Host half: usage capture, aggregation, HTTP API, agent tools
472
503
  ├── store.js Storage layer: 180-day detail retention + permanent daily rollups + atomic writes (with lock retries; pure logic, unit-testable)
473
- ├── pricing.js Pricing & tokens: price tables, peak/off-peak billing, vision model, peak-phase math (pure logic, unit-testable)
474
- ├── 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)
475
507
  ├── sync.js Cloud sync engine: device identity, incremental watermark, idempotent batches, backoff
476
508
  ├── schema.js Host settings schema (the plugin-config card fields)
477
509
  ├── view.js Three-state view merge: normalizes This machine / + cloud / Cloud only (shared by browser and tests)
@@ -482,7 +514,7 @@ Either way: if only the UI (`client.js`) changed, a **hard browser refresh** (Cm
482
514
  ├── README.md Chinese documentation
483
515
  ├── README.en.md English documentation
484
516
  ├── CHANGELOG.md Changelog (Chinese)
485
- ├── 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)
486
518
  └── docs/ README screenshots and design notes
487
519
  ```
488
520
 
package/README.md CHANGED
@@ -37,7 +37,7 @@
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,点击展开全部明细**;订阅显示具体套餐名,不再展示配额与调用次数 |
@@ -246,6 +246,8 @@ POST /api/cost-tracker/sync-test 测试云端连接
246
246
  POST /api/cost-tracker/sync-config 保存云端同步配置
247
247
  POST /api/cost-tracker/cloud 云端只读聚合(route/days/excludeSelf/devices/sources)
248
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(只回显「是否已配置」,不回显密钥)
249
251
  POST /api/cost-tracker/balance 账户余额
250
252
  POST /api/cost-tracker/prices 单价表(按计费时代分版)
251
253
  POST /api/cost-tracker/recompute 按计费时代重算已入库记录(默认只试算,传 {"apply":true} 落盘)
@@ -260,6 +262,18 @@ POST /api/cost-tracker/export 导出 CSV
260
262
 
261
263
  > 这里只列重要版本;逐版完整记录见 [`CHANGELOG.md`](./CHANGELOG.md)。
262
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
+
263
277
  ### v1.8.13(2026-09-25)
264
278
 
265
279
  **新增:可以关掉插件在前端的显示(三个落点各自独立)**
@@ -454,6 +468,23 @@ POST /api/cost-tracker/export 导出 CSV
454
468
  **Q:订阅套餐(kimi-coding)的"等效费用"是什么意思?**
455
469
  订阅制不按量扣费。插件按内置单价估算出"如果这些调用走按量计费会花多少钱",仅供你评估订阅是否划算,**不是真实扣费**。
456
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
+
457
488
  **Q:金额和官方账单对不上?**
458
489
  插件在本地按内置单价表估算,可能与官方实际计费存在细微差异(如官方价格调整、阶梯定价)。精确金额请以官方账单为准。余额以「余额查询」实时拉取的官方数据为准。
459
490
 
@@ -473,8 +504,9 @@ POST /api/cost-tracker/export 导出 CSV
473
504
  ```
474
505
  ├── index.js Host 半端:用量采集、聚合、HTTP API、Agent 工具
475
506
  ├── store.js 存储层:明细保留 + 永久日汇总 + 原子落盘(含占用重试,纯逻辑可独立测试)
476
- ├── pricing.js 定价与 Token 层:单价表、峰谷计价、视觉模型、峰值相位(纯逻辑,可独立测试)
477
- ├── config.js 配置层:峰谷计价提示 + 云端同步的默认值与规范化(纯逻辑,可独立测试)
507
+ ├── pricing.js 定价与 Token 层:单价表、峰谷计价、视觉模型、峰值相位、订阅门卫(纯逻辑,可独立测试)
508
+ ├── config.js 配置层:峰谷计价提示 + 云端同步 + 界面显示 + 火山凭据的默认值与规范化(纯逻辑,可独立测试)
509
+ ├── volcengine.js 火山方舟配额查询:HMAC-SHA256 签名、响应解析、凭据归一(纯逻辑,可独立测试)
478
510
  ├── sync.js 云端同步引擎:设备身份、增量水位、幂等批次、退避重试
479
511
  ├── schema.js 宿主设置空间的 schema(插件配置卡片字段)
480
512
  ├── view.js 三态视图合并:本机 / 本机+云端 / 仅云端的口径归一化(浏览器与测试共用)
@@ -485,7 +517,7 @@ POST /api/cost-tracker/export 导出 CSV
485
517
  ├── README.md 中文说明文档
486
518
  ├── README.en.md 英文说明文档
487
519
  ├── CHANGELOG.md 更新记录(中文)
488
- ├── test/ 单元测试(storage / pricing / config / recompute / 渲染 / 云端读取,node test/*.test.js)
520
+ ├── test/ 单元测试(storage / pricing / volcengine / config / recompute / 渲染 / 云端读取,node test/*.test.js)
489
521
  └── docs/ README 截图与设计文档
490
522
  ```
491
523
 
package/client.js CHANGED
@@ -913,6 +913,65 @@ window.__ModuleLoader__.load({
913
913
  e("div", { className: "cost-hint", style: { marginTop: "10px" } }, "订阅用量统计:" + stats + "(订阅已覆盖,等效费用仅供参考)"));
914
914
  }
915
915
 
916
+ // 火山方舟 Coding Plan 配额面板。
917
+ // 与 Kimi 面板的关键差别:管控面**主口径是百分比**(Level + Percent + Cap),
918
+ // 实测 Percent 常落在 0.05–0.4 这种小数区间,且没有各模型的 used/limit 绝对值。
919
+ // 所以不能直接套 progressBar 的「整数 / 总数」文案,这里用同一套
920
+ // cost-bar-track / cost-bar-fill 样式自己画百分比条,视觉保持一致。
921
+ function pctBar(label, percent, resetsAt, now, used, quota) {
922
+ const pct = Math.max(0, Math.min(100, Number(percent) || 0));
923
+ const color = pct >= 90 ? RED : pct >= 70 ? AMBER : BLUE;
924
+ // 百分比按实际精度展示(0.05% 也要看得见,不能四舍五入成 0%)
925
+ const pctText = pct > 0 && pct < 1 ? pct.toFixed(2).replace(/0+$/, "").replace(/\.$/, "") : String(Math.round(pct * 100) / 100);
926
+ // 有 Cap 时补一句绝对量:百分比太小的时候更直观
927
+ const absText = (typeof used === "number" && typeof quota === "number" && quota > 0)
928
+ ? (" · " + fmtInt(used) + " / " + fmtInt(quota)) : "";
929
+ return e("div", { style: { marginTop: "10px" } },
930
+ e("div", { className: "cost-row" },
931
+ e("span", { className: "cost-hint" }, label),
932
+ e("span", { className: "cost-spacer" }),
933
+ e("span", { style: { fontVariantNumeric: "tabular-nums" } },
934
+ "已用 " + pctText + "% · 剩余 " + (Math.round((100 - pct) * 100) / 100) + "%" + absText)),
935
+ e("div", { className: "cost-bar-track" },
936
+ e("div", { className: "cost-bar-fill", style: { width: Math.max(pct, pct > 0 ? 1 : 0) + "%", background: color } })),
937
+ resetsAt ? e("div", { className: "cost-hint", style: { marginTop: "4px" } }, countdown(resetsAt, now)) : null);
938
+ }
939
+
940
+ function volcenginePanel(volc, dash, now, onForce) {
941
+ const ok = volc && volc.ok;
942
+ let body;
943
+ if (!volc) {
944
+ body = e("div", { className: "cost-hint", style: { marginTop: "8px" } }, "配额查询中…");
945
+ } else if (!volc.ok) {
946
+ body = e("div", { style: { marginTop: "8px" } },
947
+ e("div", { className: "cost-err" }, "配额查询不可用:" + (volc.error || "未知错误")),
948
+ e("div", { className: "cost-hint", style: { marginTop: "4px" } },
949
+ "配额查询走方舟**管控面** OpenAPI,需要火山引擎 AccessKeyID / SecretAccessKey"
950
+ + "(IAM 子用户授予 ArkReadOnlyAccess + BillingCenterReadOnlyAccess),"
951
+ + "与推理用的 ARK API Key 是两套凭据。当前尝试的变量:" + (volc.keyEnv || "未知")
952
+ + "(来源:" + (volc.keySource || "无") + ")。"));
953
+ } else {
954
+ const list = volc.windowList || [];
955
+ if (list.length === 0) {
956
+ body = e("div", { className: "cost-hint", style: { marginTop: "8px" } }, "接口未返回任何用量窗口(可能账号没有生效中的 Coding Plan)。");
957
+ } else {
958
+ body = e("div", null, list.map(w => e("div", { key: w.name }, pctBar(w.label, w.percent, w.resetsAt, now, w.used, w.quota))));
959
+ }
960
+ }
961
+ const stats = dash
962
+ ? "累计请求 " + fmtInt(dash.subCalls) + " 次 · Tokens " + fmtInt(dash.subTokens) + " · 等效按量费用 ¥" + fmtMoney(dash.subEquivalent)
963
+ : "加载中…";
964
+ return e("div", { className: "cost-panel" },
965
+ e("div", { className: "cost-row" },
966
+ e("span", { className: "cost-panel-title" }, "订阅套餐用量 · 火山方舟 Coding Plan"),
967
+ ok && volc.action ? e("span", { className: "cost-badge" }, volc.action) : null,
968
+ e("span", { className: "cost-spacer" }),
969
+ e("button", { className: "cost-btn", onClick: onForce }, "刷新配额")),
970
+ body,
971
+ e("div", { className: "cost-hint", style: { marginTop: "10px" } },
972
+ "订阅用量统计:" + stats + "(订阅已覆盖,等效费用仅供参考)"));
973
+ }
974
+
916
975
  function kv(k, v) {
917
976
  return e("span", { style: { marginRight: "18px" } },
918
977
  e("span", { className: "cost-hint" }, k + ":"),
@@ -1669,6 +1728,7 @@ window.__ModuleLoader__.load({
1669
1728
  const [dash, setDash] = useState(null);
1670
1729
  const [dashErr, setDashErr] = useState("");
1671
1730
  const [kimi, setKimi] = useState(null);
1731
+ const [volc, setVolc] = useState(null);
1672
1732
  const [balance, setBalance] = useState(null);
1673
1733
  const [tab, setTab] = useState("period");
1674
1734
  const [scheme, setSchemeState] = useState(() => {
@@ -1762,6 +1822,9 @@ window.__ModuleLoader__.load({
1762
1822
  function loadKimi(force) {
1763
1823
  apiCall("kimi-usage", { force: !!force }).then(v => setKimi(v)).catch(() => {});
1764
1824
  }
1825
+ function loadVolc(force) {
1826
+ apiCall("volcengine-usage", { force: !!force }).then(v => setVolc(v)).catch(() => {});
1827
+ }
1765
1828
  function loadUsage() {
1766
1829
  apiCall("usage", {}).then(v => {
1767
1830
  if (v && v.ok) { setUsage(v); setUsageErr(""); }
@@ -1786,12 +1849,13 @@ window.__ModuleLoader__.load({
1786
1849
  else setUsageErr(v && v.error ? String(v.error) : "数据加载失败");
1787
1850
  }).catch(err => setUsageErr(String(err && err.message ? err.message : err)));
1788
1851
  apiCall("kimi-usage", { force: false }).then(v => setKimi(v)).catch(() => {});
1852
+ apiCall("volcengine-usage", { force: false }).then(v => setVolc(v)).catch(() => {});
1789
1853
  loadCloudUsage(view);
1790
1854
  apiCall("balance", {}).then(v => { setBalance(v); setBusy(false); }).catch(() => setBusy(false));
1791
1855
  }
1792
1856
 
1793
1857
  useEffect(() => { loadDash(days); }, [days]);
1794
- useEffect(() => { loadKimi(false); loadBalance(""); loadUsage(); loadSync(); }, []);
1858
+ useEffect(() => { loadKimi(false); loadVolc(false); loadBalance(""); loadUsage(); loadSync(); }, []);
1795
1859
  // 视图切换:local+cloud 需要额外拉「排除本机」的云端聚合、矩阵与按天用量明细
1796
1860
  useEffect(() => { loadCloud(days, view); loadCloudMatrix(days); loadCloudUsage(view); }, [view, days]);
1797
1861
  useEffect(() => {
@@ -1831,6 +1895,11 @@ window.__ModuleLoader__.load({
1831
1895
  pending: sync ? sync.pending : 0,
1832
1896
  };
1833
1897
 
1898
+ // 火山方舟面板只在「用得上」时出现:存在火山订阅调用(宿主判定并在
1899
+ // summary 里回传 volcengineActive),或已有窗口数据 / 已尝试过凭据。
1900
+ // 只跑 DeepSeek 或 Kimi 的用户界面保持不变,不会被一个无关面板撑长。
1901
+ const showVolc = !!(volc || (viewDash && viewDash.volcengineActive === true));
1902
+
1834
1903
  return e("div", { className: "cost-wrap" },
1835
1904
  e("div", { className: "cost-h1" }, pluginIcon(18), "花费统计"),
1836
1905
  filterRow(days, setDays, onExport, onRefresh, msg, busy, dash ? dash.peakWindows : "周一至周五 9:00-12:00 · 14:00-18:00(周末全天闲时)", viewCtl),
@@ -1864,6 +1933,7 @@ window.__ModuleLoader__.load({
1864
1933
  : usageErr ? e("div", { className: "cost-err" }, "加载失败:" + usageErr)
1865
1934
  : e("div", { className: "cost-hint" }, "加载中…"))),
1866
1935
  subPanel(kimi, viewDash, now, () => loadKimi(true)),
1936
+ showVolc ? volcenginePanel(volc, viewDash, now, () => loadVolc(true)) : null,
1867
1937
  balancePanel(balance, manualKey, setManualKey, k => loadBalance(k)),
1868
1938
  viewDash ? modelSections(viewDash) : null,
1869
1939
  viewDash ? recentPanel(viewDash) : null,
package/config.js CHANGED
@@ -50,6 +50,15 @@
50
50
  // 真值语义与 peakEnabled 相反:null/undefined → true(显隐是从 v1.8.12 才有的新
51
51
  // 能力,老配置文件里没有这几个键,必须保持默认全部可见),只有显式 false 才隐藏。
52
52
  // 这样两个方向上都安全:老配置升级后界面不变,新配置关掉就是关掉。
53
+ //
54
+ // 字段(火山方舟配额,v1.8.14):
55
+ // volcengineAccessKeyId 火山引擎 AccessKeyID(管控面 AK,非方舟推理 API Key)
56
+ // volcengineSecretAccessKey 火山引擎 SecretAccessKey(role=secret,不回显明文)
57
+ //
58
+ // 两者**留空即回落到凭据发现链**(DSH 凭据库 → .credentials.yaml 文件),
59
+ // 因此老配置文件升级后为零改动、开箱可用。配额查询走方舟管控面 OpenAPI,
60
+ // 需要 IAM 子用户具备 ArkReadOnlyAccess + BillingCenterReadOnlyAccess。
61
+ // 注意与推理用的 ARK API Key 是**两套不同的凭据**,不要混填。
53
62
  // ============================================================
54
63
 
55
64
  /** 默认峰谷计价生效时间(UTC;两档方案已即时生效,门控恒通过) */
@@ -131,6 +140,18 @@ export function defaultUiConfig() {
131
140
  return out
132
141
  }
133
142
 
143
+ /**
144
+ * 火山方舟配额凭据默认配置(**留空**)。
145
+ * 留空不是「缺失」,而是明确表示「走凭据发现链」——老配置文件里没有这两个键,
146
+ * 升级后读出来就是空串,行为与升级前完全一致(配额面板自动从凭据库取 AK/SK)。
147
+ */
148
+ export function defaultVolcengineConfig() {
149
+ return {
150
+ volcengineAccessKeyId: '',
151
+ volcengineSecretAccessKey: '',
152
+ }
153
+ }
154
+
134
155
  function bool(v, fallback) { return typeof v === 'boolean' ? v : fallback }
135
156
  function intIn(v, lo, hi, fallback) { return typeof v === 'number' && Number.isInteger(v) && v >= lo && v <= hi ? v : fallback }
136
157
 
@@ -202,9 +223,28 @@ export function normalizeUiConfig(raw) {
202
223
  return out
203
224
  }
204
225
 
226
+ /**
227
+ * 规范化火山方舟配额凭据。
228
+ * 只做长度与类型收敛,**不校验格式**:AK/SK 的形态由火山引擎决定,
229
+ * 这里猜错反而会把合法凭据判为非法。空串 = 未配置 = 走凭据发现链。
230
+ */
231
+ export function normalizeVolcengineConfig(raw) {
232
+ const def = defaultVolcengineConfig()
233
+ if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return def
234
+ return {
235
+ volcengineAccessKeyId: typeof raw.volcengineAccessKeyId === 'string' ? raw.volcengineAccessKeyId.trim().slice(0, 256) : def.volcengineAccessKeyId,
236
+ volcengineSecretAccessKey: typeof raw.volcengineSecretAccessKey === 'string' ? raw.volcengineSecretAccessKey.trim().slice(0, 256) : def.volcengineSecretAccessKey,
237
+ }
238
+ }
239
+
205
240
  /** 合并规范化:一份配置文件同时承载峰谷、云端同步与界面显示三组字段 */
206
241
  export function normalizePluginConfig(raw) {
207
- return Object.assign(normalizePeakConfig(raw), normalizeCloudConfig(raw), normalizeUiConfig(raw))
242
+ return Object.assign(
243
+ normalizePeakConfig(raw),
244
+ normalizeCloudConfig(raw),
245
+ normalizeUiConfig(raw),
246
+ normalizeVolcengineConfig(raw),
247
+ )
208
248
  }
209
249
 
210
250
  /**