@reconcrap/boss-recruit-mcp 1.0.19 → 1.0.21

package/src/pipeline.js

@@ -8,10 +8,16 @@ import {
   runScreenCli
 } from "./adapters.js";
 
+export const PIPELINE_STATUS_READY_TO_START_ASYNC = "READY_TO_START_ASYNC";
+
 function dedupe(values = []) {
   return [...new Set(values.filter(Boolean))];
 }
 
+function normalizeText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
 function failedCheckSet(checks = []) {
   const failed = checks
     .filter((item) => item && item.ok === false && typeof item.key === "string")
@@ -195,6 +201,99 @@ function buildFailedResponse(code, message, extra = {}) {
   };
 }
 
+class PipelineAbortError extends Error {
+  constructor(message = "Pipeline execution aborted") {
+    super(message);
+    this.name = "PipelineAbortError";
+    this.code = "PIPELINE_ABORTED";
+  }
+}
+
+function isAbortSignalTriggered(signal) {
+  return Boolean(signal && signal.aborted);
+}
+
+function ensurePipelineNotAborted(signal) {
+  if (isAbortSignalTriggered(signal)) {
+    throw new PipelineAbortError("Pipeline execution aborted by caller.");
+  }
+}
+
+function safeInvokeRuntimeCallback(callback, payload) {
+  if (typeof callback !== "function") return;
+  try {
+    callback(payload);
+  } catch {
+    // Keep pipeline stable even if runtime callback fails.
+  }
+}
+
+function createPipelineRuntime(runtime = null) {
+  const signal = runtime?.signal;
+  const heartbeatIntervalMs = Number.isFinite(runtime?.heartbeatIntervalMs) && runtime.heartbeatIntervalMs > 0
+    ? runtime.heartbeatIntervalMs
+    : 10_000;
+  const precheckOnly = runtime?.precheckOnly === true;
+
+  function setStage(stage, message = null) {
+    safeInvokeRuntimeCallback(runtime?.onStage, {
+      stage,
+      message: normalizeText(message || "") || null,
+      at: new Date().toISOString()
+    });
+  }
+
+  function heartbeat(stage, details = null) {
+    safeInvokeRuntimeCallback(runtime?.onHeartbeat, {
+      stage,
+      details: details || null,
+      at: new Date().toISOString()
+    });
+  }
+
+  function output(stage, event) {
+    safeInvokeRuntimeCallback(runtime?.onOutput, {
+      stage,
+      ...(event || {}),
+      at: new Date().toISOString()
+    });
+  }
+
+  function progress(stage, payload) {
+    safeInvokeRuntimeCallback(runtime?.onProgress, {
+      stage,
+      ...(payload || {}),
+      at: new Date().toISOString()
+    });
+  }
+
+  function adapterRuntime(stage) {
+    return {
+      signal,
+      heartbeatIntervalMs,
+      onOutput: (event) => output(stage, event),
+      onHeartbeat: (event) => heartbeat(stage, event),
+      onProgress: (payload) => progress(stage, payload)
+    };
+  }
+
+  return {
+    signal,
+    heartbeatIntervalMs,
+    precheckOnly,
+    setStage,
+    heartbeat,
+    output,
+    progress,
+    adapterRuntime
+  };
+}
+
+function isProcessAbortError(errorLike) {
+  const code = normalizeText(errorLike?.code || errorLike?.error_code || "").toUpperCase();
+  return code === "PROCESS_ABORTED" || code === "ABORTED";
+}
+
 function normalizeCsvPath(csvPath) {
   if (typeof csvPath !== "string") return null;
   const trimmed = csvPath.trim();
@@ -365,12 +464,16 @@ const defaultDependencies = {
   runScreenCli
 };
 
-export async function runRecruitPipeline({
-  workspaceRoot,
-  instruction,
-  confirmation,
-  overrides
-}, dependencies = defaultDependencies) {
+export async function runRecruitPipeline(
+  {
+    workspaceRoot,
+    instruction,
+    confirmation,
+    overrides
+  },
+  dependencies = defaultDependencies,
+  runtime = null
+) {
   const {
     parseRecruitInstruction: parseInstruction,
     ensureBossSearchPageReady: ensureSearchPageReady,
@@ -378,6 +481,8 @@ export async function runRecruitPipeline({
     runSearchCli: searchCli,
     runScreenCli: screenCli
   } = dependencies;
+  const runtimeHooks = createPipelineRuntime(runtime);
+  ensurePipelineNotAborted(runtimeHooks.signal);
   const startedAt = Date.now();
   const parsed = parseInstruction({
     instruction,
@@ -398,8 +503,14 @@ export async function runRecruitPipeline({
     return buildNeedConfirmationResponse(parsed);
   }
 
+  ensurePipelineNotAborted(runtimeHooks.signal);
+  runtimeHooks.setStage("preflight", "开始执行 preflight 检查。");
+  runtimeHooks.heartbeat("preflight");
   const preflight = runPreflight(workspaceRoot);
   if (!preflight.ok) {
+    runtimeHooks.heartbeat("preflight", {
+      status: "failed"
+    });
     const recovery = buildPreflightRecovery(preflight.checks, workspaceRoot);
     return buildFailedResponse(
       "PIPELINE_PREFLIGHT_FAILED",
@@ -429,12 +540,70 @@ export async function runRecruitPipeline({
     );
   }
 
+  ensurePipelineNotAborted(runtimeHooks.signal);
+  runtimeHooks.setStage("page_ready", "preflight 完成，开始检查 search 页面就绪状态。");
+  runtimeHooks.heartbeat("page_ready");
+  const initialPageCheck = await ensureSearchPageReady(workspaceRoot, {
+    port: preflight.debug_port
+  });
+  if (!initialPageCheck.ok) {
+    if (
+      initialPageCheck.state === "LOGIN_REQUIRED"
+      || initialPageCheck.state === "LOGIN_REQUIRED_AFTER_REDIRECT"
+    ) {
+      return buildFailedResponse(
+        "BOSS_LOGIN_REQUIRED",
+        "Boss 页面未稳定停留在 search 页面，疑似未登录或登录态失效。请先在当前 Chrome 窗口手动登录 Boss，登录完成后再继续搜索和筛选。",
+        {
+          search_params: parsed.searchParams,
+          screen_params: parsed.screenParams,
+          diagnostics: buildProgressDiagnostics({
+            preflight,
+            totalProcessedCount: 0,
+            totalPassedCount: 0,
+            roundCount: 0,
+            extra: {
+              page_state: initialPageCheck.page_state
+            }
+          })
+        }
+      );
+    }
+    return buildFailedResponse(
+      "BOSS_SEARCH_PAGE_NOT_READY",
+      "无法确认 Boss search 页面已就绪。请先确保 Chrome 调试端口可连，并且页面能稳定停留在 https://www.zhipin.com/web/chat/search。",
+      {
+        search_params: parsed.searchParams,
+        screen_params: parsed.screenParams,
+        diagnostics: buildProgressDiagnostics({
+          preflight,
+          totalProcessedCount: 0,
+          totalPassedCount: 0,
+          roundCount: 0,
+          extra: {
+            page_state: initialPageCheck.page_state
+          }
+        })
+      }
+    );
+  }
+
+  if (runtimeHooks.precheckOnly) {
+    return {
+      status: PIPELINE_STATUS_READY_TO_START_ASYNC,
+      search_params: parsed.searchParams,
+      screen_params: parsed.screenParams,
+      message: "前置门禁检查通过，可启动异步流水线。"
+    };
+  }
+
   let totalProcessedCount = 0;
   let totalPassedCount = 0;
   let roundCount = 0;
   const roundOutputCsvPaths = [];
 
   while (totalProcessedCount < initialTargetCount) {
+    ensurePipelineNotAborted(runtimeHooks.signal);
     roundCount += 1;
 
     const remainingTargetCount = Math.max(0, initialTargetCount - totalProcessedCount);
@@ -447,9 +616,17 @@ export async function runRecruitPipeline({
       target_count: remainingTargetCount
     };
 
-    const pageCheck = await ensureSearchPageReady(workspaceRoot, {
-      port: preflight.debug_port
-    });
+    if (roundCount > 1) {
+      runtimeHooks.setStage("page_ready", `第 ${roundCount} 轮：检查 search 页面就绪状态。`);
+      runtimeHooks.heartbeat("page_ready", {
+        round: roundCount
+      });
+    }
+    const pageCheck = roundCount === 1
+      ? initialPageCheck
+      : await ensureSearchPageReady(workspaceRoot, {
+          port: preflight.debug_port
+        });
     if (!pageCheck.ok) {
       if (
         pageCheck.state === "LOGIN_REQUIRED"
@@ -493,10 +670,20 @@ export async function runRecruitPipeline({
       );
     }
 
+    ensurePipelineNotAborted(runtimeHooks.signal);
+    runtimeHooks.setStage("search", `第 ${roundCount} 轮：开始执行 search。`);
+    runtimeHooks.heartbeat("search", {
+      round: roundCount
+    });
     const searchResult = await searchCli({
       workspaceRoot,
-      searchParams: roundSearchParams
+      searchParams: roundSearchParams,
+      runtime: runtimeHooks.adapterRuntime("search")
     });
+    ensurePipelineNotAborted(runtimeHooks.signal);
+    if (isProcessAbortError(searchResult)) {
+      throw new PipelineAbortError("搜索流程已取消。");
+    }
 
     if (!searchResult.ok) {
       const failure = classifySearchFailure(searchResult);
@@ -545,6 +732,14 @@ export async function runRecruitPipeline({
 
     const exhaustedByTipNoData = searchResult.no_data_tip_present === true;
     if (exhaustedByTipNoData || searchResult.candidate_count === 0) {
+      runtimeHooks.setStage("finalize", "候选池已耗尽，正在汇总结果。");
+      runtimeHooks.heartbeat("finalize");
+      runtimeHooks.progress("finalize", {
+        processed: totalProcessedCount,
+        passed: totalPassedCount,
+        skipped: Math.max(totalProcessedCount - totalPassedCount, 0),
+        greet_count: 0
+      });
       const durationSec = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
       const mergedCsvPath = mergeRoundCsvFiles(roundOutputCsvPaths);
       return {
@@ -568,10 +763,20 @@ export async function runRecruitPipeline({
       };
     }
 
+    ensurePipelineNotAborted(runtimeHooks.signal);
+    runtimeHooks.setStage("screen", `第 ${roundCount} 轮：开始执行 screen。`);
+    runtimeHooks.heartbeat("screen", {
+      round: roundCount
+    });
     const screenResult = await screenCli({
       workspaceRoot,
-      screenParams: roundScreenParams
+      screenParams: roundScreenParams,
+      runtime: runtimeHooks.adapterRuntime("screen")
     });
+    ensurePipelineNotAborted(runtimeHooks.signal);
+    if (isProcessAbortError(screenResult)) {
+      throw new PipelineAbortError("筛选流程已取消。");
+    }
 
     if (!screenResult.ok) {
       const failure = classifyScreenFailure(screenResult);
@@ -634,10 +839,24 @@ export async function runRecruitPipeline({
         : 0;
     totalProcessedCount += roundProcessedCount;
     totalPassedCount += roundPassedCount;
+    runtimeHooks.progress("screen", {
+      processed: totalProcessedCount,
+      passed: totalPassedCount,
+      skipped: Math.max(totalProcessedCount - totalPassedCount, 0),
+      greet_count: 0
+    });
   }
 
+  runtimeHooks.setStage("finalize", "筛选完成，正在汇总结果。");
+  runtimeHooks.heartbeat("finalize");
   const durationSec = Math.max(1, Math.round((Date.now() - startedAt) / 1000));
   const mergedCsvPath = mergeRoundCsvFiles(roundOutputCsvPaths);
+  runtimeHooks.progress("finalize", {
+    processed: totalProcessedCount,
+    passed: totalPassedCount,
+    skipped: Math.max(totalProcessedCount - totalPassedCount, 0),
+    greet_count: 0
+  });
   return {
     status: "COMPLETED",
     search_params: parsed.searchParams,

package/src/run-state.js

@@ -0,0 +1,294 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const RUN_MODE_SYNC = "sync";
+export const RUN_MODE_ASYNC = "async";
+
+export const RUN_STATE_QUEUED = "queued";
+export const RUN_STATE_RUNNING = "running";
+export const RUN_STATE_COMPLETED = "completed";
+export const RUN_STATE_FAILED = "failed";
+export const RUN_STATE_CANCELED = "canceled";
+
+export const RUN_STAGE_PREFLIGHT = "preflight";
+export const RUN_STAGE_PAGE_READY = "page_ready";
+export const RUN_STAGE_JOB_LIST = "job_list";
+export const RUN_STAGE_SEARCH = "search";
+export const RUN_STAGE_SCREEN = "screen";
+export const RUN_STAGE_FINALIZE = "finalize";
+
+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]);
+const VALID_RUN_STATES = new Set([
+  RUN_STATE_QUEUED,
+  RUN_STATE_RUNNING,
+  RUN_STATE_COMPLETED,
+  RUN_STATE_FAILED,
+  RUN_STATE_CANCELED
+]);
+const VALID_RUN_STAGES = new Set([
+  RUN_STAGE_PREFLIGHT,
+  RUN_STAGE_PAGE_READY,
+  RUN_STAGE_JOB_LIST,
+  RUN_STAGE_SEARCH,
+  RUN_STAGE_SCREEN,
+  RUN_STAGE_FINALIZE
+]);
+
+function toIsoNow() {
+  return new Date().toISOString();
+}
+
+function parsePositiveInteger(raw, fallback) {
+  const value = Number.parseInt(String(raw || ""), 10);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+export function getRunHeartbeatIntervalMs() {
+  return parsePositiveInteger(process.env.BOSS_RECRUIT_RUN_HEARTBEAT_MS, DEFAULT_HEARTBEAT_INTERVAL_MS);
+}
+
+export function getRunRetentionMs() {
+  return parsePositiveInteger(process.env.BOSS_RECRUIT_RUN_RETENTION_MS, DEFAULT_RETENTION_MS);
+}
+
+export function getStateHome() {
+  return process.env.BOSS_RECRUIT_HOME
+    ? path.resolve(process.env.BOSS_RECRUIT_HOME)
+    : path.join(os.homedir(), "\.boss-recruit-mcp");
+}
+
+export function getRunsDir() {
+  return path.join(getStateHome(), "runs");
+}
+
+function ensureRunsDir() {
+  fs.mkdirSync(getRunsDir(), { recursive: true });
+}
+
+function normalizeRunId(runId) {
+  return String(runId || "").trim();
+}
+
+function getRunStatePath(runId) {
+  const normalized = normalizeRunId(runId);
+  if (!normalized || normalized.includes("/") || normalized.includes("\\")) {
+    throw new Error("Invalid run_id");
+  }
+  return path.join(getRunsDir(), `${normalized}.json`);
+}
+
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeWriteJson(filePath, payload) {
+  ensureRunsDir();
+  const tempPath = `${filePath}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  fs.renameSync(tempPath, filePath);
+}
+
+function defaultProgress(progress = {}) {
+  return {
+    processed: Number.isInteger(progress.processed) && progress.processed >= 0 ? progress.processed : 0,
+    passed: Number.isInteger(progress.passed) && progress.passed >= 0 ? progress.passed : 0,
+    skipped: Number.isInteger(progress.skipped) && progress.skipped >= 0 ? progress.skipped : 0,
+    greet_count: Number.isInteger(progress.greet_count) && progress.greet_count >= 0 ? progress.greet_count : 0
+  };
+}
+
+function normalizeRunMode(mode) {
+  const normalized = String(mode || "").trim().toLowerCase();
+  return VALID_RUN_MODES.has(normalized) ? normalized : RUN_MODE_SYNC;
+}
+
+function normalizeRunState(state) {
+  const normalized = String(state || "").trim().toLowerCase();
+  return VALID_RUN_STATES.has(normalized) ? normalized : RUN_STATE_QUEUED;
+}
+
+function normalizeRunStage(stage) {
+  const normalized = String(stage || "").trim().toLowerCase();
+  return VALID_RUN_STAGES.has(normalized) ? normalized : RUN_STAGE_PREFLIGHT;
+}
+
+function normalizeMessage(message) {
+  const normalized = String(message || "").replace(/\s+/g, " ").trim();
+  return normalized || null;
+}
+
+export function createRunId() {
+  if (typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString("hex");
+}
+
+export function createRunStateSnapshot({
+  runId,
+  mode = RUN_MODE_SYNC,
+  state = RUN_STATE_QUEUED,
+  stage = RUN_STAGE_PREFLIGHT,
+  pid = process.pid,
+  lastMessage = null
+} = {}) {
+  const now = toIsoNow();
+  return {
+    run_id: normalizeRunId(runId) || createRunId(),
+    mode: normalizeRunMode(mode),
+    state: normalizeRunState(state),
+    stage: normalizeRunStage(stage),
+    started_at: now,
+    updated_at: now,
+    heartbeat_at: now,
+    pid: Number.isInteger(pid) && pid > 0 ? pid : process.pid,
+    progress: defaultProgress(),
+    last_message: normalizeMessage(lastMessage),
+    error: null,
+    result: null
+  };
+}
+
+export function writeRunState(snapshot) {
+  const runId = normalizeRunId(snapshot?.run_id);
+  if (!runId) {
+    throw new Error("run_id is required");
+  }
+  const now = toIsoNow();
+  const payload = {
+    run_id: runId,
+    mode: normalizeRunMode(snapshot.mode),
+    state: normalizeRunState(snapshot.state),
+    stage: normalizeRunStage(snapshot.stage),
+    started_at: String(snapshot.started_at || now),
+    updated_at: String(snapshot.updated_at || now),
+    heartbeat_at: String(snapshot.heartbeat_at || now),
+    pid: Number.isInteger(snapshot.pid) && snapshot.pid > 0 ? snapshot.pid : process.pid,
+    progress: defaultProgress(snapshot.progress),
+    last_message: normalizeMessage(snapshot.last_message),
+    error: snapshot.error || null,
+    result: snapshot.result || null
+  };
+  safeWriteJson(getRunStatePath(runId), payload);
+  return payload;
+}
+
+export function readRunState(runId) {
+  const payload = safeReadJson(getRunStatePath(runId));
+  if (!payload) return null;
+  return {
+    run_id: normalizeRunId(payload.run_id),
+    mode: normalizeRunMode(payload.mode),
+    state: normalizeRunState(payload.state),
+    stage: normalizeRunStage(payload.stage),
+    started_at: String(payload.started_at || ""),
+    updated_at: String(payload.updated_at || ""),
+    heartbeat_at: String(payload.heartbeat_at || ""),
+    pid: Number.isInteger(payload.pid) && payload.pid > 0 ? payload.pid : process.pid,
+    progress: defaultProgress(payload.progress),
+    last_message: normalizeMessage(payload.last_message),
+    error: payload.error || null,
+    result: payload.result || null
+  };
+}
+
+export function updateRunState(runId, updater) {
+  const current = readRunState(runId);
+  if (!current) return null;
+  const patch = typeof updater === "function" ? updater({ ...current }) : updater;
+  if (!patch || typeof patch !== "object") {
+    return current;
+  }
+  const now = toIsoNow();
+  const next = {
+    ...current,
+    ...patch,
+    run_id: current.run_id,
+    mode: normalizeRunMode(patch.mode ?? current.mode),
+    state: normalizeRunState(patch.state ?? current.state),
+    stage: normalizeRunStage(patch.stage ?? current.stage),
+    progress: defaultProgress({
+      ...current.progress,
+      ...(patch.progress || {})
+    }),
+    last_message: normalizeMessage(
+      Object.prototype.hasOwnProperty.call(patch, "last_message")
+        ? patch.last_message
+        : current.last_message
+    ),
+    updated_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
+  }));
+}
+
+export function updateRunProgress(runId, progressPatch = {}, message = null) {
+  const patch = {
+    progress: {}
+  };
+  if (Number.isInteger(progressPatch.processed) && progressPatch.processed >= 0) {
+    patch.progress.processed = progressPatch.processed;
+  }
+  if (Number.isInteger(progressPatch.passed) && progressPatch.passed >= 0) {
+    patch.progress.passed = progressPatch.passed;
+  }
+  if (Number.isInteger(progressPatch.skipped) && progressPatch.skipped >= 0) {
+    patch.progress.skipped = progressPatch.skipped;
+  }
+  if (Number.isInteger(progressPatch.greet_count) && progressPatch.greet_count >= 0) {
+    patch.progress.greet_count = progressPatch.greet_count;
+  }
+  if (message !== null) {
+    patch.last_message = message;
+  }
+  return updateRunState(runId, patch);
+}
+
+export function cleanupExpiredRuns(retentionMs = getRunRetentionMs()) {
+  ensureRunsDir();
+  const removed = [];
+  const failed = [];
+  const now = Date.now();
+  const entries = fs.readdirSync(getRunsDir(), { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const filePath = path.join(getRunsDir(), entry.name);
+    try {
+      const stat = fs.statSync(filePath);
+      const age = now - Number(stat.mtimeMs || 0);
+      if (age < retentionMs) continue;
+      fs.unlinkSync(filePath);
+      removed.push(filePath);
+    } catch (error) {
+      failed.push({
+        file: filePath,
+        reason: error.message || String(error)
+      });
+    }
+  }
+  return { removed, failed };
+}
+