dsh-wallet
DeepSeek Harness 侧边栏小组件：DeepSeek API 钱包余额 + 峰谷定价 + 时段切换倒计时 + 费用明细面板。
渲染在最左侧边栏的「对话管理」区域正下方（sidebar.footer.action 槽位，设置按钮上方），随侧边栏展开/收起自动显隐。
功能
| 区块 | 内容 |
|---|
| 余额 | 调用 https://api.deepseek.com/user/balance 的官方余额，每 60 秒自动刷新；仅本机（loopback）可访问代理路由 |
| 峰谷定价 | 当前时段徽章（空闲中/高峰中）+ 距下一时段切换的秒级倒计时。高峰 = 北京时间 周一~五 09:00-12:00 / 14:00-18:00，其余空闲半价 |
| 警告阈值 | 三级提醒：① 余额跌破红警线（默认 ¥50）→ 红色弹窗/放大警示；② 余额在「红警线 + 提前提醒」带内（默认 < ¥250）→ 黄色提醒；③ 按近 7 天日均算可用天数低于强提醒阈值（默认 3 天）→ 紫色强提醒。通用设置可配红警线/提前提醒/强提醒天数/提醒方式，红警线 0 = 关闭 |
| 费用明细（点卡片打开） | ① 概览：余额/赠送-充值拆分、时段与倒计时（附行动建议：跨高峰提醒 + 实测 flash/pro 单价倍数）、三级提醒分级、价目表；② 近日消耗：近 14 天每日柱状图 + 窗口合计/日均/今日/空闲+高峰（分项之和恒等于合计）/有消耗会话数 + 口径说明；③ 余额预测：近 7 天日均 / 14 天中位数 / 最省的一天 / 最贵的一天 / 全落高峰 ×2 五种口径分别换算可用天数（<3 天红、<7 天橙、其余绿）；④ 平均每天最烧钱的时段：24 小时柱状图 + 前三名（北京时间）；⑤ 花的钱主要在哪：输入（未命中缓存）/ 输入（缓存命中）/ 输出 三段占比 + 缓存命中率；⑥ 模型用量：耗费占比圆盘图（中心为主力模型占比）+ 每个模型的费用/占比/步数/会话数/token/缓存命中率/元每步/高峰花费，样本足够时给单价倍率；⑦ 会话费用榜：近 30 天各会话总费用、所用模型、步数、token 与最近活动时间 |
价格与时段规则来自 DeepSeek 官方定价页（api-docs.deepseek.com，2026-08-17 生效版本）；官方改价后需同步 client.js 顶部的 PRICE_ROWS 与 stats.js 顶部的 PRICING。
原理
| 层 | 机制 |
|---|
| Host | 在 dsh web server 上注册两个 loopback-only 精确路由：GET /api/dsh-wallet/balance（用 API key 代理官方余额接口，key 取自 $DEEPSEEK_API_KEY，其次 ~/.dsh/.env；响应只含余额字段）与 GET /api/dsh-wallet/stats（会话费用统计） |
| 统计 | stats.js 直接读会话库 $DSH_HOME/sessions/<slug>/session-<id>/session.v3.jsonl.zstd：主日志是「拼接 zstd 帧」容器，逐帧切分解码（Node 的 one-shot zstd API 只吃第一帧）；再折叠每条 assistant/message 的 durable usage 样本（inputTokens 未命中缓存 / cacheReadTokens 缓存命中 / outputTokens 输出）按官方价目表 × 峰谷倍率折算成钱，按「北京时间小时 × 模型」分桶聚合（会话中途换模型会分别计入各自模型） |
| 缓存与冷启动 | 每个会话文件的解析结果按 (size, mtime) 落盘缓存（$DSH_HOME/storages/dsh-wallet/stats-cache.json，CACHE_VERSION 变更即自动重建），只有正在写的那个会话会重扫；冷启动首扫按 2s 预算分段返回（warming:true + 剩余会话数），插件启动 4 秒后在后台自动续扫到完成，客户端在弹窗打开期间每 2.5 秒续拉 |
| 口径与尾差 | 响应里三种计数分开给：counts.scannedFiles（按 mtime 扫到的会话文件）/ counts.windowSessions（统计窗口内有活动）/ counts.withCost（窗口内真花了钱），界面按这三个口径分别标注，不再混用；金额一律先定合计再用 roundParts() 按最大余额法把尾差补给最大项，保证「分项之和 === 合计」（避免 103.03 + 132.58 ≠ 235.60 这种假错误） |
| 热加载 | stats.js 按文件 mtime 动态 import：改计价/采集逻辑刷新页面即可生效，只有 index.js（路由表）改动才需要重启 dsh web |
| 余额实测 | 每次余额刷新把余额样本追加进 $DSH_HOME/storages/dsh-wallet/balance-log.json（节流 + 值变化才写），明细里的「实测余额对照」用首末差值给出真实消耗/充值对照（样本 ≥2 才有） |
| Client | 手写 window.__ModuleLoader__ 工厂格式 bundle，注册进 sidebar.footer.action 槽位；时段计算是纯本地时钟数学（北京时间 UTC+8），离线可用 |
| 通信 | 浏览器直接 fetch('/api/dsh-wallet/...') 同源调用，无 Typert / RPC 依赖 |
网络说明：/api/dsh-wallet/stats 只读本机会话日志，不联网；/api/dsh-wallet/balance 只访问 DeepSeek 官方余额接口。
安装
dsh plugin --profile web add github:Bobbychina/dsh-wallet
装完即用，不需要手改 profile：dsh plugin add 是 pnpm 转发器，装完会按 package.json 的 dsh.bundle 声明自动把插件加进该 profile 的 dsh.profile.bundles，插件自带的 cordis.patch.yml 负责往组合里 insert。
改动 host 半边（index.js / stats.js）后需重启 dsh web 才会注册新路由；只改 client.js 刷新页面即可（bundle 按内容 rev 从磁盘重取）。
本地开发（直接链本地目录）：
dsh plugin --profile web add file:/path/to/dsh-wallet
profile 的 node_modules/<插件名> 是安装时的副本，不是软链：改完源目录要重新 dsh plugin add 或把文件同步进 $DSH_HOME/profiles/web/node_modules/dsh-wallet/。
兼容性与前置条件
- 依赖 dsh
0.1.5-rc.2 的侧边栏槽位 sidebar.footer.action 与手写 window.__ModuleLoader__ bundle 格式；dsh 版本不同（槽位名或 bundle 装载协议变更）可能挂不上，表现为侧边栏不出现卡片。
- 余额需要
DEEPSEEK_API_KEY（process env，其次 ~/.dsh/.env）；没有 key 时峰谷时段/倒计时照常，只有余额显示报"未找到 DEEPSEEK_API_KEY"。
- 费用统计依赖
$DSH_HOME/sessions/<slug>/session-<id>/session.v3.jsonl.zstd 的存储布局，dsh 换存储格式需同步 stats.js。
- git 安装的插件若带 install/prepare 脚本，pnpm 会拦下来要求写
allowBuilds；本插件是纯 JS 无构建步骤，不触发该拦截。
卸载
dsh plugin --profile web remove dsh-wallet
License
MIT
