@reconcrap/boss-recruit-mcp 1.0.14 → 1.0.15

package/README.md

@@ -218,11 +218,14 @@ boss-recruit-mcp doctor --port <port>
 - 正式执行前应先单独做一轮参数确认，把已识别参数、待确认项、缺失项、默认值风险分开给用户确认
 - 若用户没提“是否过滤近14天查看”，会在 `pending_questions` 里返回该问题，调用方应先补问再继续
 - 用户未补齐缺失参数时，只有在明确同意默认值及其质量风险后，才允许继续
-- `target_count` 表示“目标处理人数”，不是“目标通过人数”；状态一旦是 `COMPLETED`，就表示本轮已完成，不应因通过人数不足而自动重跑
-- 确认后自动执行：搜索 CLI -> 点击搜索 -> 勾选“过滤近14天查看”（如启用） -> 筛选 CLI
+- `target_count` 表示“目标处理人数”，不是“目标通过人数”；会按“累计处理人数”自动多轮执行，直到达到目标处理人数，或新一轮搜索返回 0 个可筛选人选
+- 若搜索页出现 `i.tip-nodata`（即使仍能看到候选人卡片），也会判定候选池已耗尽并结束多轮流程
+- 第 2 轮及后续轮次会强制 `filter_recent_viewed=true`（即过滤近 14 天查看过的人选），不受首轮开关影响
+- 确认后自动执行：搜索 CLI -> 点击搜索 -> 勾选“过滤近14天查看”（按轮次规则） -> 筛选 CLI
 - 返回摘要：目标数、已处理、通过数、耗时、输出 CSV
 - 执行前会先做本地依赖预检查，若目录 / 入口 / 配置文件缺失则返回 `PIPELINE_PREFLIGHT_FAILED`
 - 若缺少 `favorite-calibration.json`，会返回 `CALIBRATION_REQUIRED`
+- 若某轮搜索返回可筛选候选人但筛选 `processed_count` 非法或为 0，会先导出当前累计 CSV，再返回 `SCREEN_NO_PROGRESS`
 - 若当前运行环境不允许启动子进程，会返回更明确的权限错误码而不是笼统失败
 - 配置文件查找顺序：`BOSS_RECRUIT_SCREEN_CONFIG` > 工作区 `boss-recruit-mcp/config/screening-config.json` > 用户目录 `$CODEX_HOME/boss-recruit-mcp/screening-config.json` > 包内示例配置
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recruit-mcp",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Unified MCP pipeline for boss-search-cli and boss-screen-cli",
   "keywords": [
     "boss",
@@ -20,6 +20,8 @@
     "install:local": "node src/cli.js install",
     "postinstall": "node scripts/postinstall.cjs",
     "test:parser": "node src/test-parser.js",
+    "test:pipeline": "node src/test-pipeline.js",
+    "test:protocol:win": "powershell -ExecutionPolicy Bypass -File scripts/verify-multi-round-protocol.ps1 -Mode unit",
     "test:regression:win": "powershell -ExecutionPolicy Bypass -File scripts/regression.ps1 -Mode quick"
   },
   "files": [

package/src/adapters.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import CDP from "chrome-remote-interface";
 const currentFilePath = fileURLToPath(import.meta.url);
 const packagedMcpDir = path.resolve(path.dirname(currentFilePath), "..");
 const bossSearchUrl = "https://www.zhipin.com/web/chat/search";
@@ -161,6 +162,82 @@ function parseSearchCount(output) {
   return Number.parseInt(m[1], 10);
 }
 
+async function detectSearchNoDataTip(debugPort) {
+  let client = null;
+  try {
+    const targets = await CDP.List({ port: debugPort });
+    const target = targets.find(
+      (item) => typeof item?.url === "string" && item.url.includes("/web/chat/search")
+    ) || targets.find((item) => item?.type === "page");
+    if (!target) {
+      return {
+        ok: false,
+        exhausted: null,
+        error: "No page target found on Chrome DevTools"
+      };
+    }
+
+    client = await CDP({
+      port: debugPort,
+      target
+    });
+    const { Runtime } = client;
+    await Runtime.enable();
+
+    const expression = `(function () {
+      try {
+        var rootDoc = document;
+        var iframe = document.querySelector("iframe");
+        if (iframe && iframe.contentWindow && iframe.contentWindow.document) {
+          rootDoc = iframe.contentWindow.document;
+        }
+        var tip = rootDoc.querySelector("i.tip-nodata");
+        return {
+          exhausted: Boolean(tip),
+          selector: "i.tip-nodata"
+        };
+      } catch (err) {
+        return {
+          exhausted: false,
+          selector: "i.tip-nodata",
+          error: String(err && err.message ? err.message : err)
+        };
+      }
+    })()`;
+    const evaluated = await Runtime.evaluate({
+      expression,
+      returnByValue: true,
+      awaitPromise: true
+    });
+    if (evaluated.exceptionDetails) {
+      return {
+        ok: false,
+        exhausted: null,
+        error: evaluated.exceptionDetails.exception?.description || "Runtime.evaluate failed"
+      };
+    }
+
+    const value = evaluated.result?.value || {};
+    return {
+      ok: true,
+      exhausted: value.exhausted === true,
+      details: value
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      exhausted: null,
+      error: error.message
+    };
+  } finally {
+    if (client) {
+      try {
+        await client.close();
+      } catch {}
+    }
+  }
+}
+
 function parseScreenSummary(output) {
   const processed = output.match(/已处理:\s*(\d+)\s*人/);
   const passed = output.match(/通过筛选:\s*(\d+)\s*人/);
@@ -569,11 +646,18 @@ export async function runSearchCli({ workspaceRoot, searchParams }) {
 
   const combined = `${result.stdout}\n${result.stderr}`;
   const candidateCount = parseSearchCount(combined);
+  const tipCheck = result.code === 0
+    ? await detectSearchNoDataTip(debugPort)
+    : { ok: false, exhausted: null, error: null };
 
   return {
     ok: result.code === 0,
     exit_code: result.code,
     candidate_count: candidateCount,
+    no_data_tip_present: tipCheck.ok ? tipCheck.exhausted : null,
+    no_data_tip_check: tipCheck.ok
+      ? { ok: true, details: tipCheck.details || null }
+      : { ok: false, error: tipCheck.error || null },
     stdout: result.stdout,
     stderr: result.stderr,
     error_code: result.error_code || null

package/src/pipeline.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import { parseRecruitInstruction } from "./parser.js";
 import {
   ensureBossSearchPageReady,
@@ -73,6 +75,92 @@ function buildFailedResponse(code, message, extra = {}) {
   };
 }
 
+function normalizeCsvPath(csvPath) {
+  if (typeof csvPath !== "string") return null;
+  const trimmed = csvPath.trim();
+  if (!trimmed) return null;
+  return path.resolve(trimmed);
+}
+
+function isReadableFile(filePath) {
+  try {
+    if (!filePath || !fs.existsSync(filePath)) return false;
+    const stat = fs.statSync(filePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function collectReadableCsvPaths(csvPaths) {
+  const unique = new Set();
+  for (const rawPath of csvPaths || []) {
+    const normalized = normalizeCsvPath(rawPath);
+    if (!normalized || unique.has(normalized)) continue;
+    if (isReadableFile(normalized)) {
+      unique.add(normalized);
+    }
+  }
+  return Array.from(unique);
+}
+
+function parseCsvContent(content) {
+  const normalized = String(content || "").replace(/^\uFEFF/, "");
+  const lines = normalized.split(/\r?\n/).filter((line) => line.trim() !== "");
+  if (lines.length === 0) return null;
+  return {
+    header: lines[0],
+    rows: lines.slice(1)
+  };
+}
+
+function mergeRoundCsvFiles(csvPaths) {
+  const readablePaths = collectReadableCsvPaths(csvPaths);
+  if (readablePaths.length === 0) return null;
+
+  let header = null;
+  const rows = [];
+
+  for (const csvPath of readablePaths) {
+    let content;
+    try {
+      content = fs.readFileSync(csvPath, "utf8");
+    } catch {
+      continue;
+    }
+    const parsed = parseCsvContent(content);
+    if (!parsed) continue;
+    if (!header) {
+      header = parsed.header;
+    }
+    rows.push(...parsed.rows);
+  }
+
+  if (!header) return null;
+
+  const outputDir = path.dirname(readablePaths[0]);
+  const outputPath = path.join(outputDir, `筛选结果_合并_${Date.now()}.csv`);
+  const mergedContent = `\uFEFF${header}\n${rows.join("\n")}${rows.length > 0 ? "\n" : ""}`;
+  fs.writeFileSync(outputPath, mergedContent, "utf8");
+  return outputPath;
+}
+
+function buildProgressDiagnostics({
+  preflight,
+  totalProcessedCount,
+  totalPassedCount,
+  roundCount,
+  extra = {}
+}) {
+  return {
+    debug_port: preflight.debug_port,
+    total_processed_count: totalProcessedCount,
+    total_passed_count: totalPassedCount,
+    round_count: roundCount,
+    ...extra
+  };
+}
+
 function classifySearchFailure(searchResult) {
   const stderr = searchResult.stderr || "";
   const errorCode = searchResult.error_code || "";
@@ -149,14 +237,29 @@ function classifyScreenFailure(screenResult) {
   };
 }
 
+const defaultDependencies = {
+  parseRecruitInstruction,
+  ensureBossSearchPageReady,
+  runPipelinePreflight,
+  runSearchCli,
+  runScreenCli
+};
+
 export async function runRecruitPipeline({
   workspaceRoot,
   instruction,
   confirmation,
   overrides
-}) {
+}, dependencies = defaultDependencies) {
+  const {
+    parseRecruitInstruction: parseInstruction,
+    ensureBossSearchPageReady: ensureSearchPageReady,
+    runPipelinePreflight: runPreflight,
+    runSearchCli: searchCli,
+    runScreenCli: screenCli
+  } = dependencies;
   const startedAt = Date.now();
-  const parsed = parseRecruitInstruction({
+  const parsed = parseInstruction({
     instruction,
     confirmation,
     overrides
@@ -175,7 +278,7 @@ export async function runRecruitPipeline({
     return buildNeedConfirmationResponse(parsed);
   }
 
-  const preflight = runPipelinePreflight(workspaceRoot);
+  const preflight = runPreflight(workspaceRoot);
   if (!preflight.ok) {
     return buildFailedResponse(
       "PIPELINE_PREFLIGHT_FAILED",
@@ -192,127 +295,241 @@ export async function runRecruitPipeline({
     );
   }
 
-  const pageCheck = await ensureBossSearchPageReady(workspaceRoot, {
-    port: preflight.debug_port
-  });
-  if (!pageCheck.ok) {
-    if (
-      pageCheck.state === "LOGIN_REQUIRED"
-      || pageCheck.state === "LOGIN_REQUIRED_AFTER_REDIRECT"
-    ) {
-      return buildFailedResponse(
-        "BOSS_LOGIN_REQUIRED",
-        "Boss 页面未稳定停留在 search 页面，疑似未登录或登录态失效。请先在当前 Chrome 窗口手动登录 Boss，登录完成后再继续搜索和筛选。",
-        {
-          search_params: parsed.searchParams,
-          screen_params: parsed.screenParams,
-          diagnostics: {
-            debug_port: pageCheck.debug_port,
-            page_state: pageCheck.page_state
-          }
-        }
-      );
-    }
-
+  const initialTargetCount = parsed.screenParams.target_count;
+  if (!Number.isInteger(initialTargetCount) || initialTargetCount <= 0) {
     return buildFailedResponse(
-      "BOSS_SEARCH_PAGE_NOT_READY",
-      "无法确认 Boss search 页面已就绪。请先确保 Chrome 调试端口可连，并且页面能稳定停留在 https://www.zhipin.com/web/chat/search。",
+      "INVALID_TARGET_COUNT",
+      "目标处理人数无效，请确认 target_count 为正整数后重试。",
       {
         search_params: parsed.searchParams,
-        screen_params: parsed.screenParams,
-        diagnostics: {
-          debug_port: pageCheck.debug_port,
-          page_state: pageCheck.page_state
-        }
+        screen_params: parsed.screenParams
       }
     );
   }
 
-  const searchResult = await runSearchCli({
-    workspaceRoot,
-    searchParams: parsed.searchParams
-  });
+  let totalProcessedCount = 0;
+  let totalPassedCount = 0;
+  let roundCount = 0;
+  const roundOutputCsvPaths = [];
 
-  if (!searchResult.ok) {
-    const failure = classifySearchFailure(searchResult);
-    return buildFailedResponse(
-      failure.code,
-      failure.message,
-      {
-        search_params: parsed.searchParams,
-        screen_params: parsed.screenParams,
-        diagnostics: {
-          exit_code: searchResult.exit_code,
-          error_code: searchResult.error_code,
-          stderr: searchResult.stderr?.slice(0, 1200)
-        }
+  while (totalProcessedCount < initialTargetCount) {
+    roundCount += 1;
+
+    const remainingTargetCount = Math.max(0, initialTargetCount - totalProcessedCount);
+    const roundSearchParams = {
+      ...parsed.searchParams,
+      filter_recent_viewed: roundCount >= 2 ? true : parsed.searchParams.filter_recent_viewed
+    };
+    const roundScreenParams = {
+      ...parsed.screenParams,
+      target_count: remainingTargetCount
+    };
+
+    const pageCheck = await ensureSearchPageReady(workspaceRoot, {
+      port: preflight.debug_port
+    });
+    if (!pageCheck.ok) {
+      if (
+        pageCheck.state === "LOGIN_REQUIRED"
+        || pageCheck.state === "LOGIN_REQUIRED_AFTER_REDIRECT"
+      ) {
+        return buildFailedResponse(
+          "BOSS_LOGIN_REQUIRED",
+          "Boss 页面未稳定停留在 search 页面，疑似未登录或登录态失效。请先在当前 Chrome 窗口手动登录 Boss，登录完成后再继续搜索和筛选。",
+          {
+            search_params: roundSearchParams,
+            screen_params: roundScreenParams,
+            diagnostics: buildProgressDiagnostics({
+              preflight,
+              totalProcessedCount,
+              totalPassedCount,
+              roundCount,
+              extra: {
+                page_state: pageCheck.page_state
+              }
+            })
+          }
+        );
       }
-    );
-  }
 
-  if (!Number.isInteger(searchResult.candidate_count)) {
-    return buildFailedResponse(
-      "SEARCH_RESULT_UNVERIFIED",
-      "搜索流程未能确认候选人数量，说明搜索步骤可能没有真正完成，已停止后续筛选。",
-      {
-        search_params: parsed.searchParams,
-        screen_params: parsed.screenParams,
-        diagnostics: {
-          candidate_count: searchResult.candidate_count,
-          stdout: searchResult.stdout?.slice(-1200),
-          stderr: searchResult.stderr?.slice(-1200)
+      return buildFailedResponse(
+        "BOSS_SEARCH_PAGE_NOT_READY",
+        "无法确认 Boss search 页面已就绪。请先确保 Chrome 调试端口可连，并且页面能稳定停留在 https://www.zhipin.com/web/chat/search。",
+        {
+          search_params: roundSearchParams,
+          screen_params: roundScreenParams,
+          diagnostics: buildProgressDiagnostics({
+            preflight,
+            totalProcessedCount,
+            totalPassedCount,
+            roundCount,
+            extra: {
+              page_state: pageCheck.page_state
+            }
+          })
         }
-      }
-    );
-  }
+      );
+    }
 
-  if (searchResult.candidate_count === 0) {
-    return buildFailedResponse(
-      "SEARCH_EMPTY_RESULT",
-      "搜索结果为空，已停止后续筛选。请调整搜索条件后重试。",
-      {
+    const searchResult = await searchCli({
+      workspaceRoot,
+      searchParams: roundSearchParams
+    });
+
+    if (!searchResult.ok) {
+      const failure = classifySearchFailure(searchResult);
+      return buildFailedResponse(
+        failure.code,
+        failure.message,
+        {
+          search_params: roundSearchParams,
+          screen_params: roundScreenParams,
+          diagnostics: buildProgressDiagnostics({
+            preflight,
+            totalProcessedCount,
+            totalPassedCount,
+            roundCount,
+            extra: {
+              exit_code: searchResult.exit_code,
+              error_code: searchResult.error_code,
+              stderr: searchResult.stderr?.slice(0, 1200)
+            }
+          })
+        }
+      );
+    }
+
+    if (!Number.isInteger(searchResult.candidate_count)) {
+      return buildFailedResponse(
+        "SEARCH_RESULT_UNVERIFIED",
+        "搜索流程未能确认候选人数量，说明搜索步骤可能没有真正完成，已停止后续筛选。",
+        {
+          search_params: roundSearchParams,
+          screen_params: roundScreenParams,
+          diagnostics: buildProgressDiagnostics({
+            preflight,
+            totalProcessedCount,
+            totalPassedCount,
+            roundCount,
+            extra: {
+              candidate_count: searchResult.candidate_count,
+              stdout: searchResult.stdout?.slice(-1200),
+              stderr: searchResult.stderr?.slice(-1200)
+            }
+          })
+        }
+      );
+    }
+
+    const exhaustedByTipNoData = searchResult.no_data_tip_present === true;
+    if (exhaustedByTipNoData || searchResult.candidate_count === 0) {
+      const durationSec = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
+      const mergedCsvPath = mergeRoundCsvFiles(roundOutputCsvPaths);
+      return {
+        status: "COMPLETED",
         search_params: parsed.searchParams,
         screen_params: parsed.screenParams,
-        diagnostics: {
-          candidate_count: 0
+        result: {
+          target_count: initialTargetCount,
+          processed_count: totalProcessedCount,
+          passed_count: totalPassedCount,
+          duration_sec: durationSec,
+          output_csv: mergedCsvPath,
+          round_count: roundCount,
+          completion_reason: "search_exhausted_no_candidates",
+          exhausted_by_tip_nodata: exhaustedByTipNoData,
+          target_count_semantics: "target_count means processed candidate count, not passed candidate count"
+        },
+        message: exhaustedByTipNoData
+          ? "流水线已完成。检测到页面出现 tip-nodata（i.tip-nodata），判定候选池已耗尽并结束。"
+          : "流水线已完成。累计处理人数未达到目标前，会自动重跑搜索和筛选；当新一轮搜索无可筛选人选时，按候选池耗尽结束。"
+      };
+    }
+
+    const screenResult = await screenCli({
+      workspaceRoot,
+      screenParams: roundScreenParams
+    });
+
+    if (!screenResult.ok) {
+      const failure = classifyScreenFailure(screenResult);
+      return buildFailedResponse(failure.code, failure.message, {
+        search_params: roundSearchParams,
+        screen_params: roundScreenParams,
+        diagnostics: buildProgressDiagnostics({
+          preflight,
+          totalProcessedCount,
+          totalPassedCount,
+          roundCount,
+          extra: {
+            exit_code: screenResult.exit_code,
+            error_code: screenResult.error_code,
+            stderr: screenResult.stderr?.slice(0, 1200)
+          }
+        })
+      });
+    }
+
+    const summary = screenResult.summary || {};
+    const roundOutputCsvPath = normalizeCsvPath(summary.output_csv);
+    const roundProcessedCount = summary.processed_count;
+
+    if (!Number.isInteger(roundProcessedCount) || roundProcessedCount <= 0) {
+      const mergedCsvPath = mergeRoundCsvFiles([
+        ...roundOutputCsvPaths,
+        roundOutputCsvPath
+      ]);
+      return buildFailedResponse(
+        "SCREEN_NO_PROGRESS",
+        "本轮搜索返回了可筛选候选人，但筛选流程未产生有效处理进度。已先导出当前累计 CSV 结果，请检查页面状态或筛选工具日志后重试。",
+        {
+          search_params: roundSearchParams,
+          screen_params: roundScreenParams,
+          diagnostics: buildProgressDiagnostics({
+            preflight,
+            totalProcessedCount,
+            totalPassedCount,
+            roundCount,
+            extra: {
+              candidate_count: searchResult.candidate_count,
+              round_processed_count: roundProcessedCount ?? null,
+              round_passed_count: summary.passed_count ?? null,
+              round_output_csv: roundOutputCsvPath,
+              output_csv: mergedCsvPath
+            }
+          })
         }
-      }
-    );
-  }
+      );
+    }
 
-  const screenResult = await runScreenCli({
-    workspaceRoot,
-    screenParams: parsed.screenParams
-  });
+    if (roundOutputCsvPath && isReadableFile(roundOutputCsvPath)) {
+      roundOutputCsvPaths.push(roundOutputCsvPath);
+    }
 
-  if (!screenResult.ok) {
-    const failure = classifyScreenFailure(screenResult);
-    return buildFailedResponse(failure.code, failure.message, {
-      search_params: parsed.searchParams,
-      screen_params: parsed.screenParams,
-      diagnostics: {
-        exit_code: screenResult.exit_code,
-        error_code: screenResult.error_code,
-        stderr: screenResult.stderr?.slice(0, 1200)
-      }
-    });
+    const roundPassedCount =
+      Number.isInteger(summary.passed_count) && summary.passed_count >= 0
+        ? summary.passed_count
+        : 0;
+    totalProcessedCount += roundProcessedCount;
+    totalPassedCount += roundPassedCount;
   }
 
   const durationSec = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
-  const summary = screenResult.summary || {};
+  const mergedCsvPath = mergeRoundCsvFiles(roundOutputCsvPaths);
   return {
     status: "COMPLETED",
     search_params: parsed.searchParams,
     screen_params: parsed.screenParams,
     result: {
-      target_count: summary.target_count ?? parsed.screenParams.target_count,
-      processed_count: summary.processed_count ?? null,
-      passed_count: summary.passed_count ?? null,
+      target_count: initialTargetCount,
+      processed_count: totalProcessedCount,
+      passed_count: totalPassedCount,
       duration_sec: durationSec,
-      output_csv: summary.output_csv,
+      output_csv: mergedCsvPath,
+      round_count: roundCount,
       completion_reason: "processed_target_reached",
       target_count_semantics: "target_count means processed candidate count, not passed candidate count"
     },
-    message: "流水线已完成。target_count 表示处理人数目标，而不是通过人数目标；即使通过人数小于 target_count，只要已处理达到目标人数，也应视为本轮完成。"
+    message: "流水线已完成。target_count 表示处理人数目标，而不是通过人数目标；当累计处理人数仍不足时会自动多轮执行，且从第2轮起会强制过滤近14天查看过的人选。"
   };
 }

package/src/test-pipeline.js

@@ -0,0 +1,434 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runRecruitPipeline } from "./pipeline.js";
+
+const CSV_HEADER = "姓名,最高学历学校,最高学历专业,最近工作公司,最近工作职位,评估通过详细原因";
+
+function createTempDir(tag) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `boss-pipeline-${tag}-`));
+}
+
+function writeCsv(filePath, rows) {
+  const body = rows.length > 0 ? `${rows.join("\n")}\n` : "";
+  fs.writeFileSync(filePath, `\uFEFF${CSV_HEADER}\n${body}`, "utf8");
+}
+
+function readCsvLines(filePath) {
+  return fs
+    .readFileSync(filePath, "utf8")
+    .replace(/^\uFEFF/, "")
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== "");
+}
+
+function createParsed(overrides = {}) {
+  return {
+    has_unresolved_missing_fields: false,
+    needs_keyword_confirmation: false,
+    needs_search_params_confirmation: false,
+    needs_recent_viewed_filter_confirmation: false,
+    needs_criteria_confirmation: false,
+    missing_fields: [],
+    proposed_keyword: null,
+    pending_questions: [],
+    review: {},
+    searchParams: {
+      city: "杭州",
+      degree: "本科",
+      schools: ["985院校"],
+      filter_recent_viewed: false,
+      keyword: "AI infra"
+    },
+    screenParams: {
+      criteria: "候选人需有 AI infra 相关经历",
+      target_count: 100
+    },
+    ...overrides
+  };
+}
+
+function buildSearchOk(candidateCount) {
+  return {
+    ok: true,
+    candidate_count: candidateCount,
+    no_data_tip_present: false,
+    no_data_tip_check: { ok: true, details: { exhausted: false } },
+    stdout: "",
+    stderr: "",
+    error_code: null
+  };
+}
+
+function buildScreenOk({ processedCount, passedCount = 0, outputCsv = null }) {
+  return {
+    ok: true,
+    summary: {
+      processed_count: processedCount,
+      passed_count: passedCount,
+      output_csv: outputCsv
+    },
+    stdout: "",
+    stderr: "",
+    error_code: null
+  };
+}
+
+function createDependencies({
+  parsed,
+  searchResults,
+  screenResults,
+  pageStates
+}) {
+  const searchQueue = [...searchResults];
+  const screenQueue = [...screenResults];
+  const pageQueue = pageStates ? [...pageStates] : [];
+  const calls = {
+    searchParams: [],
+    screenParams: [],
+    pageChecks: 0,
+    preflightChecks: 0
+  };
+
+  return {
+    calls,
+    deps: {
+      parseRecruitInstruction: () => parsed,
+      runPipelinePreflight: () => {
+        calls.preflightChecks += 1;
+        return {
+          ok: true,
+          checks: [],
+          debug_port: 9222,
+          calibration_path: null
+        };
+      },
+      ensureBossSearchPageReady: async () => {
+        calls.pageChecks += 1;
+        if (pageQueue.length > 0) {
+          return pageQueue.shift();
+        }
+        return {
+          ok: true,
+          state: "SEARCH_READY",
+          debug_port: 9222,
+          page_state: {}
+        };
+      },
+      runSearchCli: async ({ searchParams }) => {
+        calls.searchParams.push({ ...searchParams });
+        if (searchQueue.length === 0) {
+          throw new Error("runSearchCli called more times than expected");
+        }
+        return searchQueue.shift();
+      },
+      runScreenCli: async ({ screenParams }) => {
+        calls.screenParams.push({ ...screenParams });
+        if (screenQueue.length === 0) {
+          throw new Error("runScreenCli called more times than expected");
+        }
+        return screenQueue.shift();
+      }
+    }
+  };
+}
+
+async function testSearchExhaustedCompletesAndMergesCsv() {
+  const tempDir = createTempDir("exhausted");
+  const round1Csv = path.join(tempDir, "round-1.csv");
+  writeCsv(round1Csv, [
+    "张三,清华大学,计算机,甲公司,算法工程师,理由A"
+  ]);
+
+  const parsed = createParsed({
+    screenParams: {
+      criteria: "候选人需有 AI infra 相关经历",
+      target_count: 100
+    }
+  });
+  const { deps, calls } = createDependencies({
+    parsed,
+    searchResults: [buildSearchOk(160), buildSearchOk(0)],
+    screenResults: [
+      buildScreenOk({
+        processedCount: 80,
+        passedCount: 12,
+        outputCsv: round1Csv
+      })
+    ]
+  });
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "COMPLETED");
+  assert.equal(result.result.completion_reason, "search_exhausted_no_candidates");
+  assert.equal(result.result.processed_count, 80);
+  assert.equal(result.result.passed_count, 12);
+  assert.equal(result.result.round_count, 2);
+  assert.equal(calls.searchParams[0].filter_recent_viewed, false);
+  assert.equal(calls.searchParams[1].filter_recent_viewed, true);
+  assert.ok(result.result.output_csv && fs.existsSync(result.result.output_csv));
+  const mergedLines = readCsvLines(result.result.output_csv);
+  assert.equal(mergedLines.length, 2);
+}
+
+async function testSearchExhaustedByTipNodataEvenWhenCandidateCountPositive() {
+  const tempDir = createTempDir("exhausted-tip");
+  const round1Csv = path.join(tempDir, "round-1.csv");
+  writeCsv(round1Csv, [
+    "赵六,浙大,电子信息,戊公司,工程师,理由D"
+  ]);
+
+  const parsed = createParsed({
+    screenParams: {
+      criteria: "候选人需有 AI infra 相关经历",
+      target_count: 100
+    }
+  });
+  const { deps, calls } = createDependencies({
+    parsed,
+    searchResults: [
+      buildSearchOk(120),
+      {
+        ...buildSearchOk(87),
+        no_data_tip_present: true,
+        no_data_tip_check: {
+          ok: true,
+          details: {
+            exhausted: true,
+            selector: "i.tip-nodata"
+          }
+        }
+      }
+    ],
+    screenResults: [
+      buildScreenOk({
+        processedCount: 80,
+        passedCount: 4,
+        outputCsv: round1Csv
+      })
+    ]
+  });
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "COMPLETED");
+  assert.equal(result.result.completion_reason, "search_exhausted_no_candidates");
+  assert.equal(result.result.exhausted_by_tip_nodata, true);
+  assert.equal(result.result.processed_count, 80);
+  assert.equal(result.result.round_count, 2);
+  assert.equal(calls.searchParams[1].filter_recent_viewed, true);
+}
+
+async function testTargetReachedAcrossRoundsAndDuplicateRowsKept() {
+  const tempDir = createTempDir("target");
+  const round1Csv = path.join(tempDir, "round-1.csv");
+  const round2Csv = path.join(tempDir, "round-2.csv");
+  const dupRow = "重复候选人,北大,计算机,乙公司,后端工程师,重复原因";
+  writeCsv(round1Csv, [
+    "张三,清华大学,计算机,甲公司,算法工程师,理由A",
+    dupRow
+  ]);
+  writeCsv(round2Csv, [
+    dupRow,
+    "李四,复旦大学,软件工程,丙公司,推荐算法工程师,理由B"
+  ]);
+
+  const parsed = createParsed({
+    screenParams: {
+      criteria: "候选人需有 AI infra 相关经历",
+      target_count: 100
+    }
+  });
+  const { deps, calls } = createDependencies({
+    parsed,
+    searchResults: [buildSearchOk(120), buildSearchOk(120)],
+    screenResults: [
+      buildScreenOk({
+        processedCount: 60,
+        passedCount: 5,
+        outputCsv: round1Csv
+      }),
+      buildScreenOk({
+        processedCount: 40,
+        passedCount: 8,
+        outputCsv: round2Csv
+      })
+    ]
+  });
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "COMPLETED");
+  assert.equal(result.result.completion_reason, "processed_target_reached");
+  assert.equal(result.result.processed_count, 100);
+  assert.equal(result.result.passed_count, 13);
+  assert.equal(result.result.round_count, 2);
+  assert.equal(calls.searchParams[0].filter_recent_viewed, false);
+  assert.equal(calls.searchParams[1].filter_recent_viewed, true);
+  assert.equal(calls.screenParams[1].target_count, 40);
+
+  const mergedLines = readCsvLines(result.result.output_csv);
+  assert.equal(mergedLines.length, 5);
+  const duplicateCount = mergedLines.filter((line) => line === dupRow).length;
+  assert.equal(duplicateCount, 2);
+}
+
+async function testScreenNoProgressWithZeroProcessedExportsBeforeFail() {
+  const tempDir = createTempDir("no-progress-zero");
+  const round1Csv = path.join(tempDir, "round-1.csv");
+  const round2Csv = path.join(tempDir, "round-2.csv");
+  writeCsv(round1Csv, [
+    "张三,清华大学,计算机,甲公司,算法工程师,理由A"
+  ]);
+  writeCsv(round2Csv, [
+    "王五,浙大,软件工程,丁公司,算法工程师,理由C"
+  ]);
+
+  const parsed = createParsed({
+    screenParams: {
+      criteria: "候选人需有 AI infra 相关经历",
+      target_count: 100
+    }
+  });
+  const { deps } = createDependencies({
+    parsed,
+    searchResults: [buildSearchOk(120), buildSearchOk(120)],
+    screenResults: [
+      buildScreenOk({
+        processedCount: 80,
+        passedCount: 9,
+        outputCsv: round1Csv
+      }),
+      buildScreenOk({
+        processedCount: 0,
+        passedCount: 0,
+        outputCsv: round2Csv
+      })
+    ]
+  });
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "FAILED");
+  assert.equal(result.error.code, "SCREEN_NO_PROGRESS");
+  assert.equal(result.diagnostics.total_processed_count, 80);
+  assert.equal(result.diagnostics.round_count, 2);
+  assert.ok(result.diagnostics.output_csv && fs.existsSync(result.diagnostics.output_csv));
+  const mergedLines = readCsvLines(result.diagnostics.output_csv);
+  assert.equal(mergedLines.length, 3);
+}
+
+async function testScreenNoProgressWithInvalidProcessedAndNoCsv() {
+  const tempDir = createTempDir("no-progress-invalid");
+  const parsed = createParsed({
+    screenParams: {
+      criteria: "候选人需有 AI infra 相关经历",
+      target_count: 60
+    }
+  });
+  const { deps } = createDependencies({
+    parsed,
+    searchResults: [buildSearchOk(88)],
+    screenResults: [
+      buildScreenOk({
+        processedCount: null,
+        passedCount: 0,
+        outputCsv: null
+      })
+    ]
+  });
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "FAILED");
+  assert.equal(result.error.code, "SCREEN_NO_PROGRESS");
+  assert.equal(result.diagnostics.round_count, 1);
+  assert.equal(result.diagnostics.output_csv, null);
+}
+
+async function testNeedInputGateStillWorks() {
+  const tempDir = createTempDir("need-input");
+  const parsed = createParsed({
+    has_unresolved_missing_fields: true,
+    missing_fields: ["city"]
+  });
+  let preflightCalled = false;
+  const deps = {
+    parseRecruitInstruction: () => parsed,
+    runPipelinePreflight: () => {
+      preflightCalled = true;
+      return { ok: true, checks: [], debug_port: 9222, calibration_path: null };
+    },
+    ensureBossSearchPageReady: async () => ({ ok: true, state: "SEARCH_READY", debug_port: 9222, page_state: {} }),
+    runSearchCli: async () => buildSearchOk(0),
+    runScreenCli: async () => buildScreenOk({ processedCount: 0, passedCount: 0, outputCsv: null })
+  };
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "NEED_INPUT");
+  assert.equal(preflightCalled, false);
+}
+
+async function main() {
+  await testSearchExhaustedCompletesAndMergesCsv();
+  await testSearchExhaustedByTipNodataEvenWhenCandidateCountPositive();
+  await testTargetReachedAcrossRoundsAndDuplicateRowsKept();
+  await testScreenNoProgressWithZeroProcessedExportsBeforeFail();
+  await testScreenNoProgressWithInvalidProcessedAndNoCsv();
+  await testNeedInputGateStillWorks();
+  // eslint-disable-next-line no-console
+  console.log("pipeline tests passed");
+}
+
+await main();