CUAWright와 Hermes 에이전트 스킬을 활용한 브라우저 및 데스크톱 작업 자동화

# CUAWright를 브라우저 자동화 하네스로 설정하기

## 1. 패키지 설치

```bash
npm install cuawright
# 또는
pip install cuawright
```

## 2. 백엔드 키 설정

OpenAI 또는 Anthropic 중 하나를 선택해 환경 변수로 설정합니다.

```bash
# OpenAI 사용 시
export OPENAI_API_KEY="sk-..."

# Anthropic 사용 시
export ANTHROPIC_API_KEY="sk-ant-..."
```

프로젝트 루트의 `.env` 파일에 저장하는 것을 권장하며, `.gitignore`에 반드시 추가하세요.

## 3. 스킬 폴더 등록

`skills/cuawright-web` 폴더를 에이전트 스킬로 등록합니다. 에이전트 설정 파일(예: `agent.config.json` 또는 `skills.json`)에 다음 항목을 추가하세요.

```json
{
  "skills": [
    {
      "name": "cuawright-web",
      "path": "skills/cuawright-web",
      "description": "Browser automation via CUAWright for web navigation, form filling, and screenshots"
    }
  ]
}
```

## 4. 스크립트 작성

`scripts/demo-login-form.ts` 파일을 생성합니다.

```typescript
import { cuawright } from "cuawright";
import { writeFileSync } from "fs";

interface RunOptions {
  date: string;          // 예: "2025-06-15"
  outputDir?: string;
}

export async function runDemoFlow({ date, outputDir = "artifacts" }: RunOptions) {
  const browser = await cuawright.launch({ headless: true });
  const page = await browser.newPage();

  try {
    // 1. 데모 사이트 로그인
    await page.goto("https://demo.example.com/login");
    await page.fill("#username", "demo_user");
    await page.fill("#password", "demo_pass");
    await page.click("button[type=submit]");
    await page.waitForSelector("#dashboard", { timeout: 15000 });

    // 2. 다중 필드 폼 작성 (파라미터화된 날짜 포함)
    await page.goto("https://demo.example.com/form");
    await page.fill("#firstName", "Jane");
    await page.fill("#lastName", "Doe");
    await page.fill("#email", "[email protected]");
    await page.fill("#startDate", date);
    await page.selectOption("#country", "KR");
    await page.click("#submitForm");

    // 3. 지연 로딩 콘텐츠 대기
    await page.waitForSelector(".lazy-content", { state: "visible", timeout: 20000 });

    // 4. 스크린샷 + JSON 결과 저장
    const screenshotPath = `${outputDir}/demo-${date}.png`;
    await page.screenshot({ path: screenshotPath, fullPage: true });

    const result = {
      date,
      screenshot: screenshotPath,
      url: page.url(),
      lazyContentLoaded: true,
      timestamp: new Date().toISOString(),
    };
    writeFileSync(`${outputDir}/demo-${date}.json`, JSON.stringify(result, null, 2));

    return result;
  } finally {
    await browser.close();
  }
}

// CLI 실행
if (require.main === module) {
  const date = process.argv[2] ?? new Date().toISOString().slice(0, 10);
  runDemoFlow({ date }).then((r) => console.log(JSON.stringify(r, null, 2)));
}
```

## 5. 실행 및 디버깅

```bash
mkdir -p artifacts
npx ts-node scripts/demo-login-form.ts 2025-06-15
```

실행 중 발생할 수 있는 일반적인 실패와 수정 방법:

- **셀렉터 실패**: `#dashboard`가 없으면 `page.waitForSelector`가 타임아웃됩니다. 실제 DOM을 확인해 `[data-testid=dashboard]` 같은 안정적인 셀렉터로 교체하세요.
- **타이밍 실패**: 지연 로딩 콘텐츠가 늦게 뜨면 `timeout`을 늘리거나 `page.waitForLoadState("networkidle")`를 먼저 호출하세요.
- **폼 제출 후 리다이렉트**: `page.click` 후 `page.waitForNavigation()`을 추가하세요.

수정 후 재실행하여 스크린샷과 JSON이 `artifacts/`에 생성되는지 확인합니다.

## 6. 재사용 가능한 스킬로 정리

`skills/cuawright-web/` 아래에 파라미터화된 스킬을 배치합니다.

```
skills/cuawright-web/
├── SKILL.md
├── run.ts
└── README.md
```

`run.ts`는 위 스크립트에서 `date`, `outputDir`, `headless`를 인자로 받도록 일반화한 버전입니다.

`README.md`:

```markdown
# cuawright-web 스킬

데모 사이트 로그인 → 다중 필드 폼 작성 → 지연 로딩 대기 → 스크린샷/JSON 저장을 수행하는 재사용 스킬입니다.

## 모델 없이 재실행하기

스킬은 결정론적 스크립트이므로 LLM 호출 없이 실행됩니다.

```bash
npx ts-node skills/cuawright-web/run.ts --date 2025-06-15 --out artifacts
```

### 인자
- `--date` (필수): 폼에 입력할 날짜 (YYYY-MM-DD)
- `--out` (선택): 결과 저장 디렉토리, 기본값 `artifacts`
- `--headless` (선택): 기본값 `true`, 디버깅 시 `false`

### 출력
- `artifacts/demo-<date>.png` — 전체 페이지 스크린샷
- `artifacts/demo-<date>.json` — 실행 결과 메타데이터

### 에이전트에서 호출
에이전트는 `skills/cuawright-web/SKILL.md`의 스키마에 따라 `run.ts`를 서브프로세스로 호출하기만 하면 됩니다. 모델 추론 없이 동일한 결과를 재현할 수 있습니다.
```

`SKILL.md`에는 입력 스키마(`date`, `out`, `headless`)와 출력 파일 경로, 실패 시 재시도 정책을 명시해 에이전트가 스킬을 결정론적으로 호출할 수 있도록 합니다.