dsh-usage-stats（用量统计 · 统一插件）

一个插件，两个功能面，统一安装/卸载（dsh-turn-tokens 已合并进本插件，不要再单独装它）：

功能面	位置	内容
用量统计面板	设置 → 用量统计	全会话 token 合计 / 估算费用 / 按模型分布；可编辑价格表；会话卡片列表 + 逐回合明细
消息行「本次token」	对话消息行上方	每条已完成助手消息上方常驻显示该回合实际消耗的 token：本次token：输入(未命中) X · 输入(命中缓存) Y · 输出 Z · 思考 R（与价格表同口径）

功能一：设置页「用量统计」

• 总览卡片：全会话合计（会话数 / 回合总数 / 输入 / 输出 / 缓存读取 / 缓存写入 / 思考推理 tokens + 估算费用），以及按模型的分布。
• 价格表（可编辑）：费用估算用单价（元 / 每百万 tokens），按 DeepSeek 官方计费口径分三列——输入（未命中缓存） / 输入（命中缓存） / 输出；支持增删模型行、编辑价格、恢复默认；保存在浏览器 localStorage（键 dsh.usageStats.prices.v4），仅本浏览器生效。默认值为官方高峰价（deepseek-flash / deepseek-v4-pro，2026-09-10 抓取，估算偏保守），请按实际价格及时段修改。
• 会话列表（卡片式）：每会话一张卡片——标题独占整行（完整换行显示）、下方会话 ID、再下方元信息 chips（工作区 / 回合 / 输入 / 输出 / 缓存 / 估算费用，自动换行）；点「明细」在卡片内展开逐回合卡片（用户消息独占整行完整阅读，下方回合号 / 步骤 / 工具调用 / 输出 tk / 估算 / 模型 / 完成状态）。
• 余额卡（DeepSeek 实时）：页顶展示账户真实余额（总余额 / 充值余额 / 赠金余额 / API 是否可用），由后端用配置的 API Key 调官方 /user/balance 接口实时获取（非估算），可点「刷新余额」手动更新；未配置 Key 或查询失败会给出对应提示。
• 刷新统计按钮手动重新扫描。

功能二：消息行「本次token」

每条已完成助手消息的操作行上方，右对齐常驻显示该回合实际消耗的 token：

            本次token：输入(未命中) 3.3k · 输入(命中缓存) 832.3k · 输出 4.6k · 思考 3.7k · 费用约 ¥0.13   ← 本插件
复制 · 👍👎 · 在新对话中分支      用时 9分03秒 · 首token 6.1秒 · 119 tok/s  ← 官方(悬停)

• 显示项（与价格表同口径）：输入(未命中缓存)（= inputTokens + cacheWriteTokens，首次写入缓存的输入按未命中计费）/** 输入(命中缓存)（= cacheReadTokens）/ 输出** / 思考（思考已计入输出、不重复计费，仅作参考）+ 费用约（按价格表对回合内各模型分别计价估算）；只在有数据时出现；数字用 k/M 缩写；悬停可见完整口径说明。对话结束后该项会追加显示 DeepSeek 账户真实余额（余额 ¥xx.xx，5 分钟缓存一次），与预估消耗一起展示。
• 数据来源：会话快照中该回合所有 assistant/message 事件的 usage 字段求和（与面板同源）；费用按当前价格表估算（价格可在 设置 → 用量统计 调整）。
• 官方悬停显示的用时/首token/速率是官方代码，本插件不改动；token 数字常驻显示。
• 无 usage 数据或无法解析时静默不渲染，不影响任何官方 UI。
• 窗口限制：消息行数据取自客户端会话窗口（snapshot.nodes / 0.1.2 的 chat.legacy.nodes），窗口边界处的回合可能只统计到窗口内部分（token 与费用偏小）；完整精确的逐回合数据以设置页「用量统计 → 明细」为准。

与官方功能的区别（不冲突、不重复）

• 官方 0.1.2+ 新增 ContextMeter（输入框右侧环形仪表）：显示当前会话的上下文窗口占用（~已用 / 上下文窗口 + 系统/工具/消息三段占比）——是"容量"视角的估算值（帮助判断上下文快满时压缩/开新会话），不包含费用。
• 本插件：显示实际计费 token（每回合 本次token + 全会话统计面板）+ 费用估算 + DeepSeek 账户实时余额——是"账单"视角，数据来自模型实际报告的 usage。两者互补：官方不显示费用/逐回合实际用量，本插件不显示上下文占用。
• 兼容性：dsh 0.1.2 重构了客户端快照结构（useSession 改返回 SessionSnapshot，聊天数据走新的 useChat → chat.legacy.nodes；turnTail/assistant-actions 插槽迁至 dsh-client-ui-chat 包，契约不变）。本插件消息行已做双版本兼容（0.1.2 用 useChat，旧版回退 useSession）。

数据来源（面板）

• 直接扫描 DSH_HOME/sessions/**/session.jsonl.zstd（zstd 多帧）。解码用自包含的 adoptPhysicalRow 跨版本容错处理（忽略 ignorable、折叠 v3 的 surfaceOp.op==="replace" 旧事件区间、按 seq 收纳），不依赖 @deepseek-ai/dsh-session 的内部导出（decodeStorageRecord 在 0.1.5-alpha v3 已移除），与 dsh-session-rewind 同一套机制。
• 统计对象是每条 assistant/message 事件里的 usage 字段：inputTokens / outputTokens / cacheReadTokens / cacheWriteTokens / reasoningTokens；模型名取 message.source.model。

费用计算口径（对齐 DeepSeek 官方）

• 日志不包含费用，本插件按价格表估算，仅供成本参考，请以服务商账单为准。
• 公式：费用 = 输入(未命中缓存) × 未命中单价 + 输入(命中缓存) × 命中单价 + 输出 × 输出单价，各项 token 数 ÷ 1e6 × 单价（元/每百万 tokens）。
• 字段映射：inputTokens + cacheWriteTokens（首次写入缓存的输入按未命中价计费）→ 未命中列；cacheReadTokens → 命中列；outputTokens → 输出列。
• 思考 token：reasoningTokens 已计入 outputTokens（DeepSeek 输出总量含思考），不重复计费。
• 参考：DeepSeek 官方模型 & 价格（2026-09-10 抓取：主力 deepseek-flash（DeepSeek-V4.1-Flash）高峰 命中 0.04 / 未命中 2.0 / 输出 8.0 元每百万 tokens；deepseek-v4-pro 高峰 0.30 / 9.0 / 27.0。官方为峰谷定价——高峰北京周一至周五 9:00-12:00 / 14:00-18:00，高峰为低谷 2 倍；插件默认取高峰价（估算偏保守），前端价格表可改，请按实际价格/时段修改）。
• 模型 id 退役与并价（2026-09 官方调整，重要）：当前在售主力 id 是 deepseek-flash（= DeepSeek-V4.1-Flash，1M 上下文 / 384K 最大输出 / 支持图片）。旧的 deepseek-v4-flash 与 deepseek-v4-flash-vision-exp 已退役，请求仍受理但由 V4.1-Flash 服务、按 Flash 价计费；deepseek-v4-pro 自 2026-09-14 12:00（北京时间） 起也整批路由到 V4.1-Flash 并按 Flash 价计费。因此默认价格表把三个 Flash 系 id 并到同一单价，保留 deepseek-v4-pro 自身单价直到退役完成，避免历史会话与当前会话算错费用。

接口（宿主端）

路由	说明
GET /__dsh/usage-stats/list	全部会话的用量汇总（每会话按模型聚合；解码失败会带 error 字段）
GET /__dsh/usage-stats/detail?id=	单个会话的逐回合明细 + 全会话汇总
GET /__dsh/usage-stats/balance	DeepSeek 账户真实余额（后端持 Key 调官方 /user/balance）

均要求自定义头 X-DSH-Usage-Stats: 1 防跨站触发（跨域请求无法携带该头）。

DeepSeek 真实余额（实扣非估算，2026-08-25）

• 请求：后端读取配置的 API Key，向官方 GET https://api.deepseek.com/user/balance 发起请求（Authorization: Bearer ），返回 is_available + balance_infos[]（currency / total_balance / granted_balance / topped_up_balance，单位为元）。Key 只存在于服务端，不出后端、不暴露给浏览器。
• Key 来源（取值优先级）：① 运行进程环境变量 DEEPSEEK_API_KEY；② DSH_HOME/.credentials.yaml 的 refs.DEEPSEEK_API_KEY（用户在 WebUI 设置面板配置后由 harness 持久化到该 yaml）。两者都没有则提示「未配置 Key」。
• 展示位置：设置页「用量统计」页顶余额卡 + 消息行「本次token」末尾（对话结束后显示，与预估消耗一起）。
• 缓存：消息行余额 5 分钟缓存一次（模块级，避免多个回合反复请求）；设置页余额卡可选「刷新余额」强制更新。
• 失败处理：未配置 Key / 网络异常 / 超时(8s) / HTTP 非 2xx，均返回明确提示文案，不阻塞页面其它功能。

主题与配色（深浅主题，2026-08-25）

• 背景框固定浅色：会话卡 / 元信息 chips / 回合明细块 / 总览与价格卡 / 表头等背景框刻意保持固定浅色（#ffffff / #f5f5f5 / #fafafa，边框 #dddddd / #e6e6e6），不随深浅主题变化。
• 框内文字固定深色：这些浅色框内部的文字固定为深色（主文字 #1f1f1f、次文字 #8a8f98 / #555555），不随主题变白——因为背景框颜色不变，若框内文字随深色主题变白会白字落白底看不清。含价格表表格内文字（模型名、兜底行等）：这类文字往往无显式 color、靠继承，深色下会落到页面白字，须显式补固定深色（如表格 td 统一 color: #1f1f1f）。
• 页面级文字保留主题自适应：不在框里的页面级文字（页面说明、表格行文字等）仍用 harness 语义变量 var(--dsw-alias-label-*)，随深浅主题自动切换。

即：浅框 + 深字为一组固定样式；只有框外的页面级文字跟随主题。

安装 / 卸载

:: 安装 (一个插件, 两个功能面一起生效)
python launcher.py --install-plugin plugins\dsh-usage-stats

:: 卸载 (两个功能面一起移除)
python launcher.py --remove-plugin dsh-usage-stats

安装后重启服务生效（插件管理窗口也有「选择本地插件文件夹安装…」入口）。

历史版本：v0.1.x 只含设置面板；消息行「本次token」原是独立插件 dsh-turn-tokens（v0.1.0），自 v0.2.0 起合并进本插件。若已装过 dsh-turn-tokens，请先 --remove-plugin dsh-turn-tokens（或插件管理里移除）再安装/升级本插件，避免消息行重复显示。

限制

• 大日志会话较多时，扫描解码全部日志需要几秒（页面有提示）。
• 服务运行中的会话可能仍在写入，统计为截至刷新时的数据。
• 解码失败的会话在列表中标记「解码失败」，不影响其它会话。
• 价格表存在浏览器 localStorage，换浏览器/清缓存后需重新设置（可「恢复默认」再改）。

不修改任何官方文件/包，纯插件实现。