dsh-token-curve 0.0.0-stage → 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 STao-Gee
+
+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,171 @@
-# Temporary Holding Version
+# dsh-token-curve
 
-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.
+右栏的 **Token 曲线**，两页：
+
+- **曲线**：当前对话每一轮花了多少 token、多少钱，累计到现在多少；点曲线上任意一轮的节点，展开那一轮的完整明细。
+- **账单**：本机全部会话的账本，**按月 / 按周汇总**、逐轮明细、**导出 Excel**，可直接报给老板做报销或查花销。
+
+顶部还有**账户余额**和**本会话费用**两个胶囊（都在标题行右侧），余额每 30 秒自己更新。
+
+## 安装
+
+```sh
+dsh plugin add dsh-token-curve
+```
+
+装完重启 Harness（或在插件页启用 `include:token-curve`），打开任意会话，按 `Ctrl+Alt+U`，或点会话头右侧的曲线图标。
+
+> 也可以从源码装：`dsh plugin add github:STao-Gee/dsh-token-curve`。
+> 这条路**要求本机装了 Git**，没有 Git 会报 `git ls-remote failed`——普通用户请用上面那条 npm 的。
+
+- 需要 **DeepSeek Harness >= 0.2.1-rc.5**，桌面端（Electron）。
+- Windows 上验证过；macOS / Linux 未验证。
+- 插件默认**不自动打开**——右栏常被文件/终端占着，开不开由你按。
+- 不往任何地方上传你的会话内容；只读本机 `~/.dsh/sessions` 下的日志。
+
+## 一、曲线页
+
+- 顶部大字：本对话累计 tokens；右上角两个胶囊：**余额**（蓝）和**本会话**费用（绿）。
+- 中间图：每一轮一根柱 + 一条累计曲线。图上是两条量程：左上「峰值 …/轮」、右上「累计 …」。
+- 两个开关：
+  - **Token / 费用** —— 切图的口径（费用按官方价目换算）。
+  - **图例** —— 输入 / 缓存读 / 输出 / 累计 逐条开关。
+- **点一下某一轮**（柱子或曲线上的圆点都行）：展开该轮明细 ——
+  未缓存输入 / 写缓存 / 缓存读 / 输出 四项的**确切数字、占比条、占比**，
+  加「N 次模型调用 · 缓存命中 x% · 精确 tokens · 开始–结束时刻」、该轮金额、
+  「高峰 x 条 / 空闲 y 条」。再点一次或按右上角 × 收起。
+- 下面表：每轮的 token 与金额，点行也能展开；进行中的那一轮带橙色小点。
+- 每 4 秒自己刷一次；右上角 ↻ 手动刷（会连余额、账单一起刷）。
+
+## 二、数字单位（v0.4.1 新增，可切）
+
+标题行下方有一颗 `单位 万/亿` 胶囊，**点一下换成 `M/K`**，再点换回来；记在浏览器本地，下次打开还是上次的选择。
+
+- **万/亿（默认，国内口径）**：
+  - 不到 1 万 → 显示实际数字，带千分位（如 `8,234`）；
+  - 1 万 ~ 1 亿 → 用「万」，**2 位小数**（如 `1.23万`、`8322.66万`）；
+  - 1 亿以上 → 用「亿」，**4 位小数**（如 `22.7404亿`）。
+- **M/K（国外口径）**：不到 1 千显示实际值；1 千~100 万用 `K`；100 万以上用 `M`；10 亿以上用 `B`（都是 2 位小数）。
+- 图上的刻度、悬浮提示、表格、账单卡片、账单明细都跟着这个口径走；
+  单轮明细里的四项「确切数字」保持精确值（那边本来就是给核对用的）。
+- **导出的 Excel 不受影响**：表里永远是精确数字（不写「万」），方便财务再求和。
+
+
+## 三、账户余额（v0.4.0 新增）
+
+位置：标题行，**「本会话费用」左边的蓝色胶囊**。
+
+- 数据来自 DSH 自己的账号服务（`deepseekAccount.getBalance`），跟「设置 → 账户」页的钱包**同一个来源**；
+  插件不接触 token、不碰登录态，只把数字读出来显示。
+- 显示的是**充值钱包**；有赠金时，鼠标停在胶囊上能看到「充值钱包 ¥x · 赠金 ¥y · 更新于 时:分:秒」。
+- 每 30 秒自动刷新一次；**点一下胶囊立刻刷新**。宿主侧另有 25 秒缓存，多个面板不会重复打平台。
+- 读不到时不会瞎显示 0：
+  - 没登录 → 灰色「余额 —」，提示去「设置 → 账户」登录；
+  - 查询失败 → 红色「余额 —」，鼠标停上去看原因；
+  - 账号服务没就绪 → 灰色，提示原因。
+- **金额会随用量下降**，这是平台钱包的真实变化；跟本对话费用是两笔账（一个是「还剩多少」，一个是「这次花了多少」）。
+
+## 四、账单页（v0.4.0 新增）
+
+顶部「曲线 / 账单」切换。
+
+- **口径**：按月（自然月）或按周（**周一至周日**，北京时间）。
+- **区间**：全部 / 本月 / 上月 / 近三个月 / 今年。
+- **四张卡片**：合计费用、Tokens、轮次、会话数。
+- **汇总表**：一行一个期间，列「金额 / 占比 / 轮次」；**点一行展开这一格的逐轮明细**
+  （时刻、会话名、tokens、金额；子会话带「子」标）。一格超过 150 条时只铺最近 150 条，
+  导出的 Excel 里是全的。
+- **导出 Excel**：按当前「口径 + 区间」导出，浏览器会弹保存框（默认存到「下载」）。
+  文件名形如 `Token账单_按月_全部_20261108.xlsx`。
+- 账单只在切到这一页时才算；每 60 秒自动重算一次。第一次打开要把本机会话日志读一遍，
+  耗时随日志量增长；之后只重读有变化的那个会话。
+
+### 导出的 Excel 长什么样
+
+一个文件三张表：
+
+1. **按月汇总 / 按周汇总**：标题、统计区间、计价口径、**合计金额（含人民币大写）**、生成时间；
+   表头带冻结、列宽调好；期间行 + 合计行；表尾说明「只统计本机日志」「分叉会话抄来的历史不计」
+   「未收录价目的消息不计」。
+2. **费用明细**：一行一轮，列 日期 / 时间 / 会话 / 工作区 / 轮次 / 模型 / 输入 / 缓存读 / 写缓存 /
+   输出 / 合计 tokens / 金额（元）；带筛选和冻结；最后一行合计。
+3. **按会话**：每个会话一行（会话 / 工作区 / 主会话或子会话 / 轮次 / tokens / 金额 / 首次 / 末次）。
+
+数字都是**真数字**（不是文本），Excel 里可以直接再求和、透视。
+金额按每条 4 位小数落定后逐行相加，所以**明细列加起来 == 合计行**，不会差几分钱。
+打印已设好：**A4 横向、按一页宽缩放、表头行自动重复**，直接打就是报销单的样子。
+
+## 五、口径（不是估算）
+
+宿主侧读会话日志（`session.v4.jsonl.zstd`，逐帧解压），把每条 `assistant/message`
+上报的 `usage` 按轮相加；费用是**逐条消息**按自己的时间戳判峰谷后分别计价再相加 ——
+跨峰谷的一轮也不会算成同一个价。
+
+- **只读**：不写、不改、不删任何会话文件。
+- **账单覆盖本机全部会话**（含子会话、含其它工作区）。子会话的花费不和主会话重复。
+- **分叉会话不重复收费（v0.4.0 修）**：从别的会话分叉出来的会话（日志头 `isSeeded=true` +
+  `parentSession`）会把父会话的历史事件整段抄进自己的日志。那部分 token 父会话已经付过，
+  按「分叉时刻（createdAt）」切掉，不再算第二遍。
+- **历史轮次按当前价目算**：日志里只有 token、没有当时单价；官方调价后老会话金额会跟着变。
+  这是估算口径，不是账单快照 —— 导出的表里也写明了。
+- **价目会跟着官方更新**：距上次成功同步超过 12 小时（失败 1 小时重试）就去官方《模型 & 价格》拉一次；
+  严格校验后才采用（两模型都在、六价为正、高峰≥空闲、未命中≥命中、输出≥命中、列序未变），
+  任一条不成立就整批拒收、继续用上一份。面板上的 `价目 YYYY-MM-DD` 胶囊就是当前版本。
+- **高峰** = 北京时间周一至周五 9:00–12:00、14:00–18:00；其余（含周末、法定节假日全天）空闲。
+  **法定节假日已扣除**（内置 2025 / 2026 / 2027，来源国务院办公厅通知）。
+- 缓存写入官方价目没有单列，按「未命中输入」计价（宁可高估，不漏算）。
+- 模型不在表里时：金额一栏不显示，副标题提示「未收录该模型价目，费用不计」；导出里也不计，
+  并在表尾写明有几条。
+
+## 六、开关键（自己改）
+
+默认 **Ctrl+Alt+U**。整页只装一个监听，按一下开、再按一下关。
+
+改键：点面板里那颗 `⌨ Ctrl+Alt+U` 胶囊 → 直接按你想要的组合（必须带 Ctrl 或 Alt）→
+记在浏览器本地（`localStorage['dsh-token-curve:hotkey']`），立刻生效，不用重启。
+按 Esc 取消。
+
+> **默认不自动打开**：右栏常被文件/终端占着，开不开由你按。
+> 会话头右侧那颗曲线图标按钮是同一个开关，鼠标也能用。
+
+## 七、自检清单
+
+以下是开发时用的断言清单（脚本不随插件分发；需要可向作者索取）：
+
+| 脚本 | 覆盖的断言 |
+|---|---|
+| `node --check` | `index.js` / `client.js` 语法 |
+| `verify-fold.mjs` | 单会话：逐轮合计 == 总计，金额也对 |
+| `check-peak.mjs` | 峰谷判定、法定节假日 |
+| `check-pricing.mjs` | 官方价目页能解析、与内置表一致 |
+| `verify-ledger.mjs` | 月 / 周 / 明细 / 会话四条路合计一致、周期边界、区间过滤、金额大写、跨会话无重复 message id |
+| `verify-xlsx.mjs` | 导出的 xlsx：zip 结构 + 外部读者核对行列合计、百分比格式 |
+| `verify-balance.mjs` | 余额四条路（已登录 / 凭证失效 / 查询失败 / 服务没就绪）+ 缓存 + 请求头 |
+| `verify-units.mjs` | 数字单位：万/亿 与 M/K 的换算（含边界与负数） |
+
+运行时看 `host.log`：应有 `apply ran` / `account service injected` / `route registered`；
+余额变化时会有一行 `balance ready total=…`；导出会有一行 `export … rows=…`。
+
+验证脚本会把 `DSH_TOKEN_CURVE_NO_LOG=1` 打开，不会把假数据写进真机日志。
+
+## 八、已知限制
+
+1. 桌面宠物（dsh-pet）会浮在右栏上方，可能接走落在它身上的点击；拖开或关掉即可。
+2. 进行中的那一轮数字会持续变大（每 4 秒刷一次），柱子带「进行中」标记。
+3. 轮次很少（2–3 轮）时柱状图分辨力有限，主要看累计曲线和明细。
+4. 模拟按键（SendInput）的 Ctrl/Alt 组合进不了这个应用；热键链路是用会话头按钮验证的。
+5. 账单第一次统计要把全部会话日志读一遍，耗时随数据量增长；这期间宿主是同步读的，属于已知取舍。
+6. 会话被删掉后，它的账也就不在了 —— 只统计还留着的日志。
+7. 导出用的是浏览器下载：桌面端会弹一次保存框，需要点「保存」。
+8. 余额依赖 DSH 账号登录；退出登录后只显示「—」，不会编一个数。
+
+## 九、卸载
+
+宿主条目 id 是 `include:token-curve`，可用 `plugin_manager set_plugin` 关掉而不删文件；
+彻底删：先 remove_bundle，再删目录 `local-plugins/dsh-token-curve`。
+
+## 十、反馈与许可
+
+- 问题 / 新功能 / 想要的新口径：<https://github.com/STao-Gee/dsh-token-curve/issues>
+- 许可：MIT。
+- 觉得有用就点个 star，或者来 Issue 里说一句你用它做了什么。