@reconcrap/boss-recommend-mcp 0.1.7 → 0.1.8

package/package.json

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

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

@@ -91,10 +91,10 @@ CLI fallback 的状态机与 MCP 保持一致：
 ## Setup Checklist
 
 执行前先检查：
-
-- `boss-recommend-mcp` 是否已安装
-- `screening-config.json` 是否存在且包含可用模型配置
-- Chrome 远程调试端口是否可连
+
+- `boss-recommend-mcp` 是否已安装
+- `screening-config.json` 是否存在且 `baseUrl/apiKey/model` 均已由用户填写为可用值（不能是模板占位符）
+- Chrome 远程调试端口是否可连
 - 当前 Chrome 是否停留在 `https://www.zhipin.com/web/chat/recommend`
 
 在开始执行 recommend-search-cli / recommend-screen-cli 前，必须做页面就绪门禁：
@@ -102,14 +102,19 @@ CLI fallback 的状态机与 MCP 保持一致：
 - 检查 Chrome DevTools 端口是否可连接
 - 检查 Boss 是否已登录
 - 检查当前页面是否已停留在 recommend 页面
-- 任一不满足时，不得继续执行搜索和筛选；必须先提示用户在**正确端口**的 Chrome 中完成登录并导航到 recommend 页面，待用户确认“已就绪”后再重试
+- 若端口不可连接：先自动尝试启动 Chrome，并且必须使用 `--remote-debugging-port=<port>` + `--user-data-dir=<profile>`
+- 若检测到 Boss 已登录但不在 recommend 页面：先自动 navigate 到 `https://www.zhipin.com/web/chat/recommend`
+- 若检测到 Boss 未登录：提示用户先登录；用户登录后先 navigate 到 recommend 页面再继续
+- 自动修复后仍失败时，才提示用户介入并等待“已就绪”后重试
 
 ## Preflight 失败自动修复
 
-当工具返回 `status=FAILED` 且 `error.code=PIPELINE_PREFLIGHT_FAILED` 时：
-
-1. 优先读取 `diagnostics.recovery.agent_prompt`，直接把这段提示词交给 AI agent 执行环境修复。
-2. 若 `diagnostics.recovery.agent_prompt` 不存在，使用下面的兜底提示词（严格顺序，不可跳步）：
+当工具返回 `status=FAILED` 且 `error.code=PIPELINE_PREFLIGHT_FAILED` 时：
+
+1. 若 `diagnostics.checks` 中 `screen_config` 失败，优先引导用户填写 `screening-config.json` 的 `baseUrl/apiKey/model`（必须让用户提供真实值，不可保留模板值）。
+2. 优先查看 `diagnostics.auto_repair`，若有自动修复动作则先基于其结果继续执行或给出最小化补救提示。
+3. 若自动修复后仍失败，再读取 `diagnostics.recovery.agent_prompt`，直接把这段提示词交给 AI agent 执行环境修复。
+4. 若 `diagnostics.recovery.agent_prompt` 不存在，使用下面的兜底提示词（严格顺序，不可跳步）：
 
 ```text
 你是环境修复 agent。请根据 diagnostics.checks 修复依赖，必须串行执行：

package/src/adapters.js

@@ -8,6 +8,12 @@ const currentFilePath = fileURLToPath(import.meta.url);
 const packagedMcpDir = path.resolve(path.dirname(currentFilePath), "..");
 const bossRecommendUrl = "https://www.zhipin.com/web/chat/recommend";
 const chromeOnboardingUrlPattern = /^chrome:\/\/(welcome|intro|newtab|signin|history-sync|settings\/syncSetup)/i;
+const bossLoginUrlPattern = /zhipin\.com\/web\/user|passport\.zhipin\.com/i;
+const screenConfigTemplateDefaults = {
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: "replace-with-openai-api-key",
+  model: "gpt-4.1-mini"
+};
 
 function getCodexHome() {
   return process.env.CODEX_HOME
@@ -23,6 +29,10 @@ function getDesktopDir() {
   return path.join(os.homedir(), "Desktop");
 }
 
+function ensureDir(targetPath) {
+  fs.mkdirSync(targetPath, { recursive: true });
+}
+
 function pathExists(targetPath) {
   try {
     return fs.existsSync(targetPath);
@@ -71,6 +81,45 @@ function readJsonFile(filePath) {
   }
 }
 
+function validateScreenConfig(config) {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    return {
+      ok: false,
+      message: "screening-config.json 缺失或格式无效。请填写 baseUrl、apiKey、model。"
+    };
+  }
+  const baseUrl = String(config.baseUrl || "").trim();
+  const apiKey = String(config.apiKey || "").trim();
+  const model = String(config.model || "").trim();
+  const missing = [];
+  if (!baseUrl) missing.push("baseUrl");
+  if (!apiKey) missing.push("apiKey");
+  if (!model) missing.push("model");
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      message: `screening-config.json 缺少必填字段：${missing.join(", ")}。`
+    };
+  }
+  if (/^replace-with/i.test(apiKey) || apiKey === screenConfigTemplateDefaults.apiKey) {
+    return {
+      ok: false,
+      message: "screening-config.json 的 apiKey 仍是模板占位符，请填写真实 API Key。"
+    };
+  }
+  if (
+    baseUrl === screenConfigTemplateDefaults.baseUrl
+    && apiKey === screenConfigTemplateDefaults.apiKey
+    && model === screenConfigTemplateDefaults.model
+  ) {
+    return {
+      ok: false,
+      message: "screening-config.json 仍是默认模板值，请填写 baseUrl、apiKey、model。"
+    };
+  }
+  return { ok: true, message: "screening-config.json 校验通过。" };
+}
+
 function resolveWorkspaceDebugPort(workspaceRoot) {
   const fromEnv = parsePositiveInteger(process.env.BOSS_RECOMMEND_CHROME_PORT);
   if (fromEnv) return fromEnv;
@@ -78,6 +127,63 @@ function resolveWorkspaceDebugPort(workspaceRoot) {
   return parsePositiveInteger(config?.debugPort) || 9222;
 }
 
+function getChromeExecutable() {
+  const candidates = [
+    process.env.BOSS_RECOMMEND_CHROME_PATH,
+    path.join(process.env.LOCALAPPDATA || "", "Google", "Chrome", "Application", "chrome.exe"),
+    path.join(process.env.ProgramFiles || "", "Google", "Chrome", "Application", "chrome.exe"),
+    path.join(process.env["ProgramFiles(x86)"] || "", "Google", "Chrome", "Application", "chrome.exe")
+  ].filter(Boolean);
+  return candidates.find((candidate) => pathExists(candidate)) || null;
+}
+
+function getChromeUserDataDir(port) {
+  const profileDir = path.join(getCodexHome(), "boss-recommend-mcp", `chrome-profile-${port}`);
+  ensureDir(profileDir);
+  return profileDir;
+}
+
+function launchChromeWithDebugPort(port) {
+  const chromePath = getChromeExecutable();
+  if (!chromePath) {
+    return {
+      ok: false,
+      code: "CHROME_EXECUTABLE_NOT_FOUND",
+      message: "未找到 Chrome 可执行文件，请安装 Chrome 或设置 BOSS_RECOMMEND_CHROME_PATH。"
+    };
+  }
+  const userDataDir = getChromeUserDataDir(port);
+  const args = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${userDataDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--new-window",
+    bossRecommendUrl
+  ];
+
+  try {
+    const child = spawn(chromePath, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: false
+    });
+    child.unref();
+    return {
+      ok: true,
+      code: "CHROME_LAUNCHED",
+      chrome_path: chromePath,
+      user_data_dir: userDataDir
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      code: "CHROME_LAUNCH_FAILED",
+      message: error.message || "Chrome 启动失败。"
+    };
+  }
+}
+
 function resolveRecommendSearchCliDir(workspaceRoot) {
   const localDir = path.join(workspaceRoot, "boss-recommend-search-cli");
   if (pathExists(localDir)) return localDir;
@@ -388,16 +494,11 @@ function parseJsonOutput(text) {
 
 function loadScreenConfig(configPath) {
   const parsed = readJsonFile(configPath);
-  if (!parsed) {
-    return {
-      ok: false,
-      error: `Screen config file not found or invalid: ${configPath}`
-    };
-  }
-  if (!parsed.baseUrl || !parsed.apiKey || !parsed.model) {
+  const validation = validateScreenConfig(parsed);
+  if (!validation.ok) {
     return {
       ok: false,
-      error: "Invalid screen config: baseUrl/apiKey/model are required"
+      error: `${validation.message} (path: ${configPath})`
     };
   }
   return { ok: true, config: parsed };
@@ -411,6 +512,8 @@ export function runPipelinePreflight(workspaceRoot) {
   const searchDir = resolveRecommendSearchCliDir(workspaceRoot);
   const screenDir = resolveRecommendScreenCliDir(workspaceRoot);
   const screenConfigPath = resolveScreenConfigPath(workspaceRoot);
+  const screenConfigParsed = readJsonFile(screenConfigPath);
+  const screenConfigValidation = validateScreenConfig(screenConfigParsed);
   const checks = [
     {
       key: "recommend_search_cli_dir",
@@ -438,9 +541,9 @@ export function runPipelinePreflight(workspaceRoot) {
     },
     {
       key: "screen_config",
-      ok: pathExists(screenConfigPath),
+      ok: screenConfigValidation.ok,
       path: screenConfigPath,
-      message: "screening-config.json 不存在"
+      message: screenConfigValidation.ok ? "screening-config.json 可用" : screenConfigValidation.message
     }
   ];
   checks.push(...buildRuntimeDependencyChecks({ searchDir, screenDir }));
@@ -452,6 +555,123 @@ export function runPipelinePreflight(workspaceRoot) {
   };
 }
 
+function collectFailedCheckKeys(checks = []) {
+  return new Set(
+    checks
+      .filter((item) => item && item.ok === false && typeof item.key === "string")
+      .map((item) => item.key)
+  );
+}
+
+function collectNpmInstallDirsFromChecks(checks = [], workspaceRoot) {
+  const npmKeys = 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 && npmKeys.has(item.key))
+    .map((item) => item.install_cwd)
+    .filter((item) => typeof item === "string" && item.trim())
+    .map((item) => path.resolve(item));
+  if (dirs.length > 0) {
+    return [...new Set(dirs)];
+  }
+  return [path.resolve(workspaceRoot)];
+}
+
+function installNpmDependencies(checks, workspaceRoot) {
+  const dirs = collectNpmInstallDirsFromChecks(checks, workspaceRoot);
+  const commandResults = [];
+  let allOk = true;
+  for (const cwd of dirs) {
+    const result = runProcessSync({
+      command: "npm",
+      args: ["install"],
+      cwd
+    });
+    commandResults.push({
+      cwd,
+      ok: result.ok,
+      output: result.output || result.error_message || ""
+    });
+    if (!result.ok) allOk = false;
+  }
+  return {
+    ok: allOk,
+    action: "install_npm_dependencies",
+    changed: true,
+    command_results: commandResults,
+    message: allOk ? "npm 依赖自动安装完成。" : "npm 依赖自动安装失败。"
+  };
+}
+
+function installPillowIfPossible() {
+  const detected = detectPythonCommand();
+  if (!detected.ok || !detected.command) {
+    return {
+      ok: false,
+      action: "install_pillow",
+      changed: false,
+      message: "未检测到可用 python 命令，无法自动安装 Pillow。"
+    };
+  }
+  const install = runProcessSync({
+    command: detected.command,
+    args: ["-m", "pip", "install", "pillow"]
+  });
+  return {
+    ok: install.ok,
+    action: "install_pillow",
+    changed: install.ok,
+    message: install.ok ? "Pillow 自动安装完成。" : `Pillow 自动安装失败：${install.output || install.error_message || "unknown"}`
+  };
+}
+
+export function attemptPipelineAutoRepair(workspaceRoot, preflight = {}) {
+  const checks = Array.isArray(preflight.checks) ? preflight.checks : [];
+  const failed = collectFailedCheckKeys(checks);
+  const actions = [];
+
+  if (
+    failed.has("npm_dep_chrome_remote_interface_search")
+    || failed.has("npm_dep_chrome_remote_interface_screen")
+    || failed.has("npm_dep_ws")
+  ) {
+    if (!failed.has("node_cli")) {
+      actions.push(installNpmDependencies(checks, workspaceRoot));
+    } else {
+      actions.push({
+        ok: false,
+        action: "install_npm_dependencies",
+        changed: false,
+        message: "Node 命令不可用，跳过 npm 自动安装。"
+      });
+    }
+  }
+
+  if (failed.has("python_pillow")) {
+    if (!failed.has("python_cli")) {
+      actions.push(installPillowIfPossible());
+    } else {
+      actions.push({
+        ok: false,
+        action: "install_pillow",
+        changed: false,
+        message: "python 命令不可用，跳过 Pillow 自动安装。"
+      });
+    }
+  }
+
+  const attempted = actions.length > 0;
+  const nextPreflight = runPipelinePreflight(workspaceRoot);
+  return {
+    attempted,
+    actions,
+    preflight: nextPreflight
+  };
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -519,15 +739,18 @@ export async function inspectBossRecommendPageState(port, options = {}) {
         (tab) => typeof tab?.url === "string" && tab.url.includes("zhipin.com")
       );
       if (bossTab) {
+        const requiresLogin = bossLoginUrlPattern.test(bossTab.url);
         return buildBossPageState({
           ok: false,
-          state: "LOGIN_REQUIRED",
+          state: requiresLogin ? "LOGIN_REQUIRED" : "BOSS_NOT_ON_RECOMMEND",
           path: bossTab.url,
           current_url: bossTab.url,
           title: bossTab.title || null,
-          requires_login: true,
+          requires_login: requiresLogin,
           expected_url: expectedUrl,
-          message: "Boss 页面没有停留在 recommend 页面，通常表示需要重新登录。"
+          message: requiresLogin
+            ? "Boss 页面未登录，需先完成登录后再进入 recommend 页面。"
+            : "Boss 已登录但当前不在 recommend 页面，将尝试自动跳转。"
         });
       }
     } catch (error) {
@@ -647,13 +870,39 @@ export async function ensureBossRecommendPageReady(workspaceRoot, options = {})
       page_state: stableState
     };
   }
-  if (pageState.state === "LOGIN_REQUIRED") {
-    return {
-      ok: false,
-      debug_port: debugPort,
-      state: pageState.state,
-      page_state: pageState
-    };
+
+  let launchAttempt = null;
+  if (pageState.state === "DEBUG_PORT_UNREACHABLE") {
+    launchAttempt = launchChromeWithDebugPort(debugPort);
+    if (launchAttempt.ok) {
+      await sleep(settleMs + 1200);
+      pageState = await inspectBossRecommendPageState(debugPort, {
+        timeoutMs: inspectTimeoutMs,
+        pollMs
+      });
+      if (pageState.state === "RECOMMEND_READY") {
+        const stableState = await verifyRecommendPageStable(debugPort, { settleMs, pollMs });
+        return {
+          ok: stableState.state === "RECOMMEND_READY",
+          debug_port: debugPort,
+          state: stableState.state,
+          page_state: {
+            ...stableState,
+            launch_attempt: launchAttempt
+          }
+        };
+      }
+    } else {
+      return {
+        ok: false,
+        debug_port: debugPort,
+        state: pageState.state,
+        page_state: {
+          ...pageState,
+          launch_attempt: launchAttempt
+        }
+      };
+    }
   }
 
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
@@ -672,15 +921,10 @@ export async function ensureBossRecommendPageReady(workspaceRoot, options = {})
         ok: stableState.state === "RECOMMEND_READY",
         debug_port: debugPort,
         state: stableState.state,
-        page_state: stableState
-      };
-    }
-    if (pageState.state === "LOGIN_REQUIRED") {
-      return {
-        ok: false,
-        debug_port: debugPort,
-        state: pageState.state,
-        page_state: pageState
+        page_state: {
+          ...stableState,
+          launch_attempt: launchAttempt
+        }
       };
     }
   }
@@ -689,7 +933,10 @@ export async function ensureBossRecommendPageReady(workspaceRoot, options = {})
     ok: false,
     debug_port: debugPort,
     state: pageState.state || "UNKNOWN",
-    page_state: pageState
+    page_state: {
+      ...pageState,
+      launch_attempt: launchAttempt
+    }
   };
 }
 

package/src/cli.js

@@ -582,7 +582,7 @@ function printHelp() {
   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          Run the recommend pipeline once via CLI and print JSON");
-  console.log("  boss-recommend-mcp install      Install Codex skill and initialize user config");
+  console.log("  boss-recommend-mcp install      Install Codex skill and MCP config templates (does not create screening-config.json)");
   console.log("  boss-recommend-mcp install-skill Install only the Codex skill");
   console.log("  boss-recommend-mcp init-config  Create ~/.codex/boss-recommend-mcp/screening-config.json if missing");
   console.log("  boss-recommend-mcp set-port     Persist preferred Chrome debug port to screening-config.json");
@@ -610,12 +610,11 @@ function printMcpConfig(options = {}) {
 
 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}`);
-  console.log(configResult.created ? `Config template created at: ${configResult.path}` : `Config already exists at: ${configResult.path}`);
+  console.log("screening-config.json 不会在 install 阶段自动创建。首次运行请按 doctor / agent 提示填写 baseUrl、apiKey、model。");
   console.log(`MCP config templates exported to: ${mcpTemplateResult.outputDir}`);
   for (const item of mcpTemplateResult.files) {
     console.log(`- ${item.client}: ${item.file}`);

package/src/pipeline.js

@@ -1,10 +1,11 @@
 import { parseRecommendInstruction } from "./parser.js";
-import {
-  ensureBossRecommendPageReady,
-  runPipelinePreflight,
-  runRecommendSearchCli,
-  runRecommendScreenCli
-} from "./adapters.js";
+import {
+  attemptPipelineAutoRepair,
+  ensureBossRecommendPageReady,
+  runPipelinePreflight,
+  runRecommendSearchCli,
+  runRecommendScreenCli
+} from "./adapters.js";
 
 function dedupe(values = []) {
   return [...new Set(values.filter(Boolean))];
@@ -46,25 +47,38 @@ 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")
+function buildPreflightRecovery(checks = [], workspaceRoot) {
+  const failed = failedCheckSet(checks);
+  if (failed.size === 0) return null;
+
+  const needScreenConfig = failed.has("screen_config");
+  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: [],
+
+  const ordered_steps = [];
+  if (needScreenConfig) {
+    const configCheck = checks.find((item) => item?.key === "screen_config");
+    ordered_steps.push({
+      id: "fill_screening_config",
+      title: "填写 screening-config.json（baseUrl / apiKey / model）",
+      blocked_by: [],
+      commands: [
+        `打开并填写：${configCheck?.path || "~/.codex/boss-recommend-mcp/screening-config.json"}`,
+        "确认 baseUrl、apiKey、model 都是可用值（不要保留模板占位符）。"
+      ]
+    });
+  }
+  if (needNode) {
+    ordered_steps.push({
+      id: "install_nodejs",
+      title: "安装 Node.js >= 18",
+      blocked_by: [],
       commands: [
         "winget install OpenJS.NodeJS.LTS",
         "node --version"
@@ -102,14 +116,21 @@ function buildPreflightRecovery(checks = [], workspaceRoot) {
     });
   }
 
-  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，直到所有检查通过后再重试流水线。"
-  ];
+  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，直到所有检查通过后再重试流水线。"
+  ];
+  if (needScreenConfig) {
+    promptLines.splice(
+      1,
+      0,
+      "0) 若 screen_config 失败：先让用户提供并填写 baseUrl、apiKey、model（不得使用模板占位符）。"
+    );
+  }
 
   if (needNpm) {
     const npmCommands = buildNpmInstallCommands(checks, workspaceRoot);
@@ -190,15 +211,23 @@ function buildChromeSetupGuidance({ debugPort, pageState }) {
   const currentUrl = pageState?.current_url || null;
   const state = pageState?.state || "UNKNOWN";
   const isPortIssue = state === "DEBUG_PORT_UNREACHABLE";
+  const needsLogin = state === "LOGIN_REQUIRED" || state === "LOGIN_REQUIRED_AFTER_REDIRECT";
+  const launchAttempt = pageState?.launch_attempt || null;
+  const launchLine = launchAttempt?.ok
+    ? `已自动启动 Chrome（--remote-debugging-port=${debugPort}，--user-data-dir=${launchAttempt.user_data_dir || "auto"}）。`
+    : null;
   const steps = [
     `请先在可连接到 DevTools 端口 ${debugPort} 的 Chrome 实例中完成以下操作：`,
+    ...(launchLine ? [launchLine] : []),
     "1) 确认当前 Chrome 与本次运行使用同一个远程调试端口。",
     isPortIssue
       ? `2) 若端口不可连接，请用远程调试方式启动 Chrome（示例：chrome.exe --remote-debugging-port=${debugPort}）。`
       : "2) 确认端口可连接且浏览器窗口保持打开。",
-    "3) 登录 Boss 直聘（如已掉线请重新登录）。",
-    `4) 登录后导航并停留在推荐页：${expectedUrl}`,
-    "5) 完成后回复“已就绪”，我再继续执行搜索和筛选。"
+    needsLogin
+      ? "3) 当前检测到 Boss 未登录，请先在该 Chrome 实例完成登录。"
+      : "3) 如 Boss 登录态失效，请先重新登录。",
+    `4) 登录完成后先导航并停留在推荐页：${expectedUrl}`,
+    "5) 完成后回复“已就绪”，我会继续执行并优先自动导航到推荐页。"
   ];
   return {
     debug_port: debugPort,
@@ -210,23 +239,25 @@ function buildChromeSetupGuidance({ debugPort, pageState }) {
 }
 
 const defaultDependencies = {
+  attemptPipelineAutoRepair,
   parseRecommendInstruction,
-  ensureBossRecommendPageReady,
-  runPipelinePreflight,
-  runRecommendSearchCli,
-  runRecommendScreenCli
+  ensureBossRecommendPageReady,
+  runPipelinePreflight,
+  runRecommendSearchCli,
+  runRecommendScreenCli
 };
 
-export async function runRecommendPipeline(
-  { workspaceRoot, instruction, confirmation, overrides },
-  dependencies = defaultDependencies
-) {
-  const {
-    parseRecommendInstruction: parseInstruction,
-    ensureBossRecommendPageReady: ensureRecommendPageReady,
-    runPipelinePreflight: runPreflight,
-    runRecommendSearchCli: searchCli,
-    runRecommendScreenCli: screenCli
+export async function runRecommendPipeline(
+  { workspaceRoot, instruction, confirmation, overrides },
+  dependencies = defaultDependencies
+) {
+  const {
+    attemptPipelineAutoRepair: attemptAutoRepair,
+    parseRecommendInstruction: parseInstruction,
+    ensureBossRecommendPageReady: ensureRecommendPageReady,
+    runPipelinePreflight: runPreflight,
+    runRecommendSearchCli: searchCli,
+    runRecommendScreenCli: screenCli
   } = dependencies;
   const startedAt = Date.now();
   const parsed = parseInstruction({ instruction, confirmation, overrides });
@@ -249,23 +280,49 @@ export async function runRecommendPipeline(
     return buildNeedConfirmationResponse(parsed);
   }
 
-  const preflight = runPreflight(workspaceRoot);
-  if (!preflight.ok) {
-    const recovery = buildPreflightRecovery(preflight.checks, workspaceRoot);
-    return buildFailedResponse(
-      "PIPELINE_PREFLIGHT_FAILED",
-      "Recommend 流水线运行前检查失败，请先修复缺失的本地依赖或配置文件。",
-      {
-        search_params: parsed.searchParams,
-        screen_params: parsed.screenParams,
-        diagnostics: {
-          checks: preflight.checks,
-          debug_port: preflight.debug_port,
-          recovery
-        }
-      }
-    );
-  }
+  let preflight = runPreflight(workspaceRoot);
+  let autoRepair = null;
+  if (!preflight.ok) {
+    if (typeof attemptAutoRepair === "function") {
+      autoRepair = attemptAutoRepair(workspaceRoot, preflight);
+      if (autoRepair?.preflight) {
+        preflight = autoRepair.preflight;
+      }
+    }
+  }
+
+  if (!preflight.ok) {
+    const screenConfigCheck = preflight.checks?.find((item) => item?.key === "screen_config" && item?.ok === false);
+    const recovery = buildPreflightRecovery(preflight.checks, workspaceRoot);
+    return buildFailedResponse(
+      "PIPELINE_PREFLIGHT_FAILED",
+      "Recommend 流水线运行前检查失败，请先修复缺失的本地依赖或配置文件。",
+      {
+        search_params: parsed.searchParams,
+        screen_params: parsed.screenParams,
+        required_user_action: screenConfigCheck ? "provide_screening_config" : undefined,
+        guidance: screenConfigCheck
+          ? {
+              config_path: screenConfigCheck.path,
+              agent_prompt: [
+                "请先让用户填写 screening-config.json 的以下字段：",
+                "1) baseUrl",
+                "2) apiKey",
+                "3) model",
+                `配置文件路径：${screenConfigCheck.path}`,
+                "注意：不要使用模板占位符（例如 replace-with-openai-api-key）。填写完成后重试。"
+              ].join("\n")
+            }
+          : undefined,
+        diagnostics: {
+          checks: preflight.checks,
+          debug_port: preflight.debug_port,
+          auto_repair: autoRepair,
+          recovery
+        }
+      }
+    );
+  }
 
   const pageCheck = await ensureRecommendPageReady(workspaceRoot, {
     port: preflight.debug_port

package/src/test-pipeline.js

@@ -353,6 +353,161 @@ async function testPreflightRecoveryPlanOrder() {
   assert.equal(result.diagnostics.recovery.agent_prompt.includes("不要并行跳步"), true);
 }
 
+async function testPreflightAutoRepairCanUnblockPipeline() {
+  let repairCalled = false;
+  const result = await runRecommendPipeline(
+    {
+      workspaceRoot: process.cwd(),
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    {
+      parseRecommendInstruction: () => createParsed(),
+      runPipelinePreflight: () => ({
+        ok: false,
+        debug_port: 9222,
+        checks: [{ key: "npm_dep_ws", ok: false, install_cwd: process.cwd() }]
+      }),
+      attemptPipelineAutoRepair: () => {
+        repairCalled = true;
+        return {
+          attempted: true,
+          actions: [{ ok: true, action: "install_npm_dependencies" }],
+          preflight: { ok: true, debug_port: 9222, checks: [] }
+        };
+      },
+      ensureBossRecommendPageReady: async () => ({ ok: true, state: "RECOMMEND_READY", page_state: {} }),
+      runRecommendSearchCli: async () => ({ ok: true, summary: { candidate_count: 1, applied_filters: {} } }),
+      runRecommendScreenCli: async () => ({ ok: true, summary: { processed_count: 1, passed_count: 1, skipped_count: 0 } })
+    }
+  );
+
+  assert.equal(repairCalled, true);
+  assert.equal(result.status, "COMPLETED");
+}
+
+async function testPreflightAutoRepairStillFailShouldExposeDiagnostics() {
+  const result = await runRecommendPipeline(
+    {
+      workspaceRoot: process.cwd(),
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    {
+      parseRecommendInstruction: () => createParsed(),
+      runPipelinePreflight: () => ({
+        ok: false,
+        debug_port: 9222,
+        checks: [{ key: "node_cli", ok: false }]
+      }),
+      attemptPipelineAutoRepair: () => ({
+        attempted: true,
+        actions: [{ ok: false, action: "install_npm_dependencies" }],
+        preflight: {
+          ok: false,
+          debug_port: 9222,
+          checks: [{ key: "node_cli", ok: false }]
+        }
+      }),
+      ensureBossRecommendPageReady: async () => ({ ok: true, state: "RECOMMEND_READY", page_state: {} }),
+      runRecommendSearchCli: async () => ({ ok: true, summary: {} }),
+      runRecommendScreenCli: async () => ({ ok: true, summary: {} })
+    }
+  );
+
+  assert.equal(result.status, "FAILED");
+  assert.equal(result.error.code, "PIPELINE_PREFLIGHT_FAILED");
+  assert.equal(result.diagnostics.auto_repair.attempted, true);
+}
+
+async function testScreenConfigFailureShouldRequireUserProvidedConfig() {
+  const result = await runRecommendPipeline(
+    {
+      workspaceRoot: process.cwd(),
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    {
+      parseRecommendInstruction: () => createParsed(),
+      runPipelinePreflight: () => ({
+        ok: false,
+        debug_port: 9222,
+        checks: [
+          {
+            key: "screen_config",
+            ok: false,
+            path: "C:/Users/test/.codex/boss-recommend-mcp/screening-config.json",
+            message: "screening-config.json 缺失或格式无效"
+          }
+        ]
+      }),
+      attemptPipelineAutoRepair: () => ({
+        attempted: false,
+        actions: [],
+        preflight: {
+          ok: false,
+          debug_port: 9222,
+          checks: [
+            {
+              key: "screen_config",
+              ok: false,
+              path: "C:/Users/test/.codex/boss-recommend-mcp/screening-config.json",
+              message: "screening-config.json 缺失或格式无效"
+            }
+          ]
+        }
+      }),
+      ensureBossRecommendPageReady: async () => ({ ok: true, state: "RECOMMEND_READY", page_state: {} }),
+      runRecommendSearchCli: async () => ({ ok: true, summary: {} }),
+      runRecommendScreenCli: async () => ({ ok: true, summary: {} })
+    }
+  );
+
+  assert.equal(result.status, "FAILED");
+  assert.equal(result.error.code, "PIPELINE_PREFLIGHT_FAILED");
+  assert.equal(result.required_user_action, "provide_screening_config");
+  assert.equal(result.guidance.config_path.includes("screening-config.json"), true);
+  assert.equal(result.guidance.agent_prompt.includes("baseUrl"), true);
+  assert.equal(result.guidance.agent_prompt.includes("apiKey"), true);
+  assert.equal(result.guidance.agent_prompt.includes("model"), true);
+}
+
+async function testScreenConfigRecoveryStepShouldBeFirst() {
+  const result = await runRecommendPipeline(
+    {
+      workspaceRoot: "C:/workspace/boss-recommend-mcp",
+      instruction: "test",
+      confirmation: {},
+      overrides: {}
+    },
+    {
+      parseRecommendInstruction: () => createParsed(),
+      runPipelinePreflight: () => ({
+        ok: false,
+        debug_port: 9222,
+        checks: [
+          {
+            key: "screen_config",
+            ok: false,
+            path: "C:/Users/test/.codex/boss-recommend-mcp/screening-config.json",
+            message: "screening-config.json 缺失或格式无效"
+          },
+          { key: "node_cli", ok: false }
+        ]
+      }),
+      ensureBossRecommendPageReady: async () => ({ ok: true, state: "RECOMMEND_READY", page_state: {} }),
+      runRecommendSearchCli: async () => ({ ok: true, summary: {} }),
+      runRecommendScreenCli: async () => ({ ok: true, summary: {} })
+    }
+  );
+
+  assert.equal(result.status, "FAILED");
+  assert.equal(result.diagnostics.recovery.ordered_steps[0].id, "fill_screening_config");
+}
+
 async function main() {
   await testNeedConfirmationGate();
   await testNeedSchoolTagConfirmationGate();
@@ -364,6 +519,10 @@ async function main() {
   await testLoginRequiredShouldReturnGuidance();
   await testDebugPortUnreachableShouldReturnConnectionCode();
   await testPreflightRecoveryPlanOrder();
+  await testPreflightAutoRepairCanUnblockPipeline();
+  await testPreflightAutoRepairStillFailShouldExposeDiagnostics();
+  await testScreenConfigFailureShouldRequireUserProvidedConfig();
+  await testScreenConfigRecoveryStepShouldBeFirst();
   console.log("pipeline tests passed");
 }