前言¶

在 DeepSeek Harness（DSH）里切换模型或 Provider 时，余额往往和当前选择脱节；会话里还有子智能体、fork 继承，手工对账很容易重复或漏算。社区插件 dsh-balance-usage-dock（维护者 YusenZhang0601）在 composer dock 增加一个单元格：展示当前 Provider 余额、本会话累计估算费用（含子会话），点击可打开面板查看多 Provider 配额、90 天用量热力图与按模型拆分。定价在运行时从 Provider 目录或公开价目页拉取，不内置价表，也不持久化凭据。

这是什么¶

dsh-balance-usage-dock 是零 npm 依赖的 DSH 插件（当前版本 0.2.0，MIT 许可证）。它只注册一条只读本地 HTTP 路由和一个 composer-dock 单元格，无悬浮窗、无侧栏、无捆绑素材。数据仅在本地处理：一条 loopback / 同源 GET 路由，无遥测、无浏览器存储、无凭据落盘。

与「自己记 token、查账单页」相比，它把余额展示绑定到 ctx.modelDirectories 所选的 Provider，会话费用整棵树累计，并在 UI 中标明定价来源与置信度（exact | family | community | override | none）。

核心功能¶

下面介绍 v0.2 文档中已列出的能力，均可在 GitHub README 核对。

Composer 坞区与模型跟随¶

• Model-following dock：余额目标随模型选择目录变化；切换 Provider/模型后余额立即更新，会话累计费用不因此清零。
• 点击坞区单元格打开 balance-usage-panel，可查看全部 Provider、配额、Provider 侧上报消费、90 天热力图及 byModel 拆分。

会话费用累计¶

• 覆盖当前会话及所有可达子智能体会话；fork 继承历史（seq < inheritedEventCount）跳过，避免对父会话重复计费。
• mixedProviders 标记跨 Provider 累计；pricingConfidence 反映所用定价源中最弱一档。
• CNY 与 USD 分币种并列展示，不同币种不做相加。

定价与峰谷¶

• 编译产物中不含价表；运行时按优先级从 Provider catalog、用户 catalog、DeepSeek 官方价目页或 models.dev 获取，界面标明来源与置信度。
• 官方 CNY 价按 IANA peakTimeZone（默认 Asia/Shanghai）应用峰谷；可配置 peakWindows、peakWeekdays、holidays。

Provider 与统计¶

• 支持 16 种 provider kind（含 DeepSeek API/桌面账号、Moonshot、OpenRouter、xAI、Vercel AI Gateway、Z.ai、MiniMax、Kimi Coding、OpenCode、OpenAI/Anthropic admin spend、GitHub Copilot、OpenAI Codex OAuth、Volcengine Ark 等），详见仓库 docs/providers.md。
• 90 天热力图：按 statsTimeZone 分桶，会话扫描有上限（默认 statsSessionLimit 200）。
• 传输层带 bounded retry、peerTimeoutMs / requestTimeoutMs、retryable / stale / degraded 标志；refresh=1 可 bypass 缓存。
• 诊断：?kind=diagnostics 输出脱敏快照（无 token、无账号画像、无会话正文），便于提 Issue。

环境要求¶

• DSH 桌面端，且启用浏览器 webServer 服务（插件需注册路由）。
• 宿主机 Node.js ≥ 22（推荐 24）；插件无 npm 依赖、无构建步骤，浏览器侧为单文件 client.js 模块加载 bundle。

安装与启用¶

请通过 Harness 安装，不要手改 profile 的 package.json 或 cordis.patch.yml。

从 GitHub 安装（推荐）¶

在 DSH 会话中可让智能体执行：

Install the DSH plugin github:YusenZhang0601/dsh-balance-usage-dock with plugin_manager (install_bundle), enable it if it is disabled, then verify it loaded.

若使用 dsh web profile，CLI 等价命令为：

dsh plugin --profile web add github:YusenZhang0601/dsh-balance-usage-dock

安装后验证¶

plugin_manager 会提示是否需要重启。随后：

1. 用 cordis_inspect_query（Client → Slots）确认存在 conversation.composer.dock 的 balance-usage 单元格，以及 shell.overlay 的 balance-usage-panel。
2. 刷新浏览器；若返回 restart-required，需完全退出桌面客户端（含托盘）再打开。

npm 发布后可使用 dsh plugin --profile web add dsh-balance-usage-dock（以仓库 publish 工作流为准）。

本地开发目录安装时，在会话中指定插件绝对路径，同样走 plugin_manager 的 install_bundle 流程（README 原文说明，此处不展开 clone 步骤）。

典型配置¶

配置项均为可选，写在插件行的 config（通常在 cordis.patch.yml）。完整说明见 docs/configuration.md。

常用项示例：

README 中的 YAML 片段可用于峰谷、节假日与 relay 模型别名：

- insert:
    - id: balance-usage-dock
      name: dsh-balance-usage-dock
      config:
        peakTimeZone: Asia/Shanghai
        statsTimeZone: America/New_York
        holidays: ["2026-10-01", "2026-10-02"]
        priceOverrides:
          "my-relay/deepseek-v4.1-flash":
            currency: CNY
            cacheHit: { idle: 0.02, peak: 0.04 }
            cacheMiss: { idle: 1, peak: 2 }
            output: { idle: 4, peak: 8 }
        modelAliases:
          "my-relay/fast": "deepseek-flash"
        trustedHosts: ["127.0.0.1:55976"]

HTTP 契约摘要：唯一路由 GET /balance-usage-api?kind=<kind>，仅 GET，仅 loopback/同源；权威说明见 docs/contract-v2.md。

适用场景与注意¶

适合：长期在 DSH 里多 Provider、多模型切换，需要在坞区一眼看到「当前 Provider 余额 + 本会话估算费用」，并偶尔打开面板看 90 天用量与按模型拆分的开发者。

注意：

• 插件以当前 DSH 进程权限运行，会向配置的 Provider 端点发起只读类请求（余额/用量/定价 catalog）；安装前请阅读源码与 MIT 许可证，确认 providers、apiKeyEnv 等配置符合你的安全策略。
• 社区价目（如 models.dev）可能滞后，界面会标注置信度；敏感 relay 可优先用 priceOverrides 或 extraPriceCatalogs。
• 社区目录 SkillHub 插件页 与 GitHub 仓库相互索引，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文事实以仓库 README 与文档为准。

结尾¶

经过上面的步骤，你可以在 composer dock 获得跟随当前模型的余额展示，以及含子会话的累计费用与 90 天热力图，且不在插件内保存 API Key。进一步细节与 Provider 列表请查阅：

• 目录页：https://www.skillhub.cn/plugins/YusenZhang0601/dsh-balance-usage-dock
• 源码与文档：https://github.com/YusenZhang0601/dsh-balance-usage-dock