@reconcrap/boss-recruit-mcp 1.0.19 → 1.0.21

package/README.md

@@ -1,9 +1,13 @@
 # @reconcrap/boss-recruit-mcp
 
-统一招聘流水线 MCP（stdio）服务。将 `boss-search-cli` 与 `boss-screen-cli` 串联为单工具：
+统一招聘流水线 MCP（stdio）服务。将 `boss-search-cli` 与 `boss-screen-cli` 串联为统一流程：
 
-- 工具名：`run_recruit_pipeline`
-- 状态：`NEED_INPUT` / `NEED_CONFIRMATION` / `COMPLETED` / `FAILED`
+- `run_recruit_pipeline`（默认异步，但先执行与同步一致的前置门禁）
+- `start_recruit_pipeline_run`（异步启动，返回 `run_id`）
+- `get_recruit_pipeline_run`（查询运行状态快照）
+- `cancel_recruit_pipeline_run`（取消运行中任务）
+- 流程状态：`NEED_INPUT` / `NEED_CONFIRMATION` / `COMPLETED` / `FAILED`
+- run 状态：`queued` / `running` / `completed` / `failed` / `canceled`
 
 ## 通过 npm / npx 安装
 
@@ -120,6 +124,21 @@ boss-recruit-mcp start
 
 该服务通过 stdio 与 MCP client 通信。
 
+## 长流程 Agent 兼容模式
+
+当宿主 agent 对长时间阻塞调用敏感时，建议使用默认异步模式：
+
+1. 直接调用 `run_recruit_pipeline`（默认 async）。
+2. 工具会先执行与同步一致的前置门禁（参数确认、preflight、页面就绪）。
+3. 门禁未通过时，直接返回 `NEED_INPUT/NEED_CONFIRMATION/FAILED`，不会启动后台 run。
+4. 门禁通过后返回 `ACCEPTED + run_id`，随后轮询 `get_recruit_pipeline_run`。
+5. 若需要阻塞式返回，显式传 `execution_mode=sync`。
+
+说明：
+
+- 运行态文件保存在 `~/.boss-recruit-mcp/runs/<run_id>.json`（可通过 `BOSS_RECRUIT_HOME` 覆盖）。
+- 心跳默认 120 秒；阶段切换与进度更新会刷新 `updated_at`。
+
 ## CLI Fallback
 
 如果当前 AI agent 无法添加新的 MCP、MCP 数量受限，或者只支持 shell/命令执行，也可以直接调用同一后端的 CLI fallback：
@@ -207,11 +226,13 @@ boss-recruit-mcp doctor --port <port>
 
 ```json
 {
+  "execution_mode": "async",
   "instruction": "自然语言招聘指令",
   "confirmation": {
     "keyword_confirmed": true,
     "keyword_value": "ai infra",
     "search_params_confirmed": true,
+    "criteria_confirmed": true,
     "use_default_for_missing": false
   },
   "overrides": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recruit-mcp",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "description": "Unified MCP pipeline for boss-search-cli and boss-screen-cli",
   "keywords": [
     "boss",
@@ -21,6 +21,8 @@
     "postinstall": "node scripts/postinstall.cjs",
     "test:parser": "node src/test-parser.js",
     "test:pipeline": "node src/test-pipeline.js",
+    "test:run-state": "node src/test-run-state.js",
+    "test:async": "node src/test-index-async.js",
     "test:protocol:win": "powershell -ExecutionPolicy Bypass -File scripts/verify-multi-round-protocol.ps1 -Mode unit",
     "test:regression:win": "powershell -ExecutionPolicy Bypass -File scripts/regression.ps1 -Mode quick"
   },

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

@@ -76,8 +76,9 @@ description: "Use when users ask to recruit candidates on Boss Zhipin via the bo
 
 ## Required MCP Tool
 
-- Tool name: `run_recruit_pipeline`
+- Tool name（默认异步）: `run_recruit_pipeline`
 - Input:
+  - `execution_mode` (optional: `async|sync`, default `async`)
   - `instruction` (string, required)
   - `confirmation` (object, optional)
     - `keyword_confirmed` (boolean): 是否确认关键词
@@ -91,7 +92,7 @@ description: "Use when users ask to recruit candidates on Boss Zhipin via the bo
     - `schools` (string[] | comma-separated string)
     - `keyword` (string)
     - `target_count` (number)
-- Tool response 重点字段：
+  - Tool response 重点字段：
   - `status`
   - `required_confirmations`
   - `pending_questions`
@@ -102,9 +103,17 @@ description: "Use when users ask to recruit candidates on Boss Zhipin via the bo
   - `review.default_preview`
   - `review.applied_defaults`
 
+异步工具（可选显式三步）：
+
+- `start_recruit_pipeline_run`
+- `get_recruit_pipeline_run`
+- `cancel_recruit_pipeline_run`
+
 ## Backend Selection
 
 - 默认执行路径：优先使用 MCP 工具 `run_recruit_pipeline`。
+- `run_recruit_pipeline` 默认 async，但会先执行与 sync 一致的前置门禁（参数确认、preflight、页面就绪）；门禁不通过时不会返回 `run_id`。
+- 只有门禁通过后才会返回 `ACCEPTED + run_id`，随后轮询 `get_recruit_pipeline_run`。
 - 如果当前 AI agent 无法添加新的 MCP、MCP 数量受限、或当前会话拿不到该工具：
   - 直接切换到 CLI fallback；
   - 不要放弃流程，也不要要求用户手动把所有步骤重新翻译一遍。

package/src/adapters.js

@@ -89,20 +89,102 @@ function resolveScreenCliEntry(screenDir) {
   return candidates.find((candidate) => pathExists(candidate)) || candidates[0];
 }
 
-function runProcess({ command, args, cwd, timeoutMs }) {
+function safeInvokeCallback(callback, payload) {
+  if (typeof callback !== "function") return;
+  try {
+    callback(payload);
+  } catch {
+    // Ignore callback errors to keep pipeline runtime stable.
+  }
+}
+
+function runProcess({
+  command,
+  args,
+  cwd,
+  timeoutMs,
+  onOutput,
+  onLine,
+  onHeartbeat,
+  heartbeatIntervalMs = 10_000,
+  signal
+}) {
   return new Promise((resolve) => {
     let stdout = "";
     let stderr = "";
+    let stdoutLineBuffer = "";
+    let stderrLineBuffer = "";
     let settled = false;
     let timer = null;
+    let heartbeatTimer = null;
+    let abortedBySignal = Boolean(signal?.aborted);
+    let abortListener = null;
+
+    function notifyHeartbeat(source) {
+      safeInvokeCallback(onHeartbeat, {
+        source,
+        command,
+        args,
+        cwd,
+        at: new Date().toISOString()
+      });
+    }
+
+    function emitLine(stream, line) {
+      const normalized = String(line ?? "").replace(/\r$/, "");
+      if (!normalized) return;
+      safeInvokeCallback(onLine, {
+        stream,
+        line: normalized,
+        at: new Date().toISOString()
+      });
+    }
+
+    function pushLineBuffer(stream, chunkText) {
+      if (stream === "stdout") {
+        stdoutLineBuffer += chunkText;
+      } else {
+        stderrLineBuffer += chunkText;
+      }
+      let buffer = stream === "stdout" ? stdoutLineBuffer : stderrLineBuffer;
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        emitLine(stream, buffer.slice(0, newlineIndex));
+        buffer = buffer.slice(newlineIndex + 1);
+        newlineIndex = buffer.indexOf("\n");
+      }
+      if (stream === "stdout") {
+        stdoutLineBuffer = buffer;
+      } else {
+        stderrLineBuffer = buffer;
+      }
+    }
 
     function finish(payload) {
       if (settled) return;
       settled = true;
       if (timer) clearTimeout(timer);
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      if (signal && typeof signal.removeEventListener === "function" && abortListener) {
+        signal.removeEventListener("abort", abortListener);
+      }
+      emitLine("stdout", stdoutLineBuffer);
+      emitLine("stderr", stderrLineBuffer);
+      stdoutLineBuffer = "";
+      stderrLineBuffer = "";
       resolve(payload);
     }
 
+    if (abortedBySignal) {
+      finish({
+        code: -1,
+        stdout,
+        stderr: "Process aborted before spawn",
+        error_code: "ABORTED"
+      });
+      return;
+    }
+
     let child;
     try {
       child = spawn(command, args, {
@@ -121,6 +203,16 @@ function runProcess({ command, args, cwd, timeoutMs }) {
       return;
     }
 
+    if (signal && typeof signal.addEventListener === "function") {
+      abortListener = () => {
+        abortedBySignal = true;
+        try {
+          child.kill();
+        } catch {}
+      };
+      signal.addEventListener("abort", abortListener, { once: true });
+    }
+
     if (timeoutMs && Number.isFinite(timeoutMs) && timeoutMs > 0) {
       timer = setTimeout(() => {
         try {
@@ -135,14 +227,45 @@ function runProcess({ command, args, cwd, timeoutMs }) {
       }, timeoutMs);
     }
 
+    if (Number.isFinite(heartbeatIntervalMs) && heartbeatIntervalMs > 0) {
+      heartbeatTimer = setInterval(() => {
+        notifyHeartbeat("timer");
+      }, heartbeatIntervalMs);
+    }
+
     child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
+      const text = chunk.toString();
+      stdout += text;
+      pushLineBuffer("stdout", text);
+      safeInvokeCallback(onOutput, {
+        stream: "stdout",
+        text,
+        at: new Date().toISOString()
+      });
+      notifyHeartbeat("stdout");
     });
     child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
+      const text = chunk.toString();
+      stderr += text;
+      pushLineBuffer("stderr", text);
+      safeInvokeCallback(onOutput, {
+        stream: "stderr",
+        text,
+        at: new Date().toISOString()
+      });
+      notifyHeartbeat("stderr");
     });
 
     child.on("close", (code) => {
+      if (abortedBySignal) {
+        finish({
+          code: -1,
+          stdout,
+          stderr: `${stderr}\nProcess aborted by signal`.trim(),
+          error_code: "ABORTED"
+        });
+        return;
+      }
       finish({ code, stdout, stderr });
     });
     child.on("error", (error) => {
@@ -363,6 +486,40 @@ function parseScreenSummary(output) {
   };
 }
 
+function parseScreenProgressLine(line, previous = {}) {
+  const text = String(line || "").trim();
+  if (!text) return null;
+  const next = {
+    processed: Number.isInteger(previous.processed) ? previous.processed : 0,
+    passed: Number.isInteger(previous.passed) ? previous.passed : 0,
+    skipped: Number.isInteger(previous.skipped) ? previous.skipped : 0,
+    greet_count: Number.isInteger(previous.greet_count) ? previous.greet_count : 0
+  };
+  let matched = false;
+
+  const processedMatch = text.match(/已处理[:：]\s*(\d+)/);
+  if (processedMatch) {
+    next.processed = Number.parseInt(processedMatch[1], 10);
+    matched = true;
+  }
+  const passedMatch = text.match(/(?:通过筛选|通过|已通过)[:：]\s*(\d+)/);
+  if (passedMatch) {
+    next.passed = Number.parseInt(passedMatch[1], 10);
+    matched = true;
+  }
+  const skippedMatch = text.match(/(?:已跳过|跳过)[:：]\s*(\d+)/);
+  if (skippedMatch) {
+    next.skipped = Number.parseInt(skippedMatch[1], 10);
+    matched = true;
+  }
+
+  if (!matched) return null;
+  return {
+    line: text,
+    progress: next
+  };
+}
+
 function loadScreenConfig(configPath) {
   if (!fs.existsSync(configPath)) {
     return {
@@ -721,7 +878,7 @@ export async function ensureBossSearchPageReady(workspaceRoot, options = {}) {
   };
 }
 
-export async function runSearchCli({ workspaceRoot, searchParams }) {
+export async function runSearchCli({ workspaceRoot, searchParams, runtime = null }) {
   const searchDir = resolveSearchCliDir(workspaceRoot);
   const debugPort = resolveWorkspaceDebugPort(workspaceRoot);
   if (!searchDir) {
@@ -757,7 +914,15 @@ export async function runSearchCli({ workspaceRoot, searchParams }) {
     command: "node",
     args,
     cwd: searchDir,
-    timeoutMs: 180000
+    timeoutMs: 180000,
+    heartbeatIntervalMs: runtime?.heartbeatIntervalMs,
+    signal: runtime?.signal,
+    onOutput: (event) => {
+      safeInvokeCallback(runtime?.onOutput, event);
+    },
+    onHeartbeat: (event) => {
+      safeInvokeCallback(runtime?.onHeartbeat, event);
+    }
   });
 
   const combined = `${result.stdout}\n${result.stderr}`;
@@ -780,7 +945,7 @@ export async function runSearchCli({ workspaceRoot, searchParams }) {
   };
 }
 
-export async function runScreenCli({ workspaceRoot, screenParams }) {
+export async function runScreenCli({ workspaceRoot, screenParams, runtime = null }) {
   const screenDir = resolveScreenCliDir(workspaceRoot);
   if (!screenDir) {
     return {
@@ -845,14 +1010,46 @@ export async function runScreenCli({ workspaceRoot, screenParams }) {
     outputPath
   ];
 
+  let inferredProgress = {
+    processed: 0,
+    passed: 0,
+    skipped: 0,
+    greet_count: 0
+  };
+
   const result = await runProcess({
     command: "node",
     args,
-    cwd: screenDir
+    cwd: screenDir,
+    heartbeatIntervalMs: runtime?.heartbeatIntervalMs,
+    signal: runtime?.signal,
+    onOutput: (event) => {
+      safeInvokeCallback(runtime?.onOutput, event);
+    },
+    onLine: (event) => {
+      const parsed = parseScreenProgressLine(event?.line, inferredProgress);
+      if (!parsed) return;
+      inferredProgress = parsed.progress;
+      safeInvokeCallback(runtime?.onProgress, {
+        ...inferredProgress,
+        line: parsed.line
+      });
+    },
+    onHeartbeat: (event) => {
+      safeInvokeCallback(runtime?.onHeartbeat, event);
+    }
   });
 
   const combined = `${result.stdout}\n${result.stderr}`;
   const summary = parseScreenSummary(combined);
+  if (summary) {
+    safeInvokeCallback(runtime?.onProgress, {
+      processed: Number.isInteger(summary.processed_count) ? summary.processed_count : inferredProgress.processed,
+      passed: Number.isInteger(summary.passed_count) ? summary.passed_count : inferredProgress.passed,
+      skipped: inferredProgress.skipped,
+      greet_count: inferredProgress.greet_count
+    });
+  }
 
   return {
     ok: result.code === 0,