npm - dsh-usage-mini - Versions diffs - 0.2.2 - Mend

dsh-usage-mini 0.2.2

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.

Files changed (7) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,9 @@
+MIT License
+Copyright (c) 2026 teethyachi
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,136 @@
+English | [简体中文](README.zh-CN.md)
+# 用量小窗（USEAGE WINDOW）
+![USEAGE WINDOW — Claude/Codex usage windows with reset countdowns next to DeepSeek API spend, in one floating window](docs/promo.png)
+**Your agents have big plans. Your quota has office hours.**
+A companion floating window for [`dsh-cost-meter`](https://github.com/Han-1413141/dsh-cost-meter) and `dsh-plugin-subscriptions`: they collect the numbers, this one keeps them on screen.
+A tiny floating usage dashboard for **DeepSeek Harness Web**. Check the meter without turning your workflow into a browser-tab scavenger hunt.
+> **Currently supports Claude subscriptions, Codex (ChatGPT) subscriptions, and DeepSeek API only.** Not a universal billing dashboard. Not an official Anthropic, OpenAI, or DeepSeek product.
+## What you get
+- **Claude + Codex subscriptions:** available usage windows, used/remaining percentages, reset times and countdowns. No made-up dollar balance for a subscription.
+- **DeepSeek API:** today's locally recorded official-provider spend and calls, plus the upstream cached official account balance. Includes a Flash breakdown when present.
+- **Follows your DSH language setting.** The widget reads the host's `<html lang>` and renders in Chinese or English, switching live when you change Settings → Language. It has no language switch of its own, because you already have one.
+- Drag it where you want. Collapse it into the nearest corner. It remembers its spot in this browser.
+- Settings toggle, manual refresh, and 60-second polling while expanded and the page is visible. Collapsed or hidden? No polling busywork. Your usage monitor should not need its own usage monitor.
+- **A feedback bar** at the bottom of the window. One line, press Send, and a pre-filled GitHub issue opens. Every issue gets a reply; adopted ones ship in the next release with credit. See [Feedback](#feedback-the-widget-is-built-from-your-issues).
+## Install
+Requires a DeepSeek Harness Web installation and pnpm. This repository ships ready-to-load JavaScript; no build step or install script. Compatibility with your DSH version is **not certified**; see [Compatibility](#compatibility-declared-in-packagejson).
+Latest tagged release:
+```sh
+dsh plugin --profile web add github:teethyachi/dsh-usage-mini#v0.2.2
+```
+Or download the release tarball and run:
+```sh
+dsh plugin --profile web add ./dsh-usage-mini-0.2.2.tgz
+```
+To pin an exact commit instead of a tag:
+```sh
+dsh plugin --profile web add github:teethyachi/dsh-usage-mini#<commit-sha>
+```
+Restart your existing Web profile, then refresh its page. Open Settings → 用量小窗 to show/hide the widget. Package ID stays `dsh-usage-mini` for compatibility; **USEAGE WINDOW** is the requested product spelling.
+### Required data providers
+This is a display plugin, not a replacement account connector. Enable these separately in the same Web profile:
+| Feature | Required existing plugin |
+|---|---|
+| Claude / Codex usage | `dsh-plugin-subscriptions`, with the relevant subscription signed in |
+| DeepSeek spend / balance | `dsh-cost-meter`, with ledger and official balance configured |
+They are **not bundled or silently installed**. If an endpoint is unavailable, that section shows a notice; the other section can still work. Compatibility depends on these RPC contracts, not merely having a similarly named package installed.
+## Compatibility (declared in `package.json`)
+| Field | Value | Evidence |
+|---|---|---|
+| Node.js (`engines.node`) | `22.23.2` (exact) | The only Node version actually exercised (Windows). Other Node versions, including the rest of DSH's own `^22.19.0 \|\| >=24.0.0` range, are untested and therefore not declared. |
+| DSH (`dsh.compatibility.dshReleases`) | `0.1.2-rc.1`: **compatible** · `0.1.1-rc.2`, `0.1.2-alpha.4`, `0.1.2-alpha.5`: **unknown** | `0.1.2-rc.1`: full `dsh --profile web` start from a disposable `DSH_HOME`, client delivered through the real web module loader, headless-browser render in zh-CN and en-US with zero page errors, clean uninstall — see [docs/store-evidence.md](docs/store-evidence.md). The other three have only install/composition evidence (rc.2) or none (alphas) and stay `unknown`. |
+| Profile | `web` only | Browser client; no headless/TUI behaviour. |
+| OS | Windows (`win32`) exercised | Nothing OS-specific in the code, but only Windows was exercised. |
+**Correction (0.1.2, folded into 0.1.3):** an earlier revision of this manifest declared `engines.node >=22.19.0` and marked two DSH releases `compatible`. That was overbroad: source-level compatibility and configuration composition are not self-certified full runtime compatibility. The values above are the honest state. They are not a claim that DSH STORE has completed its own Profile install or runtime acceptance, and a store listing may stay guarded or unlisted until real runtime evidence exists.
+## Permissions, dependencies and failure boundaries
+- **Lifecycle scripts:** none (`preinstall`/`install`/`postinstall`/`prepare` absent). **Runtime dependencies:** none; only `react` is required from the DSH web module loader.
+- **Network:** the browser client issues same-origin `fetch` POSTs to the current DSH origin only: `/subscriptions-auth/status`, `/subscriptions-auth/usage`, `/api/costMeter/getState`, `/api/costMeter/refreshBalance`. It never calls an external host itself. Upstream plugins (`dsh-plugin-subscriptions`, `dsh-cost-meter`) do contact Anthropic/OpenAI/DeepSeek on your behalf when serving those RPCs; a forced refresh triggers such upstream calls.
+- **Files / commands / credentials:** none. The host half is a no-op; the plugin reads no files, spawns no processes and never handles tokens. Credential state stays inside the upstream plugins.
+- **Local storage:** two browser `localStorage` keys: `dsh-usage-mini:ui` (window position, collapsed state, visibility) and `dsh-usage-mini:feedback` (last-send timestamp, send count). No usage data is persisted by this plugin.
+- **Feedback bar:** pressing Send calls `window.open` on a `https://github.com/teethyachi/dsh-usage-mini/issues/new?…` URL. That is a navigation in your browser, not a request made by the plugin; nothing is sent unless you then press Submit on GitHub. See [Feedback](#feedback-the-widget-is-built-from-your-issues).
+- **On-screen data:** account labels returned by the subscriptions plugin and cached balances can be visible in the widget. Redact screenshots.
+- **Stale-cache semantics:** the DeepSeek balance is the cost-meter cached snapshot. Automatic polling only requests a refresh when no balance was ever fetched; the manual button forces a refresh. If the refresh fails, the previous snapshot stays with its own status message.
+- **Failure boundaries:** an RPC returning HTTP 404 is shown as "channel missing" for that section only; the other section keeps working. Any other error is displayed as text in that section. By design the host entry does nothing and client errors are caught per section, so the plugin is not expected to bring down the host; this is a design statement, not a tested guarantee across DSH versions.
+## Read the numbers like an adult (tragic, we know)
+- Subscription percentages are upstream usage windows, not money and not a per-chat bill.
+- Today's DeepSeek spend comes from the cost-meter ledger (`deepseek` / `deepseek-official` routes). It is **not guaranteed to include every charge on your provider account**. Currency conversion uses cost-meter settings.
+- Balance is a cached snapshot. Manual refresh requests an update; network/provider failures can leave an older snapshot.
+- This widget does **not** enforce budgets, stop agents, switch models, or promise savings.
+## Privacy & implementation
+A no-op host entry plus a browser client using DSH's module loader and `settings.section` slot. Requests go to the current DSH origin: `/subscriptions-auth/status`, `/subscriptions-auth/usage`, `/api/costMeter/getState`, and `/api/costMeter/refreshBalance`. Existing host plugins handle upstream authentication. This package adds no external analytics or credential-entry UI.
+Browser localStorage keeps display preferences. Account labels and balances can appear on screen: redact screenshots before sharing. Never publish your DSH profile, credentials, ledger, or session history.
+## Feedback: the widget is built from your issues
+The bottom of the expanded window has a one-line input that asks **Any feedback?** (**给点儿意见？** in Chinese). Type, press Send, and a **pre-filled GitHub issue** opens in a new tab. Press Submit there and you're done.
+What goes into that URL, and nothing else:
+| Field | Value |
+|---|---|
+| `feedback` | your text, trimmed, max 500 characters |
+| `version` | the plugin version string (e.g. `0.2.0`) |
+| `title` / `labels` / `template` | `[feedback] …` (`[反馈] …` in Chinese), `feedback`, `feedback.yml` |
+Never included: usage percentages, balances, spend, account labels, subscription state, tokens, or anything read from the DSH RPCs. A 60-second local cooldown and the 500-character cap are enforced in the browser. If your browser blocks the pop-up, the widget shows a plain link instead.
+The loop on the maintainer side:
+1. Every `feedback` issue gets a reply: adopted, or not adopted with the reason.
+2. Adopted items are implemented on a branch, tested, and merged by a human. No automated commits to `main`.
+3. The release that ships them credits the issue number in the CHANGELOG.
+4. Hard boundaries that will not change regardless of votes: only Claude / Codex subscriptions and the DeepSeek API; no new network endpoints; no credential handling; no changes to the main DSH GUI.
+Prefer not to use the widget? [Open an issue directly](https://github.com/teethyachi/dsh-usage-mini/issues/new?template=feedback.yml).
+## Remove
+```sh
+dsh plugin --profile web remove dsh-usage-mini
+```
+Restart the Web profile.
+## Links
+- Hugging Face Space (project page / mirror): https://huggingface.co/spaces/BruceWuu/useage-window
+- 中文介绍（为什么做这个小窗）: [docs/blog-zh.md](docs/blog-zh.md)
+If this widget saves you a tab, a GitHub Star or a Like on the Hugging Face Space helps other DSH users find it. Bug reports and PRs are more useful still.
+## Release verification
+Run `npm test` and `npm pack --dry-run`. Automated checks cover package wiring, the compatibility manifest shape, the feedback URL builder and the balance-refresh regression; they are not a claim of fresh live-account testing on every provider or browser, nor of runtime validation on any DSH version. The installed personal copy is not modified by this publication.
+MIT licensed. Contributions welcome—especially accurate failure states, not confident-looking zeroes.

package/README.zh-CN.md ADDED Viewed

@@ -0,0 +1,136 @@
+[English](README.md) | 简体中文
+# 用量小窗（USEAGE WINDOW）
+![用量小窗 — Claude/Codex 订阅窗口与重置倒计时，加上 DeepSeek API 消耗，一个悬浮小窗](docs/promo.png)
+**Agent 的野心是无限的，你的额度是有班次的。**
+它是 [`dsh-cost-meter`](https://github.com/Han-1413141/dsh-cost-meter) 和 `dsh-plugin-subscriptions` 的搭档小窗：数据由它们去取，这个窗口只负责让数字一直待在你眼皮底下。
+一个给 **DeepSeek Harness Web** 用的悬浮用量面板。想看一眼额度，不用再在一堆标签页里翻找。
+> **目前只支持 Claude 订阅、Codex（ChatGPT）订阅和 DeepSeek API。** 不是通用账单面板，也不是 Anthropic / OpenAI / DeepSeek 的官方产品。
+## 它能给你什么
+- **Claude + Codex 订阅**：可用的用量窗口、已用/剩余百分比、重置时间与倒计时。订阅就是订阅，不会给你编一个"余额"出来。
+- **DeepSeek API**：本地账本里记录的今日官方消耗与调用次数，以及上游缓存的官方账户余额。有 Flash 明细时一并显示。
+- **跟随 DSH 的语言设置**。小窗读取宿主的 `<html lang>`，中文界面还是英文界面由它决定，你在「设置 → 语言」里一切，它立刻跟着切。它自己不提供语言开关——你已经有一个了。
+- 想放哪儿就拖到哪儿，不看的时候收进最近的屏幕角落。位置记在这个浏览器里。
+- 设置里有显示开关，可以手动刷新；展开且页面可见时每 60 秒轮询一次。收起或隐藏就不轮询了——一个看用量的东西，自己不该再需要一个看用量的东西。
+- 窗口底部有**一条反馈栏**。写一句，按「发送」，会打开一个预填好的 GitHub issue。每条都会回复，采纳的会在下一版里带署名上线。见[反馈](#反馈这个小窗是被-issue-推着长大的)。
+## 安装
+需要已经装好的 DeepSeek Harness Web 和 pnpm。仓库里放的就是可直接加载的 JavaScript，没有构建步骤，也没有安装脚本。和你手上这版 DSH 的兼容性**未经认证**，见[兼容性](#兼容性package.json-里怎么写的)。
+最新的 tag 版本：
+```sh
+dsh plugin --profile web add github:teethyachi/dsh-usage-mini#v0.2.2
+```
+或者下载 release 的 tarball：
+```sh
+dsh plugin --profile web add ./dsh-usage-mini-0.2.2.tgz
+```
+想钉死到某个具体 commit：
+```sh
+dsh plugin --profile web add github:teethyachi/dsh-usage-mini#<commit-sha>
+```
+重启你原有的 Web profile，然后刷新页面。在「设置 → 用量小窗」里控制显示/隐藏。为了兼容，包名仍然是 `dsh-usage-mini`；**USEAGE WINDOW** 是产品名的指定写法。
+### 需要的数据来源插件
+这是个展示插件，不是账号连接器的替代品。下面这些要在同一个 Web profile 里单独启用：
+| 功能 | 需要已有的插件 |
+|---|---|
+| Claude / Codex 用量 | `dsh-plugin-subscriptions`，并已登录对应订阅 |
+| DeepSeek 消耗 / 余额 | `dsh-cost-meter`，并配置好账本与官方余额 |
+它们**不会被打包进来，也不会被偷偷安装**。某个接口不可用时，对应那一栏会显示提示，另一栏照常工作。真正决定能否用起来的是这些 RPC 契约，而不是"装了个名字差不多的包"。
+## 兼容性（`package.json` 里怎么写的）
+| 字段 | 值 | 依据 |
+|---|---|---|
+| Node.js（`engines.node`） | `22.23.2`（精确版本） | 实际跑过的只有这一个 Node 版本（Windows）。DSH 自己声明的 `^22.19.0 \|\| >=24.0.0` 里的其余版本都没测过，所以不声明。 |
+| DSH（`dsh.compatibility.dshReleases`） | `0.1.2-rc.1`：**compatible** · `0.1.1-rc.2`、`0.1.2-alpha.4`、`0.1.2-alpha.5`：**unknown** | `0.1.2-rc.1`：在一次性 `DSH_HOME` 里完整 `dsh --profile web` 启动、客户端经真实 web 模块加载器下发、无头浏览器在 zh-CN 与 en-US 下渲染且零页面错误、干净卸载——见 [docs/store-evidence.md](docs/store-evidence.md)。另外三个只有安装/合成证据（rc.2）或没有证据（alpha），保持 `unknown`。 |
+| Profile | 仅 `web` | 纯浏览器端，没有 headless / TUI 行为。 |
+| 操作系统 | 只跑过 Windows（`win32`） | 代码里没有任何跟系统相关的东西，但确实只在 Windows 上跑过。 |
+**更正（0.1.2，已并入 0.1.3）：** 早先的 manifest 写过 `engines.node >=22.19.0`，还把两个 DSH 版本标成了 `compatible`。那是说过头了：源码层面的兼容和配置合成，都不等于自证的完整运行时兼容。上面这张表才是老实的状态。它也不代表 DSH STORE 已经完成了自己的 Profile 安装或运行时验收——在有真实运行时证据之前，商店条目可能一直是受限或未上架状态。
+## 权限、依赖与故障边界
+- **生命周期脚本**：没有（`preinstall`/`install`/`postinstall`/`prepare` 一个都没有）。**运行时依赖**：没有；只从 DSH 的 web 模块加载器里取 `react`。
+- **网络**：浏览器端只对当前 DSH 源发同源 `fetch` POST，一共四个：`/subscriptions-auth/status`、`/subscriptions-auth/usage`、`/api/costMeter/getState`、`/api/costMeter/refreshBalance`。它自己从不访问外部主机。上游插件（`dsh-plugin-subscriptions`、`dsh-cost-meter`）在响应这些 RPC 时会替你去访问 Anthropic/OpenAI/DeepSeek；强制刷新会触发这类上游请求。
+- **文件 / 命令 / 凭据**：都没有。宿主那一半是空实现；插件不读文件、不起进程、不碰任何 token。凭据状态始终留在上游插件里。
+- **本地存储**：两个浏览器 `localStorage` 键：`dsh-usage-mini:ui`（窗口位置、收起状态、显示与否）和 `dsh-usage-mini:feedback`（上次发送时间戳、发送次数）。用量数据一条都不落盘。
+- **反馈栏**：按「发送」会对 `https://github.com/teethyachi/dsh-usage-mini/issues/new?…` 调 `window.open`。那是你浏览器的一次跳转，不是插件发出的请求；你不在 GitHub 上按 Submit，就什么都没发出去。见[反馈](#反馈这个小窗是被-issue-推着长大的)。
+- **屏幕上的数据**：订阅插件返回的账号标识和缓存余额会显示在窗口里。截图前记得打码。
+- **缓存语义**：DeepSeek 余额是 cost-meter 的缓存快照。自动轮询只在从未取到过余额时才请求刷新，手动按钮才是强制刷新。刷新失败时，旧快照保留，并附带自己的状态说明。
+- **故障边界**：某个 RPC 返回 HTTP 404，只会让那一栏显示「通道不存在」，另一栏继续工作。其他错误在该栏里以文字显示。宿主入口本身什么都不做、客户端错误按栏捕获，所以设计上它不会把宿主拖垮——这是设计陈述，不是跨 DSH 版本验证过的保证。
+## 数字要看明白（虽然扫兴）
+- 订阅的百分比是上游的用量窗口，不是钱，也不是某次对话的账单。
+- 今日 DeepSeek 消耗来自 cost-meter 的账本（`deepseek` / `deepseek-official` 路由）。它**不保证覆盖你账户上的每一笔扣费**。汇率换算走 cost-meter 的设置。
+- 余额是缓存快照。手动刷新会请求更新，网络或服务方出问题时可能停在旧快照上。
+- 这个小窗**不会**卡预算、不会掐停 Agent、不会替你切模型，也不承诺帮你省钱。
+## 隐私与实现
+一个空实现的宿主入口，加上一个用 DSH 模块加载器和 `settings.section` 插槽的浏览器客户端。请求只发往当前 DSH 源：`/subscriptions-auth/status`、`/subscriptions-auth/usage`、`/api/costMeter/getState`、`/api/costMeter/refreshBalance`。上游认证由已有的宿主插件处理。这个包不加任何外部统计，也没有任何输入凭据的界面。
+浏览器 localStorage 只存显示偏好。账号标识和余额会出现在屏幕上：分享截图前先打码。永远不要公开你的 DSH profile、凭据、账本或会话记录。
+## 反馈：这个小窗是被 issue 推着长大的
+展开后的窗口底部有一行输入框，问你 **给点儿意见？**（英文界面是 **Any feedback?**）。写完按「发送」，浏览器新标签页里会打开一个**预填好的 GitHub issue**，你在那儿按 Submit 就完事了。
+进到那个 URL 里的，只有这些：
+| 字段 | 内容 |
+|---|---|
+| `feedback` | 你写的文字，去掉首尾空白，最多 500 字 |
+| `version` | 插件版本号（例如 `0.2.0`） |
+| `title` / `labels` / `template` | `[反馈] …`（英文界面是 `[feedback] …`）、`feedback`、`feedback.yml` |
+绝不包含：用量百分比、余额、消耗、账号标识、订阅状态、token，以及任何从 DSH RPC 读到的东西。60 秒本地冷却和 500 字上限都在浏览器里执行。如果你的浏览器拦了弹窗，小窗会改成给你一个普通链接。
+维护这边的闭环：
+1. 每条 `feedback` issue 都会得到回复：采纳，或者不采纳并说明原因。
+2. 采纳的在分支上实现、测试，由人工合并。`main` 上没有自动提交。
+3. 上线它的那一版，会在 CHANGELOG 里引用对应的 issue 号。
+4. 无论多少人投票都不会改的硬边界：只做 Claude / Codex 订阅和 DeepSeek API；不新增网络端点；不碰凭据；不改 DSH 主界面。
+不想用小窗提？[直接开 issue](https://github.com/teethyachi/dsh-usage-mini/issues/new?template=feedback.yml)。
+## 卸载
+```sh
+dsh plugin --profile web remove dsh-usage-mini
+```
+然后重启 Web profile。
+## 链接
+- Hugging Face Space（项目页 / 镜像）：https://huggingface.co/spaces/BruceWuu/useage-window
+- 中文介绍（为什么做这个小窗）：[docs/blog-zh.md](docs/blog-zh.md)
+如果它帮你省下了一个标签页，点个 GitHub Star 或者给 Hugging Face Space 点个 Like，能让别的 DSH 用户更容易找到它。当然，报 bug 和提 PR 更有用。
+## 发布前的自查
+跑 `npm test` 和 `npm pack --dry-run`。自动化检查覆盖打包接线、兼容性 manifest 的形状、反馈 URL 构造和余额刷新的回归；它们不代表在每个服务方、每个浏览器上都做过新鲜的真账号测试，也不代表在任何 DSH 版本上做过运行时验证。发布这件事不会改动本地已安装的那份副本。
+MIT 许可。欢迎贡献——尤其欢迎准确的失败状态，而不是看起来很自信的一堆零。

package/cordis.patch.yml ADDED Viewed

@@ -0,0 +1,7 @@
+# dsh-usage-mini bundle patch: one enabled host row over the web profile.
+# The row mounts the no-op node half; the browser half (lib/client.js) is
+# discovered automatically from the `dsh.client` declaration in package.json
+# and renders the floating usage mini-window.
+- insert:
+    - id: usage-mini
+      name: dsh-usage-mini