@reconcrap/boss-recommend-mcp 1.3.38 → 2.0.0

package/src/domains/recruit/search.js

@@ -0,0 +1,1149 @@
+import {
+  clearFocusedInput,
+  clickNodeCenter,
+  countSelectors,
+  describeNode,
+  findFirstNode,
+  getAttributesMap,
+  getOuterHTML,
+  insertText,
+  pressKey,
+  querySelector,
+  querySelectorAll,
+  sleep
+} from "../../core/browser/index.js";
+import {
+  htmlToText,
+  normalizeText
+} from "../../core/screening/index.js";
+import {
+  RECRUIT_CARD_SELECTOR,
+  RECRUIT_TARGET_URL,
+  RECRUIT_NO_DATA_SELECTORS,
+  RECRUIT_SEARCH_SELECTORS
+} from "./constants.js";
+import {
+  getRecruitRoots,
+  waitForRecruitRoots
+} from "./roots.js";
+
+const DEFAULT_RECRUIT_KEYWORD = "算法工程师";
+const ACTIVE_CLASS_PATTERN = /\b(active|selected|checked|cur|current)\b/i;
+const DEFAULT_RECRUIT_RESET_TIMEOUT_MS = 180000;
+const DEFAULT_RECRUIT_SEARCH_TIMEOUT_MS = 90000;
+const DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS = 30000;
+const DEFAULT_RECRUIT_CITY_NO_RESULT_FALLBACK_MS = 15000;
+
+const DEGREE_LABEL_MAP = new Map([
+  ["不限", "不限"],
+  ["本科", "本科"],
+  ["本科及以上", "本科"],
+  ["硕士", "硕士"],
+  ["硕士及以上", "硕士"],
+  ["博士", "博士"]
+]);
+
+const NATIONAL_CITY_LABELS = new Set([
+  "全国",
+  "不限",
+  "不限城市",
+  "全部",
+  "All",
+  "ALL",
+  "all"
+]);
+
+const CITY_NO_RESULT_LABELS = new Set([
+  "暂无结果",
+  "暂无数据",
+  "无结果"
+]);
+
+function uniqueNodeIds(nodeIds = []) {
+  return Array.from(new Set(nodeIds.filter(Boolean)));
+}
+
+function buildRecruitSearchFrameUrl(pageUrl = RECRUIT_TARGET_URL) {
+  const origin = new URL(pageUrl).origin;
+  return `${origin}/web/frame/search/?jobId=&keywords=&t=${Date.now()}&source=&city=`;
+}
+
+async function navigateRecruitSearchFrame(client, iframeNodeId, {
+  pageUrl = RECRUIT_TARGET_URL,
+  reason = "reset_frame"
+} = {}) {
+  if (!iframeNodeId || typeof client?.Page?.navigate !== "function") return null;
+  const iframeNode = await describeNode(client, iframeNodeId, { depth: 1, pierce: true });
+  const frameId = iframeNode?.frameId;
+  if (!frameId) return null;
+  const frameUrl = buildRecruitSearchFrameUrl(pageUrl);
+  await client.Page.navigate({ frameId, url: frameUrl });
+  return {
+    method: "Page.navigate",
+    scope: "frame",
+    frame_id: frameId,
+    url: frameUrl,
+    reason
+  };
+}
+
+export function normalizeRecruitSearchLabel(label) {
+  return normalizeText(label).replace(/\s+/g, "");
+}
+
+export function buildRecruitJobTitleSearchTerms(jobTitle) {
+  const normalized = normalizeText(jobTitle);
+  if (!normalized) return [];
+  const variants = [
+    normalized,
+    normalized.replace(/\s*[_＿]\s*/g, " "),
+    normalized.replace(/\s*[｜|]\s*/g, " ")
+  ].map(normalizeText).filter(Boolean);
+  const separatorParts = normalized.split(/\s*[_＿｜|]\s*/).map(normalizeText).filter(Boolean);
+  if (separatorParts.length > 1) {
+    variants.push(separatorParts.join(" "));
+    variants.push(separatorParts[0]);
+  }
+  return Array.from(new Set(variants));
+}
+
+export function isRecruitNationalCity(city) {
+  return NATIONAL_CITY_LABELS.has(normalizeRecruitSearchLabel(city));
+}
+
+export function resolveRecruitDegreeLabel(degree) {
+  const normalized = normalizeRecruitSearchLabel(degree || "不限");
+  return DEGREE_LABEL_MAP.get(normalized) || normalized || "不限";
+}
+
+export function normalizeRecruitDegreeLabels(value) {
+  const rawItems = Array.isArray(value)
+    ? value
+    : typeof value === "string"
+      ? value.split(/[，,、|/]/)
+      : [];
+  const labels = rawItems
+    .map(resolveRecruitDegreeLabel)
+    .filter(Boolean);
+  const uniqueLabels = uniqueNodeIds(labels);
+  return uniqueLabels.length ? uniqueLabels : ["不限"];
+}
+
+export function normalizeRecruitSearchParams(searchParams = {}) {
+  const degrees = normalizeRecruitDegreeLabels(searchParams.degrees || searchParams.degree || "不限");
+  const normalized = {
+    city: normalizeText(searchParams.city) || null,
+    degree: degrees[0] || "不限",
+    degrees,
+    schools: Array.isArray(searchParams.schools)
+      ? searchParams.schools.map(normalizeText).filter(Boolean)
+      : [],
+    keyword: normalizeText(searchParams.keyword) || DEFAULT_RECRUIT_KEYWORD,
+    filter_recent_viewed: typeof searchParams.filter_recent_viewed === "boolean"
+      ? searchParams.filter_recent_viewed
+      : null
+  };
+  const job = normalizeText(searchParams.job || searchParams.job_title || searchParams.selected_job);
+  if (job) normalized.job = job;
+  return normalized;
+}
+
+export function hasRecruitSearchParams(searchParams = {}) {
+  const degrees = normalizeRecruitDegreeLabels(searchParams.degrees || searchParams.degree || "不限");
+  const job = normalizeText(searchParams.job || searchParams.job_title || searchParams.selected_job);
+  const normalized = {
+    city: normalizeText(searchParams.city) || null,
+    degree: degrees[0] || "不限",
+    degrees,
+    schools: Array.isArray(searchParams.schools)
+      ? searchParams.schools.map(normalizeText).filter(Boolean)
+      : [],
+    keyword: normalizeText(searchParams.keyword),
+    filter_recent_viewed: typeof searchParams.filter_recent_viewed === "boolean"
+      ? searchParams.filter_recent_viewed
+      : null
+  };
+  return Boolean(
+    job
+    || normalized.city
+    || normalized.degrees.some((degree) => degree && degree !== "不限")
+    || normalized.schools.length
+    || normalized.keyword
+    || typeof normalized.filter_recent_viewed === "boolean"
+  );
+}
+
+function candidateIsActive(attributes = {}, outerHTML = "") {
+  const className = attributes.class || "";
+  const openingTag = String(outerHTML || "").split(">")[0] || "";
+  return ACTIVE_CLASS_PATTERN.test(className)
+    || ACTIVE_CLASS_PATTERN.test(openingTag)
+    || /\bchecked(?:=["']?checked)?\b/i.test(openingTag);
+}
+
+async function readTextCandidate(client, nodeId, {
+  selector = "",
+  index = 0
+} = {}) {
+  const [attributes, outerHTML] = await Promise.all([
+    getAttributesMap(client, nodeId),
+    getOuterHTML(client, nodeId)
+  ]);
+  const text = normalizeText(htmlToText(outerHTML));
+  return {
+    node_id: nodeId,
+    selector,
+    index,
+    label: normalizeRecruitSearchLabel(text),
+    text,
+    active: candidateIsActive(attributes, outerHTML),
+    class_name: attributes.class || "",
+    attributes
+  };
+}
+
+async function listTextCandidates(client, rootNodeId, selectors = []) {
+  const candidates = [];
+  const seen = new Set();
+  for (const selector of selectors) {
+    const nodeIds = uniqueNodeIds(await querySelectorAll(client, rootNodeId, selector));
+    for (let index = 0; index < nodeIds.length; index += 1) {
+      const nodeId = nodeIds[index];
+      if (seen.has(nodeId)) continue;
+      seen.add(nodeId);
+      candidates.push(await readTextCandidate(client, nodeId, { selector, index }));
+    }
+  }
+  return candidates;
+}
+
+export function chooseRecruitTextCandidate(candidates = [], {
+  label = "",
+  match = "exact"
+} = {}) {
+  const target = normalizeRecruitSearchLabel(label);
+  if (!target) return null;
+  const byExact = candidates.find((candidate) => candidate.label === target);
+  if (byExact) return byExact;
+  if (match === "exact") return null;
+  const byPrefix = candidates.find((candidate) => (
+    candidate.label.startsWith(target)
+    || target.startsWith(candidate.label)
+  ));
+  if (byPrefix) return byPrefix;
+  if (match === "prefix") return null;
+  return candidates.find((candidate) => candidate.label.includes(target) || target.includes(candidate.label)) || null;
+}
+
+async function findTextCandidate(client, rootNodeId, selectors, label, options = {}) {
+  const candidates = await listTextCandidates(client, rootNodeId, selectors);
+  return {
+    candidate: chooseRecruitTextCandidate(candidates, { label, ...options }),
+    candidates
+  };
+}
+
+function summarizeTextCandidates(candidates = [], limit = 20) {
+  return candidates.map((item) => ({
+    label: item.text,
+    active: item.active,
+    node_id: item.node_id,
+    selector: item.selector
+  })).slice(0, limit);
+}
+
+async function waitForRecruitTextCandidate(client, rootNodeId, selectors, label, {
+  timeoutMs = DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS,
+  intervalMs = 300,
+  match = "exact"
+} = {}) {
+  const started = Date.now();
+  let candidate = null;
+  let candidates = [];
+  while (Date.now() - started <= timeoutMs) {
+    const found = await findTextCandidate(client, rootNodeId, selectors, label, { match });
+    candidate = found.candidate;
+    candidates = found.candidates;
+    if (candidate) break;
+    await sleep(intervalMs);
+  }
+  return {
+    candidate,
+    candidates,
+    elapsed_ms: Date.now() - started
+  };
+}
+
+async function waitForRecruitJobTitleCandidate(client, rootNodeId, selectors, jobTitle, {
+  timeoutMs = DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS,
+  intervalMs = 300
+} = {}) {
+  const terms = buildRecruitJobTitleSearchTerms(jobTitle);
+  const started = Date.now();
+  let candidate = null;
+  let candidates = [];
+  let matchedTerm = "";
+  while (Date.now() - started <= timeoutMs) {
+    candidates = await listTextCandidates(client, rootNodeId, selectors);
+    for (const term of terms) {
+      const found = chooseRecruitTextCandidate(candidates, { label: term, match: "contains" });
+      if (found) {
+        candidate = found;
+        matchedTerm = term;
+        break;
+      }
+    }
+    if (candidate) break;
+    await sleep(intervalMs);
+  }
+  return {
+    candidate,
+    candidates,
+    matched_term: matchedTerm,
+    search_terms: terms,
+    elapsed_ms: Date.now() - started
+  };
+}
+
+async function clickFirstNodeBySelectors(client, rootNodeId, selectors, {
+  optional = false,
+  scrollIntoView = true
+} = {}) {
+  const found = await findFirstNode(client, rootNodeId, selectors);
+  if (!found) {
+    if (optional) return { clicked: false, reason: "not_found" };
+    throw new Error(`Recruit search node was not found for selectors: ${selectors.join(", ")}`);
+  }
+  try {
+    const box = await clickNodeCenter(client, found.nodeId, { scrollIntoView });
+    await sleep(250);
+    return {
+      clicked: true,
+      selector: found.selector,
+      node_id: found.nodeId,
+      box
+    };
+  } catch (error) {
+    if (optional) {
+      return {
+        clicked: false,
+        reason: "not_clickable",
+        selector: found.selector,
+        node_id: found.nodeId,
+        error: error?.message || String(error)
+      };
+    }
+    throw error;
+  }
+}
+
+export async function getRecruitSearchCounts(client, frameNodeId) {
+  return countSelectors(client, frameNodeId, {
+    keyword_input: RECRUIT_SEARCH_SELECTORS.keywordInput.join(", "),
+    search_button: RECRUIT_SEARCH_SELECTORS.searchButton.join(", "),
+    degree_option: RECRUIT_SEARCH_SELECTORS.degreeOption.join(", "),
+    school_item: RECRUIT_SEARCH_SELECTORS.schoolItem.join(", "),
+    recent_viewed_label: RECRUIT_SEARCH_SELECTORS.recentViewedLabel.join(", "),
+    candidate_card: RECRUIT_CARD_SELECTOR,
+    no_data: RECRUIT_NO_DATA_SELECTORS.join(", ")
+  });
+}
+
+export async function waitForRecruitSearchControls(client, {
+  timeoutMs = DEFAULT_RECRUIT_SEARCH_TIMEOUT_MS,
+  intervalMs = 300
+} = {}) {
+  const started = Date.now();
+  let lastState = null;
+  while (Date.now() - started <= timeoutMs) {
+    const roots = await getRecruitRoots(client, { requireFrame: false });
+    const frameNodeId = roots.iframe?.documentNodeId;
+    if (frameNodeId) {
+      const counts = await getRecruitSearchCounts(client, frameNodeId);
+      lastState = {
+        ok: counts.keyword_input > 0 && counts.search_button > 0,
+        elapsed_ms: Date.now() - started,
+        iframe_selector: roots.iframe.selector,
+        iframe_document_node_id: frameNodeId,
+        counts
+      };
+      if (lastState.ok) return lastState;
+    }
+    await sleep(intervalMs);
+  }
+  return {
+    ok: false,
+    elapsed_ms: Date.now() - started,
+    ...(lastState || {})
+  };
+}
+
+export async function resetRecruitSearchPage(client, {
+  url = RECRUIT_TARGET_URL,
+  settleMs = 5000,
+  timeoutMs = DEFAULT_RECRUIT_RESET_TIMEOUT_MS
+} = {}) {
+  const actions = [];
+  const rootTimeoutMs = Math.min(timeoutMs, 90000);
+  async function waitForRootsAfterSettle() {
+    await sleep(settleMs);
+    return waitForRecruitRoots(client, {
+      timeoutMs: rootTimeoutMs,
+      intervalMs: 300
+    });
+  }
+
+  async function waitForControls() {
+    return waitForRecruitSearchControls(client, {
+      timeoutMs,
+      intervalMs: 300
+    });
+  }
+
+  if (typeof client?.Page?.reload === "function") {
+    await client.Page.reload({ ignoreCache: true });
+    actions.push({ method: "Page.reload" });
+  } else {
+    await client.Page.navigate({ url });
+    actions.push({ method: "Page.navigate", url });
+  }
+
+  let roots = await waitForRootsAfterSettle();
+  const frameReset = await navigateRecruitSearchFrame(client, roots?.iframe?.nodeId, {
+    pageUrl: url,
+    reason: "reset_frame_after_page_reload"
+  });
+  if (frameReset) {
+    actions.push(frameReset);
+    await sleep(settleMs);
+  }
+
+  let controls = await waitForControls();
+  if (!controls.ok && typeof client?.Page?.navigate === "function") {
+    await client.Page.navigate({ url });
+    actions.push({
+      method: "Page.navigate",
+      url,
+      reason: roots?.iframe?.documentNodeId ? "controls_not_ready" : "iframe_not_ready"
+    });
+    roots = await waitForRootsAfterSettle();
+    const fallbackFrameReset = await navigateRecruitSearchFrame(client, roots?.iframe?.nodeId, {
+      pageUrl: url,
+      reason: "reset_frame_after_page_navigate"
+    });
+    if (fallbackFrameReset) {
+      actions.push(fallbackFrameReset);
+      await sleep(settleMs);
+    }
+    controls = await waitForControls();
+  }
+  roots = await getRecruitRoots(client, { requireFrame: false });
+  if (!controls.ok && !roots?.iframe?.documentNodeId) {
+    throw new Error("Recruit search page reset did not expose searchFrame iframe");
+  }
+  if (!controls.ok) {
+    throw new Error("Recruit search page reset exposed iframe but search controls were not ready");
+  }
+  return {
+    actions,
+    target_url: url,
+    iframe_selector: controls.iframe_selector || roots.iframe.selector,
+    iframe_document_node_id: controls.iframe_document_node_id || roots.iframe.documentNodeId,
+    controls
+  };
+}
+
+export async function setRecruitKeyword(client, frameNodeId, keyword) {
+  const normalizedKeyword = normalizeText(keyword);
+  if (!normalizedKeyword) {
+    return { applied: false, reason: "empty_keyword" };
+  }
+  const input = await clickFirstNodeBySelectors(client, frameNodeId, RECRUIT_SEARCH_SELECTORS.keywordInput);
+  await clearFocusedInput(client);
+  await sleep(120);
+  await insertText(client, normalizedKeyword);
+  await sleep(350);
+  return {
+    applied: true,
+    keyword: normalizedKeyword,
+    input
+  };
+}
+
+export async function selectRecruitDefaultJobTitle(client, frameNodeId) {
+  return clickFirstNodeBySelectors(client, frameNodeId, RECRUIT_SEARCH_SELECTORS.jobTitleOption, {
+    optional: true
+  });
+}
+
+export async function setRecruitJobTitle(client, frameNodeId, jobTitle, {
+  optionTimeoutMs = DEFAULT_RECRUIT_SEARCH_TIMEOUT_MS
+} = {}) {
+  const normalizedJobTitle = normalizeText(jobTitle);
+  if (!normalizedJobTitle) {
+    return { applied: false, reason: "empty_job_title" };
+  }
+  const lookup = await waitForRecruitJobTitleCandidate(
+    client,
+    frameNodeId,
+    RECRUIT_SEARCH_SELECTORS.jobTitleOption,
+    normalizedJobTitle,
+    { timeoutMs: Math.min(optionTimeoutMs, 30000) }
+  );
+  if (!lookup.candidate) {
+    throw new Error(`Recruit job title option was not found: ${normalizedJobTitle}`);
+  }
+  let box = null;
+  if (!lookup.candidate.active) {
+    box = await clickNodeCenter(client, lookup.candidate.node_id, { scrollIntoView: true });
+    await sleep(500);
+  }
+  return {
+    applied: true,
+    requested_job: normalizedJobTitle,
+    selected_label: lookup.candidate.text,
+    matched_term: lookup.matched_term,
+    search_terms: lookup.search_terms,
+    selected_node_id: lookup.candidate.node_id,
+    was_active: lookup.candidate.active,
+    clicked: !lookup.candidate.active,
+    box,
+    discovered_options: summarizeTextCandidates(lookup.candidates, 30)
+  };
+}
+
+export async function setRecruitDegree(client, frameNodeId, degree) {
+  const degreeLabel = resolveRecruitDegreeLabel(degree);
+  if (!degreeLabel || degreeLabel === "不限") {
+    return { applied: false, reason: "unlimited_degree", degree: degreeLabel || "不限" };
+  }
+  const { candidate, candidates } = await findTextCandidate(
+    client,
+    frameNodeId,
+    RECRUIT_SEARCH_SELECTORS.degreeOption,
+    degreeLabel,
+    { match: "prefix" }
+  );
+  if (!candidate) {
+    throw new Error(`Recruit degree option was not found: ${degreeLabel}`);
+  }
+  const box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+  await sleep(350);
+  return {
+    applied: true,
+    requested_degree: degree,
+    selected_label: candidate.text,
+    selected_node_id: candidate.node_id,
+    was_active: candidate.active,
+    box,
+    discovered_options: candidates.map((item) => ({
+      label: item.text,
+      active: item.active,
+      node_id: item.node_id,
+      selector: item.selector
+    }))
+  };
+}
+
+export async function setRecruitDegrees(client, frameNodeId, degrees = []) {
+  const labels = normalizeRecruitDegreeLabels(degrees).filter((label) => label && label !== "不限");
+  if (!labels.length) {
+    return { applied: false, reason: "unlimited_degree", degrees: ["不限"], selected: [] };
+  }
+
+  const selected = [];
+  let discoveredOptions = [];
+  for (const label of labels) {
+    const { candidate, candidates } = await findTextCandidate(
+      client,
+      frameNodeId,
+      RECRUIT_SEARCH_SELECTORS.degreeOption,
+      label,
+      { match: "prefix" }
+    );
+    discoveredOptions = candidates.map((item) => ({
+      label: item.text,
+      active: item.active,
+      node_id: item.node_id,
+      selector: item.selector
+    }));
+    if (!candidate) {
+      throw new Error(`Recruit degree option was not found: ${label}`);
+    }
+
+    let box = null;
+    if (!candidate.active) {
+      box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+      await sleep(350);
+    }
+    selected.push({
+      requested_degree: label,
+      selected_label: candidate.text,
+      selected_node_id: candidate.node_id,
+      was_active: candidate.active,
+      clicked: !candidate.active,
+      box
+    });
+  }
+
+  return {
+    applied: true,
+    requested_degrees: labels,
+    selected,
+    discovered_options: discoveredOptions
+  };
+}
+
+async function findClickableDescendant(client, nodeId, selectors) {
+  for (const selector of selectors) {
+    const childNodeId = await querySelector(client, nodeId, selector);
+    if (childNodeId) return { node_id: childNodeId, selector };
+  }
+  return { node_id: nodeId, selector: null };
+}
+
+export async function setRecruitSchools(client, frameNodeId, schools = []) {
+  const targets = schools.map(normalizeText).filter(Boolean);
+  const applied = [];
+  const missing = [];
+  if (!targets.length) {
+    return { applied: false, schools: [], selected: [], missing: [] };
+  }
+
+  for (const school of targets) {
+    const { candidate, candidates } = await findTextCandidate(
+      client,
+      frameNodeId,
+      RECRUIT_SEARCH_SELECTORS.schoolItem,
+      school,
+      { match: "contains" }
+    );
+    if (!candidate) {
+      missing.push({
+        school,
+        discovered: candidates.map((item) => item.text).slice(0, 20)
+      });
+      continue;
+    }
+
+    const clickable = await findClickableDescendant(client, candidate.node_id, RECRUIT_SEARCH_SELECTORS.schoolClickable);
+    let clickableActive = candidate.active;
+    if (clickable.node_id !== candidate.node_id) {
+      const clickableCandidate = await readTextCandidate(client, clickable.node_id, {
+        selector: clickable.selector || "",
+        index: 0
+      });
+      clickableActive = clickableActive || clickableCandidate.active;
+    }
+
+    let box = null;
+    if (!clickableActive) {
+      box = await clickNodeCenter(client, clickable.node_id, { scrollIntoView: true });
+      await sleep(350);
+    }
+
+    applied.push({
+      school,
+      selected_label: candidate.text,
+      selected_node_id: candidate.node_id,
+      clickable_node_id: clickable.node_id,
+      clickable_selector: clickable.selector,
+      was_active: clickableActive,
+      clicked: !clickableActive,
+      box
+    });
+  }
+
+  if (missing.length) {
+    throw new Error(`Recruit school options were not found: ${missing.map((item) => item.school).join(", ")}`);
+  }
+
+  return {
+    applied: true,
+    schools: targets,
+    selected: applied,
+    missing
+  };
+}
+
+export async function setRecruitRecentViewedFilter(client, frameNodeId, enabled) {
+  if (typeof enabled !== "boolean") {
+    return { applied: false, reason: "not_requested" };
+  }
+  const { candidate, candidates } = await findTextCandidate(
+    client,
+    frameNodeId,
+    RECRUIT_SEARCH_SELECTORS.recentViewedLabel,
+    "过滤近14天查看",
+    { match: "contains" }
+  );
+  if (!candidate) {
+    throw new Error("Recruit recent-viewed filter was not found");
+  }
+
+  let box = null;
+  if (candidate.active !== enabled) {
+    box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+    await sleep(900);
+  }
+
+  return {
+    applied: true,
+    requested: enabled,
+    was_active: candidate.active,
+    changed: candidate.active !== enabled,
+    selected_label: candidate.text,
+    selected_node_id: candidate.node_id,
+    box,
+    discovered_options: candidates.map((item) => ({
+      label: item.text,
+      active: item.active,
+      node_id: item.node_id,
+      selector: item.selector
+    }))
+  };
+}
+
+async function selectRecruitNationalCityThroughPicker(client, frameNodeId, {
+  requestedCity = "全国",
+  reason = "national_city_requested",
+  optionTimeoutMs = DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS
+} = {}) {
+  const input = await clickFirstNodeBySelectors(client, frameNodeId, RECRUIT_SEARCH_SELECTORS.cityInput);
+  await clearFocusedInput(client);
+  await sleep(500);
+
+  const path = [];
+  const categoryLookup = await waitForRecruitTextCandidate(
+    client,
+    frameNodeId,
+    RECRUIT_SEARCH_SELECTORS.citySearchResult,
+    "城市",
+    { match: "exact", timeoutMs: Math.min(optionTimeoutMs, 6000) }
+  );
+  if (categoryLookup.candidate) {
+    const box = await clickNodeCenter(client, categoryLookup.candidate.node_id, { scrollIntoView: true });
+    await sleep(400);
+    path.push({
+      label: "城市",
+      selected_label: categoryLookup.candidate.text,
+      node_id: categoryLookup.candidate.node_id,
+      box
+    });
+  } else {
+    path.push({
+      label: "城市",
+      skipped: true,
+      reason: "not_found_or_already_expanded",
+      discovered_options: summarizeTextCandidates(categoryLookup.candidates)
+    });
+  }
+
+  let popularLookup = await waitForRecruitTextCandidate(
+    client,
+    frameNodeId,
+    RECRUIT_SEARCH_SELECTORS.cityProvinceItem,
+    "热门",
+    { match: "exact", timeoutMs: optionTimeoutMs }
+  );
+  if (!popularLookup.candidate) {
+    popularLookup = await waitForRecruitTextCandidate(
+      client,
+      frameNodeId,
+      RECRUIT_SEARCH_SELECTORS.citySearchResult,
+      "热门",
+      { match: "exact", timeoutMs: Math.min(optionTimeoutMs, 6000) }
+    );
+  }
+  if (!popularLookup.candidate) {
+    return {
+      applied: false,
+      reason: "national_city_popular_not_found",
+      requested_city: requestedCity,
+      input,
+      path,
+      discovered_options: summarizeTextCandidates(popularLookup.candidates)
+    };
+  }
+  const popularBox = await clickNodeCenter(client, popularLookup.candidate.node_id, { scrollIntoView: true });
+  await sleep(400);
+  path.push({
+    label: "热门",
+    selected_label: popularLookup.candidate.text,
+    node_id: popularLookup.candidate.node_id,
+    box: popularBox
+  });
+
+  let nationalLookup = await waitForRecruitTextCandidate(
+    client,
+    frameNodeId,
+    RECRUIT_SEARCH_SELECTORS.cityDropdownItem,
+    "全国",
+    { match: "exact", timeoutMs: optionTimeoutMs }
+  );
+  if (!nationalLookup.candidate) {
+    nationalLookup = await waitForRecruitTextCandidate(
+      client,
+      frameNodeId,
+      RECRUIT_SEARCH_SELECTORS.citySearchResult,
+      "全国",
+      { match: "exact", timeoutMs: Math.min(optionTimeoutMs, 6000) }
+    );
+  }
+  if (!nationalLookup.candidate) {
+    return {
+      applied: false,
+      reason: "national_city_option_not_found",
+      requested_city: requestedCity,
+      input,
+      path,
+      discovered_options: summarizeTextCandidates(nationalLookup.candidates)
+    };
+  }
+
+  const nationalBox = await clickNodeCenter(client, nationalLookup.candidate.node_id, { scrollIntoView: true });
+  await sleep(700);
+  path.push({
+    label: "全国",
+    selected_label: nationalLookup.candidate.text,
+    node_id: nationalLookup.candidate.node_id,
+    box: nationalBox
+  });
+
+  return {
+    applied: true,
+    reason,
+    city: "全国",
+    requested_city: requestedCity,
+    selected_label: nationalLookup.candidate.text,
+    selected_node_id: nationalLookup.candidate.node_id,
+    input,
+    path,
+    box: nationalBox,
+    selection_mode: "city_picker",
+    picker_path: ["城市", "热门", "全国"]
+  };
+}
+
+async function resetRecruitCityToNational(client, {
+  requestedCity = "",
+  reason = "national_city_frame_reset",
+  optionTimeoutMs = DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS
+} = {}) {
+  const roots = await getRecruitRoots(client, { requireFrame: false });
+  const reset = await navigateRecruitSearchFrame(client, roots?.iframe?.nodeId, { reason });
+  if (!reset) {
+    return {
+      applied: false,
+      reason: "national_city_frame_reset_unavailable",
+      requested_city: requestedCity
+    };
+  }
+  await sleep(1500);
+  const controls = await waitForRecruitSearchControls(client, {
+    timeoutMs: Math.max(optionTimeoutMs, DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS),
+    intervalMs: 300
+  });
+  return {
+    applied: controls.ok,
+    reason,
+    city: "全国",
+    requested_city: requestedCity,
+    selected_label: "全国",
+    selection_mode: "frame_reset",
+    reset,
+    controls,
+    reacquire_frame: true
+  };
+}
+
+export async function setRecruitCity(client, frameNodeId, city, {
+  optionTimeoutMs = DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS
+} = {}) {
+  const normalizedCity = normalizeText(city);
+  if (!normalizedCity) {
+    return { applied: false, reason: "empty_city" };
+  }
+  if (isRecruitNationalCity(normalizedCity)) {
+    return selectRecruitNationalCityThroughPicker(client, frameNodeId, {
+      requestedCity: normalizedCity,
+      reason: "national_city_requested",
+      optionTimeoutMs
+    });
+  }
+
+  const input = await clickFirstNodeBySelectors(client, frameNodeId, RECRUIT_SEARCH_SELECTORS.cityInput);
+  await clearFocusedInput(client);
+  await sleep(120);
+  await insertText(client, normalizedCity);
+  await sleep(500);
+
+  const started = Date.now();
+  const noResultFallbackMs = Math.min(DEFAULT_RECRUIT_CITY_NO_RESULT_FALLBACK_MS, optionTimeoutMs);
+  let candidate = null;
+  let candidates = [];
+  let noResultFirstSeenAt = 0;
+  while (Date.now() - started <= optionTimeoutMs) {
+    const found = await findTextCandidate(
+      client,
+      frameNodeId,
+      RECRUIT_SEARCH_SELECTORS.citySearchResult,
+      normalizedCity,
+      { match: "contains" }
+    );
+    candidate = found.candidate;
+    candidates = found.candidates;
+    if (candidate) break;
+    const hasNoResult = candidates.some((item) => CITY_NO_RESULT_LABELS.has(item.label));
+    if (hasNoResult) {
+      if (!noResultFirstSeenAt) noResultFirstSeenAt = Date.now();
+      if (Date.now() - noResultFirstSeenAt >= noResultFallbackMs) break;
+    } else {
+      noResultFirstSeenAt = 0;
+    }
+    await sleep(300);
+  }
+  if (!candidate) {
+    const nationalFallback = await selectRecruitNationalCityThroughPicker(client, frameNodeId, {
+      requestedCity: normalizedCity,
+      reason: "city_result_not_found",
+      optionTimeoutMs
+    });
+    if (nationalFallback.applied) {
+      return {
+        ...nationalFallback,
+        reason: "city_result_not_found",
+        requested_city: normalizedCity,
+        requested_city_not_found: true,
+        fallback_to_national: true,
+        original_input: input,
+        elapsed_ms: Date.now() - started,
+        discovered_options_before_fallback: candidates.map((item) => item.text).slice(0, 20)
+      };
+    }
+
+    const resetFallback = await resetRecruitCityToNational(client, {
+      requestedCity: normalizedCity,
+      reason: "city_result_not_found_frame_reset",
+      optionTimeoutMs
+    });
+    if (resetFallback.applied) {
+      return {
+        ...resetFallback,
+        reason: "city_result_not_found",
+        requested_city: normalizedCity,
+        requested_city_not_found: true,
+        fallback_to_national: true,
+        original_input: input,
+        picker_fallback: nationalFallback,
+        elapsed_ms: Date.now() - started,
+        discovered_options_before_fallback: candidates.map((item) => item.text).slice(0, 20)
+      };
+    }
+
+    return {
+      applied: false,
+      reason: "city_result_not_found",
+      city: normalizedCity,
+      input,
+      elapsed_ms: Date.now() - started,
+      discovered_options: candidates.map((item) => item.text).slice(0, 20),
+      national_fallback: nationalFallback,
+      reset_fallback: resetFallback
+    };
+  }
+
+  const box = await clickNodeCenter(client, candidate.node_id, { scrollIntoView: true });
+  await sleep(600);
+  return {
+    applied: true,
+    city: normalizedCity,
+    selected_label: candidate.text,
+    selected_node_id: candidate.node_id,
+    input,
+    elapsed_ms: Date.now() - started,
+    box
+  };
+}
+
+export async function clickRecruitSearch(client, frameNodeId) {
+  const buttonResult = await clickFirstNodeBySelectors(client, frameNodeId, RECRUIT_SEARCH_SELECTORS.searchButton, {
+    optional: true,
+    scrollIntoView: false
+  });
+  if (buttonResult.clicked) {
+    await sleep(1500);
+    return {
+      searched: true,
+      mode: "button",
+      button: buttonResult
+    };
+  }
+
+  await pressKey(client, "Enter", {
+    code: "Enter",
+    windowsVirtualKeyCode: 13,
+    nativeVirtualKeyCode: 13
+  });
+  await sleep(1500);
+  return {
+    searched: true,
+    mode: "enter"
+  };
+}
+
+export async function waitForRecruitSearchResultState(client, {
+  timeoutMs = DEFAULT_RECRUIT_SEARCH_TIMEOUT_MS,
+  intervalMs = 500
+} = {}) {
+  const started = Date.now();
+  let lastState = null;
+  while (Date.now() - started <= timeoutMs) {
+    try {
+      const roots = await getRecruitRoots(client, { requireFrame: false });
+      const frameNodeId = roots.iframe?.documentNodeId;
+      if (frameNodeId) {
+        const counts = await countSelectors(client, frameNodeId, {
+          candidate_card: RECRUIT_CARD_SELECTOR,
+          no_data: RECRUIT_NO_DATA_SELECTORS.join(", ")
+        });
+        lastState = {
+          ok: counts.candidate_card > 0 || counts.no_data > 0,
+          elapsed_ms: Date.now() - started,
+          iframe_selector: roots.iframe.selector,
+          iframe_document_node_id: frameNodeId,
+          counts
+        };
+        if (lastState.ok) return lastState;
+      }
+    } catch (error) {
+      lastState = {
+        ok: false,
+        elapsed_ms: Date.now() - started,
+        error: error?.message || String(error)
+      };
+    }
+    await sleep(intervalMs);
+  }
+  return {
+    ok: false,
+    elapsed_ms: Date.now() - started,
+    ...(lastState || {})
+  };
+}
+
+export async function applyRecruitSearchParams(client, {
+  searchParams = {},
+  requireCards = true,
+  resetBeforeApply = false,
+  searchTimeoutMs = DEFAULT_RECRUIT_SEARCH_TIMEOUT_MS,
+  resetTimeoutMs = DEFAULT_RECRUIT_RESET_TIMEOUT_MS,
+  resetSettleMs = 5000,
+  cityOptionTimeoutMs = DEFAULT_RECRUIT_CITY_OPTION_TIMEOUT_MS
+} = {}) {
+  const normalizedSearchParams = normalizeRecruitSearchParams(searchParams);
+  const reset = resetBeforeApply
+    ? await resetRecruitSearchPage(client, {
+      timeoutMs: resetTimeoutMs,
+      settleMs: resetSettleMs
+    })
+    : null;
+  const controls = reset?.controls?.ok
+    ? reset.controls
+    : await waitForRecruitSearchControls(client, {
+      timeoutMs: searchTimeoutMs,
+      intervalMs: 500
+    });
+  if (!controls.ok) {
+    throw new Error(`Recruit search controls were not ready after navigation; counts=${JSON.stringify(controls.counts || {})}`);
+  }
+  const initialRoots = await getRecruitRoots(client);
+  let frameNodeId = initialRoots.iframe.documentNodeId;
+  const initialFrameNodeId = frameNodeId;
+  const beforeCounts = await getRecruitSearchCounts(client, frameNodeId);
+  const steps = [];
+
+  if (normalizedSearchParams.job) {
+    steps.push({
+      step: "job_title",
+      result: await setRecruitJobTitle(client, frameNodeId, normalizedSearchParams.job, {
+        optionTimeoutMs: searchTimeoutMs
+      })
+    });
+  }
+
+  if (normalizedSearchParams.city) {
+    const cityResult = await setRecruitCity(client, frameNodeId, normalizedSearchParams.city, {
+      optionTimeoutMs: cityOptionTimeoutMs
+    });
+    steps.push({
+      step: "city",
+      result: cityResult
+    });
+    if (cityResult?.reacquire_frame) {
+      const rootsAfterCity = await getRecruitRoots(client);
+      frameNodeId = rootsAfterCity.iframe.documentNodeId;
+      steps.push({
+        step: "reacquire_after_city",
+        result: {
+          selector: rootsAfterCity.iframe.selector,
+          document_node_id: frameNodeId,
+          reason: cityResult.reason
+        }
+      });
+    }
+  }
+
+  steps.push({
+    step: "degree",
+    result: await setRecruitDegrees(client, frameNodeId, normalizedSearchParams.degrees)
+  });
+
+  steps.push({
+    step: "schools",
+    result: await setRecruitSchools(client, frameNodeId, normalizedSearchParams.schools)
+  });
+
+  steps.push({
+    step: "keyword",
+    result: await setRecruitKeyword(client, frameNodeId, normalizedSearchParams.keyword)
+  });
+
+  steps.push({
+    step: "search",
+    result: await clickRecruitSearch(client, frameNodeId)
+  });
+
+  if (typeof normalizedSearchParams.filter_recent_viewed === "boolean") {
+    const postSearchRoots = await getRecruitRoots(client);
+    steps.push({
+      step: "recent_viewed",
+      result: await setRecruitRecentViewedFilter(
+        client,
+        postSearchRoots.iframe.documentNodeId,
+        normalizedSearchParams.filter_recent_viewed
+      )
+    });
+  }
+
+  const postSearchState = await waitForRecruitSearchResultState(client, {
+    timeoutMs: searchTimeoutMs
+  });
+  if (requireCards && (postSearchState.counts?.candidate_card || 0) === 0) {
+    throw new Error(`Recruit search did not produce candidate cards; no_data=${postSearchState.counts?.no_data || 0}`);
+  }
+
+  return {
+    applied: true,
+    search_params: normalizedSearchParams,
+    reset,
+    controls,
+    initial_iframe: {
+      selector: initialRoots.iframe.selector,
+      document_node_id: initialFrameNodeId
+    },
+    before_counts: beforeCounts,
+    steps,
+    post_search_state: postSearchState
+  };
+}