screenagent-ai 0.3.0__tar.gz

screenagent_ai-0.3.0/.claude/agents/demo-debugger.md

@@ -0,0 +1,106 @@
+---
+name: demo-debugger
+description: screenagent 데모 실행 중 발생한 에러를 분석하고 코드를 수정한다. 에러 로그, 스크린샷, 코드를 종합 분석하여 버그를 찾고 수정.
+model: inherit
+---
+
+# demo-debugger Subagent
+
+screenagent 데모 실행 중 발생한 에러를 분석하고 수정하는 디버깅 전문 에이전트.
+
+## Role
+
+데모 실행 중 문제가 발생했을 때, 다음을 종합 분석하여 버그를 찾고 수정한다:
+- 에러 로그 (stderr)
+- 스크린샷 (현재 화면 상태)
+- 소스코드 (관련 모듈)
+
+## Procedure
+
+### 1. 에러 정보 수집
+
+호출 시 전달받는 정보:
+- `error_log`: stderr 로그 내용 또는 로그 파일 경로
+- `screenshot_path`: 에러 발생 시점의 스크린샷 (선택)
+- `instruction`: 실행하려던 시나리오
+- `error_message`: 에러 메시지 요약
+
+### 2. 로그 분석
+
+에러 로그에서 다음을 추출한다:
+- Python traceback (파일명, 줄 번호, 함수명)
+- 마지막으로 성공한 step
+- 실패한 tool_call과 인자
+- 외부 서비스 에러 (CDP, Anthropic API 등)
+
+### 3. 소스코드 탐색
+
+에러와 관련된 소스 파일을 읽는다. 주요 파일 위치:
+
+```
+src/screenagent/
+├── agent/
+│   ├── loop.py          # 에이전트 메인 루프 (좌표 파싱, 스텝 실행)
+│   └── tools.py         # 도구 스키마 정의
+├── perception/
+│   ├── screenshot.py    # 스크린샷 캡처 + 리사이즈
+│   ├── ax.py            # 접근성 트리
+│   ├── cdp.py           # Chrome DevTools Protocol
+│   └── composite.py     # 통합 perceiver
+├── action/
+│   └── cgevent.py       # 마우스/키보드 제어
+├── cli.py               # CLI 진입점
+├── config.py            # 설정 로딩
+└── types.py             # 타입 정의
+```
+
+### 4. 원인 분석
+
+일반적인 에러 패턴:
+
+| 에러 패턴 | 원인 | 수정 위치 |
+|-----------|------|-----------|
+| `KeyError: 'x'` or coordinate parsing failure | LLM이 예상 외 좌표 형식 반환 | `loop.py` - `_parse_coord` |
+| `ConnectionRefusedError` on CDP | Chrome CDP 미연결 | `cdp.py` - retry/fallback |
+| `_downscale_png` TypeError | 스크린샷 바이트 처리 에러 | `screenshot.py` - `_downscale_png` |
+| `anthropic.APIError` | API 키 문제 또는 rate limit | `config.py` 또는 사용자 설정 |
+| `PermissionError` on AX | 접근성 권한 없음 | 사용자에게 권한 설정 안내 |
+| `timeout` on tool execution | 동작이 너무 오래 걸림 | 해당 tool의 timeout 조정 |
+
+### 5. 수정 제안/적용
+
+분석 결과에 따라:
+
+1. **코드 버그**: 직접 수정하고 변경 내용을 설명한다
+2. **설정 문제**: 올바른 설정 방법을 안내한다
+3. **환경 문제**: (접근성 권한, Chrome 설정 등) 해결 단계를 안내한다
+4. **LLM 응답 문제**: 시스템 프롬프트 개선을 제안한다
+
+### 6. 수정 검증
+
+코드를 수정한 경우:
+
+```bash
+# 단위 테스트 실행
+python -m pytest tests/ -x -q
+
+# 수정된 기능만 빠르게 확인
+screenagent run "test" --dry-run --output json
+```
+
+### 7. 결과 보고
+
+```
+## Debug Report
+
+**에러**: <에러 요약>
+**원인**: <근본 원인>
+**수정**: <수정 내용 또는 안내>
+
+### 변경된 파일
+- `src/screenagent/agent/loop.py:42` — 좌표 파싱 로직 수정
+
+### 검증
+- 테스트: ✅ 통과
+- dry-run: ✅ 정상
+```

screenagent_ai-0.3.0/.claude/skills/add-tool/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: add-tool
+description: screenagent에 새로운 tool을 추가한다. 스키마 정의, dispatch 구현, CLI 연동, 테스트까지 한번에 처리.
+argument-hint: <tool-name> <description>
+disable-model-invocation: true
+---
+
+# /add-tool Skill
+
+screenagent 에이전트에 새 tool을 추가하는 전체 과정을 자동화한다.
+
+## Arguments
+
+- `tool-name`: 추가할 도구 이름 (snake_case, 예: `wait_for_element`, `extract_text`)
+- `description`: 도구 설명
+
+## 수정 대상 파일
+
+새 tool을 추가하려면 반드시 다음 파일들을 수정해야 한다:
+
+1. **`src/screenagent/agent/tools.py`** — 도구 스키마 정의 (TOOLS 리스트에 추가)
+2. **`src/screenagent/agent/loop.py`** — `_dispatch_tool()` 메서드에 핸들러 추가
+3. **`src/screenagent/cli.py`** — (선택) CLI 서브커맨드로도 노출할 경우
+4. **`tests/test_cli.py`** — 테스트 추가
+
+## Procedure
+
+### Step 1: 기존 도구 패턴 파악
+
+먼저 현재 도구 목록을 확인한다:
+
+```bash
+.venv/bin/screenagent --output json schema | python3 -c "
+import sys, json
+tools = json.load(sys.stdin)['tools']
+for t in tools:
+    print(f\"  {t['name']}: {t['description'][:60]}\")
+"
+```
+
+### Step 2: 스키마 정의
+
+`src/screenagent/agent/tools.py`의 TOOLS 리스트에 새 도구 스키마를 추가한다.
+
+기존 패턴을 따라:
+```python
+{
+    "name": "<tool-name>",
+    "description": "<description>",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            # ... 파라미터 정의
+        },
+        "required": [...]
+    }
+}
+```
+
+### Step 3: dispatch 구현
+
+`src/screenagent/agent/loop.py`의 `_dispatch_tool()` 메서드에 elif 블록을 추가한다.
+
+패턴:
+```python
+elif name == "<tool-name>":
+    # 구현
+    return ToolResult(output="...", screenshot_png=png)
+```
+
+도구 유형별 구현 가이드:
+- **인식(perception) 도구**: `self._perceiver`를 통해 정보 수집 → ToolResult(output=...)
+- **행동(action) 도구**: `self._actor` 또는 `self._cdp_actor`를 통해 실행 → 후속 screenshot
+- **CDP 전용 도구**: `await self._get_cdp_actor()`로 CDP 사용 가능 여부 먼저 확인
+- **순수 정보 도구**: 외부 상태 변경 없이 정보만 반환
+
+### Step 4: 시스템 프롬프트 업데이트
+
+새 도구의 사용법이 비직관적이면 `loop.py`의 `SYSTEM_PROMPT`에 가이드를 추가한다.
+
+### Step 5: CLI 서브커맨드 (선택)
+
+사용자가 CLI에서 직접 호출할 수 있게 하려면 `cli.py`에:
+1. `cmd_<tool_name>` 함수 추가
+2. `build_parser()`에 서브커맨드 추가
+3. `dispatch` 딕셔너리에 등록
+
+### Step 6: 테스트
+
+```bash
+# 스키마 확인
+.venv/bin/screenagent --output json schema | python3 -c "
+import sys, json
+tools = json.load(sys.stdin)['tools']
+names = [t['name'] for t in tools]
+assert '<tool-name>' in names, f'Tool not found! Got: {names}'
+print('Schema OK')
+"
+
+# 기존 테스트 통과 확인
+.venv/bin/python -m pytest tests/ -x -q
+```
+
+### Step 7: 결과 리포트
+
+```
+## Tool Added: <tool-name>
+
+**설명**: <description>
+**파라미터**: <params>
+
+### 수정된 파일
+- `tools.py` — 스키마 추가
+- `loop.py` — dispatch 핸들러 추가
+- `cli.py` — (선택) 서브커맨드 추가
+
+### 테스트
+- 스키마: ✅
+- 기존 테스트: ✅
+```

screenagent_ai-0.3.0/.claude/skills/demo/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: demo
+description: screenagent 데모 시나리오를 실행하고 결과를 검증한다. Chrome 상태 확인, 에이전트 실행, 스크린샷 캡처, 결과 리포트까지 한번에 처리.
+argument-hint: [scenario-description] [--model sonnet|haiku] [--max-steps N]
+disable-model-invocation: true
+---
+
+# /demo Skill
+
+screenagent 데모 시나리오를 한 커맨드로 실행하고 결과를 검증한다.
+
+## Arguments
+
+- 첫 번째 인자: 시나리오 설명 (예: "youtube.com에서 lofi 검색")
+- `--model sonnet|haiku`: 사용할 모델 (기본: haiku)
+- `--max-steps N`: 최대 스텝 수 (기본: 10)
+
+## Procedure
+
+### Step 1: Chrome 상태 확인
+
+```bash
+screenagent check --output json
+```
+
+- JSON 결과의 `ok` 필드를 확인한다.
+- `ok: false`이면 사용자에게 Chrome 디버그 모드 실행을 안내하고 중단한다:
+  ```
+  Chrome CDP 연결 실패. 다음 명령어로 Chrome을 실행해주세요:
+  /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile
+  ```
+
+### Step 2: Chrome 초기화
+
+CDP로 모든 탭을 닫고 about:blank 상태로 만든다:
+
+```bash
+# 현재 열린 탭 목록 확인
+curl -s http://localhost:9222/json | python3 -c "
+import sys, json
+targets = json.load(sys.stdin)
+pages = [t for t in targets if t.get('type') == 'page']
+print(f'{len(pages)} tab(s) open')
+for p in pages:
+    print(f'  - {p.get(\"title\", \"untitled\")}: {p.get(\"url\", \"\")}')
+"
+```
+
+열린 탭이 있으면 about:blank로 이동시킨다:
+
+```bash
+# 첫 번째 탭의 websocket URL을 가져와서 about:blank으로 navigate
+curl -s http://localhost:9222/json | python3 -c "
+import sys, json
+targets = json.load(sys.stdin)
+pages = [t for t in targets if t.get('type') == 'page']
+if pages:
+    # 첫 번째 탭만 남기고 나머지는 닫기
+    for p in pages[1:]:
+        import urllib.request
+        urllib.request.urlopen(f'http://localhost:9222/json/close/{p[\"id\"]}', timeout=5)
+    # 첫 번째 탭을 about:blank으로
+    print(f'Reset to 1 tab: {pages[0][\"id\"]}')
+"
+```
+
+### Step 3: 시나리오에서 모델과 max-steps 파싱
+
+인자에서 `--model`과 `--max-steps` 값을 파싱한다.
+
+- `--model sonnet` → `--model claude-sonnet-4-6`
+- `--model haiku` → `--model claude-haiku-4-5-20251001` (기본값)
+- `--max-steps N` → `--max-steps N` (기본값: 10)
+
+나머지 텍스트가 시나리오 instruction이 된다.
+
+### Step 4: screenagent 실행
+
+```bash
+screenagent run "<instruction>" --max-steps <N> --model <model> --output json 2>demo_stderr.log
+```
+
+- stderr 로그를 `demo_stderr.log`에 저장한다.
+- 실행이 끝나면 stdout의 JSON 결과를 파싱한다.
+
+### Step 5: 결과 스크린샷 캡처
+
+```bash
+screenagent screenshot --file demo_result.png --output json
+```
+
+- 캡처된 스크린샷을 Read 도구로 확인하여 사용자에게 보여준다.
+
+### Step 6: 결과 리포트
+
+다음 형식으로 결과를 정리한다:
+
+```
+## Demo Result
+
+**시나리오**: <instruction>
+**모델**: <model>
+**스텝**: <사용된 스텝> / <max-steps>
+**결과**: ✅ 성공 / ❌ 실패
+
+### 에이전트 응답
+<result summary>
+
+### 스크린샷
+[demo_result.png 표시]
+
+### 로그 요약
+<stderr 로그에서 주요 step 요약>
+```
+
+- 실패 시: 에러 내용을 분석하고, demo-debugger subagent 사용을 제안한다.
+- 성공 시: 결과를 요약하고 스크린샷으로 확인한다.

screenagent_ai-0.3.0/.claude/skills/perf-audit/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: perf-audit
+description: screenagent 에이전트 루프의 성능 병목을 분석하고 코드를 개선한다. 스텝별 시간 측정, 불필요한 스크린샷 제거, sleep 최적화 등.
+argument-hint: [run-log-path or "analyze"]
+disable-model-invocation: true
+---
+
+# /perf-audit Skill
+
+screenagent 에이전트 루프의 성능 병목을 찾아내고 코드를 개선한다.
+
+## 배경
+
+현재 에이전트 루프의 알려진 병목:
+- 매 tool dispatch마다 스크린샷 캡처 (불필요할 수 있음)
+- `asyncio.sleep()` 고정 대기 시간 (0.3s, 2s 등)
+- LLM API 호출 대기 (줄일 수 없지만 토큰 수 줄이기 가능)
+- 스크린샷 리사이즈 (`sips` 호출)
+
+## Procedure
+
+### Step 1: 현재 성능 측정
+
+먼저 에이전트 루프를 dry-run이 아닌 실제 실행으로 시간을 측정한다.
+인자로 로그 파일 경로가 주어지면 해당 로그를 분석한다.
+
+로그가 없으면 `loop.py`의 `arun()` 메서드를 읽고 각 단계별 예상 시간을 계산한다:
+
+```
+src/screenagent/agent/loop.py 의 arun() 분석:
+```
+
+각 스텝에서 소요되는 시간 요소:
+1. `_perceive_async()` — AX tree + CDP DOM + screenshot
+2. `_client.messages.create()` — LLM API 호출
+3. `_dispatch_tool()` — tool 실행 + sleep + 후속 screenshot
+4. 메시지 직렬화/역직렬화
+
+### Step 2: 병목 식별
+
+`loop.py`와 `composite.py`를 읽고 다음을 체크한다:
+
+#### 2a. 불필요한 스크린샷
+- `_dispatch_tool`에서 click, type_text, key_press, scroll 후 모두 screenshot를 찍고 있음
+- 연속 동작(click → type → enter)에서 중간 스크린샷은 불필요할 수 있음
+- **개선**: tool 결과에 screenshot를 넣되, LLM이 다음 tool을 연속 호출할 때는 마지막 것만 사용
+
+#### 2b. sleep 최적화
+현재 sleep 값들:
+- `_open_url_via_keyboard`: 0.3s + 0.1s + 0.3s + 2.0s = **2.7s** (URL 열 때마다)
+- `click`: 0.3s
+- `type_text`: 0.3s
+- `key_press`: 0.3s
+- `scroll`: 0.3s
+- `navigate` (CDP): 1.0s
+
+**개선 방안**:
+- 페이지 로드 대기를 고정 sleep 대신 CDP `Page.loadEventFired` 이벤트 대기로 변경
+- 클릭/타이핑 후 sleep을 0.1s로 줄여볼 수 있음
+
+#### 2c. 이미지 크기 최적화
+- 스크린샷이 클수록 LLM 토큰 소모 많고 API 응답 느림
+- 현재 MAX_IMAGE_BYTES = 3.5MB → 너무 큼
+- **개선**: 1MB 이하로 줄이면 API 응답 속도 향상
+
+#### 2d. 히스토리 관리
+- MAX_HISTORY = 10이지만 각 메시지에 이미지가 포함됨
+- 오래된 메시지의 이미지를 제거하면 토큰 절약
+
+### Step 3: 코드 수정 적용
+
+분석 결과에 따라 실제 코드를 수정한다. 수정 대상 파일:
+
+| 파일 | 개선 내용 |
+|------|-----------|
+| `src/screenagent/agent/loop.py` | sleep 값 조정, 히스토리 이미지 제거, 스텝 타이밍 로그 |
+| `src/screenagent/perception/screenshot.py` | MAX_IMAGE_BYTES 축소 |
+| `src/screenagent/perception/composite.py` | CDP 우선 screenshot, 불필요한 AX tree 스킵 |
+
+수정 시 각 변경에 대해:
+1. 변경 전 동작을 설명
+2. 변경 후 기대 효과를 설명
+3. 위험 요소가 있으면 명시
+
+### Step 4: 검증
+
+```bash
+# 테스트 통과 확인
+.venv/bin/python -m pytest tests/ -x -q
+
+# dry-run 정상 확인
+.venv/bin/screenagent --output json run "test" --dry-run
+```
+
+### Step 5: 결과 리포트
+
+```
+## Performance Audit Report
+
+### 측정 결과
+| 구간 | 변경 전 | 변경 후 | 절감 |
+|------|---------|---------|------|
+| URL 열기 | 2.7s | 0.8s | -70% |
+| 클릭 후 대기 | 0.3s | 0.15s | -50% |
+| 스크린샷 크기 | ~600KB | ~200KB | -67% |
+| 스텝당 히스토리 토큰 | ~8K | ~4K | -50% |
+
+### 적용된 변경
+- [파일별 변경 내용]
+
+### 추가 권장
+- [더 할 수 있는 최적화]
+```

screenagent_ai-0.3.0/.claude/skills/reset-chrome/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: reset-chrome
+description: Chrome의 모든 탭을 닫고 새 창을 열어 깨끗한 상태로 만든다
+disable-model-invocation: true
+---
+
+# /reset-chrome Skill
+
+Chrome 브라우저를 깨끗한 상태로 리셋한다.
+
+## Procedure
+
+### Step 1: CDP 연결 확인
+
+```bash
+screenagent check --output json
+```
+
+- `ok: false`이면:
+  ```
+  Chrome CDP 연결 실패. 다음 명령어로 Chrome을 실행해주세요:
+  /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug-profile
+  ```
+  여기서 중단한다.
+
+### Step 2: 현재 탭 상태 확인
+
+```bash
+curl -s http://localhost:9222/json | python3 -c "
+import sys, json
+targets = json.load(sys.stdin)
+pages = [t for t in targets if t.get('type') == 'page']
+print(f'{len(pages)} tab(s) open')
+for p in pages:
+    print(f'  - {p.get(\"title\", \"untitled\")}: {p.get(\"url\", \"\")}')
+"
+```
+
+### Step 3: 탭 정리
+
+모든 탭을 닫고 하나의 about:blank 탭만 남긴다:
+
+```bash
+curl -s http://localhost:9222/json | python3 -c "
+import sys, json, urllib.request
+
+targets = json.load(sys.stdin)
+pages = [t for t in targets if t.get('type') == 'page']
+
+if not pages:
+    # 탭이 없으면 새 탭 생성
+    urllib.request.urlopen('http://localhost:9222/json/new?about:blank', timeout=5)
+    print('Created new blank tab')
+else:
+    # 첫 번째 탭 외 모두 닫기
+    for p in pages[1:]:
+        try:
+            urllib.request.urlopen(f'http://localhost:9222/json/close/{p[\"id\"]}', timeout=5)
+            print(f'Closed: {p.get(\"title\", \"untitled\")}')
+        except Exception as e:
+            print(f'Failed to close {p[\"id\"]}: {e}')
+
+    # 남은 탭 수 확인
+    print(f'Kept 1 tab: {pages[0].get(\"title\", \"untitled\")}')
+"
+```
+
+첫 번째 탭을 about:blank으로 이동시킨다:
+
+```bash
+curl -s http://localhost:9222/json | python3 -c "
+import sys, json, urllib.request
+targets = json.load(sys.stdin)
+pages = [t for t in targets if t.get('type') == 'page']
+if pages:
+    target_id = pages[0]['id']
+    urllib.request.urlopen(f'http://localhost:9222/json/activate/{target_id}', timeout=5)
+    print(f'Activated tab: {target_id}')
+"
+```
+
+그 다음 about:blank으로 네비게이트한다:
+
+```bash
+screenagent run "주소창에 about:blank를 입력하고 엔터를 눌러줘" --max-steps 3 --dry-run
+```
+
+대신 CDP로 직접 navigate한다:
+
+```bash
+python3 -c "
+import json, http.client
+
+# Get first page target
+conn = http.client.HTTPConnection('localhost', 9222)
+conn.request('GET', '/json')
+targets = json.loads(conn.getresponse().read())
+pages = [t for t in targets if t.get('type') == 'page']
+
+if pages:
+    ws_url = pages[0].get('webSocketDebuggerUrl', '')
+    target_id = pages[0]['id']
+    # Use CDP HTTP endpoint to navigate
+    conn.request('GET', f'/json/navigate/{target_id}?url=about:blank')
+    print(conn.getresponse().read().decode())
+    print('Navigated to about:blank')
+conn.close()
+"
+```
+
+### Step 4: 상태 확인
+
+```bash
+screenagent check --output json
+```
+
+결과를 보고한다:
+
+```
+Chrome 리셋 완료:
+- 탭: 1개 (about:blank)
+- CDP 연결: 정상
+```

screenagent_ai-0.3.0/.claude/skills/test-agent/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: test-agent
+description: screenagent CLI 도구들을 빠르게 검증한다. dry-run, screenshot, ax-tree, click 등 개별 기능을 테스트하고 결과를 리포트.
+argument-hint: [tool-name or "all"]
+disable-model-invocation: true
+---
+
+# /test-agent Skill
+
+screenagent의 개별 CLI 도구들을 빠르게 테스트하고 결과를 리포트한다.
+
+## Arguments
+
+- `all`: 모든 도구를 순서대로 테스트
+- 특정 도구 이름: `dry-run`, `screenshot`, `ax-tree`, `click`, `type`, `key`, `check`, `schema`
+
+## Procedure
+
+### 테스트 대상별 실행 방법
+
+각 테스트는 `--output json`으로 실행하여 결과를 파싱한다.
+
+#### 1. `dry-run` — 설정 검증
+
+```bash
+screenagent run "test" --dry-run --output json
+```
+
+- 확인: `ok` 필드가 `true`인지
+- 확인: `config.api_key_set`이 `true`인지
+- 확인: `config.model`이 유효한 모델명인지
+
+#### 2. `screenshot` — 스크린샷 캡처
+
+```bash
+screenagent screenshot --file /tmp/test_screenshot.png --output json
+```
+
+- 확인: `path` 필드가 존재하는지
+- 확인: `bytes`가 0보다 큰지
+- 확인: 파일이 실제로 존재하는지
+
+#### 3. `ax-tree` — 접근성 트리
+
+```bash
+screenagent ax-tree "Finder" --output json
+```
+
+- 확인: JSON 출력이 유효한지
+- 확인: `role` 필드가 존재하는지
+- 에러 시: 접근성 권한 문제인지 확인
+
+#### 4. `click` — 마우스 클릭 (안전한 좌표 사용)
+
+```bash
+screenagent click 0 0 --output json
+```
+
+- 확인: `clicked` 필드가 존재하는지
+- 주의: 화면 왼쪽 상단 구석(0,0)을 클릭하여 부작용 최소화
+
+#### 5. `type` — 키보드 입력 (빈 앱 없이 테스트하므로 skip 가능)
+
+이 테스트는 실제로 키 입력이 발생하므로, 현재 포커스된 앱에 텍스트가 입력될 수 있다.
+`all`로 실행 시에는 이 테스트를 건너뛰고, 명시적으로 `type`을 지정했을 때만 실행한다.
+
+```bash
+screenagent type "test" --output json
+```
+
+- 확인: `typed` 필드가 `"test"`인지
+
+#### 6. `key` — 키 입력
+
+```bash
+screenagent key escape --output json
+```
+
+- 확인: `pressed.key`가 `"escape"`인지
+- Escape는 대부분의 상황에서 안전한 키이다.
+
+#### 7. `check` — CDP 연결 확인
+
+```bash
+screenagent check --output json
+```
+
+- 확인: JSON 파싱 성공
+- `ok: true`이면 CDP 정상, `ok: false`이면 CDP 미연결 (경고만, 실패 아님)
+
+#### 8. `schema` — 도구 스키마
+
+```bash
+screenagent schema --output json
+```
+
+- 확인: `tools` 배열이 존재하는지
+- 확인: 각 도구에 `name`, `description`, `input_schema`가 있는지
+
+### 결과 리포트
+
+모든 테스트 완료 후 다음 형식으로 보고한다:
+
+```
+## Test Report
+
+| Tool       | Status | Details              |
+|------------|--------|----------------------|
+| dry-run    | ✅     | API key set, haiku   |
+| screenshot | ✅     | 245KB captured       |
+| ax-tree    | ✅     | Finder tree loaded   |
+| click      | ✅     | (0, 0) clicked       |
+| type       | ⏭️     | Skipped (all mode)   |
+| key        | ✅     | escape pressed       |
+| check      | ⚠️     | CDP not connected    |
+| schema     | ✅     | 6 tools found        |
+
+**Result**: 6/8 passed, 1 skipped, 1 warning
+```
+
+- ✅: 성공
+- ❌: 실패 (에러 내용 포함)
+- ⚠️: 경고 (기능은 동작하지만 주의 필요)
+- ⏭️: 건너뜀