Back to Details

peach-e2e-browse

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AI 브라우저 탐색

AI浏览器浏览

agent-browser
(기본) + 
./e2e/pwc.sh
(fallback)로 Chrome Beta를 제어한다. 사람이 로그인을 완료한 브라우저를 AI가 이어받아 탐색한다.
agent-browser
(默认) + 
./e2e/pwc.sh
(fallback) 用于控制Chrome Beta。 AI可以接管用户已完成登录的浏览器继续执行浏览操作。

도구 역할 분담

工具职责分工

용도도구이유
탐색/검증/확인agent-browsereval 6.6x 빠름, 토큰 2.3x 절약
시나리오 실행playwright-cli (
./e2e.sh run
)		lib/connect.js 기반 시나리오 인프라
fallbackplaywright-cli (
./e2e/pwc.sh
)		iframe 등 agent-browser 미지원 기능
用途工具原因
浏览/验证/确认agent-browsereval速度快6.6倍，节省2.3倍Token
场景执行playwright-cli (
./e2e.sh run
)		基于lib/connect.js的场景基础设施
fallbackplaywright-cli (
./e2e/pwc.sh
)		支持iframe等agent-browser未覆盖的功能

의사결정 트리 (최우선 확인)

决策树（优先确认）

목표가 무엇인가?
├─ 데이터 읽기 (텍스트, 개수, 값 확인)
│  → eval 한 줄로 해결
│
├─ 요소 조작 (클릭, 입력)
│  ├─ CSS 셀렉터를 알고 있다 → eval로 click/value 설정
│  └─ 셀렉터를 모른다 → snapshot -i -c + grep으로 ref 찾기 → click ref
│
├─ iframe 내부 접근
│  → playwright-cli fallback (references/iframe-모달-패턴.md 참조)
│
└─ 페이지 전체 구조 파악 (부득이할 때만)
   → snapshot -i -c (절대 전체 snapshot 금지)
핵심: eval부터 시도. snapshot은 최후수단.
目标是什么？
├─ 读取数据（确认文本、数量、值）
│  → 一行eval即可解决
│
├─ 元素操作（点击、输入）
│  ├─ 已知CSS选择器 → 通过eval设置click/value
│  └─ 未知选择器 → 用snapshot -i -c + grep查找ref → 点击ref
│
├─ 访问iframe内部
│  → playwright-cli fallback（参考references/iframe-모달-패턴.md）
│
└─ 掌握页面整体结构（仅必要时使用）
   → snapshot -i -c（绝对禁止全量snapshot）
核心：优先尝试eval，snapshot是最后手段。

워크플로우

工作流

1. 환경 확인 (setup)
2. CDP 연결 (agent-browser connect 9222)
3. tab list → 사용자에게 탭 목록 보여주고 작업 탭 확인
4. 선택된 탭에서 작업 (eval/click/snapshot)
5. 결과를 사용자에게 보고
1. 环境确认（setup）
2. CDP连接（agent-browser connect 9222）
3. 执行tab list → 向用户展示标签页列表，确认要操作的标签页
4. 在选中的标签页中执行操作（eval/click/snapshot）
5. 向用户反馈结果

1단계: 환경 확인

第1步：环境确认

bash
cd e2e && ./e2e.sh setup
setup
이 모든 환경(Chrome Beta, agent-browser, playwright-cli, CDP 연결)을 자동 체크/설치한다. CDP 미연결이면: 
./e2e.sh chrome
실행 요청.
bash
cd e2e && ./e2e.sh setup
setup
会自动检查/安装所有环境（Chrome Beta、agent-browser、playwright-cli、CDP连接）。 如果CDP未连接：请用户执行
./e2e.sh chrome
。

2단계: CDP 연결

第2步：CDP连接

bash
agent-browser connect 9222
1회 연결하면 세션 유지. 매 명령마다 재연결 불필요.
bash
agent-browser connect 9222
连接一次就会保持会话，无需每次执行命令都重新连接。

3단계: 탭 확인 → 사용자에게 선택 요청

第3步：确认标签页 → 请用户选择

bash
agent-browser tab list
탭 목록을 사용자에게 보여주고 "몇 번 탭에서 작업할까요?" 라고 확인한다. 출력 예:
  [0] Daum - https://www.daum.net/
  [1]  - chrome://webui-toolbar.top-chrome/
→ [2] NAVER - https://www.naver.com/
  [3] Google - https://www.google.com/
→
표시는 agent-browser 내부 포커스이지 Chrome UI 포커스가 아니다. CDP는 사용자가 Chrome에서 보고 있는 탭을 알 수 없다. 따라서 작업 시작 전 반드시 사용자에게 탭 번호를 확인해야 한다.
사용자가 탭 번호를 지정하면 
agent-browser tab N
으로 전환 후 진행한다.
bash
agent-browser tab list
向用户展示标签页列表，询问**「请问要在第几个标签页操作？」**。 输出示例：
  [0] Daum - https://www.daum.net/
  [1]  - chrome://webui-toolbar.top-chrome/
→ [2] NAVER - https://www.naver.com/
  [3] Google - https://www.google.com/
→
标记是agent-browser内部的焦点，不是Chrome UI的焦点。 CDP无法获知用户当前在Chrome中查看的标签页。 因此开始操作前必须向用户确认标签页编号。
用户指定标签页编号后，执行
agent-browser tab N
切换后再继续操作。

4단계: 조작

第4步：操作

선택된 탭에서 eval → 판단 → 추가 eval/click.
在选中的标签页中执行eval → 判断 → 追加执行eval/click操作。

5단계: 결과 보고

第5步：结果反馈

eval 결과, 페이지 상태를 텍스트로 요약하여 사용자에게 보고.
将eval结果、页面状态用文本总结后反馈给用户。

탭 규칙

标签页规则

현재 탭에서 작업. 탭 전환은 사용자 명시적 지시 시에만.
  • 사용자가 URL을 지정하면 → 현재 탭에서 
    agent-browser open "URL"
  • "N번 탭으로 가줘" → 
    agent-browser tab N
  • "새 탭으로 열어줘" → 
    agent-browser tab new "URL"
  • AI가 임의로 탭 전환/새 탭 열기 금지
open URL --new-tab
사용 금지! 기존 탭을 덮어쓴다. 새 탭은 반드시 
tab new "URL"
사용.
在当前标签页操作，仅当用户明确指示时才切换标签页。
  • 用户指定URL时 → 在当前标签页执行
    agent-browser open "URL"
  • 用户说「切换到第N个标签页」 → 执行
    agent-browser tab N
  • 用户说「在新标签页打开」 → 执行
    agent-browser tab new "URL"
  • 禁止AI擅自切换标签页/打开新标签页
禁止使用
open URL --new-tab
！ 会覆盖原有标签页。 打开新标签页必须使用
tab new "URL"
。

조작 명령

操作命令

페이지 이동

页面跳转

bash
agent-browser open "https://대상URL"
bash
agent-browser open "https://대상URL"

JavaScript 실행 (기본 조작 방법)

执行JavaScript（默认操作方式）

bash
undefined
bash
undefined

값 읽기

读取值

agent-browser eval "document.title" agent-browser eval "document.querySelector('#field').value" agent-browser eval "document.querySelectorAll('tr').length"
agent-browser eval "document.title" agent-browser eval "document.querySelector('#field').value" agent-browser eval "document.querySelectorAll('tr').length"

조건부 읽기

条件读取

agent-browser eval "document.querySelector('.cls') ? document.querySelector('.cls').innerText.trim() : '없음'"
agent-browser eval "document.querySelector('.cls') ? document.querySelector('.cls').innerText.trim() : '없음'"

목록 추출 (JSON.stringify 패턴)

提取列表（JSON.stringify模式）

agent-browser eval "JSON.stringify(Array.from(document.querySelectorAll('li')).map(function(el){return el.innerText}))"
agent-browser eval "JSON.stringify(Array.from(document.querySelectorAll('li')).map(function(el){return el.innerText}))"

클릭

点击

agent-browser eval "document.querySelector('a.link').click()"
agent-browser eval "document.querySelector('a.link').click()"

값 입력

输入值

agent-browser eval "document.querySelector('#keyword').value = '검색어'"

> **eval은 단순 표현식만.** IIFE `(function(){...})()` 사용 금지 -- 직렬화 오류 발생.
> 여러 동작은 각각 별도 eval로 나눠서 실행한다.
agent-browser eval "document.querySelector('#keyword').value = '검색어'"

> **eval仅支持简单表达式。** 禁止使用IIFE `(function(){...})()` -- 会出现序列化错误。
> 多个操作需要拆分为单独的eval分别执行。

요소 탐색 (snapshot -- 부득이할 때만)

元素查找（snapshot -- 仅必要时使用）

bash
undefined
bash
undefined

인터랙티브 요소만 + 컴팩트 출력 (필수 옵션)

仅提取可交互元素 + 紧凑输出（必选参数）

agent-browser snapshot -i -c
agent-browser snapshot -i -c

CSS 범위 제한 (더 절약)

限制CSS范围（更省Token）

agent-browser snapshot -i -c -s "table"

> **전체 snapshot 금지.** 토큰 비교:
> - 전체 snapshot: ~65,700 토큰
> - snapshot -i -c: ~9,800 토큰
> - eval: ~1~460 토큰

snapshot 후 ref로 조작:
```bash
agent-browser click e10
agent-browser fill e37 "검색어"
agent-browser press Enter
ref는 DOM 변경 시 무효. 클릭/이동 후 반드시 다시 snapshot.
agent-browser snapshot -i -c -s "table"

> **禁止全量snapshot。** Token消耗对比：
> - 全量snapshot：~65,700 Token
> - snapshot -i -c：~9,800 Token
> - eval：~1~460 Token

snapshot后通过ref操作：
```bash
agent-browser click e10
agent-browser fill e37 "검색어"
agent-browser press Enter
ref在DOM变更后会失效，点击/跳转后必须重新执行snapshot。

클릭 / 입력 / 키보드 (ref 기반)

点击/输入/键盘操作（基于ref）

bash
agent-browser click e10
agent-browser fill e37 "검색어"
agent-browser press Enter
bash
agent-browser click e10
agent-browser fill e37 "검색어"
agent-browser press Enter

스크린샷

截图

bash
agent-browser screenshot          # 터미널 출력
agent-browser screenshot result.png  # 파일 저장 (토큰 미소비)
bash
agent-browser screenshot          # 输出到终端
agent-browser screenshot result.png  # 保存为文件（不消耗Token）

fallback: playwright-cli (iframe/모달)

fallback: playwright-cli（iframe/模态框）

agent-browser가 지원하지 못하는 경우 playwright-cli로 전환한다.
agent-browser不支持的场景下切换到playwright-cli。

전환이 필요한 경우

需要切换的场景

  • iframe 내부 요소 접근 (jQuery UI Dialog + iframe 모달)
  • agent-browser snapshot에 iframe 태그만 보이고 내부가 비어있을 때
  • 访问iframe内部元素（jQuery UI Dialog + iframe模态框）
  • agent-browser的snapshot仅显示iframe标签，内部内容为空时

전환 방법

切换方法

bash
undefined
bash
undefined

playwright-cli 세션 오픈 (1회)

打开playwright-cli会话（执行一次即可）

./e2e/pwc.sh open
./e2e/pwc.sh open

탭 전환

切换标签页

./e2e/pwc.sh tab-select N
./e2e/pwc.sh tab-select N

iframe 내부 읽기

读取iframe内部内容

./e2e/pwc.sh eval "document.querySelector('iframe[src*=대상]').contentDocument.querySelector('#element').innerText"
./e2e/pwc.sh eval "document.querySelector('iframe[src*=대상]').contentDocument.querySelector('#element').innerText"

iframe 내부 입력 + 클릭 -- 별도 eval로 분리

iframe内部输入+点击 -- 拆分为单独eval执行

./e2e/pwc.sh eval "document.querySelector('iframe[src*=대상]').contentDocument.querySelector('#keyword').value = '검색어'" ./e2e/pwc.sh eval "document.querySelector('iframe[src*=대상]').contentDocument.querySelector('input[type=submit]').click()"

> 상세 패턴은 `references/iframe-모달-패턴.md` 참조
> playwright-cli 명령어는 `references/playwright-cli-명령어.md` 참조
./e2e/pwc.sh eval "document.querySelector('iframe[src*=대상]').contentDocument.querySelector('#keyword').value = '검색어'" ./e2e/pwc.sh eval "document.querySelector('iframe[src*=대상]').contentDocument.querySelector('input[type=submit]').click()"

> 详细模式参考`references/iframe-모달-패턴.md`
> playwright-cli命令参考`references/playwright-cli-명령어.md`

실측 비교 데이터

实测对比数据

동일 시나리오 (구글 → Gmail → 메일 15개 추출), Chrome Beta CDP 9222:
항목agent-browserplaywright-cli배율
eval 평균 속도189ms1,249ms6.6x
총 명령 시간1,521ms6,257ms4.1x
총 출력 바이트1,918B4,343B2.3x
eval 출력 형식결과값만결과+코드+탭목록+페이지정보-
相同场景（谷歌→Gmail→提取15封邮件），Chrome Beta CDP 9222环境下：
项目agent-browserplaywright-cli倍率
eval平均速度189ms1,249ms6.6x
总命令耗时1,521ms6,257ms4.1x
总输出字节1,918B4,343B2.3x
eval输出格式仅结果值结果+代码+标签页列表+页面信息-

핵심 규칙

核心规则

  1. eval 우선 -- 데이터 읽기, 클릭, 입력 모두 eval로 먼저 시도. snapshot은 셀렉터를 모를 때만.
  2. 작업 탭을 사용자에게 확인 -- CDP는 사용자의 포커스 탭을 알 수 없음. 
    tab list
    를 보여주고 탭 번호를 명시적으로 확인한다.
  3. 새 탭은 
    tab new URL
     -- 
    open URL --new-tab
    사용 금지 (기존 탭 덮어씀).
  4. snapshot은 
    -i -c
    필수     -- 전체 snapshot 금지. 토큰 폭발.
  5. eval은 단순 표현식만 -- IIFE 금지, 여러 동작은 별도 eval로 분리.
  6. ref는 매번 변경됨 -- DOM이 바뀌면 이전 ref 무효, 다시 snapshot.
  7. iframe → playwright-cli fallback -- agent-browser는 iframe 내부 접근 불가.
  8. connect 9222 필수 -- 모든 작업 전 CDP 연결 확인.
  1. 优先用eval -- 读取数据、点击、输入都先尝试用eval实现。仅当不知道选择器时才用snapshot。
  2. 向用户确认操作的标签页 -- CDP无法获知用户的焦点标签页，需展示
    tab list
    明确确认标签页编号。
  3. 打开新标签页用
    tab new URL
     -- 禁止使用
    open URL --new-tab
    （会覆盖原有标签页）。
  4. snapshot必须带
    -i -c
    参数     -- 禁止全量snapshot，会导致Token消耗暴增。
  5. eval仅支持简单表达式 -- 禁止使用IIFE，多个操作拆分为单独的eval执行。
  6. ref每次都会变更 -- DOM变更后之前的ref会失效，需要重新执行snapshot。
  7. iframe场景→切换到playwright-cli fallback -- agent-browser无法访问iframe内部。
  8. 必须执行connect 9222 -- 所有操作前确认CDP已连接。

참조 문서

参考文档

문서용도
references/agent-browser-명령어.md
agent-browser 전체 명령어 레퍼런스
references/playwright-cli-명령어.md
fallback 전용 (iframe 등 agent-browser 미지원 시)
references/iframe-모달-패턴.md
jQuery UI Dialog + iframe 모달 접근 패턴
文档用途
references/agent-browser-명령어.md
agent-browser全命令参考
references/playwright-cli-명령어.md
fallback专用（iframe等agent-browser不支持的场景）
references/iframe-모달-패턴.md
jQuery UI Dialog + iframe模态框访问模式