@reconcrap/boss-recommend-mcp 1.2.6 → 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.6",
+  "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
@@ -1575,9 +1617,7 @@ function buildRecommendIframeProbeExpression() {
         title
       };
     }
-    const frame = document.querySelector('iframe[name="recommendFrame"]')
-      || document.querySelector('iframe[src*="/web/frame/recommend/"]')
-      || document.querySelector('iframe');
+    const frame = ${buildRecommendIframeLookupExpression()};
     const frameUrl = (() => {
       try {
         return String(frame?.contentWindow?.location?.href || frame?.src || "");
@@ -1798,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 = (
@@ -1823,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';
@@ -1847,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) };
@@ -1883,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();
@@ -1929,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' };
     }
@@ -2195,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;
@@ -2215,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
@@ -2247,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;
@@ -2267,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' };
     }

package/src/index.js

@@ -9,6 +9,7 @@ import {
   runRecommendCalibration
 } from "./adapters.js";
 import { runRecommendPipeline } from "./pipeline.js";
+import { runRecommendSelfHeal } from "./self-heal.js";
 import {
   RUN_MODE_ASYNC,
   RUN_STAGE_PREFLIGHT,
@@ -39,6 +40,7 @@ const TOOL_PAUSE_RUN = "pause_recommend_pipeline_run";
 const TOOL_RESUME_RUN = "resume_recommend_pipeline_run";
 const TOOL_RUN_FEATURED_CALIBRATION = "run_featured_calibration";
 const TOOL_GET_FEATURED_CALIBRATION_STATUS = "get_featured_calibration_status";
+const TOOL_RUN_RECOMMEND_SELF_HEAL = "run_recommend_self_heal";
 
 const SERVER_NAME = "boss-recommend-mcp";
 const FRAMING_UNKNOWN = "unknown";
@@ -49,6 +51,7 @@ const DETACHED_WORKER_RUN_ID_FLAG = "--run-id";
 const DETACHED_WORKER_RESUME_FLAG = "--resume";
 
 let runPipelineImpl = runRecommendPipeline;
+let runSelfHealImpl = runRecommendSelfHeal;
 let spawnProcessImpl = spawn;
 const TERMINAL_RUN_STATES = new Set([RUN_STATE_COMPLETED, RUN_STATE_FAILED, RUN_STATE_CANCELED]);
 
@@ -321,6 +324,43 @@ function createRunFeaturedCalibrationInputSchema() {
   };
 }
 
+function createRunRecommendSelfHealInputSchema() {
+  return {
+    type: "object",
+    properties: {
+      mode: {
+        type: "string",
+        enum: ["scan", "apply"],
+        description: "scan=扫描漂移；apply=按 repair_session_id 应用高置信度修复"
+      },
+      scope: {
+        type: "string",
+        enum: ["full", "search_screen", "selectors_only"],
+        description: "扫描范围，默认 full"
+      },
+      validation_profile: {
+        type: "string",
+        enum: ["safe", "full"],
+        description: "校验强度，默认 full"
+      },
+      port: {
+        type: "integer",
+        minimum: 1,
+        description: "可选，Boss Chrome 远程调试端口"
+      },
+      repair_session_id: {
+        type: "string",
+        description: "apply 模式必填，来自 scan 返回值"
+      },
+      confirm_apply: {
+        type: "boolean",
+        description: "apply 模式必填，必须显式传 true"
+      }
+    },
+    additionalProperties: false
+  };
+}
+
 function createToolsSchema() {
   return [
     {
@@ -389,6 +429,11 @@ function createToolsSchema() {
         properties: {},
         additionalProperties: false
       }
+    },
+    {
+      name: TOOL_RUN_RECOMMEND_SELF_HEAL,
+      description: "手动运维自愈工具：扫描 Boss recommend 相关 selector / network 规则漂移，并在确认后应用高置信度修复。",
+      inputSchema: createRunRecommendSelfHealInputSchema()
     }
   ];
 }
@@ -448,6 +493,42 @@ function validateRunFeaturedCalibrationArgs(args) {
   return null;
 }
 
+function validateRunRecommendSelfHealArgs(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) {
+    return "arguments must be an object";
+  }
+
+  if (Object.prototype.hasOwnProperty.call(args, "mode")) {
+    const mode = normalizeText(args.mode).toLowerCase();
+    if (!["scan", "apply"].includes(mode)) {
+      return "mode must be one of: scan, apply";
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(args, "scope")) {
+    const scope = normalizeText(args.scope).toLowerCase();
+    if (!["full", "search_screen", "selectors_only"].includes(scope)) {
+      return "scope must be one of: full, search_screen, selectors_only";
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(args, "validation_profile")) {
+    const profile = normalizeText(args.validation_profile).toLowerCase();
+    if (!["safe", "full"].includes(profile)) {
+      return "validation_profile must be one of: safe, full";
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(args, "port")) {
+    const port = Number.parseInt(String(args.port), 10);
+    if (!Number.isFinite(port) || port <= 0) {
+      return "port must be a positive integer";
+    }
+  }
+
+  return null;
+}
+
 function getLastOutputLine(text) {
   const lines = String(text || "")
     .split(/\r?\n/)
@@ -1340,6 +1421,10 @@ async function handleRunFeaturedCalibrationTool({ workspaceRoot, args }) {
   };
 }
 
+async function handleRunRecommendSelfHealTool({ workspaceRoot, args }) {
+  return runSelfHealImpl({ workspaceRoot, args });
+}
+
 async function handleRequest(message, workspaceRoot) {
   if (!message || message.jsonrpc !== "2.0") {
     return createJsonRpcError(null, -32600, "Invalid JSON-RPC request");
@@ -1396,6 +1481,13 @@ async function handleRequest(message, workspaceRoot) {
       }
     }
 
+    if (toolName === TOOL_RUN_RECOMMEND_SELF_HEAL) {
+      const inputError = validateRunRecommendSelfHealArgs(args);
+      if (inputError) {
+        return createJsonRpcError(id, -32602, inputError);
+      }
+    }
+
     if ([TOOL_GET_RUN, TOOL_CANCEL_RUN, TOOL_PAUSE_RUN, TOOL_RESUME_RUN].includes(toolName)) {
       if (!args || typeof args.run_id !== "string" || !normalizeText(args.run_id)) {
         return createJsonRpcError(id, -32602, "run_id is required and must be a string");
@@ -1418,6 +1510,8 @@ async function handleRequest(message, workspaceRoot) {
         payload = handleGetFeaturedCalibrationStatusTool(workspaceRoot);
       } else if (toolName === TOOL_RUN_FEATURED_CALIBRATION) {
         payload = await handleRunFeaturedCalibrationTool({ workspaceRoot, args });
+      } else if (toolName === TOOL_RUN_RECOMMEND_SELF_HEAL) {
+        payload = await handleRunRecommendSelfHealTool({ workspaceRoot, args });
       } else {
         return createJsonRpcError(id, -32602, `Unknown tool: ${toolName || ""}`);
       }
@@ -1553,6 +1647,9 @@ export const __testables = {
   },
   setRunPipelineImplForTests(nextImpl) {
     runPipelineImpl = typeof nextImpl === "function" ? nextImpl : runRecommendPipeline;
+  },
+  setRunSelfHealImplForTests(nextImpl) {
+    runSelfHealImpl = typeof nextImpl === "function" ? nextImpl : runRecommendSelfHeal;
   }
 };
 

package/src/recommend-healing-config.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const currentFilePath = fileURLToPath(import.meta.url);
+const defaultRulesPath = path.join(path.dirname(currentFilePath), "recommend-healing-rules.json");
+
+let cachedRulesPath = null;
+let cachedRulesMtime = null;
+let cachedRules = null;
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function normalizePathLike(value) {
+  return String(value || "").trim();
+}
+
+function getNestedValue(root, pathParts = []) {
+  let current = root;
+  for (const part of pathParts) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+export function getRecommendHealingRulesPath() {
+  const fromEnv = normalizePathLike(process.env.BOSS_RECOMMEND_HEALING_RULES_FILE);
+  return fromEnv ? path.resolve(fromEnv) : defaultRulesPath;
+}
+
+export function loadRecommendHealingRules(options = {}) {
+  const fresh = options.fresh === true;
+  const rulesPath = getRecommendHealingRulesPath();
+  const stats = fs.statSync(rulesPath);
+  if (
+    !fresh
+    && cachedRules
+    && cachedRulesPath === rulesPath
+    && cachedRulesMtime === Number(stats.mtimeMs)
+  ) {
+    return clone(cachedRules);
+  }
+  const nextRules = require(rulesPath);
+  cachedRulesPath = rulesPath;
+  cachedRulesMtime = Number(stats.mtimeMs);
+  cachedRules = clone(nextRules);
+  return clone(cachedRules);
+}
+
+export function saveRecommendHealingRules(nextRules) {
+  const rulesPath = getRecommendHealingRulesPath();
+  const serialized = `${JSON.stringify(nextRules, null, 2)}\n`;
+  fs.writeFileSync(rulesPath, serialized, "utf8");
+  cachedRulesPath = rulesPath;
+  cachedRulesMtime = Number(fs.statSync(rulesPath).mtimeMs);
+  cachedRules = clone(nextRules);
+  return rulesPath;
+}
+
+export function getRecommendSelectorRule(pathParts = [], fallback = []) {
+  const value = getNestedValue(loadRecommendHealingRules(), ["selectors", ...pathParts]);
+  return Array.isArray(value) && value.length > 0 ? value.map((item) => String(item)) : fallback.slice();
+}
+
+export function getRecommendNetworkRule(pathParts = [], fallback = null) {
+  const value = getNestedValue(loadRecommendHealingRules(), ["network", ...pathParts]);
+  if (Array.isArray(value)) return value.map((item) => String(item));
+  if (value && typeof value === "object") return clone(value);
+  if (typeof value === "string") return value;
+  if (Array.isArray(fallback)) return fallback.slice();
+  if (fallback && typeof fallback === "object") return clone(fallback);
+  return fallback;
+}
+
+export function compileRegexList(patterns = []) {
+  return (Array.isArray(patterns) ? patterns : [])
+    .map((pattern) => {
+      try {
+        return new RegExp(String(pattern), "i");
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function findFirstMatchingPattern(value, patterns = []) {
+  const text = String(value || "");
+  for (const pattern of compileRegexList(patterns)) {
+    if (pattern.test(text)) return pattern.source;
+  }
+  return null;
+}
+
+export function matchesAnyPattern(value, patterns = []) {
+  return Boolean(findFirstMatchingPattern(value, patterns));
+}
+
+export function buildFirstSelectorLookupExpression(selectors = [], rootExpr = "document") {
+  return `(() => {
+    const selectors = ${JSON.stringify(selectors)};
+    for (const selector of selectors) {
+      try {
+        const node = ${rootExpr}.querySelector(selector);
+        if (node) return node;
+      } catch {}
+    }
+    return null;
+  })()`;
+}
+
+export function buildSelectorCollectionExpression(selectors = [], rootExpr = "document") {
+  return `(() => {
+    const selectors = ${JSON.stringify(selectors)};
+    const nodes = [];
+    for (const selector of selectors) {
+      try {
+        nodes.push(...Array.from(${rootExpr}.querySelectorAll(selector)));
+      } catch {}
+    }
+    return Array.from(new Set(nodes));
+  })()`;
+}