前言¶
在 DeepSeek Harness（DSH）里跑长对话或 Agent 任务时，token 用量会不断累积，账户余额也会随调用扣减。若只能去控制台或单独查 API，Composer 里缺少即时反馈，很难判断「这一轮对话已经花了多少」以及「余额是否接近告警线」。社区插件 dsh-composer-balance（维护者 weiw0923，分类：客户端）在 Composer 停靠栏增加一行极简 chip：一行显示余额占比与当前会话估算花费，视觉与宿主自带的 context 计量条对齐；点击可展开小卡片查看明细、刷新与本地设置。下文介绍其能力、安装方式与配置要点。
这是什么¶
dsh-composer-balance 是面向 DeepSeek Harness Web 客户端的独立实现（MIT，npm 包名 dsh-composer-balance，当前资料中版本 0.2.1）。它占用宿主公开的 conversation.composer.dock 插槽，在 Composer 底部渲染一枚 balance chip，例如：
◔ 42% ¥ 14.55 │ 0.003
左侧为余额相关指示（含阈值着色），中间为账户余额，竖线后为当前会话花费估算。插件不与其他 balance 类 chip 叠用为佳——README 说明若已安装同类插件，应禁用其中一个，否则各 entry 会各自渲染一枚 chip。
核心功能¶
账户余额¶
余额通过宿主侧读取 DeepSeek 的 /user/balance（配置中的 baseUrl 后追加该路径），在 refreshIntervalMs 内缓存；浏览器端不持有 API Key。只读路由与 Web 应用其余部分处于同一安全边界内。
当前会话花费¶
插件注册会话投影 composerBalanceCost：对每个 provider usage 样本按该轮时间戳生效的资费计价（工作日 09–12、14–18 CST 高峰双倍），再汇总为会话总额。跨高峰与平峰的会话会分段计价，而不是按 chip 渲染时刻的单一费率估算。README 称对真实会话的离线回放与账户日账单可对齐到百分之几以内。
卡片内还会区分两种来源（示例文案）：
余额变动 ¥2.83 · 按轮计价 ¥6.49
输入 106.3M · 输出 344.7K · 命中 99.8% · 按轮计价
- 按轮计价：主显示数字，按各轮 token 与峰谷规则汇总，接近 provider 对该会话 token 的计费逻辑。
- 余额变动：自 chip 开始监视以来账户余额的累计下降，反映「账户实际少了多少」，但同一 Key 上的其他活动也会计入。
展示值不会回退：取两者与本会话已显示最高值的最大值。
交互与外观¶
点击 chip 打开约 264px 宽卡片（与宿主 context card 同尺寸），展示余额、充值/赠送拆分、当前会话、输入/输出/缓存命中、最后更新时间，以及刷新与设置入口。样式使用宿主 CSS 变量（如 --dsw-specific-menu、--dsw-elevation-prominent、--dsw-radius-lg），12px/20px 间距节奏；Esc 或点击外部关闭。
告警阈值（warning / critical）仅改变 ¥ 图标颜色；自动刷新间隔保存在 localStorage。entry 的 order: 1，渲染在 Composer dock 末尾，通常排在宿主 token/context 计量条之后。
安装与启用¶
插件以 DSH Web profile 安装。资料中的官方命令如下（npm 发布后可用包名；本地开发可用目录路径）：
dsh plugin --profile web add dsh-composer-balance # once published
# or from a checkout / local directory:
dsh plugin --profile web add /path/to/dsh-composer-balance
安装后需重启 Harness（systemd 部署示例：sudo systemctl restart dsh-web），并刷新浏览器页面。
注意：插件在 DSH 进程权限下运行；安装前请自行审阅 GitHub 仓库 源码与 MIT 许可证。engines.dsh 要求 >=0.2.0-rc.1；peer 依赖含 @deepseek-ai/cordis 等，与当前宿主版本需匹配。
配置¶
在 profile 的 cordis.patch.yml 中覆盖插件 id: dsh-composer-balance 的 config：
- id: dsh-composer-balance
config:
apiKeyRef: DEEPSEEK_API_KEY # credential reference holding the key
baseUrl: https://api.deepseek.com # /user/balance is appended
refreshIntervalMs: 120000 # how long one reading stays fresh
warningThreshold: 10 # chip turns amber at or below this
dangerThreshold: 5 # chip turns red at or below this
defaultPrice: { cacheHit: 0.2, cacheMiss: 2, output: 8 } # ¥ / 1M tokens
modelPrices: # per-model overrides
deepseek-flash: { cacheHit: 0.02, cacheMiss: 1, output: 2 }
defaultPrice 与 modelPrices 自带占位数字，需按 provider 现行价目表替换，会话估算才有参考意义；token 统计仍会显示，缺价时金额区域会灰显。
适用场景与注意¶
适合长期在 DSH Web Composer 中开发、调试 Agent 或模型调用、并希望不离开对话界面即可监视余额与会话成本的开发者。DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录站点，与 DeepSeek / 幻方无官方从属关系。
若同时运行多个 balance chip，请只保留一个。资费配置未更新时，chip 上的会话金额仅为估算；余额以 /user/balance 为准。
结尾¶
dsh-composer-balance 用一行 chip 和一张卡片，把账户余额、峰谷-aware 的会话计价与宿主原生 UI 绑在一起，并支持本地阈值与刷新间隔。进一步了解可查看 目录页 与 GitHub：weiw0923/dsh-composer-balance。
