前言¶

DeepSeek Harness (DSH) 的核心设计理念是「一切皆插件」。在通过 Web GUI 进行本地开发或调试时，实时掌握 DeepSeek 账户余额、当前会话的 Token 消耗以及上下文占用情况，是控制成本和调试模型行为的基础。

dsh-session-balance 插件专门解决这一问题。它不改变会话状态，也不发起模型请求，而是在 DSH Web GUI 的会话标题栏右侧挂载一个余额徽标。点击展开后，可以查看账户余额明细、会话 Token 用量统计、上下文压力（Context Pressure）以及基于当前模型单价的费用估算。

核心功能¶

该插件通过宿主与浏览器的协作实现数据展示：

1. 账户余额：通过调用 DeepSeek GET /user/balance 接口，获取账户总额、充值余额、赠送余额及可用状态。
2. 会话用量：读取会话投影（Projection）中的 tokenUsage（细分为未缓存输入、缓存读取、缓存写入、输出）与 sessionStats（轮次、步骤、模型耗时）。
3. 上下文压力：读取 contextPressure 数据，显示已用 Token 与窗口限制的占比。
4. 费用估算：在浏览器本地，根据当前选中的模型单价（modelSelection 投影）将 Token 数量换算为 CNY（元）。
5. 安全设计：全程只读。API Key 仅在宿主进程内使用，不会写入前端响应；路由仅接受同源 GET/HEAD 请求，防止跨域调用。

安装与启用¶

插件由「宿主插件」和「浏览器插件」两部分组成，需要安装到当前使用的 web profile 中。

1. 添加插件包¶

将插件目录以软链方式加入 profile：

dsh plugin --profile web add link:/path/to/dsh-session-balance

注：link: 表示软链，修改代码后重启 dsh web 即可生效。若需固定副本，可使用 file:/path/to/dsh-session-balance。

2. 挂载插件行¶

编辑 profile 配置文件 ~/.dsh/profiles/web/cordis.patch.yml，添加插件行。该文件默认为空列表，直接追加即可：

- insert:
    - id: session-balance
      name: 'dsh-session-balance'

3. 重启服务¶

重启 DSH Web 服务以加载插件：

dsh web

刷新 Web GUI（通常是 http://127.0.0.1:3080）后，会话标题栏右侧应出现余额徽标。

配置参考¶

所有配置项均为可选，通过 config 字段覆盖默认值。

基础配置¶

显示开关¶

模型单价覆盖（Pricing）¶

插件内置了 DeepSeek 官方定价的默认值，但单价可能随时间调整，建议根据实际模型配置覆盖。

默认单价（元 / 1M tokens，空闲时段）：

配置示例：

config:
  rate: peak
  currency: CNY
  pricing:
    deepseek-v4-pro:
      cacheHitInput: 0.3
      cacheMissInput: 9
      cacheWriteInput: 9
      output: 27

注意：pricing 表中的数值按空闲时段基准填写，rate: peak 时程序会统一乘以 2。

工作原理¶

插件利用 DSH 的投影机制获取数据，不修改宿主状态。

1. 数据源：会话用量和上下文压力来自宿主已有的投影（如 dsh-token-meter 提供的 tokenUsage 和 contextPressure）。
2. 前端计算：费用估算完全在浏览器端完成，使用投影中的累计 Token 数和宿主下发的单价表。
3. 余额获取：前端通过路由 fetch /dsh-session-balance/api/overview 请求宿主，宿主读取凭据后调用 DeepSeek API。余额请求带有 TTL 缓存和并发合并机制，避免频繁请求打爆上游。
4. 安全路由：后端路由只接受同源的 GET/HEAD 请求，检查 Origin 与 Host 一致性，否则返回 403。

兼容性与要求¶

• DSH 版本：需 DSH 0.1.5-rc.1 及以上，且 Web composition 中已启用 dsh-token-meter、dsh-session-stats、dsh-api-session-controller。
• Node.js：宿主环境需 Node.js >=20。
• 浏览器：需支持 Intl.NumberFormat 和可选链操作符的现代浏览器。

排查¶

如果功能未正常显示，可参考以下现象与原因：

License¶

MIT