@reconcrap/boss-recommend-mcp 2.1.5 → 2.1.7

package/README.md

@@ -82,9 +82,10 @@ curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/ma
 MCP 工具：
 
 - `list_recommend_jobs`（只读读取推荐页岗位下拉框，返回可直接用于 cron/一次性任务的 `job_names`）
-- `prepare_recommend_pipeline_run`（只校验完整 payload 是否已可用于 cron/一次性任务；不启动筛选，返回 `READY + cron_ready=true` 后才应创建 cron）
+- `prepare_recommend_pipeline_run`（只校验完整 payload；不启动筛选。若现在运行，返回 `READY + cron_ready=true` 后继续调用 `run_recommend` / `start_recommend_pipeline_run`；只有定时任务才继续 schedule）
 - `schedule_recommend_pipeline_run`（创建 package-owned 定时任务；保存已 READY 的完整 payload，启动 detached scheduler，到点后直接调用 `start_recommend_pipeline_run`）
 - `get_recommend_scheduled_run`（查询 package-owned 定时任务；到点后会显示内层 `run_id` 和 run 快照）
+- `run_recommend`（`start_recommend_pipeline_run` 的短别名；适合 Trae/Trae-CN 在 prepare READY 后正式启动）
 - `start_recommend_pipeline_run`（异步启动；同样先经过前置门禁，通过后返回 run_id）
 - `get_recommend_pipeline_run`（轮询 run_id 状态）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
@@ -264,7 +265,7 @@ BOSS_RECOMMEND_MCP_CONFIG_TARGETS   # JSON 数组或系统 path 分隔路径列
 BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS  # JSON 数组或系统 path 分隔路径列表，指定额外 skills 根目录
 ```
 
-推荐运行入口是 MCP 工具 `start_recommend_pipeline_run`。如果宿主是 QClaw 这类 shell-only agent，没有把 MCP tools 暴露给模型，可以使用 CDP-only CLI fallback：
+推荐运行入口是 MCP 工具 `run_recommend` / `start_recommend_pipeline_run`。在 Trae/Trae-CN 这类普通 MCP 宿主中，`prepare_recommend_pipeline_run` 返回 `READY + cron_ready=true` 后，若用户要现在运行，应继续调用 `run_recommend` 或 `start_recommend_pipeline_run`，不要改用 shell/CLI。只有宿主是 QClaw 这类 shell-only agent、没有把 MCP tools 暴露给模型时，才使用 CDP-only CLI fallback：
 
 ```bash
 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
@@ -464,7 +465,7 @@ Trae-CN / 长对话防循环建议：
 
 当宿主 agent 对“长时间无回包”敏感（容易误判失败）时，建议改用异步工具：
 
-1. 调用 `start_recommend_pipeline_run`。
+1. 调用 `run_recommend`（短别名）或 `start_recommend_pipeline_run`。
 2. 若返回 `NEED_INPUT/NEED_CONFIRMATION/FAILED`，按同步流程先补齐前置条件（登录、页面就绪、岗位确认、最终确认）。
 3. 仅当门禁通过时，接口才会返回 `ACCEPTED + run_id`；默认不自动轮询，建议按需调用 `get_recommend_pipeline_run`（长任务至少每 30 分钟一次，除非用户明确要求更频繁）。
 4. 若需临时中断，调用 `pause_recommend_pipeline_run`；接口会先返回 `PAUSE_REQUESTED`，随后在安全边界进入 `paused`。
@@ -474,8 +475,9 @@ Trae-CN / 长对话防循环建议：
 
 说明：
 
-- `start_recommend_pipeline_run` 为异步入口，但不会跳过同步确认流程。
-- `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 用于 cron 设置阶段；它不启动筛选，只确认 payload 已经不需要到点后再问用户。
+- `run_recommend` 与 `start_recommend_pipeline_run` 是同一个异步 MCP 启动入口，但不会跳过同步确认流程。
+- `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 只做参数门禁；它不启动筛选。普通 MCP 宿主现在运行时，prepare READY 后继续调用 `run_recommend` / `start_recommend_pipeline_run`，不要改用 CLI fallback。
+- `prepare_recommend_pipeline_run` 的 READY 响应会带 `prepared_only=true`、`run_started=false`、`recommended_next_tool=start_recommend_pipeline_run`、`alternate_next_tool=run_recommend` 和 `next_action.do_not_call_prepare_again=true`；agent 应直接照这个字段继续下一步。
 - `schedule_recommend_pipeline_run` / `boss-recommend-mcp schedule-run` 是推荐页定时启动的唯一推荐路径；它创建真实 package-owned detached scheduler，并返回 `schedule_id`。
 - 定时心跳默认 120 秒一次；`updated_at` 仍会在阶段或进度变化时刷新。
 - 每个 run 会持久化到 `~/.boss-recommend-mcp/runs/<run_id>.json`（可通过 `BOSS_RECOMMEND_HOME` 覆盖）。

package/package.json

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

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

@@ -7,7 +7,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 
 ## Goal
 
-当用户要在 Boss 推荐页筛人时，必须走 `start_recommend_pipeline_run`；若是稍后/cron 启动，必须走 `schedule_recommend_pipeline_run`。先补齐缺失值并读取岗位列表，然后展示一次包含岗位、筛选项、criteria、目标人数、后置动作、可选最大招呼数、休息强度和定时信息的总确认；用户确认后设置 `final_confirmed=true` 即可启动或创建定时任务。2.0 CDP-only 路径不再支持 legacy recommend -> chat 自动衔接；若用户要聊天页筛选或求简历，必须在推荐页任务完成后显式改用 `boss-chat` 工具。
+当用户要在 Boss 推荐页筛人时，必须走 MCP 工具 `run_recommend`（短别名）或 `start_recommend_pipeline_run`；若是稍后/cron 启动，必须走 `schedule_recommend_pipeline_run`。先补齐缺失值并读取岗位列表，然后展示一次包含岗位、筛选项、criteria、目标人数、后置动作、可选最大招呼数、休息强度和定时信息的总确认；用户确认后设置 `final_confirmed=true` 即可启动或创建定时任务。2.0 CDP-only 路径不再支持 legacy recommend -> chat 自动衔接；若用户要聊天页筛选或求简历，必须在推荐页任务完成后显式改用 `boss-chat` 工具。
 
 ## Hard Rules (Must Follow)
 
@@ -93,9 +93,10 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 用途：当用户需要为 cron / 一次性自动任务提前填写完整参数时，先用它读取推荐页岗位下拉框的全部可用岗位名；默认会复用/自动打开本机 9222 Chrome 并导航到推荐页。
   - 输出：优先把 `job_names` 里的值作为后续 `overrides.job` / `confirmation.job_value`。
   - 限制：只读岗位列表，不启动筛选任务；若返回 `BOSS_LOGIN_REQUIRED`，必须让用户在自动打开的 Chrome 完成登录后重试，本次 cron 不得创建。
-- Cron 准备工具：`prepare_recommend_pipeline_run`
-  - 用途：只校验参数是否已可用于 cron / 一次性任务，不启动筛选任务。
-  - 要求：只有返回 `status=READY` 且 `cron_ready=true` 后，才允许继续创建定时任务。
+- 准备/门禁工具：`prepare_recommend_pipeline_run`
+  - 用途：只校验参数是否完整，不启动筛选任务。
+  - 要求：若用户要“现在启动”，返回 `status=READY` 且 `cron_ready=true` 后，下一步必须调用 MCP 工具 `run_recommend` 或 `start_recommend_pipeline_run`，禁止改用 CLI fallback。只有用户要“稍后/cron/定时启动”时，才继续创建定时任务。
+  - READY 响应会带 `prepared_only=true`、`run_started=false`、`recommended_next_tool=start_recommend_pipeline_run`、`alternate_next_tool=run_recommend`、`next_action.do_not_call_prepare_again=true`；必须照这些字段继续，不得再次调用 prepare。
   - 若返回 `NEED_INPUT` / `NEED_CONFIRMATION` / `FAILED`：继续补齐 `pending_questions` 或修复登录/页面/config；不得先创建 cron。
 - Cron 创建工具：`schedule_recommend_pipeline_run`
   - 用途：保存已经 READY 的完整 payload，并启动 package-owned detached scheduler；到点后由包内 worker 直接调用 `start_recommend_pipeline_run`。
@@ -103,7 +104,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 成功标准：必须返回 `status=SCHEDULED`、`schedule_created=true`、`schedule_id`、`run_at`。只有这个返回后，才可以告诉用户定时任务已创建。
 - Cron 查询工具：`get_recommend_scheduled_run`
   - 用途：用户问“任务是否启动/进度”时，先查 `schedule_id`。若到点后已启动，会返回内层 `run_id` 和 run 快照。
-- 主工具：`start_recommend_pipeline_run`
+- 主工具：`run_recommend` / `start_recommend_pipeline_run`
 - 必填：`instruction`
 - 关键输入：
   - `confirmation`：新流程只需要 `{ "final_confirmed": true }`；旧版 `page_confirmed/page_value/.../job_confirmed/job_value` 仍兼容但不要主动制造逐项确认。
@@ -189,7 +190,7 @@ npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <sched
 
 ## QClaw / Shell-Only Fallback
 
-当 QClaw/OpenClaw 变体只暴露 shell、没有原生 MCP tool list 时，禁止停在“请使用 `start_recommend_pipeline_run` 工具”。必须用 shell 继续启动。
+当 QClaw/OpenClaw 变体只暴露 shell、没有原生 MCP tool list 时，禁止停在“请使用 `run_recommend` / `start_recommend_pipeline_run` 工具”。必须用 shell 继续启动。
 
 推荐做法：
 
@@ -207,11 +208,11 @@ npx -y @reconcrap/boss-recommend-mcp@latest run --detached --instruction-file .\
 兼容路径：
 
 - 若 `--detached` 不可用，或返回 `RECOMMEND_CLI_RUN_UNSUPPORTED_CDP_ONLY`，说明 npm/QClaw 仍在使用旧包；先运行 `npx -y @reconcrap/boss-recommend-mcp@latest install --agent qclaw` 并重启 QClaw。
-- 在包更新未生效时，可以使用已验证过的直接 MCP stdio JSON-RPC 方式调用 `start_recommend_pipeline_run`；该方式等价于原生 MCP tool 调用，不能改用 recruit/search 路径。
+- 在包更新未生效时，可以使用已验证过的直接 MCP stdio JSON-RPC 方式调用 `run_recommend` / `start_recommend_pipeline_run`；该方式等价于原生 MCP tool 调用，不能改用 recruit/search 路径。
 
 普通 MCP 可用时：
 
-`start_recommend_pipeline_run` 仍是首选。
+`run_recommend` / `start_recommend_pipeline_run` 仍是首选。`prepare_recommend_pipeline_run` 返回 READY 后，若用户要现在启动，必须继续调用这两个 MCP 工具之一；不要声称“prepare 覆盖了 MCP run 调用”，也不要切到 CLI detached fallback。
 
 禁止错误回退：
 

package/src/index.js

@@ -98,6 +98,7 @@ const { version: SERVER_VERSION } = require("../package.json");
 const TOOL_PREPARE_RUN = "prepare_recommend_pipeline_run";
 const TOOL_SCHEDULE_RUN = "schedule_recommend_pipeline_run";
 const TOOL_GET_SCHEDULED_RUN = "get_recommend_scheduled_run";
+const TOOL_RUN_RECOMMEND = "run_recommend";
 const TOOL_START_RUN = "start_recommend_pipeline_run";
 const TOOL_GET_RUN = "get_recommend_pipeline_run";
 const TOOL_CANCEL_RUN = "cancel_recommend_pipeline_run";
@@ -1134,7 +1135,7 @@ function createToolsSchema() {
     },
     {
       name: TOOL_PREPARE_RUN,
-      description: "只校验 Boss 推荐页流水线参数是否已可用于 cron/一次性任务；不会启动筛选任务。只有返回 READY/cron_ready=true 后才应创建定时任务。",
+      description: "只校验 Boss 推荐页流水线参数是否完整；不会启动筛选任务。若用户要现在运行，返回 READY/cron_ready=true 后必须继续调用 MCP 工具 run_recommend 或 start_recommend_pipeline_run；只有定时/稍后运行才调用 schedule_recommend_pipeline_run。不要因为 prepare READY 而改用 shell/CLI fallback。",
       inputSchema: createRunInputSchema()
     },
     {
@@ -1154,11 +1155,16 @@ function createToolsSchema() {
         additionalProperties: false
       }
     },
+    {
+      name: TOOL_RUN_RECOMMEND,
+      description: "立即通过 MCP 启动 Boss 推荐页筛选。它是 start_recommend_pipeline_run 的短别名，适合 Trae/Trae-CN 等代理在 prepare_recommend_pipeline_run 返回 READY 后继续正式运行；MCP 内部会按需使用包内 detached worker，普通 MCP 可用时不要改用 CLI fallback。",
+      inputSchema: createRunInputSchema()
+    },
     {
       name: TOOL_START_RUN,
-      description: "异步启动 Boss 推荐页流水线（含同步门禁预检）；只有在前置确认与页面就绪通过后才返回 run_id。",
+      description: "立即通过 MCP 异步启动 Boss 推荐页流水线（含同步门禁预检）；prepare_recommend_pipeline_run 返回 READY 后，如果用户要现在运行就调用本工具或 run_recommend。MCP 内部会按需使用包内 detached worker，普通 MCP 可用时不要改用 CLI fallback。",
       inputSchema: createRunInputSchema()
-    },
+    },
     {
       name: TOOL_GET_RUN,
       description: "按 run_id 查询异步/同步流水线运行状态快照。",
@@ -2625,7 +2631,7 @@ async function handleRequest(message, workspaceRoot) {
     const toolName = params?.name;
     const args = params?.arguments || {};
 
-    if (toolName === TOOL_START_RUN) {
+    if ([TOOL_RUN_RECOMMEND, TOOL_START_RUN].includes(toolName)) {
       const inputError = validateRunArgs(args);
       if (inputError) {
         return createJsonRpcError(id, -32602, inputError);
@@ -2689,7 +2695,7 @@ async function handleRequest(message, workspaceRoot) {
         payload = await scheduleRecommendPipelineRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_SCHEDULED_RUN) {
         payload = getRecommendScheduledRunTool({ args });
-      } else if (toolName === TOOL_START_RUN) {
+      } else if ([TOOL_RUN_RECOMMEND, TOOL_START_RUN].includes(toolName)) {
         payload = await handleStartRunTool({ workspaceRoot, args });
       } else if (toolName === TOOL_GET_RUN) {
         payload = handleGetRunTool(args);

package/src/recommend-mcp.js

@@ -1563,13 +1563,33 @@ export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {}
     };
   }
   const { parsed, normalized } = prepared;
+  const nextAction = {
+    immediate_run: {
+      recommended_next_tool: "start_recommend_pipeline_run",
+      alternate_next_tool: "run_recommend",
+      same_arguments: true
+    },
+    scheduled_run: {
+      recommended_next_tool: "schedule_recommend_pipeline_run",
+      same_arguments: true,
+      requires_schedule_field: true
+    },
+    do_not_call_prepare_again: true,
+    do_not_use_cli_fallback_when_mcp_tools_available: true
+  };
   return {
     status: "READY",
     cron_ready: true,
+    prepared_only: true,
+    run_started: false,
+    recommended_next_tool: nextAction.immediate_run.recommended_next_tool,
+    alternate_next_tool: nextAction.immediate_run.alternate_next_tool,
+    next_action: nextAction,
+    message: "READY only means the payload passed validation; prepare_recommend_pipeline_run did not start a run. To start now, call start_recommend_pipeline_run or run_recommend with the same arguments. Do not call prepare_recommend_pipeline_run again, and do not use CLI fallback when MCP tools are available.",
     review: parsed.review,
     post_action: {
       requested: normalized.postAction,
-      execute_post_action: args.dry_run_post_action === true ? false : args.execute_post_action !== false,
+      execute_post_action: args.dry_run_post_action === true ? false : args.execute_post_action !== false,
       max_greet_count: normalized.maxGreetCount
     },
     target_count_semantics: TARGET_COUNT_SEMANTICS