@loommii/dsh-provider-usage 0.6.0

package/README.md

@@ -0,0 +1,63 @@
+# dsh-provider-usage — DSH「用量中心」
+
+> 当前版本 **v0.6.0** · npm `@loommii/dsh-provider-usage` · [更新历史](docs/CHANGELOG.md)
+
+DSH Web GUI 插件 **「用量中心」**：一个常驻右下角的用量卡片，实时显示你的 AI 服务用量 / 余额，不用再打开网页查。
+
+## v0.6.0 更新摘要
+
+- **新增提供方 Command Code（订阅+余额混合卡）**：5 小时 / 周 / 月窗口使用量 + 月度剩余额度（USD），主数字为月已用百分比
+- **窗口重置倒计时修复**：之前 5 小时/周窗口的"重置"字段恒为空，现在正常显示倒计时
+- **请求 User-Agent 跟随版本号**：告别硬编码残留，升版不再漏改
+- **订阅端点短超时**：新增 `subscriptionTimeoutMs`（默认 5s），防止次要端点挂起拖累整体响应
+- **月百分比智能隐藏**：Command Code 月用量无法推算时隐藏整行，避免"0% 还没用"的误导
+- 完整变更见 [CHANGELOG](docs/CHANGELOG.md)
+
+## 支持的提供方
+
+| 提供方 | 显示内容 |
+|---|---|
+| OpenCode Go（订阅） | 5 小时 / 7 天 / 月度三个窗口的已用百分比 + 进度条 + 重置倒计时 |
+| DeepSeek（余额） | 账户余额（CNY） |
+| Command Code（订阅+余额，自定义） | 5 小时 / 周 / 月窗口使用量 + 月度剩余额度（USD），主数字为月已用百分比 |
+
+## 功能
+
+- **常驻用量卡片**：右下角悬浮，一眼看到剩余量；可随意拖动，位置自动记住
+- **自动刷新**：每 30s 自动更新；想看最新数据点卡片上的 ↻ 立即重新查询
+- **多实例**：可以同时配置多个提供方（如多个 OpenCode Go 账号），点卡片 logo / 名称切换查看
+- **状态提示**：正常 / 未更新 / 注意 / 错误，请求中显示「查询中」动画
+- **Key 安全**：密钥只在 DSH 进程内解析使用，界面上一律打码显示；自定义 Key 可加密保存在本机（AES-256 加密），不落明文
+
+## 安装
+
+```sh
+# 从 npm 安装
+dsh plugin --profile web add @loommii/dsh-provider-usage
+
+# 从 GitHub 安装（等价，同一份代码 v0.6.0）
+dsh plugin --profile web add github:loommii/dsh-provider-usage
+
+# 安装指定版本（可选）
+dsh plugin --profile web add github:loommii/dsh-provider-usage#v0.6.0
+```
+
+安装后重启 `dsh web` 即可在设置页看到「用量中心」。
+
+> npm 包名为 `@loommii/dsh-provider-usage`（无 scope 的 `dsh-provider-usage` 在 npm 上已被他人占用）。
+
+## 快速开始
+
+1. 打开 DSH 设置 → **用量中心** → 「提供方」
+2. 添加一个实例：
+   - **OpenCode Go 订阅**：需要 OpenCode Go 的 API Key（默认读取 `OPENCODE_GO_API_KEY`）
+   - **DeepSeek 余额**：需要 DeepSeek 开放平台的 API Key（默认读取 `DEEPSEEK_API_KEY`）
+   - **Command Code（自定义）**：仅「添加自定义提供方」可选；需要 Command Code 后台生成的 API Key（`user_xxx`），填进本插件加密保存
+   - Key 也可以直接填进本插件保存（加密存储，不进 DSH 凭证）
+3. 回到主界面，右下角就会出现用量卡片，每 30s 自动刷新
+
+## 使用说明
+
+- 提供方实例的增删改、Key 设置都在 **设置 → 用量中心** 里完成，改动即时生效，无需重启
+- 设置保存在本机浏览器中；删掉实例不会上传或泄露任何 Key
+- 卡片拖动后的位置会自动保存，下次打开还是老位置

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-provider-usage M1: 插入插件行（自动 reconcile 进 profile bundles）
+- insert:
+    - id: provider-usage
+      name: dsh-provider-usage
+      config:
+        baseUrl: https://opencode.ai/zen/go   # {{baseUrl}}/v1/usage 即官方 usage 接口
+        timeoutMs: 15000

package/docs/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+## v0.6.0（2026-08-31）
+
+> **npm 首发**：本版本同步发布至 npm `@loommii/dsh-provider-usage`（无 scope 的 `dsh-provider-usage` 包名已被他人占用，故改用账号 scope）。npm 与 GitHub 渠道**同号同码**（同一提交、同一 tag `v0.6.0`）；scoped 包首次发布需 `--access public`（已在 `publishConfig` 配置），安装方无感。
+
+### 大功能
+- **新增提供方 Command Code（订阅+余额混合卡）**：只能通过「添加自定义提供方」添加（Command Code 非 DSH 内置提供方，pi-ai 注册表无对应 provider，故不出现在「从 DSH 导入提供方」列表）
+  - 新适配器 `commandcode-credits`：官方双端点查询（`/alpha/billing/credits` + `/alpha/billing/subscriptions`），只填 API Key（加密存插件私有库，不经 DSH 凭证）
+  - **新卡片类型**：主数字 = 月已用百分比，副行「已用 $X / $Y + 剩余 $Z」，下方 5 小时 / 周 / 月三窗口进度条（月窗口 = 计划总额 − 剩余推算，planId 映射表；未知计划安全降级）
+  - 订阅端点失败自动降级（保留窗口+剩余）；401/403 复用现有分类
+  - 5 档计划映射：individual-go($10) / goat($70) / pro($80) / max($150) / ultra($300)
+
+### 修复
+- **Command Code 卡片 5 小时/周窗口的「重置倒计时」恒为空白**：host 窗口字段名 `resetAt` 与 client `WindowRow` 读取的 `resetsAt` 不一致（现统一为 `resetsAt`，client 兼容读 `resetAt` 兜底旧数据）；补 20b 回归断言
+- 出站请求 `user-agent` 版本号残留 0.5.0 → 改为从 `package.json` 读取（单一来源，升版不再漏改）
+- Command Code 订阅端点（次要端点）超时从 15s 缩短为 5s（可经 `subscriptionTimeoutMs` 配置）：credits 秒回而 subscriptions 卡死时，卡片不再干等全局超时；补 20f 场景验证
+- 订阅失败/未知计划导致月% 推算不出时，Command Code 卡片隐藏月窗口行（此前渲染「--% + 0% 空进度条」，易误读为「还没开始用」）
+
+### 小功能
+- 提供方设置：自定义表单默认选中 Command Code；卡片/菜单用文字「CC」logo 占位（无官方素材，后续可换）
+
+### 文档
+- 新增 `docs/commandcode-support-plan.md`：方案评估（现状/API 能力/双端点混合模型/备选对比/待确认决策）
+
+## v0.5.2（2026-08-30）
+
+### 重构
+- 「按模型汇总」由 div+grid 改为语义化 <table>，列宽 auto 布局 + 内容自适应，数字列不再截断
+- 缩略数字保留点击展开完整值（整列同步变宽）；移除 hover 悬浮窗，交互统一为点击
+- 模型名单行省略，完整名见 title
+
+## v0.5.1（2026-08-27）
+
+### 修复
+- 提供方状态 chip 在 `data.error` 时显示「查询失败」（此前显示泛化的「错误」）
+- 用量页默认时间范围：全部 → 近 1 天（避免首次打开聚合多日数据；「全部时间」仍可选）
+
+### 重构
+- 提供方列表渲染：6 个内联 if-else 收敛为 `statusOf` 纯函数 + `ProviderRow` 组件，关注点分离（外部行为不变）
+
+## v0.5.0（2026-08-27）
+
+### 大功能
+- **本地 Token 用量统计**（模仿 cc-switch 统计模型：请求级记账 → 汇总 → 命中率；数据源 = DSH 会话日志，不依赖外部服务）
+  - 按天物化 `daily-stats/YYYY-MM-DD.json`（1 天 1 文件、原子写）；首次自动全量回填历史（`.backfilled` 哨兵），之后游标增量只解析新帧
+  - **多帧 zstd 增量解码**：会话文件每次 flush 一帧（实测 10MB / 16751 帧）；wasm（@bokuweb/zstd-wasm）主路径 + fzstd 失败帧兜底，正确性与 CLI 一致；全量回填 ~184ms、增量 200 帧 ~14ms、闲置轮询 ~30ms
+  - 指标：请求数 / 输入 / 输出 / 缓存读取 / 命中率（cacheRead ÷ (input + cacheRead)）/ 真实总 token（input + output + cacheRead）
+  - 按 provider / 按模型汇总；时间范围全部 / 近 1 天 / 近 7 天 / 近 30 天（**自然日语义**：近 1 天 = 今天 00:00 起，不是滚动 24h）
+  - 进程内按天缓存 + deps 5 分钟校验，历史天不重复读盘；新依赖 @bokuweb/zstd-wasm / fzstd（package-lock.json 入库）
+- 设置页改官方插件页同款 **二级菜单**：「提供方设置 / 用量统计」两页互不影响（方向键切换 + 各自记忆）
+
+### 小功能
+- 提供方状态圆点改 **点击展开**：红色 = 错误原因，绿色 = 完整响应 JSON（删除悬停）
+- 查询加载动画进度条
+- 缩略数字单位 k / M / B / T + **点击整卡展开完整千分位数字**（整卡悬停高亮，键盘 Enter/空格同样可用）
+
+### 文档
+- 测试脚本 `npm test` 补齐 daily-stats.test.mjs；docs/规范 发布清单数字更新
+
+## v0.4.2（2026-08-26）
+
+### 修复
+- 卡片窗口行「重置时间」改为**紧凑倒计时**（Rainytoken 小组件同款格式：3d4h / 5h32m / 42m / <1m）：此前显示绝对钟点（如 重置 00:00:00），跨天重置（本周/本月）无日期完全不可读；现在显示距下次重置的剩余时长，悬停卡片重置格显示「约 X 后重置」完整提示
+## v0.4.1（2026-08-25）
+
+### 修复
+- 卡片刷新按钮强制绕过 30s 缓存（noCache=1）：此前 30s 新鲜窗口内点击会直接命中 host 缓存，页面无任何变化；现在手动刷新真实请求上游，fetchedAt 即时更新
+- 卡片状态灯绑定请求中状态：请求进行中（含手动刷新、有旧数据时）显示**绿色呼吸「查询中」**（复用设置页同款 `dsh-pu-ms-breathe` 动画）；同时修复首次加载时「红色错误 + 正文查询中」的自相矛盾展示
+## v0.4.0（2026-08-24）
+
+### 小功能
+- 多适配器 + 提供方实例：按 adapter（usage-percent 订阅型 / balance-json 余额型）查询；设置页可管理提供方实例（名称自定义、Key 引用、增删改），卡片与选择菜单跟随清单；
+  卡片按结果字段自适应渲染（%+倒计时=订阅卡；金额+币种=余额卡）
+- 新增 host 路由：`/api/provider-usage/query?provider=<id>`（旧 `/opencode-go` 保持兼容）、`/api/provider-usage/templates`（预设清单）
+- 凭证链按 preset 泛化：DSH 设置 `llm-pi-ai.providers[<key>].apiKeyEnv` → 凭据服务 → 环境变量
+- 缓存 per-provider 隔离（30s 新鲜窗口各自独立）；cordis `baseUrl` 覆盖收敛为仅作用于 opencode-go（修复 DeepSeek 误打到 opencode 域名的 404）
+
+### UI
+- **删除宠物元素**：移除鲸鱼精灵/悬浮按钮/点击弹框，改用右下角**常驻用量卡片**（布局借鉴 Rainytoken 暗色视觉：暖深底、草莓粉、官方 logo、状态胶囊、三色窗口条、窗口行=标签/已用%/进度条/重置时间）
+- 设置面板：提供方管理（实例增删改、状态圆点），与官方「模型」页 1:1 同款骨架；卡片点击 logo/名称在**多实例**时弹出选择菜单，单实例不可点；卡片固定每 30s 自动刷新
+- 设置页实例支持「编辑」：导入的提供方可改名称；自定义提供方（vault）可改名称与 API 密钥（改 Key 后强制刷新查询，绕过 30s 缓存）；术语「供应商」统一改为「提供方」（对齐 DSH 模型页）
+- 旧数据自愈：早期手动实例（`source` 缺失/为 dsh 但 Key 仅存在插件私有库）自动迁移为 vault 手动实例，恢复可改 Key；`credential-refs` 新增 `store` 字段（dsh/vault/both/none）
+- 实例记录新增显式 `type` 字段（`import`=DSH 导入 / `manual`=自定义）：创建时写入，读取时显式 type 优先（旧数据由 source 推导兜底）；**type 决定编辑能力，source 仅表示 Key 解析位置**
+- 删除放开「最后一个实例」限制：支持删光提供方（空清单持久化，刷新不复活默认实例；用量卡片自动隐藏，设置页显示空态提示；删除自定义实例时同步清理私有库中的 Key）
+- **卡片可拖动 + 位置记忆**：与 dsh-pet 同款 pointer 拖拽（整卡可拖、4px 阈值防误触、右/下钳制在视口内）；松手即持久化到 `dsh-provider-usage.settings` 的 `right`/`bottom`，刷新/重挂载自动恢复位置（设置版本 v5）
+
+### 文档
+- README 更新为 M2（多供应商 + 卡片）；本地调研（cc-switch 机制、Rainytoken 评估）存 `tmp/` 不入仓库
+
+## v0.3.0（2026-08-24）
+
+### 小功能
+- 系统命名统一为「用量中心」：设置侧边栏入口、设置页标题、🐳 对话框标题、状态卡描述、README、包描述
+- （命名面向后续 cc-switch 式多供应商扩展，OpenCode Go 降级为当前唯一数据源说明）
+
+### 文档
+- 新增 `docs/规范/版本号说明.md`：三段 semver 规则、大/小功能表达、0.x 规则、历史对照、四段否决结论
+- 新增 `docs/规范/发布流程.md`：发布流程、提交信息约定、tag 两态规则、检查清单
+- README 增加版本规范摘要与链接
+
+## v0.2.0（2026-08-24）
+
+- **样式**：设置页按 dsh-pet（dsh-web-ui-all 0.3.2）卡片规范重做（tokens/字形/字段行/按钮）
+- **层级**：z-index 固定 2147483000（与 dsh-pet 一致），不再开放用户设置（设置迁移 v3）
+- **挂载**：🐳 改挂 body 顶层 React root（与 dsh-pet 同构），不再被 better-sidebar 等浮层遮挡
+- **对话框**：贴紧宠物实测定位（12px/10px）+ 右缘实测宽度钳制（不再越界）
+- **默认值**：对齐 dsh-pet（尺寸 160 / right 24 / bottom 20）
+
+## v0.1.0 – v0.1.7（早期逐批递增，已发布）
+
+- v0.1.0 M1：悬浮宠物 + OpenCode Go 用量查询（cc-switch 语义）
+- v0.1.1：可拖动 + 位置记忆 + 自愈看门狗
+- v0.1.2：设置分区（设置页）
+- v0.1.3：换用鲸鱼娘（精致版）精灵动画
+- v0.1.4：默认值对齐 dsh-pet（160px）
+- v0.1.5：对话框贴紧（实测高度）
+- v0.1.6/v0.1.7：修正贴紧偏移与右缘越界（均在本地，未单独发布）
+
+> 注：v0.1.8–v0.1.10 为本地迭代号，未对外发布，合并入 v0.2.0。