# Changelog

[English](./CHANGELOG_EN.md) | **中文**

本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/) 格式,版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。

## 版本导航

| 版本 | 重点 |
|---|---|
| `1.2.3` | README 移除开发者安装方式与本地开发循环;升级提示的截图与"复制之后做什么"移入「升级」章节 |
| `1.2.2` | 截图全部换新(深/浅 × 中/英、角标峰谷、升级提示);npm 包不再携带截图,1376 KB → 66 KB |
| `1.2.1` | 面板内一键升级提示:页脚版本号在检测到新版本时变成可点击徽标,一键复制升级命令;新增 `updateCommand` 配置 |
| `1.2.0` | 今日用量修复(改用官网同源的 `by_api_key` 接口并按配置时区切天,「今日」不再恒为 0)、新增 `timezoneOffsetSec` 配置、面板语言开关、热力图默认收起、模型图例同时显示金额与 Token、英文漏译补齐与文案母语化、金额币种跟随账户、页脚版本号修正 |
| `1.1.1` | 版本更新提示(查 npm latest,仅提示)、修复深色模式按钮文字不可见、优化 userToken 获取说明 |
| `1.1.0` | 界面大改:用量热力图、模型环形图(日/周/月+翻看)、指标 3×2 网格、峰谷显示与边框光效、面板交互(点击外部关闭/淡入淡出)、“花费”统一改“金额” |
| `1.0.2` | 修复 npm 包名变更后的浏览器 bundle 注册 ID,补充一致性 CI 与稳定安装路径 |
| `1.0.1` | 更换 npm 包名、移除 `zod`、补充 Windows 安装与排障文档；已被 `1.0.2` 替代 |
| `1.0.0` | 宣布稳定版本,明确仅支持 DeepSeek 官方余额、用量和扣费数据 |
| `0.1.0` | 首个功能版本,提供余额角标、用量面板、Token 管理和刷新机制 |

## [1.2.3] - 2026-09-11

### 变更

- **README 不再包含开发者安装方式**:删除「方式三:固定标签的本地源码(开发者)」及其嵌套的「本地开发循环(`link:`)」——这两段属于作者本机的开发流程,不适合展示给最终用户;升级表格中的对应行、以及排障章节里指向 `file:` 绝对路径的指引一并清理
- **升级提示的截图与说明挪到「升级」章节**:三张升级相关截图从「界面截图」图库移到 `## 升级` 下新增的「面板内的一键升级提示」,并补全点击徽标之后的完整流程——命令进剪贴板 → 粘贴到终端执行 → **重启 `dsh web`**(宿主启动时才加载插件代码,这步不能省) → 硬刷新页面;同时说明徽标只复制文本、不执行命令、也不改动本机文件

### 说明

- 本版**无代码改动**,插件行为与 1.2.2 完全一致,仅文档调整

## [1.2.2] - 2026-09-11

### 变更

- **README 截图全部换新**:两份 README 的界面截图更新为 1.2.1 实拍 —— 深色/浅色 × 中文/English 四种面板组合、余额角标峰时(琥珀呼吸光)与谷时(绿色静光)、以及升级提示(有更新时的面板页脚徽标、徽标放大、点击后的「已复制」反馈)
- **npm 包不再携带截图**:实测 npm 官方页面会把 README 里的相对图片路径重写为 GitHub raw 地址(`raw.githubusercontent.com/<owner>/<repo>/HEAD/...`),图片本来就由 GitHub 提供,与 tarball 无关。因此把 `docs/images` 从 `package.json` 的 `files` 中移除:包体积 **1376 KB → 66 KB**(26 → 11 个文件),安装与升级更快;仓库内的截图以及 GitHub / npm 页面的显示完全不受影响

### 说明

- 本版**无代码改动**,插件行为与 1.2.1 完全一致,仅为文档与打包范围调整
- `scripts/release.sh` 的同步校验放宽为"允许本地领先"(CHANGELOG 已提交未推时也能发布),仍会拒绝与远端分叉的情况

## [1.2.1] - 2026-09-11

### 新增

- **面板内一键升级提示**:此前"发现新版本"只在设置弹层里,不打开设置就看不到。现在页脚版本号会在检测到新版本时变成**可点击徽标**(显示 `当前版本 → 可用版本`,琥珀色);点击**一键复制**升级命令——只写剪贴板,不执行任何命令、不改动本机任何文件。复制成功徽标变绿显示「✓ 已复制升级命令」,失败则提示到设置里手动复制(剪贴板不可用时自动回落到 `execCommand`)
- **`updateCommand` 配置**(默认 `dsh plugin --profile web update deepseek-harness-usage-dashboard`):徽标复制的命令与设置里的说明文案都引用它,换 profile 名或多环境部署只需改一处,不再两处硬编码

### 说明

- 徽标只在 npm 上存在更新版本(`update.hasNewer`)时出现;平时页脚仍是纯文本 `v1.2.0`,零打扰

- 这是"提示 + 复制命令",**不做自动安装**:升级仍需在终端执行(且替换文件后要重启 `dsh web` 才生效)
## [1.2.0] - 2026-09-11

### 修复

- **面板「今日金额 / 今日 Token / 请求数(日)」恒为 0,与官网用量页不一致**:宿主端原用旧接口 `GET /api/v0/usage/amount|cost?month=&year=` 取每日数据。实测该接口的「天」按 **UTC** 切分(它的 `2026-09-08` 行 == GMT+8 的 9/8 08:00 → 9/9 08:00),并且**当天的桶恒为 0**:北京时间当天 0:00–8:00 的用量被算进前一天的桶,当天则永远为空。现改用官网用量页同源的 `GET /api/v0/usage/by_api_key/amount|cost?start=&end=&tz=`(epoch 秒 + 时区偏移),按 GMT+8 切天且**当天实时更新**——「今日金额 / 今日 Token / 请求数」不再为 0,模型分布的「日」视图与热力图当天格也会正常显示;月首/月末不再有 8 小时的错位
- **旧接口保留为兜底**:新接口失败(含未公开接口改版)时自动回退旧接口,仍遵循 stale-while-error,失败时保留上次成功数据
- **「今天」不再跟随浏览器时区**:客户端此前用浏览器本地日期判定"今日"与"当前月",浏览器/系统时区被代理或系统设置改变时(例如走 Flash 代理出口),跨日时段会去查一个平台尚未产生数据的日期,「今日」又变成 0。现在面板的「今日金额 / 今日 Token / 请求数」、月份加载、热力图"今天"方框、环形图「日/周」翻看、底部「数据更新于」时刻全部改按宿主下发的 `timezoneOffsetSec`(默认 GMT+8)计算;热力图与环形图的日历运算同时改为与浏览器时区/DST 无关的 UTC 运算。宿主端的"当前月"与 `/usage-dashboard/month` 默认月也一并对齐
- **页脚版本号恒为 `v1.1.1`**:版本号此前被写死在词典里(`"footer.version": "v1.1.1"`),从未使用宿主上报的版本——即使插件已是 1.2.0,页脚仍显示 1.1.1。现在词典改为 `v{version}`、由 `update.currentVersion` 渲染;宿主在 npm 检查失败(离线)或用户关闭更新检查(`checkUpdate: false`)时也会带上本机版本号,页脚永远显示真实版本
- **英文界面下的两处排版问题**:①峰谷横幅把「标题 + 建议」拼成一整行不换行文本,英文较长时被省略号截断(显示成 `… · Defer to valley h`),现改为最多两行显示;②模型分布区块头是"标题 + 排序 tab + 日周月 tab"三个控件挤在一行且不允许换行,英文下 `Model breakdown` 与 `By amount / By tokens` 都被压成两行,现允许整组换行、文字不再拆词,并把英文标题缩短为 `Models`
- **官方余额接口偶发超时,页脚常驻红字**:实测一次 8s 挂起被 abort(`This operation was aborted`),而同机 `curl` 与 Node `fetch` 该域名均为 0.1s 级响应 —— 属瞬时抖动而非配置问题。现在官方余额失败后会自动**重试一次**(间隔 1s;未配置 API Key 时不重试),抖动通常自愈
- **官方余额失败时「充值 / 赠送」整行消失**:该行此前只取官方接口的 `balances[0]`。现在用平台 `get_user_summary` 的钱包兜底(`normal_wallets` → 充值、`bonus_wallets` → 赠送),两边都没有才隐藏该行
- **页脚「数据更新于」会卡在官方接口首次失败的时刻**:该时间此前优先取 `official.fetchedAt`,而宿主在官方余额失败时保留旧值,导致官方接口持续失败时时间不再前进。现在改为取真正展示数据的抓取时间(月度 → 平台余额 → 官方余额 → 客户端抓取时刻)

### 新增

- **面板语言开关**:设置里新增「面板语言」——「跟随界面 / 中文 / English」。默认跟随 Harness 界面语言(`ctx.locale`,宿主 `t` 原样透传);显式选择后只影响本面板,并记在浏览器 localStorage(刷新、重开浏览器仍在)。由于宿主 `register(ns, { zh, en })` 要求中英双词典,非中英语言(例如将来第三方注册的日语包)会按 locale 的 fallback 链回退到英文,不会露出键名;非法/未支持的语言值自动回落到「跟随界面」
- **热力图默认收起**:面板默认少占约 120px 高度;点击「用量热力图」标题行展开/收起,展开状态记在浏览器本地偏好。模型分布的「月」回看仍复用同一份月度数据,接口调用次数不变
- **`timezoneOffsetSec` 配置**(默认 `28800` = GMT+8):决定按天分桶与请求 `start`/`end` 的对齐;必须是 900 的整数倍且落在 `[-43200, 50400]`,非法值自动回落到 GMT+8
### 变更

- **模型分布图例同时显示金额与 Token**:主值仍跟随排序维度(大号加粗),另一个维度以同排小字常显(悬停有"金额: x / Token: x"说明);「金额 / Token」切换改名为「按金额 / 按 Token」,语义明确为排序维度。金额为 0 但 Token 有值的模型不再被过滤,而是显示 ¥0.00 + 对应 Token
- **补齐英文界面下的漏译**:11 处词典外的硬编码中文(设置保存/清除提示、验证失败、热力图浮卡的"请求/命中"、周期标签、上一期/下一期按钮、token 输入框占位符)全部提取进词典;「9月11日」这类日期格式改为按语言渲染(英文为 `9/11`),`3 月` 区间同理
- **金额币种跟随账户**:「今日金额 / 本月金额」两张卡与热力图浮卡的币种此前写死 `CNY`,美元账户下会显示成 `¥`。现在按「月度数据 → 平台余额 → 官方余额 → CNY」取账户计费币种(只换符号,**不做汇率换算**,平台返回什么就显示什么);宿主在多币种桶(例如同时返回 CNY 与 USD)时也改为优先账户币种,不再固定优先 CNY
- **英文文案按母语习惯重写**:修订了若干条读起来像直译的句子,例如 `Billed usage comes from platform.deepseek.com's undocumented usage APIs…`、`Today: 19% of the month`、`Today requests`、`Cache hit rate`、`Amount: ¥34.54`、`cache hit 98.7%`、`Models`、`🌙 Valley hour · ~50% off` 等;token 校验失败时改为显示本地化的人话(`The token is invalid or expired.`),只有 HTTP/网络类错误才保留原始信息便于排查;热力图说明句中的维度词改为小写(`Daily amount over the last 6 months`)
- **token 来源标签本地化**:设置里的「已配置 token(来源: secret-file)」不再显示英文原始值,改为本地化标签(`本地密钥文件` / `环境变量 DEEPSEEK_PLATFORM_TOKEN` / `未设置`),未知来源原样显示,便于宿主将来新增来源时不至于消失

### 说明

- 面板语言只覆盖本插件的文案;Harness 自身的界面语言仍在「设置 → 通用 → 语言」中切换(该行是框架内置的,插件文案会随其联动)
- 清理死代码:删除 9 个旧版本遗留、无任何引用的词典键(`chart.empty`、`chart.axisToken`、`pv.peak.short`、`pv.valley.short`、`pv.banner.peak.count`、`pv.banner.valley.count`、`chip.requests`、`chip.cacheHit`、`pill.balance`),从未被调用的 `durationText()` 函数与其 4 个专用键(`pv.dur.hm/h/m/now`),以及宿主中永远不可达的 `runtimeToken` 分支(`source: 'runtime'`,token 来源精简为 `env → secret-file → none`);中英词典各 90 键
- 每个月 1 次请求覆盖整月(月长 ≤ 31 天,正好是平台允许的最大查询范围),请求数量、轮询与刷新频率均不变
- `?force=1` 已能绕过宿主 10 分钟缓存(面板 ↻ 按钮与打开面板都会带上);若上一次刷新是在当天 0:00 之前,轮询周期内仍可能短暂显示 0,属正常缓存延迟
## [1.1.1] - 2026-09-08

### 新增

- **面板“发现新版本”提示**:宿主端按 `updateCheckIntervalMs`(默认 6 小时)查询 npm 上 `deepseek-harness-usage-dashboard` 的 latest 版本并与自身比较;设置面板在发现新版本时提示升级命令(`dsh plugin --profile web update deepseek-harness-usage-dashboard`)。仅提示,绝不自动安装;网络失败静默忽略;可用 `checkUpdate` 关闭

### 修复

- **深色模式下按钮文字不可见**:`.dshud_btn_danger`(清除已保存的 token)与错误提示的颜色不再依赖可能随主题变暗的 `--dsw-alias-state-error-primary`,改用两种主题下都清晰的固定红色 `#ef4444`;「验证并保存」主按钮改用硬编码品牌蓝 `#2563eb` 底 + 白字(不再依赖随主题翻转亮暗的主题变量),深浅两模式均清晰可见
- **userToken 提示文案优化**:设置面板的获取说明改为分步骤(「获取」+「安全」),新手可照做、专业用户也更清晰;中英文案同步更新

### 安装与文档

- README(中/英):npm 安装方式拆为「方式一 A:跟随更新(默认,升级最方便)」与「方式一 B:固定版本(可复现)」,并新增「升级」章节,列出各安装路径的升级命令与 `dsh plugin --profile web outdated` 检查方法
- README(中/英):新增 v1.1.1 实机「界面截图 / Screenshots」组(图存于 `docs/images`,共 5 张)
- README(中/英)与 `cordis.patch.yml`:补充 `checkUpdate`、`updateCheckIntervalMs` 配置说明
- 当前稳定版本同步为 `1.1.1`

## [1.1.0] - 2026-09-08

### 新增

- **峰谷时段显示**:面板顶部统一风格横幅(峰橙红/谷绿 + 右侧紧凑倒计时 pill),右下角角标改为峰谷**边框光效**(峰=琥珀呼吸光、谷=绿色静光);默认峰时 `09:00–12:00`、`14:00–18:00`(北京时间,其余谷时约 5 折),窗口可用 `peakWindows` 覆盖;纯本地计算,随轮询自动刷新
- **用量热力图**(GitHub 风格,替代单月柱状图):覆盖近 `historyMonths` 个月(默认 6)的每日金额/Token,颜色越深越高;今日格高亮描边;悬停单格弹出即时浮卡(日期 + 金额/Token + 请求 + 命中率),无用量日提示“该日无用量”;小额/空月份自动处理
- **模型分布环形图**:按 **日 / 周 / 月** 三种周期并可 **‹ › 左右翻看**、金额/Token 两维切换;中心显示周期总量;小额模型自动并入灰色“其他”(份额 ≥1.5% 且前 8 名单独显示),0 值模型不再展示;10 色可区分调色板
- **指标卡 3×2 网格**:今日金额 · 今日Token · 请求数(日)/ 本月金额 · 本月Token · 缓存命中率(月),粒度标注不再含混;今日两张卡各带“今日占本月”进度条(悬停显示占比)
- **任务完成即时刷新**:宿主监听会话 `turn/end` 事件,任务结束后按冷却(`taskRefreshCooldownMs`,默认 60 秒)自动向 DeepSeek 拉取一次,高频任务自动合并防连击

### 变更

- 界面文案“花费”统一改为“金额”(英文 Amount)
- 角标瘦身:去掉峰/谷文字色块与独立状态点,只保留金额 + 边框峰谷光效,尺寸更紧凑
- 峰谷横幅单行化:建议文案并入标题,峰/谷样式完全统一(仅色相不同);移除月度翻页,热力图按月窗口展示
- Footer 整合为“数据来源: DeepSeek 开放平台 · 官方”(可点击,常驻下划线)+ 右侧淡色版本号 `v1.1.0`;“数据更新于”移入面板 header
- 面板交互:点击面板外任意处自动关闭;打开/关闭均带 160ms 淡入/淡出动画
- 撤销“今日/本周/本月”为短标签“日/周/月”,空状态显示“周期标签 · 暂无用量数据”

### 修复

- 热力图悬停卡片在靠右列时越出容器/被裁并触发横向滚动 —— 改为向面板内侧锚定,`overflow-x` 兜底
- 悬停卡片引用 `React.`(未定义)导致点击打开面板后整条悬浮条目消失 —— 改小写 `react.useState/useRef`
- 环形图“周”视图点击崩溃(变量作用域)与“日/周”翻看方向相反(‹ 跳到未来)—— 分别修复并做符号修正
- 关闭面板先卸载再重挂造成画面闪烁 —— `closing` 状态收进 store 同步更新,直接播放淡出
- 指标卡信息过密/失衡:改为固定 3×2 网格;请求数/命中率补齐“日/月”粒度标注

### 安装与文档

- README(中/英)功能清单、刷新策略与安装版本号同步至 `1.1.0`

## [1.0.2] - 2026-08-18

### 修复

- 修正浏览器端 `window.__ModuleLoader__.load()` 的最外层注册 ID,使其与 npm 包名 `deepseek-harness-usage-dashboard` 一致
- 保留宿主端 Cordis 运行时 ID `dsh-usage-dashboard`,避免破坏已有配置、路由、缓存和卸载标识
- 修复新用户安装后可能出现的 `Failed to load plugins`

### 安装与文档

- 当前推荐安装版本统一为 `1.0.2`
- GitHub Release 备用方式改为“下载 `.tgz`、校验 SHA-256、使用 `file:` 安装”,兼容 pnpm 完整性策略
- 明确 `1.0.1` 已被替代,避免继续安装存在前端注册 ID 问题的版本
- README 增加版本导航,中英文文档同步说明每个版本的重点变化

### CI

- 新增自动断言:客户端最外层注册 ID 必须等于 `package.json.name`,防止包重命名再次造成前端加载失败

## [1.0.1] - 2026-08-18

### 变更

- npm 包改名为未占用的 `deepseek-harness-usage-dashboard`,插件运行时 ID 继续使用 `dsh-usage-dashboard`
- 移除未使用的 `zod`,并固定 `@deepseek-ai/schemastery` 依赖版本
- npm 发布包补充中英文 README、Security、Changelog 与 License 文件

### 安装与文档

- npm 固定版本安装成为首选方式,同时提供 GitHub Release `.tgz` 备用路径
- 补充 Node.js/pnpm 前置条件、Windows `file:` 本地安装方式和同一工作目录重启说明
- 补充端口 `3080` 被占用、`link:` 依赖缺失和安装后无角标的排查步骤
- 加强 `userToken` 获取、凭据区分和日志/会话压缩包脱敏提示

### CI

- 新增 Windows 与 Ubuntu 的入口导入、客户端语法、npm 打包内容及发布 dry-run 检查

> **兼容性提示:**`1.0.1` 的 npm 包名已经更换,但前端 bundle 仍注册旧 ID。该版本已被 `1.0.2` 替代,新用户不要安装 `1.0.1`。

## [1.0.0] - 2026-08-17

### 变更

- 项目进入稳定版本,版本号升级至 `1.0.0`

### 文档

- 明确插件仅支持 DeepSeek 官方 API 与 DeepSeek Platform 的余额、用量和扣费数据
- 明确使用其他模型供应商时,面板数据不代表该供应商的真实余额或花费,并可能显示不可用或报错

## [0.1.0] - 2026-08-17

### 新增

- 右下角余额角标 + 用量仪表盘面板(注册于 `shell.overlay` 插槽)
- 账户余额:官方 `/user/balance`(API Key)+ 平台 `get_user_summary`(userToken),充值/赠送拆分
- 今日 / 本月实际扣费与 Token、请求数、缓存命中率
- 每日花费 / Token 柱状图(SVG 手绘),支持回看历史月份;模型分布
- 刷新机制:固定轮询(默认 10 分钟 / 页面 30 秒)+ 任务完成即时刷新(`turn/end` 事件,60 秒冷却)+ 手动强制刷新
- userToken 管理面板:一次性粘贴、在线验证、一键清除、脱敏显示
- 凭据安全:token 仅存本机 0600 密钥文件,浏览器只读脱敏值;支持环境变量 `DEEPSEEK_PLATFORM_TOKEN`

### 文档

- README(功能 / 数据来源 / 安全与隐私 / 安装 / 配置 / 卸载)
- SECURITY.md、CONTRIBUTING.md、LICENSE(MIT)