boss-zhipin-scraper

BOSS Zhipin Personal Job-Seeking Workflow

Run the task as a state machine with confirmation gates:

ONBOARD → PROFILE → PREFERENCES → SEARCH_CONFIRM → LOGIN_CHECK
→ CALIBRATE → RECOMMEND_TIERS → OUTREACH_CONFIRM → EXECUTE_LOOP → REVIEW

Do not skip the required input or confirmation of the current state. Information already provided by the user is inherited directly and not asked for again.

Mandatory Boundaries

• Only for the user's own job search.
• Only operate the dedicated Chrome Profile whose window title contains BOSS-Agent , and perform visible interactions on official pages through macOS Computer Use.
• BOSS CLI, CDP, remote debugging, Bridge, Patchright, Playwright, headless browsers, hidden APIs,/wapi, XHR/fetch injection, Cookie or stoken extraction, proxy rotation, fingerprint spoofing, and CAPTCHA bypass are prohibited.
• Operating rules are based only on this file and the references/ it directly references; old CLI, CDP, script dependencies, or virtual environment routes must not be reintroduced.
• Login, QR code scanning, and CAPTCHAs are completed manually by the user. CAPTCHAs and authentication information must not be read, filled in on behalf of the user, or saved.
• Search and calibration are read-only by default. Until OUTREACH_CONFIRM is passed, do not favorite, apply, greet, exchange contact information, or modify account status.
• Automatic greeting does not include automatic application, exchanging contact information, modifying the online resume, job expectations, privacy, or account settings.
• The user starting a Goal, saying "start searching," or confirming the search card does not equal authorization to send messages.

State Machine

1. ONBOARD: First-time guidance

First guide the user to upload a resume; images, PDF, Word, or pasted text are supported. If there is no formal resume, guide the user to provide years of work experience, most recent position, main projects, skills, and education.

Extract only job-matching information; unrelated privacy such as name, phone number, and email must not be proactively echoed or written into the report. Abilities not shown in the resume should be written as "not demonstrated" and must not be inferred as present.

For the complete script, fields, and no-resume path, see references/onboarding-profile.md。

2. PROFILE: Echo the resume profile

Echo years of work experience, position/industry, product type, project evidence, quantified results, skills, education, transferable abilities, and items not demonstrated. Let the user correct facts, but do not ask them to repeat content already in the resume.

3. PREFERENCES: Complete preferences in two rounds

Ask at most 3 questions per round that would change the search results:

1. Round 1: target position or reference JD, city/remote, minimum salary;
2. Round 2: JD experience upper limit, mandatory exclusions, optional company/industry/commute preferences.

Skip fields already specified; the reference JD is optional and is not a prerequisite for starting.

4. SEARCH_CONFIRM: Search confirmation gate

Generate a search confirmation card that includes at least: resume profile, city, position, search terms, salary, experience upper limit, job type, mandatory exclusions, sorting preferences, calibration sample size, and "zero messages" at this stage.

Only after the user confirms the search card or explicitly confirms equivalent content may the BOSS page be operated. Search confirmation only authorizes read-only calibration.

5. LOGIN_CHECK: Connect the dedicated browser

1. Connect to the visible regular Chrome, and operate only the BOSS-Agent Profile; ask the user to bring it to the foreground.
2. Reuse the https://www.zhipin.com/ tab first; do not operate other Profiles.
3. Perform read-only checks of the domain, login status, and security verification; do not submit additional searches for testing.
4. If not logged in, stop and ask the user to log in manually; after the user says "logged in", check again.
5. After each page action, re-read the latest UI state; reusing stale element indices is prohibited.

6. CALIBRATE: read-only market calibration

• By default, read 15–30 job cards, and from them select about 10 representative complete JDs.
• First read the list, historical deduplication, and hard-condition pre-screening, then open JDs that have not yet been fully read and may have analytical value.
• The sample covers types such as high match, borderline, high salary but high requirements, vertical industry, suspected sales/overseas assignment, and conflicts between the list and the JD.
• In this stage, the number of external actions must be 0; greeting, favoriting, or applying is not allowed.
• The complete JD takes precedence over list tags; for missing fields, write "not shown on page/to be verified".
• Calibration samples are only used to determine market requirements, scoring thresholds, and search direction, and are unrelated to the subsequent target greeting count. The number of qualifying positions in the sample must not be treated as the upper limit for the outreach batch.

For detailed calibration, scoring, and sample selection, see references/calibration-tiering.md。

7. RECOMMEND_TIERS: provide dynamic tiers

Based on the real JDs in this batch and the user's resume, output: market profile, existing evidence, transferable abilities, hard gaps, recommended search directions, and the three tiers A precise/B balanced/C opportunity.

Tiers cannot be based only on total score; they must simultaneously pass:

1. the user's hard conditions;
2. the tier total score threshold;
3. thresholds for core dimensions such as job direction, resume skills, and experience;
4. risk veto items.

Thresholds are dynamically suggested based on this batch's sample; the default reference is A≥85, B≥80, C≥72, but they must not be forcibly applied before calibration.

8. OUTREACH_CONFIRM: outreach confirmation gate

Before sending the first message, you must echo back and have the user confirm:

• the search scope and tiers for this batch;
• the target greeting count for this batch; if unspecified, proactively ask, with a default suggestion of 20 , and do not silently fill it in;
• the hard conditions, core score thresholds, and risk veto items for automatic outreach;
• how borderline positions are handled;
• greeting mode: the platform default greeting, or a custom template and the allowed scope of personalization;
• explicitly prohibited actions involving applications, contact information, and account modifications;
• authorization is valid only for this batch.

Vague expressions such as "use your judgment", "you decide", or "start searching" do not constitute outreach authorization. For the complete confirmation card and template rules, see references/outreach-authorization.md。

9. EXECUTE_LOOP: continuous search, per-job judgment, and outreach

The outreach target is based on this batch's target_outreach_count , not on the calibration sample size, the current number of result pages, or the number of qualifying positions in the first batch. As long as the target has not been reached and no real hard stop has been triggered, continue searching for new positions within the confirmed scope.

Each position is executed in strict serial order:

读列表 → 查历史台账 → 读完整 JD → 硬条件过滤
→ 逐项评分 → 风险检查 → 档位判断 → 触达或归档 → 写检查点

• If the user-selected tier is reached and there are no veto items: send a lightly personalized greeting using the approved skeleton.
• When the user approves "platform default greeting", it is allowed to click "Chat Now" to trigger the platform's built-in greeting; after sending, record the actual text displayed on the page. The platform default text must not be rewritten as resume facts.
• Near the threshold or one item pending verification: enter the pending confirmation list, do not send.
• Hard exclusion hit, insufficient information, or incomplete JD read: do not send.
• Already communicated, already sent, or historical status unknown: do not send again; mark as pending confirmation if necessary.
• Messages may only use experience evidenced in the resume; AI, Agent, RAG, large model, or industry experience must not be fabricated.
• After the user adjusts the rules, only subsequent positions are affected; no retroactive resending.
• target_outreach_count and outreach_sent only count the "number of unique positions with confirmed successful sends". Resent messages for the same position are not counted again;unknown, failures, already communicated, duplicate positions, and skipped positions are not counted toward the target.
• After each click of "立即沟通", strictly execute the transaction order: re-read the UI → confirm the send result → write the position ledger → update the batch count → write the outreach audit. Until all of the above writes succeed, the next position must not be read or contacted.
• Only when the page explicitly shows "已向BOSS发送消息" or the chat record shows delivered, count that unique position toward outreach_sent, and update remaining_outreach_count. When outreach_sent >= target_outreach_count , the outreach batch ends normally.
• When any checkpoint write fails, stop subsequent external actions, keep the current page, and continue after repairing the ledger; do not send the next message first and then batch backfill records.
• When the current keyword or results page has no more qualifying positions, switch to the next search term or results page in the confirmation card and continue; do not end early just because the calibration sample has been processed.

10. REVIEW: Batch review

Report the list card, unique positions, duplicate skips, complete JD, automatic outreach, pending confirmation, exclusions, failures, risk control, and cumulative data; give the most common strengths and gaps in this batch and whether an adjustment is recommended.

For ledger fields, checkpoints, and acceptance cases, see references/ledger-acceptance.md。

Transient UI state recovery

When Computer Use returns The user changed '/Applications/Google Chrome.app'、Computer Use is not active or a similar prompt such as "state has changed/needs to be re-read", do not conclude that the user has taken over based solely on that prompt, and do not immediately mark partial。

Recover in the following order:

1. Immediately call get_app_state to obtain the full latest state; this is a state reconnection and does not count as automatically retrying the page action.
2. The verification window is still BOSS-Agent, the domain is still zhipin.com, the login indicator is present, the current page matches expectations, and there is no security verification.
3. If the result of the previous action may already have taken effect, first confirm the result from the latest page, chat record, or "已向BOSS发送消息" prompt; do not click repeatedly before the result is confirmed.
4. If the state is normal, continue from the current step; do not require the user to say "continue" again, and do not start a new batch.

Recover running or partial batch: reconcile before operating: read the batch's last checkpoint, position ledger, outreach audit, and current UI; if the page shows that the previous step was sent but the ledger does not record it, first fill in that unique position and batch count. Do not send new messages before reconciliation is complete.

Only when the user explicitly says "I'll take over/stop", or after refresh you observe the mouse, keyboard, or page being continuously operated externally, is it determined that the user has taken over.

Risk control hard stop

If any of the following occurs, immediately save the checkpoint and stop the current batch:

• CAPTCHA, security verification,_security_check, 429, code 37, frequent access, account risk, or environment anomaly;
• Jumping back to the login page, login state becoming invalid, a blank error page, or an unexpected page;
• The page requires copying cookies, installing suspicious extensions, or executing scripts outside the site;
• The user explicitly takes over the browser or explicitly stops; a single tool status change prompt does not constitute evidence of takeover.

After stopping, do not automatically retry, change keywords, turn pages, log in again, switch tools, or switch back to an old route in the same attempt. Report marked partial, record the actual completed quantity and the sole unlock action.

Batching, Deduplication, and Pacing

• Before starting a batch, read ~/.boss-zhipin-scraper/ledger/job_ledger.jsonl and batches.jsonl。
• Deduplication priority: job link after removing query parameters → job ID → weak key of company + job + location.
• Save a search checkpoint after every 15 cards, every results page, and every keyword; after each external action, immediately save a send checkpoint in the transaction order of EXECUTE_LOOP.
• Keep it serial, single-click, and single-page read; do not operate pages concurrently.
• Do not set a fixed pause, batch interval, or cooldown countdown; base the next step on page load completion and the latest UI state.
• A batch must save target_outreach_count、outreach_sent and remaining_outreach_count. The normal completion condition is reaching the target number, not exhausting the calibration sample.
• When the user pauses, mark the batch as partial, saving the number of unique positions confirmed sent and the remaining number; when resuming, continue from the remaining number, not start over from the target total.

Scoring Baseline

Dimension	Weight
Job direction match	25
Resume skill match	25
Experience fit	15
Salary fit	10
Location fit	10
Company fit	10
HR activity	5

Hard conditions and risk vetoes take precedence over the total score. Each judgment must provide matching evidence, risks/gaps, and itemized scores; no evidence means no points may be added.

Success Criteria

• First-time guidance, profile, two rounds of preferences, and two confirmation gates are all completed according to status;
• The number of external actions during the calibration phase is 0;
• Any message has this batch's tier, target quantity and greeting mode authorization, complete JD, score, risk check, and audit record;
• The calibration sample size is separated from the target greeting count; the execution phase continues until reaching target_outreach_count or triggering a real hard stop;
• No CLI, CDP, Playwright, hidden API, cookie, or anti-detection capability was used;
• No duplicate outreach, no unauthorized submission, and no account modification;
• Each outreach completes the four checkpoints of UI confirmation, job ledger, batch count, and outreach audit before the next page action;
• The ledger, report, and partial status are reviewable;
• Stop immediately when risk control is triggered.