@reconcrap/boss-recommend-mcp 1.2.5 → 1.2.7

package/README.md

@@ -14,6 +14,12 @@ MCP 工具：
 - `cancel_recommend_pipeline_run`（取消运行中任务）
 - `pause_recommend_pipeline_run`（请求暂停 run；会在当前候选人处理完成后进入 paused）
 - `resume_recommend_pipeline_run`（继续 paused run；沿用同 run_id 与同 CSV）
+- `run_recommend_self_heal`（手动运维工具；扫描 Boss recommend 的 selector / network 规则漂移，并在确认后应用高置信度修复）
+  - `validation_profile=safe`：只做非破坏性扫描与被动 network 观察
+  - `validation_profile=full`：会主动打开候选人详情，并执行收藏往返校验与一次打招呼校验；若完整交互没跑通，会明确返回验证异常而不是静默跳过
+  - 扫描会主动覆盖 recommend/latest/featured 三个 tab 的详情链路（详情打开、详情内关键 selector、popup 关闭）
+  - 搜索链路 selector 会在状态触发后验证：职位下拉、职位搜索输入、职位 label、筛选面板、筛选分组（school/degree/gender/recentNotView）、筛选滚动容器与筛选项激活态
+  - 对关闭弹层相关 selector，会同时验证 close 按钮与 fallback close 候选 selector
 
 状态机：
 
@@ -52,6 +58,7 @@ MCP 工具：
 - 不会对每位候选人重复确认
 - 推荐页详情处理完成后，会强制关闭详情页并确认已关闭
 - 简历提取采用“分段滚动截图 + 拼成长图”的方式，再交给多模态模型判断
+- 提供显式运维自愈工具：只在手动调用 `run_recommend_self_heal` 时运行，不会接入正常 run / doctor / preflight 自动链路
 - 运行前会自动做依赖体检（Node.js、Python、Pillow、`chrome-remote-interface`、`ws`），缺失时会在 `doctor` 与流水线失败诊断中明确提示
 - 若 preflight 失败，返回 `diagnostics.recovery`（含有序修复步骤与 `agent_prompt`），可直接交给 AI agent 自动按顺序安装依赖
 - 不依赖 PowerShell；Windows / macOS 均可运行（命令提示会按平台给出）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",
@@ -25,6 +25,7 @@
     "test:run-state": "node src/test-run-state.js",
     "test:runtime": "node src/test-adapters-runtime.js",
     "test:async": "node src/test-index-async.js",
+    "test:self-heal": "node src/test-self-heal.js",
     "test:search-job": "node vendor/boss-recommend-search-cli/src/test-job-selection.js",
     "test:screen-runtime": "node vendor/boss-recommend-screen-cli/test-recoverable-resume-failures.cjs"
   },

package/src/adapters.js

@@ -1,9 +1,13 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { spawn, spawnSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import CDP from "chrome-remote-interface";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import CDP from "chrome-remote-interface";
+import {
+  buildFirstSelectorLookupExpression,
+  getRecommendSelectorRule
+} from "./recommend-healing-config.js";
 
 const currentFilePath = fileURLToPath(import.meta.url);
 const packagedMcpDir = path.resolve(path.dirname(currentFilePath), "..");
@@ -23,6 +27,44 @@ const PAGE_SCOPE_TO_TAB_STATUS = {
   latest: "1",
   featured: "3"
 };
+const RECOMMEND_IFRAME_SELECTORS = getRecommendSelectorRule(
+  ["top", "recommend_iframe"],
+  ['iframe[name="recommendFrame"]', 'iframe[src*="/web/frame/recommend/"]', "iframe"]
+);
+const RECOMMEND_TAB_SELECTORS = getRecommendSelectorRule(
+  ["frame", "tab_items"],
+  ['li.tab-item[data-status]', 'li[data-status][class*="tab"]']
+);
+const RECOMMEND_CARD_SELECTORS = getRecommendSelectorRule(["frame", "recommend_cards"], ['ul.card-list > li.card-item']);
+const FEATURED_CARD_SELECTORS = getRecommendSelectorRule(["frame", "featured_cards"], ['li.geek-info-card']);
+const LATEST_CARD_SELECTORS = getRecommendSelectorRule(["frame", "latest_cards"], ['.candidate-card-wrap .card-inner[data-geek]', '.candidate-card-wrap [data-geek]']);
+const DETAIL_POPUP_SELECTORS = getRecommendSelectorRule(
+  ["detail", "popup"],
+  [
+    ".dialog-wrap.active",
+    ".boss-popup__wrapper",
+    ".boss-popup_wrapper",
+    ".boss-dialog_wrapper",
+    ".boss-dialog",
+    ".resume-item-detail",
+    ".geek-detail-modal",
+    '[class*="popup"][class*="wrapper"]',
+    '[class*="dialog"][class*="wrapper"]'
+  ]
+);
+const DETAIL_RESUME_IFRAME_SELECTORS = getRecommendSelectorRule(
+  ["detail", "resume_iframe"],
+  ['iframe[src*="/web/frame/c-resume/"]', 'iframe[name*="resume"]']
+);
+const REFRESH_FINISHED_WRAP_SELECTORS = getRecommendSelectorRule(["frame", "refresh_finished_wrap"], [".finished-wrap"]);
+const REFRESH_BUTTON_SELECTORS = getRecommendSelectorRule(
+  ["frame", "refresh_button"],
+  [".finished-wrap .btn.btn-refresh", ".finished-wrap .btn-refresh", ".no-data-refresh .btn-refresh"]
+);
+
+function buildRecommendIframeLookupExpression(rootExpr = "document") {
+  return buildFirstSelectorLookupExpression(RECOMMEND_IFRAME_SELECTORS, rootExpr);
+}
 
 function getCodexHome() {
   return process.env.CODEX_HOME
@@ -1343,15 +1385,21 @@ function findChromeOnboardingUrl(tabs) {
   return null;
 }
 
-function isBossLoginTab(tab) {
-  const url = String(tab?.url || "");
-  const title = String(tab?.title || "");
-  return (
-    url === bossLoginUrl
-    || bossLoginUrlPattern.test(url)
-    || bossLoginTitlePattern.test(title)
-  );
-}
+function isBossLoginTab(tab) {
+  const url = String(tab?.url || "");
+  const title = String(tab?.title || "");
+  return (
+    url === bossLoginUrl
+    || bossLoginUrlPattern.test(url)
+    || bossLoginTitlePattern.test(title)
+  );
+}
+
+function findRecommendTab(tabs = []) {
+  return tabs.find(
+    (tab) => typeof tab?.url === "string" && tab.url.includes("/web/chat/recommend")
+  ) || null;
+}
 
 export async function inspectBossRecommendPageState(port, options = {}) {
   const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 6000;
@@ -1365,9 +1413,7 @@ export async function inspectBossRecommendPageState(port, options = {}) {
     try {
       const tabs = await listChromeTabs(port);
       lastTabs = tabs;
-      const exactTab = tabs.find(
-        (tab) => typeof tab?.url === "string" && tab.url.includes("/web/chat/recommend")
-      );
+      const exactTab = findRecommendTab(tabs);
       if (exactTab) {
         if (isBossLoginTab(exactTab)) {
           return buildBossPageState({
@@ -1498,36 +1544,285 @@ async function openBossRecommendTab(port) {
   };
 }
 
-async function verifyRecommendPageStable(port, options = {}) {
-  const settleMs = Number.isFinite(options.settleMs) ? options.settleMs : 1500;
-  const recheckTimeoutMs = Number.isFinite(options.recheckTimeoutMs) ? options.recheckTimeoutMs : 2500;
-  const pollMs = Number.isFinite(options.pollMs) ? options.pollMs : 600;
+async function verifyRecommendPageStable(port, options = {}) {
+  const settleMs = Number.isFinite(options.settleMs) ? options.settleMs : 1500;
+  const recheckTimeoutMs = Number.isFinite(options.recheckTimeoutMs) ? options.recheckTimeoutMs : 2500;
+  const pollMs = Number.isFinite(options.pollMs) ? options.pollMs : 600;
 
   await sleep(settleMs);
-  const recheck = await inspectBossRecommendPageState(port, {
-    timeoutMs: recheckTimeoutMs,
-    pollMs
-  });
-  if (recheck.state === "RECOMMEND_READY") {
-    return recheck;
-  }
-  if (recheck.state === "LOGIN_REQUIRED") {
-    return buildBossPageState({
-      ...recheck,
-      state: "LOGIN_REQUIRED_AFTER_REDIRECT",
+  const recheck = await inspectBossRecommendPageState(port, {
+    timeoutMs: recheckTimeoutMs,
+    pollMs
+  });
+  if (recheck.state === "RECOMMEND_READY") {
+    const iframeState = await waitForRecommendIframeReady(port, {
+      timeoutMs: recheckTimeoutMs,
+      pollMs
+    });
+    if (iframeState.state === "RECOMMEND_IFRAME_READY") {
+      return buildBossPageState({
+        ...recheck,
+        ok: true,
+        state: "RECOMMEND_READY",
+        frame_url: iframeState.frame_url || null,
+        iframe_state: iframeState
+      });
+    }
+    if (iframeState.state === "LOGIN_REQUIRED") {
+      return buildBossPageState({
+        ...iframeState,
+        state: "LOGIN_REQUIRED_AFTER_REDIRECT",
+        message: "Boss 页面曾进入 recommend 但 iframe 不可用且出现登录态特征，通常表示登录态失效。"
+      });
+    }
+    if (iframeState.state === "NO_RECOMMEND_IFRAME") {
+      return buildBossPageState({
+        ...recheck,
+        ok: false,
+        state: "NO_RECOMMEND_IFRAME",
+        current_url: iframeState.current_url || recheck.current_url || null,
+        title: iframeState.title || recheck.title || null,
+        frame_url: iframeState.frame_url || null,
+        iframe_state: iframeState,
+        message: "Boss recommend 页面已打开，但 recommend iframe 尚未就绪。"
+      });
+    }
+    return iframeState;
+  }
+  if (recheck.state === "LOGIN_REQUIRED") {
+    return buildBossPageState({
+      ...recheck,
+      state: "LOGIN_REQUIRED_AFTER_REDIRECT",
       message: "Boss 页面曾进入 recommend 但随后跳转到其他页面，通常表示登录态失效。"
     });
-  }
-  return recheck;
-}
-
-function pickBossRecommendReloadTarget(tabs = []) {
-  return tabs.find(
-    (tab) => typeof tab?.url === "string" && tab.url.includes("/web/chat/recommend")
-  ) || tabs.find(
-    (tab) => typeof tab?.url === "string" && tab.url.includes("zhipin.com")
-  ) || null;
-}
+  }
+  return recheck;
+}
+
+function buildRecommendIframeProbeExpression() {
+  return `(() => {
+    const currentUrl = (() => {
+      try { return String(window.location.href || ""); } catch { return ""; }
+    })();
+    const title = (() => {
+      try { return String(document.title || ""); } catch { return ""; }
+    })();
+    const isLogin = ${bossLoginUrlPattern}.test(currentUrl)
+      || ${bossLoginTitlePattern}.test(title);
+    if (isLogin) {
+      return {
+        ok: false,
+        error: "LOGIN_REQUIRED",
+        current_url: currentUrl || ${JSON.stringify(bossLoginUrl)},
+        title
+      };
+    }
+    const frame = ${buildRecommendIframeLookupExpression()};
+    const frameUrl = (() => {
+      try {
+        return String(frame?.contentWindow?.location?.href || frame?.src || "");
+      } catch {
+        return String(frame?.src || "");
+      }
+    })();
+    const iframeCount = document.querySelectorAll("iframe").length;
+    if (!frame || !frame.contentDocument) {
+      return {
+        ok: false,
+        error: "NO_RECOMMEND_IFRAME",
+        current_url: currentUrl,
+        title,
+        frame_url: frameUrl,
+        frame_present: Boolean(frame),
+        iframe_count: iframeCount
+      };
+    }
+    return {
+      ok: true,
+      current_url: currentUrl,
+      title,
+      frame_url: frameUrl,
+      frame_present: true,
+      iframe_count: iframeCount
+    };
+  })()`;
+}
+
+async function probeRecommendIframeState(port, options = {}) {
+  const expectedUrl = options.expectedUrl || bossRecommendUrl;
+  let client = null;
+  try {
+    const tabs = await listChromeTabs(port);
+    const exactTab = findRecommendTab(tabs);
+    if (!exactTab) {
+      const loginTab = tabs.find((tab) => isBossLoginTab(tab));
+      if (loginTab) {
+        return buildBossPageState({
+          ok: false,
+          state: "LOGIN_REQUIRED",
+          path: loginTab.url || bossLoginUrl,
+          current_url: loginTab.url || bossLoginUrl,
+          title: loginTab.title || null,
+          requires_login: true,
+          expected_url: expectedUrl,
+          login_url: bossLoginUrl,
+          message: "Boss 页面未登录，需先完成登录后再进入 recommend 页面。"
+        });
+      }
+      const bossTab = tabs.find(
+        (tab) => typeof tab?.url === "string" && tab.url.includes("zhipin.com")
+      );
+      if (bossTab) {
+        return buildBossPageState({
+          ok: false,
+          state: "BOSS_NOT_ON_RECOMMEND",
+          path: bossTab.url,
+          current_url: bossTab.url,
+          title: bossTab.title || null,
+          requires_login: false,
+          expected_url: expectedUrl,
+          message: "Boss 已登录但当前不在 recommend 页面。"
+        });
+      }
+      return buildBossPageState({
+        ok: false,
+        state: "BOSS_TAB_NOT_FOUND",
+        path: expectedUrl,
+        current_url: null,
+        title: null,
+        requires_login: false,
+        expected_url: expectedUrl,
+        message: "未检测到 Boss 推荐页标签页。",
+        sample_urls: extractSampleUrls(tabs)
+      });
+    }
+    if (isBossLoginTab(exactTab)) {
+      return buildBossPageState({
+        ok: false,
+        state: "LOGIN_REQUIRED",
+        path: exactTab.url || bossLoginUrl,
+        current_url: exactTab.url || bossLoginUrl,
+        title: exactTab.title || null,
+        requires_login: true,
+        expected_url: expectedUrl,
+        login_url: bossLoginUrl,
+        message: "当前标签页虽在 recommend 路径，但检测到登录态页面特征，请先完成 Boss 登录。"
+      });
+    }
+
+    client = await CDP({ port, target: exactTab });
+    const { Runtime, Page } = client;
+    if (Runtime && typeof Runtime.enable === "function") {
+      await Runtime.enable();
+    }
+    if (Page && typeof Page.enable === "function") {
+      await Page.enable();
+    }
+    const frameProbe = await evaluateCdpExpression(client, buildRecommendIframeProbeExpression());
+    if (frameProbe?.ok) {
+      return buildBossPageState({
+        ok: true,
+        state: "RECOMMEND_IFRAME_READY",
+        path: frameProbe.current_url || exactTab.url || expectedUrl,
+        current_url: frameProbe.current_url || exactTab.url || null,
+        title: frameProbe.title || exactTab.title || null,
+        expected_url: expectedUrl,
+        frame_url: frameProbe.frame_url || null,
+        frame_present: frameProbe.frame_present === true,
+        iframe_count: Number.isFinite(Number(frameProbe.iframe_count))
+          ? Number(frameProbe.iframe_count)
+          : null,
+        message: "Boss 推荐页 iframe 已就绪。"
+      });
+    }
+    if (frameProbe?.error === "LOGIN_REQUIRED") {
+      return buildBossPageState({
+        ok: false,
+        state: "LOGIN_REQUIRED",
+        path: frameProbe.current_url || exactTab.url || bossLoginUrl,
+        current_url: frameProbe.current_url || exactTab.url || bossLoginUrl,
+        title: frameProbe.title || exactTab.title || null,
+        requires_login: true,
+        expected_url: expectedUrl,
+        login_url: bossLoginUrl,
+        message: "页面检测到登录态特征，请先完成 Boss 登录。"
+      });
+    }
+    return buildBossPageState({
+      ok: false,
+      state: frameProbe?.error || "NO_RECOMMEND_IFRAME",
+      path: frameProbe?.current_url || exactTab.url || expectedUrl,
+      current_url: frameProbe?.current_url || exactTab.url || null,
+      title: frameProbe?.title || exactTab.title || null,
+      expected_url: expectedUrl,
+      frame_url: frameProbe?.frame_url || null,
+      frame_present: frameProbe?.frame_present === true,
+      iframe_count: Number.isFinite(Number(frameProbe?.iframe_count))
+        ? Number(frameProbe.iframe_count)
+        : null,
+      message: "recommend iframe 暂不可用。"
+    });
+  } catch (error) {
+    return buildBossPageState({
+      ok: false,
+      state: "DEBUG_PORT_UNREACHABLE",
+      path: `http://127.0.0.1:${port}`,
+      current_url: null,
+      title: null,
+      requires_login: false,
+      expected_url: expectedUrl,
+      message: `无法连接到 Chrome DevTools 端口 ${port}。请确认 Chrome 已以远程调试模式启动。`,
+      error: error?.message || String(error)
+    });
+  } finally {
+    if (client) {
+      try {
+        await client.close();
+      } catch {}
+    }
+  }
+}
+
+async function waitForRecommendIframeReady(port, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 3000;
+  const pollMs = Number.isFinite(options.pollMs) ? options.pollMs : 600;
+  const expectedUrl = options.expectedUrl || bossRecommendUrl;
+  const deadline = Date.now() + timeoutMs;
+  let lastState = null;
+
+  while (Date.now() < deadline) {
+    lastState = await probeRecommendIframeState(port, { expectedUrl });
+    if (lastState?.state === "RECOMMEND_IFRAME_READY") {
+      return lastState;
+    }
+    if (
+      lastState?.state === "LOGIN_REQUIRED"
+      || lastState?.state === "LOGIN_REQUIRED_AFTER_REDIRECT"
+      || lastState?.state === "DEBUG_PORT_UNREACHABLE"
+      || lastState?.state === "BOSS_TAB_NOT_FOUND"
+      || lastState?.state === "BOSS_NOT_ON_RECOMMEND"
+    ) {
+      return lastState;
+    }
+    await sleep(pollMs);
+  }
+
+  return lastState || buildBossPageState({
+    ok: false,
+    state: "NO_RECOMMEND_IFRAME",
+    path: expectedUrl,
+    current_url: null,
+    title: null,
+    expected_url: expectedUrl,
+    message: "recommend iframe 尚未就绪。"
+  });
+}
+
+function pickBossRecommendReloadTarget(tabs = []) {
+  return findRecommendTab(tabs) || tabs.find(
+    (tab) => typeof tab?.url === "string" && tab.url.includes("zhipin.com")
+  ) || null;
+}
 
 async function evaluateCdpExpression(client, expression) {
   const result = await client.Runtime.evaluate({
@@ -1543,15 +1838,16 @@ async function evaluateCdpExpression(client, expression) {
 
 function buildRecommendTabStateExpression() {
   return `(() => {
-    const frame = document.querySelector('iframe[name="recommendFrame"]')
-      || document.querySelector('iframe[src*="/web/frame/recommend/"]')
-      || document.querySelector('iframe');
+    const frame = ${buildRecommendIframeLookupExpression()};
     if (!frame || !frame.contentDocument) {
       return { ok: false, error: 'NO_RECOMMEND_IFRAME' };
     }
     const doc = frame.contentDocument;
     const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
-    const tabs = Array.from(doc.querySelectorAll('li.tab-item[data-status], li[data-status][class*="tab"]')).map((node) => {
+    const tabs = Array.from(new Set(${JSON.stringify(RECOMMEND_TAB_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      }))).map((node) => {
       const status = normalize(node.getAttribute('data-status'));
       const className = normalize(node.className);
       const active = (
@@ -1568,9 +1864,18 @@ function buildRecommendTabStateExpression() {
       };
     });
     const activeTab = tabs.find((item) => item.active && item.status) || null;
-    const featuredCount = doc.querySelectorAll('li.geek-info-card').length;
-    const recommendCount = doc.querySelectorAll('ul.card-list > li.card-item').length;
-    const latestCount = doc.querySelectorAll('.candidate-card-wrap .card-inner[data-geek], .candidate-card-wrap [data-geek]').length;
+    const featuredCount = ${JSON.stringify(FEATURED_CARD_SELECTORS)}
+      .reduce((sum, selector) => {
+        try { return sum + doc.querySelectorAll(selector).length; } catch { return sum; }
+      }, 0);
+    const recommendCount = ${JSON.stringify(RECOMMEND_CARD_SELECTORS)}
+      .reduce((sum, selector) => {
+        try { return sum + doc.querySelectorAll(selector).length; } catch { return sum; }
+      }, 0);
+    const latestCount = ${JSON.stringify(LATEST_CARD_SELECTORS)}
+      .reduce((sum, selector) => {
+        try { return sum + doc.querySelectorAll(selector).length; } catch { return sum; }
+      }, 0);
     let inferredStatus = activeTab?.status || null;
     if (!inferredStatus) {
       if (featuredCount > 0 && recommendCount === 0 && latestCount === 0) inferredStatus = '3';
@@ -1592,15 +1897,16 @@ function buildRecommendTabStateExpression() {
 
 function buildRecommendTabSwitchExpression(targetStatus) {
   return `((targetStatus) => {
-    const frame = document.querySelector('iframe[name="recommendFrame"]')
-      || document.querySelector('iframe[src*="/web/frame/recommend/"]')
-      || document.querySelector('iframe');
+    const frame = ${buildRecommendIframeLookupExpression()};
     if (!frame || !frame.contentDocument) {
       return { ok: false, state: 'NO_RECOMMEND_IFRAME' };
     }
     const doc = frame.contentDocument;
     const normalize = (value) => String(value || '').replace(/\\s+/g, ' ').trim();
-    const tabs = Array.from(doc.querySelectorAll('li.tab-item[data-status], li[data-status][class*="tab"]'));
+    const tabs = Array.from(new Set(${JSON.stringify(RECOMMEND_TAB_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      })));
     const target = tabs.find((node) => normalize(node.getAttribute('data-status')) === String(targetStatus)) || null;
     if (!target) {
       return { ok: false, state: 'TAB_NOT_FOUND', target_status: String(targetStatus) };
@@ -1628,19 +1934,7 @@ function buildRecommendTabSwitchExpression(targetStatus) {
 
 function buildRecommendDetailStateExpression() {
   return `(() => {
-    const selectors = [
-      '.dialog-wrap.active',
-      '.boss-popup__wrapper',
-      '.boss-popup_wrapper',
-      '.boss-dialog_wrapper',
-      '.boss-dialog',
-      '.resume-item-detail',
-      '.geek-detail-modal',
-      'iframe[src*="/web/frame/c-resume/"]',
-      'iframe[name*="resume"]',
-      '[class*="popup"][class*="wrapper"]',
-      '[class*="dialog"][class*="wrapper"]'
-    ];
+    const selectors = ${JSON.stringify([...DETAIL_POPUP_SELECTORS, ...DETAIL_RESUME_IFRAME_SELECTORS])};
     const isVisible = (node) => {
       if (!node || !node.getBoundingClientRect) return false;
       const rect = node.getBoundingClientRect();
@@ -1674,9 +1968,7 @@ function buildRecommendDetailStateExpression() {
     const topDetail = findVisibleDetail(document, 'top');
     if (topDetail) return topDetail;
 
-    const frame = document.querySelector('iframe[name="recommendFrame"]')
-      || document.querySelector('iframe[src*="/web/frame/recommend/"]')
-      || null;
+    const frame = ${buildRecommendIframeLookupExpression()} || null;
     if (!frame || !frame.contentDocument) {
       return { ok: true, open: false, reason: 'NO_RECOMMEND_IFRAME' };
     }
@@ -1940,14 +2232,12 @@ export async function switchRecommendTab(workspaceRoot, options = {}) {
   }
 }
 
-function buildRecommendRefreshStateExpression() {
-  return `(() => {
-    const frame = document.querySelector('iframe[name="recommendFrame"]')
-      || document.querySelector('iframe[src*="/web/frame/recommend/"]')
-      || document.querySelector('iframe');
-    if (!frame || !frame.contentDocument) {
-      return { ok: false, error: 'NO_RECOMMEND_IFRAME' };
-    }
+function buildRecommendRefreshStateExpression() {
+  return `(() => {
+    const frame = ${buildRecommendIframeLookupExpression()};
+    if (!frame || !frame.contentDocument) {
+      return { ok: false, error: 'NO_RECOMMEND_IFRAME' };
+    }
     const doc = frame.contentDocument;
     const isVisible = (el) => {
       if (!el) return false;
@@ -1960,13 +2250,29 @@ function buildRecommendRefreshStateExpression() {
       const rect = el.getBoundingClientRect();
       return rect.width > 2 && rect.height > 2 && el.offsetParent !== null;
     };
-    const finishedWrap = Array.from(doc.querySelectorAll('.finished-wrap')).find((el) => isVisible(el)) || null;
-    const refreshButton = Array.from(doc.querySelectorAll('.finished-wrap .btn.btn-refresh, .finished-wrap .btn-refresh, .no-data-refresh .btn-refresh'))
-      .find((el) => isVisible(el)) || null;
-    const cards = Array.from(doc.querySelectorAll('ul.card-list > li.card-item'));
+    const finishedWrap = ${JSON.stringify(REFRESH_FINISHED_WRAP_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      })
+      .find((el) => isVisible(el)) || null;
+    const refreshButton = ${JSON.stringify(REFRESH_BUTTON_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      })
+      .find((el) => isVisible(el)) || null;
+    const cards = ${JSON.stringify(RECOMMEND_CARD_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      });
     const candidateCards = cards.filter((card) => card.querySelector('.card-inner[data-geekid]'));
-    const latestCards = Array.from(doc.querySelectorAll('.candidate-card-wrap .card-inner[data-geek], .candidate-card-wrap [data-geek]'));
-    const tabs = Array.from(doc.querySelectorAll('li.tab-item[data-status], li[data-status][class*="tab"]'));
+    const latestCards = ${JSON.stringify(LATEST_CARD_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      });
+    const tabs = ${JSON.stringify(RECOMMEND_TAB_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      });
     const activeTab = tabs.find((node) => /(?:^|\\s)(?:curr|current|active|selected)(?:\\s|$)/i.test(String(node.className || ''))) || null;
     const activeStatus = activeTab ? String(activeTab.getAttribute('data-status') || '') : '';
     const inferredStatus = activeStatus
@@ -1992,14 +2298,12 @@ function buildRecommendRefreshStateExpression() {
   })()`;
 }
 
-function buildRecommendRefreshClickExpression() {
-  return `(() => {
-    const frame = document.querySelector('iframe[name="recommendFrame"]')
-      || document.querySelector('iframe[src*="/web/frame/recommend/"]')
-      || document.querySelector('iframe');
-    if (!frame || !frame.contentDocument) {
-      return { ok: false, state: 'NO_RECOMMEND_IFRAME' };
-    }
+function buildRecommendRefreshClickExpression() {
+  return `(() => {
+    const frame = ${buildRecommendIframeLookupExpression()};
+    if (!frame || !frame.contentDocument) {
+      return { ok: false, state: 'NO_RECOMMEND_IFRAME' };
+    }
     const doc = frame.contentDocument;
     const isVisible = (el) => {
       if (!el) return false;
@@ -2012,8 +2316,11 @@ function buildRecommendRefreshClickExpression() {
       const rect = el.getBoundingClientRect();
       return rect.width > 2 && rect.height > 2 && el.offsetParent !== null;
     };
-    const refreshButton = Array.from(doc.querySelectorAll('.finished-wrap .btn.btn-refresh, .finished-wrap .btn-refresh, .no-data-refresh .btn-refresh'))
-      .find((el) => isVisible(el)) || null;
+    const refreshButton = ${JSON.stringify(REFRESH_BUTTON_SELECTORS)}
+      .flatMap((selector) => {
+        try { return Array.from(doc.querySelectorAll(selector)); } catch { return []; }
+      })
+      .find((el) => isVisible(el)) || null;
     if (!refreshButton) {
       return { ok: false, state: 'REFRESH_BUTTON_NOT_FOUND' };
     }