Agent Profiler：看清会话时间去向的 Claude Code 性能分析器

Agent Profiler 是 YeonwooSung 开发的 Claude Code 性能分析器，属于 my-claude-code-mods 合集。它只回答一个问题：会话感觉很慢时，时间到底花在了哪里？它把每一轮的时间拆成等待模型、运行工具、阻塞的子代理和引擎开销，并在三个地方展示结果。

• 状态栏：Claude 工作时实时更新，例如 model 100% · tools 0% · ▶ model claude-haiku-5-5 12.5s。
• /profile：整个会话的文字报告；/profile turn 只看最近一轮。内容包括时间类别、首个 token 延迟、token 数、慢工具、重复读取的文件、子代理，以及简短的结论列表。
• /profile-pane：实时面板，显示进行中的请求和工具。/profile-export 会把会话写成 OTLP JSON。

插件对自己的说法很谨慎，从不报告“推理时间”。每个数字都带一个等级：measured（由 Claude Code 提供，例如工具耗时）、observed（插件在事件边界自己计时）、reported（API 报告的 token 用量）或 inferred（推算出的余量）。作者的 README 要求 Claude Code 2.1.287 或更高版本。

录屏中，我们在小型演示项目里启动加载了该插件的 Claude Code，并让 Claude 读取 README.md，用一句话描述这个项目。这一轮运行期间，页脚上方的状态栏实时计时：先是 model 92% · tools 0%，随后是 model 100%，以及正在进行的请求 ▶ model claude-haiku-5-5 和已用秒数。这一轮结束后，录屏运行 /profile。报告显示 29.0 秒的模型响应等待、5 毫秒的工具时间、首个 token 延迟、82.3k 输入 token、唯一一次 Read 调用，以及“等待模型占 agent 时间的 100%”这条结论。

使用安装区块中的任意一种方式；它们都直接从作者自己的插件市场安装。该市场里有许多插件，请选择 agent-profiler。状态栏和命令会在下一次会话开始时出现。

模块 hooks/register.tsx 在内存中保存一个 Profiler 对象，并在各个事件边界上喂给它数据：turn.start 和 turn.complete，每次模型调用通过 turn.step，每个工具通过 tool.call，以及来自 classic.PostToolUse 的 Claude Code 自己的工具耗时。tool.call 钩子只做观察：它用 await next(e) 等待工具完成，并原样返回结果，来自 hooks/register.tsx：

on('tool.call', async ($, e, next) => {
  anonymous += 1
  const id = e.tool_use_id ?? `anonymous-${anonymous}`
  const tool = String(e.tool)
  safe(() => profiler.toolStart(Date.now(), { id, tool, agentId: e.agentId, input: summarizeInput(tool, e as unknown as Record<string, unknown>) }))
  paint($)
  try {
    const answer = await next(e)
    safe(() => profiler.toolEnd(Date.now(), id, toolOutcome(answer)))
    return answer
  } // ...
}).catch(($, e, next) => next(e))

所有记录步骤都经过 safe()，所以分析器自身的错误会被丢弃，而不会破坏会话。状态栏每秒最多重绘两次。每一轮结束后，插件把新完成的 span 写入 <outputDir>/<sessionId>/<loadId>-<seq>.otlp.json，会话结束时再写入剩余部分和会话根 span。span 名称遵循 GenAI 约定（chat <model>、execute_tool <tool>、invoke_agent <type>）。span 和 trace 的 id 是确定性的，所以同一会话发送两次会得到相同的 span。内存中最多保留 20,000 个请求和工具调用，超出后最旧的已完成轮次会被丢弃。

三个选项位于 /plugin 设置菜单或 pluginConfigs 中：

要在 Jaeger 中查看追踪，运行仓库里的 examples/jaeger/docker-compose.yml，把 otlpEndpoint 设为 http://localhost:4318，然后打开 http://localhost:16686。Grafana Tempo 使用同样的 OTLP/HTTP 端点。

在运行之前，我们读过了插件可以执行的文件：.claude-plugin/plugin.json、hooks/hooks.json，以及完整的 hooks/register.tsx 和 Jaeger compose 文件。hooks/core/ 中的十一个模块里，我们完整读了 export.ts、otlp.ts、redact.ts 和 profiler.ts 中的输入摘要函数，并在所有模块中搜索了网络、进程、文件、eval、import() 和环境变量调用（唯一的命中都在 register.tsx 中）。测试文件只列出了文件名，没有阅读。没有 package.json、安装脚本、二进制文件、打包或压缩过的代码，也没有 eval 或动态 import()。hooks/ 源码中没有零宽字符或隐藏字符；非 ASCII 字符只是可见的状态栏和报告符号，例如 █、░、· 和 ⏱。插件不会向提示词或工具结果中注入文本。

值得注意的发现：

• 默认会写文件。 它在每一轮之后和会话结束时调用 $.fs.write，写入 ~/.claude/agent-profiler/<sessionId>/，除非你设置了 outputDir。这是插件自己的文件夹，不是 settings.json 或 shell 文件，但写入时不会询问。文件包含耗时、token 数、模型名称、工具名称、Read/Edit/Write 的文件路径，以及每条 Bash 命令的类别（例如 test 或 build）。文件路径总会被导出。提示词、Bash 命令和搜索模式只有在 exportCommandText 开启时才会导出。
• 只有你选择后才会联网。 只有 otlpEndpoint 不为空时才会调用 $.http.fetch，而且只是把同样的追踪 JSON POST 到 <endpoint>/v1/traces。主机由你自己填写。如果指向远程收集器，文件路径以及（开启 exportCommandText 时）经过脱敏的命令会离开你的机器。README 提醒脱敏只是尽力而为。
• 读取一个环境变量，HOME，用来展开 outputDir 中的 ~。
• 拦截工具调用但不改变它们。 tool.call 和 tool.check 只被观察并原样放行，两者都有 .catch 保护。没有任何调用被拒绝或改写。claude plugin validate 还把 classic.* 钩子列为没有 .catch 的拦截型钩子；它们其实是返回 next(e) 的观察者。按 validate 的说明，在组织管理 Claude Code 的环境里，classic.* 钩子不会运行，所以那里的报告可能不完整。
• 不运行进程、没有守护进程、不调用模型。 它不运行命令，也没有后台服务，只有会话内的计时器。
• 可选的外部服务。 只有想浏览追踪时才需要 Jaeger 或 Tempo。compose 文件会拉取 jaegertracing/all-in-one:latest，插件自己从不运行它。
• 许可证。 Apache-2.0（仓库根目录的 LICENSE）。

claude plugin validate 没有报告错误或警告，只有上面的提示信息。作者的 11 个文件共 67 个测试，用 claude plugin test 在 Claude Code 2.1.303 上全部通过。

已在 macOS 上使用 Claude Code 2.1.303 检查：validate、作者的测试和演示录屏。README 说明它自己的端到端测试在 2.1.280 上运行，事件结构遵循 2.1.292 的类型声明。面板和状态栏可以在终端和桌面版 Code 标签页中绘制，但 VS Code 聊天面板和 claude -p 中不行；/profile 文字在各处都可用。

• 没有状态栏或命令。 确认 claude --version 为 2.1.287 或更高版本，并在已打开的会话中安装后运行 /reload-plugins。
• 没有追踪文件。 在得知会话 id 之前不会写入任何内容。写入失败会以通知形式显示一次；请检查 outputDir 是否可写。
• 热重载后数字会重置。 内存中的状态会重新开始，但已经写入的批次仍保留在磁盘上，位于旧的加载 id 之下。
• 通过 Bash 修改的文件。 重复读取检测看不到它们。
• 模型服务器内部的时间（排队、预填充、解码）任何客户端工具都无法拆分；首个 token 延迟把它们合在一起。