1. 为什么非做这个监控面板不可Claude Code 会话复盘的三块硬伤1.1 会话一关记忆就断黑盒式开发的挫败感Claude Code 用久了最让我难受的不是它偶尔犯错而是会话一旦关闭整个过程就像没发生过一样。人在终端里敲命令Shell 的 history 还会留下记录好歹能翻出昨天半个小时前敲过什么。但 Claude Code 不一样它是一个会自己规划、自己读文件、自己执行命令、自己来回试错的代理一次会话里可能跑了十几个工具调用、改了七八个文件、执行了几十条命令。会话结束之后你手上只剩一个结果过程完全黑盒。我最早想复盘一次几个小时的会话时第一反应是去翻终端输出结果发现早被滚屏刷没了。用/resume倒是能把上下文接回来可那是让 Claude 自己回忆不是让我自己看数据更没法回答上周那个功能它到底绕了多少弯路这次会话烧了多少 token它为什么改完 A 文件又去改 B 文件这类问题。真正让我下决心做监控面板的是一次我花了两小时排查一个构建问题最后感觉什么都没推进想回头看看中间哪一步决策错了居然没有任何可查的东西。所以这个Claude Code 会话监控面板解决的就是这么一件事把每一次会话从黑盒变成透明盒子让你事后能像看录像一样回放整个过程同时能对每天的 token 消耗、工具调用、命令执行做统计和分析。适合谁重度使用 Claude Code 的开发者、给团队接入第三方模型的人、以及所有关心 AI 编程成本和安全性的用户。1.2 想看 token、想看成本统计缺口的现实感官方版本在会话结束时确实会显示 token 数但那是瞬时的窗口一关数字就没了。你想回答这个月到底烧了多少 token哪几天消耗特别大哪个项目吃掉了大部分预算靠肉眼完全做不到。更麻烦的是很多人并不只是用官方订阅。社区里用 cc switch 把 Claude Code 切到 DeepSeek、Qwen、GLM 这类第三方模型接口的场景非常普遍还有人把 Claude Code 接上 LMStudio 拉本地模型。这种情况下官方自带的 token 统计要么不显示要么数字明显不准成本更是完全对不上。我自己的做法是把会话记录和token 统计分开看待记录永远有统计则按渠道口径灵活处理。下面这张表是我在选型时梳理过的数据可用性情况。接入方式会话 JSONL 记录Hook 事件token_usage 统计成本估算官方订阅/API完整完整完整可按公开价格估算cc switch 接第三方模型完整完整部分缺失或为 0按第三方渠道定价LMStudio 本地模型完整完整普遍缺失不适用按 0 处理这个表是我后面设计所有统计口径的基础。一开始如果没想清楚很容易被某些会话没有 token 数据这种事情搞崩所以先把口径定死后面写代码才顺。1.3 复盘不是看日志是看决策过程面板做的第二件事是把日志变成决策过程回放。原始 JSONL 里有几百行事件流你直接打开它看就像考古。但把这些事件按时间顺序串起来就能看到一个很有意思的叙事用户提了什么需求Claude 先读哪个文件第一次给的方案是什么执行命令报错了它怎么办最后是靠哪一步改对的。说到这可能有人觉得反正 Claude Code 自己会输出过程看着它跑不就完了问题是你盯着它跑的时候只能看当下盯不了三小时前的第二个拐点。而且人会走神、会中途去开会。面板的意义就是把注意力变成可回溯的数据让你可以在任何时间点重新审视当时那个决定是否合理。这也是我在设计数据表结构时优先保证时间线完整可重放的原因。2. 数据从哪来Hook 事件流和 JSONL 会话录播的双通道方案2.1 Hook 机制先搞清七个事件点Claude Code 自带一套 Hook 机制可以理解成会话生命周期的回调。它在特定时机往你配置的命令里塞一段 JSON你写完脚本处理这段 JSON 就行。和监控相关的关键事件点有这些。事件名触发时机对我的监控面板的价值SessionStart会话刚开始记录会话起点、项目路径UserPromptSubmit用户提交新提示词记录需求内容作为时间线节点PreToolUse工具调用前可选记录准备调用PostToolUse工具调用后记录工具名、输入、输出结果Stop一轮任务结束等待下一条判断一段工作的阶段性结束SubagentStop子代理任务结束追踪多代理协作场景SessionEnd会话结束汇总 token、turns落库收尾每个事件传到脚本里的 JSON 结构大致长这样关键字段是 session_id、cwd、hook_event_nameUserPromptSubmit 会带 promptPostToolUse 会带 tool_name 和 tool_input/tool_response。{ session_id: 5f3a..., transcript_path: /home/user/.claude/projects/.../5f3a....jsonl, cwd: /home/user/projects/my-app, hook_event_name: PostToolUse, tool_name: Bash, tool_input: { command: git diff }, tool_response: ... }提示Hook 拿到的 JSON 是经过脱敏还是原文取决于具体字段和版本但至少 session_id、cwd、事件名是稳定的。不要把敏感信息原样写进面板日志这是后话。2.2 settings.json 配置示例与常见坑配置放在~/.claude/settings.json用户级如果某个项目想单独配置就在项目根目录放一份.claude/settings.json会覆盖用户级同名配置。我自己的监控配置是这样的。{ hooks: { SessionStart: [ { matcher: , hooks: [ { type: command, command: python3 /home/user/.claude_monitor/hook_sink.py } ] } ], UserPromptSubmit: [ { matcher: , hooks: [ { type: command, command: python3 /home/user/.claude_monitor/hook_sink.py } ] } ], PostToolUse: [ { matcher: , hooks: [ { type: command, command: python3 /home/user/.claude_monitor/hook_sink.py } ] } ], SessionEnd: [ { matcher: , hooks: [ { type: command, command: python3 /home/user/.claude_monitor/hook_sink.py } ] } ] } }几个我实际踩过的坑Hook 命令里不能直接写需要交互的命令脚本必须能安静跑完不要等键盘输入。脚本执行时间不要拖太长。我见过有人往 hook 里塞了完整的 AI 摘要服务Claude Code 明显变卡。监控脚本只做接 JSON、写 SQLite这两件事毫秒级完成。matcher 字段留空字符串就能匹配所有场景但要注意不同版本对空 matcher 的写法要求有人写成matcher: *反而没触发。2.3 JSONL 会话日志拿来补数、回溯和兜底除了 HookClaude Code 本来就会把每次会话完整写进 JSONL 文件位置在~/.claude/projects/下面按项目路径编码的目录里文件名就是 session_id。每一行是一个事件对象type 字段区分 user、assistant、result、system其中 system 的 subtype 为 token_usage 时本行是累计的 token 统计。这套日志其实就是监控面板的录像母带。Hook 负责实时、轻量的统计入库JSONL 负责事后深挖和补数据。比如我有时候想回看某个具体时刻 Claude 的想法块thinking 块或者想统计一次会话中某段文本的完整输出JSONL 才是完整的来源。我建议的思路是两条腿走路线上监控的统计用 Hook保证实时和低开销需要完整时间线时再写一个 JSONL 解析器做重放。两者共用同一个 SQLite 库JSONL 解析出来的历史会话用补充写入的方式进去不去重也没关系查询时按来源字段过滤即可。补数这个操作很重要因为面板是后做的之前的老会话已经躺在 JSONL 里了不补就亏了历史数据。3. 监控后端骨架SQLite 建表、事件写库与分析口径3.1 建表设计的核心思想会话-事件两级结构我后端没有搞太重一个 Python 进程加一个 SQLite 文件就够个人开发者用了。为什么不用 MySQL/PostgreSQL因为监控面板是单机工具SQLite 零运维、单文件、备份方便查询能力完全够。后面如果要多机汇总再定期导出合并也可以。核心是两张表sessions 记录会话维度的汇总信息events 记录每个事件明细。CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, project_path TEXT, model TEXT, started_at INTEGER, ended_at INTEGER, total_turns INTEGER, total_api_calls INTEGER, total_input_tokens INTEGER, total_output_tokens INTEGER, data_source TEXT DEFAULT hook ); CREATE TABLE events ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, ts REAL, event_type TEXT, tool_name TEXT, tool_input TEXT, tool_output TEXT, content TEXT, cwd TEXT, raw_json TEXT ); CREATE INDEX idx_events_session ON events(session_id, ts); CREATE INDEX idx_events_type ON events(event_type);事件表不拆成消息表工具表而是用一张宽表。理由很简单做时间线回放时你要把用户提示、assistant 文本、工具调用、工具结果按时间顺序混排一张表取出就是完整序列排序一次搞定。工具调用的输入输出字段单独抽取出来是为了后面做命令统计时不用再去解析 raw_json。3.2 写库实现一个 Python 脚本解决 Hook 上报所有事件共用一个 sink 脚本的最省事方案是脚本读 stdin 的 JSON靠 hook_event_name 判断类型做对应插入。核心代码大约 60 行。#!/usr/bin/env python3 import json import sqlite3 import sys import time import os DB_PATH os.path.expanduser(~/.claude_monitor/monitor.db) def get_conn(): conn sqlite3.connect(DB_PATH) conn.execute(PRAGMA journal_modeWAL) return conn def main(): raw sys.stdin.read() if not raw: return try: data json.loads(raw) except json.JSONDecodeError: return event data.get(hook_event_name, ) session_id data.get(session_id, ) cwd data.get(cwd, ) ts time.time() conn get_conn() try: if event SessionStart: conn.execute( INSERT OR IGNORE INTO sessions(session_id, project_path, started_at, data_source) VALUES(?,?,?, hook), (session_id, cwd, int(ts)), ) elif event UserPromptSubmit: conn.execute( INSERT INTO events(session_id, ts, event_type, content, cwd, raw_json) VALUES(?,?,?,?,?,?), (session_id, ts, user_prompt, data.get(prompt, ), cwd, raw), ) elif event PostToolUse: tool_input json.dumps(data.get(tool_input, {}), ensure_asciiFalse) tool_output data.get(tool_response, ) if isinstance(tool_output, (dict, list)): tool_output json.dumps(tool_output, ensure_asciiFalse) conn.execute( INSERT INTO events(session_id, ts, event_type, tool_name, tool_input, tool_output, cwd, raw_json) VALUES(?,?,?,?,?,?,?,?), (session_id, ts, tool_use, data.get(tool_name, ), tool_input, tool_output, cwd, raw), ) elif event SessionEnd: conn.execute( UPDATE sessions SET ended_at? WHERE session_id?, (int(ts), session_id), ) conn.commit() finally: conn.close() if __name__ __main__: main()注意几个细节脚本开头不要做重活直接读 stdin如果脚本没来得及读完就退出事件就丢了。所有数据库操作都要 try/except 包住不要让 hook 脚本异常反过来影响 Claude Code 本身。PRAGMA journal_modeWAL能减少读写锁冲突因为 Hook 写入和后面面板查询是同时发生的。SessionEnd 事件里通常没有完整的 token 汇总。真正的累计 token 数据在 JSONL 的 token_usage 行里。所以我的做法是SessionEnd 只更新 ended_at等面板刷新时主动去解析该会话的 JSONL把 token 数据补进 sessions 表。或者写一个定时任务每小时扫一遍还没有 token 数据且已结束的会话。后者更可靠。3.3 时间与成本口径token 汇总、成本估算与多模型对照先明确 token_usage 事件在 JSONL 里的含义它的 total_input_tokens 和 total_output_tokens 是累计值不是当前增量。你取该会话最后一条 token_usage 就能得到整个会话的消耗。成本估算我做了个非常朴素的口径把模型当成一个可配置项每种模型在配置表里写单价。官方模型按公开 API 价格填第三方 API 按你自己的渠道价填本地模型填 0表示不计算成本。PRICE { claude-sonnet-4: {input: 3.0, output: 15.0}, # 每百万 token 的美元价格单位按实际渠道调整 deepseek-chat: {input: 0.27, output: 1.1}, qwen-max: {input: 1.6, output: 8.0}, local-lmstudio: {input: 0, output: 0}, } def estimate_cost(model, input_tokens, output_tokens): p PRICE.get(model, {input: 0, output: 0}) return (input_tokens / 1_000_000) * p[input] (output_tokens / 1_000_000) * p[output]价格这东西会变别写死在面板代码里。我在配置文件里维护哪天渠道改价了改配置重启就行。提示本地模型不是真的零成本只是不产生 API 费用。如果你想算电费或显卡折旧那是另一个话题别混进监控口径里。4. 面板视图怎么排时间线重放、消耗曲线与工具热力图4.1 会话时间线把一次开发过程放录像面板的核心视图我给了会话时间线。选中一个 session_id后端返回按 ts 排序的事件数组前端按类型渲染成纵向时间线用户提示是一个大节点下面展开 assistant 的文本、工具调用块、工具输出块。工具输出太长时就折叠只显示前 500 字符点开看全文。后端查询很简单SELECT session_id, ts, event_type, tool_name, tool_input, tool_output, content FROM events WHERE session_id ? ORDER BY ts;实际渲染时我最关注的是 Bash 命令的输入输出成对出现的效果。你能清楚看到 Claude 是先跑了git status看状态再rg搜代码再读写文件最后npm test验证。哪一步开始反复 retry哪一步开始乱改配置一眼就能看出来。这个视图对为什么它会这么改的解释力比任何聊天记录都强。4.2 当天消耗曲线什么时候在烧钱什么时候在摸鱼第二个视图是逐小时/逐日的 token 消耗曲线。按小时聚合的 SQL 大概是SELECT strftime(%Y-%m-%d %H:00, datetime(ts, unixepoch, localtime)) AS hour, COALESCE(SUM(json_extract(raw_json, $.total_input_tokens)), 0) AS input_tokens, COALESCE(SUM(json_extract(raw_json, $.total_output_tokens)), 0) AS output_tokens FROM events WHERE event_type system GROUP BY hour ORDER BY hour;注意这里我依赖的是 JSONL 解析后补进 events 的 token_usage 行而不是 Hook 写入的事件。Hook 事件里不带累计 token。这个视图用堆叠面积图展示 input/output 两条曲线下面再放一条成本估算的折线。实测里这个视图相当残酷。我有一阵子习惯晚上 11 点开始改需求面板上那个时间段的曲线直接拉满白天基本是条平线。说白了AI 编程成本不是均匀分散的它和你投入时间高度同步。看这个曲线的作用是帮你意识到什么样的工作节奏在烧多少资源而不是真的去限制什么。4.3 工具与命令的统计视图发现你的 AI 搭档的工作模式第三个视图是工具调用分布和命令统计。按 tool_name 分组计数再用柱状图展示。我这边跑了一段时间后典型分布大概是工具名占比说明Bash40% 左右执行命令、跑测试、查 gitRead25% 左右读文件内容Edit15% 左右修改文件Write10% 左右新建文件其他10% 左右WebSearch、TodoWrite、Task 等命令统计更有意思。把 tool_input 里的 command 字段按第一个 token 分组能看出 Claude Code 的工作习惯git status、git diff、rg、ls这类信息收集命令最频繁npm test、python -m pytest这类验证命令次之真正执行破坏性操作的命令其实很少。我专门加了一个风险命令审计视图把包含rm -rf、git push --force、DROP TABLE、curl | sh这类模式的命令列出来。不是要阻止 Claude 执行而是让我知道它什么时候执行过。毕竟面板的价值不只是看消耗还包含AI 在终端里到底做过什么的安全审计意义。5. 从数据里读出来的几个真相实测统计与应对思路5.1 会话时长的二八定律面板跑通之后我拿一周的数据做了次盘点印象最深的是二八定律在 AI 编程会话里同样成立。我那一周大概有 40 多个会话按时长排前 20% 的会话吃掉了接近 70% 的 token 消耗。下面是一组示意数据我自己盘的一周数据量级不变但具体数字按项目不同会有差异。会话类型数量占比token 占比典型场景短会话10 分钟55%15%问语法、查文档、小改动中等会话10~40 分钟25%30%单功能开发、修 bug长会话40 分钟以上20%55%多文件重构、跨模块联调这个分布带来一个实际动作长会话开始前我会先在最开始把需求说得尽可能明确并且中途主动把大任务拆成/compact或新会话。因为长会话后半段的效率明显低于前半段上下文越堆越多模型反而更容易绕远路。5.2 高 token 低产出会话的识别与止损面板最大的意外收获是帮我揪出了高 token 低产出的会话。这类会话的特征非常典型工具调用次数多、文件修改少、最后有大量验证命令反复失败。有一次我排查一个前端构建问题Claude 在一个半小时里跑了 47 次 Bash 命令大部分是重复构建和查日志最后只改了两行配置而且还没改对。如果没有面板我只会记得那天搞了一个半小时最后算是弄完了有了面板我能清楚看到它真正有效的尝试其实只有最后三次前面四十多次都在同一个误区里打转。我现在在面板上加了两个探测条件会话的 tool_use 事件数大于 30但 Write/Edit 事件数小于 3。同一工具的输出里错误关键字error、failed、exception密度超过某个阈值。命中任一条件就在会话列表里标一个疑似低效的黄标。这个不阻止运行只提醒我事后去看一眼。5.3 命令执行结构Bash 为主、文件编辑为辅的典型画像另一个观察是 Claude Code 的工作方式其实非常终端优先。它不像某些工具那样只改文件而是频繁用 Bash 收集信息、验证假设。这个画像决定了我给面板设计的默认统计重点命令频率、工具频率、文件修改清单三者并列。文件修改清单我通过解析 Edit/Write 工具的 tool_input 里的 file_path 得到。按文件分组统计后能看到哪些文件被 AI 改得最多。我项目里被测得最多的往往是配置文件、路由文件、测试文件这符合直觉但真看到 Top 5 的时候还是比想象中更能说明问题那些文件往往就是系统的热点复杂度所在。6. 运行环境差异与排查手册Ubuntu、VS Code 插件与本地模型场景6.1 Hook 不生效的排查链路不管你是 Ubuntu 直跑 CLI还是用 VS Code 插件跑 Claude Code监控逻辑都依赖同一个东西Hook 有没有真的触发。我遇到过几次面板突然没数据的情况排查链路基本固定这里完整写一遍先确认版本。claude --version确保 Hook 特性在当前版本可用。如果是从老版本一路升上来的配置文件格式可能变了。确认 settings 文件生效位置。用户级在~/.claude/settings.json项目级在项目根目录.claude/settings.json。项目级会覆盖用户级如果项目里有一份旧的空配置用户级的新增 Hook 可能不生效。给脚本加日志。在 hook_sink.py 第一行写open(/tmp/hook.log, a).write(called\n)。然后随便开一个会话看文件有没有追加。没追加说明配置完全没被触发追加了但数据库没数据再往下查。手动验证脚本本身。echo {hook_event_name:UserPromptSubmit,session_id:test,cwd:/tmp} | python3 hook_sink.py之后查库有没有 test 记录。脚本本身有问题就先在这一步暴露。检查权限和路径。Hook 命令里的 python3 路径、脚本路径必须是绝对路径或用~展开正确。脚本没有可执行权限没关系因为是用 python3 解释器调用的不依赖 shebang。最后检查 Claude Code 是否在升级后改了事件 JSON 结构。版本升级有时会让 raw_json 多了或少了字段但 session_id 和 hook_event_name 一直稳定所以脚本只依赖这两个字段就对了。这套链路我走了不知道多少遍核心原则是先确认触发再确认脚本再确认数据不要一上来就怀疑数据库。6.2 本地模型LMStudio/DeepSeek/Qwen/GLM下的统计盲区用 cc switch 接第三方模型或者把 Claude Code 指到 LMStudio 的本地 OpenAI 兼容接口会话的 Hook 照常触发JSONL 也照常写所以时间线和工具统计完全不受影响。真正受影响的是 token 统计。从我的观察看这类接入方式下JSONL 里 token_usage 行要么缺失要么数字为 0要么只有本轮调用级别的局部数字没有完整的累计值。原因是路由层通常只转发请求并没有按 Claude Code 期望的格式回填 usage 字段。处理办法是分层降级优先读取 token_usage 事件的累计值。没有的话退而求其次用 assistant 事件里每条消息自带的 usage 字段累加部分第三方接口会带。再没有就只统计消息条数、工具调用次数token 展示为未知。成本上cc switch 接 DeepSeek 这类渠道是有明确价格的我在配置里按渠道价填所以成本估算依然有意义。LMStudio 本地模型就直接填 0面板上会标注本地运行无 API 成本避免误读。6.3 日志字段版本差异与兼容写法Claude Code 社区更新很频繁JSONL 和 Hook 的 JSON 字段在不同小版本里出现过命名不一致的情况。比如同样是消息 ID有的版本叫messageId有的版本嵌套在message.id里。碰到这种情况别去猜直接在解析时做多字段兼容。def pick(obj, *keys): for key in keys: if key in obj: return obj[key] return None用的时候message_id pick(msg, messageId, id)这样写不同版本都能兼容。这类防御性写法不优雅但在工具链快速迭代的时候很实用。你永远不知道下次升级会不会又改字段名。顺带一提Windows 上~/.claude实际是C:\Users\你的用户名\.claude目录结构完全一样Python 脚本用pathlib.Path.home()展开就能跨平台。桌面版和 VS Code 插件跑出的会话日志在同一个位置所以监控面板不用区分你是在终端还是插件里开的会话。7. 让面板真正成为工作流的一部分告警、周报与多机器汇总7.1 预算告警token 冲高时第一时间通知光有面板被动查询还不够我做了主动告警。最简单的实现是每隔 10 分钟跑一次检查脚本统计当天的 inputoutput token 总量超阈值就往飞书自定义机器人发一条 Webhook。公司用飞书的话这个最省事。Webhook 消息格式大概是{ msg_type: text, content: { text: Claude Code 今日 token 消耗已达 120 万超过阈值 100 万请留意。 } }发送用一个 curl 就行curl -X POST -H Content-Type: application/json \ -d {msg_type:text,content:{text:Claude Code token 告警}} \ https://open.feishu.cn/open-apis/bot/v2/hook/你的机器人地址阈值怎么定我看了一周的数据之后把正常开发日的 80 分位值设成了默认阈值。超了不一定是坏事但至少会让你知道今天消耗异常值得停下来想想是不是某个会话在空转。7.2 周报自动生成把会话成本变成可汇报的数据第二个实用功能是周报。每周日晚上定时跑一个脚本把 SQLite 最近 7 天的数据聚合出来生成一段 Markdown包含活跃天数、会话总数、token 总量、API 调用次数、Top 5 高频命令、Top 5 被修改文件、成本估算。生成的文本我会贴进周会文档。周报里的两个指标我最看重一个是被修改文件 Top 5它反映这一周 AI 主要在哪个区域工作另一个是命令执行总数如果命令数远大于文件修改数说明这周很多时间花在试错上。用面板的话说这周是高效推进还是反复横跳一眼就看得出来。7.3 多机器汇总与历史归档如果你和我一样笔记本、台式机、服务器上都在跑 Claude Code每台机器的 SQLite 是独立的。我的汇总方案不复杂每台机器上放一个导出脚本每天把 JSONL 增量同步到一个统一目录晚上跑一次合并任务把新增记录插到中央数据库里。中央库的 schema 和单机完全一样所以面板代码不用改。合并时按 session_id 做幂等同一个会话不会重复统计。最后提一句安全意识Hook 脚本会接触到工具输出的原文包括文件内容、命令输出所以面板数据库本身就是一份敏感数据。我的个人经验是别把面板数据库放进公开仓库。别把第三方 API Key 或订阅凭证写进 Hook 脚本。Webhook 地址泄漏等于别人能给你发消息保管好。我自己的完整做法是监控目录放在~/.claude_monitor/整个目录不进 git只定期用加密备份。会话 JSONL 原始文件越来越大我只保留最近 30 天再老的压缩存档。这些细节听起来琐碎但面板跑起来之后数据是会越积越多的提前想好归档策略能省掉后面很多麻烦。面板做到这里已经不只是个统计工具了。它让我第一次能对我说过的每一句提示词、AI 执行过的每一条命令负责也让AI 编程效率高不高这个问题从感觉变成了数据。每天早上我打开电脑先扫一眼昨晚的 token 曲线和会话列表心里对今天该从哪接续就很有数。这个习惯说实话比面板本身更值钱。
