magpie-tokentracker 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +96 -59
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,53 +4,63 @@
4
4
  [![License: MIT](https://img.shields.io/github/license/jerryjiao/magpie-tokentracker)](./LICENSE)
5
5
  [![node](https://img.shields.io/node/v/magpie-tokentracker)](https://www.npmjs.com/package/magpie-tokentracker)
6
6
 
7
- 在 magpie 窗口里追踪本机 [TokenTracker](https://github.com/xiufengsun/TokenTracker) 的 AI 用量:今天 / 7 天 / 30 天的 token 用量、花费、缓存命中、会话数,按编程工具和模型拆分,带小时级与每日趋势;另有订阅配额、近一年活动热力图、成就徽章,以及官方账号 / 云同步入口。零依赖。
7
+ 在 magpie 窗口里看本机 [TokenTracker](https://github.com/xiufengsun/TokenTracker) 追踪的 AI 用量:今天 / 7 天 / 30 天的总 token、花费、缓存读取、会话数,按编程工具和模型拆分,带小时级与每日趋势;另有订阅配额、近一年活动热力图、成就徽章,以及官方账号 / 云同步入口。全部数据来自本机回环接口,零依赖、不上传。
8
8
 
9
- ![本机看板截图(深色)](docs/screenshots/dashboard-dark-today.png)
9
+ ![本机看板(浅色,默认主题)](docs/screenshots/dashboard-today.png)
10
10
 
11
- ## 安装(发布后,从 npm)
11
+ 深色主题(跟随 magpie 的深浅色设置):
12
12
 
13
- npm 包发布后,一条命令安装:
13
+ ![本机看板(深色)](docs/screenshots/dashboard-dark-today.png)
14
14
 
15
- ```sh
16
- magpie plugin add magpie-tokentracker
17
- ```
18
-
19
- > 截至本文更新,npm 包尚未发布。当前本地开发安装方式见下文[「本地安装(开发中)」](#本地安装开发中)。
15
+ 「云同步」面板(官方账号登录、云同步与排行榜入口):
20
16
 
21
- ## 结构
17
+ ![云同步面板](docs/screenshots/cloud-panel.png)
22
18
 
23
- ```
24
- index.mjs magpie 宿主入口:server(input, options),懒启动服务
25
- server.mjs 零依赖 node:http 服务(只绑 127.0.0.1)
26
- lib/usage.mjs 纯函数:周期换算、卡片/拆分/序列整理
27
- lib/tokentracker.mjs TokenTracker 探活、自动拉起、API 调用
28
- page/index.html magpie 托管的带路页(bridge → 导航到本机服务)
29
- page/boot.js 读 bridge(语言/主题/端口/magpie.service)后跳转
30
- page/board.html|app.js|style.css 看板本体(服务端拼成全内联单页,见「注意」)
31
- test/*.test.mjs 28 个测试(node --test)
32
- test/fixtures/ 从真实 TokenTracker 接口抓的样例
33
- docs/ 设计规范、发布文档(不进 npm 包)
34
- ```
19
+ ## 安装
35
20
 
36
- ## 本地安装(开发中)
21
+ 已发布到 npm:
37
22
 
38
23
  ```sh
39
- magpie plugin add /Users/mac/Documents/projects/magpie-tokentracker
24
+ magpie plugin add magpie-tokentracker
40
25
  ```
41
26
 
42
- 装完后 magpie 窗口侧栏的 Plugins 组里出现「TokenTracker」页。
27
+ 装完重启 magpie(桌面 app 只在启动时索引插件库):侧栏 Plugins 组里出现「TokenTracker」页。验证:app.log 里出现 `plugin: [magpie-tokentracker] board on http://127.0.0.1:<port>/`。
43
28
 
44
- **本地路径安装的坑(2026-11-17 白屏事故)**:magpie 的页面文件(`magpie.page.file`)只从插件库 `~/.config/magpie/plugins/node_modules/<name>/` 下发;`plugin add <本地路径>` 只注册 spec、执行服务代码,但不拷 page 文件 → 页面 tab 永远白屏(服务其实是活的)。本地开发二选一:
29
+ - 升级:`magpie plugin update`(把所有插件装到最新版)。升级后页面还是旧版就重启 magpie。
30
+ - 卸载:`magpie plugin rm magpie-tokentracker`。
31
+ - 环境:node >= 20、magpie >= 0.1.1340。
45
32
 
46
- ```sh
47
- # A. 软链进插件库(本机用的就是这种)
48
- ln -sfn "$PWD" ~/.config/magpie/plugins/node_modules/magpie-tokentracker
33
+ ## 看板内容
49
34
 
50
- # B. 发 npm 包后 `magpie plugin add magpie-tokentracker`
51
- ```
35
+ - **指标卡**:总 Token(附输入 / 输出)、花费(附均摊到会话)、缓存读取(附命中率与缓存写入)、会话数。
36
+ - **周期**:今天 / 7 天 / 30 天。今天看每小时趋势,7 天和 30 天看每日趋势;柱图带纵轴刻度,横轴最多 10 个刻度。
37
+ - **拆分**:按编程工具(source)和按模型(Top 10)排行。
38
+ - **订阅配额**:按 provider 列出各用量窗口的百分比与重置时间;<70% 绿、70–85% 橙、>85% 红。
39
+ - **近一年活跃**:365 天热力图,附活跃天数与连续天数。
40
+ - **成就**:各成就的 tier 与进度(已满级单独标注)。
41
+ - **云同步**:右上「云同步」按钮在头部下方展开面板,显示官方账号登录态与入口(详见下文)。
42
+ - **主题与语言**:浅色为默认;magpie 深色模式下自动切深色。中文 / 英文跟随 magpie,也可用 `?theme=dark|light`、`?lang=zh|en` 指定。
43
+ - **刷新**:20 秒自动刷新主用量,页面隐藏时暂停、切回来立刻拉一次;右上「刷新」和 ⟳ 都会强制拉全部数据。
44
+ - **降级**:配额 / 热力图 / 成就任一接口失败只把该面板显示成「暂不可用」,不影响主用量区;TokenTracker 整体不可达时显示离线面板(命令、地址、原因、重试)。
52
45
 
53
- 装完(或第一次建好软链后)**要重启 magpie app**:桌面 app 只在启动时索引插件库,不重启它认不到新 page。验证:重启后 app.log 里出现 `plugin: [magpie-tokentracker] board on ...`。
46
+ ## 结构
47
+
48
+ ```
49
+ index.mjs magpie 宿主入口:server(input, options),懒启动本机服务
50
+ server.mjs 零依赖 node:http 服务(只绑 127.0.0.1),拼全内联看板页并暴露 /api/*
51
+ lib/usage.mjs 纯函数:周期换算、卡片/拆分/序列整理、配额/热力图/成就整理
52
+ lib/tokentracker.mjs TokenTracker 探活、自动拉起、回环接口调用
53
+ lib/official.mjs 官方账号登录态:读本机 config.json,返回掩码后的 ID
54
+ page/index.html magpie 托管的带路页(bridge 握手 → 导航到本机服务)
55
+ page/boot.js 读语言/主题/端口;magpie web 转发模式下先探活,失败给重试
56
+ page/board.html 看板模板(服务端把 style/app 内联进来)
57
+ page/app.js 看板逻辑(渲染、周期、自动刷新、各面板降级)
58
+ page/style.css 看板样式(浅色/深色两套变量)
59
+ page/icon.svg 插件页图标
60
+ test/*.test.mjs 29 个测试(node --test)
61
+ test/fixtures/ 从真实 TokenTracker 接口抓的样例
62
+ docs/ 设计规范、发布手册、截图(不进 npm 包)
63
+ ```
54
64
 
55
65
  ## 依赖
56
66
 
@@ -60,54 +70,71 @@ ln -sfn "$PWD" ~/.config/magpie/plugins/node_modules/magpie-tokentracker
60
70
  npx tokentracker serve # 或 tokentracker serve
61
71
  ```
62
72
 
73
+ 实测版本:TokenTracker 1.5.22。配额 / 热力图 / 成就三个面板读的是较新的本机接口,老版本没有对应接口时这三个面板显示「暂不可用」,主用量不受影响。
74
+
63
75
  ## 选项(magpie → Plugins → TokenTracker 的 options)
64
76
 
65
- | 键 | 默认 | 说明 |
66
- |---|---|---|
67
- | `port` | `3491` | 看板服务的端口(`0` = 随机,测试用) |
68
- | `tokentrackerPort` | `7680` | TokenTracker 的端口 |
69
- | `autoStart` | `true` | 探活失败时自动 `spawn` TokenTracker |
70
- | `command` | `""` | 拉起用的命令;空 = PATH 里的 `tokentracker`,再退到 `npx -y tokentracker-cli` |
71
- | `timeZone` | `""` | 「今天」的时区;空 = `Asia/Shanghai` |
77
+ | 键 | 环境变量 | 默认 | 说明 |
78
+ |---|---|---|---|
79
+ | `port` | `MAGPIE_TOKENTRACKER_PORT` | `3491` | 看板服务的端口(`0` = 随机,测试用) |
80
+ | `tokentrackerPort` | `MAGPIE_TOKENTRACKER_TT_PORT` | `7680` | TokenTracker 的端口 |
81
+ | `autoStart` | `MAGPIE_TOKENTRACKER_AUTOSTART` | `true` | 探活失败时自动 `spawn` TokenTracker |
82
+ | `command` | `MAGPIE_TOKENTRACKER_COMMAND` | `""` | 拉起用的命令;空 = PATH 里的 `tokentracker`,再退到 `npx -y tokentracker-cli` |
83
+ | `timeZone` | `MAGPIE_TOKENTRACKER_TZ` | `""` | 「今天」的时区;空 = `Asia/Shanghai` |
72
84
 
73
- 环境变量同名大写(`MAGPIE_TOKENTRACKER_PORT` 等)也能喂,手动跑服务时方便。
85
+ 环境变量在手动跑服务时方便,同名选项优先。
74
86
 
75
87
  ## 服务接口(全部只读,只对 127.0.0.1 开)
76
88
 
77
89
  | 路由 | 说明 |
78
90
  |---|---|
79
- | `GET /` | 看板 HTML(全内联单页;CSP `unsafe-inline` + 显式回环 connect-src,见「注意」) |
80
- | `GET /api/usage?period=today\|7d\|30d[&force=1]` | 整理好的 JSON:卡片、按工具、按模型、小时/日序列 |
81
- | `GET /api/status` | 服务端口 + TokenTracker 探活结果 |
82
- | `GET /api/healthz` | 存活检查 |
83
-
84
- - 数据 8 秒缓存,`force=1` 跳过;同周期并发请求合并。
85
- - TokenTracker 不在时回 503,payload 里带 `hint.command`;自动拉起失败后有 60 秒冷却,避免每 20 秒的自动刷新反复 spawn。
91
+ | `GET /`、`/index.html` | 看板 HTML(全内联单页;CSP `unsafe-inline` + 显式回环 connect-src,见「注意」) |
92
+ | `GET /app.js`、`/style.css`、`/icon.svg`、`/favicon.ico` | 原始静态文件(调试用,看板本身不引用) |
93
+ | `GET /api/usage?period=today\|7d\|30d[&force=1]` | 主用量 JSON:卡片、按工具、按模型、小时/日序列 |
94
+ | `GET /api/limits[?force=1]` | 订阅配额:各 provider 的用量窗口百分比与重置时间 |
95
+ | `GET /api/heatmap[?force=1]` | 近一年热力图:365 天格子、活跃天数、连续天数、月份标签 |
96
+ | `GET /api/achievements[?force=1]` | 成就:tier 与进度 |
97
+ | `GET /api/cloud` | 官方账号登录态(ID 掩码)+ 官方链接 + 登录命令 |
98
+ | `GET /api/status` | 本服务端口 + TokenTracker 探活结果与版本 |
99
+ | `GET /api/healthz[?probe=]` | 存活检查;带 `probe` 时回一段合法 JS,供带路页跨源探测 |
100
+
101
+ - 缓存:主用量 8 秒,配额 60 秒,热力图 / 成就 5 分钟;`force=1` 跳过,同周期并发请求合并。`/api/cloud` 只读本机配置文件,不缓存。
102
+ - TokenTracker 不在时数据接口回 503,payload 里带 `hint.command`;自动拉起失败后有 60 秒冷却,避免每 20 秒的自动刷新反复 spawn。
86
103
  - magpie 的页面 frame 是 opaque origin(`Origin: null`),所以 `/api/*` 对它回 `Access-Control-Allow-Origin: null`;其它 Origin 一律 403。数据本身不是秘密(TokenTracker 自己的读接口就是回环裸奔的),不加鉴权。
87
104
  - 拉起的 TokenTracker 用独立进程组(`detached: true`),服务退出时整组 SIGTERM,不留孤儿占着 7680。
88
105
 
89
106
  ## TokenTracker 接口约定(实测 1.5.22)
90
107
 
91
- - `GET /api/local-auth` → 探活 + 版本。
108
+ 本机接口挂在 `/functions/<slug>` 下:
109
+
110
+ - `GET /api/local-auth` → 探活 + `serverVersion`。
92
111
  - `tokentracker-usage-summary?from&to&tz&rolling=1`:总量、花费、缓存、会话、`rolling.last_7d/last_30d`。
93
- - `tokentracker-usage-daily` / `-usage-hourly`:日/小时序列。
112
+ - `tokentracker-usage-daily` / `tokentracker-usage-hourly`:日/小时序列。
94
113
  - `tokentracker-usage-model-breakdown`:按工具(source)→ 模型的拆分和定价。
114
+ - `tokentracker-usage-limits`:订阅配额窗口。
115
+ - `tokentracker-usage-heatmap?from&to`:每日活跃。
116
+ - `tokentracker-achievements`:成就与进度。
95
117
  - 花费不在 `queue.jsonl` 里,是按定价表算的,所以必须走 HTTP 接口,不能直接读文件。
118
+ - 官方账号登录态不在接口里,读本机 `~/.tokentracker/tracker/config.json`(`lib/official.mjs`)。
96
119
 
97
120
  ## 官方云同步与排行榜(可选)
98
121
 
99
122
  看板之外,[TokenTracker](https://github.com/xiufengsun/TokenTracker) 官方还提供两项云上能力:
100
123
 
101
124
  - **全球排行榜**:登录官方账号即可参加,免费。
102
- - **官方 Cloud 云同步**(付费,[tokentracker.cc/cloud](https://tokentracker.cc/cloud)):多设备用量聚合与网页历史。
125
+ - **官方 Cloud 云同步**(付费,[www.tokentracker.cc/cloud](https://www.tokentracker.cc/cloud)):多设备用量聚合与网页历史。官方标价 $4.99/月,以官方页面为准。
103
126
 
104
- 本插件看板会显示官方账号的登录状态与对应入口;不登录也不影响本地功能——看板的全部本地能力(读取、展示、按工具/模型拆分、趋势)只走本机回环接口,不需要任何账号。
127
+ 看板右上「云同步」按钮展开面板:未登录时给登录方式(打开本机 TokenTracker 看板的 Settings → Account,或 `tokentracker device-login`)和 Cloud 介绍入口;已登录时显示掩码后的账号 ID。不登录也不影响本地功能——看板的全部本地能力(读取、展示、按工具/模型拆分、趋势、配额、热力图、成就)只走本机回环接口,不需要任何账号。
105
128
 
106
129
  ## 常见问题
107
130
 
108
131
  ### 本机没装 TokenTracker,怎么办?
109
132
 
110
- 不用提前装。服务第一次被问到用量时会探活 `127.0.0.1:<tokentrackerPort>`(默认 7680);失败且 `autoStart` 开着(默认开)就自动拉起:优先 PATH 里的 `tokentracker`,退到 `npx -y tokentracker-cli`,都可以用 `command` 选项自定义。拉不起来时页面显示离线提示和可直接复制的命令;拉起失败后有 60 秒冷却,避免自动刷新反复 spawn(细节见「依赖」「选项」「服务接口」三节)。
133
+ 不用提前装。服务第一次被问到用量时会探活 `127.0.0.1:<tokentrackerPort>`(默认 7680);失败且 `autoStart` 开着(默认开)就自动拉起:优先 PATH 里的 `tokentracker`,退到 `npx -y tokentracker-cli`,都可以用 `command` 选项自定义。拉不起来时页面显示离线面板(可直接复制的命令 + 地址/原因 + 重试);拉起失败后有 60 秒冷却,避免自动刷新反复 spawn(细节见「依赖」「选项」「服务接口」三节)。
134
+
135
+ ### 安装后在侧栏找不到「TokenTracker」页,或页面空白?
136
+
137
+ 按顺序查:① 重启 magpie(桌面 app 只在启动时索引插件库);② `magpie plugin list` 里有没有 `magpie-tokentracker`,版本是不是最新的(升级见「安装」);③ app.log 里有没有 `plugin: [magpie-tokentracker] board on ...`;④ 直接打开日志里那个 `http://127.0.0.1:<port>/`,能打开说明服务正常,问题在页面下发。本地路径安装的旧坑见下文「本地开发」。
111
138
 
112
139
  ### 没登录官方账号?
113
140
 
@@ -116,27 +143,37 @@ npx tokentracker serve # 或 tokentracker serve
116
143
  ### 数据上传了什么?
117
144
 
118
145
  插件看板本身不向任何地方上传数据——它只读本机 TokenTracker 的回环接口。这些接口暴露的也只是聚合用量数字:tokens 数、按定价表估算的费用、模型名、编程工具名、小时/日时间桶,不含任何代码、提示词、对话内容或文件内容(见「TokenTracker 接口约定」)。只有当你主动使用官方 Cloud 云同步(付费)时,数据才会同步到官方云端,内容同样是用量数字,不是代码与对话。
119
- <!-- TODO(发布前): 到 TokenTracker 官方仓库(https://github.com/xiufengsun/TokenTracker)核对官方隐私说明的准确表述与链接后,替换本行。 -->
120
146
 
121
- ## 开发
147
+ ## 本地开发
148
+
149
+ 改代码时不装 npm 包,把项目软链进插件库(本机开发用的就是这种):
150
+
151
+ ```sh
152
+ ln -sfn "$PWD" ~/.config/magpie/plugins/node_modules/magpie-tokentracker
153
+ ```
154
+
155
+ 重启 magpie 后生效。**本地路径安装的坑(2026-11-17 白屏事故)**:magpie 的页面文件(`magpie.page.file`)只从插件库 `~/.config/magpie/plugins/node_modules/<name>/` 下发;`magpie plugin add <本地路径>` 只注册 spec、执行服务代码,但不拷 page 文件 → 页面 tab 永远白屏(服务其实是活的)。软链就是为绕开这个;正常用户从 npm 装则不存在这个问题(page 文件随包下发)。
156
+
157
+ ### 开发命令
122
158
 
123
159
  ```sh
124
- npm test # node --test test/*.test.mjs
160
+ npm test # node --test test/*.test.mjs(29 个)
125
161
  node index.mjs # 手动跑服务(默认 3491),Ctrl-C 会带走拉起的 TokenTracker
126
- open http://127.0.0.1:3491/
162
+ open http://127.0.0.1:3491/ # 直接看板(浏览器里 localStorage 可用,周期会被记住)
127
163
  ```
128
164
 
129
- 改完代码要再 `magpie plugin add <路径>` 一次,magpie 的 Bun 宿主才会重新加载(宿主进程 magpie-bu 会换 pid)。
165
+ 改了 `server.mjs` 或 `index.mjs` 要再 `magpie plugin add <路径>` 一次(或重启 magpie),magpie 的 Bun 宿主才会重新加载;只改 `page/` 下的文件不用,看板是每次请求现拼的,刷新页面即可(`server.mjs` 的 `BUILD` 需要 +1 的情况除外,见「注意」)。
130
166
 
131
- 发布流程(GitHub repo / npm publish / magpie 收录)见 [`docs/publish-checklist.md`](./docs/publish-checklist.md)。
167
+ 发布流程(GitHub release / npm publish / magpie 收录)见 [`docs/publish-checklist.md`](./docs/publish-checklist.md);界面规范见 [`docs/design-spec.md`](./docs/design-spec.md)。
132
168
 
133
169
  ## 注意
134
170
 
135
171
  - TokenTracker CLI 第一次 `serve` 会做初始化:给 Claude Code 写 hooks、改 Codex CLI 配置、装 Opencode 插件。都是可逆的,但要知情。
136
172
  - 端口 3491 是挑过的:magpie 里 loop-guard 插件占了 3477/3478,避开。
137
- - 端口被占时不再硬失败(magpie 自升级交接的真实事故修出来的):同款服务连续两次探活成功 → 复用;否则每秒重试绑定,最多 20 秒,等旧实例退出;外来占用者等满 20 秒才报错。`/api/healthz` 带指纹 `{service, build}`(复用按服务名判,不按 build —— 多实例共存的稳定优先;升级代码后想让老 build 退位,`magpie plugin rm <路径> && magpie plugin add <路径>` 走一遍,宿主整个换进程)。
173
+ - 端口被占时不再硬失败(magpie 自升级交接的真实事故修出来的):同款服务连续两次探活成功 → 复用;否则每秒重试绑定,最多 20 秒,等旧实例退出;外来占用者等满 20 秒才报错。`/api/healthz` 带指纹 `{service, build}`(复用按服务名判,不按 build —— 多实例共存的稳定优先;升级代码后想让老 build 退位,`magpie plugin rm magpie-tokentracker && magpie plugin add magpie-tokentracker` 走一遍,宿主整个换进程)。
138
174
  - 已知边界:同一台机器同时跑桌面 app 和 `magpie web` 时,第二个实例会复用桌面侧的服务(同款指纹),页面照常跳本机服务。
139
175
  - 看板是全内联单页(服务端把 style.css/app.js 内联进 board.html,并把 `__SERVICE_BASE__` 注入成 `http://127.0.0.1:<port>`):magpie 的页面 frame 是 `sandbox="allow-scripts"` 的 opaque origin,CSP 里 `'self'` 匹配不到任何来源,外链 css/js 和相对 fetch 全会被拦;所以 CSP 用 `'unsafe-inline'` + 显式回环 connect-src,fetch 一律走绝对地址。
176
+ - 同一个沙盒原因,页面里的 `localStorage` 不可用(读周期选择会降级为不记忆,不影响其它功能);直接浏览器打开时正常记忆。
140
177
  - 改了 `server.mjs` 记得 `BUILD` +1(healthz 里看得见);改了 page 文件不用,内联是每次请求现拼的。
141
178
 
142
179
  ## License
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "magpie-tokentracker",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "在 magpie 窗口里追踪 TokenTracker 的 AI 用量:今天 / 7 天 / 30 天的 token 与花费,按编程工具和模型拆分,带订阅配额、近一年热力图、成就与官方账号入口。",
5
5
  "type": "module",
6
6
  "main": "./index.mjs",