[Plugin] dsh-usage-chart —— DeepSeek 用量 / 成本 / 余额仪表盘（每轮成本解释 · 多币种 · 实时汇率）

[Max-Samson]

[Plugin] dsh-usage-chart —— DeepSeek 用量 / 成本 / 余额仪表盘（每轮成本解释 · 多币种 · 实时汇率）

1. 插件名称与仓库地址

• 名称：dsh-usage-chart（npm 发布，dsh.bundle.patch → cordis.patch.yml 标准 profile bundle）
• 仓库：https://github.com/Max-Samson/dsh-usage-chart
• 形态：标准 dsh web profile 插件（host 半区 = Node 路由，client 半区 = conversation.composer.dock + conversation.chat.assistant-actions 槽位）

2. 功能简介及与 DeepSeek 的关系

在 DSH Web 输入框下方实时显示 token 用量、成本估算、模型、余额与细上下文压力条；点击展开零依赖 SVG 可视化面板。核心能力（v0.2 + v0.3）：

• 每轮成本解释力：host 从会话日志（adapter 上报的完整事件流）折叠每轮用量，逐轮给出 总耗时 / TTFT / 输出吞吐 / 模型归因 / 结束原因 / 成本分拆（输入·缓存命中·输出 × 单价）；
• 三视角柱状图：总量（token）/ 构成（100%）/ 成本（各桶 × 单价堆叠）+ 柱顶耗时叠加点线 + 成本异常标记（相对近 N 轮突增，归因 chip：输出增长 / 上下文膨胀 / 缓存命中下降）+ 柱底缓存命中迷你刻度 + 解释卡 Tooltip（成本 / 模型 / 耗时 / TTFT / TPS / 结束原因）；
• 价格治理：成本按「用户覆盖 pricing.json > 内置官方刊例价 > 回退估算」解析，面板标注来源与核验日期；未定价模型显式标记，不静默按 0 计；
• 多币种成本显示（v0.3）：USD / CNY 切换（config.currency + config.cnyPerUsd，默认 6.76），选择在浏览器记住；价格说明跟随显示币种并标注所用汇率；
• 实时汇率刷新（v0.3）：一键经宿主 /dsh-usage-chart/rate 代理拉取最新 USD→CNY 汇率并立即重估；多源回退（配置源 → 内置 FX 源），上次成功汇率持久化，离线刷新保持上次汇率；
• 每轮成本徽章：助手消息尾部可关闭的「本轮 ≈ $0.00xx」；
• 中英双语：跟随 DSH 应用内语言设置，运行时切换。

与 DeepSeek 的关系：token 与上下文数据来自官方 adapter 上报的会话投影（tokenUsage / contextPressure）与会话事件流（turn/* / request/context / assistant/*）；余额来自官方 GET /user/balance（经宿主侧代理，API Key 不暴露给浏览器）；成本为官方刊例价估算值，非官方账单。非官方项目，无 DeepSeek 背书。

3. 安装或使用方式

dsh plugin --profile web add dsh-usage-chart   # npm 安装并登记为 profile 插件层
dsh web --profile web                          # 启动（或重启）DSH Web

可选配置（cordis.patch.yml，v0.3）：

- insert:
    - id: dsh-usage-chart
      name: dsh-usage-chart
      config:
        currency: 'cny'        # 'usd' | 'cny'，成本显示币种（默认 usd）
        cnyPerUsd: 6.76        # cny 时使用的汇率（默认 6.76；可用界面刷新按钮实时更新）
        fxUrl: 'https://open.er-api.com/v6/latest/USD'   # 可选：自定义汇率源

GitHub（源码构建）与本地目录（开发自测）安装方式见 README。升级后必须重启 dsh web：宿主进程在启动时缓存插件代码（无热重载），新路由只在重启后生效。

4. 界面预览

截图仅使用虚构演示数据，不含真实会话内容 / Token / 成本 / 余额 / API Key。

5. 技术要点与路线图

• 零运行时依赖：图表为手写 SVG，无图表库；TypeScript 源码 + esbuild 双产物构建；
• 架构：docs/ARCHITECTURE.md（深模块：RoundFold / PricingSource 接缝 / RoundBars / Anomaly）；docs/ROADMAP.md 记录 v0.2 / v0.3 交付与后续方向（上下文诊断：contextBreakdown 组成视图 + compaction/summary 压缩时间线 + 上下文增长归因）、v0.4（跨会话概览）；
• 测试：npm run verify 28 项全绿（折叠 / 价格解析 / 异常判定 / 汇率与币种），scripts/verify-render.mjs 对运行中的 DSH Web 端到端验证。

6. 相关链接

• README（中/英）：https://github.com/Max-Samson/dsh-usage-chart
• 更新日志（中/英）：https://github.com/Max-Samson/dsh-usage-chart/blob/main/CHANGELOG_ZH.md
• 问题反馈：https://github.com/Max-Samson/dsh-usage-chart/issues