@reconcrap/boss-recommend-mcp 1.0.11 → 1.0.12

package/README.md

@@ -9,7 +9,7 @@ Boss 推荐页自动化流水线 MCP（stdio）服务。
 
 MCP 工具：
 
-- `run_recommend_pipeline`（同步，兼容旧 agent）
+- `run_recommend_pipeline`（默认异步启动；传 `execution_mode=sync` 时同步执行）
 - `start_recommend_pipeline_run`（异步启动，立即返回 run_id）
 - `get_recommend_pipeline_run`（轮询 run_id 状态）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
@@ -143,13 +143,14 @@ node src/cli.js run --instruction-file request.txt --confirmation-file confirmat
 
 当宿主 agent 对“长时间无回包”敏感（容易误判失败）时，建议改用异步工具：
 
-1. 先调用 `start_recommend_pipeline_run`，拿到 `run_id`。
+1. 优先直接调用 `run_recommend_pipeline`，默认会返回异步 `run_id`。
 2. 每 5~15 秒调用一次 `get_recommend_pipeline_run` 轮询。
 3. 若需终止，调用 `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.12",
   "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,14 @@ description: "Use when users ask to run Boss recommend-page filtering and screen
 
 长耗时宿主兼容（推荐）：
 
-- 若宿主存在“工具超时误判”风险，优先改用异步三件套：
+- `run_recommend_pipeline` 现在默认直接异步启动。
+- 若宿主要显式拆成三步，也可使用：
   - `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,7 +221,7 @@ function createToolsSchema() {
   return [
     {
       name: TOOL_RUN_PIPELINE,
-      description: "Boss 推荐页同步流水线：解析推荐筛选指令并执行 search+screen，直到返回最终结果。",
+      description: "Boss 推荐页流水线：默认异步启动并返回 run_id；传 execution_mode=sync 时改为同步执行。",
       inputSchema: createRunInputSchema()
     },
     {
@@ -285,6 +291,12 @@ 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 safeUpdateRunState(runId, updater) {
   try {
     return updateRunState(runId, updater);
@@ -324,6 +336,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;
@@ -699,7 +716,10 @@ 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 })
+          : handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_START_RUN) {
         payload = handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_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

@@ -123,20 +123,36 @@ async function testAsyncStartStatusCancelAndSyncCompatibility() {
     const canceledRun = await waitForTerminalRunState(started.run_id);
     assert.equal(canceledRun.state, "canceled");
 
-    const syncResponse = await handleRequest(
+    const defaultAsyncResponse = await handleRequest(
       makeToolCall(4, "run_recommend_pipeline", { instruction: "fast sync run" }),
       process.cwd()
     );
-    const syncPayload = await readToolPayload(syncResponse);
+    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 syncFailedResponse = await handleRequest(
+      makeToolCall(5, "run_recommend_pipeline", {
+        instruction: "fast forced sync run",
+        execution_mode: "sync"
+      }),
+      process.cwd()
+    );
+    const syncPayload = await readToolPayload(syncFailedResponse);
     assert.equal(syncPayload.status, "COMPLETED");
     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(6, "run_recommend_pipeline", {
+        instruction: "force fail",
+        execution_mode: "sync"
+      }),
       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 || "推荐列表不可用");
       }