如何让看板自动实时刷新?Token Dashboard的SSE服务端推送实现详解
如何让看板自动实时刷新?Token Dashboard的SSE服务端推送实现详解
Token Dashboard 是一个面向 Claude Code token 用量与成本的本地看板,它读取本地 JSONL 会话日志,把 token 消耗、花费、热点工具等数据可视化。它的概览页无需手动刷新——服务端每 30 秒扫描一次,一旦有新增数据就通过 SSE(Server-Sent Events)服务端推送实时更新图表。本文以这个项目为例,用尽量少的代码,详解如何用纯 Python 标准库实现看板的自动实时刷新,从后台扫描线程讲到浏览器的 EventSource 订阅。
1. “自动实时刷新”解决什么问题?
Token Dashboard 的数据源是 Claude Code 持续写入磁盘的 JSONL 会话日志。假设你一边在终端运行 Claude Code,一边在浏览器打开看板:
- 手动刷新:每隔一会儿按一次 F5,既容易漏掉最新数据,又很烦人;
- 前端轮询:浏览器每隔几秒请求一次
/api/overview——没有新数据时也空耗请求,且服务端无法主动通知。
这个项目的目标就是服务端主动推送:数据只读、全部本地,一个单向通道就足够了。💡 运行 python3 cli.py dashboard 后,看板“每 30 秒重新扫描并实时推送更新”,这正是本文要拆解的实现。
2. 为什么选 SSE,而不是轮询或 WebSocket?
| 方案 | 通信方向 | 依赖 | 适合度 |
|---|---|---|---|
| 前端轮询 | 浏览器 → 服务端 | 无 | 空耗请求、有延迟 |
| WebSocket | 双向 | 需要第三方库 | 杀鸡用牛刀(看板只读) |
| SSE | 服务端 → 浏览器 | 零(原生 HTTP + 浏览器 API) | ✅ 单向推送、自带重连 |
关键约束:Token Dashboard 只用 Python 标准库(无 pip 安装步骤),WebSocket 并不容易实现;而 SSE 就是一条保持打开的 HTTP 连接:
- 服务端持续向连接里写数据即可;
- 浏览器用内置的
EventSourceAPI 订阅,断线后会自动重连。
对于“只读看板周期性刷新数据”这种场景,SSE 是最优解。
3. 服务端实现三件套
整个推送逻辑都在 token_dashboard/server.py 中,由三个协作部分组成。
3.1 后台扫描线程:每 30 秒扫一次
服务端处理请求时并不现扫数据,而是跑一个独立后台线程持续扫描(见 _scan_loop):
def _scan_loop(db_path, projects_dir, interval=30.0):
while True:
try:
n = scan_dir(projects_dir, db_path)
if n["messages"] > 0:
EVENTS.put({"type": "scan", "n": n, "ts": time.time()})
except Exception as e:
EVENTS.put({"type": "error", "message": str(e)})
time.sleep(interval)
关键点:只有发现新增数据(n<a href="https://link.gitcode.com/i/7f58e455ec74624b499bb205825b8b05" target="_blank">"messages"] > 0)才推送事件,没有新内容就不打扰前端;扫描出错时则推一个 error 事件。该线程在 [run() 启动服务器时以守护线程方式创建,不阻塞主线程的 HTTP 服务。
3.2 EVENTS 事件队列:生产者与消费者解耦
扫描线程和 SSE 端点之间,隔着一个模块级队列(见 server.py L27):
EVENTS: "queue.Queue[dict]" = queue.Queue()
这是经典的生产者-消费者解耦:
- 扫描线程只管
EVENTS.put(...),不关心谁在听; - SSE 端点只管
EVENTS.get(...),不关心数据从哪来; - 没有数据时
get会带超时地等待,天然形成心跳机制。
3.3 /api/stream 推送端点:打开一条长连接
SSE 端点的核心代码(见 do_GET):
if path == "/api/stream":
self.send_response(200)
self.send_header("Content-Type", "text/event-stream")
self.send_header("Cache-Control", "no-store")
self.send_header("Connection", "keep-alive")
self.end_headers()
while True:
try:
evt = EVENTS.get(timeout=15)
chunk = f"data: {json.dumps(evt)}\n\n".encode()
except queue.Empty:
chunk = b": ping\n\n"
try:
self.wfile.write(chunk)
self.wfile.flush()
except (BrokenPipeError, ConnectionResetError):
return
三个关键细节:
Content-Type: text/event-stream:声明这是一条 SSE 流,浏览器的EventSource才能正确解析;Cache-Control: no-store:禁止任何代理缓存这条流,保证每次连接都是实时数据;EVENTS.get(timeout=15)+ ping:最多等 15 秒,拿不到真实事件就发一行 SSE 注释: ping——它对业务逻辑不可见(浏览器会忽略),但能让连接保持活跃,防止中间代理或 NAT 超时断连。
💡 这就是 SSE 的标准模式:业务事件 + 心跳保活。客户端断开时 wfile.write 会抛出 BrokenPipeError / ConnectionResetError,代码捕获后直接返回释放连接,不留“僵尸连接”。
4. 前端实现:EventSource 几行搞定
前端逻辑简单到几乎可以抄走,位于 web/app.js 的启动函数 boot():
const es = new EventSource('/api/stream');
es.onmessage = ev => {
const evt = JSON.parse(ev.data);
if (evt.type === 'scan') render();
};
工作原理:
new EventSource('/api/stream')与服务端建立长连接;- 每收到一条
data:行就触发onmessage,ev.data就是服务端发来的 JSON; - 事件类型为
scan(说明扫描线程发现了新数据)时调用render()重新渲染——看板 7 个标签页都由 JSON 接口支撑,重新拉取即呈现最新数字。
💡 SSE 最大的隐藏福利:断网或服务器重启后浏览器自动重连,不需要自己写重连逻辑。整段代码还包在 try/catch 中,即使流不可用,看板本身也照常可用(只是少了自动刷新)。
5. 整体数据流一图看懂
把三件套串起来,数据是这样流动的:
Claude Code 写 JSONL 日志
│
▼
扫描线程(每 30s)──发现新数据──► EVENTS 队列
│
浏览器 ◄── EventSource 长连接 ◄── /api/stream(15s 超时 / ping 心跳)
│
▼
收到 scan 事件 ──► render() 重新渲染看板
服务器使用 ThreadingHTTPServer,每个浏览器标签页的 SSE 长连接各自占用一个线程,多标签页并存互不干扰。
6. 动手验证:如何看到实时刷新生效?
三步跑起来:
git clone https://gitcode.com/gh_mirrors/tok/token-dashboard
cd token-dashboard
python3 cli.py dashboard
浏览器打开看板后,等后台线程的 30 秒周期到来(或另开终端执行 python3 cli.py scan),只要有新数据,页面数字就会自动更新。
💡 还可以用 curl 直接观察 SSE 流:
curl -N http://127.0.0.1:8080/api/stream
你会看到周期性的 : ping 心跳行;一旦扫到新数据,紧跟一条 data: {"type": "scan", ...} 事件。
想读源码的话,关键文件:
- SSE 推送端点:token_dashboard/server.py
- 后台扫描线程:token_dashboard/server.py
- 前端 EventSource 订阅:web/app.js
- 服务器端测试用例:tests/test_server.py
7. 小结:看板自动实时刷新的 5 个要点
- 选对工具:只读看板用单向 SSE,不必上双向 WebSocket;
- 标准库就够:
http.server+queue+ 浏览器原生 API,零第三方依赖; - 生产者-消费者解耦:扫描线程只喂队列,推送端点只取队列;
- 心跳保活:15 秒一次的
ping注释行,防止中间设备断连; - 有变化才推送:发现新数据才
EVENTS.put,前端不被无谓打扰。
这套模式几十行代码就能复用,适合本地工具、监控页、日志查看器等一切需要“数据一变,页面自动更新”的场景。

