# External usage snapshots / 外部用量快照

## English

Another local process can write `$DSH_HOME/storages/cost-meter/external_usage.json` to add usage from the **same account** that bypasses DSH. The plugin reads the file on each state refresh. It never calls Hindsight or any other external service. Settings → Cost shows DSH and external usage separately, plus combined today/month/all-time totals. Expand a source to see its token buckets, calls, costs and up to 90 recent daily rows. DSH session totals and official balance reconciliation remain DSH-only.

Write the entire snapshot to a temporary file in the same directory, then atomically rename it to `external_usage.json`. Replace the file on every refresh; **do not append deltas**. The same snapshot can be read repeatedly without double-counting. Use ISO 8601 timestamps with `Z` or an explicit offset. `source` is a stable name (1–64 characters), not a model name. Up to eight sources are accepted. The file is capped at 512 KiB; each source can supply up to 3,660 daily summaries, or the whole file can supply up to 5,000 individual records. Snapshots older than 24 hours are marked stale; those older than 30 days, malformed, oversized, or unreadable are ignored. The producer should refresh regularly and keep historical days in each replacement snapshot. All-time totals cover only the days supplied by the producer.

**Daily summary mode**: `input` means uncached input, `cached` means cache-read input, and `cacheWrite` is a separate optional bucket. All buckets are mutually exclusive. `costUsd` is the exact USD cost calculated by the producer; it is required because daily totals cannot reconstruct peak/off-peak or long-context prices for individual calls. `calls` is the number of calls. Optional `reasoning` is reported separately. Amounts are converted to the selected display currency by the plugin.

```json
{
  "fetchedAt": "2026-09-26T09:00:00Z",
  "sources": [
    {
      "source": "Hindsight",
      "days": {
        "2026-09-25": {
          "input": 4888706,
          "output": 592536,
          "cached": 1082880,
          "calls": 363,
          "costUsd": 1.2345
        }
      }
    }
  ]
}
```

**Call record mode**: send one record per completed call with a stable unique `id` within that source. The plugin calculates USD cost using its configured provider/model prices and each call's timestamp, including the configured DeepSeek peak/off-peak rules. Current price settings are reapplied when the snapshot is read, so use daily `costUsd` summaries if historical costs must remain fixed. An unpriced provider/model invalidates the snapshot instead of silently recording zero cost. `input`, `output`, `cached`, optional `cacheWrite` and `reasoning` have the same meanings as in summary mode. Each record represents one call.

```json
{
  "fetchedAt": "2026-09-26T09:00:00Z",
  "source": "Hindsight",
  "records": [
    {
      "id": "request-abc123",
      "at": "2026-09-25T08:40:00Z",
      "provider": "deepseek",
      "model": "deepseek-chat",
      "input": 1200,
      "output": 250,
      "cached": 100
    }
  ]
}
```

A snapshot can contain a single top-level source as above, or a `sources` array. Each source uses either `days` or `records`, never both. Do not include calls already reported to DSH; source separation prevents same-name model collisions but cannot detect duplicate calls across systems. The file must contain no API keys or other credentials. The budget widget continues to use DSH's own ledger; combined totals appear in the external usage section.

## 中文

其他本地进程可将同一账户、但绕过 DSH 的用量写入 `$DSH_HOME/storages/cost-meter/external_usage.json`。插件每次刷新状态时读取，不直接请求 Hindsight 等服务。设置 → 费用按来源显示外部用量、DSH 与外部合计，以及近 90 天的逐日数据；DSH 会话金额和官方余额对账仍只使用 DSH 账本。

采集器先在同目录写完整临时文件，再原子重命名为 `external_usage.json`。每次刷新替换整份快照，**不要追加增量**；重复读取不会重复计费。时间使用带 `Z` 或时区偏移的 ISO 8601。`source` 是稳定的来源名称，不是模型名。最多 8 个来源；文件上限 512 KiB；每来源最多 3660 条日汇总，或整份快照最多 5000 条调用记录。超过 24 小时未更新会标为过期；超过 30 天、损坏、过大或不可读的快照会被忽略。刷新时应保留所需的历史日期；累计费用只覆盖采集器提供的日期。

上方第一例为**每日汇总**：`input` 是非缓存输入，`cached` 是缓存读取，可选 `cacheWrite` 是独立缓存写入；各桶互不重叠。`costUsd` 是采集器计算的准确美元费用，必须提供，因为日合计不能还原每次调用的峰谷或长上下文价格。`calls` 是调用次数，`reasoning` 可单独提供。插件按当前显示汇率展示费用。

第二例为**逐次记录**：每次完成的调用提供来源内唯一且稳定的 `id`。插件按 `at`、provider/model 及现有价表计算美元费用，包括 DeepSeek 峰谷规则。快照每次读取会应用当前价格设置；若历史费用必须固定，请使用含 `costUsd` 的日汇总。未知价格的模型会使整份快照失效，避免误记零费用。每个来源只能在 `days` 和 `records` 中选一种。不要包含已由 DSH 记录的调用；来源分栏能区分同名模型，但无法自动识别跨系统重复调用。文件中不要存放密钥。预算图框仍按 DSH 账本计算；合计显示在外部用量区。