• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI

本篇技术指南讲解 ZCode 内置的agent-browser浏览器自动化技能（Skill）中用于**性能分析（Profiling）**的完整能力：如何在你编写的自动化脚本、Agent 工作流或 CI 流水线中，一键捕获 Chrome DevTools 的性能 Trace（性能剖析），据此定位页面加载瓶颈、交互卡顿与渲染问题。读完本文，你将掌握agent-browser profiler start/stop的完整命令用法、Trace 分类（Categories）的选择策略、Chrome Trace Event 输出格式的解读方法，以及把性能回归检查嵌入 CI 的实战方案。

该技能随 ZCode 仓库分发，目录位于 .agents/skills/agent-browser，其中 SKILL.md 提供快速上手，references/commands.md 提供全部命令参考，本文对应的原始文档为 references/profiling.md。

Profiling 是什么：给浏览器自动化加上性能仪表

agent-browser是一个通过 Chrome DevTools 协议（CDP）直接驱动 Chrome/Chromium 的浏览器自动化 CLI。它的大多数命令（open、click、fill、wait等）服务于"把页面操作跑起来"，而profiler子命令服务于另一类问题：页面到底慢在哪里。

Profiling 的本质是在浏览器自动化运行期间，开启 Chrome 的性能追踪器，把主线程任务、JavaScript 执行、渲染管线、用户输入延迟等事件记录成一份结构化 Trace 文件，随后可以在 Chrome DevTools 或 Perfetto 等工具中加载回放、逐帧分析。

典型的使用节奏是：start开始记录 → 执行若干自动化操作 →stop停止并落盘，三步即可拿到一份可复现的性能报告：

# 开始记录 agent-browser profiler start # 执行待分析的页面操作 agent-browser navigate https://example.com agent-browser click "#button" agent-browser wait 1000 # 停止并保存为 Trace 文件 agent-browser profiler stop ./trace.json

注意：这里的start无需传参，stop必须给出保存路径。该能力仅适用于基于 Chromium 的浏览器（Chrome、Edge），这是 Chrome Trace Event 格式的硬性前提。

Profiler 命令详解：start / stop 与自定义分类

profiler子命令只有两个动作，但通过--categories参数可以精细控制采集范围：

# 使用默认分类开始剖析 agent-browser profiler start # 使用自定义 Trace 分类（逗号分隔）开始剖析 agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing" # 停止剖析并保存到指定文件 agent-browser profiler stop ./trace.json

• profiler start：开启性能追踪。不传--categories时使用默认分类集合（见下文），足以覆盖绝大多数性能诊断场景。
• profiler start --categories "<逗号分隔列表>"：按需裁剪采集范围。只采集你关心的层面可以减少数据体积，例如只关心 JavaScript 执行时间时，可仅保留v8.execute与devtools.timeline。
• profiler stop <path>：停止追踪并将内存中累积的事件序列化为 JSON 落盘。路径参数是必填的，文件即 Chrome Trace Event 格式的性能剖析文件。

在 SKILL.md 的 Visual Browser 调试小节中，profiler与另一组调试命令并列出现，方便在可视化调试时组合使用：

agent-browser --headed open https://example.com agent-browser highlight @e1 # 高亮元素 agent-browser inspect # 为当前页面打开 Chrome DevTools agent-browser record start demo.webm # 录屏 agent-browser profiler start # 开始 DevTools 剖析 agent-browser profiler stop trace.json # 停止并保存（路径可选）

从命令参考 commands.md 可以看到，profiler与trace start/trace stop同属 Debugging 命令族，前者产出 JSON 格式的 Trace 事件流，后者产出可离线分析的 trace 压缩包，二者可按需选用。

Trace 分类（Categories）：采集哪些事件

--categories接受逗号分隔的 Chrome Trace 分类列表。Chrome 的 Trace 系统按主题划分事件类别，选择不同的分类决定了最终数据里能看到什么。默认分类包括：

此外，采集还会默认附带若干disabled-by-default-*分类，用于提供更细粒度的 Timeline、调用栈（call stack）以及 V8 CPU 剖析数据。这类分类默认不开启、需要显式请求，它们能回答"某个函数到底占了多久 CPU"这类更深入的问题。

如何选择分类

• 快速定位整体瓶颈：使用默认分类即可，devtools.timeline已经能勾勒出主线程的时间分配；
• 聚焦脚本性能：追加v8.execute，区分"JS 太慢"还是"渲染太慢"；
• 验证业务埋点：追加blink.user_timing，与你自己的performance.mark()对齐，量化关键业务阶段耗时；
• 深挖函数级热点：依赖默认附带的disabled-by-default-*V8 CPU 剖析数据，配合调用栈分析。

三个实战用例：加载、交互与 CI 回归

用例一：诊断页面加载缓慢

最经典的场景是自动化打开页面后立即开始记录，等网络空闲后停止：

agent-browser profiler start agent-browser navigate https://app.example.com agent-browser wait --load networkidle agent-browser profiler stop ./page-load-profile.json

这里wait --load networkidle是 SKILL.md 中推荐的慢页面等待策略——等待网络活动平息后再停止采集，确保 Trace 覆盖从导航开始到资源加载完成的完整区间，而不是在页面还在加载时就过早截断。

用例二：剖析用户交互卡顿

聚焦"点击按钮后的响应与重渲染"：

agent-browser navigate https://app.example.com agent-browser profiler start agent-browser click "#submit" agent-browser wait 2000 agent-browser profiler stop ./interaction-profile.json

先导航、再开启剖析，可以避免把无关的初始加载开销混入交互数据；点击后固定等待 2 秒，把点击触发的任务、布局、绘制事件完整收进窗口。配合latencyInfo分类，还能评估从用户输入到画面响应的延迟。

用例三：CI 性能回归检查

把剖析嵌入构建流程，每个构建产物都留下一条可对比的性能基线：

#!/bin/bash agent-browser profiler start agent-browser navigate https://app.example.com agent-browser wait --load networkidle agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"

将BUILD_ID拼入文件名，即可在构建产物中留存每次构建的 Trace；后续通过脚本对比两次 Trace 中关键事件（如首屏任务总时长、RunTask事件耗时分布）的变化，即可在 UI 性能退化时第一时间告警。若在 CI 中使用，请参考 SKILL.md 中的建议为会话设置空闲自动回收（AGENT_BROWSER_IDLE_TIMEOUT_MS），避免后台守护进程残留。

输出格式：Chrome Trace Event（JSON）

profiler stop产出的文件是标准的Chrome Trace Event 格式JSON：

{ "traceEvents": [ { "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... }, ... ], "metadata": { "clock-domain": "LINUX_CLOCK_MONOTONIC" } }

核心字段含义：

• traceEvents：事件数组，是 Trace 的主体。每个事件至少包含：
  • cat：事件所属分类，对应上文的 Trace 分类（如devtools.timeline）；
  • name：事件名称，如RunTask（执行一个任务）、FunctionCall、Layout等；
  • ph：事件类型（phase），X表示完整事件（有开始和结束），此外还有B/E（开始/结束）、i（瞬时事件）、M（元数据）等；
  • ts：时间戳（微秒级，相对于 Trace 起始的时钟）；
  • dur：持续时间（微秒），仅完整事件（ph: "X"）具有。
• metadata：元信息。metadata.clock-domain字段根据宿主平台设置——在 Linux 上为LINUX_CLOCK_MONOTONIC，在 macOS 上对应 macOS 的单调时钟；在 Windows 上该字段会被省略。

理解ph与dur的配合是解读 Trace 的关键：X类型的完整事件自带持续时间，可以直接用来统计某类任务的总耗时；这也是性能回归脚本可以自动解析的依据。

查看与分析 Trace

生成的 JSON 可以直接拖入以下任一工具加载：

• Chrome DevTools：打开开发者工具（Ctrl+Shift+I）→ Performance 面板 → Load profile，选择 JSON 文件即可回放性能时间线；
• Perfetto UI：在线拖放 JSON 文件，获得更现代的交互式 Trace 分析视图，支持缩放、筛选与关键事件标记；
• Trace Viewer：在任意 Chromium 浏览器中打开chrome://tracing，加载 JSON 进行传统时间线查看。

加载后建议按cat过滤、按dur排序，先看总耗时最长的任务类型，再逐步下钻到具体函数，这与分类选择策略（先宽后窄）相互呼应。

已知限制与使用注意

• 仅支持 Chromium 内核：只适用于 Chrome、Edge 等 Chromium 系浏览器，不支持 Firefox 或 WebKit；使用其他内核（如 SKILL.md 中提到的 Lightpanda 引擎）时该能力不可用；
• 内存占用：剖析期间 Trace 数据在内存中持续累积，上限为500 万事件。请在关注区间结束后及时stop，避免长时间运行导致内存膨胀甚至丢失数据；
• 停止超时：停止采集有30 秒超时。如果浏览器无响应，profiler stop可能失败，此时应先排查浏览器是否卡死（如页面存在死循环脚本）；
• 与超时配置的联动：若你在自动化中通过AGENT_BROWSER_DEFAULT_TIMEOUT调整了默认超时（见 SKILL.md 的 Timeouts 小节），注意停止采集的 30 秒上限独立于该配置，属于浏览器侧的采集约束；
• 会话纪律：剖析完成后建议执行agent-browser close清理会话，避免后台守护进程残留影响下一次采集的纯净度。

总结

agent-browser profiler把"性能剖析"从繁琐的浏览器开发者工具操作中解放出来，变成一行命令即可嵌入自动化脚本与 CI 的能力。通过掌握start/stop的调用节奏、--categories的分类选择、Chrome Trace Event 格式的字段语义，以及三个开箱即用的实战用例，你可以把 ZCode 中的浏览器自动化从"能跑"提升到"跑得快、可度量、可回归"的工程化水平。更完整的命令与配置项，可继续查阅 commands.md 与 SKILL.md。

• 人工智能
• 大模型
• 代码智能体
• AI Agent
• 桌面应用
• 后端
• 前端
• CLI