12 KiB
명령어 하나로, 10개 플랫폼까지.
샤오훙수 · 더우인 · TikTok · 빌리빌리 · 콰이서우 · 웨이보 · 셴위 · 타오바오 · 징둥 · X
곧 탑승: Instagram · YouTube · Facebook · 즈후 · 위챗 공식 계정 · 진르터우탸오 · 더우 · 핀둬둬 · 메이퇀 · 다중뎬핑
플랫폼마다 API도, 서명 방식도, 로그인 방법도, 데이터 형식도 제각각입니다. catbus는 이 모두를 한 대의 버스에 태웁니다. 같은 명령어, 같은 JSON, 같은 로그인 정보 디렉터리. 플랫폼을 바꿀 때는 단어 하나만 바꾸면 됩니다.
✨ catbus란?
catbus(猫巴士)는 중국과 해외의 주요 플랫폼 10곳의 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입니다. 한 번 배우면 10개 플랫폼 모두에서 쓸 수 있습니다.
🚀 왜 catbus인가
🧭 같은 의미, 같은 이름의미가 같은 기능은 모든 플랫폼에서 같은 명령어, 같은 파라미터, 같은 출력을 씁니다. 플랫폼 고유의 용어( |
📦 Node만 있으면 됩니다Python도, 컴파일러도, 어떤 시스템 의존성도 필요 없습니다. 네이티브 의존성은 모두 사전 빌드된 바이너리를 제공하며 Windows, macOS, Linux의 x64 / arm64(musl 포함)를 지원합니다. 8개 대상 시스템 모두 CI에서 하나하나 스모크 테스트를 거칩니다. |
🤖 AI 에이전트를 위한 설계stdout에는 JSON만 나오고, 종료 코드는 안정적이며, 오류에는 다음에 실행할 명령어가 함께 담깁니다. |
🔐 로그인 정보는 내 컴퓨터에만QR 코드, SMS, cookie 가져오기를 모두 지원합니다. 인증 정보는 플랫폼 × 엔드포인트 × 계정 단위로 |
🧪 업스트림과 바이트 단위로 일치모든 요청의 URL, 헤더 순서, cookie, body, 서명을 난수와 시계를 고정한 상태에서 업스트림 구현과 바이트 단위로 대조합니다. 560+건의 골든 데이터와 940+개의 오프라인 테스트가 모든 변경을 지킵니다. |
🛡️ 브라우저급 네트워크 스택실제 Chrome과 동일한 TLS / HTTP2 핑거프린트. 업스트림의 서명 JS는 수정 없이 그대로 샌드박스에서 실행되고, 슬라이더·클릭 선택형 캡차는 로컬 ONNX와 OpenCV로 자동 인식합니다. |
📊 숫자로 보는 catbus
| 🚌 플랫폼 | ⌨️ 구현된 명령어 | 🧪 골든 데이터 | ✅ 오프라인 테스트 | 💻 대상 시스템 |
|---|---|---|---|---|
| 10 | 300+ | 560+ | 940+ | 8 |
🏗️ 아키텍처
- 하나의 레지스트리가 모든 것을 움직입니다: 명령어 파싱, 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
탑승하세요, 어느 플랫폼으로든 · All aboard, every platform.