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를 던지고 무모한 재시도 없이 즉시 중단한다.

현재 소스에서 다시 확인한 실행·저장 경계

2026-10-29 공식 관측의 archived 값은 false이며 해당 소스는 공개돼 있다. 이전의 아카이브·개발 중단 안내를 제거했다. 문서의 Docker 예시는 Node 22 계열로 프런트를 빌드하고 Python 3.11 환경에 Chromium을 포함한다. 로컬 프런트의 잠금 파일은 Vite에 Node ^20.19.0 || >=22.12.0를 요구한다. README에 적힌 과거 Node 20.18.3 빌드 관측을 현재 최소 조건으로 사용하면 안 된다.

sqlite_bootstrap.py는 스키마를 초기화하고 작업·결과·가격 스냅샷의 과거 파일을 각각 최초 가져오기한다. 마이그레이션 완료 마커가 있거나 작업 테이블이 이미 차 있으면 기존 데이터를 덮어 가져오지 않는다. 현재 조회의 정본은 data/app.sqlite3이며 state/ 로그인 상태·프롬프트·로그·임시 이미지는 파일로 남는다.

AI 작업 생성의 진행 상태는 TaskGenerationService 안의 메모리 딕셔너리에 있고 별도 스레드의 이벤트 루프가 작업을 수행한다. SQLite에 저장된 감시 작업과 진행 중인 생성 job은 수명이 다르다. API의 202 응답을 작업 저장 완료로 읽지 말고 job 상태를 계속 확인해야 한다.

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참고 링크

2026-10-29 재검토: 공식 소스 커밋 77f8d75869acd65f9dba72731b95c7c49ea67bdf. 아래 초판 기록과 현재 소스 개정 내용을 구분한다.

더 파고들 곳.