@reconcrap/boss-recommend-mcp 1.0.11 → 1.0.13

package/README.md

@@ -9,8 +9,8 @@ Boss 推荐页自动化流水线 MCP（stdio）服务。
 
 MCP 工具：
 
-- `run_recommend_pipeline`（同步，兼容旧 agent）
-- `start_recommend_pipeline_run`（异步启动，立即返回 run_id）
+- `run_recommend_pipeline`（默认异步，但会先执行与同步一致的前置门禁；仅门禁通过后返回 run_id）
+- `start_recommend_pipeline_run`（异步启动；同样先经过前置门禁，通过后返回 run_id）
 - `get_recommend_pipeline_run`（轮询 run_id 状态）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
 
@@ -143,13 +143,15 @@ node src/cli.js run --instruction-file request.txt --confirmation-file confirmat
 
 当宿主 agent 对“长时间无回包”敏感（容易误判失败）时，建议改用异步工具：
 
-1. 先调用 `start_recommend_pipeline_run`，拿到 `run_id`。
-2. 每 5~15 秒调用一次 `get_recommend_pipeline_run` 轮询。
-3. 若需终止，调用 `cancel_recommend_pipeline_run`。
+1. 优先调用 `run_recommend_pipeline`（默认异步）。
+2. 若返回 `NEED_INPUT/NEED_CONFIRMATION/FAILED`，按同步流程先补齐前置条件（登录、页面就绪、岗位确认、最终确认）。
+3. 仅当门禁通过时，接口才会返回 `ACCEPTED + run_id`；随后每 5~15 秒调用一次 `get_recommend_pipeline_run` 轮询。
+4. 若需终止，调用 `cancel_recommend_pipeline_run`。
 
 说明：
 
-- 同步工具 `run_recommend_pipeline` 继续保留，不影响旧流程。
+- `run_recommend_pipeline` 默认异步，但不会跳过同步确认流程；若确实需要阻塞式返回，可传 `execution_mode=sync`。
+- 定时心跳默认 120 秒一次；`updated_at` 仍会在阶段或进度变化时刷新。
 - 每个 run 会持久化到 `~/.boss-recommend-mcp/runs/<run_id>.json`（可通过 `BOSS_RECOMMEND_HOME` 覆盖）。
 - 轮询期间不要重复 `start`，优先复用已有 `run_id`，避免重复筛选。
 

package/package.json

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

package/skills/boss-recommend-pipeline/SKILL.md

@@ -80,9 +80,10 @@ description: "Use when users ask to run Boss recommend-page filtering and screen
 
 ## Tool Contract
 
-- Tool name（同步，默认兼容）: `run_recommend_pipeline`
+- Tool name（默认异步）: `run_recommend_pipeline`
 - Input:
-  - `instruction` (required)
+  - `execution_mode`（可选：`async|sync`，默认 `async`）
+  - `instruction` (required)
   - `confirmation`
     - `filters_confirmed`
     - `school_tag_confirmed`
@@ -116,13 +117,15 @@ description: "Use when users ask to run Boss recommend-page filtering and screen
 
 长耗时宿主兼容（推荐）：
 
-- 若宿主存在“工具超时误判”风险，优先改用异步三件套：
+- `run_recommend_pipeline` 默认异步，但开始前会先走与同步一致的前置门禁（登录/页面就绪/岗位确认/最终确认）。
+- 只有门禁通过后才会返回 `ACCEPTED + run_id`；否则会先返回 `NEED_INPUT/NEED_CONFIRMATION/FAILED`，必须先按提示补齐。
+- 若宿主要显式拆成三步，也可使用：
   - `start_recommend_pipeline_run`
   - `get_recommend_pipeline_run`
   - `cancel_recommend_pipeline_run`
 - 建议轮询间隔 5~15 秒。
 - 已有 `run_id` 时不要重复 start，优先继续轮询同一个 run。
-- 若宿主明确只支持同步工具，再回退 `run_recommend_pipeline`。
+- 若宿主明确需要阻塞式返回，再传 `execution_mode=sync`。
 
 ## Execution Notes
 

package/src/index.js

@@ -16,6 +16,7 @@ import {
   createRunStateSnapshot,
   getRunHeartbeatIntervalMs,
   readRunState,
+  touchRunHeartbeat,
   updateRunProgress,
   updateRunState,
   writeRunState
@@ -77,6 +78,11 @@ function createRunInputSchema() {
         type: "string",
         description: "用户自然语言推荐筛选指令"
       },
+      execution_mode: {
+        type: "string",
+        enum: [RUN_MODE_ASYNC, RUN_MODE_SYNC],
+        description: "执行模式；默认 async。"
+      },
       confirmation: {
         type: "object",
         properties: {
@@ -215,12 +221,12 @@ function createToolsSchema() {
   return [
     {
       name: TOOL_RUN_PIPELINE,
-      description: "Boss 推荐页同步流水线：解析推荐筛选指令并执行 search+screen，直到返回最终结果。",
+      description: "Boss 推荐页流水线：默认异步，但会先走与同步一致的前置确认/页面就绪门禁；仅在门禁通过后返回 run_id。传 execution_mode=sync 可改为全程同步执行。",
       inputSchema: createRunInputSchema()
     },
     {
       name: TOOL_START_RUN,
-      description: "异步启动 Boss 推荐页流水线，立即返回 run_id，后续通过 get_recommend_pipeline_run 轮询状态。",
+      description: "异步启动 Boss 推荐页流水线（含同步门禁预检）；只有在前置确认与页面就绪通过后才返回 run_id。",
       inputSchema: createRunInputSchema()
     },
     {
@@ -285,6 +291,49 @@ function getLastOutputLine(text) {
   return lines.length > 0 ? lines[lines.length - 1] : null;
 }
 
+function normalizeExecutionMode(value) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (normalized === RUN_MODE_SYNC) return RUN_MODE_SYNC;
+  return RUN_MODE_ASYNC;
+}
+
+function normalizeRequiredConfirmations(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item) => normalizeText(item))
+    .filter(Boolean);
+}
+
+function hasExplicitFinalConfirmation(args) {
+  return args?.confirmation?.final_confirmed === true;
+}
+
+function buildAsyncPrecheckConfirmation(confirmation) {
+  if (!confirmation || typeof confirmation !== "object") {
+    return {
+      final_confirmed: false
+    };
+  }
+  return {
+    ...confirmation,
+    final_confirmed: false
+  };
+}
+
+function buildAsyncPrecheckArgs(args) {
+  return {
+    instruction: args.instruction,
+    confirmation: buildAsyncPrecheckConfirmation(args.confirmation),
+    overrides: args.overrides
+  };
+}
+
+function isFinalReviewOnlyConfirmation(result) {
+  if (result?.status !== "NEED_CONFIRMATION") return false;
+  const required = normalizeRequiredConfirmations(result.required_confirmations);
+  return required.length > 0 && required.every((item) => item === "final_review");
+}
+
 function safeUpdateRunState(runId, updater) {
   try {
     return updateRunState(runId, updater);
@@ -324,6 +373,11 @@ function createRuntimeCallbacks(runId, heartbeatIntervalMs) {
         patch.last_message = detailsMessage;
       }
       safeUpdateRunState(runId, patch);
+      try {
+        touchRunHeartbeat(runId, detailsMessage || undefined);
+      } catch {
+        // Ignore heartbeat persistence failures here; state updates above already best-effort.
+      }
     },
     onOutput(event) {
       const stage = normalizeText(event?.stage) || lastStage;
@@ -523,7 +577,38 @@ async function handleSyncRunTool({ workspaceRoot, args }) {
   return attachSyncRunMetadata(tracked.result, runId, tracked.lastStage);
 }
 
-function handleStartRunTool({ workspaceRoot, args }) {
+async function handleStartRunTool({ workspaceRoot, args }) {
+  const precheckArgs = buildAsyncPrecheckArgs(args);
+  let precheckResult;
+  try {
+    precheckResult = await runPipelineImpl(
+      {
+        workspaceRoot,
+        instruction: precheckArgs.instruction,
+        confirmation: precheckArgs.confirmation,
+        overrides: precheckArgs.overrides
+      },
+      undefined,
+      null
+    );
+  } catch (error) {
+    precheckResult = {
+      status: "FAILED",
+      error: {
+        code: "UNEXPECTED_ERROR",
+        message: error?.message || "Unexpected error",
+        retryable: true
+      }
+    };
+  }
+
+  if (precheckResult?.status !== "NEED_CONFIRMATION") {
+    return precheckResult;
+  }
+  if (!hasExplicitFinalConfirmation(args) || !isFinalReviewOnlyConfirmation(precheckResult)) {
+    return precheckResult;
+  }
+
   cleanupExpiredRuns();
   const runId = createRunId();
   try {
@@ -699,9 +784,12 @@ async function handleRequest(message, workspaceRoot) {
     try {
       let payload;
       if (toolName === TOOL_RUN_PIPELINE) {
-        payload = await handleSyncRunTool({ workspaceRoot, args });
+        const executionMode = normalizeExecutionMode(args.execution_mode);
+        payload = executionMode === RUN_MODE_SYNC
+          ? await handleSyncRunTool({ workspaceRoot, args })
+          : await handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_START_RUN) {
-        payload = handleStartRunTool({ workspaceRoot, args });
+        payload = await handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_RUN) {
         payload = handleGetRunTool(args);
       } else if (toolName === TOOL_CANCEL_RUN) {

package/src/run-state.js

@@ -19,7 +19,7 @@ export const RUN_STAGE_SEARCH = "search";
 export const RUN_STAGE_SCREEN = "screen";
 export const RUN_STAGE_FINALIZE = "finalize";
 
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 120_000;
 const DEFAULT_RETENTION_MS = 24 * 60 * 60 * 1000;
 
 const VALID_RUN_MODES = new Set([RUN_MODE_SYNC, RUN_MODE_ASYNC]);
@@ -229,13 +229,18 @@ export function updateRunState(runId, updater) {
         : current.last_message
     ),
     updated_at: now,
-    heartbeat_at: String(patch.heartbeat_at || now)
+    heartbeat_at: String(
+      Object.prototype.hasOwnProperty.call(patch, "heartbeat_at")
+        ? (patch.heartbeat_at || now)
+        : current.heartbeat_at
+    )
   };
   return writeRunState(next);
 }
 
 export function touchRunHeartbeat(runId, message = null) {
   return updateRunState(runId, (current) => ({
+    heartbeat_at: toIsoNow(),
     last_message: message ?? current.last_message
   }));
 }
@@ -286,4 +291,3 @@ export function cleanupExpiredRuns(retentionMs = getRunRetentionMs()) {
   }
   return { removed, failed };
 }
-

package/src/test-index-async.js

@@ -52,6 +52,31 @@ async function testAsyncStartStatusCancelAndSyncCompatibility() {
   const tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "boss-recommend-index-async-"));
 
   setRunPipelineImplForTests(async (input, _deps, runtime) => {
+    if (input.confirmation?.job_confirmed !== true) {
+      return {
+        status: "NEED_CONFIRMATION",
+        required_confirmations: ["job"],
+        pending_questions: [
+          {
+            field: "job",
+            question: "请先确认岗位"
+          }
+        ]
+      };
+    }
+    if (input.confirmation?.final_confirmed !== true) {
+      return {
+        status: "NEED_CONFIRMATION",
+        required_confirmations: ["final_review"],
+        pending_questions: [
+          {
+            field: "final_review",
+            question: "请做最终确认"
+          }
+        ]
+      };
+    }
+
     runtime?.onStage?.({ stage: "preflight", message: "preflight started" });
     await sleep(50);
     if (input.instruction.includes("fail")) {
@@ -96,17 +121,33 @@ async function testAsyncStartStatusCancelAndSyncCompatibility() {
   process.env.BOSS_RECOMMEND_HOME = tempHome;
 
   try {
-    const startResponse = await handleRequest(
+    const gatedStartResponse = await handleRequest(
       makeToolCall(1, "start_recommend_pipeline_run", { instruction: "slow task for cancel" }),
       process.cwd()
     );
+    const gatedStartPayload = await readToolPayload(gatedStartResponse);
+    assert.equal(gatedStartPayload.status, "NEED_CONFIRMATION");
+    assert.deepEqual(gatedStartPayload.required_confirmations, ["job"]);
+    assert.equal(gatedStartPayload.run_id, undefined);
+
+    const startResponse = await handleRequest(
+      makeToolCall(2, "start_recommend_pipeline_run", {
+        instruction: "slow task for cancel",
+        confirmation: {
+          job_confirmed: true,
+          job_value: "mock job",
+          final_confirmed: true
+        }
+      }),
+      process.cwd()
+    );
     const started = await readToolPayload(startResponse);
     assert.equal(started.status, "ACCEPTED");
     assert.equal(typeof started.run_id, "string");
     assert.equal(started.poll_after_sec >= 5 && started.poll_after_sec <= 15, true);
 
     const statusResponse = await handleRequest(
-      makeToolCall(2, "get_recommend_pipeline_run", { run_id: started.run_id }),
+      makeToolCall(3, "get_recommend_pipeline_run", { run_id: started.run_id }),
       process.cwd()
     );
     const initialStatus = await readToolPayload(statusResponse);
@@ -114,7 +155,7 @@ async function testAsyncStartStatusCancelAndSyncCompatibility() {
     assert.equal(["queued", "running"].includes(initialStatus.run.state), true);
 
     const cancelResponse = await handleRequest(
-      makeToolCall(3, "cancel_recommend_pipeline_run", { run_id: started.run_id }),
+      makeToolCall(4, "cancel_recommend_pipeline_run", { run_id: started.run_id }),
       process.cwd()
     );
     const canceled = await readToolPayload(cancelResponse);
@@ -123,8 +164,41 @@ async function testAsyncStartStatusCancelAndSyncCompatibility() {
     const canceledRun = await waitForTerminalRunState(started.run_id);
     assert.equal(canceledRun.state, "canceled");
 
+    const defaultAsyncGatedResponse = await handleRequest(
+      makeToolCall(5, "run_recommend_pipeline", { instruction: "fast default async gate" }),
+      process.cwd()
+    );
+    const defaultAsyncGatedPayload = await readToolPayload(defaultAsyncGatedResponse);
+    assert.equal(defaultAsyncGatedPayload.status, "NEED_CONFIRMATION");
+    assert.deepEqual(defaultAsyncGatedPayload.required_confirmations, ["job"]);
+
+    const defaultAsyncResponse = await handleRequest(
+      makeToolCall(6, "run_recommend_pipeline", {
+        instruction: "fast async accepted run",
+        confirmation: {
+          job_confirmed: true,
+          job_value: "mock job",
+          final_confirmed: true
+        }
+      }),
+      process.cwd()
+    );
+    const defaultAsyncPayload = await readToolPayload(defaultAsyncResponse);
+    assert.equal(defaultAsyncPayload.status, "ACCEPTED");
+    assert.equal(typeof defaultAsyncPayload.run_id, "string");
+    const completedDefaultAsyncRun = await waitForTerminalRunState(defaultAsyncPayload.run_id);
+    assert.equal(completedDefaultAsyncRun.state, "completed");
+
     const syncResponse = await handleRequest(
-      makeToolCall(4, "run_recommend_pipeline", { instruction: "fast sync run" }),
+      makeToolCall(7, "run_recommend_pipeline", {
+        instruction: "fast forced sync run",
+        execution_mode: "sync",
+        confirmation: {
+          job_confirmed: true,
+          job_value: "mock job",
+          final_confirmed: true
+        }
+      }),
       process.cwd()
     );
     const syncPayload = await readToolPayload(syncResponse);
@@ -132,11 +206,19 @@ async function testAsyncStartStatusCancelAndSyncCompatibility() {
     assert.equal(typeof syncPayload.result.run_id, "string");
     assert.equal(syncPayload.result.processed_count, 40);
 
-    const syncFailedResponse = await handleRequest(
-      makeToolCall(5, "run_recommend_pipeline", { instruction: "force fail" }),
+    const failedSyncResponse = await handleRequest(
+      makeToolCall(8, "run_recommend_pipeline", {
+        instruction: "force fail",
+        execution_mode: "sync",
+        confirmation: {
+          job_confirmed: true,
+          job_value: "mock job",
+          final_confirmed: true
+        }
+      }),
       process.cwd()
     );
-    const syncFailedPayload = await readToolPayload(syncFailedResponse);
+    const syncFailedPayload = await readToolPayload(failedSyncResponse);
     assert.equal(syncFailedPayload.status, "FAILED");
     assert.equal(typeof syncFailedPayload.diagnostics?.run_id, "string");
     assert.equal(typeof syncFailedPayload.diagnostics?.last_stage, "string");

package/src/test-run-state.js

@@ -13,6 +13,7 @@ import {
   createRunStateSnapshot,
   getRunsDir,
   readRunState,
+  touchRunHeartbeat,
   updateRunProgress,
   updateRunState,
   writeRunState
@@ -53,6 +54,7 @@ function testRunStateLifecycle() {
     });
     assert.equal(running.state, RUN_STATE_RUNNING);
     assert.equal(running.stage, RUN_STAGE_SCREEN);
+    const heartbeatBeforeProgress = running.heartbeat_at;
 
     const progressed = updateRunProgress(runId, {
       processed: 7,
@@ -64,6 +66,11 @@ function testRunStateLifecycle() {
     assert.equal(progressed.progress.passed, 2);
     assert.equal(progressed.progress.skipped, 5);
     assert.equal(progressed.progress.greet_count, 1);
+    assert.equal(progressed.heartbeat_at, heartbeatBeforeProgress);
+
+    const heartbeated = touchRunHeartbeat(runId, "still running");
+    assert.equal(heartbeated.last_message, "still running");
+    assert.equal(Date.parse(heartbeated.heartbeat_at) >= Date.parse(heartbeatBeforeProgress), true);
 
     const completed = updateRunState(runId, {
       state: RUN_STATE_COMPLETED,
@@ -105,4 +112,3 @@ function main() {
 }
 
 main();
-

package/vendor/boss-recommend-screen-cli/boss-recommend-screen-cli.cjs

@@ -368,6 +368,7 @@ const jsGetListState = `(() => {
   }
   const doc = frame.contentDocument;
   const body = doc.body;
+  const frameRect = frame.getBoundingClientRect();
   const cards = Array.from(doc.querySelectorAll('ul.card-list > li.card-item'));
   const candidateCards = cards.filter((card) => card.querySelector('.card-inner[data-geekid]'));
   return {
@@ -375,6 +376,15 @@ const jsGetListState = `(() => {
     scrollTop: body ? body.scrollTop : 0,
     scrollHeight: body ? body.scrollHeight : 0,
     clientHeight: body ? body.clientHeight : 0,
+    clientWidth: body ? body.clientWidth : 0,
+    frameRect: {
+      width: frameRect.width,
+      height: frameRect.height
+    },
+    viewport: {
+      width: (doc.defaultView && Number.isFinite(doc.defaultView.innerWidth)) ? doc.defaultView.innerWidth : 0,
+      height: (doc.defaultView && Number.isFinite(doc.defaultView.innerHeight)) ? doc.defaultView.innerHeight : 0
+    },
     candidateCount: candidateCards.length,
     totalCards: cards.length
   };
@@ -1024,7 +1034,9 @@ class RecommendScreenCli {
     this.Runtime = null;
     this.Input = null;
     this.Page = null;
+    this.Browser = null;
     this.target = null;
+    this.windowId = null;
     this.discoveredKeys = new Set();
     this.processedKeys = new Set();
     this.candidateQueue = [];
@@ -1053,12 +1065,21 @@ class RecommendScreenCli {
       throw this.buildError("RECOMMEND_PAGE_NOT_READY", "No debuggable recommend page target found.");
     }
     this.client = await CDP({ port: this.args.port, target: this.target });
-    const { Runtime, Input, Page } = this.client;
+    const { Runtime, Input, Page, Browser } = this.client;
     this.Runtime = Runtime;
     this.Input = Input;
     this.Page = Page;
+    this.Browser = Browser || null;
     await Runtime.enable();
     await Page.enable();
+    if (this.Browser && typeof this.Browser.getWindowForTarget === "function") {
+      try {
+        const windowInfo = await this.Browser.getWindowForTarget();
+        if (Number.isInteger(windowInfo?.windowId)) {
+          this.windowId = windowInfo.windowId;
+        }
+      } catch {}
+    }
     await Page.bringToFront();
   }
 
@@ -1155,7 +1176,92 @@ class RecommendScreenCli {
     return state?.closed === false;
   }
 
+  async getListState() {
+    const state = await this.evaluate(jsGetListState);
+    if (state && typeof state === "object") return state;
+    return { ok: false, error: "INVALID_LIST_STATE" };
+  }
+
+  isListViewportCollapsed(state) {
+    if (!state?.ok) return false;
+    const clientHeight = Number(state.clientHeight || 0);
+    const clientWidth = Number(state.clientWidth || 0);
+    const frameWidth = Number(state.frameRect?.width || 0);
+    const frameHeight = Number(state.frameRect?.height || 0);
+    const viewportWidth = Number(state.viewport?.width || 0);
+    const viewportHeight = Number(state.viewport?.height || 0);
+
+    return (
+      (clientHeight > 0 && clientHeight < 260)
+      || (clientWidth > 0 && clientWidth < 280)
+      || (frameHeight > 0 && frameHeight < 320)
+      || (frameWidth > 0 && frameWidth < 460)
+      || (viewportHeight > 0 && viewportHeight < 260)
+      || (viewportWidth > 0 && viewportWidth < 360)
+    );
+  }
+
+  async maximizeWindowIfPossible(reason = "unknown") {
+    if (!this.Browser || !this.windowId || typeof this.Browser.setWindowBounds !== "function") {
+      return false;
+    }
+    try {
+      await this.Browser.setWindowBounds({
+        windowId: this.windowId,
+        bounds: {
+          windowState: "maximized"
+        }
+      });
+      log(`[视口恢复] 已尝试最大化 Chrome 窗口，原因: ${reason}`);
+      return true;
+    } catch (error) {
+      log(`[视口恢复] 最大化窗口失败: ${error.message || error}`);
+      return false;
+    }
+  }
+
+  async ensureHealthyListViewport(reason = "unknown") {
+    let state = await this.getListState();
+    if (!this.isListViewportCollapsed(state)) {
+      return { ok: true, recovered: false, state };
+    }
+
+    log(`[视口恢复] 检测到推荐列表视口异常缩小，尝试自动恢复。原因: ${reason}`);
+    await this.maximizeWindowIfPossible(reason);
+    await sleep(humanDelay(800, 120));
+    state = await this.getListState();
+    if (!this.isListViewportCollapsed(state)) {
+      return { ok: true, recovered: true, state };
+    }
+
+    const reloaded = await this.evaluate(jsReloadRecommendFrame);
+    if (reloaded?.ok) {
+      log("[视口恢复] 已触发 recommendFrame reload。");
+      await this.waitForListReady(45);
+      await sleep(humanDelay(900, 150));
+      state = await this.getListState();
+      if (!this.isListViewportCollapsed(state)) {
+        return { ok: true, recovered: true, state };
+      }
+    }
+
+    return {
+      ok: false,
+      recovered: false,
+      state
+    };
+  }
+
   async discoverCandidates() {
+    const health = await this.ensureHealthyListViewport("discover_candidates");
+    if (!health?.ok) {
+      return {
+        ok: false,
+        error: "LIST_VIEWPORT_COLLAPSED",
+        added: 0,
+        list_state: health?.state || null
+      };
+    }
     const scan = await this.evaluate(buildListCandidatesExpr(Array.from(this.processedKeys)));
     if (!scan?.ok) {
       return {
@@ -1211,10 +1317,11 @@ class RecommendScreenCli {
   }
 
   async scrollAndLoadMore() {
-    const before = await this.evaluate(jsGetListState);
+    const health = await this.ensureHealthyListViewport("scroll_and_load_more");
+    const before = health?.state?.ok ? health.state : await this.getListState();
     const scrollResult = await this.evaluate(jsScrollList);
     await sleep(humanDelay(1200, 260));
-    const after = await this.evaluate(jsGetListState);
+    const after = await this.getListState();
     const bottom = await this.evaluate(jsDetectBottom);
     return { before, scrollResult, after, bottom };
   }
@@ -1595,7 +1702,11 @@ class RecommendScreenCli {
       if (!startupListReady) {
         throw this.buildError("RECOMMEND_PAGE_NOT_READY", "推荐列表未就绪（可能仍停留在详情页）");
       }
-      const initialList = await this.evaluate(jsGetListState);
+      const initialHealth = await this.ensureHealthyListViewport("startup");
+      if (!initialHealth?.ok) {
+        throw this.buildError("LIST_VIEWPORT_COLLAPSED", "推荐列表视口异常缩小，自动恢复失败。");
+      }
+      const initialList = initialHealth.state || await this.getListState();
       if (!initialList?.ok) {
         throw this.buildError("RECOMMEND_PAGE_NOT_READY", initialList?.error || "推荐列表不可用");
       }