boss-agent-cli

<div align="center"> <img src="docs/assets/logo.svg" width="112" alt="boss-agent-cli logo"> # Tool List *🤖 BOSS ZhiPin local assistant CLI for AI Agent — Search · Welfare Screening · Candidate Pool · JSON Envelope, default assisted, support explicit Research Mode.* [](https://github.com/can4hou6joeng4/boss-agent-cli/actions/workflows/ci.yml) [](https://codecov.io/gh/can4hou6joeng4/boss-agent-cli) [](https://python.org) [](LICENSE) [](https://github.com/can4hou6joeng4/boss-agent-cli/releases) [](https://pypi.org/project/boss-agent-cli/) [](https://github.com/can4hou6joeng4/boss-agent-cli/pulls) [Getting Started](docs/getting-started.md) · [Agent Integration](#-agent-integration) · [Commands](#-commands) · [Troubleshooting](docs/troubleshooting.md) · [Roadmap](ROADMAP.md) · **[English](README.en.md)** <a href="demo/showcase/boss-agent-cli-showcase.mp4" title="Watch the full project showcase video"> <img src="demo/showcase/boss-agent-cli-showcase.gif" alt="boss-agent-cli project showcase gif" width="100%"> </a> **[Watch the full showcase video](demo/showcase/boss-agent-cli-showcase.mp4)** · [Terminal interaction demo](demo/demo-zh.gif) · schema driven · Welfare Screening · JSON Envelope </div> <p align="center"> <a href="https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=boss-agent-cli"> <img src="docs/assets/atlas-cloud-logo.png" alt="Atlas Cloud" width="180"> </a> </p> > 🎁 **[Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=boss-agent-cli)** provides a full-modal, OpenAI-compatible inference portal — one key to access DeepSeek, Qwen, GLM, Kimi, MiniMax, Claude, GPT and other models, no need to connect to each one. In `boss ai config`, select `--provider atlas` (`base_url=https://api.atlascloud.ai/v1`, default model `deepseek-ai/deepseek-v4-pro`) to use. For more information, see [AI Model Integration](docs/integrations/ai-models.md#atlas-cloud-one-key-to-cover-multiple-models). > [!TIP] > <img src="https://github.com/peterfei/ai-agent-team/raw/main/examples/doloffer.png" alt="Doloffer logo" width="220"> > > **Doloffer Guide** aims to make high-quality AI tools more accessible. The platform focuses on official membership recharge for mainstream AI services like GPT and Claude, providing one-stop subscription management, emphasizing security, stability, and worry-free after-sales support. > > 💡 **Fast Subscription**: [Exclusive Link](https://doloffer.com/friend/BEv3yvKS) (enter the discount code `AI8888` for a 10% discount) ## 🧭 Why Automated job application and batch greetings are essentially doing what the platform doesn't want to be automated — account suspension is just a matter of time. `boss-agent-cli` takes a different approach: **it delegates low-risk, read-only tasks to the terminal and Agent, while leaving sensitive actions like greetings, applications, and communication to manual completion on the official website.** You describe your expectations, and the Agent handles searching, screening, and organizing candidate positions, outputting structured JSON; `boss schema` is the source of capabilities, naturally compatible with Claude, Cursor, and other MCP hosts. Compliance is not a post-hoc patch, but a default posture. ## ⚠️ Compliance Boundary **Assisted Mode** is enabled by default: local assistance, read-only priority, and user-initiated actions. Sensitive capabilities like greetings, applications, contact exchange, recruiter candidate search/resume/chat, and message replies are blocked by default and return `COMPLIANCE_BLOCKED`; if needed, please manually complete these actions on the BOSS ZhiPin platform. The repository also allows explicit `boss config set operating_mode research` to enable **Research Mode** for bounded browser protocol, anti-debugging, risk control adaptation, and controlled collection research; this mode still requires desensitization, checkpointing, stop switches, and auditable script sources. ## ✨ Core Capabilities - **Job Discovery**: keyword search + 8-dimensional screening, review cached results by number — `search` `show` `detail` - **Welfare Screening (Core Differentiation)**: `--welfare "double leave, five insurances and one fund"` automatically flips pages, grabs and matches **realistic AND logic**, and sorts by local matching score — `search --welfare` - **Local Candidate Pool and Statistics**: save locally after viewing details, synchronize webpage job collection, use tags and notes to review candidate positions, offline comparison, and view funnel statistics; applications and communication are manually completed on the official website — `shortlist` `stats` `watch` `preset` `favorites` - **AI Job Search Enhancement + Local Model**: JD analysis, resume polishing, directional optimization, candidate pool matching, simulated interview, communication guidance; local model weights are external, supporting Ollama/vLLM OpenAI compatible interface — `ai analyze-jd` `ai local configure` `ai local smoke` - **Schema Driven + JSON Envelope**: stdout outputs `{ok, data, pagination, error, hints}` envelope, `boss schema` is the source of capabilities, suitable for CLI orchestration/Shell Agent/MCP/Python SDK - **Recruiter Minimum Loop**: job list and up/down ( `hr jobs list/online/offline` ); candidate personal data link is blocked by default - **Multi-Platform Abstraction**: `Platform` / `RecruiterPlatform` dual registry, `--platform zhipin|zhilian|qiancheng` ## 🚀 Quick Start ```bash # Installation (uv recommended; browser kernel is only used for user-initiated login/local export) uv tool install boss-agent-cli patchright install chromium # Run through low-risk closed loop boss doctor # Environment self-test boss login # User-initiated login (select platform) boss status # Verify login status boss search "Golang" --city Guangzhou --welfare "double leave, five insurances and one fund" # Search + Welfare Screening boss detail <security_id> # View details boss shortlist add <security_id> <job_id> --tags backend,remote # Add to local candidate pool and set local tags boss shortlist compare --tag remote # Offline comparison of candidate positions boss stats # Local statistics # Recruiter mode (candidate data link is blocked by default) boss hr jobs list ``` All command outputs are structured JSON (`ok` determines success or failure, `exit 0/1`). For complete getting started, see [Getting Started](docs/getting-started.md). ## 🎭 Roles and Multi-Platform | Platform | Job Seeker | Recruiter | Status | |------|:--:|:--:|------| | BOSS ZhiPin (`zhipin`) | ✅ | ✅ | Default | | Zhilian Recruitment (`zhilian`) | ✅ Candidate side read-only + local assistance equivalent | 🟡 `agent` browser/CDP automation V1 | `hr` subcommands are still limited to BOSS; Zhilian recruiter side enters through `boss --platform zhilian --role recruiter agent ...` | | Qiancheng/51job (`qiancheng`) | 🚧 Registered placeholder | — | Returns `NOT_SUPPORTED` uniformly, to be accessed after read-only research threshold is met | ```bash boss --platform zhilian search "Python" # Specify platform (also supports --platform zhipin|zhilian|qiancheng) boss config set platform zhilian # Set as default ``` `boss hr ...` currently only supports default recruiter platform `zhipin-recruiter`; Zhilian recruiter side automation uses `agent` command and browser/CDP adapter. Design details see [docs/platform-abstraction.md](docs/platform-abstraction.md). ## 🤖 Agent Integration Recommended reading: [Agent Quickstart](docs/agent-quickstart.md) · [Capability Matrix](docs/capability-matrix.md) · [Host Examples](docs/agent-hosts.md) ```json // Method 1: MCP (recommended) — Claude Desktop/Cursor and other MCP hosts, exposing 50 low-risk and local task tools { "mcpServers": { "boss-agent": { "command": "uvx", "args": ["--from", "boss-agent-cli[mcp]", "boss-mcp"] } } } ``` OpenCode source project can directly use the repository example: ```bash cp examples/opencode/opencode.json ./opencode.json uv sync --all-extras uv run boss-mcp --data-dir ./.boss-agent --help ``` After portable/global installation, use `examples/opencode.json` in any OpenCode project, which will start `boss-mcp --data-dir ./.boss-agent`, allowing review, pending, and logs to be isolated by project. ```bash # Method 2: subprocess — let Agent read capability self-description, then parse stdout JSON boss schema ``` ```python # Method 3: Python direct embedding (released with py.typed, can be used as a typed library) from boss_agent_cli import AuthManager, BossClient, AuthRequired with BossClient(AuthManager(...)) as client: result = client.search_jobs("Golang", city="Guangzhou") ``` ## 📚 Commands `boss schema` exposes 38 top-level commands + 9 recruiter subcommands, grouped by workflow: - **Authentication**: `login` · `logout` · `status` · `doctor` - **Job Discovery**: `search` · `detail` · `show` · `cities` · `history` - **Local Organization**: `watch` · `preset` · `shortlist` · `stats` · `favorites` - **Restricted Research Collection**: `crawl configure/run/start/status/results/resume/stop/shortlist` (only in explicit `operating_mode=research`; MCP only reads or imports existing runs) - **Resume/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` - **System**: `schema` · `platforms` · `export` · `config` · `clean` - **Recruiter**: `hr jobs list/online/offline` - **Restricted Actions (blocked by default low-risk mode)**: `greet` · `batch-greet` · `apply` · `exchange` · `chat*` · `pipeline` · `digest` Complete command table, parameters, and welfare screening principles see **[Command Reference](docs/commands.md)**; capability source is `boss schema` (supporting `--format openai-tools` / `anthropic-tools` to export tool definitions). Batch collection requires additional installation of `uv sync --extra crawl`. It only runs in explicit `operating_mode=research` mode, self-cleaning and exiting `<data-dir>/crawl/chrome-profile`, without taking over daily Chrome profile. No hooks are injected by default; if there are authorized local script requirements, Hook file and directory containing `SHA256SUMS` must be provided: ```powershell boss crawl configure --max-requests 20 --max-details 50 --max-seconds 600 --max-retries 1 boss crawl run "AI" --city Hangzhou --pages 3 --with-detail ` --hook-profile screenshot-full --hook-dir E:\boss-agent-cli-local-hooks\AntiDebug_Breaker boss crawl resume <run_id> boss crawl stop <run_id> boss agent crawl --run-id <run_id> --resume <resume_name> ``` `crawl run` executes sequentially and saves SQLite checkpoints and JSON/CSV/XLSX incremental products; request count, detail count, wall clock time, and retries are all constrained by a fixed budget, and `boss crawl stop` can stop at the next safe point. Export and `crawl results` do not expose `security_id`, job ID, or recruiter fields by default; executing `boss clean --privacy` deletes crawl status, budget, and export. MCP keeps assisted-only, can only read or import existing `run_id` through `crawl_status`, `crawl_results`, and `crawl_shortlist`; creation, recovery, and stopping are completed by explicit Research Mode CLI. Stops and returns recovery commands when encountering platform risk codes or security pages. `boss agent crawl --run-id` only analyzes completed tasks; new real Chrome collection requires setting `operating_mode=research` and passing `--allow-crawl`. ## 🩺 Diagnosis and Troubleshooting ```bash boss doctor # Environment self-test boss status --live # Optional: low-frequency read-only probe boss doctor --live-probe ``` Error envelopes uniformly carry `code` + `recoverable` + `recovery_action`, allowing programmatic recovery. Browser Bridge local diagnosis covers `bridge_daemon` / `bridge_extension` / `bridge_protocol` / `bridge_workspace` / `bridge_exec` / `bridge_fetch` / `bridge_navigate` seven items, with daemon started using `python -m boss_agent_cli.bridge.daemon --serve`. Assisted Mode stops automated access when encountering platform risk control; Research Mode can run explicit risk control adapters, but must run with limited operation, save checkpoints, and allow users to decide whether to continue. Complete inspection items, CDP startup examples, and error codes see **[Diagnosis and Troubleshooting](docs/troubleshooting.md)**; issues related to Cookie/CDP/patchright/request frequency/interface drift are discussed in [Platform Risk Boundary](docs/platform-risk.md). ## ⚙️ Configuration ```bash boss config list # List all configurations boss config set log_level debug # Set log level boss config reset # Reset to default ``` Configurations are located in `~/.boss-agent/config.json`: operating mode (`operating_mode=assisted|research`), request interval, batch greeting interval, log level, CDP address, export directory, platform/role. ## 🏗️ Technical Architecture ``` CLI (Click) └─ Capability Strategy (default assisted; research explicitly enables research capabilities) └─ AuthManager ── User-initiated login state (Fernet + PBKDF2 machine binding encryption) └─ Platform dual registry ── BossPlatform / ZhilianPlatform / QianchengPlatform └─ BossClient ── httpx + throttling (Gaussian delay); compatible with CDP / Bridge / patchright login and export └─ CacheStore (SQLite WAL) · AIService (OpenAI-compatible / Ollama / vLLM) └─ output.py → JSON envelope → stdout ``` `QianchengPlatform (51job placeholder adapter, unified return NOT_SUPPORTED)`: only used for platform registration and schema visibility, requiring read-only research threshold before connecting to real interfaces. **Constants**: stdout only JSON envelope · stderr only logs · `exit 0/1` · error contains `code/recoverable/recovery_action` · `boss schema` is the capability source. **Selection**: Python ≥ 3.10 · Click · httpx · patchright / CDP / Bridge (login, export, and explicit Research Mode adapter) · cryptography (Fernet) · sqlite3 (WAL) · pytest (1400+ items). ## 🔌 Local Storage All states in `~/.boss-agent/`: encrypted login state, search cache, candidate pool, local resume, AI configuration, and external model registration. Model weights do not enter the Python package; data does not leave the machine except for explicit API calls or local model downloads. ## 🤝 Contributors Contributions are welcome: `git clone` → `feat/xxx` branch → write tests → `python scripts/quality_baseline.py` (Windows Chinese system can use `$env:PYTHONUTF8='1'`) → PR. See [CONTRIBUTING.md](CONTRIBUTING.md) for details, and [Getting Started](docs/getting-started.md) for a quick start. Thanks to all contributors who make boss-agent-cli better! ❤️ <a href="https://github.com/can4hou6joeng4/boss-agent-cli/graphs/contributors"> <img src="./CONTRIBUTORS.svg" alt="Contributors" width="1000" /> </a> ## ❤️ Support - If it helps you, the most direct support is to star ⭐ [this repository](https://github.com/can4hou6joeng4/boss-agent-cli) or share it with others who might find it useful. - If you encounter issues or have new ideas, feel free to open an [Issue](https://github.com/can4hou6joeng4/boss-agent-cli/issues); if you're willing to contribute, go ahead and create a PR. - Explore other projects in the same ecosystem, and welcome to visit [bobochang.cn](https://bobochang.cn) 🧭, with navigation records on [Juejin Column](https://juejin.cn/user/1187904004821262). This project benefits from [geekgeekrun](https://github.com/geekgeekrun/geekgeekrun) · [boss-cli](https://github.com/jackwener/boss-cli) · [opencli](https://github.com/jackwener/opencli), thanks to them. ## ⭐ Star History <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/star-history-dark.svg"> <img alt="Star History" src="docs/assets/star-history.svg" width="100%"> </picture> Generated locally by [mystarhistory](https://github.com/carsteneu/mystarhistory) as a static SVG, same origin, no third-party services. ## ⚠️ Disclaimer This project is for learning and local assistance only. Please comply with relevant laws and regulations, BOSS Direct Recruitment platform user agreements, and privacy policies. The default low-risk mode blocks automatic reaching, batch operations, risk avoidance, and candidate personal information processing; any delivery, communication, contact exchange, and recruiter candidate processing should be done manually on the platform's official website. Misuse consequences are borne by the user and are not related to the project author. ## 📑 License & Friendly Links [MIT](LICENSE) © [can4hou6joeng4](https://github.com/can4hou6joeng4) · Friendly link [LINUX DO](https://linux.do/)