@reconcrap/boss-recommend-mcp 1.3.28 → 1.3.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "1.3.28",
+  "version": "1.3.29",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",

package/src/test-boss-chat.js

@@ -484,6 +484,106 @@ async function testBossChatRecoverToChatIndexShouldForceNavigateAndWaitForComple
   );
 }
 
+async function testBossChatPageShouldFallbackToEscapeWhenClosingCandidateDetail() {
+  const calls = [];
+  const mouseEvents = [];
+  let stateIndex = 0;
+  const states = [
+    {
+      open: true,
+      panelCount: 1,
+      closeCount: 1,
+      topPanelClass: "base-info-single-top-detail",
+      topPanelScore: 520,
+      panelRect: {
+        left: 940,
+        top: 60,
+        width: 360,
+        height: 720,
+        right: 1300,
+        bottom: 780
+      },
+      closeRect: {
+        left: 1274,
+        top: 12,
+        width: 30,
+        height: 30,
+        right: 1304,
+        bottom: 42
+      }
+    },
+    {
+      open: true,
+      panelCount: 1,
+      closeCount: 1,
+      topPanelClass: "base-info-single-top-detail",
+      topPanelScore: 520,
+      panelRect: {
+        left: 940,
+        top: 60,
+        width: 360,
+        height: 720,
+        right: 1300,
+        bottom: 780
+      },
+      closeRect: {
+        left: 1274,
+        top: 12,
+        width: 30,
+        height: 30,
+        right: 1304,
+        bottom: 42
+      }
+    },
+    {
+      open: false,
+      panelCount: 0,
+      closeCount: 0,
+      topPanelClass: "",
+      topPanelScore: 0,
+      panelRect: null,
+      closeRect: null
+    }
+  ];
+
+  const fakeChromeClient = {
+    Input: {
+      async dispatchMouseEvent(payload) {
+        mouseEvents.push(payload);
+      }
+    },
+    async pressEscape() {
+      calls.push("pressEscape");
+    },
+    async callFunction(fn) {
+      calls.push(fn.name);
+      if (fn.name === "browserIsCandidateDetailOpen") {
+        const value = states[Math.min(stateIndex, states.length - 1)];
+        stateIndex += 1;
+        return value;
+      }
+      if (fn.name === "browserCloseCandidateDetailDomOnce") {
+        return {
+          ok: true,
+          selector: ".close-btn",
+          method: "dom-click-once"
+        };
+      }
+      throw new Error(`unexpected function: ${fn.name}`);
+    }
+  };
+
+  const page = new BossChatPage(fakeChromeClient);
+  const result = await page.closeCandidateDetail({
+    maxAttempts: 1,
+    ensureDismiss: true
+  });
+
+  assert.equal(result.closed, true);
+  assert.equal(calls.includes("pressEscape"), true);
+  assert.equal(mouseEvents.length > 0, true);
+}
+
 async function testBossChatMcpToolsShouldValidateAndRoute() {
   await withBossChatWorkspace(async (workspaceRoot) => {
     const toolsResponse = await handleRequest({
@@ -1132,6 +1232,122 @@ async function testBossChatAppShouldResetPrimaryChatLabelBeforeInitialPrime() {
   assert.equal(summary.skipped, 1);
 }
 
+async function testBossChatAppShouldCloseCandidateDetailDuringRunCleanup() {
+  const calls = [];
+  const page = {
+    async ensureReady() {
+      calls.push("ensureReady");
+      return { hasListContainer: true, listItemCount: 1 };
+    },
+    async activatePrimaryChatLabel(label) {
+      calls.push(`activatePrimaryChatLabel:${label}`);
+      return { changed: false, verified: true, activeLabel: label };
+    },
+    async selectJob(jobSelection) {
+      calls.push(`selectJob:${jobSelection.label}`);
+      return jobSelection;
+    },
+    async activateUnreadFilter() {
+      calls.push("activateUnreadFilter");
+      return { changed: false, verified: true, activeLabel: "未读" };
+    },
+    async primeConversationByFirstCandidate() {
+      calls.push("primeConversationByFirstCandidate:1");
+      return {
+        candidate: {
+          customerId: "1008",
+          name: "候选人清理",
+          sourceJob: "算法工程师",
+          domIndex: 0
+        },
+        totalVisibleCandidates: 1,
+        readyState: {
+          hasOnlineResume: true,
+          hasAskResume: true,
+          hasAttachmentResume: false
+        }
+      };
+    },
+    async getLoadedCustomers() {
+      calls.push("getLoadedCustomers:1");
+      return [];
+    },
+    async closeResumeModalDomOnce() {
+      calls.push("closeResumeModalDomOnce");
+      return {
+        closed: true,
+        method: "already-closed",
+        finalState: { scopeCount: 0, iframeCount: 0, closeCount: 0, topScopeClass: "" }
+      };
+    },
+    async closeCandidateDetailDomOnce() {
+      calls.push("closeCandidateDetailDomOnce");
+      return {
+        closed: true,
+        method: "dom-close-once:.close-btn",
+        finalState: { panelCount: 0, closeCount: 0, topPanelClass: "" }
+      };
+    }
+  };
+  const stateStore = {
+    async load() {},
+    hasAny() {
+      return false;
+    },
+    async record() {}
+  };
+  const app = new BossChatApp({
+    page,
+    llmClient: {},
+    interaction: {
+      async sleepRange() {},
+      async maybeRest() {}
+    },
+    resumeCaptureService: {},
+    stateStore,
+    reportStore: {
+      async write() {
+        return "report.json";
+      }
+    },
+    logger: { log() {} },
+    dryRun: true,
+    artifactRootDir: os.tmpdir(),
+    resumeOpenCooldownMs: 0
+  });
+  app.waitForCandidateList = async ({ reason } = {}) => {
+    calls.push(`waitForCandidateList:${reason || "unknown"}`);
+    return {
+      ready: true,
+      waitedMs: 0,
+      attempts: 1,
+      listItemCount: 1,
+      lastError: ""
+    };
+  };
+  app.processCustomer = async () => ({
+    name: "候选人清理",
+    passed: false,
+    requested: false,
+    reason: "skip",
+    error: "",
+    artifacts: {}
+  });
+
+  const summary = await app.run({
+    screeningCriteria: "有 AI 项目经验",
+    targetCount: 1,
+    startFrom: "unread",
+    jobSelection: { label: "算法工程师", value: "job-1" },
+    chrome: { port: 9222 },
+    llm: { model: "gpt-test" }
+  });
+
+  assert.equal(summary.inspected, 1);
+  assert.equal(calls.includes("closeCandidateDetailDomOnce"), true);
+  assert.equal(calls.lastIndexOf("closeCandidateDetailDomOnce") > calls.indexOf("getLoadedCustomers:1"), true);
+}
+
 async function testBossChatAppShouldRestoreListContextAfterRecovery() {
   const calls = [];
   let primeCount = 0;
@@ -1509,6 +1725,7 @@ async function main() {
   await testBossChatPrepareShouldRetryWhenChatPageIsNotReady();
   await testBossChatPageShouldTreatBlankChatShellAsOnChatPage();
   await testBossChatRecoverToChatIndexShouldForceNavigateAndWaitForCompleteLoad();
+  await testBossChatPageShouldFallbackToEscapeWhenClosingCandidateDetail();
   await testBossChatMcpToolsShouldValidateAndRoute();
   await testBossChatCliShouldSupportRunAndFollowUpParsing();
   await testVendorBossChatCliShouldWaitForHydratedChatShell();
@@ -1519,6 +1736,7 @@ async function main() {
   await testBossChatLlmTextChunkFallbackShouldWork();
   await testBossChatLlmShouldApplyThinkingDefaultsAndOverrides();
   await testBossChatAppShouldResetPrimaryChatLabelBeforeInitialPrime();
+  await testBossChatAppShouldCloseCandidateDetailDuringRunCleanup();
   await testBossChatAppShouldRestoreListContextAfterRecovery();
   await testBossChatAppShouldWaitForCandidateListBeforePriming();
   await testBossChatAppShouldPersistEvidenceArtifacts();

package/vendor/boss-chat-cli/src/app.js

@@ -214,6 +214,46 @@ export class BossChatApp {
     };
   }
 
+  async cleanupPanels({
+    resumeMaxAttempts = 6,
+    detailMaxAttempts = 4,
+    ensureDismiss = true,
+  } = {}) {
+    const resume =
+      typeof this.page.closeResumeModalDomOnce === 'function'
+        ? await this.page.closeResumeModalDomOnce()
+        : await this.page.closeResumeModal({
+          maxAttempts: resumeMaxAttempts,
+          ensureDismiss,
+        });
+
+    let detail = {
+      closed: true,
+      method: 'unsupported',
+      finalState: {
+        panelCount: 0,
+        closeCount: 0,
+        topPanelClass: '',
+      },
+    };
+    if (typeof this.page.closeCandidateDetailDomOnce === 'function') {
+      detail = await this.page.closeCandidateDetailDomOnce();
+      if (!detail.closed && typeof this.page.closeCandidateDetail === 'function') {
+        detail = await this.page.closeCandidateDetail({
+          maxAttempts: detailMaxAttempts,
+          ensureDismiss,
+        });
+      }
+    } else if (typeof this.page.closeCandidateDetail === 'function') {
+      detail = await this.page.closeCandidateDetail({
+        maxAttempts: detailMaxAttempts,
+        ensureDismiss,
+      });
+    }
+
+    return { resume, detail };
+  }
+
   async run(profile) {
     const startedAt = new Date().toISOString();
     const runId = runToken(new Date());
@@ -576,12 +616,13 @@ export class BossChatApp {
     }
 
     try {
-      const finalClose =
-        typeof this.page.closeResumeModalDomOnce === 'function'
-          ? await this.page.closeResumeModalDomOnce()
-          : await this.page.closeResumeModal({ maxAttempts: 6, ensureDismiss: true });
+      const finalClose = await this.cleanupPanels({
+        resumeMaxAttempts: 6,
+        detailMaxAttempts: 4,
+        ensureDismiss: true,
+      });
       this.logger.log(
-        `运行收尾关闭简历弹层：closed=${finalClose.closed} | method=${finalClose.method}`,
+        `运行收尾关闭弹层：resumeClosed=${finalClose.resume.closed} | resumeMethod=${finalClose.resume.method} | detailClosed=${finalClose.detail.closed} | detailMethod=${finalClose.detail.method}`,
       );
     } catch (cleanupError) {
       this.logger.log(`运行收尾清理告警：${cleanupError?.message || cleanupError}`);
@@ -614,13 +655,17 @@ export class BossChatApp {
     let modalOpened = false;
     try {
       this.logger.log(`候选人开始：${customer.name || '未知'} (${customer.customerKey})`);
-      const preClose =
-        typeof this.page.closeResumeModalDomOnce === 'function'
-          ? await this.page.closeResumeModalDomOnce()
-          : await this.page.closeResumeModal({ maxAttempts: 4, ensureDismiss: true });
-      if (preClose.method !== 'already-closed') {
+      const preClose = await this.cleanupPanels({
+        resumeMaxAttempts: 4,
+        detailMaxAttempts: 3,
+        ensureDismiss: true,
+      });
+      if (
+        preClose.resume.method !== 'already-closed' ||
+        preClose.detail.method !== 'already-closed'
+      ) {
         this.logger.log(
-          `候选人开始前清理残留弹层：closed=${preClose.closed} | method=${preClose.method}`,
+          `候选人开始前清理残留面板：resumeClosed=${preClose.resume.closed} | resumeMethod=${preClose.resume.method} | detailClosed=${preClose.detail.closed} | detailMethod=${preClose.detail.method}`,
         );
       }
       if (!skipCardClick) {
@@ -980,6 +1025,24 @@ export class BossChatApp {
         }
       }
 
+      const finalPanels = await this.cleanupPanels({
+        resumeMaxAttempts: 4,
+        detailMaxAttempts: 4,
+        ensureDismiss: true,
+      });
+      baseResult.artifacts.finalResumeCloseMethod = finalPanels.resume.method;
+      baseResult.artifacts.finalResumeClosed = finalPanels.resume.closed;
+      baseResult.artifacts.finalDetailCloseMethod = finalPanels.detail.method;
+      baseResult.artifacts.finalDetailClosed = finalPanels.detail.closed;
+      if (
+        finalPanels.resume.method !== 'already-closed' ||
+        finalPanels.detail.method !== 'already-closed'
+      ) {
+        this.logger.log(
+          `候选人收尾清理：resumeClosed=${finalPanels.resume.closed} | resumeMethod=${finalPanels.resume.method} | detailClosed=${finalPanels.detail.closed} | detailMethod=${finalPanels.detail.method}`,
+        );
+      }
+
       await this.stateStore.record(baseResult.customerKey, baseResult, baseAliases);
       return baseResult;
     } catch (error) {
@@ -987,16 +1050,19 @@ export class BossChatApp {
         throw error;
       }
 
-      if (modalOpened) {
+      if (modalOpened || typeof this.page.closeCandidateDetailDomOnce === 'function' || typeof this.page.closeCandidateDetail === 'function') {
         try {
-          const closeResult =
-            typeof this.page.closeResumeModalDomOnce === 'function'
-              ? await this.page.closeResumeModalDomOnce()
-              : await this.page.closeResumeModal({ maxAttempts: 6, ensureDismiss: true });
-          baseResult.artifacts.resumeCloseMethod = closeResult.method;
-          baseResult.artifacts.resumeClosed = closeResult.closed;
+          const closeResult = await this.cleanupPanels({
+            resumeMaxAttempts: 6,
+            detailMaxAttempts: 4,
+            ensureDismiss: true,
+          });
+          baseResult.artifacts.resumeCloseMethod = closeResult.resume.method;
+          baseResult.artifacts.resumeClosed = closeResult.resume.closed;
+          baseResult.artifacts.finalDetailCloseMethod = closeResult.detail.method;
+          baseResult.artifacts.finalDetailClosed = closeResult.detail.closed;
           this.logger.log(
-            `异常后关闭简历结果：closed=${closeResult.closed} | method=${closeResult.method} | scope=${closeResult?.finalState?.scopeCount ?? 'n/a'} | iframe=${closeResult?.finalState?.iframeCount ?? 'n/a'} | close=${closeResult?.finalState?.closeCount ?? 'n/a'} | class=${closeResult?.finalState?.topScopeClass || 'n/a'}`,
+            `异常后关闭面板结果：resumeClosed=${closeResult.resume.closed} | resumeMethod=${closeResult.resume.method} | resumeScope=${closeResult?.resume?.finalState?.scopeCount ?? 'n/a'} | resumeIframe=${closeResult?.resume?.finalState?.iframeCount ?? 'n/a'} | resumeClose=${closeResult?.resume?.finalState?.closeCount ?? 'n/a'} | resumeClass=${closeResult?.resume?.finalState?.topScopeClass || 'n/a'} | detailClosed=${closeResult.detail.closed} | detailMethod=${closeResult.detail.method} | detailPanels=${closeResult?.detail?.finalState?.panelCount ?? 'n/a'} | detailClose=${closeResult?.detail?.finalState?.closeCount ?? 'n/a'} | detailClass=${closeResult?.detail?.finalState?.topPanelClass || 'n/a'}`,
           );
         } catch {}
       }

package/vendor/boss-chat-cli/src/browser/chat-page.js

@@ -1011,6 +1011,272 @@ function browserOpenOnlineResume(options = {}) {
   };
 }
 
+function browserIsCandidateDetailOpen() {
+  const collectSnapshot = () => {
+    const normalize = (value) => String(value || '').replace(/\s+/g, ' ').trim();
+    const isVisible = (el) => {
+      if (!(el instanceof HTMLElement)) return false;
+      const style = getComputedStyle(el);
+      if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity || '1') < 0.01) {
+        return false;
+      }
+      const rect = el.getBoundingClientRect();
+      return rect.width > 2 && rect.height > 2;
+    };
+    const rectToJson = (rect) => ({
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height,
+      right: rect.right,
+      bottom: rect.bottom,
+    });
+    const panelSelectors = [
+      '.base-info-single-top-detail',
+      '.resume-detail-wrap',
+      '.geek-card-detail',
+      '.candidate-detail-wrap',
+      '.chat-detail-wrap',
+    ];
+    const closeButtons = Array.from(document.querySelectorAll('.close-btn')).filter(isVisible);
+    const panelEntries = [];
+    const seen = new Set();
+    const pushPanel = (node, source) => {
+      if (!(node instanceof HTMLElement) || !isVisible(node)) return;
+      const rect = node.getBoundingClientRect();
+      if (rect.width < 240 || rect.height < 160) return;
+      const key = `${Math.round(rect.left)}:${Math.round(rect.top)}:${Math.round(rect.width)}:${Math.round(rect.height)}:${normalize(node.className || '')}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      panelEntries.push({ node, rect, source });
+    };
+
+    for (const selector of panelSelectors) {
+      for (const node of Array.from(document.querySelectorAll(selector))) {
+        pushPanel(node, `selector:${selector}`);
+      }
+    }
+
+    for (const closeButton of closeButtons) {
+      let current = closeButton.parentElement;
+      let depth = 0;
+      while (current instanceof HTMLElement && depth < 10) {
+        pushPanel(current, 'close-ancestor');
+        current = current.parentElement;
+        depth += 1;
+      }
+    }
+
+    const scoredPanels = panelEntries
+      .map((entry) => {
+        const classText = normalize(entry.node.className || '').toLowerCase();
+        const text = normalize(entry.node.textContent || '').slice(0, 240).toLowerCase();
+        const containsClose = closeButtons.some((button) => entry.node.contains(button));
+        const anchoredRight =
+          entry.rect.left >= window.innerWidth * 0.4 ||
+          entry.rect.right >= window.innerWidth * 0.72;
+        const hasKnownDetailClass =
+          classText.includes('base-info-single-top-detail') ||
+          classText.includes('resume-detail-wrap') ||
+          classText.includes('candidate-detail') ||
+          classText.includes('chat-detail') ||
+          classText.includes('geek-card-detail');
+        const hasDetailHint =
+          text.includes('在线简历') ||
+          text.includes('附件简历') ||
+          text.includes('牛人分析器') ||
+          text.includes('活跃');
+
+        let score = 0;
+        if (containsClose) score += 220;
+        if (anchoredRight) score += 140;
+        if (hasKnownDetailClass) score += 160;
+        if (hasDetailHint) score += 80;
+        if (entry.source === 'close-ancestor') score += 40;
+        score += Math.min(180, Math.floor((entry.rect.width * entry.rect.height) / 12000));
+
+        return {
+          ...entry,
+          score,
+        };
+      })
+      .sort((a, b) => b.score - a.score);
+
+    const topPanel = scoredPanels[0] || null;
+    const topPanelNode = topPanel?.node || null;
+    const closeButton =
+      closeButtons.find((button) => topPanelNode instanceof HTMLElement && topPanelNode.contains(button)) ||
+      closeButtons[0] ||
+      null;
+
+    return {
+      open: Boolean(topPanel || closeButton),
+      panelCount: scoredPanels.length,
+      closeCount: closeButtons.length,
+      topPanelClass: normalize(topPanelNode?.className || ''),
+      topPanelScore: Number(topPanel?.score || 0),
+      panelRect: topPanel ? rectToJson(topPanel.rect) : null,
+      closeRect: closeButton ? rectToJson(closeButton.getBoundingClientRect()) : null,
+    };
+  };
+
+  return collectSnapshot();
+}
+
+function browserCloseCandidateDetailDomOnce() {
+  const collectSnapshot = () => {
+    const normalize = (value) => String(value || '').replace(/\s+/g, ' ').trim();
+    const isVisible = (el) => {
+      if (!(el instanceof HTMLElement)) return false;
+      const style = getComputedStyle(el);
+      if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity || '1') < 0.01) {
+        return false;
+      }
+      const rect = el.getBoundingClientRect();
+      return rect.width > 2 && rect.height > 2;
+    };
+    const rectToJson = (rect) => ({
+      left: rect.left,
+      top: rect.top,
+      width: rect.width,
+      height: rect.height,
+      right: rect.right,
+      bottom: rect.bottom,
+    });
+    const panelSelectors = [
+      '.base-info-single-top-detail',
+      '.resume-detail-wrap',
+      '.geek-card-detail',
+      '.candidate-detail-wrap',
+      '.chat-detail-wrap',
+    ];
+    const closeButtons = Array.from(document.querySelectorAll('.close-btn')).filter(isVisible);
+    const panelEntries = [];
+    const seen = new Set();
+    const pushPanel = (node, source) => {
+      if (!(node instanceof HTMLElement) || !isVisible(node)) return;
+      const rect = node.getBoundingClientRect();
+      if (rect.width < 240 || rect.height < 160) return;
+      const key = `${Math.round(rect.left)}:${Math.round(rect.top)}:${Math.round(rect.width)}:${Math.round(rect.height)}:${normalize(node.className || '')}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      panelEntries.push({ node, rect, source });
+    };
+
+    for (const selector of panelSelectors) {
+      for (const node of Array.from(document.querySelectorAll(selector))) {
+        pushPanel(node, `selector:${selector}`);
+      }
+    }
+
+    for (const closeButton of closeButtons) {
+      let current = closeButton.parentElement;
+      let depth = 0;
+      while (current instanceof HTMLElement && depth < 10) {
+        pushPanel(current, 'close-ancestor');
+        current = current.parentElement;
+        depth += 1;
+      }
+    }
+
+    const scoredPanels = panelEntries
+      .map((entry) => {
+        const classText = normalize(entry.node.className || '').toLowerCase();
+        const text = normalize(entry.node.textContent || '').slice(0, 240).toLowerCase();
+        const containsClose = closeButtons.some((button) => entry.node.contains(button));
+        const anchoredRight =
+          entry.rect.left >= window.innerWidth * 0.4 ||
+          entry.rect.right >= window.innerWidth * 0.72;
+        const hasKnownDetailClass =
+          classText.includes('base-info-single-top-detail') ||
+          classText.includes('resume-detail-wrap') ||
+          classText.includes('candidate-detail') ||
+          classText.includes('chat-detail') ||
+          classText.includes('geek-card-detail');
+        const hasDetailHint =
+          text.includes('在线简历') ||
+          text.includes('附件简历') ||
+          text.includes('牛人分析器') ||
+          text.includes('活跃');
+
+        let score = 0;
+        if (containsClose) score += 220;
+        if (anchoredRight) score += 140;
+        if (hasKnownDetailClass) score += 160;
+        if (hasDetailHint) score += 80;
+        if (entry.source === 'close-ancestor') score += 40;
+        score += Math.min(180, Math.floor((entry.rect.width * entry.rect.height) / 12000));
+
+        return {
+          ...entry,
+          score,
+        };
+      })
+      .sort((a, b) => b.score - a.score);
+
+    const topPanel = scoredPanels[0] || null;
+    const topPanelNode = topPanel?.node || null;
+    const closeButton =
+      closeButtons.find((button) => topPanelNode instanceof HTMLElement && topPanelNode.contains(button)) ||
+      closeButtons[0] ||
+      null;
+
+    return {
+      open: Boolean(topPanel || closeButton),
+      panelCount: scoredPanels.length,
+      closeCount: closeButtons.length,
+      topPanelClass: normalize(topPanelNode?.className || ''),
+      topPanelScore: Number(topPanel?.score || 0),
+      panelRect: topPanel ? rectToJson(topPanel.rect) : null,
+      closeRect: closeButton ? rectToJson(closeButton.getBoundingClientRect()) : null,
+      closeButton,
+    };
+  };
+  const serializeSnapshot = (snapshot = {}) => ({
+    open: Boolean(snapshot?.open),
+    panelCount: Number(snapshot?.panelCount || 0),
+    closeCount: Number(snapshot?.closeCount || 0),
+    topPanelClass: String(snapshot?.topPanelClass || ''),
+    topPanelScore: Number(snapshot?.topPanelScore || 0),
+    panelRect: snapshot?.panelRect || null,
+    closeRect: snapshot?.closeRect || null,
+  });
+
+  const snapshot = collectSnapshot();
+  if (!snapshot?.open || !(snapshot.closeButton instanceof HTMLElement)) {
+    return {
+      ok: false,
+      error: 'CANDIDATE_DETAIL_CLOSE_BUTTON_NOT_FOUND',
+      state: serializeSnapshot(snapshot),
+    };
+  }
+
+  try {
+    snapshot.closeButton.click();
+    const rect = snapshot.closeButton.getBoundingClientRect();
+    return {
+      ok: true,
+      selector: '.close-btn',
+      method: 'dom-click-once',
+      rect: {
+        left: rect.left,
+        top: rect.top,
+        width: rect.width,
+        height: rect.height,
+        right: rect.right,
+        bottom: rect.bottom,
+      },
+      state: serializeSnapshot(snapshot),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `CANDIDATE_DETAIL_DOM_CLOSE_FAILED:${error?.message || error}`,
+      state: serializeSnapshot(snapshot),
+    };
+  }
+}
+
 function browserCloseResumeModalDomOnce() {
   const isVisible = (el) => {
     if (!(el instanceof HTMLElement)) return false;
@@ -2596,6 +2862,160 @@ export class BossChatPage {
     };
   }
 
+  async isCandidateDetailOpen() {
+    const result = await this.chromeClient.callFunction(browserIsCandidateDetailOpen);
+    return Boolean(result?.open);
+  }
+
+  async getCandidateDetailState() {
+    const result = await this.chromeClient.callFunction(browserIsCandidateDetailOpen);
+    return {
+      open: Boolean(result?.open),
+      panelCount: Number(result?.panelCount || 0),
+      closeCount: Number(result?.closeCount || 0),
+      topPanelClass: String(result?.topPanelClass || ''),
+      topPanelScore: Number(result?.topPanelScore || 0),
+      panelRect: result?.panelRect || null,
+      closeRect: result?.closeRect || null,
+    };
+  }
+
+  async closeCandidateDetailDomOnce() {
+    const stateBefore = await this.getCandidateDetailState();
+    const drawerOpen = (state) =>
+      Boolean(state?.open) ||
+      Number(state?.panelCount || 0) > 0 ||
+      Number(state?.closeCount || 0) > 0;
+    const openBefore = drawerOpen(stateBefore);
+    if (!openBefore) {
+      return {
+        closed: true,
+        method: 'already-closed',
+        finalState: stateBefore,
+      };
+    }
+
+    const result = await this.chromeClient.callFunction(browserCloseCandidateDetailDomOnce);
+    if (!result?.ok) {
+      const finalState = await this.getCandidateDetailState();
+      return {
+        closed: false,
+        method: `dom-close-miss:${result?.error || 'unknown'}`,
+        finalState,
+      };
+    }
+
+    let finalState = await this.getCandidateDetailState();
+    let openAfter = drawerOpen(finalState);
+    for (let attempt = 0; openAfter && attempt < 8; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, 220));
+      finalState = await this.getCandidateDetailState();
+      openAfter = drawerOpen(finalState);
+    }
+    return {
+      closed: !openAfter,
+      method: `dom-close-once:${result.selector || '.close-btn'}`,
+      finalState,
+    };
+  }
+
+  async closeCandidateDetail({ maxAttempts = 4, ensureDismiss = false } = {}) {
+    const drawerOpen = (state) =>
+      Boolean(state?.open) ||
+      Number(state?.panelCount || 0) > 0 ||
+      Number(state?.closeCount || 0) > 0;
+    const methods = [];
+    for (let index = 0; index < maxAttempts; index += 1) {
+      const state = await this.getCandidateDetailState();
+      if (!drawerOpen(state) && !ensureDismiss) {
+        return {
+          closed: true,
+          method: methods.join('+') || 'already-closed',
+          finalState: state,
+        };
+      }
+
+      const selectorResult = await this.chromeClient.callFunction(browserCloseCandidateDetailDomOnce);
+      if (selectorResult?.ok) {
+        methods.push(`selector:${selectorResult.selector || '.close-btn'}`);
+      } else {
+        methods.push(`selector-miss:${selectorResult?.error || 'unknown'}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 220));
+
+      let midState = await this.getCandidateDetailState();
+      if (!drawerOpen(midState)) {
+        return {
+          closed: true,
+          method: methods.join('+'),
+          finalState: midState,
+        };
+      }
+
+      if (midState?.panelRect) {
+        await this.clickRect(midState.panelRect);
+        methods.push('focus-panel');
+        await new Promise((resolve) => setTimeout(resolve, 160));
+      } else if (midState?.closeRect) {
+        await this.clickRect(midState.closeRect);
+        methods.push('focus-close');
+        await new Promise((resolve) => setTimeout(resolve, 160));
+      }
+
+      await this.chromeClient.pressEscape();
+      methods.push('escape');
+      await new Promise((resolve) => setTimeout(resolve, 220));
+
+      midState = await this.getCandidateDetailState();
+      if (!drawerOpen(midState)) {
+        return {
+          closed: true,
+          method: methods.join('+'),
+          finalState: midState,
+        };
+      }
+
+      if (midState?.closeRect) {
+        await this.clickRect(midState.closeRect);
+        methods.push('rect-close');
+        await new Promise((resolve) => setTimeout(resolve, 220));
+        midState = await this.getCandidateDetailState();
+        if (!drawerOpen(midState)) {
+          return {
+            closed: true,
+            method: methods.join('+'),
+            finalState: midState,
+          };
+        }
+      }
+
+      if (ensureDismiss && index >= 1) {
+        const finalSweep = await this.getCandidateDetailState();
+        if (!drawerOpen(finalSweep)) {
+          return {
+            closed: true,
+            method: methods.join('+'),
+            finalState: finalSweep,
+          };
+        }
+      }
+    }
+
+    const finalState = await this.getCandidateDetailState();
+    if (!drawerOpen(finalState)) {
+      return {
+        closed: true,
+        method: methods.join('+') || 'fallback',
+        finalState,
+      };
+    }
+    return {
+      closed: false,
+      method: methods.join('+') || 'failed',
+      finalState,
+    };
+  }
+
   async waitForResumeModalOpen(options = {}) {
     const maxAttempts = options.maxAttempts || 30;
     const delayMs = options.delayMs || 300;