can4hou6joeng4/boss-agent-cli

boss‑agent‑cli – 터미널 기반 구직·채용 어시스턴트

개요

• Python 기반 명령줄 인터페이스로, 사용자 또는 AI 에이전트가 중국 구직 플랫폼 BOSS 직핀 (zhipin)과 상호작용할 수 있습니다. 구직 검색, 복리후생 필터링, 로컬 후보 선별, AI 기반 이력서 작성, 채용 담당자 작업 등 전체 채용 워크플로우를 단일 JSON 출력 CLI에 통합합니다.

중요성

• 플랫폼을 스키마 기반 JSON 엔벨로프 ({ok, data, pagination, error, hints}) 뒤로 추상화하여 다운스트림 자동화(MCP 호스트, 셸 스크립트, Python SDK)가 HTML을 직접 스크래핑하지 않고 기능을 활용할 수 있습니다.
• **“복리후생 필터”**를 추가하여 복리후생(예: 주 5일 근무, 오현일금)을 AND 로직으로 매칭하고 로컬 관련성 점수로 결과를 정렬할 수 있습니다. 이는 네이티브 사이트에서 제공하지 않는 기능입니다.
• 검색, 상세 조회, 채팅, 이력서 다듬기 등 모든 고부하 작업은 로컬 LLM(Ollama/vLLM 또는 OpenAI 호환 엔드포인트)을 통해 실행할 수 있으며, 데이터를 사용자 머신에 유지합니다.

주요 기능

영역	명령어 (예시)	하이라이트
구직 검색	boss search "Golang" --city 广州 --welfare "双休,五险一金"	키워드 검색 + 8차원 필터, 캐시된 결과, HR 활동 필터 (--active 3d).
복리후생 필터링	--welfare "双休,五险一金" --sort score	자동 페이지네이션, 실시간 매칭, 점수 기반 순위.
로컬 후보 풀	boss shortlist add <sec_id> <job_id> --tags 后端,远程 boss stats	SQLite 기반 숏리스트 (태그, 메모, 퍼널 통계 포함).
AI 기반 구직자 도구	boss ai analyze-jd boss ai polish boss ai local configure	JD 분석, 이력서 다듬기, 면접 시뮬레이션; 외부 LLM과 연동.
채용 담당자 워크플로우	boss hr candidates "Python" --city 101010100 boss hr greet boss hr download-resume	후보 검색, 인사말 보내기, 지원서 관리, 채팅, 이력서 다운로드 – 모두 동일한 CLI에서.
에이전트 통합	boss schema (OpenAI/Anthropic 도구 정의 출력) boss-mcp (MCP 호스트)	JSON 스키마가 유일한 진실의 원천; MCP, 서브프로세스, Python SDK로 호출 가능.
복구 가능한 크롤링	boss crawl configure … boss crawl run …	헤드리스 Chrome (CDP) 기반 크롤링, 체크포인트, 예산 제한, 개인정보 안전 내보내기 포함.

일반적인 인간 워크플로우

# 설치 (uv 권장)
uv tool install boss-agent-cli
patchright install chromium   # Chrome 로그인에 필요

# 대화형 마법사 시작
boss

# 복리후생 필터로 검색
boss search "Golang" --city 广州 --welfare "双休,五险一金"

# 유망한 공고를 로컬 풀에 추가
boss shortlist add <security_id> <job_id> --tags 后端,远程

# AI 지원 이력서 다듬기 실행
boss ai polish --model ollama:mistral

# 오프라인 통계 보기
boss stats

에이전트/프로그래밍 방식 사용

• MCP 호스트 – JSON 설정으로 77개의 구현된 도구 노출:

  {"mcpServers": {"boss-agent": {"command": "uvx", "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"]}}}
  

• 서브프로세스 – boss schema를 호출하여 도구 정의를 가져온 후 명령을 호출하고 JSON 엔벨로프를 파싱합니다.
• Python SDK – BossClient 임포트:

  from boss_agent_cli import AuthManager, BossClient
  client = BossClient(AuthManager(...))
  result = client.search_jobs("Golang", city="广州")
  

아키텍처 개요

CLI (Click) ──> AuthManager (Fernet 암호화 로그인) ──> Platform registry (zhipin, zhipin‑recruiter)
          │                     │
          │                     └─> BossClient (httpx + 속도 제한, 선택적 CDP 브리지)
          │
          └─> CacheStore (SQLite WAL) ──> AIService (OpenAI 호환 / Ollama / vLLM)
                │
                └─> output.py → JSON 엔벨로프 (stdout)

모든 상태는 ~/.boss-agent/ (암호화된 자격 증명, 검색 캐시, 숏리스트, AI 설정)에 저장됩니다. 모델 가중치는 포함되지 않으며 요청 시 가져옵니다.

설치 및 배포

• PyPI에 게시 (boss-agent-cli).
• Docker로도 배포 가능 (docker compose run --rm boss-mcp).
• 크롤링용 선택적 추가 지원 (uv sync --extra crawl).

라이선스

• MIT 라이선스 (LICENSE 참조).

대상 사용자

• 터미널 UI를 선호하고 AI 기반 이력서 작업을 원하는 구직자.
• BOSS 직핀에서 스크립트로 후보를 관리해야 하는 채용 담당자.
• 플랫폼에 대한 안정적인 JSON 기반 인터페이스가 필요한 자동화 엔지니어/AI 에이전트 (예: 개인 구직 봇 구축 또는 대규모 RAG 파이프라인 통합).

주의사항

• 로그인 및 크롤링에는 Chrome/Chromium 설치가 필요합니다 (patchright로 처리).
• 플랫폼 특정: 현재 BOSS 직핀만 지원하며, 다른 중국 구직 사이트는 지원하지 않습니다.
• 사용자는 플랫폼 약관, 속도 제한, 개인정보 보호 규정을 준수해야 합니다. 도구는 구조화된 오류 코드 (NOT_SUPPORTED, AUTH_REQUIRED 등)와 내장 타임아웃/재시도 제어를 제공하여 규정 준수를 돕습니다.

---

전체 명령어 참조, 빠른 시작 가이드, 문제 해결 단계는 저장소의 docs/ 폴더를 참조하세요.