cv-cat/catbus

플랫폼마다 API도, 서명 방식도, 로그인 방법도, 데이터 형식도 제각각입니다. catbus는 이 모두를 한 대의 버스에 태웁니다. 같은 명령어, 같은 JSON, 같은 로그인 정보 디렉터리. 플랫폼을 바꿀 때는 단어 하나만 바꾸면 됩니다.

❤️ Sponsor

✨ catbus란?

catbus(猫巴士)는 중국과 해외의 주요 플랫폼 12곳의 web 엔드포인트 기능을 통일된 문법으로 호출하는 커맨드라인 도구입니다. 검색, 상세 정보, 댓글, 사용자, 추천 피드, 다운로드, 게시, DM, 라이브 방송 탄막, 열차 잔여석 및 운임 조회, 공연 정보……

catbus xhs      item search 露营 --sort latest
catbus douyin   item search 露营 --sort latest
catbus bilibili item search 露营 --sort latest
catbus x        item search camping --sort latest

플랫폼 4곳, 거의 똑같은 명령어 4줄, 그리고 같은 구조의 JSON 출력. 노트, 작품, 동영상, 트윗 모두 item이고, 검색은 언제나 search, 좋아요는 언제나 like입니다. 한 번 배우면 12개 플랫폼 모두에서 쓸 수 있습니다.

🚀 왜 catbus인가

🧭 같은 의미, 같은 이름 의미가 같은 기능은 모든 플랫폼에서 같은 명령어, 같은 파라미터, 같은 출력을 씁니다. 플랫폼 고유의 용어(note, aweme, tweet……)를 써도 괜찮습니다. 어떤 단어를 써야 하는지 catbus가 알려 줍니다.	📦 Node만 있으면 됩니다 Python도, 컴파일러도, 어떤 시스템 의존성도 필요 없습니다. 네이티브 의존성은 모두 사전 빌드된 바이너리를 제공하며 Windows, macOS, Linux의 x64 / arm64(musl 포함)를 지원합니다. 8개 대상 시스템 모두 CI에서 하나하나 스모크 테스트를 거칩니다.
🤖 AI 에이전트를 위한 설계 stdout에는 JSON만 나오고, 종료 코드는 안정적이며, 오류에는 다음에 실행할 명령어가 함께 담깁니다. catbus platforms는 전체 기능 목록을 출력합니다. 에이전트 스킬과 llms.txt를 기본 제공합니다.	🔐 로그인 정보는 내 컴퓨터에만 QR 코드, SMS, cookie 가져오기를 모두 지원합니다. 인증 정보는 플랫폼 × 엔드포인트 × 계정 단위로 ~/.catbus/(0700 / 0600)에 분리 저장되며, 여러 계정을 언제든 전환할 수 있습니다. 어떤 데이터도 수집하거나 업로드하지 않고, 텔레메트리도 없습니다.
🧪 업스트림과 바이트 단위로 일치 모든 요청의 URL, 헤더 순서, cookie, body, 서명을 난수와 시계를 고정한 상태에서 업스트림 구현과 바이트 단위로 대조합니다. 560+건의 골든 데이터와 940+개의 오프라인 테스트가 모든 변경을 지킵니다.	🛡️ 브라우저급 네트워크 스택 실제 Chrome과 동일한 TLS / HTTP2 핑거프린트. 업스트림의 서명 JS는 수정 없이 그대로 샌드박스에서 실행되고, 슬라이더·클릭 선택형 캡차는 로컬 ONNX와 OpenCV로 자동 인식합니다.

📊 숫자로 보는 catbus

🏗️ 아키텍처

• 하나의 레지스트리가 모든 것을 움직입니다: 명령어 파싱, 4단계 --help, catbus platforms, 기능 매트릭스가 모두 같은 레지스트리에서 생성되므로 서로 어긋날 일이 없습니다.
• 플랫폼 하나에 파일 한 세트: client는 세션과 서명을 맡고, api는 업스트림 메서드와 일대일로 대응하며, normalize는 원본 데이터를 통일된 타입으로 바꾸고, resolve는 ID, 링크, 공유용 단축 링크, me를 모두 인자로 쓸 수 있게 합니다.
• 확장 가능: 명세에 app / pc 엔드포인트 자리가 마련되어 있으며, JS가 아닌 업스트림은 provider 프로토콜로 연결될 예정입니다.

🤖 AI 에이전트를 위한 설계

catbus는 첫날부터 '프로그램이 호출하는 도구'로 설계되었습니다.

catbus platforms douyin | jq '.data.commands[] | select(.status=="implemented") | .resource + " " + .action'

• 자기 기술적: 플랫폼별, 명령어별 로그인 요구 사항, 구현 상태, 업스트림 지원 수준을 명령어 하나로 확인할 수 있습니다.
• 예측 가능: 성공과 실패 모두 같은 엔벨로프 { ok, data, page, error }를 쓰며, error.hint가 다음에 실행할 명령어를 바로 알려 줍니다.
• 연결 가능: 모든 출력 객체에 id와 url이 들어 있어, 앞 명령어의 결과를 그대로 다음 명령어에 넘길 수 있습니다.
• 절제: 위험한 작업에는 반드시 명시적인 -y가 필요하고, 게시물은 나만 보기로 올릴 수 있으며, 리스크 컨트롤에 걸리면 RISK_CONTROL로 분명히 알리고 몰래 재시도하지 않습니다.

명령어 하나로 catbus 스킬을 Claude Code, Cursor, Codex 등 에이전트에 설치할 수 있습니다:

npx skills add cv-cat/catbus

스킬은 필요한 만큼만 불러옵니다. 개요는 한 페이지뿐이고, 다루는 플랫폼과 작업 종류(수집, 게시, 라이브·DM, 문제 해결)에 따라 하위 파일만 읽습니다. 안전 규칙도 내장되어 있습니다: 로그인은 사용자에게 맡기고, 쓰기 작업은 먼저 확인하며, 게시는 기본적으로 비공개, 리스크 컨트롤을 만나면 멈춥니다.

⚡ 30초 만에 탑승

npm i -g catbus-cli

catbus doctor                 # 환경 점검
catbus bilibili auth login    # QR 코드로 로그인
catbus bilibili item search 猫 --limit 20

Docker나 소스에서 설치할 수도 있습니다. 전체 절차는 빠른 시작을 참고하세요.

📚 문서

아래 문서는 중국어(간체)로 작성되어 있습니다.

🚀 빠른 시작	설치부터 첫 데이터 내보내기까지
🔑 로그인 · ⚙️ 설정 · 🐳 Docker	QR 코드 / cookie, 다중 계정, 프록시, 컨테이너
📤 출력과 오류 처리	엔벨로프, 정규화 타입, 페이지네이션, 종료 코드
🧭 플랫폼별 안내 · 🗂️ 기능 매트릭스	플랫폼마다 무엇을 지원하는지, 인자는 어떻게 넘기는지
🧪 예제 스크립트	크로스 플랫폼 검색, 댓글 내보내기, 게시물 백업, 라이브 탄막 기록
📐 AGENTS.md	catbus 명세 그 자체
❓ 자주 묻는 질문	왜 로그인해야 하나요? 리스크 컨트롤에 걸리면 어떻게 하나요?……

🤝 기여하기

issue와 PR 모두 환영합니다. 새 플랫폼, 새 명령어, 플랫폼 API 변경 대응, 문서 개선 등 무엇이든 좋습니다. 시작하기 전에 CONTRIBUTING.md와 AGENTS.md를 읽어 주세요(명세가 먼저이며, 요청에는 반드시 골든 테스트가 있어야 합니다). 보안 문제는 SECURITY.md에 따라 비공개로 제보해 주세요.

📈 Star 추이

🍔 커뮤니티

스크래핑과 AI 에이전트에 관심이 있다면 그룹 채팅(중국어)에 참여해 함께 이야기해요.

그룹이 가득 찼거나 QR 코드가 만료되었다면 issue를 남기거나 위챗 / QQ로 알려 주세요.

group-1	group-2	group-3	group-4 (2,000명 QQ 그룹)

⚠️ 면책 조항

• 이 프로젝트는 학습 및 연구 목적으로만 제공됩니다. 상업적 목적이나 어떠한 불법적 목적으로도 사용하지 마십시오.
• 사용 시 각 플랫폼의 사용자 약관과 서비스 약관, 그리고 거주 지역의 법령을 준수하십시오. 타인의 개인 정보를 수집하거나 유포하지 말고, 플랫폼에 과도한 요청 부하를 주지 마십시오.
• 자동화된 작업은 플랫폼의 리스크 컨트롤을 작동시켜 캡차, 요청 제한, 나아가 계정 정지로 이어질 수 있습니다. 이 프로젝트의 사용으로 발생하는 모든 결과에 대한 책임은 전적으로 사용자 본인에게 있습니다.
• 이 프로젝트는 위에 언급된 어떤 플랫폼과도 관련이 없으며, 해당 플랫폼의 허가나 승인을 받지 않았습니다. 각 플랫폼의 명칭과 상표는 해당 소유자에게 귀속됩니다.

📄 License

MIT © 2026 cv-cat