Spectature/dev-browser-local-profile-skill

Dev Browser Local Profile

이 스킬은 브라우저 자동화가 새로운 브라우저 상태를 시작하는 대신 장기 실행되는 로컬 브라우저 프로필에 연결해야 할 때 사용하세요.

이 프로젝트는 dev-browser에서 가져와 수정되었지만, 현재 스킬은 독립적으로 실행되며 dev-browser가 필요하지 않습니다.

핵심 규칙

• dev-browser 대신 번들된 Playwright-over-CDP 스크립트를 사용하세요.
• 지속적인 브라우저 프로필이 로그인 상태의 진실 공급원(source of truth)이라고 가정합니다.
• 고정된 원격 디버깅 포트를 선호합니다. 사용자가 다른 값을 지정하지 않는 한 기본값은 9222입니다.
• 프로필 경로는 사용자 상대 경로로 유지하세요. 시스템별 사용자 이름을 하드코딩하지 마십시오.
• 요청이 없는 한 사용자의 현재 탭을 대체하지 말고 기본적으로 새 탭을 여세요.

설정 워크플로우

1. 종속성 설치

스킬 디렉토리 내에서 한 번 실행하세요:

npm install

이 명령은 playwright-core만 설치합니다. 별도의 관리형 브라우저를 다운로드하지 않습니다.

2. 지속적인 프로필로 Chrome 또는 Chromium 시작

현재 사용자의 홈 디렉토리 아래에 고정된 사용자 데이터 디렉토리를 사용하세요:

• Windows: Join-Path $env:USERPROFILE 'chrome-dev-browser-profile'
• macOS/Linux: ~/chrome-dev-browser-profile

크로스 플랫폼 시작을 위해 번들된 런처 스크립트를 사용하세요:

python scripts/start_chrome_debug.py

유용한 옵션:

python scripts/start_chrome_debug.py --port 9222
python scripts/start_chrome_debug.py --profile-dir "C:\Users\name\chrome-dev-browser-profile"
python scripts/start_chrome_debug.py --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

3. 독립형 브라우저 도구 사용

새 탭에서 URL 열기:

node scripts/browser_tools.mjs open --url "http://localhost:9800/h5-bzzx/"

현재 탭 목록 보기:

node scripts/browser_tools.mjs list

스크린샷 촬영:

node scripts/browser_tools.mjs screenshot --url "http://localhost:9800/h5-bzzx/" --output "./page.png"

4. 사용자 정의 자동화 작업 실행

단순한 열기/목록/스크린샷 흐름보다 더 복잡한 작업을 위해 일반 작업 실행기를 사용하세요:

node scripts/run_task.mjs --task ./my-task.mjs --url "http://localhost:9800/h5-bzzx/" --task-arg mode=debug

작업 모듈은 기본 async 함수 또는 run이라는 이름의 함수를 내보내야 합니다.

예시:

export default async function ({ page, helpers, taskArgs }) {
  await page.waitForLoadState("domcontentloaded");
  return {
    title: await page.title(),
    url: page.url(),
    taskArgs
  };
}

해시 라우트 처리

해시 라우트 URL의 경우 json/new?... 등과 같은 직접 DevTools 열기 흐름에 의존하지 마세요. #... 부분이 생략될 수 있습니다.

해시 라우트의 경우 번들된 스크립트는 이미 2단계 탐색 전략을 사용합니다:

1. 먼저 기본 URL을 엽니다.
2. 그런 다음 페이지 내에서 window.location.href를 설정합니다.

예시:

node scripts/browser_tools.mjs open --url "http://localhost:9527/#/inspection/log/list?book_id=352"

확인 체크리스트

페이지를 연 후 성공을 명시적으로 확인하세요:

• JSON 출력 url이 예상 경로와 일치하는지 확인합니다.
• 페이지에 동적 제목이 있는 경우 title 또는 알려진 선택자를 확인합니다.
• 작업이 조용히 실패한 것처럼 보이면 재시도 전에 node scripts/browser_tools.mjs list를 실행합니다.
• 로그인이 누락된 경우 Chrome이 임시 프로필이 아닌 지속적인 프로필로 시작되었는지 확인합니다.

실패 모드

브라우저 도구가 연결할 수 없음

가능한 원인: Chrome이 --remote-debugging-port=<port>로 실행되지 않았습니다.

해결 방법:

• python scripts/start_chrome_debug.py로 Chrome을 다시 시작합니다.
• 포트가 스크립트에 전달된 포트와 일치하는지 확인합니다.

새 탭이 열렸지만 경로가 잘못됨

가능한 원인: 외부 도구에서 해시 라우트가 잘리거나 수동으로 단축된 URL입니다.

해결 방법:

• 번들된 열기 명령을 사용합니다.
• 전체 해시 라우트 URL을 전달합니다.

로그인 상태가 없음

가능한 원인: Chrome이 다른 프로필 디렉토리로 시작되었습니다.

해결 방법:

• 지속적인 --user-data-dir로 Chrome을 다시 시작합니다.
• 동일한 프로필 디렉토리를 일관되게 재사용합니다.

범위

이 스킬은 의도적으로 워크플로우에 초점을 맞춥니다. CDP를 통한 Playwright를 사용하여 지속적인 로컬 로그인 상태를 위한 독립형 브라우저 자동화 설정을 표준화합니다.