dsh-cost-pill：官方统计行内的费用与余额胶囊

前言¶

DeepSeek Harness（DSH）的 Web 客户端提供了一套官方统计行。这个插件将“会话 API 费用”与“账户余额”合并为胶囊，置于官方统计行中。点击胶囊可展开详情面板，查看分时段金额、账户余额、分模型明细及价目来源。

核心功能¶

视觉零发明：胶囊与面板的每个数值、样式（颜色 token、字号、间距、圆角、hover 态）均逐条抄自官方源码。
纯插槽放置：插件使用 conversation.composer.dock 列表插槽，利用 order 排序钉在行最右，不依赖 DOM 搬运。
走官方投影缝：宿主侧在 ctx.sessionProjections 注册 costPill 单元，浏览器侧通过 useProjection('costPill') 读取。
价目在线刷新且有闸门：启动时后台从官方定价页刷新价目，具备 TTL 缓存、多重校验与离线降级能力。
子代理费用计入：按会话头部的 parentSession / origin 收集整棵子代理树，与本体一起计价。
模型可见面为零：不注入任何提示词或模型调用。

安装与启用¶

1、安装插件：

dsh plugin --profile web add dsh-cost-pill

2、重启 dsh web 并在浏览器硬刷新（Ctrl+Shift+R）。
3、打开任意会话，官方统计行里会出现一枚胶囊（例如：费用 ¥2.033 · 余额 ¥105.82 · 命中 99.5%）。会话没有计费样本时不显示。
4、卸载命令：

dsh plugin --profile web remove dsh-cost-pill

配置¶

插件支持在 profile 的 cordis.patch.yml 里进行配置。

1. 覆盖价目表¶

使用 pricing 段覆盖价格表，优先级高于内置价目：

- id: cost-pill
  config:
    pricing:
      deepseek-flash:                      # 键 = 模型 id
        offpeak: { input: 1, cacheRead: 0.02, cacheWrite: 1, output: 4 }
        peak: { input: 2, cacheRead: 0.04, cacheWrite: 2, output: 8 }
      acme/mystery-1:                      # 也可写完整 provider/model
        input: 3
        output: 6

选价顺序：完整 provider/model 精确匹配 → 模型 id 精确匹配 → 最长前缀匹配。

2. 启用余额显示¶

使用 balance 段启用余额查询：

- id: cost-pill
  config:
    balance:
      enabled: true          # false 则完全不注册余额路由
      lowThreshold: 10       # 低于该值标红
      cacheMs: 120000        # 宿主侧 TTL 缓存
      timeoutMs: 15000       # 上游超时

3. 在线价目刷新¶

使用 pricingRefresh 段控制在线刷新行为：

- id: cost-pill
  config:
    pricingRefresh:
      enabled: true          # false = 只用内置价目，完全不联网
      ttlMs: 86400000        # 缓存存活时间（默认 24 小时）
      timeoutMs: 15000       # 单次抓取超时
      url: 'https://api-docs.deepseek.com/zh-cn/quick_start/pricing/'
      cachePath: ''          # 默认 $DSH_HOME/storages/dsh-cost-pill-pricing.json

计费与数据¶

数据来源：只认 provider 在 assistant/message 事件里上报的 usage。
子代理归集：宿主侧按会话头部的 parentSession / origin: 'subagent' 收集派生树，用同一套折叠逻辑逐会话计价后合并。
余额数据通路：宿主注册一条 loopback-only 的精确路由 /api/cost-pill/balance，使用提供商的账户接口取数。浏览器只拿到余额数字，API Key 始终留在宿主进程。

注意事项与限制¶

不做跨调价的历史分段：所有历史样本都按当前价目表重算。
在线刷新的滞后性：投影注册表只在事件提交时重算，刷新在下一个计费样本体现。
金额是估算值：不等于账单，中转渠道、合同折扣等无法从会话 token 推算。
子代理发现机制：依赖 $DSH_HOME/sessions 目录下的日志与 parentSession 头部字段。
面板锚定方式：使用 position: absolute 相对 pill，不做官方 fixed + 视口边缘重排。
图标绘制：图标是自绘内联 SVG，为了安全合入官方那一行。
客户端限制：只在 Web 面渲染，TUI/其他客户端没有该插槽。