@reconcrap/boss-recruit-mcp 1.0.15 → 1.0.17

package/README.md

@@ -25,10 +25,12 @@ npx @reconcrap/boss-recruit-mcp install
 - 安装 Codex skill 到 `$CODEX_HOME/skills/boss-recruit-pipeline`
 - 初始化用户配置到 `$CODEX_HOME/boss-recruit-mcp/screening-config.json`
 - 生成通用 MCP 配置模板到 `$CODEX_HOME/boss-recruit-mcp/agent-mcp-configs`
+- 自动尝试写入已检测到的外部 agent MCP 配置（含 Trae / trae-cn / Cursor / Claude / OpenClaw）
+- 自动尝试把 skill 镜像到已检测到的外部 agent skills 目录
 - 包内自带 `boss-search-cli` 与 `boss-screen-cli` 运行时文件，无需额外目录结构
 - 不包含 `favorite-calibration.json`，首次使用前需要自行校准生成
 
-## 跨 Agent 快速接入（Cursor / Trae / Claude Code / OpenClaw）
+## 跨 Agent 快速接入（Cursor / Trae / trae-cn / Claude Code / OpenClaw）
 
 生成 MCP 配置模板：
 
@@ -58,6 +60,7 @@ $CODEX_HOME/boss-recruit-mcp/agent-mcp-configs
 boss-recruit-mcp mcp-config --client cursor
 boss-recruit-mcp mcp-config --client claudecode
 boss-recruit-mcp mcp-config --client trae
+boss-recruit-mcp mcp-config --client trae-cn
 boss-recruit-mcp mcp-config --client openclaw
 boss-recruit-mcp mcp-config --client generic
 ```
@@ -73,6 +76,13 @@ boss-recruit-mcp mcp-config --client generic
 boss-recruit-mcp mcp-config --client generic --command boss-recruit-mcp --args-json "[\"start\"]"
 ```
 
+可选环境变量（用于跨 agent 自动配置）：
+
+```bash
+BOSS_RECRUIT_MCP_CONFIG_TARGETS   # JSON 数组或系统 path 分隔路径列表，指定额外 mcp.json 目标文件
+BOSS_RECRUIT_EXTERNAL_SKILL_DIRS  # JSON 数组或系统 path 分隔路径列表，指定额外 skills 根目录
+```
+
 ## 准备配置
 
 1. 初始化后编辑用户配置文件：
@@ -224,6 +234,7 @@ boss-recruit-mcp doctor --port <port>
 - 确认后自动执行：搜索 CLI -> 点击搜索 -> 勾选“过滤近14天查看”（按轮次规则） -> 筛选 CLI
 - 返回摘要：目标数、已处理、通过数、耗时、输出 CSV
 - 执行前会先做本地依赖预检查，若目录 / 入口 / 配置文件缺失则返回 `PIPELINE_PREFLIGHT_FAILED`
+- preflight 会检查 Node.js 与 npm 依赖（`chrome-remote-interface` / `ws`）；失败时会返回 `diagnostics.recovery`（含有序修复步骤与 `agent_prompt`）
 - 若缺少 `favorite-calibration.json`，会返回 `CALIBRATION_REQUIRED`
 - 若某轮搜索返回可筛选候选人但筛选 `processed_count` 非法或为 0，会先导出当前累计 CSV，再返回 `SCREEN_NO_PROGRESS`
 - 若当前运行环境不允许启动子进程，会返回更明确的权限错误码而不是笼统失败

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recruit-mcp",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Unified MCP pipeline for boss-search-cli and boss-screen-cli",
   "keywords": [
     "boss",

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

@@ -289,6 +289,8 @@ description: "Use when users ask to recruit candidates on Boss Zhipin via the bo
 - 不要把底层 stderr 原样大段贴给用户，只提炼关键错误和下一步。
 - 如果失败原因明显是环境问题，要直接说明不是用户输入有误。
 - 如果工具已经返回 `diagnostics.checks`，优先基于这些检查项生成排障建议。
+- 如果返回 `PIPELINE_PREFLIGHT_FAILED` 且含 `diagnostics.recovery.agent_prompt`，优先把该提示词直接交给 AI agent 自动修复依赖。
+- 自动修复依赖必须严格串行：先 Node.js，再 npm 依赖；若涉及 Python / Pillow，先 Python 再 Pillow。
 - 如果工具返回 `output_csv`，在摘要里给出路径，避免重复解释内部流程。
 - 如果端口还没确认，必须先问用户“是否使用推荐的 `9222`，还是你已经有别的远程调试端口”，不能直接把 `9222` 当成已确认值。
 - 用户确认端口后，先执行一次 `boss-recruit-mcp set-port --port <port>`，让后续 `doctor / launch-chrome / calibrate / run` 自动复用同一端口。

package/src/adapters.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import CDP from "chrome-remote-interface";
 const currentFilePath = fileURLToPath(import.meta.url);
@@ -156,6 +156,117 @@ function runProcess({ command, args, cwd, timeoutMs }) {
   });
 }
 
+function runProcessSync({ command, args, cwd }) {
+  try {
+    const result = spawnSync(command, args, {
+      cwd,
+      windowsHide: true,
+      shell: false,
+      env: process.env,
+      encoding: "utf8"
+    });
+    const stdout = String(result.stdout || "").trim();
+    const stderr = String(result.stderr || "").trim();
+    return {
+      ok: result.status === 0,
+      status: result.status,
+      stdout,
+      stderr,
+      output: [stdout, stderr].filter(Boolean).join("\n").trim(),
+      error_code: result.error?.code || null,
+      error_message: result.error?.message || null
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: -1,
+      stdout: "",
+      stderr: "",
+      output: "",
+      error_code: error.code || "SPAWN_FAILED",
+      error_message: error.message || String(error)
+    };
+  }
+}
+
+function parseMajorVersion(raw) {
+  const match = String(raw || "").match(/v?(\d+)(?:\.\d+){0,2}/);
+  if (!match) return null;
+  const major = Number.parseInt(match[1], 10);
+  return Number.isFinite(major) ? major : null;
+}
+
+function buildNodeCommandCheck() {
+  const probe = runProcessSync({
+    command: "node",
+    args: ["--version"]
+  });
+  const major = parseMajorVersion(probe.output);
+  const versionOk = Number.isInteger(major) && major >= 18;
+  return {
+    key: "node_cli",
+    ok: probe.ok && versionOk,
+    path: "node --version",
+    message: probe.ok
+      ? (versionOk
+        ? `Node 命令可用 (${probe.output || "unknown version"})`
+        : `Node 版本过低 (${probe.output || "unknown version"})，要求 >= 18`)
+      : `未找到 node 命令，请先安装 Node.js >= 18。${probe.error_message ? ` (${probe.error_message})` : ""}`
+  };
+}
+
+function buildNodePackageCheck({ key, moduleName, cwd, missingMessage }) {
+  if (!cwd || !pathExists(cwd)) {
+    return {
+      key,
+      ok: false,
+      path: moduleName,
+      module: moduleName,
+      install_cwd: null,
+      message: missingMessage
+    };
+  }
+  const probe = runProcessSync({
+    command: "node",
+    args: ["-e", `require.resolve(${JSON.stringify(moduleName)});`],
+    cwd
+  });
+  return {
+    key,
+    ok: probe.ok,
+    path: moduleName,
+    module: moduleName,
+    install_cwd: cwd,
+    message: probe.ok
+      ? `${moduleName} npm 依赖可用`
+      : `缺少 npm 依赖 ${moduleName}，请在 boss-recruit-mcp 目录执行 npm install。`
+  };
+}
+
+function buildRuntimeDependencyChecks({ searchDir, screenDir }) {
+  return [
+    buildNodeCommandCheck(),
+    buildNodePackageCheck({
+      key: "npm_dep_chrome_remote_interface_search",
+      moduleName: "chrome-remote-interface",
+      cwd: searchDir,
+      missingMessage: "无法校验 chrome-remote-interface：boss-search-cli 目录不存在。"
+    }),
+    buildNodePackageCheck({
+      key: "npm_dep_chrome_remote_interface_screen",
+      moduleName: "chrome-remote-interface",
+      cwd: screenDir,
+      missingMessage: "无法校验 chrome-remote-interface：boss-screen-cli 目录不存在。"
+    }),
+    buildNodePackageCheck({
+      key: "npm_dep_ws",
+      moduleName: "ws",
+      cwd: screenDir,
+      missingMessage: "无法校验 ws：boss-screen-cli 目录不存在。"
+    })
+  ];
+}
+
 function parseSearchCount(output) {
   const m = output.match(/找到\s*(\d+)\s*个候选人/);
   if (!m) return null;
@@ -351,13 +462,18 @@ export function runPipelinePreflight(workspaceRoot) {
       message: "favorite-calibration.json 不存在（可选，仅在旧页面回退点击时需要）"
     }
   ];
+  checks.push(...buildRuntimeDependencyChecks({ searchDir, screenDir }));
 
   const requiredCheckKeys = new Set([
     "search_cli_dir",
     "search_cli_entry",
     "screen_cli_dir",
     "screen_cli_entry",
-    "screen_config"
+    "screen_config",
+    "node_cli",
+    "npm_dep_chrome_remote_interface_search",
+    "npm_dep_chrome_remote_interface_screen",
+    "npm_dep_ws"
   ]);
 
   return {

package/src/cli.js

@@ -28,14 +28,16 @@ const SUPPORTED_MCP_CLIENTS = ["generic", "cursor", "trae", "claudecode", "openc
 const DEFAULT_MCP_SERVER_NAME = "boss-recruit";
 const DEFAULT_MCP_COMMAND = "npx";
 const DEFAULT_MCP_ARGS = ["-y", "@reconcrap/boss-recruit-mcp@latest", "start"];
-const AUTO_SYNC_SKIP_COMMANDS = new Set([
-  "install",
-  "install-skill",
-  "where",
-  "help",
-  "--help",
-  "-h"
-]);
+const AUTO_SYNC_SKIP_COMMANDS = new Set([
+  "install",
+  "install-skill",
+  "where",
+  "help",
+  "--help",
+  "-h"
+]);
+const EXTERNAL_MCP_TARGETS_ENV = "BOSS_RECRUIT_MCP_CONFIG_TARGETS";
+const EXTERNAL_SKILL_DIRS_ENV = "BOSS_RECRUIT_EXTERNAL_SKILL_DIRS";
 
 function getPackageVersion() {
   try {
@@ -58,13 +60,46 @@ function getCodexHome() {
     : path.join(os.homedir(), ".codex");
 }
 
-function ensureDir(targetPath) {
-  fs.mkdirSync(targetPath, { recursive: true });
-}
-
-function getDesktopDir() {
-  return path.join(os.homedir(), "Desktop");
-}
+function ensureDir(targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true });
+}
+
+function pathExists(targetPath) {
+  try {
+    return fs.existsSync(targetPath);
+  } catch {
+    return false;
+  }
+}
+
+function readJsonObjectFileSafe(filePath) {
+  if (!pathExists(filePath)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // Fallback below.
+  }
+  return {};
+}
+
+function dedupePaths(items) {
+  const result = [];
+  const seen = new Set();
+  for (const item of items || []) {
+    const resolved = path.resolve(String(item || ""));
+    if (!resolved || seen.has(resolved)) continue;
+    seen.add(resolved);
+    result.push(resolved);
+  }
+  return result;
+}
+
+function getDesktopDir() {
+  return path.join(os.homedir(), "Desktop");
+}
 
 function getUserConfigPath() {
   return path.join(getCodexHome(), "boss-recruit-mcp", "screening-config.json");
@@ -146,12 +181,13 @@ function parseStringArrayOption(value, label) {
   return parsed;
 }
 
-function normalizeMcpClientName(value) {
-  const raw = String(value || "").trim().toLowerCase();
-  if (!raw) return "";
-  if (raw === "claude-code") return "claudecode";
-  return raw;
-}
+function normalizeMcpClientName(value) {
+  const raw = String(value || "").trim().toLowerCase();
+  if (!raw) return "";
+  if (raw === "claude-code") return "claudecode";
+  if (raw === "trae-cn") return "trae";
+  return raw;
+}
 
 function parseMcpClientTargets(rawValue) {
   if (!rawValue) return SUPPORTED_MCP_CLIENTS.slice();
@@ -214,7 +250,7 @@ function buildMcpConfigFileContent(options = {}) {
   };
 }
 
-function writeMcpConfigFiles(options = {}) {
+function writeMcpConfigFiles(options = {}) {
   const clients = parseMcpClientTargets(options.client);
   const outputDir = getAgentConfigOutputDir(options);
   ensureDir(outputDir);
@@ -227,8 +263,142 @@ function writeMcpConfigFiles(options = {}) {
     files.push({ client, file: filePath });
   }
 
-  return { outputDir, files };
-}
+  return { outputDir, files };
+}
+
+function parsePathListFromEnv(raw) {
+  if (!raw) return [];
+  const text = String(raw).trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      return dedupePaths(parsed.filter(Boolean));
+    }
+  } catch {
+    // Fallback to delimiter split.
+  }
+  return dedupePaths(
+    text
+      .split(path.delimiter)
+      .map((item) => item.trim())
+      .filter(Boolean)
+  );
+}
+
+function getKnownExternalMcpConfigPaths() {
+  const home = os.homedir();
+  const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+  return dedupePaths([
+    path.join(appData, "Cursor", "User", "mcp.json"),
+    path.join(appData, "Trae", "User", "mcp.json"),
+    path.join(appData, "Trae CN", "User", "mcp.json"),
+    path.join(home, ".trae", "mcp.json"),
+    path.join(home, ".trae-cn", "mcp.json"),
+    path.join(home, ".claude", "mcp.json"),
+    path.join(home, ".openclaw", "mcp.json")
+  ]);
+}
+
+function resolveExternalMcpConfigTargets() {
+  const fromEnv = parsePathListFromEnv(process.env[EXTERNAL_MCP_TARGETS_ENV]);
+  const known = getKnownExternalMcpConfigPaths().filter((filePath) => {
+    if (pathExists(filePath)) return true;
+    return pathExists(path.dirname(filePath));
+  });
+  return dedupePaths([...fromEnv, ...known]);
+}
+
+function mergeMcpServerConfigFile(filePath, options = {}) {
+  const nextConfig = buildMcpConfigFileContent(options);
+  const serverName = Object.keys(nextConfig.mcpServers || {})[0] || DEFAULT_MCP_SERVER_NAME;
+  const launchConfig = nextConfig.mcpServers?.[serverName] || buildMcpLaunchConfig(options);
+  const current = readJsonObjectFileSafe(filePath);
+  const existingServers =
+    current?.mcpServers && typeof current.mcpServers === "object" && !Array.isArray(current.mcpServers)
+      ? current.mcpServers
+      : {};
+  const existingEntry = existingServers[serverName];
+  const merged = {
+    ...current,
+    mcpServers: {
+      ...existingServers,
+      [serverName]: launchConfig
+    }
+  };
+
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf8");
+  const updated = JSON.stringify(existingEntry || null) !== JSON.stringify(launchConfig);
+  return {
+    file: filePath,
+    server: serverName,
+    updated
+  };
+}
+
+function installExternalMcpConfigs(options = {}) {
+  const targets = resolveExternalMcpConfigTargets();
+  const applied = [];
+  const skipped = [];
+  for (const target of targets) {
+    try {
+      const existed = pathExists(target);
+      const merged = mergeMcpServerConfigFile(target, options);
+      applied.push({
+        file: target,
+        server: merged.server,
+        created: !existed,
+        updated: merged.updated
+      });
+    } catch (error) {
+      skipped.push({
+        file: target,
+        reason: error.message
+      });
+    }
+  }
+  return { targets, applied, skipped };
+}
+
+function getKnownExternalSkillBaseDirs() {
+  const home = os.homedir();
+  const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+  return dedupePaths([
+    path.join(home, ".cursor", "skills"),
+    path.join(home, ".trae", "skills"),
+    path.join(home, ".trae-cn", "skills"),
+    path.join(home, ".claude", "skills"),
+    path.join(home, ".openclaw", "skills"),
+    path.join(appData, "Cursor", "User", "skills"),
+    path.join(appData, "Trae", "User", "skills"),
+    path.join(appData, "Trae CN", "User", "skills"),
+    path.join(appData, "OpenClaw", "User", "skills")
+  ]);
+}
+
+function resolveExternalSkillBaseDirs() {
+  const fromEnv = parsePathListFromEnv(process.env[EXTERNAL_SKILL_DIRS_ENV]);
+  const known = getKnownExternalSkillBaseDirs().filter((dirPath) => pathExists(dirPath));
+  return dedupePaths([...fromEnv, ...known]);
+}
+
+function mirrorSkillToExternalDirs() {
+  const baseDirs = resolveExternalSkillBaseDirs();
+  const mirrored = [];
+  const skipped = [];
+  for (const baseDir of baseDirs) {
+    try {
+      const targetDir = path.join(baseDir, skillName);
+      ensureDir(path.dirname(targetDir));
+      fs.cpSync(skillSourceDir, targetDir, { recursive: true, force: true });
+      mirrored.push({ base_dir: baseDir, target_dir: targetDir });
+    } catch (error) {
+      skipped.push({ base_dir: baseDir, reason: error.message });
+    }
+  }
+  return { baseDirs, mirrored, skipped };
+}
 
 function readTextFile(filePath, label) {
   const resolved = path.resolve(String(filePath));
@@ -909,7 +1079,7 @@ async function launchChrome(options) {
   };
 }
 
-function printHelp() {
+function printHelp() {
   console.log("boss-recruit-mcp");
   console.log("");
   console.log("Usage:");
@@ -920,7 +1090,7 @@ function printHelp() {
   console.log("  boss-recruit-mcp install-skill Install only the Codex skill");
   console.log("  boss-recruit-mcp init-config  Create ~/.codex/boss-recruit-mcp/screening-config.json if missing");
   console.log("  boss-recruit-mcp set-port     Persist preferred Chrome debug port to active screening-config");
-  console.log("  boss-recruit-mcp mcp-config   Generate MCP config JSON for Cursor/Trae/Claude Code/OpenClaw");
+  console.log("  boss-recruit-mcp mcp-config   Generate MCP config JSON for Cursor/Trae(含 trae-cn)/Claude Code/OpenClaw");
   console.log("  boss-recruit-mcp doctor       Check config, calibration, and runtime prerequisites");
   console.log("  boss-recruit-mcp calibrate    Auto-open Boss search page, then run favorite-button calibration");
   console.log("  boss-recruit-mcp launch-chrome Reuse existing Chrome debug instance when possible; otherwise launch one, open Boss search, and check login state");
@@ -972,22 +1142,41 @@ function printMcpConfig(options = {}) {
   console.log("2. Merge its mcpServers block into that client's MCP config.");
 }
 
-function installAll() {
-  const skillTarget = installSkill();
-  const configResult = ensureUserConfig();
-  const mcpTemplateResult = writeMcpConfigFiles({ client: "all" });
-  console.log(`Skill installed to: ${skillTarget}`);
-  if (configResult.created) {
-    console.log(`Config template created at: ${configResult.path}`);
-  } else {
-    console.log(`Config already exists at: ${configResult.path}`);
+function installAll() {
+  const skillTarget = installSkill();
+  const configResult = ensureUserConfig();
+  const mcpTemplateResult = writeMcpConfigFiles({ client: "all" });
+  const externalMcpResult = installExternalMcpConfigs({});
+  const externalSkillResult = mirrorSkillToExternalDirs();
+  console.log(`Skill installed to: ${skillTarget}`);
+  if (configResult.created) {
+    console.log(`Config template created at: ${configResult.path}`);
+  } else {
+    console.log(`Config already exists at: ${configResult.path}`);
   }
   console.log(`MCP config templates exported to: ${mcpTemplateResult.outputDir}`);
-  for (const item of mcpTemplateResult.files) {
-    console.log(`- ${item.client}: ${item.file}`);
-  }
-  console.log("");
-  console.log("Next steps:");
+  for (const item of mcpTemplateResult.files) {
+    console.log(`- ${item.client}: ${item.file}`);
+  }
+  if (externalMcpResult.targets.length > 0) {
+    console.log(`Auto-configured external MCP files: ${externalMcpResult.applied.length}`);
+    for (const item of externalMcpResult.applied) {
+      const action = item.created ? "created" : item.updated ? "updated" : "unchanged";
+      console.log(`- ${item.file} (${action})`);
+    }
+  } else {
+    console.log("No external MCP config target detected. Set BOSS_RECRUIT_MCP_CONFIG_TARGETS to auto-configure custom agents.");
+  }
+  if (externalSkillResult.baseDirs.length > 0) {
+    console.log(`Mirrored skill to external dirs: ${externalSkillResult.mirrored.length}`);
+    for (const item of externalSkillResult.mirrored) {
+      console.log(`- ${item.target_dir}`);
+    }
+  } else {
+    console.log("No external skill dir detected. Set BOSS_RECRUIT_EXTERNAL_SKILL_DIRS to mirror skill for non-Codex agents.");
+  }
+  console.log("");
+  console.log("Next steps:");
   console.log("1. Fill in baseUrl/apiKey/model in the config file above.");
   console.log("2. Choose a client template from the exported MCP config files and merge it into your AI client config.");
   console.log("3. Choose a Chrome remote-debugging port (9222 is recommended, but you can reuse an existing port).");

package/src/pipeline.js

@@ -8,6 +8,126 @@ import {
   runScreenCli
 } from "./adapters.js";
 
+function dedupe(values = []) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function failedCheckSet(checks = []) {
+  const failed = checks
+    .filter((item) => item && item.ok === false && typeof item.key === "string")
+    .map((item) => item.key);
+  return new Set(failed);
+}
+
+function collectNpmInstallDirs(checks = [], workspaceRoot) {
+  const npmCheckKeys = new Set([
+    "npm_dep_chrome_remote_interface_search",
+    "npm_dep_chrome_remote_interface_screen",
+    "npm_dep_ws"
+  ]);
+  const dirs = checks
+    .filter((item) => item && item.ok === false && npmCheckKeys.has(item.key))
+    .map((item) => item.install_cwd)
+    .filter((value) => typeof value === "string" && value.trim());
+  if (dirs.length > 0) return dedupe(dirs);
+  return workspaceRoot ? [workspaceRoot] : [];
+}
+
+function buildNpmInstallCommands(checks = [], workspaceRoot) {
+  const dirs = collectNpmInstallDirs(checks, workspaceRoot);
+  const commands = [];
+  for (const dir of dirs) {
+    const escaped = String(dir).replace(/'/g, "''");
+    commands.push(`Set-Location '${escaped}'`);
+    commands.push("npm install");
+  }
+  return commands;
+}
+
+function formatCommandBlock(commands = []) {
+  return commands.map((command) => `- ${command}`).join("\n");
+}
+
+function buildPreflightRecovery(checks = [], workspaceRoot) {
+  const failed = failedCheckSet(checks);
+  if (failed.size === 0) return null;
+
+  const needNode = failed.has("node_cli");
+  const needNpm = (
+    failed.has("npm_dep_chrome_remote_interface_search")
+    || failed.has("npm_dep_chrome_remote_interface_screen")
+    || failed.has("npm_dep_ws")
+  );
+  const needPython = failed.has("python_cli");
+  const needPillow = failed.has("python_pillow");
+
+  const ordered_steps = [];
+  if (needNode) {
+    ordered_steps.push({
+      id: "install_nodejs",
+      title: "安装 Node.js >= 18",
+      blocked_by: [],
+      commands: [
+        "winget install OpenJS.NodeJS.LTS",
+        "node --version"
+      ]
+    });
+  }
+  if (needNpm) {
+    ordered_steps.push({
+      id: "install_npm_dependencies",
+      title: "安装 npm 依赖（chrome-remote-interface / ws）",
+      blocked_by: needNode ? ["install_nodejs"] : [],
+      commands: buildNpmInstallCommands(checks, workspaceRoot)
+    });
+  }
+  if (needPython) {
+    ordered_steps.push({
+      id: "install_python",
+      title: "安装 Python（确保 python 命令可用）",
+      blocked_by: [],
+      commands: [
+        "winget install Python.Python.3.12",
+        "python --version"
+      ]
+    });
+  }
+  if (needPillow) {
+    ordered_steps.push({
+      id: "install_pillow",
+      title: "安装 Pillow",
+      blocked_by: needPython ? ["install_python"] : [],
+      commands: [
+        "python -m pip install --upgrade pip",
+        "python -m pip install pillow"
+      ]
+    });
+  }
+
+  const promptLines = [
+    "你是环境修复 agent。请先读取 diagnostics.checks，再严格按下面顺序执行，不要并行跳步：",
+    "1) node_cli 失败 -> 先安装 Node.js，未成功前禁止执行 npm install。",
+    "2) npm_dep_* 失败 -> 再安装 npm 依赖（chrome-remote-interface / ws）。",
+    "3) python_cli 失败 -> 安装 Python 并确保 python 命令可用。",
+    "4) python_pillow 失败 -> 最后安装 Pillow。",
+    "每一步完成后都重新运行 doctor，直到所有检查通过后再重试 run_recruit_pipeline。"
+  ];
+
+  if (needNpm) {
+    const npmCommands = buildNpmInstallCommands(checks, workspaceRoot);
+    if (npmCommands.length > 0) {
+      promptLines.push("建议执行的 npm 命令：");
+      promptLines.push(formatCommandBlock(npmCommands));
+    }
+  }
+
+  return {
+    failed_check_keys: [...failed],
+    ordered_steps,
+    agent_prompt: promptLines.join("\n")
+  };
+}
+
 function buildRequiredConfirmations(parsedResult) {
   const confirmations = [];
 
@@ -280,6 +400,7 @@ export async function runRecruitPipeline({
 
   const preflight = runPreflight(workspaceRoot);
   if (!preflight.ok) {
+    const recovery = buildPreflightRecovery(preflight.checks, workspaceRoot);
     return buildFailedResponse(
       "PIPELINE_PREFLIGHT_FAILED",
       "招聘流水线运行前检查失败，请先修复缺失的本地依赖或配置文件。",
@@ -289,7 +410,8 @@ export async function runRecruitPipeline({
         diagnostics: {
           checks: preflight.checks,
           debug_port: preflight.debug_port,
-          calibration_path: preflight.calibration_path
+          calibration_path: preflight.calibration_path,
+          recovery
         }
       }
     );

package/src/test-pipeline.js

@@ -420,6 +420,45 @@ async function testNeedInputGateStillWorks() {
   assert.equal(preflightCalled, false);
 }
 
+async function testPreflightRecoveryPlanOrder() {
+  const tempDir = createTempDir("preflight-recovery");
+  const parsed = createParsed();
+  const deps = {
+    parseRecruitInstruction: () => parsed,
+    runPipelinePreflight: () => ({
+      ok: false,
+      debug_port: 9222,
+      calibration_path: null,
+      checks: [
+        { key: "node_cli", ok: false },
+        { key: "npm_dep_ws", ok: false, install_cwd: "C:/workspace/boss-recruit-mcp" }
+      ]
+    }),
+    ensureBossSearchPageReady: async () => ({ ok: true, state: "SEARCH_READY", debug_port: 9222, page_state: {} }),
+    runSearchCli: async () => buildSearchOk(0),
+    runScreenCli: async () => buildScreenOk({ processedCount: 0, passedCount: 0, outputCsv: null })
+  };
+
+  const result = await runRecruitPipeline(
+    {
+      workspaceRoot: tempDir,
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    deps
+  );
+
+  assert.equal(result.status, "FAILED");
+  assert.equal(result.error.code, "PIPELINE_PREFLIGHT_FAILED");
+  assert.deepEqual(
+    result.diagnostics.recovery.ordered_steps.map((item) => item.id),
+    ["install_nodejs", "install_npm_dependencies"]
+  );
+  assert.deepEqual(result.diagnostics.recovery.ordered_steps[1].blocked_by, ["install_nodejs"]);
+  assert.equal(result.diagnostics.recovery.agent_prompt.includes("不要并行跳步"), true);
+}
+
 async function main() {
   await testSearchExhaustedCompletesAndMergesCsv();
   await testSearchExhaustedByTipNodataEvenWhenCandidateCountPositive();
@@ -427,6 +466,7 @@ async function main() {
   await testScreenNoProgressWithZeroProcessedExportsBeforeFail();
   await testScreenNoProgressWithInvalidProcessedAndNoCsv();
   await testNeedInputGateStillWorks();
+  await testPreflightRecoveryPlanOrder();
   // eslint-disable-next-line no-console
   console.log("pipeline tests passed");
 }