@reconcrap/boss-recommend-mcp 2.1.0 → 2.1.1

package/README.md

@@ -20,6 +20,7 @@ Boss 推荐 / 搜索 / 聊天筛选 MCP（stdio）服务。
 MCP 工具：
 
 - `list_recommend_jobs`（只读读取推荐页岗位下拉框，返回可直接用于 cron/一次性任务的 `job_names`）
+- `prepare_recommend_pipeline_run`（只校验完整 payload 是否已可用于 cron/一次性任务；不启动筛选，返回 `READY + cron_ready=true` 后才应创建 cron）
 - `start_recommend_pipeline_run`（异步启动；同样先经过前置门禁，通过后返回 run_id）
 - `get_recommend_pipeline_run`（轮询 run_id 状态）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
@@ -53,10 +54,19 @@ boss-recommend-mcp list-jobs --slow-live --port 9222
 
 返回的 `job_names` 可直接作为后续 `start_recommend_pipeline_run` 的 `confirmation.job_value` / `overrides.job`。
 
+Cron / 一次性定时任务设置建议先在设置阶段完成 Chrome/登录/岗位发现与全部确认：
+
+```bash
+boss-recommend-mcp prepare-run --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --slow-live --port 9222
+```
+
+只有输出 `status: "READY"` 且 `cron_ready: true` 后，才把同一份 payload 写入 cron 并在到点时调用 `start_recommend_pipeline_run` / `boss-recommend-mcp run --detached`。如果设置阶段返回 `BOSS_LOGIN_REQUIRED`、`NEED_INPUT` 或 `NEED_CONFIRMATION`，先让用户登录或补齐确认，不要创建 cron。
+
 状态机：
 
 - `NEED_INPUT`
 - `NEED_CONFIRMATION`
+- `READY`（仅准备工具）
 - `COMPLETED`
 - `FAILED`
 
@@ -374,6 +384,7 @@ Trae-CN / 长对话防循环建议：
 说明：
 
 - `start_recommend_pipeline_run` 为异步入口，但不会跳过同步确认流程。
+- `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 用于 cron 设置阶段；它不启动筛选，只确认 payload 已经不需要到点后再问用户。
 - 定时心跳默认 120 秒一次；`updated_at` 仍会在阶段或进度变化时刷新。
 - 每个 run 会持久化到 `~/.boss-recommend-mcp/runs/<run_id>.json`（可通过 `BOSS_RECOMMEND_HOME` 覆盖）。
 - screen 阶段会持久化 checkpoint：`~/.boss-recommend-mcp/runs/<run_id>.checkpoint.json`。

package/package.json

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

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

@@ -89,9 +89,13 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 ## Tool Usage
 
 - 岗位发现工具：`list_recommend_jobs`
-  - 用途：当用户需要为 cron / 一次性自动任务提前填写完整参数时，先用它读取推荐页岗位下拉框的全部可用岗位名。
+  - 用途：当用户需要为 cron / 一次性自动任务提前填写完整参数时，先用它读取推荐页岗位下拉框的全部可用岗位名；默认会复用/自动打开本机 9222 Chrome 并导航到推荐页。
   - 输出：优先把 `job_names` 里的值作为后续 `overrides.job` / `confirmation.job_value`。
-  - 限制：只读岗位列表，不启动筛选任务；仍然必须在正式 `start_recommend_pipeline_run` 前完成岗位与最终确认。
+  - 限制：只读岗位列表，不启动筛选任务；若返回 `BOSS_LOGIN_REQUIRED`，必须让用户在自动打开的 Chrome 完成登录后重试，本次 cron 不得创建。
+- Cron 准备工具：`prepare_recommend_pipeline_run`
+  - 用途：只校验参数是否已可用于 cron / 一次性任务，不启动筛选任务。
+  - 要求：只有返回 `status=READY` 且 `cron_ready=true` 后，才允许创建 cron。
+  - 若返回 `NEED_INPUT` / `NEED_CONFIRMATION` / `FAILED`：继续补齐 `pending_questions` 或修复登录/页面/config；不得先创建 cron。
 - 主工具：`start_recommend_pipeline_run`
 - 必填：`instruction`
 - 关键输入：
@@ -107,6 +111,25 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 - 拿到 `ACCEPTED + run_id` 后默认停止本轮，不自动轮询。
 - 在拿到 `ACCEPTED + run_id` 之前，禁止以“我已帮你确认参数”为由越过必填确认阶段。
 
+## Cron / Scheduled Run Policy
+
+创建 cron 时必须在设置 cron 的当下完成全部交互：
+
+1. 锁定用户原始 instruction，不改写、不摘要，criteria 放入 `overrides.criteria` 时必须逐字保留。
+2. 收集 Stage A 全部筛选项、`target_count`、`post_action`、`max_greet_count`（如需要）和本次 `rest_level`。
+3. 调用 `list_recommend_jobs`；若 Chrome 未打开，工具会尝试自动打开本机 9222 Chrome 并进入推荐页。若返回 `BOSS_LOGIN_REQUIRED` 或页面不可用，停止 cron 创建，让用户登录/修复后重试。
+4. 用 `job_names` 中的精确岗位名完成岗位确认，并完成最终总确认，写入 `job_confirmed=true` 与 `final_confirmed=true`。
+5. 调用 `prepare_recommend_pipeline_run` 传入将来要执行的完整 payload；只有 `READY + cron_ready=true` 才能创建 cron。
+6. cron 到点时只调用 `start_recommend_pipeline_run`，并传入准备阶段验证过的同一份 payload。到点后若 Chrome/登录异常，应作为运行失败处理，不得再向用户追问参数。
+
+Shell-only OpenClaw/QClaw cron 设置同样先运行：
+
+```powershell
+npx -y @reconcrap/boss-recommend-mcp@latest prepare-run --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --slow-live --port 9222
+```
+
+仅当上述命令输出 `READY` 且 `cron_ready=true` 后，才把对应的 detached `run` 命令写入 cron。
+
 ## Async Run Policy
 
 - 用户未明确要求“持续跟进”时，不自动 `sleep + get_recommend_pipeline_run`。
@@ -150,13 +173,14 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 推荐做法：
 
 1. 将锁定的用户原文写入 instruction 文件，将已确认参数写入 `overrides` 与 `confirmation` JSON 文件。
-2. 用 detached CLI 启动，让父命令返回启动证据，子进程继续持有 CDP 会话：
+2. 先用 `prepare-run` 校验完整 payload 已 cron-ready；未返回 `READY + cron_ready=true` 不得创建 cron 或启动 run。
+3. 用 detached CLI 启动，让父命令返回启动证据，子进程继续持有 CDP 会话：
 
 ```powershell
 npx -y @reconcrap/boss-recommend-mcp@latest run --detached --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --slow-live --port 9222
 ```
 
-3. 若返回 `ACCEPTED + run_id`，即任务已启动；记录 `run_id/stdout_path/stderr_path`。若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`，只补 `pending_questions`，不要重写已锁定的用户原文。
+4. 若返回 `ACCEPTED + run_id`，即任务已启动；记录 `run_id/stdout_path/stderr_path`。若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`，说明 cron 设置阶段漏掉了准备门禁，应回到 `prepare-run` 补齐，不能在到点后继续问用户确认。
 
 兼容路径：
 

package/src/cli.js

@@ -23,10 +23,11 @@ import {
   prepareBossChatRunTool,
   resumeBossChatRunTool
 } from "./chat-mcp.js";
-import {
-  listRecommendJobsTool,
-  startRecommendPipelineRunTool
-} from "./recommend-mcp.js";
+import {
+  listRecommendJobsTool,
+  prepareRecommendPipelineRunTool,
+  startRecommendPipelineRunTool
+} from "./recommend-mcp.js";
 import {
   getBossScreenConfigResolution,
   resolveBossChatRuntimeLayout as resolveCdpBossChatRuntimeLayout,
@@ -53,7 +54,7 @@ const defaultMcpServerName = "boss-recommend";
 const defaultMcpCommand = "npx";
 const recommendMcpPackageName = "@reconcrap/boss-recommend-mcp";
 const recommendMcpBinaryName = "boss-recommend-mcp";
-const autoSyncSkipCommands = new Set(["install", "install-skill", "where", "help", "--help", "-h", "list-jobs", "jobs", "recommend-jobs"]);
+const autoSyncSkipCommands = new Set(["install", "install-skill", "where", "help", "--help", "-h", "list-jobs", "jobs", "recommend-jobs"]);
 const externalMcpTargetsEnv = "BOSS_RECOMMEND_MCP_CONFIG_TARGETS";
 const externalSkillDirsEnv = "BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS";
 const installConfigDefaults = Object.freeze({
@@ -2621,10 +2622,11 @@ function printHelp() {
   console.log("boss-recommend-mcp");
   console.log("");
   console.log("Usage:");
-  console.log("  boss-recommend-mcp              Start the MCP server");
-  console.log("  boss-recommend-mcp start        Start the MCP server");
-  console.log("  boss-recommend-mcp run          Start a CDP-only recommend run through the shared run service");
-  console.log("  boss-recommend-mcp list-jobs    CDP-only list of exact recommend job names for cron/one-shot inputs");
+  console.log("  boss-recommend-mcp              Start the MCP server");
+  console.log("  boss-recommend-mcp start        Start the MCP server");
+  console.log("  boss-recommend-mcp prepare-run  Validate a cron-ready recommend run payload without starting screening");
+  console.log("  boss-recommend-mcp run          Start a CDP-only recommend run through the shared run service");
+  console.log("  boss-recommend-mcp list-jobs    CDP-only list of exact recommend job names for cron/one-shot inputs");
   console.log("  boss-recommend-mcp chat <subcommand>  Run CDP-only boss-chat health/prepare/status commands");
   console.log("  boss-recommend-mcp install      Install/migrate skills and MCP configs; replaces legacy Boss MCP routes (supports --agent trae-cn/openclaw/qclaw/...)");
   console.log("  boss-recommend-mcp install-skill Install bundled Codex skills (recommend/recruit/chat)");
@@ -2636,10 +2638,11 @@ function printHelp() {
   console.log("  boss-recommend-mcp calibrate    Disabled until CDP-only featured calibration is live-verified");
   console.log("  boss-recommend-mcp launch-chrome Launch or reuse Chrome debug instance and open Boss recommend page");
   console.log("  boss-recommend-mcp where        Print installed package, skill, and config paths");
-  console.log("");
-  console.log("Run command:");
-  console.log("  boss-recommend-mcp run --instruction \"推荐页上筛选211男生，近14天没有，有大模型平台经验\" --overrides-file overrides.json --confirmation-file confirmation.json");
-  console.log("  boss-recommend-mcp run --detached --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
+  console.log("");
+  console.log("Run command:");
+  console.log("  boss-recommend-mcp prepare-run --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
+  console.log("  boss-recommend-mcp run --instruction \"推荐页上筛选211男生，近14天没有，有大模型平台经验\" --overrides-file overrides.json --confirmation-file confirmation.json");
+  console.log("  boss-recommend-mcp run --detached --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json");
   console.log("  boss-recommend-mcp list-jobs --slow-live --port 9222");
   console.log("  boss-recommend-mcp chat prepare-run --slow-live --port 9222    # CDP-only preflight; start runs through MCP start_boss_chat_run");
   console.log("  boss-recommend-mcp config set --base-url <url> --api-key <key> --model <model> [--thinking-level off|low|medium|high|current] [--greeting-message <text>] [--openai-organization <id>] [--openai-project <id>]");
@@ -2733,14 +2736,13 @@ async function installAll(options = {}) {
   }
 }
 
-async function runPipelineOnce(options = {}) {
-  const instruction = getRunInstruction(options);
-  const confirmation = getRunConfirmation(options);
-  const overrides = getRunOverrides(options);
-  const followUp = getRunFollowUp(options);
-  const workspaceRoot = getWorkspaceRoot(options);
-  const port = parsePositivePort(options.port) || parsePositivePort(process.env.BOSS_RECOMMEND_CHROME_PORT) || 9222;
-
+function buildRecommendRunCliInput(options = {}) {
+  const instruction = getRunInstruction(options);
+  const confirmation = getRunConfirmation(options);
+  const overrides = getRunOverrides(options);
+  const followUp = getRunFollowUp(options);
+  const port = parsePositivePort(options.port) || parsePositivePort(process.env.BOSS_RECOMMEND_CHROME_PORT) || 9222;
+
   const args = {
     instruction,
     confirmation: confirmation ?? undefined,
@@ -2797,15 +2799,46 @@ async function runPipelineOnce(options = {}) {
     "llm_image_limit",
     "llm_image_detail"
   ];
-  for (const key of optionalPassthrough) {
-    const kebab = key.replace(/_/g, "-");
-    if (options[key] !== undefined) args[key] = options[key];
-    else if (options[kebab] !== undefined) args[key] = options[kebab];
-  }
-
-  const result = await startRecommendPipelineRunTool({
-    workspaceRoot,
-    args
+  for (const key of optionalPassthrough) {
+    const kebab = key.replace(/_/g, "-");
+    if (options[key] !== undefined) args[key] = options[key];
+    else if (options[kebab] !== undefined) args[key] = options[kebab];
+  }
+
+  return {
+    args,
+    port
+  };
+}
+
+async function preparePipelineOnce(options = {}) {
+  const workspaceRoot = getWorkspaceRoot(options);
+  const { args, port } = buildRecommendRunCliInput(options);
+  const result = prepareRecommendPipelineRunTool({
+    workspaceRoot,
+    args
+  });
+  printJson({
+    ...result,
+    cli: {
+      command: "prepare-run",
+      cdp_only: true,
+      shared_run_service: true,
+      workspace_root: workspaceRoot,
+      port
+    }
+  });
+  if (result.status !== "READY" || result.cron_ready !== true) {
+    process.exitCode = 1;
+  }
+}
+
+async function runPipelineOnce(options = {}) {
+  const workspaceRoot = getWorkspaceRoot(options);
+  const { args, port } = buildRecommendRunCliInput(options);
+  const result = await startRecommendPipelineRunTool({
+    workspaceRoot,
+    args
   });
   printJson({
     ...result,
@@ -2974,11 +3007,11 @@ export async function runCli(argv = process.argv) {
     case "mcp":
       startServer();
       break;
-    case "run":
-      try {
-        if (
-          (options.detached === true || options.background === true)
-          && process.env[detachedRecommendRunChildEnv] !== "1"
+    case "run":
+      try {
+        if (
+          (options.detached === true || options.background === true)
+          && process.env[detachedRecommendRunChildEnv] !== "1"
         ) {
           await runPipelineDetached(argv.slice(3), options);
         } else {
@@ -2993,9 +3026,26 @@ export async function runCli(argv = process.argv) {
             retryable: false
           }
         });
-        process.exitCode = 1;
-      }
-      break;
+        process.exitCode = 1;
+      }
+      break;
+    case "prepare-run":
+    case "prepare":
+      try {
+        await preparePipelineOnce(options);
+      } catch (error) {
+        printJson({
+          status: "FAILED",
+          cron_ready: false,
+          error: {
+            code: "INVALID_CLI_INPUT",
+            message: error.message || "Invalid CLI input",
+            retryable: false
+          }
+        });
+        process.exitCode = 1;
+      }
+      break;
     case "list-jobs":
     case "jobs":
     case "recommend-jobs":
@@ -3153,10 +3203,11 @@ export const __testables = {
   installSkill,
   isInstalledPackageRoot,
   mergeMcpServerConfigFile,
-  resolveBossChatRuntimeLayout: resolveCdpBossChatRuntimeLayout,
-  runBossChatCliCommand,
-  runPipelineOnce
-};
+  resolveBossChatRuntimeLayout: resolveCdpBossChatRuntimeLayout,
+  runBossChatCliCommand,
+  preparePipelineOnce,
+  runPipelineOnce
+};
 
 if (process.argv[1] && path.resolve(process.argv[1]) === currentFilePath) {
   await runCli(process.argv);

package/src/index.js

@@ -87,8 +87,9 @@ import {
 } from "./run-state.js";
 
 const require = createRequire(import.meta.url);
-const { version: SERVER_VERSION } = require("../package.json");
-
+const { version: SERVER_VERSION } = require("../package.json");
+
+const TOOL_PREPARE_RUN = "prepare_recommend_pipeline_run";
 const TOOL_START_RUN = "start_recommend_pipeline_run";
 const TOOL_GET_RUN = "get_recommend_pipeline_run";
 const TOOL_CANCEL_RUN = "cancel_recommend_pipeline_run";
@@ -1089,10 +1090,15 @@ function createToolsSchema() {
       description: "CDP-only 读取 Boss 推荐页岗位下拉框，返回所有可用岗位完整名称，方便 cron/一次性任务提前填写 job 参数。不会启动筛选任务。",
       inputSchema: createListRecommendJobsInputSchema()
     },
+    {
+      name: TOOL_PREPARE_RUN,
+      description: "只校验 Boss 推荐页流水线参数是否已可用于 cron/一次性任务；不会启动筛选任务。只有返回 READY/cron_ready=true 后才应创建定时任务。",
+      inputSchema: createRunInputSchema()
+    },
     {
       name: TOOL_START_RUN,
       description: "异步启动 Boss 推荐页流水线（含同步门禁预检）；只有在前置确认与页面就绪通过后才返回 run_id。",
-      inputSchema: createRunInputSchema()
+      inputSchema: createRunInputSchema()
     },
     {
       name: TOOL_GET_RUN,
@@ -2618,6 +2624,8 @@ async function handleRequest(message, workspaceRoot) {
       let payload;
       if (toolName === TOOL_LIST_RECOMMEND_JOBS) {
         payload = await listRecommendJobsTool({ workspaceRoot, args });
+      } else if (toolName === TOOL_PREPARE_RUN) {
+        payload = prepareRecommendPipelineRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_START_RUN) {
         payload = await handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_RUN) {

package/src/recommend-mcp.js

@@ -1464,15 +1464,21 @@ async function startRecommendPipelineRunInternal(args = {}, { workspaceRoot = ""
   };
 }
 
-export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {} } = {}) {
-  const prepared = prepareRecommendPipelineStart(args, { workspaceRoot });
-  if (prepared.response) return prepared.response;
-  const { parsed, normalized } = prepared;
-  return {
-    status: "READY",
-    review: parsed.review,
-    post_action: {
-      requested: normalized.postAction,
+export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {} } = {}) {
+  const prepared = prepareRecommendPipelineStart(args, { workspaceRoot });
+  if (prepared.response) {
+    return {
+      ...prepared.response,
+      cron_ready: false
+    };
+  }
+  const { parsed, normalized } = prepared;
+  return {
+    status: "READY",
+    cron_ready: true,
+    review: parsed.review,
+    post_action: {
+      requested: normalized.postAction,
       execute_post_action: args.dry_run_post_action === true ? false : args.execute_post_action !== false,
       max_greet_count: normalized.maxGreetCount
     },