<div align="center">
<img src="https://raw.githubusercontent.com/can4hou6joeng4/boss-agent-cli/HEAD/docs/assets/logo.png" width="112" alt="boss-agent-cli 로고">
boss-agent-cli
🤖 사람과 AI Agent를 위한 채용 플랫폼 CLI — 순수 터미널 가이드 · 복리후생 필터링 · 이중 역할 워크플로우 · JSON 봉투.
Python
License
GitHub Release
PyPI Downloads
PRs Welcome
빠른 시작 · 아키텍처 · Agent 통합 · 명령어 · 문제 해결 · 로드맵 · 中文 | English
<a href="demo/showcase/boss-agent-cli-showcase.mp4" title="48초 제품 발표회 애니메이션 시청">
<img src="https://raw.githubusercontent.com/can4hou6joeng4/boss-agent-cli/HEAD/demo/showcase/boss-agent-cli-showcase.gif?v=keynote-20261008" alt="boss-agent-cli 극광 발표회 애니메이션: 복리후생 필터링, 이중 역할 워크플로우 및 Agent 연결" width="100%">
</a>
48초 발표회 애니메이션 시청 · 인터랙티브 버전 · 터미널 상호작용 데모 · 복리후생 필터링 · 이중 역할 워크플로우 · Agent 연결
</div
🧭 왜
boss-agent-cli는 직무 발견, 복리후생 필터링, 로컬 이력서와 AI 연동, 지원 커뮤니케이션, 채용 담당자 후보자 처리 및 복구 가능한 수집을 하나의 CLI에 통합합니다. 실제 사용자는 boss를 직접 실행하여 순수 터미널 가이드를 이용하고; Agent는 JSON, schema, MCP 또는 Python API를 사용하여 동일한 워크플로우와 상태를 호출합니다. boss schema는 항상 능력의 진원지입니다.
⚠️ 작동 경계
이전 설정인 operating_mode=assisted|research는 계속 호환되지만, 두 가지 모드 모두 구현된 모든 기능을 호출할 수 있으며 더 이상 모드 레벨의 COMPLIANCE_BLOCKED가 발생하지 않습니다. 플랫폼이 아직 구현하지 못한 기능은 여전히 정확하게 NOT_SUPPORTED를 반환합니다. 인증 만료, 계정 위험 및 네트워크 오류는 구조화된 오류와 복구 동작을 유지합니다. 장기 프로세스는 여전히 timeout, retry, 예산(budget), 체크포인트(checkpoint) 및 stop 제어의 영향을 받습니다.
✨ 핵심 기능
- 직무 발견: 키워드 검색 + 8차원 필터링, 번호별 캐시 결과 조회 —
search show detail
- 복지 조건 필터링 (핵심 차별화):
--welfare "주 5일 근무제, 5대 보험 및 퇴직금"을 사용하여 자동 페이지 넘김으로 추가 수집하고, AND 논리로 실제 일치 여부를 확인하며, --sort score로 로컬 매칭 점수 순 정렬 가능 — search --welfare
- HR 활동도 필터링:
--active 3d는 최근 활동한 HR만 남겨서, 장기간 비활성 상태인 포지션에 지원 기회를 낭비하는 것을 방지합니다. online은 목록만 확인하며 요청량은 일반 검색과 동일하지만, 나머지 단계는 개별 직무 상세를 조회해야 하므로 더 느리고 위험 통제(risk control) 위험이 높습니다. 따라서 저위험 시나리오에서는 --active online 사용을 권장합니다 — search --active
- 순수 터미널 가이드:
boss 또는 boss wizard를 직접 실행하여 역할, 플랫폼 및 목표를 선택할 수 있습니다. 동일한 워크플로우는 --input-json, run ID 또는 MCP를 사용하여 진행 및 복구도 가능합니다.
- 로컬 후보군 및 통계: 상세 내용을 확인 후 로컬 저장하거나, 유효 상태의 웹 페이지 직무 컬렉션을 읽어와 유효 항목만 동기화할 수 있습니다 / 태그와 메모를 사용해 후보 포지션을 검토하고, 오프라인 비교를 하거나, 퍼널(funnel) 통계를 확인할 수 있습니다 —
shortlist stats watch preset favorites
- AI 구직 강화 + 로컬 모델: JD 분석, 이력서 교정, 방향성 최적화, 후보군 매칭, 모의 면접, 커뮤니케이션 가이드 등을 제공합니다. 로컬 모델 가중치(weight)는 외부에 배치되어 Ollama/vLLM OpenAI 호환 인터페이스를 지원합니다 —
ai analyze-jd ai local configure ai local smoke
- Schema 기반 + JSON Envelope: stdout은
{ok, schema_version, command, data, pagination, error, hints}의 7개 키 봉투(envelope)만 출력하며, boss schema가 핵심 능력 원천이므로 CLI 오케스트레이션 / Shell Agent / MCP / Python SDK에 적합합니다.
- 채용 담당자 전체 프로세스: 먼저 채용 담당자의 신분을 확인한 후, 후보자 검색, 우수 인재 추천, 첫 인사(greet), 근무지, 첨부 이력서 수신 및 다운로드, 이력서, 채팅/최근 메시지, 답장 및 직무 관리 등의 전 과정을 지원합니다 —
hr whoami/candidates/recommendations/greet/location/applications/resume/chat/last-messages/reply/request-resume/accept-resume/download-resume/jobs
- 플랫폼 추상화:
Platform / RecruiterPlatform 이중 레지스트리(double registry)와 --platform 전역 옵션을 제공합니다. 현재 등록된 플랫폼은 zhipin (BOSS 직핀)입니다.
🚀 빠른 시작
uv tool install boss-agent-cli
boss doctor
...
모든 명령어 출력은 구조화된 JSON 형식입니다 (ok로 성공/실패 판단, 기본값 exit 0/1; 선택적 --exit-codes sysexits는 오류 유형별로 구분된 시맨틱 종료 코드를 반환합니다). 전체 사용법은 빠른 시작 가이드를 참고하세요.
🎭 역할 및 플랫폼
| 플랫폼 | 구직자 | 채용 담당자 | 상태 |
|---|
BOSS 직핀 (zhipin) | ✅ | ✅ | 기본값 |
boss platforms
boss --platform zhipin search "Python"
boss hr ...와 구직자 측 agent 자동화는 현재 모두 zhipin-recruiter만 지원합니다. 상세 설계 내용은 docs/platform-abstraction.md를 참고하세요.
🤖 Agent 통합
다음 내용을 먼저 읽어보시는 것을 권장합니다: Agent Quickstart · Capability Matrix · Host Examples
{ "mcpServers": { "boss-agent": { "command": "uvx", "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"] } } }
로컬에 Python 도구 체인을 설정하고 싶지 않다면, 저장소 자체의 컨테이너를 사용할 수 있습니다: BOSS_UID=$(id -u) BOSS_GID=$(id -g) docker compose run --rm boss-mcp.
이미지는 의도적으로 브라우저 커널을 포함하지 않습니다 — 먼저 호스트 머신에서 boss login을 수행한 후, ~/.boss-agent를 마운트합니다. 자세한 내용은 Docker 연동을 참조하세요.
OpenCode 소스 코어 프로젝트에서는 저장소 예시를 직접 사용할 수 있습니다:
cp examples/opencode/opencode.json ./opencode.json
uv sync --all-extras
uv run boss-mcp --data-dir ./.boss-agent --help
포터블(portable) 또는 전역 설치 후, 임의의 OpenCode 프로젝트에서 examples/opencode.json을 사용하면, 이는 boss-mcp --data-dir ./.boss-agent를 실행하여 검토(review), 보류 중(pending), 로그가 프로젝트별로 격리되도록 합니다.
from boss_agent_cli import AuthManager, BossClient, AuthRequired
with BossClient(AuthManager(...)) as client:
...
📚 명령어
boss schema는 39개의 최상위 명령어와 15개의 1차 채용자 하위 명령어를 노출하며, 작업 흐름별로 그룹화되어 있습니다:
- 인증:
login · logout · status · doctor
- 직무 검색:
search · recommend · detail · show · cities · history
- 로컬 정리:
watch · preset · shortlist · stats · favorites
- 복구 가능한 수집:
crawl configure/run/start/status/results/resume/stop/shortlist
- 이력서 / AI:
resume · me · ai analyze-jd · ai polish · ai optimize · ai fit · ai suggest-keywords · ai resume-optimize · ai cover-letter · ai interview-prep · ai chat-coach · ai local
- 시스템 / 워크플로우:
wizard · schema · platforms · export · config · clean
- 후보자 행동:
greet · batch-greet · apply · exchange · chat · chatmsg · chat-summary · mark · interviews · pipeline · digest · follow-up
- 채용 담당자:
hr whoami/applications/candidates/recommendations/greet/location/resume/chat/chatmsg/last-messages/reply/request-resume/accept-resume/download-resume/jobs
전체 명령어 목록, 매개변수 및 혜택 필터링 원리는 **명령어 참고**를 참조하십시오. 핵심 기능의 근원은 boss schema이며, 이는 --format openai-tools / anthropic-tools / mcp-tools를 통해 도구 정의를 내보낼 수 있습니다.
대량 수집(Batch Crawling)을 위해서는 추가로 pip install "boss-agent-cli[crawl]" (또는 uv tool install "boss-agent-cli[crawl]"; 소스 코드가 있는 저장소에서는 uv sync --extra crawl)를 설치해야 합니다. 이는 독립적인 <data-dir>/crawl/chrome-profile을 사용하므로 일상적인 Chrome 프로필을 가로채지 않습니다. 기본적으로 Hook 주입은 수행하지 않으며, 로컬 스크립트를 사용하려면 반드시 Hook 경로와 SHA256SUMS를 포함하는 디렉토리를 명시적으로 제공해야 합니다:
boss crawl configure --max-requests 20 --max-details 50 --max-seconds 600 --max-retries 1
boss crawl run "AI" --city 杭州 --pages 3 --with-detail `
--hook-profile screenshot-full --hook-dir E:\boss-agent-cli-local-hooks\AntiDebug_Breaker
...
crawl run은 순차적으로 실행되며 SQLite 체크포인트와 JSON / CSV / XLSX 증분 결과물을 저장합니다. 요청 수, 상세 정보 수, 벽시계 시간 및 재시도는 고정된 예산 제약 하에 작동하며, boss crawl stop을 통해 다음 안전 지점에서 중지할 수 있습니다. 내보내기(Export) 및 crawl results는 기본적으로 security_id, 직무 ID 또는 채용자 필드를 노출하지 않습니다. boss clean --privacy를 실행하면 크롤링 상태, 예산 및 내보낸 결과물이 삭제됩니다. 세밀한 MCP crawl tools는 기존의 run_id를 읽거나 가져옵니다. boss_wizard를 통해 워크플로우(workflow) 공유 기능을 사용하여 작업을 시작, 복구 및 중지할 수 있습니다. 플랫폼 위험 코드나 보안 페이지가 나타나면 중지하고 복구 명령을 반환합니다.
🩺 진단 및 문제 해결 (Diagnosis & Troubleshooting)
boss doctor
boss status --live
boss doctor --live-probe
오류 메시지는 공통적으로 code + recoverable + recovery_action을 포함하며, 이는 프로그램적인 복구가 가능함을 의미합니다. boss doctor는 CDP(Chrome DevTools Protocol) 가용성을 확인하고 browser_channel 상태를 집계합니다. chat / chatmsg는 기본 auto 소스에서 로컬 자격 증명(credential)을 사용하는 httpx를 사용합니다. --browser-source existing-browser를 명시적으로 선택해야만 CDP를 통해 기존 페이지를 재사용할 수 있으며, 이 경우 CLI가 저장한 쿠키는 읽지 않습니다. 기존 브라우저 후보가 소진되면 BROWSER_SESSION_NOT_FOUND와 함께 boss doctor가 반환됩니다. 일반적인 미로그인 경로는 여전히 AUTH_REQUIRED와 함께 boss login을 요구합니다. 모든 소스에서 플랫폼 위험 통제(risk control)에 걸리면 현재 워크플로우를 중지하고 체크포인트(checkpoint)를 저장합니다. 어댑터는 반드시 제한적으로 실행, 민감 정보 제거(de-sensitize), 그리고 중지 가능해야 하며, 위험 상태가 해제된 후에만 명시적으로 복구되어야 합니다.
v3.0.0 마이그레이션: Browser Bridge daemon, Chrome 확장 및 [bridge] 설치 extra는 제거되었습니다. CLI를 업그레이드해도 기존 데몬은 중지되지 않으며, 브라우저 확장은 제거되지 않습니다. 이전 데몬을 수동으로 중지하고, 이전 확장 기능을 비활성화하거나 제거한 후, 설치 명령어에서 [bridge]를 제외하십시오. 브라우저는 기본적으로 CDP → headless 순서로 다운그레이드됩니다. 기존 세션만 재사용하려면 먼저 로컬 CDP 브라우저의 공식 페이지에 수동으로 로그인한 다음 다음을 실행하십시오:
boss --browser-source existing-browser --cdp-url http://localhost:9222 chat
이 소스는 새 페이지를 만들거나, 탐색하거나, 쿠키를 주입하지 않으며, 브라우저도 시작하지 않습니다. CDP 디버깅 포트는 로컬 신뢰 환경에서만 사용해야 하며, 공용 인터넷에 노출하거나 플랫폼 위험 통제를 우회하는 데 사용해서는 안 됩니다.
전체 점검 항목, CDP 시작 예시 및 오류 코드는 **진단 및 문제 해결**를 참조하십시오. 쿠키 / CDP / patchright / 요청 빈도 / 인터페이스 드리프트(interface drift)와 관련된 문제는 먼저 플랫폼 위험 경계를 읽어보십시오.
⚙️ 설정
boss config list # 모든 설정 보기
boss config set log_level debug # 로그 레벨 설정하기
boss config reset log_level # 개별 설정 항목의 기본값 복원
설정은 ~/.boss-agent/config.json에 위치합니다: 운영 모드 (operating_mode=assisted|research), 요청 간격, 일괄 인사 간격, 로그 레벨, CDP 주소, 내보내기 디렉토리, 플랫폼/역할.
🏗️ 기술 아키텍처
CLI (Click)
└─ 호환 실행 메타데이터 (assisted / research 모두 개방 및 구현된 능력)
└─ AuthManager ── 사용자 능동 로그인 상태 (Fernet + PBKDF2 기기 바인딩 암호화)
...
불변성(Invariants): stdout은 JSON Envelope만 · stderr는 로그만 · exit 0/1 (선택적 --exit-codes sysexits 의미론적 종료 코드) · 오류에는 code/recoverable/recovery_action 포함 · boss schema가 능력의 진정한 출처입니다.
이중 청중 안내(Dual Audience Hints): hints.next_actions는 Agent가 실행할 후속 명령이며, hints.operator_actions는 실제 사용자 운영자에게 제공되는 자연어 지침(QR 코드 스캔, 브라우저에서 조건 조정 등 터미널을 벗어나 완료해야 하는 동작)입니다. TTY 환경에서는 후자를 stderr로만 렌더링하며, Agent는 이를 운영자에게 전달해야 합니다.
명령 vs. 위자드: 단일, 비상태 능력 호출은 최상위 명령어를 사용합니다. 단계적 상태가 필요하거나, 복구 가능해야 하거나, 도중에 지침을 실제 사용자에게 넘겨야 하는 경우는 boss wizard를 사용합니다 (goal 값은 boss schema의 wizard_catalog에서 확인).
선택 기술(Stack): Python ≥ 3.11 · Click · httpx · patchright / CDP (로그인, 내보내기 및 선언을 위한 브라우저 어댑터) · cryptography (Fernet) · sqlite3 (WAL) · pytest (2900+ 항목).
🔌 로컬 저장소
모든 상태는 ~/.boss-agent/에 저장됩니다: 암호화된 로그인 상태, 검색 캐시, 후보 풀, 로컬 이력서, AI 설정 및 외부 모델 등록. 모델 가중치는 Python 패키지에 포함되지 않습니다. 명시적으로 발동된 API 호출이나 로컬 모델 다운로드를 제외하고 데이터는 본 기기를 벗어나지 않습니다.
🤝 기여자
Issue / PR 환영: git clone → feat/xxx 브랜치 → 테스트 작성 → python scripts/quality_baseline.py (Windows 중국어 시스템의 경우 $env:PYTHONUTF8='1' 먼저 실행) → PR 제출. 자세한 내용은 CONTRIBUTING.md를 참조하고, 시작 경로는 빠른 시작 가이드를 참고하세요. 재현 가능한 오프라인 MCP 평가는 evals/README.md에서 확인할 수 있습니다. 참여는 행동 강령을 준수하는 것에 동의함을 의미합니다.
boss-agent-cli를 더 좋게 만들어준 모든 기여자분들께 감사드리며, 그들을 응원해주세요! ❤️
<a href="https://github.com/can4hou6joeng4/boss-agent-cli/graphs/contributors">
<img src="https://raw.githubusercontent.com/can4hou6joeng4/boss-agent-cli/HEAD/CONTRIBUTORS.svg" alt="기여자" width="1000" />
</a>
❤️ 지원
- 도움이 되었다면, 가장 직접적인 지원은 Star ⭐를 누르거나 구직 중인 사람에게 공유하는 것입니다.
- 문제가 있거나 새로운 아이디어가 있다면, Issue를 제기해 주세요; 직접 기여하고 싶다면 바로 PR을 올려주세요. 보안 취약점은 공개적으로 Issue를 제기하지 말고 SECURITY.md에 따라 비공개로 보고해 주세요.
- 도움이 필요하신가요? 먼저 지원받기를 확인하세요: 문서 진입점, Discussions, Issue 및 비공개 보안 보고의 정확한 위치입니다.
- 다른 배들을 보고 싶다면 모항구 bobochang.cn에 정박하는 것을 환영합니다 🧭, 항해 기록은掘金专栏에서 확인할 수 있습니다.
이 프로젝트는 geekgeekrun · boss-cli · opencli의 도움을 받았으며, 함께 감사를 표합니다.
⭐ Star History
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/star-history-dark.svg">
<img alt="Star History" src="https://raw.githubusercontent.com/can4hou6joeng4/boss-agent-cli/HEAD/docs/assets/star-history.svg" width="100%">
</picture>
mystarhistory에 의해 로컬로 생성된 정적 SVG이며, 저장소와 동일 출처이고 제3자 서비스에 의존하지 않습니다.
⚠️ 면책 조항
사용 시 해당 법률, 플랫폼 프로토콜 및 개인 정보 보호 요구 사항을 준수해 주십시오. 대량 접촉(batch outreach), 후보자 개인 데이터 및 브라우저 적응형 설정에 대해 명확한 입력, 수량, 시간 초과 및 중지 조건을 설정하고 로컬 자격 증명 및 내보내기 결과물을 안전하게 보호해야 합니다. 부적절한 사용으로 인해 발생하는 결과는 사용자 본인이 책임지며, 프로젝트 작성자와는 무관합니다.
📑 라이선스 & 관련 링크
MIT © [can4hou6joeng4] · 관련 링크 [LINUX DO]