@reconcrap/boss-recruit-mcp 1.0.19 → 1.0.21

package/src/index.js

@@ -2,16 +2,59 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { runRecruitPipeline } from "./pipeline.js";
+import {
+  PIPELINE_STATUS_READY_TO_START_ASYNC,
+  runRecruitPipeline
+} from "./pipeline.js";
+import {
+  RUN_MODE_ASYNC,
+  RUN_MODE_SYNC,
+  RUN_STAGE_PREFLIGHT,
+  RUN_STATE_CANCELED,
+  RUN_STATE_COMPLETED,
+  RUN_STATE_FAILED,
+  RUN_STATE_RUNNING,
+  cleanupExpiredRuns,
+  createRunId,
+  createRunStateSnapshot,
+  getRunHeartbeatIntervalMs,
+  readRunState,
+  touchRunHeartbeat,
+  updateRunProgress,
+  updateRunState,
+  writeRunState
+} from "./run-state.js";
 
 const require = createRequire(import.meta.url);
 const { version: SERVER_VERSION } = require("../package.json");
-const TOOL_NAME = "run_recruit_pipeline";
+
+const TOOL_RUN_PIPELINE = "run_recruit_pipeline";
+const TOOL_START_RUN = "start_recruit_pipeline_run";
+const TOOL_GET_RUN = "get_recruit_pipeline_run";
+const TOOL_CANCEL_RUN = "cancel_recruit_pipeline_run";
+
 const SERVER_NAME = "boss-recruit-mcp";
 const FRAMING_UNKNOWN = "unknown";
 const FRAMING_HEADER = "header";
 const FRAMING_LINE = "line";
 
+const activeAsyncRuns = new Map();
+let runPipelineImpl = runRecruitPipeline;
+
+function normalizeText(value) {
+  return String(value || "").replace(/\s+/g, " ").trim();
+}
+
+function parsePositiveInteger(raw, fallback) {
+  const value = Number.parseInt(String(raw || ""), 10);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+function getDefaultPollAfterSec() {
+  const fromEnv = parsePositiveInteger(process.env.BOSS_RECRUIT_POLL_AFTER_SEC, 10);
+  return Math.max(5, Math.min(15, fromEnv));
+}
+
 function writeMessage(message, framing = FRAMING_LINE) {
   const body = JSON.stringify(message);
   if (framing === FRAMING_HEADER) {
@@ -30,48 +73,530 @@ function createJsonRpcError(id, code, message) {
   };
 }
 
-function createToolSchema() {
+function createRunInputSchema() {
   return {
-    name: TOOL_NAME,
-    description: "统一招聘流水线：解析招聘指令、校验条件、执行搜索与筛选并返回摘要。",
-    inputSchema: {
-      type: "object",
-      properties: {
-        instruction: {
-          type: "string",
-          description: "用户自然语言招聘指令"
+    type: "object",
+    properties: {
+      instruction: {
+        type: "string",
+        description: "用户自然语言招聘指令"
+      },
+      execution_mode: {
+        type: "string",
+        enum: [RUN_MODE_ASYNC, RUN_MODE_SYNC],
+        description: "执行模式；默认 async。"
+      },
+      confirmation: {
+        type: "object",
+        properties: {
+          keyword_confirmed: { type: "boolean" },
+          keyword_value: { type: "string" },
+          search_params_confirmed: { type: "boolean" },
+          criteria_confirmed: { type: "boolean" },
+          use_default_for_missing: { type: "boolean" }
         },
-        confirmation: {
-          type: "object",
-          properties: {
-            keyword_confirmed: { type: "boolean" },
-            keyword_value: { type: "string" },
-            search_params_confirmed: { type: "boolean" },
-            use_default_for_missing: { type: "boolean" }
+        additionalProperties: false
+      },
+      overrides: {
+        type: "object",
+        properties: {
+          city: { type: "string" },
+          degree: { type: "string" },
+          filter_recent_viewed: { type: "boolean" },
+          schools: {
+            anyOf: [
+              { type: "array", items: { type: "string" } },
+              { type: "string" }
+            ]
           },
-          additionalProperties: false
+          keyword: { type: "string" },
+          target_count: { type: "integer", minimum: 1 },
+          criteria: { type: "string" }
         },
-        overrides: {
-          type: "object",
-          properties: {
-            city: { type: "string" },
-            degree: { type: "string" },
-            filter_recent_viewed: { type: "boolean" },
-            schools: {
-              anyOf: [
-                { type: "array", items: { type: "string" } },
-                { type: "string" }
-              ]
-            },
-            keyword: { type: "string" },
-            target_count: { type: "integer", minimum: 1 }
-          },
-          additionalProperties: false
+        additionalProperties: false
+      }
+    },
+    required: ["instruction"],
+    additionalProperties: false
+  };
+}
+
+function createToolsSchema() {
+  return [
+    {
+      name: TOOL_RUN_PIPELINE,
+      description: "Boss 招聘流水线：默认异步，但会先走与同步一致的前置确认/页面就绪门禁；仅在门禁通过后返回 run_id。传 execution_mode=sync 可改为全程同步执行。",
+      inputSchema: createRunInputSchema()
+    },
+    {
+      name: TOOL_START_RUN,
+      description: "异步启动 Boss 招聘流水线（含同步门禁预检）；只有在前置确认与页面就绪通过后才返回 run_id。",
+      inputSchema: createRunInputSchema()
+    },
+    {
+      name: TOOL_GET_RUN,
+      description: "按 run_id 查询异步/同步流水线运行状态快照。",
+      inputSchema: {
+        type: "object",
+        properties: {
+          run_id: { type: "string" }
+        },
+        required: ["run_id"],
+        additionalProperties: false
+      }
+    },
+    {
+      name: TOOL_CANCEL_RUN,
+      description: "取消指定 run_id 的运行中流水线。",
+      inputSchema: {
+        type: "object",
+        properties: {
+          run_id: { type: "string" }
+        },
+        required: ["run_id"],
+        additionalProperties: false
+      }
+    }
+  ];
+}
+
+function createToolResultResponse(id, payload, isError = false) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(payload, null, 2)
         }
+      ],
+      structuredContent: payload,
+      ...(isError ? { isError: true } : {})
+    }
+  };
+}
+
+function validateRunArgs(args) {
+  if (!args || typeof args !== "object") {
+    return "arguments must be an object";
+  }
+  if (!args.instruction || typeof args.instruction !== "string") {
+    return "instruction is required and must be a string";
+  }
+  return null;
+}
+
+function getLastOutputLine(text) {
+  const lines = String(text || "")
+    .split(/\r?\n/)
+    .map((line) => normalizeText(line))
+    .filter(Boolean);
+  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 buildAsyncPrecheckArgs(args) {
+  return {
+    instruction: args.instruction,
+    confirmation: args.confirmation,
+    overrides: args.overrides
+  };
+}
+
+function safeUpdateRunState(runId, updater) {
+  try {
+    return updateRunState(runId, updater);
+  } catch {
+    return null;
+  }
+}
+
+function safeUpdateRunProgress(runId, patch, message = null) {
+  try {
+    return updateRunProgress(runId, patch, message);
+  } catch {
+    return null;
+  }
+}
+
+function createRuntimeCallbacks(runId, heartbeatIntervalMs) {
+  let lastStage = RUN_STAGE_PREFLIGHT;
+  let lastOutputPersistAt = 0;
+  return {
+    heartbeatIntervalMs,
+    onStage(event) {
+      const stage = normalizeText(event?.stage) || RUN_STAGE_PREFLIGHT;
+      lastStage = stage;
+      safeUpdateRunState(runId, {
+        state: RUN_STATE_RUNNING,
+        stage,
+        last_message: normalizeText(event?.message || "")
+      });
+    },
+    onHeartbeat(event) {
+      const stage = normalizeText(event?.stage) || lastStage;
+      lastStage = stage || lastStage;
+      const detailsMessage = normalizeText(event?.details?.message || "");
+      const patch = { stage: lastStage };
+      if (detailsMessage) {
+        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;
+      lastStage = stage || lastStage;
+      const now = Date.now();
+      if (now - lastOutputPersistAt < 1000) return;
+      lastOutputPersistAt = now;
+      const message = getLastOutputLine(event?.text);
+      if (!message) return;
+      safeUpdateRunState(runId, {
+        stage: lastStage,
+        last_message: message
+      });
+    },
+    onProgress(event) {
+      const stage = normalizeText(event?.stage) || lastStage;
+      lastStage = stage || lastStage;
+      safeUpdateRunState(runId, { stage: lastStage });
+      safeUpdateRunProgress(
+        runId,
+        {
+          processed: Number.isInteger(event?.processed) ? event.processed : undefined,
+          passed: Number.isInteger(event?.passed) ? event.passed : undefined,
+          skipped: Number.isInteger(event?.skipped) ? event.skipped : undefined,
+          greet_count: Number.isInteger(event?.greet_count) ? event.greet_count : undefined
+        },
+        normalizeText(event?.line || "")
+      );
+    },
+    getLastStage() {
+      return lastStage;
+    }
+  };
+}
+
+function attachSyncRunMetadata(result, runId, lastStage) {
+  if (!result || typeof result !== "object") return result;
+  if (result.status === "COMPLETED") {
+    const nextResult = result.result && typeof result.result === "object" ? result.result : {};
+    return {
+      ...result,
+      result: {
+        ...nextResult,
+        run_id: runId
+      }
+    };
+  }
+  if (result.status === "FAILED") {
+    const diagnostics = result.diagnostics && typeof result.diagnostics === "object" ? result.diagnostics : {};
+    return {
+      ...result,
+      diagnostics: {
+        ...diagnostics,
+        run_id: runId,
+        last_stage: lastStage || RUN_STAGE_PREFLIGHT
+      }
+    };
+  }
+  return result;
+}
+
+async function executeTrackedPipeline({
+  runId,
+  mode,
+  workspaceRoot,
+  args,
+  signal
+}) {
+  const heartbeatIntervalMs = getRunHeartbeatIntervalMs();
+  const runtimeCallbacks = createRuntimeCallbacks(runId, heartbeatIntervalMs);
+  safeUpdateRunState(runId, {
+    state: RUN_STATE_RUNNING,
+    stage: RUN_STAGE_PREFLIGHT,
+    last_message: "流水线已启动，等待 preflight。"
+  });
+
+  let result;
+  try {
+    result = await runPipelineImpl(
+      {
+        workspaceRoot,
+        instruction: args.instruction,
+        confirmation: args.confirmation,
+        overrides: args.overrides
       },
-      required: ["instruction"],
-      additionalProperties: false
+      undefined,
+      {
+        signal,
+        heartbeatIntervalMs,
+        onStage: runtimeCallbacks.onStage,
+        onHeartbeat: runtimeCallbacks.onHeartbeat,
+        onOutput: runtimeCallbacks.onOutput,
+        onProgress: runtimeCallbacks.onProgress
+      }
+    );
+  } catch (error) {
+    const canceled = Boolean(signal?.aborted) || error?.code === "PIPELINE_ABORTED";
+    if (canceled) {
+      const canceledResult = {
+        status: "FAILED",
+        error: {
+          code: "PIPELINE_CANCELED",
+          message: "流水线已取消。",
+          retryable: true
+        }
+      };
+      safeUpdateRunState(runId, {
+        mode,
+        state: RUN_STATE_CANCELED,
+        stage: runtimeCallbacks.getLastStage(),
+        last_message: "流水线已取消。",
+        error: canceledResult.error,
+        result: canceledResult
+      });
+      return {
+        result: canceledResult,
+        lastStage: runtimeCallbacks.getLastStage(),
+        state: RUN_STATE_CANCELED
+      };
     }
+
+    const failedResult = {
+      status: "FAILED",
+      error: {
+        code: "UNEXPECTED_ERROR",
+        message: error?.message || "Unexpected error",
+        retryable: true
+      }
+    };
+    safeUpdateRunState(runId, {
+      mode,
+      state: RUN_STATE_FAILED,
+      stage: runtimeCallbacks.getLastStage(),
+      last_message: failedResult.error.message,
+      error: failedResult.error,
+      result: failedResult
+    });
+    return {
+      result: failedResult,
+      lastStage: runtimeCallbacks.getLastStage(),
+      state: RUN_STATE_FAILED
+    };
+  }
+
+  const terminalState = result?.status === "FAILED"
+    ? RUN_STATE_FAILED
+    : RUN_STATE_COMPLETED;
+  safeUpdateRunState(runId, {
+    mode,
+    state: terminalState,
+    stage: runtimeCallbacks.getLastStage(),
+    last_message: terminalState === RUN_STATE_COMPLETED ? "流水线执行完成。" : (result?.error?.message || "流水线执行失败。"),
+    error: terminalState === RUN_STATE_FAILED ? (result?.error || null) : null,
+    result: result || null
+  });
+  return {
+    result,
+    lastStage: runtimeCallbacks.getLastStage(),
+    state: terminalState
+  };
+}
+
+function initializeRunStateOrThrow(runId, mode) {
+  const snapshot = createRunStateSnapshot({
+    runId,
+    mode,
+    state: "queued",
+    stage: RUN_STAGE_PREFLIGHT,
+    pid: process.pid,
+    lastMessage: "流水线任务已创建，等待执行。"
+  });
+  return writeRunState(snapshot);
+}
+
+async function handleSyncRunTool({ workspaceRoot, args }) {
+  cleanupExpiredRuns();
+  const runId = createRunId();
+  try {
+    initializeRunStateOrThrow(runId, RUN_MODE_SYNC);
+  } catch (error) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "RUN_STATE_IO_ERROR",
+        message: `无法写入运行状态目录：${error.message || "unknown"}`,
+        retryable: false
+      }
+    };
+  }
+  const tracked = await executeTrackedPipeline({
+    runId,
+    mode: RUN_MODE_SYNC,
+    workspaceRoot,
+    args,
+    signal: null
+  });
+  return attachSyncRunMetadata(tracked.result, runId, tracked.lastStage);
+}
+
+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,
+      {
+        precheckOnly: true
+      }
+    );
+  } catch (error) {
+    precheckResult = {
+      status: "FAILED",
+      error: {
+        code: "UNEXPECTED_ERROR",
+        message: error?.message || "Unexpected error",
+        retryable: true
+      }
+    };
+  }
+
+  if (precheckResult?.status !== PIPELINE_STATUS_READY_TO_START_ASYNC) {
+    return precheckResult;
+  }
+
+  cleanupExpiredRuns();
+  const runId = createRunId();
+  try {
+    initializeRunStateOrThrow(runId, RUN_MODE_ASYNC);
+  } catch (error) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "RUN_STATE_IO_ERROR",
+        message: `无法写入运行状态目录：${error.message || "unknown"}`,
+        retryable: false
+      }
+    };
+  }
+
+  const abortController = new AbortController();
+  const promise = executeTrackedPipeline({
+    runId,
+    mode: RUN_MODE_ASYNC,
+    workspaceRoot,
+    args,
+    signal: abortController.signal
+  }).finally(() => {
+    activeAsyncRuns.delete(runId);
+  });
+  activeAsyncRuns.set(runId, {
+    abortController,
+    promise
+  });
+
+  return {
+    status: "ACCEPTED",
+    run_id: runId,
+    state: "queued",
+    poll_after_sec: getDefaultPollAfterSec(),
+    message: "异步流水线已启动，请使用 get_recruit_pipeline_run 轮询状态。"
+  };
+}
+
+function handleGetRunTool(args) {
+  cleanupExpiredRuns();
+  const runId = normalizeText(args?.run_id);
+  if (!runId) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "INVALID_RUN_ID",
+        message: "run_id is required",
+        retryable: false
+      }
+    };
+  }
+  const snapshot = readRunState(runId);
+  if (!snapshot) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "RUN_NOT_FOUND",
+        message: `未找到 run_id=${runId} 的运行记录。`,
+        retryable: false
+      }
+    };
+  }
+  return {
+    status: "RUN_STATUS",
+    run: snapshot
+  };
+}
+
+function handleCancelRunTool(args) {
+  const runId = normalizeText(args?.run_id);
+  if (!runId) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "INVALID_RUN_ID",
+        message: "run_id is required",
+        retryable: false
+      }
+    };
+  }
+  const snapshot = readRunState(runId);
+  if (!snapshot) {
+    return {
+      status: "FAILED",
+      error: {
+        code: "RUN_NOT_FOUND",
+        message: `未找到 run_id=${runId} 的运行记录。`,
+        retryable: false
+      }
+    };
+  }
+
+  if ([RUN_STATE_COMPLETED, RUN_STATE_FAILED, RUN_STATE_CANCELED].includes(snapshot.state)) {
+    return {
+      status: "CANCEL_IGNORED",
+      run: snapshot,
+      message: "目标任务已结束，无需取消。"
+    };
+  }
+
+  const activeRun = activeAsyncRuns.get(runId);
+  if (activeRun?.abortController) {
+    activeRun.abortController.abort();
+  }
+  safeUpdateRunState(runId, {
+    stage: snapshot.stage || RUN_STAGE_PREFLIGHT,
+    last_message: "已收到取消请求，正在停止任务。"
+  });
+
+  const latest = readRunState(runId) || snapshot;
+  return {
+    status: "CANCEL_REQUESTED",
+    run: latest
   };
 }
 
@@ -108,64 +633,56 @@ async function handleRequest(message, workspaceRoot) {
       jsonrpc: "2.0",
       id,
       result: {
-        tools: [createToolSchema()]
+        tools: createToolsSchema()
       }
     };
   }
 
   if (method === "tools/call") {
-    if (!params || params.name !== TOOL_NAME) {
-      return createJsonRpcError(id, -32602, `Unknown tool: ${params?.name || ""}`);
+    const toolName = params?.name;
+    const args = params?.arguments || {};
+
+    if ([TOOL_RUN_PIPELINE, TOOL_START_RUN].includes(toolName)) {
+      const inputError = validateRunArgs(args);
+      if (inputError) {
+        return createJsonRpcError(id, -32602, inputError);
+      }
     }
 
-    const args = params.arguments || {};
-    if (!args.instruction || typeof args.instruction !== "string") {
-      return createJsonRpcError(id, -32602, "instruction is required and must be a string");
+    if ([TOOL_GET_RUN, TOOL_CANCEL_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");
+      }
     }
 
     try {
-      const result = await runRecruitPipeline({
-        workspaceRoot,
-        instruction: args.instruction,
-        confirmation: args.confirmation,
-        overrides: args.overrides
-      });
-      return {
-        jsonrpc: "2.0",
-        id,
-        result: {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ],
-          structuredContent: result
-        }
-      };
+      let payload;
+      if (toolName === TOOL_RUN_PIPELINE) {
+        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 = await handleStartRunTool({ workspaceRoot, args });
+      } else if (toolName === TOOL_GET_RUN) {
+        payload = handleGetRunTool(args);
+      } else if (toolName === TOOL_CANCEL_RUN) {
+        payload = handleCancelRunTool(args);
+      } else {
+        return createJsonRpcError(id, -32602, `Unknown tool: ${toolName || ""}`);
+      }
+      const isError = payload?.status === "FAILED";
+      return createToolResultResponse(id, payload, isError);
     } catch (error) {
       const failed = {
         status: "FAILED",
         error: {
           code: "UNEXPECTED_ERROR",
-          message: error.message || "Unexpected error",
+          message: error?.message || "Unexpected error",
           retryable: true
         }
       };
-      return {
-        jsonrpc: "2.0",
-        id,
-        result: {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(failed, null, 2)
-            }
-          ],
-          structuredContent: failed,
-          isError: true
-        }
-      };
+      return createToolResultResponse(id, failed, true);
     }
   }
 
@@ -181,9 +698,11 @@ async function handleRequest(message, workspaceRoot) {
 
 export function startServer() {
   const envRoot = process.env.BOSS_WORKSPACE_ROOT;
-  const thisFile = fileURLToPath(import.meta.url);
-  const mcpRoot = path.resolve(path.dirname(thisFile), "..");
-  const workspaceRoot = envRoot ? path.resolve(envRoot) : path.resolve(mcpRoot, "..");
+  const workspaceRoot = envRoot
+    ? path.resolve(envRoot)
+    : process.env.INIT_CWD
+      ? path.resolve(process.env.INIT_CWD)
+      : path.resolve(process.cwd());
   let buffer = Buffer.alloc(0);
   let framing = FRAMING_UNKNOWN;
 
@@ -274,7 +793,16 @@ export function startServer() {
   });
 }
 
+export const __testables = {
+  handleRequest,
+  activeAsyncRuns,
+  setRunPipelineImplForTests(nextImpl) {
+    runPipelineImpl = typeof nextImpl === "function" ? nextImpl : runRecruitPipeline;
+  }
+};
+
 const thisFilePath = fileURLToPath(import.meta.url);
 if (process.argv[1] && path.resolve(process.argv[1]) === thisFilePath) {
   startServer();
 }
+