dsh-cost-tracker

Readme

# dsh-cost-tracker · 花费统计插件

[![npm version](https://img.shields.io/npm/v/dsh-cost-tracker.svg)](https://www.npmjs.com/package/dsh-cost-tracker)
[![npm downloads](https://img.shields.io/npm/dm/dsh-cost-tracker.svg)](https://www.npmjs.com/package/dsh-cost-tracker)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-lyfZhixing%2Fdsh--cost--tracker-181717?logo=github)](https://github.com/lyfZhixing/dsh-cost-tracker)

**中文** | [English](README.en.md)

为 DeepSeek Harness Web（`dsh --profile web`）记录**每日 LLM 调用花费**，支持按会话 / 模型 / 天多维度查看。

> Daily LLM cost tracking for DeepSeek Harness Web: records token usage per call and shows per-session / per-model / per-day costs in a built-in dashboard.

![入口示例](docs/screenshot-entry.png)

## 功能

- 自动记录每次模型调用的用量：输入（未命中）、缓存命中、输出、其中推理 tokens
- 按定价表估算花费（¥ / 100 万 tokens），支持**高峰时段倍率**（默认北京时间 9-12、14-18，2x）；周末全天按谷价计算（不应用高峰倍率）
- 入口：
  - 侧边栏底部「¥ 花费统计」按钮（打开面板）
  - 会话标题栏右侧「¥ 花费」（显示该会话金额）
  - 输入框下方本会话花费读数
- 面板：总览（今日 / 近 7 天 / 累计）、按模型、按会话、最近调用、价格设置
- 价格可随时在面板「价格设置」页修改，保存后历史记录按新价格重算
- **零 token 消耗**：只读取 API 响应里已有的 usage 数据做本地算术，从不调用模型

## 安装

### 方式一：npm（推荐）

```bash
dsh plugin --profile web add dsh-cost-tracker
```

然后**重启 dsh web**，刷新页面即可在侧边栏底部看到「¥ 花费统计」。

> 国内镜像（npmmirror）同步新包有延迟（几分钟到几小时），若安装报 404，可临时指定官方源：
> `dsh plugin --profile web add dsh-cost-tracker --registry=https://registry.npmjs.org/`

### 方式二：从 GitHub 直接安装

```bash
dsh plugin --profile web add github:lyfZhixing/dsh-cost-tracker
```

（包无构建步骤，git 安装无需额外配置）

### 方式三：本地目录（开发 / 内部分享）

```bash
dsh plugin --profile web add /path/to/dsh-cost-tracker
```

### 卸载

```bash
dsh plugin --profile web remove dsh-cost-tracker
```

卸载只移除插件，本机数据文件 `~/.dsh/cost-tracker.json` 会保留。

## 使用

1. 打开任意会话，正常使用即可——每次模型回复都会自动记录
2. 点侧边栏底部「¥ 花费统计」打开面板：
   - **总览**：今日 / 近 7 天 / 累计花费，近 30 天日花费柱状图，Top 模型 / 会话
   - **按模型**：每个模型的调用次数、tokens、花费、占比
   - **按会话**：每个会话的花费与最后调用时间
   - **最近调用**：最近 200 条调用明细
   - **价格设置**：修改高峰时段、默认价格、按模型价格；可一键把「记录中出现但未定价的模型」加入定价
3. 面板关闭方式：右上角 ✕、点击面板外遮罩、按 `Esc`、再次点击侧边栏按钮

## 价格说明

![价格设置](docs/screenshot-pricing.png)

- 单价单位：**元 / 100 万 tokens**；`inputMiss` = 未命中缓存输入价，`inputHit` = 缓存命中输入价，`output` = 输出价
- 默认价格（`deepseek-v4-pro` / `deepseek-v4-flash`）为**估算值**，请务必在「价格设置」页按实际价格修改
- 高峰倍率对输入和输出同时生效；时区偏移默认 +8（北京时间）；周末全天按谷价计算（默认不应用高峰倍率）

## 数据与隐私

- 数据全部保存在本机：`~/.dsh/cost-tracker.json`（记录、会话标题、定价表）
- **不包含任何 API 密钥 / 凭据**：插件只读取模型响应自带的用量数据，不调用任何模型接口
- 无任何网络上报；页面每 4 秒通过本机 HTTP 接口（`/cost-tracker/data`）拉取统计
- 花费计算不消耗任何额外 token

## 常见问题（FAQ）

**Q: 安装后没有记录 / 显示 0？**
A: 插件只记录**安装之后**新产生的模型调用；历史调用无法回溯。确认「价格设置」页存在对应模型的定价（未定价的模型会提示，可用 fallback 兜底）。

**Q: 价格不准确怎么办？**
A: 默认价格为估算值，请在面板「价格设置」页按你的实际计费标准修改（单位：元 / 100 万 tokens）。

**Q: 卸载插件后数据会丢吗？**
A: 不会。数据文件 `~/.dsh/cost-tracker.json` 独立保存，重装插件后自动恢复。

**Q: 国内镜像安装报 404？**
A: npmmirror 对新包同步有延迟，临时用 `--registry=https://registry.npmjs.org/` 安装，或稍后再试。

## 开发

```
dsh-cost-tracker/
├── package.json        # dsh.bundle + dsh.client 声明
├── cordis.patch.yml    # 安装时的插件行插入层
└── lib/
    ├── index.js        # 宿主端：记录用量、持久化、HTTP 路由
    └── client.js       # 浏览器端：UI（原生 JS bundle，无构建步骤）
```

- `lib/client.js` 由服务器实时读取（`cache-control: no-cache`），**改完刷新页面即生效**
- `lib/index.js` 为宿主端代码，改动需**重启 dsh web**
- 无 TypeScript / 无打包 / 无外部运行时依赖；客户端必须用 `window.__ModuleLoader__.load({ id, factory })` 格式编写
- 源码仓库：[github.com/lyfZhixing/dsh-cost-tracker](https://github.com/lyfZhixing/dsh-cost-tracker)

## Changelog

- **v1.0.1** (2026-08-17)：新增英文 README（README.en.md）与界面截图；文档完善。
- **v1.0.0** (2026-08-17)：首个公开发布版本。自动记录每次模型调用用量并按定价表估算花费；面板支持总览 / 按模型 / 按会话 / 最近调用 / 价格设置；支持高峰时段倍率与自定义价格。

## License

MIT