kernel-browser-harness

使用 Kernel Cloud Browsers 的 Browser-Harness

本技能介绍如何使用 browser-harness（browser-use 的开源 CDP harness）驱动 Kernel 云浏览器。browser-harness 已支持通过 BU_CDP_WS 环境变量连接任意 CDP 端点；本技能介绍的内容包括：从 Kernel CLI 提取该 URL、选择合适的 kernel browsers create 标志，以及使用 Kernel 会话 ID 作为 harness 守护进程名称，避免会话冲突。

何时使用本技能

在以下情况下使用本技能：

• 通过 browser-harness 驱动 Kernel 浏览器，而非用户本地的 Chrome
• 从 kernel browsers create -o json 提取 CDP URL，并将其传给 BU_CDP_WS
• 在长任务中跨多次 harness 调用（创建、驱动、检查、继续驱动、拆除）
• 针对多个 Kernel 浏览器运行并行 harness 会话，避免套接字冲突

先决条件

• 加载 kernel-cli 技能，以安装并验证 Kernel CLI。
• 如果 $PATH 中尚未安装 browser-harness，请按照其 setup-prompt 安装。如果已安装，请勿重新安装或运行设置提示词，直接创建 Kernel 浏览器即可。
• 仅在缺少 jq 时安装它（用于从 CLI 的 -o json 输出中提取字段）。

环境变量

变量	描述	默认值
KERNEL_API_KEY	必需，除非已运行 kernel login。CLI 使用它创建会话。	（无）
BU_CDP_WS	browser-harness 连接的 CDP WebSocket URL。仅在首次调用时设置——守护进程会缓存连接，供同一 BU_NAME 下的后续调用使用。	（发现本地 Chrome）
BU_NAME	为 harness 守护进程套接字设置命名空间。使用 Kernel 会话 ID（BU_NAME=$SESSION_ID）——每个会话都不会冲突，也无需记住额外的命名惯例。	default

基本用法

快速方式：只创建一个 Kernel 浏览器，将其原始 JSON 响应保存到私有且唯一的临时文件中，并从该文件中提取所有值。将 cdp_ws_url 视为凭证：不要记录它，也不要在不同任务之间复制它。

将以下内容作为一个 Bash 脚本运行，这样无论成功、失败还是中断，EXIT 陷阱都会执行清理：

set -euo pipefail

SESSION_FILE=$(mktemp "${TMPDIR:-/tmp}/kernel-browser-harness.XXXXXX.json")
SESSION_ID=
cleanup() {
  if [ -n "$SESSION_ID" ]; then
    BU_NAME="$SESSION_ID" browser-harness --reload >/dev/null 2>&1 || true
    kernel browsers delete "$SESSION_ID" || true
  fi
  rm -f "$SESSION_FILE"
}
trap cleanup EXIT

kernel browsers create --stealth --timeout 1800 -o json >"$SESSION_FILE"
SESSION_ID=$(jq -er '.session_id' "$SESSION_FILE")
CDP_WS=$(jq -er '.cdp_ws_url' "$SESSION_FILE")
echo "live view: $(jq -r '.browser_live_view_url // empty' "$SESSION_FILE")"

BU_NAME="$SESSION_ID" BU_CDP_WS="$CDP_WS" browser-harness <<'PY'
new_tab("https://news.ycombinator.com")
wait_for_load()
print(page_info())
PY

Kernel 浏览器默认以有头模式启动——创建响应中包含 browser_live_view_url。打印该 URL，用户即可观看 Agent 的操作；也可以传入 --headless 选择无头模式（无实时视图，镜像更小）。

kernel browsers create 标志选择

为 harness 创建会话时的常见选项：

标志	用途
--stealth (-s)	绕过机器人检测——大多数公开网站都应启用
--headless (-H)	不使用默认的有头模式——无实时视图、无 VNC
--profile-name NAME	重用已保存的 Kernel 配置文件（已登录状态、Cookie、localStorage）
--proxy-id ID	通过 Kernel 管理的代理路由（住宅、区域等）
--timeout N	空闲超时时间，单位为秒（默认值为 60，最大值为 259200）——长时间运行 Agent 时请调大
--start-url URL	会话启动时打开指定 URL
--save-changes	会话结束时将配置文件变更持久化

完整列表请参阅 kernel browsers create --help。

默认隐身代理的控制属于运行时更新，而非创建标志。如果隐身会话必须直接连接，请在首次 harness 调用前运行以下命令：

kernel browsers update "$SESSION_ID" --disable-default-proxy

使用 --disable-default-proxy=false 重新启用默认隐身代理。更改显式配置的代理时，请改用 --proxy-id 或 --clear-proxy。

多步使用

对于跨越多次 harness 调用的任务（创建、驱动、检查、继续驱动、拆除），守护进程会持有 CDP 连接。在所属脚本的 EXIT 陷阱运行前完成所有调用；对于该 BU_NAME，仅首次调用需要 BU_CDP_WS。

按照 BU_NAME=$SESSION_ID 的约定，之后的每次 harness 调用都只需：

BU_NAME=$SESSION_ID browser-harness <<'PY'
print(js("document.title"))
PY

这样也能自动支持并行会话：每个 Kernel 浏览器都有唯一的会话 ID，因此，针对不同会话的两个 BU_NAME=$SESSION_ID 调用不会争用守护进程套接字。

如果无法避免使用不同的 Shell 进程，请让父级协调器负责响应文件和最终清理；短生命周期的创建子进程中的陷阱可能会过早删除会话。变量丢失时，从保存的 JSON 中重新加载 session_id 和 cdp_ws_url。如果文件已不存在，使用 kernel browsers list --limit 100 -o json | jq 检查活动会话；使用 --offset 获取后续页面，并在继续操作或删除任何内容前确认确切的会话。

有关 harness 会话期间的重放录制，请参阅 kernel-cli 技能的重放参考。

并行会话

为每个工作进程创建一个 Kernel 浏览器，并将每个工作进程的响应文件、会话 ID、CDP URL 和守护进程名称放在一起。绝不要在不同工作进程之间共享响应文件或 BU_NAME。会话创建成功后，立即将其登记到父级清理流程中：

set -euo pipefail
declare -a SESSION_IDS=() SESSION_FILES=()

cleanup_parallel() {
  for sid in "${SESSION_IDS[@]}"; do
    BU_NAME="$sid" browser-harness --reload >/dev/null 2>&1 || true
    kernel browsers delete "$sid" || true
  done
  rm -f "${SESSION_FILES[@]}"
}
trap cleanup_parallel EXIT

mint() {
  local sid_var=$1 cdp_var=$2 file_var=$3 file sid cdp
  file=$(mktemp "${TMPDIR:-/tmp}/kernel-browser-harness.XXXXXX.json")
  SESSION_FILES+=("$file")
  kernel browsers create --stealth --timeout 1800 -o json >"$file"
  sid=$(jq -er '.session_id' "$file")
  SESSION_IDS+=("$sid")
  cdp=$(jq -er '.cdp_ws_url' "$file")
  printf -v "$sid_var" '%s' "$sid"
  printf -v "$cdp_var" '%s' "$cdp"
  printf -v "$file_var" '%s' "$file"
}

mint SESSION_A CDP_A FILE_A
mint SESSION_B CDP_B FILE_B

BU_NAME="$SESSION_A" BU_CDP_WS="$CDP_A" browser-harness <<'PY' &
new_tab("https://example.com"); wait_for_load(); print(page_info())
PY
PID_A=$!

BU_NAME="$SESSION_B" BU_CDP_WS="$CDP_B" browser-harness <<'PY' &
new_tab("https://example.org"); wait_for_load(); print(page_info())
PY
PID_B=$!

wait "$PID_A" "$PID_B"

陷阱会停止每个本地守护进程、删除每个计费中的 Kernel 会话，并移除两个响应文件。不要依赖 wait 或空闲超时来进行清理。

常见问题

1. 任务中途出现 BU_CDP_WS unreachable：Kernel 会话可能已达到空闲超时。默认值为 60s — 创建时传入 --timeout 1800（或符合任务需求的值）。

2. 区分不同 URL：将 cdp_ws_url 视为不透明的机密，并直接传给 BU_CDP_WS，不要改写。browser_live_view_url 仅供人工查看。

3. 守护进程未连接到新会话：如果创建了新的 Kernel 浏览器，却复用了过期的 BU_NAME，守护进程会继续连接旧的 CDP URL。使用 BU_NAME=$SESSION_ID 可避免此问题。否则，在将该名称连接到新端点前，运行 BU_NAME=<name> browser-harness --reload。

4. 额外创建会浪费时间并导致费用损失：一项任务通常只需调用一次 kernel browsers create。保存并复用其 -o json 响应；绝不要硬编码之前任务中的 ID 或 CDP URL。

5. 始终拆除两层资源：使用 BU_NAME="$SESSION_ID" browser-harness --reload 停止指定的本地守护进程，然后运行 kernel browsers delete "$SESSION_ID" 并移除保存的 JSON 文件。--reload 不会删除 Kernel 浏览器；Kernel 会话会持续计费，直到被删除或达到空闲超时。脚本应在 EXIT 陷阱中执行这三项操作。

browser-harness 技能负责辅助工具的用法（new_tab、page_info、js 等）。kernel-cli 技能负责浏览器和重放的生命周期管理。此技能仅限于 CLI 与 harness 之间的连接方式。