dsh-api-usage-bar

Readme

# dsh-api-usage-bar

[![CI](https://github.com/hurry060215-tech/dsh-api-usage-bar/actions/workflows/ci.yml/badge.svg)](https://github.com/hurry060215-tech/dsh-api-usage-bar/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/hurry060215-tech/dsh-api-usage-bar)](https://github.com/hurry060215-tech/dsh-api-usage-bar/releases/latest)

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

适用于 DeepSeek Harness Web UI 的轻量 API token 用量条。它把完整会话的用量显示为三个分段：**缓存输入**、**未缓存输入**和**输出**，并在旁边给出紧凑数值。

![DSH API 用量条](docs/screenshot.png)

## 特点

- 直接读取 DSH 已有的 `tokenUsage` 会话投影，不请求 DeepSeek API。
- 不读取 API Key，不查询账号余额，不修改会话日志。
- 绿色表示缓存读取，黄色表示未缓存输入，蓝色表示输出。
- 鼠标悬停或辅助技术可以读取三个分段的精确 token 数量。
- 桌面端和窄屏均可用；窄屏隐藏文字标签但保留颜色与数值。
- 纯 UI 插件：不新增模型工具、system prompt 或 token 开销。

## 要求

- DeepSeek Harness `>=0.1.0-rc.6 <0.2.0`
- Web profile
- Node.js `^22.19.0` 或 `>=24`
- pnpm 10（`dsh plugin` 内部会调用它）

## 安装

在 PowerShell 中执行：

```powershell
npm install --global pnpm@10
pnpm --version
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add https://github.com/hurry060215-tech/dsh-api-usage-bar/releases/download/v0.1.1/dsh-api-usage-bar-0.1.1.tgz
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web
```

打开 <http://127.0.0.1:3080>。完成一次模型请求后，用量条会自动出现在输入框下方。安装包包含预构建的 `lib/`，用户不需要克隆仓库或运行构建。

插件尚未发布到 npm；不要使用 `add dsh-api-usage-bar`。上面的命令直接安装 GitHub Release 中的预构建包。

### 3080 端口已被占用

如果 3080 上已经运行着 DSH，先在原来的终端按 `Ctrl+C` 停止它，再执行上面的 `web` 命令，使新插件在重启后加载。如果 3080 被其他程序占用，可以改用：

```powershell
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web --port 3091
```

然后打开 <http://127.0.0.1:3091>。检查端口占用程序：

```powershell
Get-NetTCPConnection -LocalPort 3080 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess
```

卸载：

```powershell
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web remove dsh-api-usage-bar
```

## 统计口径

| 分段 | DSH token 投影字段 |
| --- | --- |
| 缓存输入 | `cacheReadTokens` |
| 未缓存输入 | `uncachedInputTokens + cacheWriteTokens` |
| 输出 | `outputTokens` |

三个分段按 token 总数归一化，所以条形图表达的是**用量构成**，不是账号额度或余额进度。DeepSeek 的请求 usage 会报告提示词缓存命中与未命中 token；余额接口没有提供总额度分母，因此本插件不会虚构“已用百分比”。

## 开发

```sh
pnpm install
pnpm run check       # typecheck + tests + build
pnpm pack            # 生成可离线安装的 tarball
```

源码结构：

- `src/index.ts`：Host 端空插件，用于客户端模块发现。
- `src/client/index.ts`：locale、样式和 composer dock 注册。
- `src/client/ApiUsageBar.tsx`：用量条与紧凑图例。
- `src/client/usage.ts`：token 分桶与格式化纯函数。
- `cordis.patch.yml`：由 `dsh.bundle` 自动激活的 profile 配置层。

## 隐私与模型体验

插件只读取浏览器已收到的累计 token 投影。它不发起网络请求，不持有凭据，不写会话事件，也不会改变发送给模型的任何内容。

## License

[MIT](LICENSE)