@reconcrap/boss-recommend-mcp 2.1.1 → 2.1.3

package/README.md

@@ -7,6 +7,68 @@ Boss 推荐 / 搜索 / 聊天筛选 MCP（stdio）服务。
 - npm: `@reconcrap/boss-recommend-mcp`（https://www.npmjs.com/package/@reconcrap/boss-recommend-mcp）
 - GitHub: `reconcrap-cpu/boss-recommend-mcp`（https://github.com/reconcrap-cpu/boss-recommend-mcp）
 
+## AI harness install entrypoint
+
+如果用户只把这个 GitHub 链接交给 Codex、Claude Code、Cursor、OpenClaw、QClaw、Trae 等 AI harness，并要求“安装这个工具”，请优先执行本节，而不是直接在 macOS 上裸跑 `npm install -g`。
+
+AI harness 不能只完成 npm 安装就结束。安装流程还必须帮助用户完成必填 LLM 配置；如果用户没有提前提供，请向用户索取：
+
+- LLM base URL（默认可用 `https://api.openai.com/v1`）
+- LLM API key
+- LLM model（默认可用 `gpt-4.1-mini`）
+
+然后写入配置：
+
+```bash
+boss-recommend-mcp config set --base-url <baseUrl> --api-key <apiKey> --model <model> --thinking-level low
+boss-recommend-mcp doctor
+```
+
+如果用户用 macOS bootstrap，它会自动尝试交互式询问并写入这些字段。非交互式 AI harness 如果拿不到用户输入，应暂停并询问用户上述三项，不要把安装标记为完成。
+
+macOS 首次安装推荐使用仓库里的 nvm bootstrap。它会把 Node/npm/global packages 放到用户目录，避免首次安装或后续升级时出现：
+
+```text
+EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@reconcrap'
+```
+
+这是 npm global prefix 权限问题，不是 `boss-recommend-mcp` 包内部创建目录失败。
+
+macOS 一键安装：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash
+```
+
+如果要直接配置某个宿主：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent openclaw
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent qclaw
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent trae-cn
+```
+
+安装后，未来升级只需要在同一个 nvm shell 里运行：
+
+```bash
+npm -g i @reconcrap/boss-recommend-mcp@latest
+boss-recommend-mcp where
+```
+
+如果升级前 `npm config get prefix` 返回 `/usr/local`，说明当前 shell 没有使用 nvm Node；请先重新加载 nvm，不要使用 `sudo npm install -g`。
+
+macOS bootstrap 会执行 `boss-recommend-mcp install --mcp-launch global-wrapper`。该模式会把 MCP 宿主配置为启动稳定 wrapper：`~/.boss-recommend-mcp/bin/boss-recommend-mcp-mcp-server`。这个 wrapper 每次启动时都会调用当前全局 `boss-recommend-mcp start`，因此后续 `npm -g i @reconcrap/boss-recommend-mcp@latest` 会更新 MCP 宿主实际运行的版本，不需要每次升级后重写 MCP 配置。
+
+如果 AI harness 已经从用户处拿到 LLM 信息，可以非交互式传给 bootstrap：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh \
+  | BOSS_RECOMMEND_BASE_URL="https://api.openai.com/v1" \
+    BOSS_RECOMMEND_API_KEY="<apiKey>" \
+    BOSS_RECOMMEND_MODEL="gpt-4.1-mini" \
+    bash -s -- --agent openclaw
+```
+
 2.0.0 是 CDP-only 重写版本：活跃浏览器路径只允许 Chrome DevTools Protocol 的 `DOM` / `Input` / `Page` / `Network` / `Accessibility` 等域，不使用 `Runtime.evaluate` 或页面 JS。包内保留 recommend、search/recruit、chat 三条域服务，并共享浏览器、生命周期、筛选、CV 获取、无限滚动、自愈与 CSV 报告层。
 
 安装 `boss-recommend-mcp` 后可以直接：
@@ -21,6 +83,8 @@ MCP 工具：
 
 - `list_recommend_jobs`（只读读取推荐页岗位下拉框，返回可直接用于 cron/一次性任务的 `job_names`）
 - `prepare_recommend_pipeline_run`（只校验完整 payload 是否已可用于 cron/一次性任务；不启动筛选，返回 `READY + cron_ready=true` 后才应创建 cron）
+- `schedule_recommend_pipeline_run`（创建 package-owned 定时任务；保存已 READY 的完整 payload，启动 detached scheduler，到点后直接调用 `start_recommend_pipeline_run`）
+- `get_recommend_scheduled_run`（查询 package-owned 定时任务；到点后会显示内层 `run_id` 和 run 快照）
 - `start_recommend_pipeline_run`（异步启动；同样先经过前置门禁，通过后返回 run_id）
 - `get_recommend_pipeline_run`（轮询 run_id 状态）
 - `cancel_recommend_pipeline_run`（取消运行中任务）
@@ -58,15 +122,18 @@ 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
+boss-recommend-mcp 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
+boss-recommend-mcp schedule-status --schedule-id <schedule_id>
 ```
 
-只有输出 `status: "READY"` 且 `cron_ready: true` 后，才把同一份 payload 写入 cron 并在到点时调用 `start_recommend_pipeline_run` / `boss-recommend-mcp run --detached`。如果设置阶段返回 `BOSS_LOGIN_REQUIRED`、`NEED_INPUT` 或 `NEED_CONFIRMATION`，先让用户登录或补齐确认，不要创建 cron。
+只有 `prepare-run` 输出 `status: "READY"` 且 `cron_ready: true` 后，才继续调用 `schedule-run`。只有 `schedule-run` 输出 `status: "SCHEDULED"` 且带有 `schedule_id` 后，才算定时任务真的创建成功。不要让外部 AI harness 自己拼 `/tmp/*.log` shell cron 或未来对话提醒；那类 cron 容易丢失 JSON/file 参数并在到点后重新卡确认门禁。
 
 状态机：
 
 - `NEED_INPUT`
 - `NEED_CONFIRMATION`
 - `READY`（仅准备工具）
+- `SCHEDULED`（仅定时工具）
 - `COMPLETED`
 - `FAILED`
 
@@ -125,6 +192,13 @@ npm install -g @reconcrap/boss-recommend-mcp@latest
 boss-recommend-mcp start
 ```
 
+macOS 首次安装如果没有确认 npm prefix 在用户目录，优先使用本文开头的 `scripts/install-macos.sh`。完成 bootstrap 后，后续升级仍然使用同一个 npm 命令：
+
+```bash
+npm -g i @reconcrap/boss-recommend-mcp@latest
+boss-recommend-mcp where
+```
+
 无需安装（npx 直接运行）：
 
 ```bash
@@ -150,7 +224,8 @@ node src/cli.js start
 如果检测到 legacy Boss server entries，installer 会：
 
 - 保留非 Boss MCP server。
-- 写入统一 server：`boss-recommend -> npx -y @reconcrap/boss-recommend-mcp@<installed-version> start`
+- 默认写入统一 server：`boss-recommend -> npx -y @reconcrap/boss-recommend-mcp@<installed-version> start`
+- 如果传入 `--mcp-launch global-wrapper`，写入升级稳定入口：`boss-recommend -> ~/.boss-recommend-mcp/bin/boss-recommend-mcp-mcp-server`。该 wrapper 会加载 `~/.nvm/nvm.sh` 并执行当前全局 `boss-recommend-mcp start`，适合 macOS 上通过 `npm -g i @reconcrap/boss-recommend-mcp@latest` 持续升级。
 - 从同一个 `mcp.json` 删除旧 `boss-recruit-mcp`、standalone `boss-chat`、旧本地 Boss repo 路径，避免 agent 继续调用 legacy 包。
 - 在原文件旁生成 `mcp.json.boss-mcp-migration-*.bak`。
 - 同步外部 skills 目录里的 `boss-recommend-pipeline`、`boss-recruit-pipeline`、`boss-chat`。
@@ -166,6 +241,14 @@ boss-recommend-mcp doctor --agent openclaw
 boss-recommend-mcp doctor --agent qclaw
 ```
 
+macOS 上如果希望 MCP 宿主总是使用全局 npm 最新安装版本：
+
+```bash
+boss-recommend-mcp install --mcp-launch global-wrapper --agent openclaw
+boss-recommend-mcp install --mcp-launch global-wrapper --agent qclaw
+boss-recommend-mcp install --mcp-launch global-wrapper --agent trae-cn
+```
+
 自定义路径：
 
 ```bash
@@ -191,6 +274,16 @@ npx -y @reconcrap/boss-recommend-mcp@latest run --detached --instruction-file bo
 
 `--detached` 会让父进程输出 `ACCEPTED + run_id` 后退出，子进程继续持有 Chrome DevTools 会话并执行长任务。岗位发现可以使用只读 CLI：
 
+如果是稍后启动/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 schedule-status --schedule-id <schedule_id>
+```
+
+`schedule-run` 会保存同一份已验证 payload 并启动 detached scheduler worker；到点后 worker 会直接调用包内 `start_recommend_pipeline_run`，不会重新让 AI harness 拼参数。
+
 ```bash
 npx -y @reconcrap/boss-recommend-mcp@latest list-jobs --slow-live --port 9222
 # 源码模式（GitHub clone 后）
@@ -385,6 +478,7 @@ Trae-CN / 长对话防循环建议：
 
 - `start_recommend_pipeline_run` 为异步入口，但不会跳过同步确认流程。
 - `prepare_recommend_pipeline_run` / `boss-recommend-mcp prepare-run` 用于 cron 设置阶段；它不启动筛选，只确认 payload 已经不需要到点后再问用户。
+- `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` 覆盖）。
 - 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.1",
+  "version": "2.1.3",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",
@@ -82,6 +82,7 @@
     "bin",
     "config/screening-config.example.json",
     "skills",
+    "scripts/install-macos.sh",
     "scripts/postinstall.cjs",
     "src/core",
     "src/domains",
@@ -92,6 +93,7 @@
     "src/index.js",
     "src/parser.js",
     "src/recommend-mcp.js",
+    "src/recommend-scheduler.js",
     "src/recruit-mcp.js",
     "src/run-state.js",
     "README.md"

package/scripts/install-macos.sh

@@ -0,0 +1,280 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="@reconcrap/boss-recommend-mcp"
+DEFAULT_NODE_VERSION="${BOSS_RECOMMEND_NODE_VERSION:-22}"
+DEFAULT_NVM_VERSION="${BOSS_RECOMMEND_NVM_VERSION:-v0.40.4}"
+
+NODE_VERSION="$DEFAULT_NODE_VERSION"
+NVM_VERSION="$DEFAULT_NVM_VERSION"
+AGENT="${BOSS_RECOMMEND_AGENT:-}"
+DRY_RUN=0
+SKIP_DOCTOR=0
+SKIP_LLM_CONFIG=0
+BASE_URL="${BOSS_RECOMMEND_BASE_URL:-https://api.openai.com/v1}"
+API_KEY="${BOSS_RECOMMEND_API_KEY:-}"
+MODEL="${BOSS_RECOMMEND_MODEL:-gpt-4.1-mini}"
+THINKING_LEVEL="${BOSS_RECOMMEND_THINKING_LEVEL:-low}"
+GREETING_MESSAGE="${BOSS_RECOMMEND_GREETING_MESSAGE:-Hi同学，能麻烦发下简历吗？}"
+
+usage() {
+  cat <<'EOF'
+Install boss-recommend-mcp on macOS with nvm-backed npm globals.
+
+Usage:
+  install-macos.sh [--agent <agent|all>] [--node-version <version>] [--nvm-version <tag>] [--dry-run] [--skip-doctor] [--skip-llm-config]
+
+Examples:
+  curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash
+  curl -fsSL https://raw.githubusercontent.com/reconcrap-cpu/boss-recommend-mcp/main/scripts/install-macos.sh | bash -s -- --agent openclaw
+
+Supported agents: cursor, trae, trae-cn, claude, openclaw, qclaw, all
+
+LLM config can be supplied non-interactively with:
+  BOSS_RECOMMEND_BASE_URL, BOSS_RECOMMEND_API_KEY, BOSS_RECOMMEND_MODEL,
+  BOSS_RECOMMEND_THINKING_LEVEL, BOSS_RECOMMEND_GREETING_MESSAGE
+EOF
+}
+
+log() {
+  printf '%s\n' "[boss-recommend-mcp] $*"
+}
+
+die() {
+  printf '%s\n' "[boss-recommend-mcp] ERROR: $*" >&2
+  exit 1
+}
+
+run() {
+  log "+ $*"
+  if [ "$DRY_RUN" -eq 0 ]; then
+    "$@"
+  fi
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --agent)
+      [ "$#" -ge 2 ] || die "--agent requires a value"
+      AGENT="$2"
+      shift 2
+      ;;
+    --node-version)
+      [ "$#" -ge 2 ] || die "--node-version requires a value"
+      NODE_VERSION="$2"
+      shift 2
+      ;;
+    --nvm-version)
+      [ "$#" -ge 2 ] || die "--nvm-version requires a value"
+      NVM_VERSION="$2"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --skip-doctor)
+      SKIP_DOCTOR=1
+      shift
+      ;;
+    --skip-llm-config)
+      SKIP_LLM_CONFIG=1
+      shift
+      ;;
+    --base-url)
+      [ "$#" -ge 2 ] || die "--base-url requires a value"
+      BASE_URL="$2"
+      shift 2
+      ;;
+    --api-key)
+      [ "$#" -ge 2 ] || die "--api-key requires a value"
+      API_KEY="$2"
+      shift 2
+      ;;
+    --model)
+      [ "$#" -ge 2 ] || die "--model requires a value"
+      MODEL="$2"
+      shift 2
+      ;;
+    --thinking-level)
+      [ "$#" -ge 2 ] || die "--thinking-level requires a value"
+      THINKING_LEVEL="$2"
+      shift 2
+      ;;
+    --greeting-message)
+      [ "$#" -ge 2 ] || die "--greeting-message requires a value"
+      GREETING_MESSAGE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      die "Unknown option: $1"
+      ;;
+  esac
+done
+
+prompt_text() {
+  local label="$1"
+  local default_value="$2"
+  local secret="${3:-0}"
+  local value
+  if [ ! -r /dev/tty ]; then
+    return 1
+  fi
+  if [ "$secret" -eq 1 ]; then
+    printf '%s' "${label}: " > /dev/tty
+    IFS= read -r -s value < /dev/tty || return 1
+    printf '\n' > /dev/tty
+  elif [ -n "$default_value" ]; then
+    printf '%s' "${label} [${default_value}]: " > /dev/tty
+    IFS= read -r value < /dev/tty || return 1
+    if [ -z "$value" ]; then
+      value="$default_value"
+    fi
+  else
+    printf '%s' "${label}: " > /dev/tty
+    IFS= read -r value < /dev/tty || return 1
+  fi
+  printf '%s' "$value"
+}
+
+if [ "$(uname -s)" != "Darwin" ]; then
+  if [ "$DRY_RUN" -eq 1 ]; then
+    log "dry-run on non-macOS host; skipping platform enforcement"
+  else
+    die "This bootstrap script is for macOS. Use npm install -g ${PACKAGE_NAME}@latest on other platforms."
+  fi
+fi
+
+export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+
+load_nvm() {
+  if [ -s "$NVM_DIR/nvm.sh" ]; then
+    # shellcheck disable=SC1090
+    . "$NVM_DIR/nvm.sh"
+  elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+    export NVM_DIR="$HOME/.nvm"
+    # shellcheck disable=SC1091
+    . "$HOME/.nvm/nvm.sh"
+  fi
+}
+
+install_nvm() {
+  if command -v nvm >/dev/null 2>&1; then
+    return
+  fi
+  log "nvm was not found; installing ${NVM_VERSION} into ${NVM_DIR}"
+  if [ "$DRY_RUN" -eq 1 ]; then
+    log "+ curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh | bash"
+    return
+  fi
+  curl -fsSL "https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh" | bash
+  load_nvm
+  command -v nvm >/dev/null 2>&1 || die "nvm installed but is not available in this shell. Open a new terminal and rerun this script."
+}
+
+load_nvm
+install_nvm
+
+run nvm install "$NODE_VERSION"
+run nvm alias default "$NODE_VERSION"
+run nvm use "$NODE_VERSION"
+
+if [ "$DRY_RUN" -eq 0 ]; then
+  NODE_PATH="$(command -v node || true)"
+  NPM_PATH="$(command -v npm || true)"
+  NPM_PREFIX="$(npm config get prefix || true)"
+  log "node: ${NODE_PATH}"
+  log "npm: ${NPM_PATH}"
+  log "npm prefix: ${NPM_PREFIX}"
+
+  case "$NPM_PREFIX" in
+    /usr/local|/usr/local/*)
+      die "npm is still using /usr/local. Reload nvm and rerun this script; do not use sudo npm install -g."
+      ;;
+  esac
+  case "$NPM_PREFIX" in
+    "$NVM_DIR"/*)
+      ;;
+    *)
+      die "npm prefix is not under ${NVM_DIR}. Current prefix: ${NPM_PREFIX}"
+      ;;
+  esac
+else
+  log "+ verify: npm config get prefix must be under ${NVM_DIR}, not /usr/local"
+fi
+
+run npm -g i "${PACKAGE_NAME}@latest"
+run boss-recommend-mcp where
+
+INSTALL_ARGS=(install --mcp-launch global-wrapper)
+DOCTOR_ARGS=(doctor)
+if [ -n "$AGENT" ]; then
+  INSTALL_ARGS+=(--agent "$AGENT")
+  DOCTOR_ARGS+=(--agent "$AGENT")
+fi
+
+run boss-recommend-mcp "${INSTALL_ARGS[@]}"
+
+if [ "$SKIP_LLM_CONFIG" -eq 0 ]; then
+  log "LLM screening config is required before running candidate screening."
+  if [ "$DRY_RUN" -eq 0 ]; then
+    if [ -r /dev/tty ]; then
+      BASE_URL="$(prompt_text "LLM base URL" "$BASE_URL")"
+      MODEL="$(prompt_text "LLM model" "$MODEL")"
+      THINKING_LEVEL="$(prompt_text "LLM thinking level" "$THINKING_LEVEL")"
+      GREETING_MESSAGE="$(prompt_text "Greeting message for candidates" "$GREETING_MESSAGE")"
+      if [ -z "$API_KEY" ]; then
+        API_KEY="$(prompt_text "LLM API key (input hidden)" "" 1)"
+      fi
+    fi
+    if [ -z "$BASE_URL" ] || [ -z "$API_KEY" ] || [ -z "$MODEL" ]; then
+      cat >&2 <<EOF
+[boss-recommend-mcp] LLM config is still required.
+[boss-recommend-mcp] Ask the user for:
+  1. LLM base URL
+  2. LLM API key
+  3. LLM model name
+[boss-recommend-mcp] Then run:
+  boss-recommend-mcp config set --base-url <baseUrl> --api-key <apiKey> --model <model> --thinking-level ${THINKING_LEVEL}
+EOF
+      exit 2
+    fi
+  fi
+
+  CONFIG_ARGS=(config set --base-url "$BASE_URL" --api-key "$API_KEY" --model "$MODEL")
+  if [ -n "$THINKING_LEVEL" ]; then
+    CONFIG_ARGS+=(--thinking-level "$THINKING_LEVEL")
+  fi
+  if [ -n "$GREETING_MESSAGE" ]; then
+    CONFIG_ARGS+=(--greeting-message "$GREETING_MESSAGE")
+  fi
+
+  if [ "$DRY_RUN" -eq 1 ]; then
+    log "+ boss-recommend-mcp config set --base-url ${BASE_URL:-<baseUrl>} --api-key <hidden> --model ${MODEL:-<model>} --thinking-level ${THINKING_LEVEL:-<level>}"
+  else
+    log "+ boss-recommend-mcp config set --base-url ${BASE_URL} --api-key <hidden> --model ${MODEL}"
+    boss-recommend-mcp "${CONFIG_ARGS[@]}"
+  fi
+else
+  log "Skipping LLM config because --skip-llm-config was provided."
+fi
+
+if [ "$SKIP_DOCTOR" -eq 0 ]; then
+  log "+ boss-recommend-mcp ${DOCTOR_ARGS[*]}"
+  if [ "$DRY_RUN" -eq 0 ]; then
+    if ! boss-recommend-mcp "${DOCTOR_ARGS[@]}"; then
+      log "doctor reported follow-up work. The npm package install still completed."
+    fi
+  fi
+fi
+
+cat <<EOF
+[boss-recommend-mcp] install complete.
+[boss-recommend-mcp] Future upgrades:
+  npm -g i ${PACKAGE_NAME}@latest
+  boss-recommend-mcp where
+EOF

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

@@ -94,8 +94,14 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - 限制：只读岗位列表，不启动筛选任务；若返回 `BOSS_LOGIN_REQUIRED`，必须让用户在自动打开的 Chrome 完成登录后重试，本次 cron 不得创建。
 - Cron 准备工具：`prepare_recommend_pipeline_run`
   - 用途：只校验参数是否已可用于 cron / 一次性任务，不启动筛选任务。
-  - 要求：只有返回 `status=READY` 且 `cron_ready=true` 后，才允许创建 cron。
+  - 要求：只有返回 `status=READY` 且 `cron_ready=true` 后，才允许继续创建定时任务。
   - 若返回 `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`。
+  - 必填：同 `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`
+  - 用途：用户问“任务是否启动/进度”时，先查 `schedule_id`。若到点后已启动，会返回内层 `run_id` 和 run 快照。
 - 主工具：`start_recommend_pipeline_run`
 - 必填：`instruction`
 - 关键输入：
@@ -119,16 +125,30 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 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/登录异常，应作为运行失败处理，不得再向用户追问参数。
+5. 调用 `prepare_recommend_pipeline_run` 传入将来要执行的完整 payload；只有 `READY + cron_ready=true` 才能继续。
+6. 立即调用 `schedule_recommend_pipeline_run`，传入同一份完整 payload 和 `schedule_delay_minutes` / `schedule_run_at`。禁止让 OpenClaw 自己写 `/tmp/*.log` shell cron、自然语言提醒、或未来对话回调来代替此工具。
+7. 只有拿到 `SCHEDULED + schedule_id` 后才告诉用户定时任务已创建。回复必须包含 `schedule_id`，而不是只说“10 分钟后会启动”。
+8. 到点后由 package-owned detached scheduler 启动；若 Chrome/登录异常，应作为 schedule/run 失败处理，不得再向用户追问参数。
 
-Shell-only OpenClaw/QClaw cron 设置同样先运行：
+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
 ```
 
-仅当上述命令输出 `READY` 且 `cron_ready=true` 后，才把对应的 detached `run` 命令写入 cron。
+仅当上述命令输出 `READY` 且 `cron_ready=true` 后，才允许继续创建定时任务。
+
+然后必须用 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
+```
+
+用户查询时：
+
+```powershell
+npx -y @reconcrap/boss-recommend-mcp@latest schedule-status --schedule-id <schedule_id>
+```
 
 ## Async Run Policy
 
@@ -173,14 +193,15 @@ npx -y @reconcrap/boss-recommend-mcp@latest prepare-run --instruction-file .\bos
 推荐做法：
 
 1. 将锁定的用户原文写入 instruction 文件，将已确认参数写入 `overrides` 与 `confirmation` JSON 文件。
-2. 先用 `prepare-run` 校验完整 payload 已 cron-ready；未返回 `READY + cron_ready=true` 不得创建 cron 或启动 run。
-3. 用 detached CLI 启动，让父命令返回启动证据，子进程继续持有 CDP 会话：
+2. 先用 `prepare-run` 校验完整 payload 已 cron-ready；未返回 `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
 ```
 
-4. 若返回 `ACCEPTED + run_id`，即任务已启动；记录 `run_id/stdout_path/stderr_path`。若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`，说明 cron 设置阶段漏掉了准备门禁，应回到 `prepare-run` 补齐，不能在到点后继续问用户确认。
+4. 若用户要“稍后/cron/定时启动”，用 `schedule-run`，不是 `run --detached`。若 `schedule-run` 未返回 `SCHEDULED + schedule_id`，不得告诉用户定时任务已创建。
+5. 若即时 `run --detached` 返回 `ACCEPTED + run_id`，即任务已启动；记录 `run_id/stdout_path/stderr_path`。若返回 `NEED_INPUT` 或 `NEED_CONFIRMATION`，说明设置阶段漏掉了准备门禁，应回到 `prepare-run` 补齐，不能在到点后继续问用户确认。
 
 兼容路径：