GAIA – Goal-oriented Autonomous Intelligence for Adaptive GUI Testing

GAIA는 “기획서만 주어지면 브라우저 테스트 플랜부터 실행·보고까지 자동으로 만들어 준다”는 목표로 설계된 1학기 MVP다. 현재 운영 방향은 OpenClaw가 화면 판단을 맡고, GAIA가 실행 안정화·검증·추적을 담당하는 thin-wrapper 구조다. 세부 운영 규약과 검증 기준은 gaia/docs/AGENT_HARNESS_PLAYBOOK.md를 우선한다.

AI 작업을 이 저장소에서 수행할 때는 저장소 전체를 읽지 말고, 먼저 루트 AGENTS.md 와 context pack을 사용한다.

python scripts/context_pack.py --area repo-entry
python scripts/context_pack.py --list-areas
python scripts/lint_harness_docs.py

발표용 빠른 링크 (중간발표 v2)

대본(12슬라이드): gaia/docs/presentation/MIDTERM_15MIN_V2.md
슬라이드 증빙맵: gaia/docs/presentation/SLIDE_EVIDENCE_MAP.md
발표 리허설용 포트폴리오 요약: PORTFOLIO_SKELETON.md
실행 이력 증빙 로그: PORTFOLIO_RUN_LOG.md
에이전트 작업 규약: gaia/docs/AGENT_HARNESS_PLAYBOOK.md

데모 실행 명령(발표 중 1회 smoke 확인용):

python -m gaia.cli chat \
  --llm-provider openai \
  --llm-model gpt-5.5 \
  --auth reuse \
  --auth-method oauth \
  --url https://inuu-timetable.vercel.app/ \
  --runtime terminal \
  --session workspace_default \
  --once \
  --feature-query "15학점 정도 과목 담고 시간표 조합 버튼으로 조합 생성 후 시간표에 적용"

주의:

위 명령 1회 실행은 smoke 확인이다.
완료 판정은 별도 verifier 검토 또는 독립 재현 + trace 증거까지 있어야 한다.

왜 GAIA인가?

Spec → Test까지 One-click: PDF 기획서를 투입하면 100+ 시나리오와 25개 체크리스트가 자동 생성된다.
Adaptive Execution: 우선순위·DOM 변화·실패 히스토리를 반영하는 스케줄러가 가장 가치 있는 시나리오부터 반복 실행한다.
Investor-ready UX: PySide6 GUI가 실시간 로그, 스크린샷, 커서 오버레이, 부분 성공률을 보여줘 비개발자도 데모를 진행할 수 있다.

시스템 아키텍처

          ┌──────────────┐      ┌──────────────┐
          │  Phase 1     │      │ Adaptive     │
Planning  │ PDF Loader + │──┬──▶│ Scheduler    │
PDF →     │ Agent Builder│  │   │ (priority PQ)│
Scenario  └──────────────┘  │   └──────┬───────┘
                             │          │
                             │    Prioritized plan
                             ▼          │
                        ┌───────────────┴──────────────┐
                        │ GAIA Thin Wrapper Runtime     │
                        │ ┌───────────────────────────┐ │
                        │ │ Goal/Run Orchestration    │ │
                        │ ├───────────────────────────┤ │
                        │ │ Dispatch + Stale Recovery │ │
                        │ ├───────────────────────────┤ │
                        │ │ Post-action Probe + QA    │ │
                        │ └───────────────────────────┘ │
                        │            │                  │
                        └────────────┼─────────────────┘
                                     │ ref actions / raw role tree
                         ┌───────────▼──────────┐
                         │ OpenClaw Browser     │
                         │ Runtime (embedded)   │
                         └───────────┬──────────┘
                                     │ DOM/Screenshot
                     ┌───────────────▼────────────────┐
                     │ GUI + Checklist Tracker + Report│
                     └─────────────────────────────────┘

End-to-End Flow

Phase 1 – Spec Analysis
- pdf_loader.PDFLoader가 PDF 텍스트를 정제하고, agent_client.AgentServiceClient가 OpenAI 모델(기본 gpt-5.5)으로 워크플로를 실행해 TestScenario + 체크리스트를 JSON으로 받는다.
Phase 4 – Autonomous Execution
- 현재 선호 경로는 OpenClaw-backed thin-wrapper다.
- OpenClaw browser runtime이 raw role tree / raw snapshot / ref 액션을 제공한다.
- GAIA는 실행 직전 디스패치·stale recovery·post-action probe·final verdict에 집중한다.
Browser Runtime
- embedded OpenClaw runtime이 브라우저를 제어하고 raw role tree와 action endpoint를 제공한다.
- legacy local Playwright host/fallback 경로는 제거됐고, 현재 실행 경로는 OpenClaw-only다.
Tracking & Reporting
- tracker.ChecklistTracker가 커버리지를 업데이트하고, GUI(gaia/src/gui)가 실시간 로그·스크린샷·Cursor overlay·4단계 결과(성공/부분/실패/스킵)를 시각화한다.

컴포넌트 상세

Phase 1 – Planner & Checklists

PDF Loader: 섹션·목차 구조를 유지한 채 텍스트를 정제.
Agent Builder Client: OpenAI Agent Workflow(GAIA_WORKFLOW_ID)를 호출해 100개 이상의 시나리오와 25개 체크리스트를 생성.
Fallback Plans: API 실패 시 artifacts/plans/*.json에 있는 플랜을 GUI에서 즉시 재사용 가능.

Adaptive Scheduler

Priority Queue: MUST/SHOULD/MAY + DOM 신규성 + 최근 실패를 점수화해 가장 가치 있는 테스트부터 실행.
Historical Awareness: 같은 URL의 반복 실패를 감지해 재시도 우선순위를 높임.
Streaming Interface: Phase 4 오케스트레이터가 큐에서 시나리오 배치를 받아 실행.

Phase 4 Execution Layer

OpenClaw Browser Runtime:
- raw role tree, raw snapshot, stable ref 기반 action contract를 제공한다.
- embedded runtime으로 repo 안에서 바로 띄울 수 있고, 필요 시 별도 backend로도 연결할 수 있다.
GAIA Thin Wrapper:
- raw OpenClaw evidence를 decision-time 1차 근거로 유지한다.
- wrapper 요약/semantic tag는 보조 힌트로만 사용한다.
- dispatch, stale recovery, post-action probe, trace, final QA verdict를 담당한다.
Higher-level Orchestration:
- planner, scheduler, navigation memory, cache 계층은 여전히 존재한다.
- 다만 이 계층이 OpenClaw보다 먼저 액션 의미를 강하게 확정하지 않는 것이 현재 운영 원칙이다.

Tracking, GUI & Reporting

Checklist Tracker: 시나리오에서 참조된 체크리스트 항목을 실시간으로 마킹.
PySide6 GUI:
- 실시간 로그 하이라이팅, 스크린샷/DOM 업데이트, SVG 커서 오버레이.
- Smart Navigation 이벤트, Scroll, Vision fallback 등 주요 이벤트를 즉시 렌더 (QCoreApplication.processEvents()로 UI 렉 방지).
Phase5 Report (WIP): 실행 결과를 요약해 회귀 테스트 보고서로 활용 예정.

Intelligent Capabilities & 안정성

페이지-요소 메모리: 최대 4개 페이지의 내비게이션 요소를 저장하고 다른 페이지에서 자동 탐색.
Aggressive Text Matching: DOM을 분석하기 전 step description에서 한/영 키워드를 모두 추출해 현재 페이지 요소부터 검색.
Semantic Matching + Embedding Cache: text-embedding-3-small + 로컬 fallback으로 시맨틱 유사도를 계산하고, 일치 시 LLM 검증.
Selector Cache: 동일한 스텝이 재실행될 때 후보 탐색/재매핑 힌트로 재사용해 LLM 호출을 줄인다. 직접 element action을 selector로 실행하지는 않는다.
Hash Navigation Recovery: Hash 이동 후 DOM 카운트가 비정상적으로 낮으면 홈으로 돌아가 버튼 클릭을 시도해 SPA 콘텐츠를 다시 로드.
Explicit Selector Fallback: 플랜에 기재된 셀렉터는 직접 실행용이 아니라 힌트로 사용되며, 실패 시 최신 snapshot/ref 기준 재분석으로 전환해 시나리오를 살린다.
4-Tier Result Reporting: 스킵률을 기반으로 PASS와 PARTIAL을 구분해 투자자 데모에서 정직한 결과를 제공한다.

실행 방법

1. Homebrew 설치 (권장)

brew tap capston2025/homebrew-gaia
brew install gaia
gaia --help

capston2025는 배포한 GitHub owner/조직으로 맞춰주세요.

Homebrew Formula 갱신

GitHub Actions 자동 갱신은 제거했습니다.
formula를 갱신해야 하면 로컬에서 scripts/sync_homebrew_formula.sh를 직접 실행해 관리합니다.
사용자 입장에서는 brew update 후 brew reinstall gaia 또는 brew upgrade gaia가 필요합니다.

2. 소스 실행 환경 (개발/직접 실행)

python -m venv .venv
source .venv/bin/activate
pip install -r gaia/requirements.txt
playwright install chromium

3. 필수/선택 환경 변수

OPENAI_API_KEY: OpenAI API 키 직접 사용 시에만 필요 (gaia auth login --provider openai --method manual).
GAIA_LLM_MODEL, GAIA_LLM_REASONING_EFFORT, GAIA_LLM_VERBOSITY: Planner 튜닝.
GAIA_WORKFLOW_ID, GAIA_WORKFLOW_VERSION: Agent Builder 워크플로 선택.
MCP_HOST_URL (기본 http://localhost:8001), MCP_TIMEOUT.

인증 관리

gaia auth login --provider openai     # OpenAI 로그인(권장: oauth)
gaia auth login --provider openai --method oauth
gaia auth login --provider openai --method manual  # API 키 직접 입력
gaia auth login --provider gemini     # Gemini 토큰 저장(옵션)
gaia auth status                    # 저장 상태 확인
gaia auth logout --provider openai   # 저장 토큰 삭제

gaia 실행 시 인증 전략을 reuse|fresh로 선택합니다(기본 reuse).

reuse: 저장 토큰 사용, 없으면 자동 fresh 로그인
fresh: 새 로그인 강제(OpenAI는 OAuth)

.env 예시:

# OpenAI oauth를 쓰지 않고 API 키 직접 쓰는 경우만 필요
OPENAI_API_KEY=sk-xxx
GAIA_WORKFLOW_ID=wf_68ea589f...
GAIA_LLM_MODEL=gpt-5.5
MCP_HOST_URL=http://localhost:8001

4. 실행 플로우

실행 모드

# 권장: gaia 단일 진입 (필수 설정 -> runtime/control 선택 -> chat hub)
gaia

# 레거시 alias (동일 동작)
gaia start

# 직접 모드 실행
gaia chat --gui --url https://example.com
gaia ai --terminal --url https://example.com
gaia plan --gui --spec /path/to/spec.pdf
gaia plan --gui --resume <run-id>

# legacy 명령도 유지됨
gaia start gui --mode chat --url https://example.com
gaia start terminal --mode ai --url https://example.com

# 세션 제어
gaia --session workspace_default      # 지정 세션 키 재사용
gaia --new-session                    # 새 MCP 세션 강제 생성

Telegram 원격 제어 (옵션)

# bot token 파일 준비
mkdir -p ~/.gaia
echo "<telegram-bot-token>" > ~/.gaia/telegram_bot_token

# polling 모드
gaia --control telegram \
  --tg-mode polling \
  --tg-token-file ~/.gaia/telegram_bot_token

# webhook 모드
gaia --control telegram \
  --tg-mode webhook \
  --tg-token-file ~/.gaia/telegram_bot_token \
  --tg-webhook-url https://your.domain/gaia-bot \
  --tg-webhook-bind 0.0.0.0:8088

# (권장) 관리자 chat_id 고정 지정
gaia --control telegram \
  --tg-mode polling \
  --tg-token-file ~/.gaia/telegram_bot_token \
  --tg-allowlist 123456789,987654321

인터랙티브 gaia 실행 시 제어 채널에서 telegram | no를 먼저 선택합니다.
telegram 선택 시 Telegram 설정 전략 reuse | fresh를 선택합니다.
reuse에서 저장된 설정이 없으면 오류를 출력하고 fresh로 재설정하도록 안내합니다.
fresh에서는 파일 경로 대신 Telegram Bot Token 문자열을 직접 입력하고 기본 경로(~/.gaia/telegram_bot_token)에 저장합니다.
--tg-allowlist는 "사용자 전체 허용목록"이 아니라 관리자 chat_id 목록입니다.
미승인 사용자는 텔레그램에서 /pair request 로 승인 요청합니다.
관리자는 /pair pending 후 /pair approve <request_id> 로 승인합니다.
--tg-allowlist를 비우면 첫 번째 /start 사용자가 초기 관리자로 자동 등록됩니다.

Chat Hub 운영 명령

/help
/status
/session
/session new
/session reuse <key>
/handoff
/handoff key=value ...
/stop
/memory stats
/memory clear

세션 포인터는 ~/.gaia/sessions/<session-key>.json에 저장되어 다음 실행에서 동일 브라우저/MCP 세션을 재사용합니다.

Telegram 페어링 명령

/start
/whoami
/pair request
/pair status
/pair pending               # admin
/pair approve <request_id>  # admin
/pair reject <request_id>   # admin
/pair revoke <chat_id>      # admin

과거 플로우인 python run_auto_test.py는 스크립트가 제거되어 더 이상 사용되지 않습니다.

5. 최신화 노트 (2026-02-22)

Ref-only 정책을 강화했습니다.
click/fill/press/hover/scroll/select 등 element 액션은 snapshot_id + ref_id가 없으면 실행하지 않습니다.
제약 fallback에서 ref 없는 scroll을 발행하지 않도록 수정했습니다(ref 없으면 wait 경로로 전환).
목표 수치 파싱을 개선했습니다.
3자리 숫자 제한(999)을 제거하고 큰 수치/콤마 수치(1,500)를 처리합니다.
collect_min/apply_target 기반 동적 상한을 사용합니다(고정 <=300 제거).
session id 생성 충돌을 줄이기 위해 초 단위 대신 time_ns 기반으로 변경했습니다.
DOM 복구 시 중후반 phase(AUTH/COMPOSE/APPLY/VERIFY)에서는 시작 URL 강제 복귀를 피하도록 조정했습니다.
focus 액션은 현재 실행 경로와 정합성을 위해 내부적으로 click으로 정규화합니다.

6. 빠른 실행 체크리스트 (팀 공통)

cd /path/to/capston
python -m pip install -e .
python -m playwright install chromium
python -m gaia.cli

Telegram 제어를 쓸 경우:

python -m pip install "python-telegram-bot>=21"

7. 자주 발생한 오류와 해결

ModuleNotFoundError: No module named gaia.cli

원인: editable install 미적용 또는 프로젝트 루트 밖에서 실행.
해결:

cd /path/to/capston
python -m pip install -e .
python -m gaia.cli

ModuleNotFoundError: No module named fastapi

원인: 런타임 의존성 미설치.
해결:

python -m pip install -e .

MCP host 자동 시작에 실패했습니다

원인: 의존성 누락, 포트 충돌, 기존 프로세스 점유.
해결:

lsof -ti tcp:8001 | xargs kill -9
python -m gaia.cli

DOM 분석 오류: HTTP 500 또는 반복 DOM Not found

원인: Chromium 미설치/브라우저 세션 비정상.
해결:

python -m playwright install chromium

확인:

curl http://127.0.0.1:8001/health
curl http://127.0.0.1:8001/metrics-lite

Windows에서 No module named termios

원인: Unix 전용 모듈 import 경로 사용.
해결: 최신 코드로 업데이트 후 재설치.

python -m pip install -e .

codex exec 인자/UTF-8 관련 오류

원인: Codex CLI 버전/입력 인코딩 편차.
해결:
Codex CLI 업데이트
PowerShell/터미널 UTF-8 환경 확인
fresh oauth로 재로그인 후 재시도

8. 검증용 1회 실행 예시 (터미널 자동 종료)

python -m gaia.cli chat \
  --llm-provider openai \
  --llm-model gpt-5.5 \
  --auth reuse \
  --auth-method oauth \
  --url https://inuu-timetable.vercel.app/ \
  --runtime terminal \
  --session workspace_default \
  --once \
  --feature-query "15학점 정도 과목 담고 시간표 조합 버튼으로 조합 생성 후 시간표에 적용"

또한 과거에는 ./scripts/run_gui.sh가 python -m gaia.main로 실행됐으나 이제 gaia plan --gui를 사용합니다.

GUI에서 기존 플랜 재사용 시 “이전 테스트 불러오기”로 artifacts/plans/*.json 선택 시 즉시 실행할 수 있습니다.

9. 팀 분업/운영 자동화 문서

오너십 맵: gaia/docs/TEAM_OWNERSHIP.md
4주 실행 플레이북: gaia/docs/TEAM_PLAYBOOK.md
설치 가이드(Windows/macOS): gaia/docs/INSTALL_WINDOWS_MAC.md
팀원별 작업 가이드:
- gaia/docs/team/01_core_lead_codex.md
- gaia/docs/team/02_platform_devops_codex.md
- gaia/docs/team/03_product_ui_claude.md
- gaia/docs/team/04_reliability_embedded_codex.md

10. 하드닝/리포트 스크립트

# 5분 하드닝 실행
python scripts/run_hardening.py --minutes 5 --url https://inuu-timetable.vercel.app/

# 30분 하드닝 실행
python scripts/run_hardening.py --minutes 30 --url https://inuu-timetable.vercel.app/

# reason_code 분포 리포트 생성
python scripts/reason_code_report.py

11. 회귀 시나리오 팩

경로: gaia/tests/scenarios/*.json
필수 필드: id, url, goal, constraints, expected_signals, time_budget_sec
포맷 상세: gaia/tests/scenarios/README.md

12. Playwright 검증 레일 (CLI)

경로: gaia/playwright-rail
목적: /test 실행 직후 결정론적 레일(smoke/full)로 교차검증

설치:

cd gaia/playwright-rail
npm install
npx playwright install chromium

수동 실행:

# smoke 3개
cd gaia/playwright-rail
npx playwright test tests/smoke --config=playwright.config.ts

# full (수동 전용)
npx playwright test tests/full --config=playwright.config.ts

GAIA 연동:

/test 종료 후 기본적으로 smoke 레일 자동 실행
환경변수:
- GAIA_RAIL_ENABLED=1
- GAIA_RAIL_SCOPE_DEFAULT=smoke
- GAIA_RAIL_MODE=soft
- GAIA_RAIL_TIMEOUT_SEC=300
아티팩트: gaia/artifacts/validation-rail/<run_id>/<scope>/summary.json

실행 기억(KB)

저장 위치: ~/.gaia/memory/kb.sqlite3
기본 활성화: gaia 실행 시 자동 사용
범위: 도메인 단위 재사용
보관 기간: 30일 (자동 정리)

워크스페이스 구조

gaia/
├── src/
│   ├── phase1/                # PDF 분석 + Agent Builder 연동
│   ├── phase4/
│   │   ├── goal_driven/              # 목표 기반 에이전트 루프
│   │   ├── mcp_ref/                  # ref 기반 action/snapshot 헬퍼
│   │   ├── orchestrator/             # intelligent orchestrator 런타임 묶음
│   │   └── llm_vision_client.py      # Vision/selector LLM 래퍼
│   ├── tracker/               # Checklist 커버리지 트래커
│   ├── gui/                   # PySide6 GUI, 워커 스레드
│   ├── phase5/                # 리포트/요약 유틸 (WIP)
│   ├── utils/                 # 설정/데이터 모델 (Pydantic)
│   └── orchestrator.py        # CLI 오케스트레이터
├── artifacts/                 # benchmark, wrapper trace, 임시 디버그 산출물 (source of truth 아님)
├── scripts/                   # run_gui.sh 등
├── tests/                     # Pytest (planner, scheduler, orchestration)
├── homebrew/                  # Homebrew formula
└── README.md

테스트 & 자동화

pytest gaia/tests
python test_scheduler_logic.py      # 스케줄러 로직 단독 검증
python test_automation.py           # 단순 시나리오 실행기
python run_local_test.py            # 로컬 UI 테스트 사이트용 데모

문서 & 진행 관리

gaia/docs/presentation/MIDTERM_15MIN_V2.md: 중간발표 15분 대본(12슬라이드).
gaia/docs/presentation/SLIDE_EVIDENCE_MAP.md: 슬라이드별 근거 문서 매핑.
gaia/docs/AGENT_HARNESS_PLAYBOOK.md: Planner / Developer / Verifier / Cleanup 하네스 운영 규약.
gaia/docs/TEAM_OWNERSHIP.md: 오너십/역할 분담.
gaia/docs/TEAM_PLAYBOOK.md: 4주 실행 계획/운영 리듬.
gaia/docs/INSTALL_WINDOWS_MAC.md: 플랫폼별 설치 가이드.
gaia/docs/team/*.md: 팀원별 세부 실행 가이드.
PORTFOLIO_SKELETON.md, PORTFOLIO_RUN_LOG.md: 발표/포트폴리오 서술 + 증빙 로그.
artifacts/: benchmark, wrapper trace, tmp 산출물. 필요 시 재생성 가능.

GAIA는 “학생/초기 팀도 버튼 몇 번이면 회귀 테스트를 돌릴 수 있는” QA 파이프라인을 목표로 계속 진화하고 있다. 새로운 기능을 추가할 때는 gaia/docs/TEAM_PLAYBOOK.md와 관련 팀 문서를 함께 갱신하고, generated artifact 경로가 바뀌면 관련 문서를 함께 갱신해 주세요.

Name		Name	Last commit message	Last commit date
Latest commit History 361 Commits
.claude		.claude
.github		.github
Formula		Formula
docs/harness		docs/harness
examples		examples
gaia-battle-web		gaia-battle-web
gaia		gaia
git-hooks		git-hooks
homebrew/Formula		homebrew/Formula
monitoring		monitoring
scripts		scripts
vendor		vendor
.gitignore		.gitignore
.python-version		.python-version
.tmp_analyze_page_elements.js		.tmp_analyze_page_elements.js
AGENTS.md		AGENTS.md
README.md		README.md
measure_metrics.py		measure_metrics.py
opencode.json		opencode.json
pyproject.toml		pyproject.toml
train_ui_detector.ipynb		train_ui_detector.ipynb

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

GAIA – Goal-oriented Autonomous Intelligence for Adaptive GUI Testing

발표용 빠른 링크 (중간발표 v2)

왜 GAIA인가?

시스템 아키텍처

End-to-End Flow

컴포넌트 상세

Phase 1 – Planner & Checklists

Adaptive Scheduler

Phase 4 Execution Layer

Tracking, GUI & Reporting

Intelligent Capabilities & 안정성

실행 방법

1. Homebrew 설치 (권장)

Homebrew Formula 갱신

2. 소스 실행 환경 (개발/직접 실행)

3. 필수/선택 환경 변수

인증 관리

4. 실행 플로우

5. 최신화 노트 (2026-02-22)

6. 빠른 실행 체크리스트 (팀 공통)

7. 자주 발생한 오류와 해결

8. 검증용 1회 실행 예시 (터미널 자동 종료)

9. 팀 분업/운영 자동화 문서

10. 하드닝/리포트 스크립트

11. 회귀 시나리오 팩

12. Playwright 검증 레일 (CLI)

실행 기억(KB)

워크스페이스 구조

테스트 & 자동화

문서 & 진행 관리

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages