mcpField
R
record-web-journey

record-web-journey

github.com/ikatkov测试与质量0138 次安装1 周前更新
代码仓库

关于 record-web-journey

record-web-journey 是用于录制浏览器操作流程并生成可审阅材料的 skill，适合测试人员或 Agent 记录网页旅程。支持人工或 Agent 驱动，并在浏览器所在主机保存步骤、截图和视频。

主要功能

  1. 01将浏览器操作录为可视步骤
  2. 02保存截图和 WebM 视频
  3. 03记录步骤及观察结果
  4. 04支持人工或 Agent 驱动录制

适用场景

  1. 01记录可复现的 Web 应用流程
  2. 02测试后查看截图和视频
  3. 03使用 Chrome 配置文件录制登录流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ikatkov/agent-skills --skill record-web-journey

安装后在 Claude Code 中输入/record-web-journey确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
auth-and-bot-checks.md
scripts/
.gitignore
package.json
record-flow.mjs
setup.sh

详细介绍

记录网页操作流程

生成 <out>/<NAME>-<timestamp>/，其中包含 steps.md、screenshots/NNN-<kind>-<label>.png 和 videos/*.webm。steps.md 不会保留输入的值和查询字符串。

在同一台主机上运行记录器和浏览器驱动。将产物直接保存在该主机上：在虚拟机中运行的浏览器会将产物写入虚拟机，在本地运行的浏览器则会将产物写入本机。完成后保留文件夹，以便后续查看，并报告其绝对路径。

将 SKILL_DIR 设置为包含此 SKILL.md 的绝对目录，然后通过绝对路径使用随附的记录器：

SKILL_DIR="/absolute/path/to/record-web-journey"
RECORDER="$SKILL_DIR/scripts/record-flow.mjs"
AB="$SKILL_DIR/scripts/node_modules/.bin/agent-browser"

每次单独调用 shell 时，都要重新设置 SKILL_DIR、RECORDER、AB、保留的 CDP 端口，以及适用情况下的 DISPLAY；Agent 工具环境中的 shell 可能彼此独立。

设置（每台浏览器主机仅需一次）

"$SKILL_DIR/scripts/setup.sh"
"$AB" skills get core

在记录器旁安装 agent-browser 和 Playwright，添加 Playwright 的 ffmpeg 辅助程序以录制视频，并在不存在 Google Chrome 时添加 Chromium。如果存在 Google Chrome，优先使用 --chrome：它在登录页面看来就像普通浏览器。

Agent 驱动录制（由你操作）

将请求解析为：起始 URL、录制 NAME，以及要执行的步骤。

  1. 检查主机。pgrep -a Xvnc 或 echo $DISPLAY 可告知你是否存在桌面；如果存在，则在每次 shell 调用中执行 export DISPLAY=<it>，这样用户就能实时观看。没有显示器时添加 --headless。检查 df -h /dev/shm；如果显示 64M，则重新挂载为 2G，以免 Chrome 渲染进程崩溃。在共享主机上，检查正在运行的 agent-browser 进程，选择唯一的会话，并在完成时仅关闭该命名会话。

  2. 在要录制的工作区中，选择此主机上的绝对输出目录和一个可用的本地 CDP 端口。在专用的长时间运行终端或 Agent 工具环境进程会话中启动记录器，并保持该会话运行：

    OUT="$PWD/.context/flow-recordings"
PORT="$(node -e 'const s=require("node:net").createServer();s.listen(0,"127.0.0.1",()=>{console.log(s.address().port);s.close()})')"
BROWSER_ARGS=()
if command -v google-chrome >/dev/null || { [[ "$(uname -s)" == Darwin ]] && [[ -x "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" ]]; }; then
  BROWSER_ARGS=(--chrome)
fi
printf 'CDP port: %s\n' "$PORT"
node "$RECORDER" "https://app.example.com/" --name "journey-name" "${BROWSER_ARGS[@]}" --cdp "$PORT" --out "$OUT"

在后续 shell 调用中保留打印出的端口和录制目录的绝对路径。对于已登录的操作流程，传入 --profile <dir>（参见 references/auth-and-bot-checks.md）。 3. 将 agent-browser 连接到该 Chrome，并使用唯一的会话名称按常规方式操作：

"$AB" --session "rec-journey-name" --cdp "$PORT" snapshot -i -u
"$AB" --session "rec-journey-name" --cdp "$PORT" click @e5

每条命令都使用 --session 和 --cdp。从记录器加载的起始 URL 继续操作；如果请求的步骤要求直接导航，则使用 open。 4. 按照人的节奏操作：每次操作间隔约一秒；导航后使用 wait --load networkidle。每张截图都在点击后 250 ms 拍摄，因此连续快速点击会让人难以分辨哪张截图对应哪一步。 5. 对于首屏以下的内容：先执行 scrollintoview @ref，再执行 wait 1000，然后执行 click @ref。带有 scroll-behavior: smooth 的网站会使用动画滚动；明确等待滚动稳定后再点击，可确保点击坐标与目标对齐，并避免在 claude.ai 上已验证的动画过程中读取坐标。点击时使用来自 snapshot -i 的最新可见引用。视觉上隐藏的 1x1 输入框会被记录为“（无可见目标）”，因此应选择代表该输入框的可见标签或控件。 6. 通过 <recordingDir>/STOP 结束操作；等待记录器会话中出现 “Saved N visual steps”，然后关闭命名的 agent-browser 会话。此顺序可在交接前完成 WebM 的写入。

touch "/absolute/recording/directory/STOP"

恢复或等待记录器的长时间运行会话，直到它打印出 Saved N visual steps，然后关闭命名的驱动会话：

"$AB" --session "rec-journey-name" close
  1. 在浏览器主机上完善 steps.md，在每个步骤下添加一条简短观察：可见文案、来自 agent-browser network requests 的相关响应，以及与预期流程不同的任何结果。保留产物文件夹。报告其绝对路径、步骤数、观察到的结果，以及阻碍执行请求步骤的任何因素。

人工驱动录制（由用户操作）

node "$RECORDER" https://app.example.com/ -name "F06" --chrome --profile .context/chrome-profile

用户照常使用窗口，并在完成后按下终端中的 Enter 键。生成的文件夹会留在该机器上所选的输出目录中，以供后续查看。

标志

标志含义
-name "<NAME>"文件夹前缀，例如 F06-custom-mcp-<timestamp>
--chrome使用已安装的 Google Chrome（若已安装，建议使用）
--profile <dir>重用 Chrome 用户数据目录，让登录状态在多次录制之间保持
--cdp <port>暴露 CDP，以便 Agent 使用 agent-browser --cdp <port> 连接
--headless不显示窗口；仍会生成视频和屏幕截图
--out <dir>父目录，默认为 .context/flow-recordings
--viewport WxH视口和视频尺寸，默认为 1440x900
--sign-in配合 --profile 使用：打开普通 Chrome，以通过机器人检查或登录，然后退出

结束信号：Enter（TTY）、STOP 文件、关闭浏览器、SIGTERM。Enter 或 STOP 会让 Playwright 走正常的最终收尾流程。

评论

支持 Markdown