如何让看板自动实时刷新?Token Dashboard的SSE服务端推送实现详解

原创2026-10-29 19:21:071,855 阅读

如何让看板自动实时刷新?Token Dashboard的SSE服务端推送实现详解

Token Dashboard 是一个面向 Claude Code token 用量与成本的本地看板,它读取本地 JSONL 会话日志,把 token 消耗、花费、热点工具等数据可视化。它的概览页无需手动刷新——服务端每 30 秒扫描一次,一旦有新增数据就通过 SSE(Server-Sent Events)服务端推送实时更新图表。本文以这个项目为例,用尽量少的代码,详解如何用纯 Python 标准库实现看板的自动实时刷新,从后台扫描线程讲到浏览器的 EventSource 订阅。

Token Dashboard 实时刷新的概览面板:会话数、token 总量、估算成本与每日用量柱状图

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 连接:

  • 服务端持续向连接里写数据即可;
  • 浏览器用内置的 EventSource API 订阅,断线后会自动重连。

对于“只读看板周期性刷新数据”这种场景,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

三个关键细节:

  1. Content-Type: text/event-stream:声明这是一条 SSE 流,浏览器的 EventSource 才能正确解析;
  2. Cache-Control: no-store:禁止任何代理缓存这条流,保证每次连接都是实时数据;
  3. 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();
};

工作原理:

  1. new EventSource('/api/stream') 与服务端建立长连接;
  2. 每收到一条 data: 行就触发 onmessage,ev.data 就是服务端发来的 JSON;
  3. 事件类型为 scan(说明扫描线程发现了新数据)时调用 render() 重新渲染——看板 7 个标签页都由 JSON 接口支撑,重新拉取即呈现最新数字。

💡 SSE 最大的隐藏福利:断网或服务器重启后浏览器自动重连,不需要自己写重连逻辑。整段代码还包在 try/catch 中,即使流不可用,看板本身也照常可用(只是少了自动刷新)。

5. 整体数据流一图看懂

Token Dashboard 实时分析看板:按项目 token 用量、模型占比、Top 工具与最近会话列表

把三件套串起来,数据是这样流动的:

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", ...} 事件。

想读源码的话,关键文件:

7. 小结:看板自动实时刷新的 5 个要点

  1. 选对工具:只读看板用单向 SSE,不必上双向 WebSocket;
  2. 标准库就够:http.server + queue + 浏览器原生 API,零第三方依赖;
  3. 生产者-消费者解耦:扫描线程只喂队列,推送端点只取队列;
  4. 心跳保活:15 秒一次的 ping 注释行,防止中间设备断连;
  5. 有变化才推送:发现新数据才 EVENTS.put,前端不被无谓打扰。

这套模式几十行代码就能复用,适合本地工具、监控页、日志查看器等一切需要“数据一变,页面自动更新”的场景。

登录后查看全文
token-dashboard