@zhubaodian/dsh-token-panel

Readme

# dsh-token-panel

DSH Web GUI 右侧 Token 面板（双面插件，host + client）。

**自 v0.2 起内置 Token Harbor 额度查询引擎**，额度数据在 DSH 宿主进程内直接查询，
不再需要额外启动 `127.0.0.1:4173` 的独立 Token Harbor 服务。

- **上栏 · 额度剩余**（`GET /token-panel/quota`）：内置引擎直查，只展示查询成功的 provider：
  - Kimi Coding（`api.kimi.com/coding/v1/usages`，支持多账号）
  - DeepSeek 官方余额
  - Codex Plus（读取 macOS Keychain `Codex Auth` 或 `~/.codex/auth.json` 的 ChatGPT OAuth 登录态）
- **下栏 · Token 已使用**（`GET /token-panel/usage?range=today|7d|30d|all`）：合并多路数据，按模型分类、按时间截取、无价格：
  - cc-switch `~/.cc-switch/cc-switch.db` 中 `data_source='proxy'` 的真实代理流量；
  - Codex / Kimi Code / Pi 本地日志增量同步（`lib/usage_tool.py`，参考 cc-switch 的 `codex_session` 构建法）；
  - Hermes Agent `~/.hermes/state.db` 的 `session_model_usage` 累计行差分同步（只读打开，WAL 下与运行中的 hermes 共存）；
  - DSH 自身用量实时记录（`llm/stream` 模型归属 + `session/event` 落盘）。

## 安装

```bash
dsh plugin --profile web add github:zhubaodian/dsh-token-panel
```

前置条件：本机有 `python3`（用量同步助手）、`sqlite3`（读取 cc-switch 库）和 `zstd`
（解压 DSH 历史会话回填；macOS 需 `brew install zstd`，Linux 一般自带或用包管理器安装）。
运行环境需 Node.js ≥ 18（用到全局 `fetch` / `structuredClone`）。

安装后重启 DSH。面板注册在 `shell.overlay`，可收起为右侧边缘小标签。

## 配置（额度查询）

配置文件在 **`~/.dsh/token-panel/config.json`**（用户数据目录，插件重装/升级不会丢失），
首次启动自动播种默认配置。字段模板见 [`data/config.example.json`](data/config.example.json)。

- 填入各 provider 的 `apiKey` 并把 `enabled` 设为 `true` 即可；
- Kimi Coding 支持多账号（`kimiCodings` 数组）；
- Codex Plus 不需要 API Key，直接读本机 OAuth 登录态；
- 密钥也可以用环境变量提供（`KIMI_CODING_API_KEY` / `DEEPSEEK_API_KEY`）。

也可以通过接口管理配置（密钥回显为掩码，回传掩码不会覆盖真实值）：

```bash
curl http://127.0.0.1:3080/token-panel/config            # 读取（掩码）
curl -X POST http://127.0.0.1:3080/token-panel/config \
  -H 'content-type: application/json' -d '{"providers":{"deepseek":{"apiKey":"sk-...","enabled":true}}}'
```

## 数据文件

| 路径 | 内容 |
| --- | --- |
| `~/.dsh/token-panel/config.json` | 额度查询配置（含 API Key，勿提交） |
| `~/.dsh/token-usage/records.jsonl` | DSH 实时记录（每次模型调用一行） |
| `~/.dsh/token-usage/codex-records.jsonl` | Codex rollout 增量同步（token_count 差分） |
| `~/.dsh/token-usage/kimi-records.jsonl` | Kimi Code wire.jsonl 增量同步（usage.record） |
| `~/.dsh/token-usage/pi-records.jsonl` | Pi 会话转录增量同步（assistant usage 事件） |
| `~/.dsh/token-usage/hermes-records.jsonl` | Hermes session_model_usage 累计行差分同步 |
| `~/.dsh/token-usage/usage_tool.py` | 同步/聚合助手（随包携带，启动时自动更新） |

命令行也可直接查账：`python3 ~/.dsh/token-usage/usage_tool.py query 30d`。

## HTTP 接口（DSH web 端口，仅 loopback）

| 路由 | 说明 |
| --- | --- |
| `GET /token-panel/quota` | 面板额度数据（只含查询成功的 provider），白名单 CORS |
| `GET /token-panel/usage?range=today\|7d\|30d\|all` | 合并 token 用量，白名单 CORS |
| `GET /token-panel/refresh` | Tab Harbor 浏览器插件兼容端点（与旧 4173 `/api/refresh` 同形，返回全部 provider，不含 localUsage），白名单 CORS |
| `GET /token-panel/config` | 读取配置（密钥掩码） |
| `POST /token-panel/config` | 更新配置（要求 `content-type: application/json`，请求体上限 1 MB） |

CORS 白名单：仅本机 loopback 页面和浏览器扩展（`chrome-extension://` 等）的 Origin 会被允许跨源读取；
其他网站不会收到 CORS 头，浏览器层面读不到数据。额外的精确 Origin 可用环境变量
`TOKEN_PANEL_ALLOWED_ORIGINS`（逗号分隔）追加。

### Tab Harbor 浏览器插件迁移

旧架构中 Tab Harbor 通过 `http://127.0.0.1:4173/api/refresh` 取额度。合并后只需把
`token-quota.js` 中的地址改为 DSH web 端口（默认 `http://127.0.0.1:3080/token-panel/refresh`），
即可继续展示额度卡片；独立的 4173 服务可以退役。