关于 lynx-trace-record
lynx-trace-record 是用于从已连接的 Lynx 开发应用录制并导出 trace 的技能，指导按顺序使用 CLI，并将自然语言需求转换为录制选项。
主要功能
- 01列出已连接的客户端
- 02开始和停止 trace 录制
- 03筛选 trace 类别
- 04采集内存和堆快照
- 05配置 JavaScript 性能分析
- 06将 trace 数据保存到本地
适用场景
- 01捕获页面的初始帧
- 02录制设备交互以便调试
- 03采集内存或堆数据
- 04导出 trace 供分析
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/lynx-trace-record确认已加载。
附带文件LICENSEscripts/trace_record.bundle.cjs
详细介绍
1. 工作流示例
录制过程需要使用 trace_record CLI 工具。操作顺序至关重要。
步骤 1. 列出已连接的客户端：
首先，列出所有已连接的客户端以获取客户端 ID。这有助于你确定要跟踪哪个应用。
- 如果有多个已连接的客户端，请让用户指定要跟踪的客户端 ID。然后，使用此 ID 和
--client参数进行跟踪。 - 如果只有一个已连接的客户端，可以省略
--client参数。 - 如果未找到客户端，请提示用户通过 USB 连接设备并打开调试应用。
node <path_to_the_skill>/scripts/trace_record.bundle.cjs list-clients
步骤 2. 开始录制：
在设备上构建或打开页面之前执行开始命令。这样可以确保捕获页面的完整首帧。使用步骤 1 中的客户端 ID 和 --client 参数。
node <path_to_the_skill>/scripts/trace_record.bundle.cjs start --client <client-id>
可选的开始参数可以根据用户的自然语言请求进行设置：
| 用户意图 | CLI 参数 | 跟踪配置字段 | 默认值 |
|---|---|---|---|
| 仅包含指定的跟踪类别 | --include-categories <categories> | includedCategories | * |
| 排除指定的跟踪类别 | --exclude-categories <categories> | excludedCategories | * |
| 启用内存数据采集 | --enable-memory-trace | enableMemoryTrace | false |
| 禁用自动垃圾回收 | --no-force-gc | forceGC | true |
| 自动为“shared-group” VM 捕获堆快照 | --enable-auto-heap-snapshot | enableAutoHeapSnapshot | false |
| 仅为指定的“shared-group” VM 捕获自动堆快照 | --shared-group-id <id> | sharedGroupId | 空字符串 |
| 指定 JS 配置文件类型，例如 quickjs 或 v8 | --js-profile-type <type> | JSProfileType | 空字符串（禁用 JS 配置文件） |
| 指定 JS 配置文件间隔，例如 100 | --js-profile-interval <interval> | JSProfileInterval | 当 JSProfileType 非空且间隔 <= 0 时为 100；否则为 -1 |
当用户用自然语言提出请求时，将请求转换为对应的 start 标志。例如，如果用户说“使用 trace_record 录制跟踪，启用内存数据采集，并自动捕获名为‘xxx’的 VM 的堆快照”，则运行：
node <path_to_the_skill>/scripts/trace_record.bundle.cjs start --client <client-id> --enable-memory-trace --enable-auto-heap-snapshot --shared-group-id xxx
常见的跟踪类别包括 lynx、vitals、javascript、jsb 和 devtool。如果用户要求仅包含指定的事件类别，请使用 --include-categories 并以逗号分隔列表。例如，“录制trace时只允许以下类型的事件js，jsb”对应 --include-categories lynx,jsb。如果用户要求“录制trace时允许所有事件”，则不要传入 --include-categories；默认的 includedCategories: ['*'] 会记录所有事件。
如果用户要求排除指定的事件类别，请使用 --exclude-categories 并以逗号分隔列表。例如，“录制trace时关闭devtool事件和vitals事件”对应 --exclude-categories devtool,vitals。
如果用户要求使用指定的 JS 引擎配置文件类型，例如“使用 v8 JS 配置文件进行录制”，则添加 --js-profile-type v8。如果用户未要求采集 JS 配置文件，则不要传入 --js-profile-type；默认的空字符串会禁用 JS 配置文件采集。
如果用户要求使用指定的 JS 配置文件间隔，例如“使用 JS 配置文件间隔 100 进行录制”，则添加 --js-profile-interval 100。例如，“使用 v8 JS 配置文件和间隔 100 进行录制”对应 --js-profile-type v8 --js-profile-interval 100。
步骤 3. 构建并打开页面
启动开发服务器。如果页面未自动打开，请手动打开目标页面。
pnpm run dev
步骤 4. 执行操作
如果要调试交互（例如滚动、点击、数据更新），现在请在设备上执行这些操作。
步骤 5. 停止录制并获取流句柄
停止跟踪录制。CLI 将输出一个包含 stream 字段的 JSON 响应（这是你的流句柄）。使用步骤 1 中相同的客户端 ID 和 --client 参数。
node <path_to_the_skill>/scripts/trace_record.bundle.cjs end --client <client-id>
步骤 6. 读取并保存跟踪数据
使用从步骤 5 获取的流句柄，将跟踪文件下载并保存到本地计算机。使用 --client 参数，并指定与步骤 1 中相同的客户端 ID。
node <path_to_the_skill>/scripts/trace_record.bundle.cjs readData --client <client-id> --stream <stream-handle> --output ./my-trace.pftrace
2. 常见错误排查
“请重启应用以启用跟踪功能”
enable_debug_mode 处于关闭状态。CLI 尝试自动启用该功能。解决方法：在设备上强制关闭应用，然后重启，并从步骤 1 开始重新录制。
“当前版本不支持跟踪功能”
请确保使用的是 Lynx 开发版本。更多信息请访问：https://lynxjs.org/guide/start/integrate-lynx-dev-version.html
“跟踪尚未启动，请先启动跟踪”
运行 end 和 readData 之前，需要先运行 start。