前言¶

在 DeepSeek Harness（DSH）里写智能体、跑长会话时，官方用量胶囊通常只反映当前会话的 token 与成本。想回答「这周一共烧了多少」「缓存到底省了多少钱」「成本主要落在哪个工具上」，往往要翻日志或自己写脚本聚合。

下面介绍社区插件 dsh-usage-orb（维护者 zhifeiNi，MIT）。它在界面右下角提供常驻圆环，并附带可拖动的跨会话用量面板；数据只从本地会话日志读取，不联网、无遥测。分类为客户端插件，当前 GitHub 星标为 1。

这是什么¶

DSH 用量光球：右下角圆形进度环 + 可拖动的用量面板。宿主侧扫描 ~/.dsh/storages/ 下的 *.jsonl，按 DSH 四类 token 口径做跨会话聚合；客户端侧在 Web 界面挂载按钮与自建面板（零依赖、零构建，仅用 Node 内置模块与宿主提供的 react）。

与原生胶囊的差异可以概括为：原生侧重当前会话；本插件补跨会话视图、缓存经济性、按模型/工具归因，以及余额与布局偏好等本地能力（余额依赖 DSH 账户服务，不可用时降级为仅用量）。

核心功能¶

以下能力均来自仓库 README 与 package.json 说明，按使用路径归纳。

界面与交互¶

• 常驻圆环：右下角环状指示；悬停可看余额百分比；状态有呼吸/扫圈提示。
• 用量按钮与面板：对话区顶部工具栏右侧出现「用量」按钮（README 中「预期现象」一节）；点击后打开固定定位面板（不占用官方 dock 分栏）。
• 可拖动按钮：位置按比例记忆，双击复位。
• 磁贴 DIY：类似 iOS 控制中心——拖卡片重排、拖右下角把手改宽高、⊙ 隐藏；支持简洁 / 详细两档文案密度与 15 项玩法开关。
• 按钮面孔：默认项目图标；可选 bloub 机器人（眼睛追光标等，默认关闭，许可见仓库 THIRD-PARTY-NOTICES.md）。

统计与成本¶

• 跨会话用量：token 四分类（未缓存输入、缓存读取、缓存写入、输出）、会话/请求/轮次、按模型拆分、缓存命中率。
• 成本与省钱：按模型估算人民币成本、缓存省下金额、峰谷占比与「把高峰挪到空闲」模拟。
• 工具烧钱榜：成本归因到具体工具/命令，含失败率。
• 等级条：累计 token 分 Lv.1–6，附连续使用天数与今日强度。
• 点按热力图：当天明细（token / 成本 / 请求 / 模型占比）。
• 分享卡片：导出仅含聚合数字的 PNG。

余额与数据口径¶

• 余额追踪：水位曲线、掉血与充值提示；余额血条以历史最高水位为满格，见底会呼吸告警（需 DSH 账户服务）。
• 缓存命中率（与官方一致）：

缓存命中率 = 缓存读取 / (未缓存输入 + 缓存读取)

四类字段名：uncachedInputTokens、cacheReadTokens、cacheWriteTokens、outputTokens。插件声明不把不同来源的口径混加。

隐私与本地文件¶

• 只读本地会话日志与 ~/.dsh/usage-panel/ 下的缓存（布局、余额水位、报错等）。
• 不存储账户凭据；余额经 DSH 的 deepseekAccount 服务读取。重置可删除 ~/.dsh/usage-panel/。

安装与启用¶

安装方式取决于 profile 由谁管理。桌面端 profile 由 Electron 应用独占，不能用 CLI 改 desktop profile（会报 profile "desktop" is managed exclusively by the Electron application）。

桌面端（DeepSeek Harness 应用）¶

1. 打开左侧栏 插件 页面。
2. 在「从 GitHub / 本地路径安装」中填入：

https://github.com/zhifeiNi/dsh-usage-orb

3. 安装后重启应用；右下角出现圆形进度环即表示加载成功。同一页面可开关或卸载。

CLI 或 Web 端（profile 由 CLI 管理）¶

将 --profile 换成你实际使用、且由 CLI 管理的 profile 名：

dsh plugin --profile web add github:zhifeiNi/dsh-usage-orb
dsh plugin --profile web remove dsh-usage-orb

卸载示例：

dsh plugin --profile web remove dsh-usage-orb

环境与兼容性¶

• package.json 要求 Node >=22.19。
• peerDependencies 包括 @deepseek-ai/cordis、@deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-slots 及 react / react-dom；具体版本范围以仓库内 package.json 为准。
• 当前插件版本：0.2.2。

典型用法与预期现象¶

启动 DSH 并启用插件后，可按 README 自检：

1. 宿主日志应出现类似两行（数字因本机而异）：

[dsh-usage-orb] host 侧已加载
[dsh-usage-orb] 自检：扫描 12 个会话文件，采用 9 个，跳过 3 个；合计 857218617 tokens，缓存命中率 99.63%，模型 1 个，有日期的 2 天

有 host 日志表示会话文件扫描与聚合正常。

2. 工具栏右侧出现 「用量」 按钮；点击后面板应显示链路已打通及插件 id、React 版本、加载时间等信息。

3. 日常使用：悬停右下角圆环看余额比例；打开面板查看跨会话 token、缓存命中率、成本与工具榜；按需拖动弹窗、调整磁贴布局；需要对外展示时用分享卡片导出 PNG。

README 注明：网页搜索触发的 LLM 调用不计入统计，面板会提示「未计入」。

适用场景与注意¶

适合谁：长期在 DSH 桌面端或 Web/CLI profile 上跑多会话、关心 token 结构（尤其缓存命中率对成本的影响）、需要工具级成本归因或本地余额曲线的开发者。

安装前请知悉：

• 本插件以当前 DSH 进程权限运行，会读取本地会话日志；安装前应自行查看 GitHub 源码 与 MIT 许可证。
• 非官方插件，与 DeepSeek、幻方无隶属关系；统计仅供观察，不作为账单依据。DSH 升级后内部事件流或 *.jsonl 布局变化可能导致统计失效，需随上游修复。
• README 已知风险：通过 patch 绝对路径插入时，dsh.client 是否被 ctx.clientModules 扫描到尚未完全验证；工具栏 slot 名借鉴第三方 dsh-ui-workbench，若你使用的 DSH 版本 slot 不同，按钮可能不出现，需按官方 ui-sidebar-right 文档改用 ctx.sidebarRightTabs.register()。
• 社区目录 SkillHub 插件页 为独立生态站点，不是 DeepSeek 官方应用商店。

排错简表（摘自 README）：

结尾¶

dsh-usage-orb 把 DSH 本地会话日志聚合成可操作的跨会话视图：右下角光球 + 可定制面板，覆盖 token 四分类、缓存经济性、成本、余额与工具归因，且默认只读本地、不上传数据。若你正被「只能看当前会话账」限制，可按上文路径在应用内或 CLI 安装试用。

• 社区目录：https://www.skillhub.cn/plugins/zhifeiNi/dsh-usage-orb
• 源码与完整说明：https://github.com/zhifeiNi/dsh-usage-orb