安装与配置


# dsh 配置示例
- id: cost-meter
  name: dsh-daily-cost-meter
  config:
    enabled: true
    persistence:
      enabled: true                 # 聚合数据落盘，重启恢复
      filePath: cost-meter-data.json  # 相对路径相对于 dsh 进程工作目录
    budget:
      dailyUsd: 5                   # 每日预算上限（USD），0 关闭
      weeklyUsd: 30                 # 近 7 天滚动预算上限（USD），0 关闭
      onExceed: warn                # 超限行为（当前仅 warn 生效，见"已知限制"）
    pricing:                        # 覆盖/追加定价，单位 USD/百万 tokens
      deepseek-chat:                # 与内置条目同名 → 覆盖内置价
        inputPerMillion: 0.27
        outputPerMillion: 1.10
        cachedPerMillion: 0.07      # 缓存读价；缺省按 input 价计
      "openrouter/llama-3":         # provider/model 精确键
        inputPerMillion: 0.10
        outputPerMillion: 0.10
      "gpt-*":                      # 通配前缀键（* 结尾）
        inputPerMillion: 2.50
        outputPerMillion: 10.00

定价查找顺序：精确 model 名 → provider/model → 通配前缀（最长前缀优先，先后匹配 model 与 provider/model）。cacheWritePerMillion（缓存写价）同样可配，缺省按 input 价计。

工具

cost_report：范围参数 scope（session 当前会话 / today / 7days / all，默认 today）。输出结构化 JSON（总花费、token 总量、按模型分解、未定价模型清单、预算状态），render 为可读文本表。
cost_budget：查看或设置预算。dailyUsd / weeklyUsd 设置上限（0 关闭，持久化保存，优先级高于插件配置）；reset=true 恢复插件配置；不传参查看当前预算与已花费。
cost_pricing：查看当前生效定价表及每条来源（内置默认 / 用户配置）；传 model（可选 provider）测试某模型的定价命中。

用量采集说明

接缝：订阅 session 事件 assistant/message（每条 loop 产生的 assistant 消息自带 message.source.{provider,model} 与 usage），而非包装 llm/stream waterfall——session 事件天然携带会话 id 与 provider/model，且是 harness 自己的记账记录，更稳定。
adapter 未上报 usage 的调用不会被统计（没有可计的数字）。
reasoningTokens 仅作信息展示，不在 output 之外重复计费：provider（含 DeepSeek）已把 reasoning 计入 completion/output tokens。
费用在出报告时按当前定价表计算，只持久化 token 数——所以事后修改定价会追溯生效。
未命中定价表的模型照常统计 token，花费记为"未定价"，在报告里单列；总花费仅为已定价模型的下界。

权限透明

本插件对宿主环境的影响面，逐条交代清楚：

读写位置：仅读写一个聚合数据 JSON 文件（persistence.filePath，默认 cost-meter-data.json，写盘为"临时文件 + 改名"原子替换）。持久化可用 persistence.enabled: false 整体关闭。
网络域名：无。本插件不发起任何网络请求。
凭证：不持有任何凭证。
确认点：无。预算超限只写日志与会话事件，不触发 ask（见"已知限制"）。
日志内容：数据文件只存数值与模型名（provider、model、token 计数、调用次数、预算上限），不存任何消息内容、提示词或工具参数。会话日志中仅追加 cost-meter/budget-exceeded 事件（花费数值与上限），同样不含内容。

已知限制

预算超限只能警告，不能拦截：用量接缝（session assistant/message）在调用完成后才可见，无法在调用前 veto。配置 onExceed: ask 会在启动时降级为 warn 并打印警告；警告写插件 logger 与会话事件 cost-meter/budget-exceeded（每个周期每天最多一次，重启后若仍超限会再次警告）。
周预算是"近 7 个本地日"滚动窗口（含今天），不是 ISO 自然周。
未定价模型不参与预算与花费合计（token 照算）。预算只能防住已定价模型的花费。
非 agent-loop 手工发起的 llm.stream 调用（不经过 session 日志）不在统计范围内。
内置价格快照可能过时（见顶部价格声明）。

手动验证

本仓库的 CI 只覆盖类型检查与纯函数单测。接入真实 dsh 后请手动验证：

在 dsh 配置中启用本插件，确认启动日志出现 cost-meter: loaded。
与模型完成几轮对话，然后让 agent 调用 cost_report（或直接说"查一下今天的花费"），确认按模型分解的 token 与花费输出，scope=all 与 scope=today 数字合理。
调用 cost_budget 设置一个很低的 dailyUsd（如 0.0001），再进行一轮对话，确认 logger 出现超限警告、会话日志追加 cost-meter/budget-exceeded 事件，cost_report 中预算状态显示"已超限"。
重启 dsh，再次 cost_report scope=all，确认数据从 cost-meter-data.json 恢复；删除该文件后重启，确认从空数据重新开始。
调用 cost_pricing，确认内置条目标注"内置默认"、pricing 配置条目标注"用户配置"。

许可

MIT

安装

说明文档

安装与配置

工具

用量采集说明

权限透明

已知限制

手动验证

许可