dsh-consumption-badge 0.0.0-stage → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zlc13
+
+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

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+# dsh-consumption-badge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A **persistent** DSH (DeepSeek Harness) Web UI plugin that puts a live consumption badge
+next to every assistant message, and opens a detail panel with the session's spend curve.
+
+```
+⛽ 25.6k | ≈¥0.020 | valley
+```
+
+- **Collapsed pill** – session-cumulative tokens, estimated cost (always prefixed `≈`), and the
+  current peak/valley tier (red `peak`, green `valley`), injected into
+  `conversation.chat.assistant-actions` right after the shipped copy/branch controls.
+- **Detail modal** (centered, blurred backdrop, `Esc` or backdrop-click to close):
+  cumulative tokens with hit/miss/output split, estimated cost, current pricing tier,
+  DeepSeek account balance, and a **per-turn dual-axis line chart**
+  (left axis: tokens, right axis: ¥) with a hover tooltip showing the model,
+  input-hit / input-miss / output tokens, and the turn's peak/valley flag.
+- **Settings page · 消耗** (`settings.section`, id `balance-dsh-consumption`, order 26):
+  a top row of four cards — **累计 Token** (with hit/miss/output split, all-history totals),
+  **估算金额**, **当前时段** (peak/idle) and **账户余额** (reusing the badge's cached balance) —
+  then **all-session history** as one line chart, filterable by time range
+  (today / last 7 days / last 30 days / last 12 months), by workspace
+  (全部工作区 + every registered workspace + 未归属工作区), and by an explicit
+  calendar range that overrides the dropdown. Bucket size follows the range:
+  **hourly for today and any single-day calendar range**, daily for multi-day ranges, and
+  monthly for the last 12 months. Left axis (tokens) is hidden until you
+  toggle it in the legend; the right axis (¥) is always on. Hovering a point shows its
+  total, its peak/valley split and the models involved; the footer sums the current
+  selection. No data in range → a plain “该范围内暂无消耗记录” note instead of an empty chart.
+  The cards are **all-history** totals (independent of the filters); the footer is the
+  filtered total, so the two numbers differ by design.
+- **Personalization integration** (auto-detected, no configuration): when
+  [`dsh-plugin-personalization`](https://www.npmjs.com/package/dsh-plugin-personalization) is
+  installed alongside this plugin, a **消耗弹窗** block is appended to its settings page —
+  same `pp-block` / `pp-field` / `pp-modes` layout and the same `Pill` primitive as the shipped
+  personalization rows — offering four backgrounds for the consumption modal:
+  **默认 / 毛玻璃 / 自定义背景 / 纯色**.
+  - **默认** keeps the themed surface; **毛玻璃** is real `backdrop-filter` glass — both the veil behind
+    the modal and the panel itself are theme-derived (`--dsw-alias-bg-base`), so light themes get a light
+    haze and dark themes a dark one instead of the panel painting a dark slab over the page;
+    **自定义背景** takes an image URL *or* a local image plus an **不透明度** slider (0–100 %, default
+    85 %) that sets the background layer's own `opacity` — the same semantic as the other
+    personalization background rows, so lowering it fades the image over the themed panel instead of
+    dimming it; **纯色** takes a hex colour and derives a light/dark ink palette so the
+    cards, chart and tooltips stay readable (the palette also overrides the tooltip surface).
+  - A **毛玻璃** switch appears for 自定义背景 and 纯色, so glass composites with them:
+    on an image it blurs the image itself (frosted photo), on a solid it makes the colour
+    translucent over a blurred page. A **毛玻璃强度** slider (0–48 px, default 22 px) sets the
+    blur radius for both the panel and the veil behind it.
+  - **清除** wipes the image, the URL field and the file picker in one go. The image row shows a
+    **thumbnail** plus the live save state
+    (正在保存 / 已保存到本机 / `error: …`), and failures are logged with a
+    `[consumption-badge]` tag instead of failing silently. The picker is a button
+    (“选择图片… / 更换图片…”), not a raw file input, so saving never leaves a misleading
+    “未选择文件” label behind.
+  - Local images are **stored on this machine with no size limit**: the picked file is written as a
+    Blob into IndexedDB (`dsh-consumption-assets` → `images`), and the preference only keeps a small
+    key — so a 20 MB wallpaper no longer blows the `localStorage` quota. On startup the blob is read
+    back into a `blob:` URL for the modal; **清除** deletes the stored record as well.
+    If IndexedDB is unavailable the file is read as a data URL instead, and the row says so.
+  - The choice is a local preference (`dsh-consumption:modal-style`) and is applied to the open
+    modal immediately. Nothing about the conversation or sidebar backgrounds is touched.
+- **Update notice** (same shape as `dsh-plugin-personalization`'s): ~2.5 s after the page loads the
+  plugin asks `https://registry.npmjs.org/dsh-consumption-badge/latest` for the newest version
+  (24 h cache, 5 s timeout, fails silently). If the installed version is older — and that version
+  was not ignored — a non-blocking card appears in the bottom-right corner with
+  **current → latest**, the exact `dsh plugin --profile web update dsh-consumption-badge` command,
+  and three actions: **复制更新命令**, **忽略此版本** (remembered on this machine) and
+  **稍后提醒** (this page load only). It never blocks the conversation and never covers controls.
+
+Everything is an **estimate** for reference only — this plugin is not a billing system of record.
+
+## Requirements
+
+| Capability | Why |
+| --- | --- |
+| DSH `0.1.0-rc.7` or compatible | slot API `conversation.chat.assistant-actions`, `shell.overlay` |
+| `DEEPSEEK_API_KEY` in the DSH credential store | account balance (`GET /user/balance`) |
+| `curl` on `PATH` | the balance request; on Windows 10+ it ships as `C:\Windows\System32\curl.exe` |
+
+The API key is resolved **per request** through the Cordis `credentials` service and passed to
+`curl` on **stdin** (`curl -K -`), never through argv, and never reaches the browser.
+
+If the key or `curl` is missing, only the balance card degrades (it shows the reason);
+tokens, cost and the chart keep working.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-consumption-badge
+```
+
+Then **restart the DSH process** — a host-side plugin (and the browser plugin roster) is composed
+at process start, so a page refresh is not enough.
+
+Verify:
+
+```bash
+cd "$DSH_HOME/profiles/web"
+dsh --profile web --dump-config | grep consumption-badge     # expect exactly one row
+# after restart:
+curl -s http://127.0.0.1:<port>/api/consumption/account      # expect {"ok":true,...,"model":"..."}
+curl -s -o /dev/null -w '%{http_code}\n' \
+     http://127.0.0.1:<port>/plugins/dsh-consumption-badge/client.js   # expect 200
+```
+
+### If the row does not mount
+
+Some deployments compose `dsh.profile.bundles` into `--dump-config` without mounting those rows
+at runtime. The reliable path is a roster row in the **profile's own patch layer** — add it to
+`$DSH_HOME/profiles/web/cordis.patch.yml` and remove `dsh-consumption-badge` from
+`dsh.profile.bundles` so the id is inserted exactly once:
+
+```yaml
+- insert:
+    - id: consumption-badge
+      name: 'dsh-consumption-badge'
+```
+
+The package also ships its own `cordis.patch.yml` (`dsh.bundle.patch`) with the same row for
+deployments where the bundle layer does mount. Keep only **one** of the two active.
+
+## What it reads
+
+| Data | Source |
+| --- | --- |
+| Per-turn tokens | `assistant/message.usage` events in the session log, folded per turn (`cacheReadTokens` → hit, `inputTokens + cacheWriteTokens` → miss, `outputTokens` → output; multi-step turns are summed) |
+| Turn timing | `turn/start` event time (peak/valley is attributed to **request start**) |
+| Model per turn | `request/context` / `request/header.config`; falls back to the agent default model, then `deepseek-flash` |
+| Session totals | the shipped `tokenUsage` projection when present, otherwise the folded turns |
+| Balance | `GET https://api.deepseek.com/user/balance` via curl, 60s cache |
+
+Turn records are also mirrored into browser `localStorage` under
+`dsh-consumption:<sessionId>:<turn>` so the chart survives reloads. Persistence writes are
+scheduled off the render path (`requestIdleCallback`), and the aggregation is O(turns).
+
+The settings page reads **those same records** (no second store, no new field): workspace
+attribution is resolved at read time from DSH's own accounting ledger
+(`WorkspaceView.sessionIds` from `useWorkspaces`), so historical records are attributed without
+any backfill. Records whose session no longer exists land in the 未归属工作区 bucket.
+Above 5000 records the aggregation runs in a Web Worker (built from the pure aggregator's own
+source, so both paths are the same code); if the browser refuses the Worker it silently falls
+back to the main thread, where 6000 records aggregate in ~6 ms.
+
+## Pricing model
+
+Off-peak prices in **CNY per 1M tokens**; peak multiplies everything by **2**.
+
+| Model | input cache hit | input cache miss | output |
+| --- | --- | --- | --- |
+| `deepseek-flash` | 0.02 | 1 | 4 |
+| `deepseek-v4-pro` | 0.15 | 4.5 | 13.5 |
+
+```
+cost = (hit/1e6)*hit_price + (miss/1e6)*miss_price + (out/1e6)*out_price   [×2 at peak]
+```
+
+**Peak** = Beijing time (UTC+8), Monday–Friday, 09:00–12:00 and 14:00–18:00, excluding statutory
+holidays. Everything else, plus weekends, is **valley**.
+
+Unrecognised model ids are priced as `deepseek-flash` (or `deepseek-v4-pro` when the id contains
+`pro`) and the UI marks the figure as an estimate. The table lives in `PRICES` at the top of
+`lib/client.js` — fork and edit to follow a price change.
+
+The fixed-date holiday list (`CN_FIXED_HOLIDAYS`, `MM-DD`) covers New Year, Labour Day and the
+first three days of National Day. Lunar holidays (Spring Festival, Qingming, Dragon Boat,
+Mid-Autumn) must be added by hand.
+
+## HTTP surface
+
+The host half registers three exact, read-only routes on the DSH web server:
+
+| Route | Returns |
+| --- | --- |
+| `GET /api/consumption/turns?sessionId=<id>` | per-turn `{turn, hit, miss, out, time, model}` (log-length cached) |
+| `GET /api/consumption/account` | current provider/model + whether the key is configured |
+| `GET /api/consumption/balance[?force=1]` | `{ok, available, currency, total, granted, toppedUp}`; `is_available:false` renders a red “insufficient balance” |
+
+These routes are **unauthenticated**. If your DSH web server binds `0.0.0.0`, anyone on the
+network can read the balance and token figures; keep it on `127.0.0.1` unless you need otherwise.
+
+## Prompt for your AI agent (copy-paste)
+
+Paste this into Claude Code / Codex / DSH and let it do the install and verification:
+
+```text
+Install the DSH plugin "dsh-consumption-badge" into my web profile and prove it works.
+
+1. In $DSH_HOME/profiles/web run: `dsh plugin --profile web add dsh-consumption-badge`.
+   (For a local checkout use `dsh plugin --profile web add "file:<abs path to the package>"`.)
+2. Check `dsh --profile web --dump-config` contains exactly ONE `id: consumption-badge` row.
+   `dsh plugin add` also appends the package to `dsh.profile.bundles`; if that row does not
+   actually mount after the restart, move it: remove it from `dsh.profile.bundles` and add
+   `- insert: [{id: consumption-badge, name: 'dsh-consumption-badge'}]` to the profile's
+   `cordis.patch.yml` instead. Never leave both.
+3. Restart the DSH process (a browser refresh is NOT enough — host plugins are composed at boot).
+4. Verify the host half: `curl -s http://127.0.0.1:<port>/api/consumption/account` must return
+   `{"ok":true,...}`. Verify the client half:
+   `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:<port>/plugins/dsh-consumption-badge/client.js`
+   must return `200`.
+5. Open any session and confirm the `⛽ <tokens> | ≈¥<cost> | peak|valley` pill in the assistant
+   action row; click it and confirm the modal shows the four cards, the dual-axis chart, the
+   balance, and that Esc closes it.
+6. Open Settings → 消耗: confirm the history chart renders, then
+   switch the time range (今天 / 近一周 / 近一月 / 近一年), switch the workspace
+   (全部工作区 → a specific workspace → 未归属工作区), set the calendar range and confirm both
+   the chart and the footer totals update, and that the Token axis only appears after clicking
+   its legend chip.
+7. If `dsh-plugin-personalization` is installed, open Settings → 个性化 and confirm a 消耗弹窗
+   block appears at the bottom; switch it to 毛玻璃 / 纯色 / 自定义背景 and confirm the ⛽ modal
+   (click a badge) re-renders with that background.
+8. Report which step failed and paste the boot log lines that mention `consumption-badge`.
+
+Rules while doing this: never write to the DSH credentials file yourself (ask me for
+DEEPSEEK_API_KEY), never bind a second server to the same port, and do not try to persist the
+plugin by "running" it — a session-scoped dynamic plugin always dies with the process.
+```
+
+## Notes for AI agents
+
+- This is a **profile-level** plugin: `package.json` carries `dsh.bundle.patch` and `dsh.client`
+  (`platform: web`). It cannot be shipped as a dynamic/session plugin — `harness.handle` and
+  `host.call` are dynamic-runner-only and do not exist for a bundled plugin; the client half talks
+  to the host half over the same-origin routes listed above.
+- The client bundle is hand-written in `window.__ModuleLoader__.load({id, factory})` form and only
+  `require("react")` — React must stay external (a second React instance breaks slot rendering).
+- `lib/index.js` imports nothing at all (no `@deepseek-ai/cordis`), so it does not depend on the
+  profile being able to resolve Cordis; it exports plain `name` / `inject` / `apply`.
+- Self-check without booting DSH: `node check.mjs` (46 assertions over the route contract and the
+  client bundle contract). It lives outside the published `files` list.
+
+## Known limitations
+
+- All amounts are **estimates** — price table, peak/valley rules and model detection can drift
+  from your actual invoice.
+- One chart point per turn; multiple steps in a turn are summed.
+- Balance parsing depends on DeepSeek's `/user/balance` response shape; failures only affect the
+  balance card.
+- The chart covers turns present in the session log fold (whole log), while the pill's total uses
+  the shipped `tokenUsage` projection — both are whole-session, but a heavily-compacted session may
+  differ by the tokens lost to compaction.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-consumption-badge —— bundle patch
+# 本插件作为 profile 的 bundle 层被挂载：profile 的 package.json 把它列进
+# dsh.profile.bundles 后，这一行 insert 就会把它插进配置树。
+# `name:` 必须与安装后的包名完全一致，否则表现为「装上了但界面上没有」。
+- insert:
+    - id: consumption-badge
+      name: dsh-consumption-badge