dsh-tide-gauge

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# 潮汐计 · TideGauge

DeepSeek Harness 的用量与账单浮层插件。它在 Web 界面右上角注入一枚**常显**波浪图标（主页与进入会话后均显示），点击后展开右侧浮层：进入会话后实时呈现 **本会话的模型用量、上下文占用、会话统计、各 provider 账户余额与费用估算**；主页上则显示账户余额与费用估算，本会话用量需进入会话后查看。

> 「TideGauge / 验潮仪」取自海洋学术语，用于持续记录水位随时间的变化。本插件以同样的思路，持续记录 token 用量与余额的“水位”。

## 目录

- [特性](#特性)
- [安装](#安装)
- [使用](#使用)
- [配置](#配置)
- [余额解析规则](#余额解析规则)
- [架构与数据流](#架构与数据流)
- [API 参考](#api-参考)
- [已知限制](#已知限制)
- [License](#license)

## 特性

| 模块 | 说明 |
| --- | --- |
| **模型用量** | 本会话的未缓存输入 / 输出 / 缓存读取 / 缓存写入 token 及合计 |
| **上下文占用** | 预计压力、窗口容量、占用率 |
| **会话统计** | 轮次 / 步数、模型耗时、首 token 延迟、解码 tokens |
| **账户余额** | 仅展示配置了余额端点的 provider；多个 provider 时以标签页切换 |
| **费用估算** | 按 `config.pricing` 价格表，将本会话 token 用量折算为费用 |
| **密钥安全** | 密钥仅在主机侧解析，余额请求由主机发出，浏览器只接收结果，密钥永不进入浏览器 |

## 安装（一条命令，无需构建授权）

本插件是纯 JS 的 `dsh.bundle` + `dsh.client` 双面包，**没有构建步骤**，因此从 npm、GitHub 或 tarball 安装都不需要构建授权（无需配置 pnpm 的 `allowBuilds`）。以下方式任选其一：

```sh
# ① npm（发布后可用，推荐）
dsh plugin --profile web add dsh-tide-gauge

# ② GitHub（拉取源码，无需构建授权）
dsh plugin --profile web add github:DzDenzel/dsh-tide-gauge

# ③ tarball（离线交付）
cd dsh-tide-gauge && pnpm pack   # 生成 dsh-tide-gauge-.tgz
dsh plugin --profile web add ./dsh-tide-gauge-.tgz
```

`dsh plugin --profile  ` 在 profile 目录内转发给 pnpm，并把声明了 `dsh.bundle` 的包自动追加到该 profile 的 `dsh.profile.bundles`。安装后**重启对应 profile**（重启 `dsh web` 进程），右上角出现波浪图标即表示加载成功（主页与进入会话后均显示）。本地开发时可直接 `dsh plugin --profile web add ./dsh-tide-gauge`。

## 使用

1. 点击右上角的波浪图标，展开右侧浮层；再次点击或按右上角「×」关闭。主页（未进入会话）时图标浮于右上角，进入会话后位于会话头「Session log」旁。
2. 「账户余额」区右上角的「刷新」按钮会立即重新拉取余额；各 provider 余额也会按 `refreshMs` 自动缓存刷新。
3. 当配置了多个 provider 时，「账户余额」区顶部会出现以配置名称命名的胶囊按钮，点击即可在 provider 间切换，查看对应 provider 的余额与刷新时间。

## 配置

编辑 profile 的用户层配置 `$DSH_HOME/profiles//cordis.patch.yml`，为 `tide-gauge` 行追加 `config`。内置的 DeepSeek 官方余额规则始终启用，无需配置。

### `providers` — 其它 provider 的余额接口

`providers` 是一个数组，每个元素描述一个额外 provider 的余额端点：

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `provider` | `string` | 是 | — | provider 唯一 id，同时作为缓存键与切换按钮标识 |
| `label` | `string` | 否 | `provider` | 面板按钮与余额项展示的友好名称 |
| `kind` | `string` | 否 | `openai-compatible` | 余额响应解析方式：`deepseek` 或 `openai-compatible` |
| `balanceUrl` | `string` | 是 | — | 余额查询端点 URL；未配置的 provider 不会出现在面板中 |
| `currency` | `string` | 否 | `""` | 默认币种符号，响应未返回 `currency` 时兜底 |
| `apiKeyEnv` | `string` | 否 | `DEEPSEEK_API_KEY` | 密钥来源：优先 `credentials.resolve`，其次 `process.env` |
| `refreshMs` | `number` | 否 | `300000` | 余额缓存刷新间隔（毫秒） |

### `pricing` — 按模型的价格表

`pricing` 是一个以 **模型 id 为键** 的对象，价格为 **每百万 token** 单价；仅列入此表的模型会参与费用估算。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `label` | `string` | 否 | 费用估算区展示的模型名称 |
| `provider` | `string` | 否 | 归属 provider（元数据，暂不参与过滤） |
| `currency` | `string` | 否 | 币种符号 |
| `inputPer1M` | `number` | 是 | 未缓存输入 token 每百万单价 |
| `outputPer1M` | `number` | 是 | 输出 token 每百万单价 |
| `cacheReadPer1M` | `number` | 否 | 缓存读取 token 每百万单价 |

### 完整示例

```yaml
- id: tide-gauge
  name: dsh-tide-gauge
  config:
    # ① 其它 provider 的余额接口
    providers:
      - provider: openrouter
        label: OpenRouter
        kind: openai-compatible
        balanceUrl: https://openrouter.ai/api/v1/credits
        currency: USD
        apiKeyEnv: OPENROUTER_API_KEY
        refreshMs: 600000

    # ② 按模型价格（每百万 token 单价）
    pricing:
      deepseek-v4-flash:
        label: DeepSeek-V4-Flash
        currency: CNY
        inputPer1M: 1.0
        outputPer1M: 2.0
        cacheReadPer1M: 0.1
      gpt-4o-mini:
        label: GPT-4o mini
        currency: USD
        inputPer1M: 0.15
        outputPer1M: 0.60
```

## 余额解析规则

主机侧以 `Authorization: Bearer ` 请求 `balanceUrl`，并按 `kind` 解析响应：

- **`deepseek`**：读取 `balance_infos[0]`，映射 `total_balance` / `granted_balance` / `topped_up_balance` 与 `currency`。
- **`openai-compatible`**：尽力从响应中读取 `totalBalance` → `total_balance` → `total` → `balance` → `credits`（按顺序取第一个命中），并读取 `currency`；响应缺省时回退到规则里的 `currency`。

未命中任何可识别字段时，该 provider 标记为 `error`，面板显示错误原因。

## 架构与数据流

本插件由主机侧与浏览器侧两半组成：

- **主机侧（`lib/index.js`）**：纯函数 Cordis 插件（零 import），注入 `webServer`。仅收录配置了余额端点的 provider，在主机上拉取并缓存余额，并通过 `/tide-gauge/state` 路由对外提供数据；密钥永不进入浏览器。
- **浏览器侧（`lib/client.js`）**：`window.__ModuleLoader__.load` 惰性 CJS 包，注入 `slots`，注册到 `conversation.session.header.utilities` 槽位（进入会话后会话头右上角）与 `shell.overlay` 槽位（主页常显入口），负责渲染图标与浮层，并通过 `fetch("/tide-gauge/state")` 拉取余额与计价数据。

```text
┌──────────────┐   GET /tide-gauge/state   ┌─────────────────┐
│   浏览器 UI    │ ────────────────────────▶ │  lib/index.js   │
│ (client.js)  │ ◀──────────────────────── │   (主机侧)       │
└──────────────┘   JSON（余额 + 计价）        └───────┬─────────┘
                                                     │ Bearer
                                                     ▼
                                            ┌─────────────────┐
                                            │  各 provider API │
                                            └─────────────────┘
```

## API 参考

### `GET /tide-gauge/state`

返回各 provider 的余额与计价表（`/tide-gauge/balance` 为等价别名）。响应为 `application/json`，`Cache-Control: no-cache`：

```json
{
  "providers": [
    {
      "provider": "deepseek-official",
      "label": "DeepSeek 官方",
      "balance": {
        "status": "ok",
        "currency": "CNY",
        "totalBalance": "…",
        "grantedBalance": "…",
        "toppedUpBalance": "…",
        "refreshedAt": 1710000000000,
        "nextRefreshAt": 1710000300000,
        "error": ""
      }
    }
  ],
  "pricing": { "deepseek-v4-flash": { "inputPer1M": 1.0 } },
  "refreshedAt": 1710000000000
}
```

其中 `balance.status` 取值：`ok`（成功）、`error`（请求或解析失败）、`unavailable`（未配置密钥或端点）。

## 已知限制

- **token 为近似值**：由提供方上报 + 启发式估算得到，CJK 文本会被低估；
- **路由仅绑定主机**：余额/计价路由绑定在 web server 上（默认 `127.0.0.1`，不对公网暴露）；无 API Key / 无端点的 provider 显示「未配置余额端点」；
- **协议耦合**：浏览器侧 `client.js` 为预构建的 `window.__ModuleLoader__.load` 格式，跟随 harness 客户端模块协议版本，升级 harness 时需同步校验；
- **价格不内置**：`pricing` 缺省为空，需自行填入价格后才会显示费用数字。

## License

[MIT](./LICENSE)