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/其他客戶端沒有該插槽。