boss-resume-downloader

Boss Resume Downloader

目的

決定論的な BOSS/Zhipin 採用担当者向け履歴書同期ワークフローをインストールして運用します。boss-agent-cli のコマンドパス、CDP エンドポイント、Chrome の起動規約、認証データディレクトリ、履歴書の保存先ルート、履歴書ダウンロードのフォールバックロジックを標準化し、マシン間および各種エージェントハーネス（Claude Code、Claude Desktop、Cursor など）でワークフローを再現できるようにします。

このスキルは、次の2つの関連する目的に使用します。

1. 新しいマシンでのインストールと初回実行の成功を速めます。
2. 他のセッションでも、CDP パス、Chrome 実行ファイルの場所、boss-agent-cli の保存ディレクトリ、securityId のフォールバック動作を再調査せずに、同じ BOSS 履歴書同期フローを実行できるようにします。

基本設定

ユーザーが明示的に別の設定を求めない限り、以下のデフォルトを優先してください。~ を含むパスは POSIX（macOS/Linux）形式です。Windows では %USERPROFILE% を使用します。

項目	値（POSIX）	値（Windows）
プラットフォーム	zhipin	zhipin
ロール	recruiter	recruiter
CDP URL	http://localhost:9222	http://localhost:9222
boss コマンド	boss（PATH 上）	boss（PATH 上）または %USERPROFILE%\bin\boss.cmd
boss-agent-cli 認証データディレクトリ	~/.boss-agent	%USERPROFILE%\.boss-agent
履歴書の出力先ルート	~/WorkBuddy/boss-resumes	%USERPROFILE%\WorkBuddy\boss-resumes
同期スクリプト	scripts/sync_boss_resumes.py（この SKILL.md からの相対パス）	同じ

CLI は次のように実行します（boss が PATH 上にあることが前提です）。

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

重要な既知の事実：

• プラットフォームには zhipin-recruiter ではなく zhipin を使用してください。
• 採用担当者の認証が必要な場合は、CDP URL http://localhost:9222 を使用してください。
• 認証データディレクトリには POSIX では ~/.boss-agent、Windows では %USERPROFILE%\.boss-agent を使用してください。.boss-agent-cli と推測しないでください。
• Windows でサブプロセスから boss を解決できない場合は、%USERPROFILE%\bin\boss.cmd にフォールバックしてください。
• 履歴書の閲覧には、暗号化された geek ID、暗号化された job ID、securityId が必要です。
• hr applications では応募者を一覧表示できますが、すべての出力に securityId が含まれるとは限りません。
• hr chat では候補者名を取得できますが、securityId が省略される場合があります。
• 同梱スクリプトは、数値の friendId から securityId を解決するためのフォールバックとして、boss-agent-cli 内部の friend_detail(friendIds) を使用できます。このフォールバックには、アクティブな環境から boss_agent_cli Python パッケージをインポートできることが必要です。
• 追加のフォールバックソースとして hr candidates を使用できます。
• encryptFriendId が securityId と同じだと想定しないでください。

推奨される使用パターン：1時間ごとの増分同期＋ローカル分析

一括ダウンロードを一度だけ行う方法より、こちらを強く推奨します。

⚠️ リスクに関する注意 — 採用担当者による履歴書へのアクセスは慎重に扱う必要があります。 採用担当者側からの履歴書へのアクセスは監視対象となる、機微性の高い操作です。履歴書を一括でスクリーニングすると、アカウント単位のリスク制御が作動することが確認されています（レート制限、CAPTCHA チャレンジ、一時的なアカウント制限。上流の issue #232 を参照）。このスキルのパターンと制限はリスクを軽減しますが、完全になくすものではありません。ここに記載されている保護策（増分スケジュール、ランダムな遅延、実行ごと／求人ごとのダウンロード上限）は、リスク軽減策であり、安全を保証するものではありません。採用担当者アカウントは、いつでも制限、チャレンジ、または制約を受ける可能性があります。ACCOUNT_RISK／RATE_LIMITED エラーを監視し、発生した場合は処理を控えてください。

エージェントで毎時の増分同期をスケジュールする

エージェントハーネスのスケジュールタスク機能（Claude Code の /loop、cron、または定期実行ジョブなど）を使って、毎時 sync-all を実行します。

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

Claude Code では、次のように設定できます。

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

各実行では、candidate_index.json にまだ登録されていない候補者のみをダウンロードするため、毎時のジョブで通常ダウンロードするのは、過去1時間に応募した数名の新しい候補者だけです。

一括同期を一度だけ実行するよりも、この方法を推奨する理由：

1. リスク管理の対象となる可能性を軽減します（なくすことはできません）。 1回のセッションで数十件、数百件の履歴書をダウンロードすると、スクレイピングのように見え、アカウントのリスク管理を引き起こす可能性が高まります。作業を多数の小規模な毎時実行に分散させることで、その可能性を下げられますが、なくすことはできません。また、このスクリプトは実行単位およびジョブ単位のダウンロード数に上限（--max-downloads-per-run、--max-downloads-per-job）を設けているため、新しい候補者が多数蓄積していても、1回の実行で意図せず一括アクセスのようなパターンが発生することはありません。

2. ローカルでの分析は高速かつ無料です。 履歴書を resume.md としてディスクに保存すれば、キーワードによる絞り込み、候補者の比較、要約、順位付けなどの分析はすべてローカルで実行されます。ネットワーク通信も、レート制限も、BOSS への追加 API 呼び出しもありません。

ローカルの Markdown ファイルから分析する

同期後、すべての履歴書は次の場所にあります。

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

分析するには、ローカルファイルを直接読み込みます。ファイルの同期後に有効なプロンプトの例：

• 「~/WorkBuddy/boss-resumes 以下にあるすべての resume.md ファイルを読み込み、Python の経験がある候補者を絞り込んでください。」
• 「ダウンロード済みのすべての履歴書について、職務経験のセクションを求人 <job_name> ごとに比較してください。」
• 「履歴書に crawler／scrapy／selenium と記載している候補者を見つけてください。」

分析のたびに BOSS にリアルタイムで問い合わせるより、高速で信頼性の高い方法です。

---

初回セットアップのチェックリスト

1. boss CLI が使用可能であることを確認する

boss --help

boss が PATH にない場合は、インストール済みのエントリーポイントを探し、PATH に追加するか、同梱スクリプトに --boss-bin で渡します。Windows では、通常、エントリーポイントは %USERPROFILE%\bin\boss.cmd（環境内の boss.exe を呼び出すラッパー）です。

2. 安定した CDP エンドポイントで Chrome を起動する

http://localhost:9222 を公開している、すでに実行中の Chrome セッションを優先してください。CDP を利用できないためにステータス確認が失敗する場合は、リモートデバッグを有効にし、専用プロファイルを指定して Chrome を手動で起動します。一般的な実行ファイルの場所：

• macOS：/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux：PATH 上の google-chrome または chromium
• Windows：C:\Program Files\Google\Chrome\Application\chrome.exe、C:\Program Files (x86)\Google\Chrome\Application\chrome.exe、または %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe

推奨する起動形式：

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.workbuddy/chrome-profiles/boss-cdp"

# Linux
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.workbuddy/chrome-profiles/boss-cdp"

:: Windows
"<chrome.exe>" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.workbuddy\chrome-profiles\boss-cdp"

ポート 9222 が使用中でない限り、CDP ポートやプロファイルディレクトリをランダムに変更しないでください。

3. 採用担当者としてログインしていることを確認する

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 status

ログインしていない場合は、CDP ログインを実行し、ブラウザー上で必要な QR コードの読み取りやログイン操作をユーザーに完了してもらいます。

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 login --cdp

4. オンライン中の求人を確認する

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr jobs list

コマンドが想定される採用担当者の求人を返してから、次に進みます。

デフォルトの保存先

ユーザーが別のディレクトリを指定しない限り、履歴書の保存先には次のデフォルトを使用します。

• POSIX：~/WorkBuddy/boss-resumes
• Windows：%USERPROFILE%\WorkBuddy\boss-resumes

想定される構成：

boss-resumes/
  config.json
  job_index.json
  jobs/
    <jobId>_<safeJobName>/
      job.json
      candidate_index.json
      resumes/
        <safeCandidateName>_<candidateId>/
          resume.json
          resume.md
          raw_response.json

主なワークフロー

1. ログイン状態と求人を確認する

まずステータスを確認します。認証されていない場合、または認証の有効期限が切れている場合は、CDP ログインフローを使用します。

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 status
boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr jobs list

現在オンライン中のすべての求人を、安定した求人 ID と暗号化された求人 ID をキーとして job_index.json に保存します。

2. 求人ごとのディレクトリを作成する

オンライン中の各求人について、次の名前のディレクトリを作成します。

<jobId>_<safeJobName>

未加工の求人メタデータを job.json に保存します。

3. 応募済み候補者を一覧表示する

各求人について、暗号化された求人 ID がある場合は、それを使って応募情報を取得します。

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr applications --job-id <encryptJobId>

CLI の出力でページが残っていることが示された場合は、ページネーションを行います。

4. 再開に必要なパラメーターを解決する

適用対象の候補者ごとに、以下を解決します。

• encryptGeekId / 暗号化された候補者 ID
• 表示名
• securityId
• 該当する暗号化された求人 ID

まず applications を使用します。securityId がない場合は、数値の friendId を使って、内部の boss-agent-cli friend_detail(friendIds) API から解決します。このエンドポイントは、候補者名、securityId、encryptUid、jobId、encryptJobId を返します。追加のフォールバック情報源としてのみ、hr candidates または hr chat を使用します。encryptFriendId が securityId と同じだと仮定しないでください。

securityId を解決できない場合は、候補者を candidate_index.json に pending_security_id として記録し、その候補者の履歴書のダウンロードをスキップします。恒久的な失敗として扱わないでください。

5. オンライン履歴書をダウンロードする

すべてのパラメーターがそろったら、以下を呼び出します。

boss --role recruiter --platform zhipin --cdp-url http://localhost:9222 hr resume <encryptGeekId> --job-id <encryptJobId> --security-id <securityId>

以下を保存します。

• 生の JSON レスポンスを raw_response.json として保存
• 正規化した JSON を resume.json として保存
• 読みやすい Markdown 形式の履歴書を resume.md として保存

6. 差分処理

ダウンロードする前に、candidate_index.json を確認します。

以下の場合は候補者をスキップします。

• 候補者 ID がインデックスに存在する
• 履歴書のステータスが downloaded である
• --force オプションが指定されていない

以下の場合は候補者を更新します。

• 新しい候補者である
• 前回のステータスが pending_security_id、failed、または partial だった
• --force が指定されている

7. ランダムな待機時間

一括ダウンロード中は、候補者のダウンロードが成功した場合または試行された場合に、その間にランダムな待機時間を設けます。

3-6 seconds

ドライランまたは一覧表示のみの操作では、待機しないでください。

同梱スクリプト

スクリプトは、この SKILL.md と同じ場所にある scripts/sync_boss_resumes.py にあります。${SKILL_DIR} をこの SKILL.md が含まれるディレクトリに解決し、以下を呼び出します。

# Sync all online jobs incrementally
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all

# Sync all online jobs with command echoing; --verbose is a global option and must be placed before the subcommand
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" --verbose sync-all

# Sync one job by numeric jobId or encrypted jobId
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-job --job-id <jobId>

# Refresh job index only
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" refresh-jobs

# Dry run without downloading resumes
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all --dry-run

# Override per-run / per-job download caps (defaults: 20 per run, 10 per job)
python "${SKILL_DIR}/scripts/sync_boss_resumes.py" sync-all \
  --max-downloads-per-run 50 --max-downloads-per-job 20

このスクリプトは、1 回の実行で多数の新しい候補者が蓄積していても、一括アクセスのようなパターンが発生しないように、デフォルトで慎重なダウンロード上限を適用します。

フラグ	デフォルト	意味
--max-downloads-per-run	20	実行全体の履歴書ダウンロード数に対するハード上限です。上限に達すると、実行は正常に停止します（現在の求人の処理を完了した後、以降の求人は処理されません）。
--max-downloads-per-job	10	1 件の求人内での履歴書ダウンロード数に対するハード上限です。上限に達すると、その求人の候補者ループが正常に終了し、次の求人に進みます。

上限に達した場合も、実行は ok: true で終了します。概要の stopped_due_to_limit フィールドには（"run"、"job"、または null）が設定され、未処理の作業が残っていることと、次回のスケジュール実行で今回の続きから再開されることがわかります。

boss_agent_cli をインポートできる Python インタープリターを使用してください。そうでない場合、friend_detail のフォールバックは無効になります。この場合、スクリプトは（--verbose を指定すると）標準エラー出力に警告を表示します。

PATH に boss がない場合は、--boss-bin <path> で上書きするか、環境に BOSS_BIN=<path> を設定してください。

トラブルシューティング

症状	考えられる原因	対処方法
unrecognized arguments: --verbose	グローバルオプションがサブコマンドの後に指定されている	--verbose を sync-all または sync-job の前に置いてください
[WinError 2] 系统找不到指定的文件 / FileNotFoundError: boss	サブプロセスが PATH 上で boss を見つけられない	--boss-bin <path> を渡すか、BOSS_BIN を設定してください。Windows では %USERPROFILE%\bin\boss.cmd を使用します
ブラウザーにはログイン済みなのに、ログインしていないと表示される	認証データのディレクトリが間違っている	--data-dir ~/.boss-agent を使用してください（Windows の場合は %USERPROFILE%\.boss-agent）
CDP 接続が拒否される	Chrome がリモートデバッグを有効にして起動されていない	--remote-debugging-port=9222 を指定して Chrome を再起動してください
すべての候補者が pending_security_id になっている	applications の出力に securityId がなく、内部フォールバックも失敗している	boss_agent_cli をインポートできる Python でスクリプトを実行するか、--verbose を指定してインポートエラーを確認してください
zhipin-recruiter プラットフォームエラー	プラットフォーム名が間違っている	--platform zhipin を使用してください
Applications のページ送りが 100 ページ目で停止した	ハード上限に達した	対象の求人に絞って再実行するか、他のフィルターで分割してください。上限に達すると、スクリプトは標準エラー出力に警告を表示します

出力要件

同期のたびに、以下を報告してください。

• 履歴書のルートディレクトリ
• 検出した求人
• 更新した求人
• 検出した候補者
• ダウンロードした履歴書
• 既存のためスキップした履歴書
• securityId が未設定の候補者
• 正確なエラーメッセージを含む失敗
• ダウンロード上限に達したため実行が早期終了したかどうか

同期成功時のエンベロープの形式：

{
  "ok": true,
  "resume_root": "<resolved path>",
  "mode": "sync-all",
  "stopped_due_to_limit": null,
  "totals": {
    "candidates_discovered": 0,
    "downloaded": 0,
    "skipped_existing": 0,
    "pending_security_id": 0,
    "failed": 0
  }
}

stopped_due_to_limit には、null（最後まで実行）、"run"（実行全体の上限に到達）、または "job"（少なくとも1件の求人で求人ごとの上限に到達）のいずれかが設定されます。

安全性とエチケット

• 候補者にメッセージを送信しないでください。
• 求人のオンライン／オフライン状態を変更しないでください。
• 同期中に以前の履歴書やインデックスを削除しないでください。
• デバッグ用に生の API レスポンスを保持してください。
• BOSS のデータは非公開の採用データとして扱ってください。
• 配布可能なスキルパッケージに、ダウンロードした候補者の履歴書を含めないでください。