@reconcrap/boss-recommend-mcp 2.1.7 → 2.1.9

package/README.md

@@ -265,19 +265,21 @@ BOSS_RECOMMEND_MCP_CONFIG_TARGETS   # JSON 数组或系统 path 分隔路径列
 BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS  # JSON 数组或系统 path 分隔路径列表，指定额外 skills 根目录
 ```
 
-推荐运行入口是 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：
+推荐运行入口是 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`，不要改用 terminal/shell/run_command/CLI/manual JSON-RPC，也不要用短延迟 `schedule_recommend_pipeline_run` 冒充立即启动。`prepare` 能返回结果就证明该宿主已经可以调用本 MCP server。
+
+只有宿主是 QClaw 这类真正 shell-only agent、没有把 MCP tools 暴露给模型、且当前会话从未成功调用过 `boss-recommend/prepare_recommend_pipeline_run` 时，才使用 CDP-only CLI fallback。CLI fallback 也必须显式传本次用户确认的 rest level：
 
 ```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
+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 --rest-level <low|medium|high> --slow-live --port 9222
 ```
 
 `--detached` 会让父进程输出 `ACCEPTED + run_id` 后退出，子进程继续持有 Chrome DevTools 会话并执行长任务。岗位发现可以使用只读 CLI：
 
-如果是稍后启动/cron/定时任务，不要手写系统 cron；用 package-owned scheduler：
+如果用户明确要求稍后启动/cron/定时任务，不要手写系统 cron；用 package-owned scheduler：
 
 ```bash
-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
-npx -y @reconcrap/boss-recommend-mcp@latest schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --slow-live --port 9222
+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 --rest-level <low|medium|high> --slow-live --port 9222
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file boss-recommend-overrides.json --confirmation-file boss-recommend-confirmation.json --rest-level <low|medium|high> --slow-live --port 9222
 npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <schedule_id>
 ```
 

package/package.json

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

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

@@ -17,6 +17,13 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 只有用户**明确**说搜索页（`search/搜索页//web/chat/search`）时，才可转 `boss-recruit-pipeline`。
   - recommend 失败时（如 `JOB_TRIGGER_NOT_FOUND/NO_RECOMMEND_IFRAME/BOSS_LOGIN_REQUIRED`）禁止降级到 recruit；先修 recommend 页面就绪/登录态。
 
+- **Trae-CN / 原生 MCP 启动强制规则**
+  - 如果当前会话里已经成功调用过 `boss-recommend/prepare_recommend_pipeline_run`，说明 Trae-CN 已经具备原生 MCP tool call 能力；下一步必须继续调用 `boss-recommend/start_recommend_pipeline_run` 或 `boss-recommend/run_recommend`。
+  - `prepare_recommend_pipeline_run` 返回 `READY` 只代表参数校验通过，不代表已经启动；严禁再次调用 prepare 试图启动。
+  - 在 Trae-CN、Trae、Codex、Cursor、Claude Code 等普通 MCP 宿主中，严禁用 `run_command`、终端、PowerShell、`npx ... run --detached`、手写 `tools/call` JSON-RPC 或任何 CLI fallback 启动 recommend run。
+  - 用户要“现在启动”时，严禁用 `schedule_recommend_pipeline_run` 加短延迟冒充立即启动；schedule 只用于用户明确要求稍后/cron/定时。
+  - 不要说“prepare 覆盖了 MCP run 调用”。正确说法是：prepare 没有启动，下一步是原生 MCP tool call。
+
 - **确认不可代填（强制）**
   - 禁止 agent 自行“设置合理参数”并代替用户确认。
   - 禁止在用户未明确回复前，把 `final_confirmed=true`。
@@ -95,11 +102,12 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 限制：只读岗位列表，不启动筛选任务；若返回 `BOSS_LOGIN_REQUIRED`，必须让用户在自动打开的 Chrome 完成登录后重试，本次 cron 不得创建。
 - 准备/门禁工具：`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。
+  - 要求：若用户要“现在启动”，返回 `status=READY` 且 `cron_ready=true` 后，下一步必须调用 MCP 工具 `run_recommend` 或 `start_recommend_pipeline_run`，禁止改用 terminal/shell/run_command/CLI/manual JSON-RPC。只有用户要“稍后/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`、`agent_guidance.native_mcp_required_after_prepare=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`。
+  - 用途：只在用户明确要求“稍后/cron/定时启动”时保存已经 READY 的完整 payload，并启动 package-owned detached scheduler；到点后由包内 worker 直接调用 `start_recommend_pipeline_run`。
+  - 禁止：用户要“现在启动”时，不得用短延迟 schedule 作为 `run_recommend` / `start_recommend_pipeline_run` 的替代。
   - 必填：同 `start_recommend_pipeline_run` 的完整 payload，另加 `schedule_delay_minutes` / `schedule_delay_seconds` / `schedule_run_at` 之一。
   - 成功标准：必须返回 `status=SCHEDULED`、`schedule_created=true`、`schedule_id`、`run_at`。只有这个返回后，才可以告诉用户定时任务已创建。
 - Cron 查询工具：`get_recommend_scheduled_run`
@@ -132,10 +140,10 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 7. 只有拿到 `SCHEDULED + schedule_id` 后才告诉用户定时任务已创建。回复必须包含 `schedule_id`，而不是只说“10 分钟后会启动”。
 8. 到点后由 package-owned detached scheduler 启动；若 Chrome/登录异常，应作为 schedule/run 失败处理，不得再向用户追问参数。
 
-Shell-only OpenClaw/QClaw cron 设置同样先运行 prepare：
+Shell-only OpenClaw/QClaw cron 设置同样先运行 prepare，并显式带上用户已确认的休息强度：
 
 ```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
+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 --rest-level <low|medium|high> --slow-live --port 9222
 ```
 
 仅当上述命令输出 `READY` 且 `cron_ready=true` 后，才允许继续创建定时任务。
@@ -143,7 +151,7 @@ npx -y @reconcrap/boss-recommend-mcp@latest prepare-run --instruction-file .\bos
 然后必须用 package-owned scheduler 创建定时任务，不要手写系统 cron：
 
 ```powershell
-npx -y @reconcrap/boss-recommend-mcp@latest schedule-run --schedule-delay-minutes 10 --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --slow-live --port 9222
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-run --schedule-delay-minutes 10 --instruction-file .\boss-recommend-instruction.txt --overrides-file .\boss-recommend-overrides.json --confirmation-file .\boss-recommend-confirmation.json --rest-level <low|medium|high> --slow-live --port 9222
 ```
 
 用户查询时：
@@ -188,18 +196,22 @@ npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <sched
 - `featured` 且缺少校准文件：先 `boss-recommend-mcp calibrate`。
 - `latest`：流程同 `recommend`，但使用最新 tab 结构（`data-status=1`）。
 
-## QClaw / Shell-Only Fallback
+## True Shell-Only Fallback (Never Trae-CN)
+
+本节只适用于宿主**完全没有**原生 MCP tool list、也无法调用 `boss-recommend/prepare_recommend_pipeline_run` 的 QClaw/OpenClaw 变体。
+
+只要当前会话里出现过 `boss-recommend/prepare_recommend_pipeline_run`、`boss-recommend/run_recommend`、`boss-recommend/start_recommend_pipeline_run` 这类原生 MCP 调用，本节立即失效。Trae-CN 永远不使用本节。
 
-当 QClaw/OpenClaw 变体只暴露 shell、没有原生 MCP tool list 时，禁止停在“请使用 `run_recommend` / `start_recommend_pipeline_run` 工具”。必须用 shell 继续启动。
+当 QClaw/OpenClaw 变体只暴露 shell、没有原生 MCP tool list 时，才可以用 shell 继续启动。
 
 推荐做法：
 
 1. 将锁定的用户原文写入 instruction 文件，将已确认参数写入 `overrides` JSON；`confirmation` JSON 只需要 `{ "final_confirmed": true }`。
-2. 先用 `prepare-run` 校验完整 payload 已 cron-ready；未返回 `READY + cron_ready=true` 不得创建定时任务或启动 run。
+2. 先用 `prepare-run` 校验完整 payload 已 cron-ready，并显式传 `--rest-level <low|medium|high>`；未返回 `READY + cron_ready=true` 不得创建定时任务或启动 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
+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 --rest-level <low|medium|high> --slow-live --port 9222
 ```
 
 4. 若用户要“稍后/cron/定时启动”，用 `schedule-run`，不是 `run --detached`。若 `schedule-run` 未返回 `SCHEDULED + schedule_id`，不得告诉用户定时任务已创建。
@@ -208,7 +220,7 @@ 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 方式调用 `run_recommend` / `start_recommend_pipeline_run`；该方式等价于原生 MCP tool 调用，不能改用 recruit/search 路径。
+- 禁止使用 `npx @reconcrap/boss-recommend-mcp --stdio` 或 PowerShell 手写 `tools/call` JSON-RPC；该包的 MCP server 入口是 `start`，普通 MCP 宿主必须使用原生 tool call。
 
 普通 MCP 可用时：
 

package/src/cli.js

@@ -2716,11 +2716,11 @@ function printHelp() {
   console.log("  boss-recommend-mcp install --mcp-launch global-wrapper  Use ~/.boss-recommend-mcp/bin wrapper so npm global upgrades affect MCP hosts");
   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 schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file overrides.json --confirmation-file confirmation.json");
+  console.log("  boss-recommend-mcp prepare-run --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json --rest-level medium");
+  console.log("  boss-recommend-mcp schedule-run --schedule-delay-minutes 10 --instruction-file boss-recommend-instruction.txt --overrides-file overrides.json --confirmation-file confirmation.json --rest-level medium");
   console.log("  boss-recommend-mcp schedule-status --schedule-id <id>");
-  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 run --instruction \"推荐页上筛选211男生，近14天没有，有大模型平台经验\" --overrides-file overrides.json --confirmation-file confirmation.json --rest-level medium");
+  console.log("  boss-recommend-mcp run --detached --instruction \"...\" --overrides-file overrides.json --confirmation-file confirmation.json --rest-level medium");
   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>]");

package/src/index.js

@@ -1135,12 +1135,22 @@ function createToolsSchema() {
     },
     {
       name: TOOL_PREPARE_RUN,
-      description: "只校验 Boss 推荐页流水线参数是否完整；不会启动筛选任务。若用户要现在运行，返回 READY/cron_ready=true 后必须继续调用 MCP 工具 run_recommend 或 start_recommend_pipeline_run；只有定时/稍后运行才调用 schedule_recommend_pipeline_run。不要因为 prepare READY 而改用 shell/CLI fallback。",
+      description: "只校验 Boss 推荐页流水线参数是否完整；不会启动筛选任务。若用户要现在运行，返回 READY/cron_ready=true 后必须继续调用本 MCP server 的 run_recommend 或 start_recommend_pipeline_run；只有定时/稍后运行才调用 schedule_recommend_pipeline_run。prepare 能返回结果就证明原生 MCP 可用，禁止改用 terminal/shell/run_command/CLI/manual JSON-RPC。",
+      inputSchema: createRunInputSchema()
+    },
+    {
+      name: TOOL_RUN_RECOMMEND,
+      description: "立即通过原生 MCP 启动 Boss 推荐页筛选。它是 start_recommend_pipeline_run 的短别名，适合 Trae/Trae-CN 等代理在 prepare_recommend_pipeline_run 返回 READY 后继续正式运行；必须作为 MCP tool call 调用，禁止通过 terminal/shell/run_command/CLI/manual JSON-RPC 代替，也不要用 schedule_recommend_pipeline_run 冒充立即启动。",
+      inputSchema: createRunInputSchema()
+    },
+    {
+      name: TOOL_START_RUN,
+      description: "立即通过原生 MCP 异步启动 Boss 推荐页流水线（含同步门禁预检）；prepare_recommend_pipeline_run 返回 READY 后，如果用户要现在运行就调用本工具或 run_recommend。必须作为 MCP tool call 调用，禁止通过 terminal/shell/run_command/CLI/manual JSON-RPC 代替，也不要用 schedule_recommend_pipeline_run 冒充立即启动。",
       inputSchema: createRunInputSchema()
     },
     {
       name: TOOL_SCHEDULE_RUN,
-      description: "创建 package-owned Boss 推荐页定时任务：先校验 READY/cron_ready，再保存完整 payload，并由 detached scheduler 到点直接启动，不再依赖 AI harness 自己拼 shell cron。",
+      description: "只用于用户明确要求稍后/cron/定时启动的 package-owned Boss 推荐页定时任务。若用户要现在运行，必须调用 run_recommend 或 start_recommend_pipeline_run，不要用短延迟 schedule 冒充立即启动。schedule 会先校验 READY/cron_ready，再保存完整 payload，并由 detached scheduler 到点直接启动，不依赖 AI harness 自己拼 shell cron。",
       inputSchema: createScheduleRunInputSchema()
     },
     {
@@ -1155,16 +1165,6 @@ 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: "立即通过 MCP 异步启动 Boss 推荐页流水线（含同步门禁预检）；prepare_recommend_pipeline_run 返回 READY 后，如果用户要现在运行就调用本工具或 run_recommend。MCP 内部会按需使用包内 detached worker，普通 MCP 可用时不要改用 CLI fallback。",
-      inputSchema: createRunInputSchema()
-    },
     {
       name: TOOL_GET_RUN,
       description: "按 run_id 查询异步/同步流水线运行状态快照。",

package/src/recommend-mcp.js

@@ -1567,7 +1567,8 @@ export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {}
     immediate_run: {
       recommended_next_tool: "start_recommend_pipeline_run",
       alternate_next_tool: "run_recommend",
-      same_arguments: true
+      same_arguments: true,
+      native_mcp_required: true
     },
     scheduled_run: {
       recommended_next_tool: "schedule_recommend_pipeline_run",
@@ -1575,7 +1576,35 @@ export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {}
       requires_schedule_field: true
     },
     do_not_call_prepare_again: true,
-    do_not_use_cli_fallback_when_mcp_tools_available: true
+    do_not_use_cli_fallback_when_mcp_tools_available: true,
+    do_not_use_terminal_or_shell: true,
+    forbidden_fallbacks: [
+      "run_command",
+      "terminal",
+      "shell",
+      "CLI detached fallback",
+      "manual JSON-RPC over shell",
+      "npx --stdio"
+    ]
+  };
+  const agentGuidance = {
+    host_has_native_mcp: true,
+    native_mcp_required_after_prepare: true,
+    proof: "This prepare_recommend_pipeline_run response was returned by the MCP server, so the host can call MCP tools from this server.",
+    immediate_run: {
+      tool: nextAction.immediate_run.recommended_next_tool,
+      alternate_tool: nextAction.immediate_run.alternate_next_tool,
+      same_arguments: true
+    },
+    scheduled_run: {
+      tool: nextAction.scheduled_run.recommended_next_tool,
+      same_arguments: true
+    },
+    trae_cn: {
+      next_step: "Call boss-recommend/start_recommend_pipeline_run or boss-recommend/run_recommend through the native MCP tool interface.",
+      never_use_terminal_fallback_after_prepare: true
+    },
+    forbidden_when_mcp_tools_are_available: nextAction.forbidden_fallbacks
   };
   return {
     status: "READY",
@@ -1585,7 +1614,8 @@ export function prepareRecommendPipelineRunTool({ workspaceRoot = "", args = {}
     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.",
+    agent_guidance: agentGuidance,
+    message: "READY only means the payload passed validation; prepare_recommend_pipeline_run did not start a run. This response proves the MCP server is available. To start now, call the native MCP tool start_recommend_pipeline_run or run_recommend with the same arguments. Do not call prepare_recommend_pipeline_run again, and do not use terminal, shell, CLI detached fallback, or manual JSON-RPC when MCP tools are available.",
     review: parsed.review,
     post_action: {
       requested: normalized.postAction,