dsh-billing-badge 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2026-09-18
+
+### Fixed
+
+- The chip follows the statistics reading into the composer dock on DeepSeek Harness
+  0.1.6, where the labelled statistics row was replaced by a row of pill buttons and the
+  old anchor no longer existed. Both shapes are supported: the labelled row stays first
+  in the resolution order, the dock row is the fallback.
+- The panel no longer closes on every scroll or resize. The composer scrolls on its own
+  while a turn renders, so a click could be dismissed a moment after it opened. The panel
+  now follows the chip and closes only once the chip itself is out of sight.
+
+### Added
+
+- `README.zh.md`, a full Chinese README. The catalog card renders a per-language README
+  and its language sniff classified the mixed-language file as Chinese only, which the
+  card then printed. The main README is English again, with a language link.
+- `screenshots.json`, the catalog convention for author-curated card screenshots, with
+  the panel and the pill in its row. Both the catalog detail page and the market's
+  storefront read it from this repository, so a screenshot no longer waits on a
+  maintainer.
+
+### Removed
+
+- The panel note saying that prices are published in CNY per million tokens while the
+  balance keeps the currency the API reports. The plugin shows no prices, so the sentence
+  explained nothing, and on an account reporting USD it read as if the account's own
+  numbers were CNY. The empty note no longer reserves its spacing.
+
 ## [0.1.1] - 2026-09-13
 
 ### Changed

package/README.md

@@ -1,5 +1,7 @@
 # dsh-billing-badge
 
+English | [中文](README.zh.md)
+
 [![npm](https://img.shields.io/npm/v/dsh-billing-badge)](https://www.npmjs.com/package/dsh-billing-badge)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
@@ -11,6 +13,8 @@ opens a small panel with the full picture.
 2288M tok · Cache hit 99.8% · ● Off-peak · 2h13m
 ```
 
+![The pill in the composer statistics row and the panel it opens](https://raw.githubusercontent.com/devacc8/dsh-billing-badge/main/docs/preview.png)
+
 ## What it shows
 
 | Where | What |
@@ -77,6 +81,10 @@ dsh plugin --profile web add github:devacc8/dsh-billing-badge
 then restart `dsh web`. The package declares `dsh.bundle.patch`, so the host half is
 reconciled into the profile's bundle list automatically.
 
+Works on DeepSeek Harness 0.1.5 and 0.1.6. Older builds render the composer statistics
+as one labelled row and the chip joins it; 0.1.6 moved those readings into the composer
+dock as pill buttons, and the chip follows the cache-hit pill into that row.
+
 Working on the plugin itself, install the checkout by path instead:
 
 ```sh
@@ -129,52 +137,4 @@ test/            season, sync, host and bundle tests
 
 GitHub Actions runs `npm test` and `npm run check` on Node 20 and 22.
 
-## 中文说明
-
-DeepSeek Harness 网页界面的计费时段与账户余额插件。它在输入框下方的统计行里、原生 **Cache hit** 之后加一个小胶囊，点击后展开一个小面板。
-
-```
-2288M tok · Cache hit 99.8% · ● Off-peak · 2h13m
-```
-
-- **胶囊**：一个圆点（高峰为琥珀色，非高峰为绿色）、当前时段，以及距离切换的倒计时。
-- **面板**（点击展开）：计费时段、下次切换时间与北京时间、当前北京时间、账户余额及其货币、赠送额度与充值额度的拆分，以及刷新按钮。
-
-计费时段采用官方公布的规则：高峰为北京时间周一至周五 09:00-12:00 与 14:00-18:00，其余时间（含整个周六与周日）均为非高峰，价格为半价。
-
-余额来自官方 `GET /user/balance` 接口，其中三个数字含义不同：
-
-```
-total_balance = granted_balance + topped_up_balance
-```
-
-- `total_balance`（Account balance）：可用总额。
-- `granted_balance`（Granted）：官方赠送的额度，接口只返回尚未过期的部分，过期的赠送额度会自动从这一行消失。
-- `topped_up_balance`（Topped up）：你自己充值的金额。
-
-前两行数值相等时，说明账户没有赠送额度。`is_available` 是响应顶层的字段，回答一个问题：余额是否足够调用接口。只有接口报告余额不足时，面板才会加一行警告；该字段对任何有余额的账户都是 true，因此平时不显示。货币一律取自接口返回值，不做假设：返回 USD 的账户不会被标上人民币符号。
-
-### 安装
-
-从 npm 安装：
-
-```sh
-dsh plugin --profile web add dsh-billing-badge
-```
-
-或直接从仓库安装：
-
-```sh
-dsh plugin --profile web add github:devacc8/dsh-billing-badge
-```
-
-然后重启 `dsh web`。包内声明了 `dsh.bundle.patch`，宿主部分会自动写入 profile 的 bundle 列表。
-
-### 安全
-
-- API key 只在宿主进程中通过 DSH credentials 接口读取（`ctx.credentials.resolve('DEEPSEEK_API_KEY')`，环境变量兜底），不会进入浏览器；
-- 唯一的路由要求请求头 `x-dsh-billing-badge: 1`，并拒绝跨站 `Origin`；
-- 不写任何文件，除 `api.deepseek.com` 外不访问其他地址；
-- 缺少 key、HTTP 错误或网络故障都会降级为面板可显示的状态，不会抛异常。
-
 MIT.

package/README.zh.md

@@ -0,0 +1,108 @@
+[English](README.md) | 中文
+
+# dsh-billing-badge
+
+[![npm](https://img.shields.io/npm/v/dsh-billing-badge)](https://www.npmjs.com/package/dsh-billing-badge)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+DeepSeek Harness 网页界面的计费时段与账户余额插件。它在输入框的统计行里、原生 **Cache hit** 读数之后加一个小胶囊，点击后展开一个小面板，把完整信息一次说清。
+
+```
+2288M tok · Cache hit 99.8% · ● Off-peak · 2h13m
+```
+
+![统计行里的胶囊与点击展开的面板](https://raw.githubusercontent.com/devacc8/dsh-billing-badge/main/docs/preview.png)
+
+## 显示内容
+
+| 位置 | 内容 |
+|---|---|
+| 胶囊 | 一个圆点（高峰为琥珀色，非高峰为绿色）、当前时段，以及距离切换的倒计时 |
+| 面板（点击展开） | 计费时段、下次切换时间与北京时间、当前北京时间、账户余额及其货币、赠送与充值的拆分，以及刷新按钮 |
+
+计费时段采用官方公布的规则：高峰为北京时间周一至周五 09:00-12:00 与 14:00-18:00，其余时间（含整个周六与周日）均为非高峰，价格为半价。
+
+## 余额
+
+三个数字来自官方 `GET /user/balance` 接口，含义各不相同：
+
+```
+total_balance = granted_balance + topped_up_balance
+```
+
+- `total_balance`，界面显示为 **Account balance**，是你可以动用的全部金额。
+- `granted_balance`，界面显示为 **Granted**，是官方赠送的额度。接口只返回尚未过期的部分，过期的赠送额度会自动从这一行消失。
+- `topped_up_balance`，界面显示为 **Topped up**，是你自己充值的金额。
+
+前两行数值相等时，说明账户没有赠送额度。`is_available` 是响应顶层的字段，只回答一个问题：余额是否足够调用接口。只有接口报告余额不足时，面板才会加一行警告，其余时候保持安静，因为任何有余额的账户这个字段都是 true。
+
+货币一律取自接口返回值，不做假设：返回 USD 的账户不会被标上人民币符号。
+
+## 为什么再做一版
+
+社区里已经有两个插件覆盖了其中一部分，它们各自教了一件事：
+
+- [dsh-price-phase](https://github.com/lijunyu726/dsh-price-phase) 显示计费时段。它的倒计时曾在周五收盘后指向周六 09:00，而那个事件根本不会发生；它的徽标用哈希 CSS 类居中，模型名一长就与模型标签重叠。本插件把每个候选边界与其前一瞬对比，只计入真实的状态翻转；胶囊是原生统计行里的普通 flex 子元素。
+- [dsh-usage-monitor](https://github.com/liyiersan/dsh-usage-monitor) 显示余额，但无论接口返回什么货币都按人民币格式化。
+
+本插件有意**不做**费用与 token 记账。
+
+## 安装
+
+从 npm 安装：
+
+```sh
+dsh plugin --profile web add dsh-billing-badge
+```
+
+或直接从仓库安装：
+
+```sh
+dsh plugin --profile web add github:devacc8/dsh-billing-badge
+```
+
+然后重启 `dsh web`。包内声明了 `dsh.bundle.patch`，宿主部分会自动写入 profile 的 bundle 列表。
+
+兼容 DeepSeek Harness 0.1.5 与 0.1.6。旧版本把输入框统计渲染成一行带标记的元素，胶囊加入这一行；0.1.6 把这些读数移进输入框底栏，变成一排胶囊按钮，胶囊会跟随缓存命中那个胶囊加入同一行。
+
+在本地开发这个插件时，改为按路径安装检出目录：
+
+```sh
+dsh plugin --profile web add link:/absolute/path/to/dsh-billing-badge
+```
+
+## 安全
+
+余额的暴露面很小，插件就让它保持小：
+
+- API key 只在宿主进程中通过 DSH credentials 接口读取（`ctx.credentials.resolve('DEEPSEEK_API_KEY')`，环境变量兜底），不会进入浏览器；
+- 唯一的路由要求请求头 `x-dsh-billing-badge: 1` 并拒绝跨站 `Origin`，因此第三方页面无法访问它；
+- 不写任何文件，除 `api.deepseek.com` 外不访问任何地址；
+- 缺少 key、HTTP 错误或网络故障都会降级为面板可渲染的状态，不会抛异常。
+
+## 开发
+
+时段逻辑放在 `lib/season.js`，是一个普通 ESM 模块，可以直接测试。浏览器端包无法导入同目录文件（加载器只解析平台种子、已物化的包和已注册的工厂，用子路径 require 自身会抛 "missed the module table"），因此 `scripts/inline-season.mjs` 把该模块去掉 `export` 后复制进 `lib/client.js` 的两个标记之间，`test/client-sync.test.mjs` 在副本漂移时失败。
+
+```sh
+npm test          # 30 项测试：时段规则、倒计时不变量、宿主路由、浏览器端包
+npm run sync      # 把 season.js 重新内联进浏览器端包
+npm run check     # 校验内联是否同步，并对两半做语法检查
+```
+
+倒计时用的是不变量测试而不是固定样本：九天之内每 13 分钟取一个时刻，报告的目标必须在未来、必须改变时段，并且时段不能在它之前改变。
+
+## 目录结构
+
+```
+lib/season.js    时段规则、倒计时与格式化（唯一事实来源，有测试）
+lib/index.js     宿主部分：余额路由
+lib/client.js    浏览器部分：胶囊与面板，season.js 已内联
+cordis.patch.yml 把宿主部分挂载进 profile
+scripts/         内联脚本
+test/            时段、内联同步、宿主与浏览器端包的测试
+```
+
+GitHub Actions 在 Node 20 与 22 上运行 `npm test` 与 `npm run check`。
+
+MIT.

package/lib/client.js

@@ -12,13 +12,16 @@ window.__ModuleLoader__.load({
 		 * composer's statistics row, immediately after the native "Cache hit" pill,
 		 * and opens a small panel with the full reading on click.
 		 *
-		 * The native row is a single component (`[data-composer-stats]`) rather than a
-		 * slot, and the composer container is a column, so a sibling in the slot would
-		 * land underneath instead of beside it. The slot registration below is
-		 * therefore a mount point only: it renders nothing and appends the chip into
-		 * the native row. The data attribute is deliberate, unlike the hashed class an
-		 * earlier community plugin centred itself on (which collided with the model
-		 * chip), and the chip is an ordinary flex child so it cannot overlap anything.
+		 * The native row is not a slot the chip could be a sibling in, and the composer
+		 * container is a column, so a sibling of the dock would land underneath instead
+		 * of beside it. Up to 0.1.5 the row is one labelled component
+		 * (`[data-composer-stats]`); from 0.1.6 the readings are pill buttons inside the
+		 * composer dock. The slot registration below is therefore a mount point only:
+		 * it renders nothing and appends the chip into whichever row `statsRow()`
+		 * resolves. The data attribute and the slot name are deliberate, unlike the
+		 * hashed class an earlier community plugin centred itself on (which collided
+		 * with the model chip), and the chip is an ordinary flex child so it cannot
+		 * overlap anything.
 		 */
 
 		// >>> billing-badge:season (generated from lib/season.js by scripts/inline-season.mjs) >>>
@@ -216,6 +219,7 @@ window.__ModuleLoader__.load({
 .dsh-billing-rows dt { color: var(--dsw-alias-label-secondary); }
 .dsh-billing-rows dd { margin: 0; color: var(--dsw-alias-label-primary); font-variant-numeric: tabular-nums; text-align: right; }
 .dsh-billing-note { margin-top: 10px; color: var(--dsw-alias-label-caption); }
+.dsh-billing-note:empty { display: none; }
 .dsh-billing-err { color: var(--dsw-alias-state-warn-label); }
 `;
 
@@ -277,10 +281,33 @@ window.__ModuleLoader__.load({
 			return rows;
 		}
 
+		/**
+		 * The element the chip joins: the native statistics row, in either shape the
+		 * harness has shipped it. Up to 0.1.5 it is a single labelled element; from
+		 * 0.1.6 the readings are pill buttons in the composer dock, so the chip follows
+		 * the pill that carries the cache-hit reading into the row that holds it.
+		 *
+		 * @returns {HTMLElement|null} Null while the row does not exist yet.
+		 */
+		function statsRow() {
+			const legacy = document.querySelector('[data-composer-stats="true"]');
+			if (legacy !== null) return legacy;
+			const dock = document.querySelector('[data-slot="conversation.composer.dock"]');
+			if (dock === null) return null;
+			const reading = [...dock.querySelectorAll("button")].find((el) =>
+				/cache hit/i.test(el.textContent || ""),
+			);
+			if (reading === undefined) return null;
+			for (const child of dock.children) {
+				if (child.contains(reading)) return child;
+			}
+			return null;
+		}
+
 		/**
 		 * Mount the chip and its panel into the native statistics row.
 		 *
-		 * @param {HTMLElement} row - The `[data-composer-stats]` element.
+		 * @param {HTMLElement} row - The native statistics row, from `statsRow()`.
 		 * @returns {() => void} Teardown.
 		 */
 		function mountChip(row) {
@@ -327,9 +354,7 @@ window.__ModuleLoader__.load({
 					if (tone === "warn") dd.style.color = "var(--dsw-alias-state-warn-label)";
 					body.append(dt, dd);
 				}
-				note.textContent = balance && balance.ok === false && balance.error
-					? String(balance.error)
-					: "Prices are published in CNY per million tokens; the balance keeps the currency the API reports.";
+				note.textContent = balance && balance.ok === false && balance.error ? String(balance.error) : "";
 				note.classList.toggle("dsh-billing-err", Boolean(balance && balance.ok === false));
 			};
 
@@ -356,7 +381,31 @@ window.__ModuleLoader__.load({
 			const onKey = (event) => {
 				if (event.key === "Escape") closePanel();
 			};
-			const onViewport = () => closePanel();
+			/**
+			 * Follow the chip instead of dismissing the panel. The composer scrolls
+			 * under the reader on its own while a turn renders, and closing on any
+			 * scroll made the panel flicker away right after a click. A chip scrolled
+			 * out of sight still closes, because a panel parked at the viewport edge
+			 * no longer points at anything.
+			 */
+			let repositioning = false;
+			const reposition = () => {
+				if (panel === null) return;
+				const rect = chip.getBoundingClientRect();
+				if (rect.bottom < 0 || rect.top > window.innerHeight) {
+					closePanel();
+					return;
+				}
+				placePanel();
+			};
+			const onViewport = () => {
+				if (panel === null || repositioning) return;
+				repositioning = true;
+				window.requestAnimationFrame(() => {
+					repositioning = false;
+					reposition();
+				});
+			};
 
 			function closePanel() {
 				if (panel === null) return;
@@ -428,7 +477,7 @@ window.__ModuleLoader__.load({
 
 				const attach = () => {
 					if (teardown !== null && document.querySelector(".dsh-billing-badge") !== null) return;
-					const row = document.querySelector('[data-composer-stats="true"]');
+					const row = statsRow();
 					if (row === null) return;
 					if (teardown !== null) teardown();
 					teardown = mountChip(row);
@@ -467,7 +516,7 @@ window.__ModuleLoader__.load({
 
 		exports.apply = apply;
 		exports.inject = inject;
-		exports.__internal = { mountChip, panelBody };
+		exports.__internal = { mountChip, panelBody, statsRow };
 		return module.exports;
 	},
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-billing-badge",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Billing season and account balance chip for the DeepSeek Harness web GUI composer: a native-looking pill after the cache-hit stat, with a panel on click. DeepSeek Harness 计费时段与余额插件",
   "type": "module",
   "main": "lib/index.js",