# @fangwangme/tokenpulse 中文文档

规范地址：https://npmcn.com/package/%40fangwangme/tokenpulse/

版本：0\.6\.16
npm 元数据更新时间：2026-11-09T09:40:35.144Z
中文译文更新时间：2026-11-14T09:53:37.495Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fangwangme/tokenpulse
原文对照：https://npmcn.com/package/%40fangwangme/tokenpulse/?lang=original
项目主页：https://github.com/fangwangme/tokenpulse#readme
源码仓库：https://github.com/fangwangme/tokenpulse

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：18.4 kB，3 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-15T07:41:00.697Z
- 最新版本发布：2026-11-09T09:40:34.804Z
- 近 30 天下载量：2376（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

编码剂的托肯用法和配额仪表板(Claude Code、Codex、Copilot、双子座CLI、反重力)

## 安装

```sh
npm install @fangwangme/tokenpulse
```

也可以使用：`pnpm add @fangwangme/tokenpulse`、`yarn add @fangwangme/tokenpulse`、`bun add @fangwangme/tokenpulse`

## README

# 托肯普尔斯

TokenPulse是一个Rust CLI + TUI仪表板,用于跟踪信使用途,成本,以及 多个AI编码代理的配额. 它将本地会话数据解为 SQLite分类账和介绍交互式仪表板——或简写/JSON/CSV 用于脚本的输出.

## 安装

TokenPulse 从本地文件系统读取代理会话数据, 所以安装在 同样的机器 特工运行.

### 预建二进制( 不需要 Rust 工具链)

通过 npm 在全球安装 :

```bash
npm install -g @fangwangme/tokenpulse
```

或者通过面包:

```bash
bun add -g @fangwangme/tokenpulse
```

或直接运行而不安装 :

```bash
npx @fangwangme/tokenpulse
```

```bash
bunx @fangwangme/tokenpulse
```

安装后,启动仪表板:

```bash
tokenpulse
```

为macOS(英特尔和苹果硅)和Linux发布预建二进制 (x64和arm64) (中文(简体) ). npm/bun 解析匹配您的机器的机器; 在任何其他的机器上 平台,从源头构建.

### 从源

需要一个 Rust 工具链 (1.75+):

```bash
cargo install --git https://github.com/fangwangme/tokenpulse tokenpulse-cli
```

或克隆并构建:

```bash
git clone https://github.com/fangwangme/tokenpulse
cd tokenpulse
cargo install --path tokenpulse-cli
```

## 截图

| 概览 | 配额 |
| --- | --- |
| ![Overview](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/overview.png) | ![Quota](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/quota.png) |

| 模型 | 每日 |
| --- | --- |
| ![Models](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/models.png) | ![Daily](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/daily.png) |

| 守护者 | 活动 |
| --- | --- |
| ![Keeper](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/keeper.png) | ![Activity](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/activity.png) |

| 设置 |  |
| --- | --- |
| ![Settings](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/images/settings.png) |  |

## 支持供应商

**用法分析** (会议历史):

| 提供者 | 来源 |
| --- | --- |
| 克劳德代码 | `~/.claude/projects/` 编号 : `~/.claude/transcripts/` |
| 代码 | `~/.codex/sessions/` |
| GitHub 副驾驶 | `~/.local/share/github-copilot/events.jsonl` |
| 打开代码 | `${XDG_DATA_HOME:-~/.local/share}/opencode/` 1.x和2.x存储,或 `OPENCODE_DB`(中文(简体) ) |
| 双子座CLI | `~/.gemini/tmp/` |
| 个人信息 | `~/.pi/agent/sessions/` |
| 反重力 | 语言服务器( GUI/ CLI) |

**配额获取** (剩余费率限额/贷项):

| 提供者 | 状态 |
| --- | --- |
| 克劳德代码 | ✅ |
| 代码 | ✅ |
| 反重力 | ✅ |

> 注释:
> 
> -   双子座用于历史分析;解析手柄 流出 JSONL 分解并包含缓存的输入符号.
> -   与运行中的语言服务器(GUI/CLI)同步反重力使用和 维护本地原始缓存 `~/.local/share/tokenpulse/antigravity-cache/`。 。 。 .

## 特征

-   **统一仪表板** 使用(概览/模式/每日/活动/配额/保管人/定居) 和一个交互式TUI中的配额,加上用于脚本的纯文本/JSON/CSV导出
-   **会话保持器和自动心跳** - 预定轻量级心跳 Claude Code, Codex, 和 Google 反重力 提前触发 5h 冷却计时器 和自动同步 在每周的配额重组后立即。 默认关闭; 每个键 花真正的配额,所以你选择每个代理
-   **活执行流** 具有已执行命令的实时心跳日志面板, 提示、回复、持续时间、状态代码和滑动鼠标轮滚动
-   **编目支持** ——本地SQLite 有每日的定价快照 如此历史性 成本不会悄悄漂移
-   **配额概况** 每个供应商最多4个窗口;每个窗口是一个 带预期进度标记并加详细行的全宽进度栏 由统一窗口标签领导( name`5H:`, (中文(简体) ), `WEEKLY · SONNET:`并显示重置 倒计时、使用/保留百分比和按当前速度指标
-   **自动更新 TUI** 配额和使用间隔时间 (0/1/2/5/10/15分,默认为5分);在设置标签中循环或切换,使用 在页脚中显示倒计时
-   **`r` 要刷新** ——在配额和使用视图中,不重启TUI
-   **堆叠的条形图** ——每日持续时间可在信使和成本视图之间切换,将零使用日期保留为空位
-   **热图** —— 值级的固电池色; GitHub- green调色板 成本,卡格-蓝色调色板用于代币;5个强度等级,20/40/60/80% 显示窗口峰; 主题变化的背景和边框
-   **活动加热图** ——鼠标可选择可点击的传奇范围, 代理/ 模型钻入和可滚动的选定日期细节
-   **模型表** ——按符号排序的默认(`t`可切换到成本(`c`)或日期(`d`),与 `%` 活动排序度量和源过滤器叠加的比例(`s`(中文(简体) )
-   **公司意识型号** 数据中的代理人/提供者分离 模式
-   **纯文本模式** 用于脚本和远程贝壳
-   **JSON 输出** · 在一个有效载荷中使用摘要+配额快照
-   **CSV 输出** ——按型号或每日细分,供作进一步分析
-   **观察历史** · 每一次配额调查(每个提供者、费率窗口和 模式家族),每个守护者运行都附加在本地SQLite数据库中,用于 自己的趋势分析

## 快速启动

### 第一次设置

```bash
# Interactive setup wizard — detects installed providers and guides configuration
tokenpulse init

# Auto-detect and enable found providers, skip prompts
tokenpulse init --default
```

### 运行仪表盘

```bash
# Interactive TUI (auto-detects terminal)
tokenpulse

# Plain text output (scripting / remote shells)
tokenpulse --no-tui

# JSON output (usage + quota in one payload)
tokenpulse --json

# CSV output
tokenpulse --csv daily
tokenpulse --csv models
```

### 过滤器

```bash
# Show data starting from a specific date
tokenpulse --since 2026-04-01

# Re-parse a specific date range
tokenpulse --refresh-days 2026-04-01:2026-04-09

# Force a fresh pricing fetch (otherwise uses cached pricing)
tokenpulse --refresh-pricing

# Full rebuild from scratch
tokenpulse --rebuild-all
```

> \[大 **重建后的反重力同步**:如果重建数据库(例如通过 `--rebuild-all`),您必须同时运行一次Antigravity CLI和桌面,以便完全同步使用历史。 之所以需要这样做,是因为它们需要同时积极进行数据同步和对接.

```bash
# Write timing diagnostics to a log file
tokenpulse --log
```

### 提供者设置

```bash
# Show current config
tokenpulse config show

# Enable / disable quota providers (claude, codex, antigravity)
tokenpulse config enable claude
tokenpulse config disable antigravity

# Quota display mode: "remaining" (default) or "used"
tokenpulse config set quota_display_mode=used

# Theme: auto, dark, light
# "auto" follows the OS appearance and re-checks on each refresh, so the TUI
# switches light/dark when you change the system setting while it's running (macOS).
tokenpulse config set theme=dark

# Auto-refresh interval in minutes for quota + usage (0 = disabled)
tokenpulse config set auto_refresh_interval=5

# Show empty providers in the dashboard
tokenpulse config set show_empty_providers=true

# Account row in quota cards: none, plan, or full (plan + email; default)
tokenpulse config set account_display=plan

# Enable / disable quota refresh (default: true)
tokenpulse config set refresh_quota=false

# Quota recovery alerts: how far the notification reaches
#   off       nothing at all
#   in_app    sound + the in-TUI toast and ambient pulse
#   terminal  ... plus a terminal bell and an OSC 9 desktop notification
#   system    ... plus a macOS Notification Center banner
tokenpulse config set notification_level=system

# The sound every level except `off` plays. Either `chime` (built in),
# `none` to stay silent, or any name under /System/Library/Sounds.
tokenpulse config set notification_sound=chime

# Fire a sample alert to check the whole chain without waiting for a real reset
tokenpulse config test-notification
```

> **音标上注.** 声音传来 `afplay` 而不是现在 终极钟,因为大多数终端船 带有可听钟 (例如,幽灵默认为 `bell-features = no-system,no-audio`) (中文(简体) ). 这个 内置的烟囱已经正常化到 macOS 上方约 11 dB `Ping.aiff` 就是这样 耳机里很难错过 若为 `notification_level=system` 没有显示横幅, 允许您的终端在系统设置 > 通知中发布通知; 声音演奏不管.

若为 `config.toml` 有错误, 更改它的命令和设置行 让它不受伤害,你应当报告错误,而不要重写它; 修复或删除文件,然后重试.

### 会话保持器( 心跳和醒动)

这个 **守护者** 选项卡允许您管理 Claude Code 、 Codex 和 Google Antigravity 的已排定的 pings 和 wakeups , 以便在指定时间保持会话温暖并触发冷却循环 .

每一个小叮当都花真正的配额, 所以发动机船 **已禁用**打开它 页:1 `keeper_engine` 在设置标签栏中行,然后启用您想要的开关 每个特工。 唤醒时间、提示和命令模板 `config.toml` 下级 `[keeper]`; 守护者动态解决每个最便宜的活动模式 本地目录的代理( Claude Haiku, Codex Luna, 抗重力闪光- Low) 开始和一天一次。 标签头显示精确的配置路径 .

-   **`←` 编号 : `→` (或 `h` 编号 : `l`(中文(简体) )** - 在仪表板标签之间切换
-   **`↑` 编号 : `↓` (或 `k` 编号 : `j` 编号 : `Tab`(中文(简体) )** ——选择代理卡(Claude Code / Codex / Antigravity)
-   **`1` 编号 : `d`** - 切换每天早上5小时的醒悟计时器(默认) `10:30`错过了比赛,只有两个小时之内
-   **`2` 编号 : `w`** ——切换每周自动同步(将每个尚未启动的每周窗口切入,所以一个重置永远不会被错过)
-   **`p`** ——立即测试所选代理
-   **鼠标轮** 活活地行刑和心跳历史流

面板显示最新50跑,发射时恢复;完整历史 保存在 `tokenpulse.db`。 。 。 .

## 数据模型

TokenPulse跟踪两个不同的概念:

-   **探员** ——您使用的客户端工具(例如, `Claude Code`, (中文(简体) ), `Codex`, (中文(简体) ), `GitHub Copilot`, (中文(简体) ), `Gemini CLI`, (中文(简体) ), `PI`, (中文(简体) ), `Antigravity`(中文(简体) )
-   **提供者** ——后端/型号公司(如:, `Anthropic`, (中文(简体) ), `OpenAI`, (中文(简体) ), `Google`, (中文(简体) ), `GitHub Copilot`(中文(简体) )

仪表板保持这些分离,所以可以归属于相同的模型家族 跨越多个特工.

## 本地存储

所有当地州都生活在一个单一的目录之下:

```
~/.local/share/tokenpulse/
├── config.toml        # user configuration
├── keeper_state.json  # Keeper last-fired bookkeeping
├── usage.db           # SQLite usage ledger
├── tokenpulse.db      # quota cache + quota/Keeper observation history
├── pricing.json       # cached model pricing
├── antigravity-cache/ # raw Antigravity session cache
└── log/               # daily rotating diagnostics log
```

`tokenpulse.db` 保留每一次配额调查的附加记录(每个提供者, 每个费率窗口,每个模型家族)和每个守门员运行,供日后分析. 这个 没有保留政策——如果老行长得太大,就自己删除.

## 项目结构

```
tokenpulse/
├── Cargo.toml                  # workspace root
├── tokenpulse-core/            # library: parsing, pricing, quota, ledger
│   ├── Cargo.toml
│   └── src/
│       ├── auth/               # provider credential detection
│       ├── config/             # config model & persistence
│       ├── history/            # quota + Keeper observation history (SQLite)
│       ├── keeper/             # scheduled agent pings
│       ├── pricing/            # model pricing (LiteLLM, OpenRouter, Models.dev)
│       ├── quota/              # live quota fetchers
│       └── usage/              # session parsers & SQLite store
├── tokenpulse-cli/             # binary: CLI entrypoints & TUI
│   ├── Cargo.toml
│   └── src/
│       ├── commands/           # init, config, usage, quota registry
│       ├── tui/                # ratatui dashboard
│       │   ├── views/usage/    # Overview, Models, Daily, Activity, Quota, Keeper, Settings
│       │   └── widgets/        # barchart, heatmap, gauge, trend
│       └── main.rs
└── docs/
    └── DESIGN.md               # design document & architecture notes
```

## 发展

```bash
cargo fmt --all
cargo test --workspace
```

> **绩效分析**
> 
> 当测试启动延迟时, 文件解析速度或 TUI 性能, 总是 构建和运行 `--release` (例如, `cargo run --release`) (中文(简体) ). 不尽人意的人 调试构建( e)`dev` profile)运行 mtime stat check, JSON 剖析和 SQLite 查询速度要慢到 5x , 这可能会扭曲测量.

主设计笔记 [文件/DESIGN.md](https://npmcn.com/package/%40fangwangme/tokenpulse/docs/DESIGN.md)。 。 。 .

## 承认

TokenPulse受到这些项目的启发并在此基础上发展:

-   **[代码栏](https://github.com/steipete/CodexBar)** 以 [@steipete (英语)](https://github.com/steipete) —— 说 macOS菜单栏应用程序实时配额能见度. 认证流量和配额 Codex、副驾驶、双子座和反重力的API模式从中得知 其开源执行.
    
-   **[缩放](https://github.com/junhoyeo/tokscale)** 以 [@ junhoyoo (英语)](https://github.com/junhoyeo) —— 说 Rust CLI + TUI 用于多个AI编码代理的象征性使用和成本. 启发了多塔布局和多代理归属设计.
    
-   **[开口](https://github.com/robinebers/openusage)** 以 [@ robinebers (中文(简体) )](https://github.com/robinebers) —— 说 用于 AI 订阅使用跟踪的 macOS 菜单栏 。 激励着我们 供应商覆盖范围和基于插件的方法,以添加新的配额来源.

## 常见问题

### @fangwangme/tokenpulse 是什么？

编码剂的托肯用法和配额仪表板\(Claude Code、Codex、Copilot、双子座CLI、反重力\)

### 如何安装 @fangwangme/tokenpulse？

在项目目录运行 npm install @fangwangme/tokenpulse，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 tokenpulse，可以用 npx tokenpulse 直接运行。

### @fangwangme/tokenpulse 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fangwangme\_\_tokenpulse 是否存在。

### @fangwangme/tokenpulse 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fangwangme/tokenpulse 可以商用吗？

@fangwangme/tokenpulse 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fangwangme/tokenpulse 的下载量有多少？

根据 npm 官方下载统计，@fangwangme/tokenpulse 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,376 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fangwangme/tokenpulse 还在维护吗？

最新版本 0\.6\.16 发布于 2026/11/09（5 天前）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/08/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。