ai-goofish-monitor 딥다이브
— "AI가 대신 중고장터를 잠복 감시한다": 스크래핑 × 멀티모달 LLM × 실시간 관제

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

ai-goofish-monitor는 闲鱼(셴위, 알리바바가 운영하는 중국 최대 개인 간 중고거래 앱)에서 특정 키워드의 새 매물을 실시간·예약으로 감시하고, 각 매물을 비전 LLM(이미지 판독이 되는 대형언어모델) 이 사용자가 설정한 구매 기준으로 자동 심사해, "살 만하다"고 판단한 매물만 휴대폰 알림으로 보내주는 프로그램이다. 모든 조작은 웹 관리 UI(대시보드)에서 이뤄진다.

코드 내부 버전은 2.0.0(FastAPI 앱 타이틀 기준)이며, AI 심사 페르소나의 코드네임은 EagleEye-V6.4다. 라이선스는 관대한 MIT(원저작권자 dingyufei615, 현재 Usagi-org 조직 호스팅). 별 13,200개·포크 1,900개로 인기가 검증됐지만, 현재 GitHub에서 저장소가 archived(보관·읽기전용) 상태라는 점은 유의해야 한다(추가 업데이트·보안 패치가 멈춤).

2왜 주목받는가

트렌딩 이유와, 흔한 "크롤러 스크립트"와의 결정적 차이.

① LLM을 "필터"가 아니라 "판단자"로 쓴다

대부분의 매물 알리미는 키워드·가격 범위 같은 단순 규칙으로 거른다. 이 프로젝트는 한 발 더 나아가, 매물 사진 + 상세정보 + 판매자 이력을 통째로 비전 LLM에게 주고 "사람처럼 판단"하게 한다. 예컨대 "겉보기 개인 판매자지만 실제로는 되팔이(업자)인지"를 판매자의 구매·판매·평가 이력에서 행동 서사를 재구성해 가려낸다. 프롬프트에는 "PERSONA-FIRST 원칙", "이미지 우선 원칙", "한 방에 탈락시키는 deal-breaker 규칙" 같은 실전 프롬프트 엔지니어링이 담겨 있다.

② "안티봇 vs 스크래퍼" 공방을 실물로 보여준다

闲鱼는 자동화를 막으려고 여러 방어선을 친다. 이 프로젝트는 그걸 계층적으로 돌파한다.

• 실제 브라우저 지문 복제 — 전용 크롬 확장으로 로그인 쿠키(HttpOnly 포함) + UA·시간대·화면크기·deviceMemory 같은 환경 정보를 통째로 추출해 Playwright에 그대로 재현
• navigator.webdriver 위장 + 모바일 기기 에뮬레이션(안드로이드 UA·터치·상하이 위치)
• DOM이 아니라 내부 API 응답을 가로챔 — 화면 긁기(취약)가 아니라 mtop JSON API를 page.on("response")로 낚아챔(견고)
• 사람 같은 랜덤 지연 + 홈페이지 워밍업 + 리스크컨트롤(캡차) 감지 시 즉시 중단

즉, "서버가 막으면 어떻게 우회하나"의 여러 계층을 한 코드베이스에서 관찰할 수 있다.

③ 스크립트가 아니라 "제대로 설계된 풀스택 앱"

루트의 spider_v2.py 한 파일이 전부가 아니다. 112개 Python + 79개 Vue + 46개 TypeScript 파일이 api → services → domain → infrastructure 4계층(DDD풍)으로 나뉘고, WebSocket 실시간 로그, APScheduler 크론 예약, 6종 알림 채널, SQLite 저장, Docker 멀티스테이지 빌드, 40여 개 테스트(실트래픽 스모크 포함)까지 갖췄다. "크롤러 하나"를 어떻게 운영 가능한 제품으로 키우는지 보여주는 표본이다.

3기술 스택 전체 지도

무엇으로 만들어졌나 — 계층별로. (requirements.txt·package.json에서 실제 확인)

백엔드 — 웹/비동기 코어

그 밖에 requests(이미지 다운로드를 executor로), httpx[socks]+python-socks(프록시), aiofiles, Pillow, pyzbar+qrcode(QR 로그인 처리), jinja2를 쓴다. 테스트는 pytest·pytest-asyncio·coverage.

프런트엔드 — 관리 대시보드 (web-ui/)

화면은 Dashboard·Tasks·Results·Accounts·Settings·Logs·Login 뷰로 구성된다. Vite 개발 서버는 /api·/auth·/ws를 백엔드(:8000)로 프록시한다.

인프라 / 부가 요소

4아키텍처 심화 분석

감시 작업 하나가 처음부터 끝까지 어떻게 흐르는가.

2계층 프로세스 모델 — 웹서버와 작업이 분리돼 있다

이 설계의 첫 번째 핵심은 "웹서버 프로세스"와 "감시 작업 프로세스"가 완전히 분리돼 있다는 것이다. 웹서버(python -m src.app)는 API를 제공하고 예약을 관리할 뿐, 실제 스크래핑은 작업마다 별도 OS 서브프로세스(spider_v2.py --task-name)로 띄운다. 한 작업이 캡차에 막히거나 죽어도 서버·다른 작업은 멀쩡하다.

AI 심사 파이프라인 — 프롬프트가 2층으로 조립된다

AI 심사는 이 프로젝트의 백미다. 프롬프트는 고정된 "출력 형식 계약"과, 작업별 "구매 기준"이 런타임에 합쳐지는 2층 구조다.

# prompts/base_prompt.txt — 모든 작업이 공유하는 출력 형식 계약
너는 EagleEye-V6.4. 반드시 아래 JSON 스키마로만 답하라:
{
  "prompt_version": ...,
  "is_recommended": true|false,      # 이 불리언 하나로 알림 여부가 갈린다
  "reason": "...",
  "risk_tags": ["...", ...],
  "criteria_analysis": {             # 기준별 세부 판정
    "model_chip": ..., "battery_health": ...,
    "condition": ..., "seller_type": { "analysis_details": ... },
    "shipping": ..., "seller_credit": ...
  }
}
{{CRITERIA_SECTION}}                  # ← 여기에 작업별 기준이 주입됨

런타임에 spider_v2.py가 base_prompt.replace("{{CRITERIA_SECTION}}", 기준텍스트)로 합친다. 기준 파일(예: prompts/macbook_criteria.txt)에는 "겉보기 개인/실제 업자 구분", "한 방 탈락 규칙", "이미지 우선", 사후 확인이 필요한 항목은 NEEDS_MANUAL_CHECK로 보류 같은 실전 프롬프트 규칙이 들어있다.

요청 조립(ai_message_builder.py)은 매물 JSON(판매자·가격 참조 포함)을 시스템 프롬프트와 합치고, 매물 이미지들을 data:image/jpeg;base64,… image_url 파트로 붙인 멀티모달 메시지를 만든다. temperature=0.1(재시도 시 0.05), 최대 4회 재시도, 필수 필드 누락 시 재요청하는 검증기(validate_ai_response_format)까지 붙는다.

운영 견고성 — RotationPool · FailureGuard · 리스크컨트롤

중국 마켓플레이스의 강한 안티봇과 쿠키 만료에 대응하는 장치가 촘촘하다. RotationPool은 여러 계정/프록시를 TTL 블랙리스트와 함께 돌려쓰고, FailureGuard는 연속 실패(TASK_FAILURE_THRESHOLD 기본 3회)가 나면 작업을 TASK_FAILURE_PAUSE_SECONDS(기본 86400초=24시간) 정지시킨 뒤 쿠키 갱신 시 자동 복구한다. 캡차 오버레이(baxia-dialog)나 FAIL_SYS_USER_VALIDATE 응답을 만나면 RiskControlError를 던지고 무모한 재시도 없이 즉시 중단한다.

5디렉토리 구조 해부

어디에 무엇이 있나 — 계층형(DDD풍) 백엔드 + Vue SPA.

진입점을 읽는 순서를 권한다: ① src/app.py(서버가 뜰 때 무슨 일이 일어나나) → ② spider_v2.py(작업 하나가 어떻게 실행되나) → ③ src/scraper.py의 scrape_xianyu()(수집 루프) → ④ item_analysis_dispatcher.py + ai_handler.py(심사) → ⑤ ai_request_compat.py(LLM 호환) 순.

6학습 포인트 (기술별)

이 코드를 뜯어 무엇을 내 것으로 만들 수 있나.

① 비동기 스크래핑 & 프로세스 격리

asyncio.create_subprocess_exec로 작업을 독립 프로세스로 띄우고, os.setsid로 프로세스 그룹을 분리해 SIGTERM으로 통째 정리하는 패턴. 크래시 격리·개별 취소가 필요한 워커 시스템의 정석이다. page.on("response")로 네트워크 응답을 도청하는 스크래핑 기법도 여기서 배운다.

② 멀티모달 LLM 파이프라인 설계

이미지+텍스트를 하나의 메시지로 조립하고, 구조화 JSON 출력을 강제·검증·재시도하는 전 과정. 특히 ai_request_compat.py의 "에러 메시지를 보고 미지원 파라미터를 스스로 끄는" 방식은 여러 LLM 제공사를 지원해야 하는 실무에서 그대로 쓸 수 있다.

③ 계층형 백엔드(DDD풍) + 의존성 주입

api → services → domain → infrastructure 분리, 리포지토리 패턴(SqliteTaskRepository), src/api/dependencies.py의 DI. "크롤러 스크립트"를 "유지보수 가능한 서비스"로 승격시키는 구조를 실물로 관찰할 수 있다.

④ 실시간 관제 UI (FastAPI + WebSocket + Vue 3)

백엔드가 작업 상태를 /ws로 브로드캐스트하고 Vue 프런트가 실시간 갱신하는 전형. 단일 FastAPI 서버가 API와 SPA 정적파일을 함께 서빙하고, catch-all 라우트로 SPA 히스토리 모드를 받치는 배포 구성도 배울 만하다.

7시스템 요구사항

돌리려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

난이도별로. (합법·안전한 범위 내에서 아키텍처를 익히는 데 초점)

9관련 기술 심화 학습 로드맵

이 레포를 축으로 4주 커리큘럼.

10핵심 키워드 사전

문서에 나온 용어를 한 번에.

11참고 링크

더 파고들 곳.