dsh-usage-spend 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itiswaller
+
+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,94 @@
-# Temporary Holding Version
+# Usage and spend (dsh-usage-spend)
 
-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.
+Shows the session's token usage and an **estimated spend** under the DSH composer, priced at DeepSeek's **peak and off-peak rates**, and appends the amount to the built-in per-turn usage action. Currency and exchange rate are configured on the **Plugins** page.
+
+One package is both the bundle (it declares the `usage-cost` row) and the feature itself, so installing it gives you a card on the Plugins page.
+
+## What you get
+
+- **Composer usage pill**: `85.3M tok · ≈¥3.09 · cache hit 99.4%`, replacing the built-in `usage` row; a `峰` / `谷` badge after the amount says which window it was priced in.
+- **Click the card**: the header shows the exact token count and amount, followed by buckets for cache hits, uncached input, cache reads, cache writes, output and the billing window.
+- **Per-turn action**: the built-in `用量 85.3M tok` becomes `85.3M tok · ≈¥3.09`, priced at that turn's end time.
+- **Peak pricing**: Beijing time weekdays 09:00–12:00 and 14:00–18:00 cost double; everything else, weekends and public holidays included, is off-peak.
+- **Plugins page settings**: currency (CNY / USD / both), exchange rate, and whether to show the sidebar balance, with a read-only price table below the form.
+- **Sidebar balance**: `余额 ¥12.34` at the bottom of the sidebar, refreshed every 60 seconds or on click; the grant is in the tooltip; collapsed the sidebar shows a compact amount. Can be turned off.
+
+## Install
+
+```sh
+dsh plugin --profile <profile> add dsh-usage-spend
+```
+
+Or in DSH Desktop / Web open **Plugins → Add plugin**, enter `dsh-usage-spend`, then choose **Enable now**. Restart or reload afterwards.
+
+Open **Plugins** and expand the **Usage and spend** card to confirm the `usage-cost` row is on.
+
+## Settings
+
+Click **Configure** on the row; changes apply immediately. They are written to the profile's `cordis.patch.yml`:
+
+```yaml
+- id: usage-cost
+  name: 'dsh-usage-spend'
+  config:
+    currency: CNY      # CNY | USD | BOTH
+    usdToCny: 7.2
+    showBalance: true
+```
+
+Turning the row off removes the pill, the per-turn amount and the sidebar balance; turning it back on restores them.
+
+## How the estimate works
+
+Rates come from DeepSeek's official card (`api-docs.deepseek.com/zh-cn/quick_start/pricing`, checked 2026-11-07), in **CNY per 1M tokens**, and the table below is the **off-peak** rate:
+
+| Model | Input (cache miss) | Input (cache hit) | Output |
+|---|---:|---:|---:|
+| `deepseek-flash` (DeepSeek-V4.1-Flash-1017) | 1 | 0.02 | 4 |
+| `deepseek-v4-pro` (DeepSeek-V4-Pro-0813) | 4.5 | 0.15 | 13.5 |
+
+`deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` are retired names that still work: requests are served by V4.1-Flash and billed at the Flash price, so they share its rates. `deepseek-chat` and `deepseek-reasoner` were discontinued on 2026-07-24 and are no longer priced.
+
+### Peak and off-peak
+
+DeepSeek charges half the peak price off-peak, so **peak = twice the table**.
+
+- Peak: Beijing time, **Monday to Friday**, `09:00–12:00` and `14:00–18:00`
+- Everything else is off-peak: nights, the lunch gap, **weekends** and **whole public holidays**
+- Holidays follow the State Council schedule; the plugin ships the 2026 dates and needs one update a year
+
+How the numbers are produced:
+
+- Cost = (uncached input × input + cache reads × cache-read + cache writes × cache-write + output × output) / 1e6 × window multiplier
+- Cache writes bill at the cache-miss input price, matching DeepSeek
+- **Per-turn amounts use that turn's end time**, so they are exact
+- **The session total uses the window in effect now**: the whole-log token projection carries no time dimension, so a session cannot be replayed turn by turn. Reopening an old session prices the total at the window you open it in while the per-turn amounts stay put
+- The `峰` / `谷` badge on the pill shows which window the total used
+- CNY is the base currency; USD is converted with the configured rate and only affects that column
+- Discounts, granted credit, Search/Fetch fees and the platform's actual bill are **not** included. This is an estimate only.
+
+## Custom prices
+
+Write `localStorage["dsh.cost.prices"]` from the browser console, keyed by model name (**CNY per 1M tokens, off-peak**; peak doubles it):
+
+```json
+{
+  "deepseek-flash": { "input": 1, "cacheRead": 0.02, "cacheWrite": 1, "output": 4 }
+}
+```
+
+Keys may be the full model name, `provider/model`, or the bare model name. Reload to apply.
+
+> 0.1.0 overrides were USD; 0.2.0 switched to CNY and added the peak multiplier, so old overrides need re-entering in the new unit.
+
+## Compatibility and limits
+
+- Targets the client slot / projection API of DSH `0.2.2-rc.1`.
+- The per-turn text is rewritten through a DOM observer; if a DSH release changes the built-in button's structure it degrades to the original `用量 N tok` and never affects the session.
+- Switching models inside a session estimates the whole session at the current model's prices.
+- The sidebar balance calls `account.getBalance` (DeepSeek account) and shows `--` when signed out or when the read fails. It is the platform's balance, not a local estimate.
+- Currency and rate come from host settings; when the settings service is unavailable it falls back to `localStorage` (`dsh.cost.currency` / `dsh.cost.usdToCny`).
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,94 @@
+# 用量与花费（dsh-usage-spend）
+
+在 DSH 的输入框下方显示本次会话的 token 用量与**估算花费**，按 DeepSeek 官方的**峰谷价**计价，并把金额补到内置的每轮用量按钮上。币种和汇率在 **插件** 页配置。
+
+一个包同时是 bundle（声明 `usage-cost` 这一行）和功能本体，装上即出现插件页卡片。
+
+## 功能
+
+- **底部用量 pill**：`85.3M tok · ≈¥3.09 · 缓存命中 99.4%`，替换内置的 `usage` 行；金额后面带 `峰` / `谷` 小标签，标明这一笔按哪档价格算。
+- **点击卡片**：标题行显示精确 token 数与金额，下面是缓存命中、未缓存输入、缓存读取、缓存写入、输出、计费时段。
+- **每轮按钮**：把内置的 `用量 85.3M tok` 改成 `85.3M tok · ≈¥3.09`，金额按该轮结束时间判断峰谷。
+- **峰谷计价**：北京时间工作日 9:00–12:00、14:00–18:00 为高峰（价目 ×2），其余时段含周末与法定节假日为空闲。
+- **插件页配置**：`币种`（人民币 / 美元 / 同时显示）、`汇率（1 USD = ? CNY）`、是否显示左侧栏余额，并在表单下方以只读表格展示当前单价表。
+- **左侧栏余额**：在侧栏底部显示 `余额 ¥12.34`，每 60 秒或点击时刷新；赠金放在 tooltip 里；折叠栏显示紧凑金额。可关闭。
+
+## 安装
+
+```sh
+dsh plugin --profile <profile> add dsh-usage-spend
+```
+
+或者在 DSH 桌面端 / Web 的 **插件 → 添加插件** 里输入包名 `dsh-usage-spend`，装完点 **立即启用**。之后重启或刷新页面。
+
+启用后打开 **插件** 页，能看到 **用量与花费** 卡片，展开确认 `usage-cost` 行是开启的。
+
+## 配置
+
+点该行的 **配置** 修改，保存后立即生效。配置写入 profile 的 `cordis.patch.yml`：
+
+```yaml
+- id: usage-cost
+  name: 'dsh-usage-spend'
+  config:
+    currency: CNY      # CNY | USD | BOTH
+    usdToCny: 7.2
+    showBalance: true
+```
+
+关闭该行会移除底部 pill、每轮金额与侧栏余额；重新打开即恢复。
+
+## 估算口径
+
+单价取自 DeepSeek 官方价目（`api-docs.deepseek.com/zh-cn/quick_start/pricing`，2026-11-07 核对），单位是**元 / 百万 token**，下表为**空闲时段**价格：
+
+| 模型 | 输入（缓存未命中） | 输入（缓存命中） | 输出 |
+|---|---:|---:|---:|
+| `deepseek-flash`（DeepSeek-V4.1-Flash-1017） | 1 | 0.02 | 4 |
+| `deepseek-v4-pro`（DeepSeek-V4-Pro-0813） | 4.5 | 0.15 | 13.5 |
+
+`deepseek-v4-flash` 与 `deepseek-v4-flash-vision-exp` 是**已下线但仍可调用**的旧模型名，请求由 V4.1-Flash 提供并按 Flash 价格计费，因此与 `deepseek-flash` 同价。`deepseek-chat` / `deepseek-reasoner` 已于 2026-07-24 停止服务，不再有价格。
+
+### 峰谷计价
+
+官方规则：**空闲时段价格是高峰时段的一半**，即高峰 = 表中价格 ×2。
+
+- 高峰时段：北京时间**周一至周五** `9:00–12:00`、`14:00–18:00`
+- 其余时段全部为空闲：夜间、午休、**周末**、**中国法定节假日全天**
+- 节假日按国务院办公厅的放假安排，插件内置 2026 年日期（元旦、春节、清明、劳动节、端午、中秋、国庆）；次年安排公布后需要更新一次
+
+计算方式：
+
+- 费用 = （未缓存输入 × 输入价 + 缓存读取 × 缓存读价 + 缓存写入 × 缓存写价 + 输出 × 输出价）/ 1e6 × 时段倍率
+- 缓存写入按缓存未命中的输入价计费，与官方一致
+- **单轮金额按该轮结束时间**判断峰谷，是精确的
+- **会话总额按当前时段**估算：整份 token 统计没有时间维度，无法回溯每一轮分别落在哪个时段。所以隔天回看老会话时，总额按你打开它时的时段算，而每轮按钮上的金额不变
+- 底部 pill 上的 `峰` / `谷` 小标签就是当前用的哪档
+- 币种默认人民币；选美元时按配置的汇率把人民币换算过去，汇率只影响美元那一栏
+- **不包含**折扣、赠送额度、Search/Fetch 费用或平台实际账单，只用于估算
+
+## 自定义价格
+
+价格表可用浏览器 `localStorage` 覆盖，格式为「模型名 → **元** / 1M token」，填**空闲时段**价格（高峰会再乘 2）：
+
+```json
+{
+  "deepseek-flash": { "input": 1, "cacheRead": 0.02, "cacheWrite": 1, "output": 4 }
+}
+```
+
+键可以是完整模型名、`provider/model` 或裸模型名；刷新页面生效。
+
+> 0.1.0 的覆盖值是美元，0.2.0 起改为人民币并新增峰谷倍率，旧覆盖值需要按新单位重填。
+
+## 兼容性与限制
+
+- 面向 DSH `0.2.2-rc.1` 的客户端 slot / projection API。
+- 每轮按钮的文字通过 DOM 观察器改写内置按钮；DSH 改版后结构变化可能让它退化为原来的 `用量 N tok`，不影响会话。
+- 会话内切换模型时，整段会话按当前模型单价估算。
+- 左侧栏余额调用 `account.getBalance`（DeepSeek 账号），未登录或读取失败时显示 `--`；余额来自平台，不是本地估算。
+- 币种与汇率优先读 Host 配置；设置服务不可用时退回 `localStorage`（`dsh.cost.currency` / `dsh.cost.usdToCny`）。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# Bundle layer for dsh-usage-spend.
+# One row per feature; the row points at this same package, which also carries
+# the browser half through `dsh.client`. The row id stays stable so profile
+# patches and the settings key `<package>#<row id>` keep working across versions.
+- insert:
+    - id: usage-cost
+      name: 'dsh-usage-spend'
+      config:
+        currency: CNY
+        usdToCny: 7.2
+        showBalance: true

package/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none">
+  <rect x="3" y="5" width="26" height="22" rx="6" stroke="currentColor" stroke-width="2"/>
+  <path d="M8 20V16M13 20V12M18 20V18M23 20V10" stroke="currentColor" stroke-width="2.4" stroke-linecap="round"/>
+</svg>