Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,16 @@
"name": "hermes",
"source": "./hermes-gateway-plugin",
"description": "Interact with Hermes Agent via local or SSH-tunneled connection"
},
{
"name": "split-work-plugin",
"source": "./split-work-plugin",
"description": "Split current project work into parallel-safe task groups with worktree branch names and structured starting prompts"
},
{
"name": "browser-walkthrough-plugin",
"source": "./browser-walkthrough-plugin",
"description": "Headed browser walkthrough — step-by-step interactive flow for iframe/security-heavy sites. Requires playwright-cli skill"
}
]
}
8 changes: 8 additions & 0 deletions browser-walkthrough-plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"name": "browser-walkthrough-plugin",
"description": "Headed browser walkthrough — step-by-step interactive flow with the user. Pairs with playwright-cli skill for iframe-heavy/security-program-heavy sites (홈택스, 정부24, banking).",
"version": "1.0.0",
"author": {
"name": "Stefan Cho"
}
}
39 changes: 39 additions & 0 deletions browser-walkthrough-plugin/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# browser-walkthrough-plugin

playwright-cli **headed 모드**로 브라우저를 같이 보면서 한 스텝씩 대화형으로 진행하는 워크플로우. 홈택스·정부24·은행·쇼핑몰처럼 iframe·보안프로그램·팝업이 많은 사이트를 사용자와 함께 진행할 때 사용.

## 전제 조건 (사전 설치 필요)

이 플러그인은 별도 `playwright-cli` 스킬에 의존한다. 본 플러그인에 묶지 않은 이유: playwright-cli는 외부에서 활발히 갱신되고 다른 플러그인(impeccable, frontend-design 등)도 동일 스킬을 가져오므로, 묶으면 본가 업데이트가 끊긴다.

설치 옵션:
- 가장 간단: 외부 플러그인(예: `frontend-design`, `impeccable`) 설치 시 `playwright-cli` 스킬이 함께 따라옴
- 또는 user-level에 직접 두기: `~/.claude/skills/playwright-cli/`

`playwright-cli`가 사용 가능한 상태인지 먼저 확인 후 본 플러그인을 사용하라.

## 사용법

자연어 트리거:
- "브라우저 보면서 같이 진행"
- "홈택스 같이 / 정부24 같이"
- "step-by-step browser" / "한 스텝씩"

## 대화 프로토콜 (요약)

| 입력 | 행동 |
|---|---|
| `다음`, `next`, `진행`, `ok` | 직전 제안 액션 실행 → snapshot → 다음 스텝 |
| `뒤로` | go-back |
| `잠깐`, `wait` | 액션 금지, 대기 (사용자 수동 조작 중) |
| 구체적 값 | 직전 필드에 fill |
| 질문 | 답변만 하고 대기 |
| `ok 제출`, `결제 진행` | 위험 액션 게이트 통과 |
| `완료`, `끝` | 후속 액션 아이템 요약 |

## Install

```bash
/plugin marketplace add devstefancho/claude-plugins
/plugin install browser-walkthrough-plugin@devstefancho-claude-plugins
```
219 changes: 219 additions & 0 deletions browser-walkthrough-plugin/skills/browser-walkthrough/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,219 @@
---
name: browser-walkthrough
description: playwright-cli headed 모드로 브라우저를 같이 보면서 한 스텝씩 대화형으로 진행하는 워크플로우. 사용자가 "다음"이라고 하면 다음 스텝 실행, 질문하면 답만 하고 대기, 최종 제출 같은 위험 액션은 명시적 키워드 필요. 홈택스·정부24·은행·쇼핑몰처럼 iframe·보안프로그램·팝업이 많은 사이트를 사용자와 함께 진행할 때 사용. Trigger: "브라우저 보면서 같이 진행", "headed 모드로 같이", "단계별로 진행해줘", "홈택스 같이", "정부24 같이", "step-by-step browser", "walkthrough 모드", "한 스텝씩", "한 단계씩 진행".
allowed-tools: Bash
---

# Browser Walkthrough (headed 모드 대화형 진행)

사용자가 열어둔 headed 브라우저에 **attach**해서 같은 화면을 보며 한 스텝씩 진행한다.
명령어 전체 레퍼런스는 `playwright-cli` skill 참조. 이 skill의 핵심은 **대화 프로토콜**이다.

> **사전 조건**: `playwright-cli` 스킬이 사용 가능해야 한다 (외부 플러그인 또는 user-level 설치). 본 플러그인은 의존만 표시하고 묶지 않는다 — 본가 업데이트가 끊기지 않게 하려는 의도. 자세한 내용은 README 참조.

## 사용자 응답 해석 (최우선)

| 입력 | 행동 |
|---|---|
| `다음` / `next` / `진행` / `ok` / `응` | 직전에 제안한 액션 실행 → snapshot → 다음 스텝 요약·대기 |
| `뒤로` | `go-back` |
| `스킵` / `건너뛰기` | 현재 스텝 건너뛰고 다음 |
| `잠깐` / `멈춰` / `wait` / `대기` | 아무 액션도 하지 말고 대기. 사용자가 수동 조작 중 (인증서 비번, 보안프로그램 설치, 텍스트 마스킹 등) |
| 구체적 값 (`스테판초 랩스`, `010-...`, `10`) | 직전에 물어본 필드에 `fill` |
| 질문 (`이거 뭐임?`, `~~는 뭐가 유리?`) | **액션 금지.** 답변만 하고 다시 대기 |
| `ok 제출` / `결제 진행` / `최종 확인` | 위험 액션 실행 (아래 "위험 액션 게이트") |
| `완료` / `끝` | 후속 액션 아이템 요약 (기한·체크리스트) |

## Step Loop

매 스텝 반복:

1. `playwright-cli -s=<name> snapshot` — 현재 화면의 DOM(yaml, ref 포함) 확보
2. 2-5줄 요약 — 무슨 페이지이고 어떤 선택지·필드가 있는지
3. 다음 액션 제안 or 필요한 입력값 질문
4. 사용자 응답 대기 → 위 표대로 해석

snapshot이 비거나 ref가 안 잡히면 iframe 가능성 → `references/iframe-handling.md` 참고.

## Bootstrap

```bash
# 기존 세션 확인
playwright-cli list

# 없으면 headed 크롬으로 새 세션 (세션 이름은 도메인 기반)
playwright-cli -s=<name> open <url> --browser=chrome --persistent --headed

# 이미 열린 브라우저가 attach 가능하면
playwright-cli -s=<name> attach
```

세션 이름은 작업 도메인 (`hometax`, `gov24`, `coupang`). 이후 **모든 명령에 `-s=<name>` 필수.**

## 위험 액션 게이트 (필수)

최종 제출, 결제, 삭제, 취소 등 **되돌릴 수 없는 액션**은 `다음`만으로 실행하지 않는다.

실행 전에:
1. **체크포인트 요약 표**로 지금까지 입력한 핵심 값 재표시 (금액·날짜·상호·접수번호 등)
2. `ok 제출`, `결제 진행`, `최종 확인` 중 어떤 키워드가 필요한지 명시
3. 사용자가 그 키워드를 말할 때까지 대기

## 중간 체크포인트

긴 폼(5-6단계 이상)에서는 페이지 전환 직전에 지금까지 채운 값을 짧은 표로 재요약해 스텝 드리프트 방지.

## 민감값 처리

- 사용자가 브라우저 확장으로 주민번호·계좌·비번 등을 **마스킹 중**일 수 있다. screenshot에 마스킹된 모습이 보여도 헷갈리지 말 것.
- 주민번호·인증서 비밀번호·계좌번호·카드번호는 **응답에 그대로 에코 금지.**
- 인증서 비번 입력 같은 단계는 사용자가 직접 하도록 요청하고 `잠깐` 대기.

## 한국 사이트 특이사항

- 홈택스·금융사: iframe 안에 실제 컨텐츠 → `references/iframe-handling.md`
- IPINSIDE / Veraport / MagicLine: 보안프로그램 설치 게이트. playwright에서 우회 불가, 사용자 수동 설치 후 새로고침
- 다운로드: playwright가 `/private/var/folders/**/playwright-artifacts-*/`로 가로챔. 필요시 `cp`로 `~/Downloads`에 복사 → `references/downloads.md`
- 공동인증서 팝업: 사용자가 직접 비번 입력. Claude는 `잠깐` 모드

## 안내(Guide) 모드 — 사용자가 직접 클릭하게 하기

기본은 Claude가 `click`/`fill`한다. 다만 다음 상황에선 **대상을 강조만 하고 사용자가 직접 조작**하는 게 낫다:

- **인증/민감정보 입력**: 카드번호, 주민번호, OTP 등 — Claude가 값을 몰라야 안전
- **학습 목적**: 사용자가 다음부터 혼자 할 수 있도록 경로를 체감시켜야 할 때
- **최종 제출·결제 버튼**: 위험 액션 게이트와 결합. highlight로 강조 → 사용자가 `ok 제출` 키워드 말하면 Claude가 click

### 사용법

```bash
scripts/guide-launcher.sh <mode> "<title>" "<ref|heading|desc>" [more...]
```

**모드**:
- `seq` — 순차 스텝, 스텝별 다른 색상 (핑크/보라/청록/주황/파랑/빨강/민트/자주 순환)
- `opt` — 택1 옵션, 주황색 + 알파벳 라벨 (A/B/C)
- `one` — 단일 타겟, 핑크 + 👉

**Spec 포맷**: `ref|heading|desc` (heading/desc 생략 가능, desc 안의 `\n`은 줄바꿈)

**환경변수**: `CC_HL_SESSION` (기본값 `hometax`) — 다른 playwright-cli 세션이면 지정
```bash
CC_HL_SESSION=gov24 scripts/guide-launcher.sh seq "..." "..."
```

### 렌더 구성

- 각 대상 요소에 색상 outline + 좌상단 번호/알파벳 배지 (스크롤·resize·DOM 변경 자동 추적)
- **우측 상단 고정 사이드 패널**에 헤딩·설명 리스트
- 패널 항목 클릭 → 해당 요소로 scrollIntoView + 3회 깜빡임
- 패널 "×" 닫기 → 전체 outline·배지·패널 제거

### 예시

```bash
scripts/guide-launcher.sh seq "카드 등록 4단계" \
"e1033|카드사 선택|드롭다운에서 본인 카드사" \
"e1035|카드번호 16자리|4자리씩 4칸" \
"e1067|휴대전화|가운데·뒤 4자리" \
"e1082|등록접수하기|⚠ 누르기 전 확인"
```

### 판단 기준 — Claude 직접 click vs highlight 가이드

| 상황 | 권장 방식 |
|---|---|
| 단순 폼 (제목·내용·날짜 등 비민감) | Claude `fill` |
| 민감값 (아이디/비번, 카드번호, 전화번호) | `highlight` → 사용자 직접 |
| 체크박스·라디오 선택 | Claude `click` (확인 후) |
| 최종 제출·결제·삭제 | `highlight` → `ok 제출`에 Claude가 최종 click |
| 인증서 로그인·OTP | 기본 대기 (`잠깐`) |

## Dialog / Tab

```bash
playwright-cli -s=<name> dialog-accept
playwright-cli -s=<name> dialog-dismiss
playwright-cli -s=<name> tab-list
playwright-cli -s=<name> tab-select 2
```
snapshot에 `dialog` 키워드 있으면 먼저 accept/dismiss. 팝업이 떴으면 tab-list부터.

## 폼 일괄 입력

여러 필드 확정되면 한 번에:
```bash
playwright-cli -s=<name> fill e133 "0" && \
playwright-cli -s=<name> fill e138 "10" && \
playwright-cli -s=<name> click e174
```

## 스크린샷 해상도 (중요)

Claude vision encoder는 긴 변 **1568px**까지만 손실 없이 처리한다 (그 이상은 자동 다운스케일되어 픽셀 낭비 + 응답 지연). 토큰 ≈ (w×h)/750.

**원칙**: screenshot 찍고 바로 `sips`로 리사이즈한 뒤 Read.

```bash
# 1. 스크린샷
playwright-cli -s=<name> screenshot --filename=step.png
# 2. 긴 변 1568px로 다운스케일 (원본보다 작으면 그대로 둠)
sips -Z 1568 .playwright-cli/step.png --out .playwright-cli/step-small.png
# 3. Read로 확인
```

한 줄 체이닝:
```bash
playwright-cli -s=<name> screenshot --filename=s.png && sips -Z 1568 .playwright-cli/s.png --out .playwright-cli/s-small.png >/dev/null
```

예외: 폰트 작거나 PDF 페이지 읽기 등 **해상도 낮아 못 읽을 때만** 1568 상향(2000~2500). 대부분 1568로 충분.

snapshot(yaml)은 토큰 기준이라 해상도 무관 — 가능하면 screenshot보다 snapshot 먼저.

## PDF 뷰어

playwright로 페이지 넘기기 어려움 → 사용자에게 "n페이지로 넘겨줘" 요청 → `screenshot` 으로 읽음 (위 리사이즈 적용).

## 세션 종료

```bash
playwright-cli -s=<name> close # 창만 닫기
playwright-cli -s=<name> delete-data # 퍼시스턴트 프로필까지 삭제
```

사용자가 `완료`라고 하면 후속 액션 아이템을 **기한 포함 체크리스트**로 요약. (세션에서 효과적이었던 패턴)

## 예시 흐름

```
User: 홈택스 개인사업자등록 같이 진행해줘
Claude: playwright-cli -s=hometax list → snapshot → "로그인 페이지. 로그인해달라" → 대기

User: 로그인했음
Claude: snapshot → "메인 진입. '증명·등록·신청' hover 하면 서브메뉴 열림. 진행?" → 대기

User: 다음
Claude: hover → snapshot → "서브메뉴 열림. '개인 사업자등록 신청' 4가지 중 어떤 거?" → 대기

User: 기본
Claude: click → dialog-accept (보안 alert) → snapshot → "상호 입력 필드. 뭐로?" → 대기

User: 스테판초 랩스
Claude: fill → snapshot → 다음 필드 ...

... (여러 스텝 후)

Claude: "최종 제출 직전. [체크포인트 표]. 'ok 제출' 답하면 접수."

User: ok 제출
Claude: click → "접수 완료 (번호: ...)"

User: 완료
Claude: "[후속 체크리스트: 4/21 건보 확인, 4/22 등록증 출력, ...]"
```

## 참고 문서

- `references/iframe-handling.md` — iframe 안 요소 찾기/클릭 패턴
- `references/downloads.md` — playwright 다운로드 가로채기 대응
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# 다운로드 처리

playwright headed 모드에서 브라우저가 파일을 다운로드하면, playwright가 이를 **임시폴더에 UUID 이름으로** 저장한다 (Chrome이 `~/Downloads`로 저장하는 게 아니다).

## 위치 찾기

```bash
ls -la /private/var/folders/**/playwright-artifacts-*/ 2>/dev/null
# 또는 최근 10분내 생성된 파일
find ~/Library/Caches/ms-playwright /private/var/folders -type f -mmin -10 2>/dev/null | head -20
```

파일은 확장자 없이 UUID 형식으로 저장된다.

## 파일 타입 확인

```bash
file /private/var/folders/.../playwright-artifacts-.../UUID
# 예: xar archive → .pkg
# 예: PDF document, version 1.4 → .pdf
# 예: Zip archive → .zip
```

## Downloads로 복사 + rename

```bash
cp /private/var/folders/.../playwright-artifacts-.../<UUID> ~/Downloads/<의미있는이름>.<확장자>
```

## Chrome 내부 다운로드 목록 조회

`chrome://downloads/` 탭을 열어 shadow DOM으로 조회:

```bash
playwright-cli -s=<name> tab-new chrome://downloads/
playwright-cli -s=<name> eval "(() => {
const m = document.querySelector('downloads-manager');
const items = m?.shadowRoot?.querySelectorAll('downloads-item');
if (!items) return 'no items';
return Array.from(items).slice(0, 5).map(it => {
const s = it.shadowRoot;
return {
name: s?.querySelector('#name')?.textContent?.trim(),
url: s?.querySelector('#url')?.href,
status: s?.querySelector('.description')?.textContent?.trim()
};
});
})()"
```

원래 탭으로 복귀:
```bash
playwright-cli -s=<name> tab-select 0
```

## macOS 설치 패키지(.pkg)

사용자 동의 없이 `installer` / `open` 으로 자동 실행하지 않는다. 복사 후 Finder에서 더블클릭하도록 안내:

> "`~/Downloads/파일명.pkg` 를 Finder에서 더블클릭 → macOS Installer 마법사 따라가기. 설치 완료 후 Chrome 탭에서 Cmd+R 새로고침하고 알려줘."
Loading
Loading