fancyboi999/goofish-cli

闲鱼 CLI · 原生支持 MCP · 为 AI Agent 而生 | Goofish (Xianyu) automation CLI · MCP-ready · Built for AI Agents

그것이 무엇인가

goofish‑cli는 중국 중고 거래 플랫폼 Xianyu(또는 Goofish라고도 함)의 핵심 작업을 래핑하는 Python 명령줄 도구입니다. 인간 또는 AI 에이전트(Claude Code, Cursor, OpenClaw 등)가 단일하고 구조화된 명령 집합을 통해 프로그래밍 방식으로 상품을 게시하고, 목록을 관리하고, 메시지를 보내고 받고, 플랫폼을 조회할 수 있게 해줍니다.

AI 에이전트에게 중요한 이유

이 도구는 AI 우선 설계로 만들어졌습니다:

모든 명령은 기계가 읽을 수 있는 형식(json, yaml, csv, md, table)으로 출력할 수 있습니다.
MCP(Model Context Protocol) 서버로 등록되므로 에이전트가 명령을 "도구"로 호출할 수 있습니다(예: goofish_item_get).
5개의 Claude Skills가 번들로 제공되어 Claude 기반 에이전트가 제로샷 프롬프트에 의존하지 않고 도메인별 지식(게시, 답변, 위험 가드, 상점 진단, 개요)을 자동으로 로드할 수 있습니다.
OpenClaw는 저장소를 호환 가능한 플러그인 번들로 로드하여 자체 에이전트 프레임워크에 동일한 명령을 노출할 수 있습니다.

핵심 기능(17개 명령)

영역	예시 명령	기능
인증	`goofish auth login <cookies.json>`	브라우저 쿠키 파일을 가져와 세션을 생성합니다. `auth status`는 유효성을 확인합니다.
상품	`goofish item get <id>`	상품 세부 정보를 검색합니다. `goofish item publish …`
미디어	`goofish media upload <file>`	이미지를 Xianyu의 CDN에 업로드합니다.
카테고리	`goofish category recommend <title>`	AI 지원 카테고리 추천.
위치	`goofish location default`	기본 배송 주소를 가져옵니다.
메시징	`goofish message list-chats`, `goofish message send …`, `goofish message watch`	채팅 목록, 텍스트/이미지 보내기, 세 가지 이벤트 유형(`message`, `read`, `new_msg`)의 실시간 WebSocket 스트림 유지.
검색 및 보기	`goofish search items …`, `goofish item view …`	브라우저 자동화 검색(Playwright) 및 안티스팸 제한을 우회하는 전체 필드 "보기" 모드.
스킬	`goofish skills install`	5개의 Claude 스킬 번들을 `~/.claude/skills/`에 설치합니다.

안전 및 규정 준수

속도 제한 – 계정당 상한(1 게시/분, 9 미디어 업로드/분) 및 자동 회로 차단기(RGV587).
위험 가드 – 금지 단어, 외부 링크 및 기타 플랫폼별 금지 사항에 대한 내장 검사.
규정 준수 고지 – README는 이 도구가 개인 계정 자동화 전용임을 강조합니다. 사기, 대량 판매 SaaS 또는 Xianyu 사용자 계약을 우회하는 데 사용해서는 안 됩니다.

시작하기(60초)

pip install goofish-cli            # 또는: uv pip install goofish-cli
# Chrome DevTools → Application → Cookies에서 Xianyu 쿠키 내보내기
goofish auth login ~/Downloads/goofish-cookies.json
goofish auth status                # 로그인 작동 확인
# 예시 작업
goofish item get 1045171414271
goofish message watch             # 실시간 IM 피드
goofish message send <cid> <toid> --text "在的"

모든 명령은 쉬운 다운스트림 파싱을 위해 --format json|yaml|table|md|csv를 지원합니다.

Claude Code(MCP) 통합 단계

도구 설치(위와 동일).

~/.config/claude-code/config.json에 항목 추가:

{"mcpServers": {"goofish": {"command": "uvx", "args": ["goofish-cli"]}}}

이제 Claude는 대화에서 직접 호출할 수 있는 goofish_item_publish와 같은 함수를 노출합니다.

OpenClaw / ClawHub 사용법

openclaw plugins install clawhub:openclaw-goofish
# 선택 사항: QR 코드로 로그인
uvx --from goofish-cli==0.5.3 goofish auth login --qr
openclaw plugins inspect goofish --json
openclaw gateway restart

플러그인 번들은 동일한 MCP 도구와 5개의 Claude 스킬을 제공합니다.

개발 및 테스트

환경 관리를 위해 uv 사용(uv venv --python 3.11).
33개의 단위 테스트(pytest) 및 ruff를 사용한 정적 분석(경고 0개).
기여 지침 및 아키텍처 문서는 저장소에 있습니다.

라이선스

Apache 2.0 – 개인 및 상업적 사용에 무료이며, 일반적인 저작자 표시 요구 사항이 적용됩니다.

결론: goofish-cli는 Xianyu를 위한 완전한 기능을 갖춘 Python 기반 자동화 레이어로, MCP 및 Claude 스킬을 통해 현대 AI 에이전트가 소비할 수 있도록 의도적으로 설계되었으며, 인간 친화적인 CLI와 안전 메커니즘을 제공합니다.