# ChatGPT Daily Token Tracker

一个面向 ChatGPT 网页使用场景的每日 Token 统计工具，包含：

- **MCP Server**：可以在 ChatGPT 中直接问“今天用了多少 token”；
- **Edge / Chrome 浏览器扩展**：自动捕获 `chatgpt.com` 页面中可见的用户消息与助手回复，并在本机估算 Token；
- **Windows 自动运行**：可用 ngrok 固定开发域名提供长期 MCP 地址，并通过计划任务开机自动启动；
- **本地数据存储**：统计数据保存在本机，不把完整聊天正文写入统计文件；
- **去重机制**：页面刷新、重复扫描不会把同一条消息重复累计。

> [!IMPORTANT]
> 这里统计的是**网页可见文本的 Token 估算值**，不是 OpenAI / ChatGPT 官方账号级 Token 账单。隐藏系统提示词、内部推理、不可见上下文等无法从普通网页扩展或 MCP 获取。

## 功能

### MCP 工具

| 工具 | 作用 |
| --- | --- |
| `today_usage` | 查看今天或指定日期的 Token 用量 |
| `usage_range` | 查看日期区间累计用量 |
| `record_usage` | 记录已经获得的精确 API usage |
| `estimate_and_record` | 估算指定输入/输出文本并记录 |
| `estimate_tokens` | 只估算文本 Token，不保存 |
| `tracker_info` | 查看能力、版本与限制 |

### 浏览器自动统计

安装扩展后，新产生的 ChatGPT 可见消息会自动发送到：

```text
http://127.0.0.1:8787/api/track-message
```

本机服务使用 `o200k_base` tokenizer 估算 Token，并只保存 Token 数、角色、时间、消息去重 ID 等统计信息。

扩展还提供 **“回填当前对话”** 功能，可按需把当前已加载的对话补计入当天；相同消息会自动去重。

## 环境要求

推荐环境：

- Windows 10 / 11
- Node.js 22+
- Microsoft Edge 或 Google Chrome
- 一个免费 ngrok 账号（仅固定公网 MCP 地址需要）
- ChatGPT 账号支持自定义 MCP / App

## 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 启动本地服务

Windows 可双击：

```text
启动Token统计插件.bat
```

也可以运行：

```bash
npm start
```

默认地址：

- MCP：`http://127.0.0.1:8787/mcp`
- 健康检查：`http://127.0.0.1:8787/health`
- 本地仪表盘：`http://127.0.0.1:8787/dashboard`

### 3. 安装 Edge / Chrome 自动统计扩展

Windows 可双击：

```text
安装浏览器自动统计扩展.bat
```

或者手动操作：

1. Edge 打开 `edge://extensions`，Chrome 打开 `chrome://extensions`；
2. 开启“开发人员模式”；
3. 点击“加载解压缩的扩展”；
4. 选择仓库中的 `browser-extension` 文件夹；
5. 回到 `chatgpt.com` 并刷新页面。

扩展弹窗会显示当天输入、输出、总 Token 和记录数。

## 固定 MCP 地址 + Windows 开机自启

如果要让 ChatGPT 长期连接本机 MCP，需要一个公网 HTTPS 地址。项目提供基于 ngrok 固定开发域名的 Windows 自动配置脚本。

双击：

```text
安装长期固定地址并开机自启.bat
```

脚本会：

1. 检查 Node.js 与 ngrok；
2. 在浏览器打开 ngrok authtoken 页面；
3. 让你在**本机 PowerShell** 中输入 authtoken；
4. 获取账号分配的固定 ngrok 开发域名；
5. 生成本机 `config/ngrok.yml`；
6. 将可执行的 ngrok 副本放入本机 `bin/`；
7. 创建 Windows 计划任务 `ChatGPT-Token-Tracker-Fixed`；
8. 自动启动并守护 Node MCP + ngrok；
9. 输出最终固定 MCP URL。

如果已有配置需要修复，可运行：

```text
修复固定地址自启动.bat
```

### ChatGPT 中添加 MCP

在 ChatGPT 的自定义 App / MCP 页面中：

- Server URL：填写脚本最终输出的 `https://xxxxx.ngrok-free.dev/mcp`；
- 身份验证：选择 **None / 无身份验证**；
- 扫描工具并保存。

之后即可在聊天中调用 `today_usage` 查询。

## 数据与隐私

以下内容**不会提交到 GitHub**：

- `data/`：本机 Token 统计、日志、运行时 URL；
- `config/`：ngrok authtoken 和运行配置；
- `bin/`：本地 ngrok 可执行文件；
- `.env`；
- `node_modules/`。

浏览器扩展不会把完整聊天正文发送到项目的公网 ngrok 地址；自动统计写入接口限定在本机 `127.0.0.1`。

> [!WARNING]
> 当前 MCP 连接示例采用“无身份验证”。固定公网 URL 不应主动公开分享。任何公网服务都应按你的风险需求增加认证、访问控制和审计。

## Token 统计口径

- `exact`：来自 OpenAI API 已返回的真实 `usage` 数字；
- `estimated`：使用 tokenizer 对可见文本进行估算；
- 浏览器自动统计记录标记为 `chatgpt-browser-auto` + `estimated`。

项目不会把估算值冒充为官方计费数据。

## 测试

```bash
npm test
```

当前测试覆盖：

- 中英文 Token 估算；
- 精确值与估算值分开汇总；
- Asia/Shanghai 按日切分；
- 相同 `eventId` 去重；
- 浏览器自动记录 HTTP API 写入与去重。

## 项目结构

```text
browser-extension/      Edge / Chrome Manifest V3 扩展
src/server.js           MCP + HTTP 服务
src/store.js            本地统计存储与去重
src/tokenizer.js        Token 估算
setup-fixed-ngrok.ps1   固定 ngrok 地址与开机任务安装
run-fixed-supervisor.ps1 Windows 后台守护
repair-fixed-autostart.ps1 固定地址/自启动修复
test/                   自动测试
```

## 开发与升级

建议每次升级后：

```bash
npm install
npm test
```

如果修改了 `src/server.js`，Windows 固定部署用户可以运行：

```text
修复固定地址自启动.bat
```

让后台 SYSTEM 服务重新加载新代码。

## License

MIT License。详见 [LICENSE](LICENSE)。