Claude Code工具调用性能分析：瀑布流时间线快速定位瓶颈

有次让 Claude Code 跑一个稍微复杂的重构任务，七八分钟过去了，终端还在刷。

完全看不出它卡在哪里。Bash 命令没有报错，模型仍在输出，可就是慢得像蜗牛。是某个文件被反复读取了几十次？还是哪个命令在等 IO 响应？抑或是模型钻进了某种死循环？终端输出全是过去时，刷屏后就消失了。等任务跑完，你根本说不清时间到底耗在了哪一段。

后来装上了 cctrace，同样的任务跑完之后打开瀑布流时间线，一眼就发现问题所在：有一个 Bash 工具调用卡了将近两分钟，前后各有一批 Read 快速通过，中间夹着十几个工具调用的结果。困惑从「完全不知道」变成了「哦，原来是这里」。

cctrace 的核心逻辑其实特别直白：把一整段会话过程，转化成你能一眼看明白的瀑布流时间线。

一、那些看不见的性能瓶颈

用 Claude Code 或 Codex 执行稍微复杂一点的任务时，终端里会不停刷新输出。看起来它在卖力工作，但你根本说不清楚：哪个工具调用耗时最长？是 Read 读取了一堆文件，还是 bash 在苦等某个命令？模型什么时候在真正思考，什么时候彻底卡住了？子 agent 是何时开始扇出（fan out）的，又扇出了几层？一次对话窗口跑了五分钟，wall-clock 时间究竟耗费在哪一段？

这些问题，光看终端输出根本无法回答。Claude Code 没有内置的 profiler——transcript 文件虽然存在，但只是一行一行的 JSON，需要手动关联事件顺序；ccglass 记录用另一套格式；进程层面的事件又是另一回事。三路数据，散落各地。

二、cctrace 的解决方案

cctrace 的做法非常简单：在你启动 agent 之前，先套上一层包装器。

cctrace claude -- claude

执行这一行命令之后，cctrace 会同时监控三个来源：agent 进程本身的活动（process 层）、transcript 文件的写入（transcript 层）、以及 ccglass 的 trace 记录（ccglass 层）。三路事件汇入同一套 Event / Session 模型，用启发式算法把跨来源的相关事件关联起来，每条关联标上四档置信度（exact/likely/possible/unknown）。

然后在本地启动一个 web server（默认 127.0.0.1:43179），打印出 URL，浏览器打开就是瀑布流时间线。没有后台进程，没有遥测，数据只写入本地的 JSONL 文件。

三、实际能观察到什么

瀑布流时间线

左侧按请求轮次分组，每一个事件（用户输入、AI 回复、工具调用、工具结果）都在同一条时间轴上。顶部有整段会话的事件密度总览，哪个时间段最密集，一眼就能锁定。支持横向拖动缩放，纵向滚动查看全部。

单个事件详情

点开任意一条工具操作，可以看到：参数和输出，耗时（start / end timestamp），关联 ID（与哪些事件有关联、四档置信度标签），以及原始事件 JSON。所以像「为什么这个工具调用这么慢」或者「这个工具调用的结果被后面哪个事件引用了」这类问题，点进去就能直接排查。

回放

每次会话都是以 JSONL 文件保存在磁盘上。跑完之后，随时可以：

cctrace view 

重新打开，无需重跑 agent。JSONL 格式，也可以直接用 grep、jq 或管道传给其他工具处理。

四、使用方法

安装

Go 1.22+ 环境：

go install github.com/androidZzT/cctrace/cmd/cctrace@latest

仅支持 macOS / Linux。

录制 Claude Code 会话

cctrace claude -- claude

CLI 会打印出本地 web UI 的 URL，浏览器直接打开即可。

录制 Codex 会话

cctrace codex -- codex

同一套录制管线，切换 agent 只需更换第一个参数。

回放已保存的会话

cctrace view 

五、设计上的几项取舍

代码结构按职责拆分得非常清晰：cmd/cctrace 是 CLI 入口，internal/ 下分 app（组装 CLI 解析、采集、持久化、server 启动）、trace（共享的 Event / Session 模型）、store（把会话和事件写入 session 目录的 JSONL）、collectors（process / transcript / ccglass 到 trace events 的转换）、correlate（启发式事件关联 + 四档置信度标记）、以及 server（本地 web UI + 事件 JSON API）。

选择 Go 的原因很实际：单一二进制交付，不依赖 Python 环境，也不依赖 Node。go install 一条命令就能装好，没有包管理器冲突。对于需要包装其他进程的 CLI 工具来说，这个约束极为重要。

为什么采用 JSONL 而不是 SQLite？JSONL 可以直接用 grep / jq 查询，对比两次会话非常直接，也方便管道输出给其他工具。不需要专门的查看工具就能读取数据。

关联置信度是如何计算的？基于启发式算法，利用时间邻近 + 事件类型：对于 API 请求/响应事件，在时间窗口内寻找最近的候选父事件（候选类型限定为 ToolCall/AgentTurn/Skill/Subagent），找到则标为 likely，找不到则标为 unknown。置信度是四档枚举（exact/likely/possible/unknown），不是数值分数。边缘情况可能会遗漏，但遗漏时显示 unknown，不会错误地标为 likely。

采集是否会拖慢 agent 性能？cctrace 是轻量包装层，采集过程是异步的，不会在 agent 的关键路径上造成阻塞。

六、小结

cctrace 并不追求大而全的调试平台，它只做一件事：把你已经在跑的 Claude Code / Codex 会话变得可观测。一个 Go 二进制，MIT 开源。

项目刚开源，还很早期——关联算法、UI、支持的事件类型都有很大的迭代空间。致谢：cctrace 读取 ccglass 导出的 trace 作为其中一路数据源，命令范式也借鉴了它「包一层、看清楚」的思路。