boss-resume-downloader

# Boss Resume Downloader

## Purpose

Install and operate a deterministic BOSS/Zhipin recruiter resume synchronization workflow. Standardize the boss-agent-cli command path, CDP endpoint, Chrome launch convention, auth data directory, resume storage root, and resume download fallback logic so that the workflow is reproducible across machines and across agent harnesses (Claude Code, Claude Desktop, Cursor, etc.).

Use this skill for two related goals:

1. Speed up installation and first successful run on a new machine.
2. Let other sessions operate the same BOSS resume synchronization flow without rediscovering CDP paths, Chrome executable locations, boss-agent-cli storage directories, or `securityId` fallback behavior.

## Golden Configuration

Prefer these defaults unless the user explicitly requests otherwise. Paths shown with `~` are POSIX (macOS/Linux); the Windows equivalent uses `%USERPROFILE%`.

| Item | Value (POSIX) | Value (Windows) |
|---|---|---|
| Platform | `zhipin` | `zhipin` |
| Role | `recruiter` | `recruiter` |
| CDP URL | `http://localhost:9222` | `http://localhost:9222` |
| boss command | `boss` (on PATH) | `boss` (on PATH) or `%USERPROFILE%\bin\boss.cmd` |
| boss-agent-cli auth data dir | `~/.boss-agent` | `%USERPROFILE%\.boss-agent` |
| Resume output root | `~/WorkBuddy/boss-resumes` | `%USERPROFILE%\WorkBuddy\boss-resumes` |
| Sync script | `scripts/sync_boss_resumes.py` (relative to this SKILL.md) | same |

Invoke the CLI like this (assumes `boss` is on PATH):

```bash
boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 <command>
```

Important known facts:

- Use platform `zhipin`, not `zhipin-recruiter`.
- Use CDP URL `http://localhost:9222` when recruiter authentication is needed.
- Use auth data directory `~/.boss-agent` (POSIX) / `%USERPROFILE%\.boss-agent` (Windows). Do not guess `.boss-agent-cli`.
- On Windows, if `boss` is not resolvable from subprocess, fall back to `%USERPROFILE%\bin\boss.cmd`.
- Resume viewing requires encrypted geek ID, encrypted job ID, and `securityId`.
- `hr applications` can list applied candidates but may not expose `securityId` in all outputs.
- `hr chat` can expose candidate names but may still omit `securityId`.
- The bundled script can use boss-agent-cli internal `friend_detail(friendIds)` as a fallback to resolve `securityId` from numeric `friendId`. This fallback requires the `boss_agent_cli` Python package to be importable from the active environment.
- `hr candidates` can be used as an additional fallback source.
- Do not assume `encryptFriendId` equals `securityId`.

## Recommended Usage Pattern: Hourly Incremental Sync + Local Analysis

**Strongly recommended over one-shot bulk downloads.**

> ⚠️ **Risk notice — recruiter resume access is sensitive.**
> Recruiter-side resume access is a monitored, high-sensitivity action. Bulk resume screening has been observed to trigger account-level risk controls (rate limiting, CAPTCHA challenges, temporary account restrictions; see upstream issue #232). The patterns and limits in this skill **reduce** that risk but do not eliminate it. Treat any safeguards here — incremental scheduling, randomized delay, per-run/per-job download caps — as **risk-reduction measures, not safety guarantees**. Recruiter accounts may still be limited, challenged, or restricted at any time; monitor for `ACCOUNT_RISK` / `RATE_LIMITED` errors and back off.

### Schedule hourly incremental sync via agent

Use your agent harness's scheduled task capability (e.g., Claude Code `/loop`, cron, or any recurring job) to run `sync-all` every hour:

```bash
# Run once per hour, keep Chrome open in the background
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all
```

In Claude Code you can set this up with:

```
/loop 1h python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all
```

Each run only downloads candidates not yet in `candidate_index.json`, so an hourly job typically only needs to download the few new applicants from the past hour.

**Why this is preferred over a one-shot bulk sync:**

1. **Reduces (does not eliminate) risk-control exposure.** Downloading dozens or hundreds of resumes in one session resembles scraping and is more likely to trigger account risk controls. Spreading work across many small hourly runs lowers — but does not remove — that likelihood. The script also enforces hard per-run/per-job download caps (`--max-downloads-per-run`, `--max-downloads-per-job`) so a single run cannot accidentally produce a bulk-access pattern even if many new candidates accumulated.

2. **Local analysis is fast and free.** Once resumes are on disk as `resume.md`, any analysis (filtering by keyword, comparing candidates, summarizing, ranking) runs entirely locally — no network round-trips, no rate limits, no extra API calls to BOSS.

### Analyze from local Markdown files

After sync, all resumes are at:

```
~/WorkBuddy/boss-resumes/jobs/<jobId>_<jobName>/resumes/<name>_<id>/resume.md
```

To analyze them, read the local files directly. Example prompts that work well once files are synced:

- "Read all resume.md files under ~/WorkBuddy/boss-resumes and shortlist candidates with Python experience."
- "Compare the work experience sections across all downloaded resumes for job <job_name>."
- "Find candidates who mentioned crawler/scrapy/selenium in their resumes."

This is faster and more reliable than querying BOSS live for each analysis question.

---

## First-Time Setup Checklist

### 1. Verify the boss CLI is available

```bash
boss --help
```

If `boss` is not on PATH, locate the installed entrypoint and either add it to PATH or pass it via `--boss-bin` to the bundled script. On Windows the entrypoint is typically `%USERPROFILE%\bin\boss.cmd` (a wrapper around the env's `boss.exe`).

### 2. Start Chrome with a stable CDP endpoint

Prefer an already-running Chrome session that exposes `http://localhost:9222`. If status checks fail because CDP is unavailable, launch Chrome manua