@reconcrap/boss-recruit-mcp 1.0.8 → 1.0.9

package/README.md

@@ -97,6 +97,7 @@ $CODEX_HOME/boss-recruit-mcp/screening-config.json
   - `openaiOrganization`
   - `openaiProject`
 - `debugPort` 可选，默认 `9222`
+  - 端口优先级：`--port > BOSS_RECRUIT_CHROME_PORT > screening-config.json.debugPort > 9222`
 - `calibrationFile` 可选；不填时默认使用 `$CODEX_HOME/boss-recruit-mcp/favorite-calibration.json`
 - `outputDir` 可选；不填时默认输出到用户桌面
 - 学校标签支持 `统招本科` / `双一流院校` / `985` / `211` / `qs100` / `qs500`；如果输入 `qs50`、`qs200`、`qs500` 等其他 `QS数字`，会按 `<=100 -> qs100`、`>100 -> qs500` 归一
@@ -140,7 +141,15 @@ boss-recruit-mcp run --instruction-file request.txt --confirmation-file confirma
 
 ## Chrome 与校准
 
-先确认你要使用的 Chrome 远程调试端口。推荐 `9222`，但如果你已经有一个正在运行的远程调试 Chrome，也可以继续使用那个端口。确认端口后，再执行下面的命令。
+先确认你要使用的 Chrome 远程调试端口。推荐 `9222`，但如果你已经有一个正在运行的远程调试 Chrome，也可以继续使用那个端口。
+
+建议先固化一次端口（后续命令自动沿用）：
+
+```bash
+boss-recruit-mcp set-port --port <port>
+```
+
+确认端口后，再执行下面的命令。
 
 执行校准（会自动尝试打开 Boss 搜索页）：
 
@@ -179,6 +188,8 @@ $CODEX_HOME/boss-recruit-mcp/favorite-calibration.json
 也可以用下面的命令检查依赖、配置和校准文件：
 
 ```bash
+boss-recruit-mcp doctor
+# 或显式指定
 boss-recruit-mcp doctor --port <port>
 ```
 

package/package.json

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

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

@@ -35,6 +35,7 @@ boss-recruit-mcp mcp-config --client all
 - 参数确认尽量复用统一模板：`已识别参数` / `待确认或待修正` / `缺失参数` / `默认值提醒` / `请用户回复`。
 - 在正式执行前，必须单独让用户确认筛选 `criteria`（尤其学历/学校/论文等硬性条件）无误，不能只确认关键词和搜索参数。
 - 端口未确认时，必须先询问用户是否使用推荐的 `9222`，或提供一个已有的其他远程调试端口，不能直接默认 `9222`。
+- 用户确认端口后，先执行 `boss-recruit-mcp set-port --port <port>`，让后续 `doctor / launch-chrome / calibrate / run` 自动复用同一端口。
 - 任何需要打开 Chrome 的动作前，先检查调试端口是否已有可用实例；端口可连时必须复用，不要再新开一个 9222 实例。
 - 若页面未停留在 Boss search（例如跳到登录页或首页），必须提示用户先手动登录 Boss，再继续。
 - 如果识别结果里出现明显脏值或可疑字段，例如“杭州筛选做过”，必须要求用户改成标准值后再继续。

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

@@ -27,16 +27,18 @@
    - 建议使用 `9222`
    - 但也允许用户明确提供一个已在使用的其他远程调试端口
 3. 在用户确认端口前，不要直接假设 `9222` 并执行任何依赖端口的命令。
-4. 端口确认后，先检查依赖与端口状态：
-   - `boss-recruit-mcp doctor --port <port>`
-5. 任何“准备打开 Chrome”的动作前，必须先判断该端口是否已有可用实例：
+4. 用户确认端口后，先执行一次端口固化，确保后续动作自动沿用同一端口：
+   - `boss-recruit-mcp set-port --port <port>`
+5. 再检查依赖与端口状态：
+   - `boss-recruit-mcp doctor`（或显式 `boss-recruit-mcp doctor --port <port>`）
+6. 任何“准备打开 Chrome”的动作前，必须先判断该端口是否已有可用实例：
    - 若调试端口可连，禁止再新开 Chrome；直接复用现有实例，并确保页面在 `https://www.zhipin.com/web/chat/search`
    - 仅当调试端口不可连时，才执行 `boss-recruit-mcp launch-chrome --port <port>`
-6. 若执行 `launch-chrome` 后页面没有停留在 `https://www.zhipin.com/web/chat/search`：
+7. 若执行 `launch-chrome` 后页面没有停留在 `https://www.zhipin.com/web/chat/search`：
    - 若仍在 search 页面，可继续；
    - 若跳转到登录页、首页或其他 Boss 页面，视为“需要重新登录”；
    - 必须明确提示用户手动登录 Boss，并等待用户回复“已登录/可以继续”后，才能继续后续动作。
-7. 只有在以上条件满足后，才继续调用流水线。
+8. 只有在以上条件满足后，才继续调用流水线。
 
 ## Calibration Requirement
 
@@ -278,6 +280,7 @@
 - 如果工具已经返回 `diagnostics.checks`，优先基于这些检查项生成排障建议。
 - 如果工具返回 `output_csv`，在摘要里给出路径，避免重复解释内部流程。
 - 如果端口还没确认，必须先问用户“是否使用推荐的 `9222`，还是你已经有别的远程调试端口”，不能直接把 `9222` 当成已确认值。
+- 用户确认端口后，先执行一次 `boss-recruit-mcp set-port --port <port>`，让后续 `doctor / launch-chrome / calibrate / run` 自动复用同一端口。
 - 如果需要打开 Chrome，优先帮用户执行而不是只给命令。
 - 如果新打开的 Chrome 页面跳离了 search 页面，必须判断为“需要登录”，提示用户手动登录后再继续。
 
@@ -290,12 +293,13 @@
 期望行为：
 
 1. 先询问用户是否使用推荐的 Chrome 调试端口 `9222`，或提供一个已有的其他端口。
-2. 用户确认端口后，启动对应端口的调试 Chrome 并打开 Boss 搜索页面。
-3. 先检查校准文件是否存在；若不存在，提醒用户按步骤完成校准。
-4. 环境就绪后再首次调用流水线。
-5. 若 keyword 被自动提取为 `AI infra`，先让用户确认。
-6. 确认后再次调用。
-7. 成功则返回通过人数与 CSV 路径；失败则按错误类型给出下一步。
+2. 用户确认端口后，先执行 `boss-recruit-mcp set-port --port <port>` 固化端口。
+3. 启动对应端口的调试 Chrome 并打开 Boss 搜索页面。
+4. 先检查校准文件是否存在；若不存在，提醒用户按步骤完成校准。
+5. 环境就绪后再首次调用流水线。
+6. 若 keyword 被自动提取为 `AI infra`，先让用户确认。
+7. 确认后再次调用。
+8. 成功则返回通过人数与 CSV 路径；失败则按错误类型给出下一步。
 
 ## Response Style
 

package/src/adapters.js

@@ -49,6 +49,11 @@ function pathExists(targetPath) {
   }
 }
 
+function parsePositiveInteger(raw) {
+  const value = Number.parseInt(String(raw || ""), 10);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
 function resolveSearchCliDir(workspaceRoot) {
   const localDir = path.join(workspaceRoot, "boss-search-cli");
   if (pathExists(localDir)) {
@@ -190,35 +195,43 @@ function loadScreenConfig(configPath) {
   }
 }
 
-function resolveDebugPort(config) {
-  const fromEnv = Number.parseInt(process.env.BOSS_RECRUIT_CHROME_PORT || "", 10);
-  if (Number.isFinite(fromEnv) && fromEnv > 0) return fromEnv;
-  const fromConfig = Number.parseInt(String(config?.debugPort || ""), 10);
-  if (Number.isFinite(fromConfig) && fromConfig > 0) return fromConfig;
-  return 9222;
+function readScreenConfigJson(configPath) {
+  if (!pathExists(configPath)) return null;
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveDebugPortFromConfigPath(configPath) {
+  const parsed = readScreenConfigJson(configPath);
+  const fromConfig = parsePositiveInteger(parsed?.debugPort);
+  if (fromConfig) return fromConfig;
+  return null;
 }
 
 function resolveWorkspaceDebugPort(workspaceRoot) {
+  const fromEnv = parsePositiveInteger(process.env.BOSS_RECRUIT_CHROME_PORT);
+  if (fromEnv) return fromEnv;
+
   const configPath = resolveScreenConfigPath(workspaceRoot);
-  if (pathExists(configPath)) {
-    const loaded = loadScreenConfig(configPath);
-    if (loaded.ok) {
-      return resolveDebugPort(loaded.config);
-    }
-  }
-  return resolveDebugPort(null);
+  const fromConfig = resolveDebugPortFromConfigPath(configPath);
+  if (fromConfig) return fromConfig;
+
+  return 9222;
 }
 
 export function runPipelinePreflight(workspaceRoot) {
   const searchDir = resolveSearchCliDir(workspaceRoot);
   const screenDir = resolveScreenCliDir(workspaceRoot);
   const screenConfigPath = resolveScreenConfigPath(workspaceRoot);
-  const loaded = pathExists(screenConfigPath) ? loadScreenConfig(screenConfigPath) : null;
-  const debugPort = loaded?.ok ? resolveDebugPort(loaded.config) : resolveDebugPort(null);
-  const calibrationPath = loaded?.ok
-    ? (loaded.config.calibrationFile
-      ? path.resolve(path.dirname(screenConfigPath), loaded.config.calibrationFile)
-      : getUserCalibrationPath())
+  const rawConfig = readScreenConfigJson(screenConfigPath);
+  const debugPort = resolveWorkspaceDebugPort(workspaceRoot);
+  const calibrationPath = rawConfig?.calibrationFile
+    ? path.resolve(path.dirname(screenConfigPath), rawConfig.calibrationFile)
     : getUserCalibrationPath();
   const checks = [
     {
@@ -354,7 +367,7 @@ export async function runScreenCli({ workspaceRoot, screenParams }) {
   const calibration = loaded.config.calibrationFile
     ? path.resolve(configBaseDir, loaded.config.calibrationFile)
     : getUserCalibrationPath();
-  const debugPort = resolveDebugPort(loaded.config);
+  const debugPort = resolveWorkspaceDebugPort(workspaceRoot);
 
   const outputName = `筛选结果_${Date.now()}.csv`;
   let outputPath = outputName;

package/src/cli.js

@@ -284,6 +284,99 @@ function getWorkspaceRoot(options) {
   return path.resolve(String(raw));
 }
 
+function parsePositivePort(raw) {
+  const port = Number.parseInt(String(raw || ""), 10);
+  return Number.isFinite(port) && port > 0 ? port : null;
+}
+
+function getActiveScreenConfigPath(workspaceRoot) {
+  const preflight = runPipelinePreflight(workspaceRoot);
+  const screenConfigCheck = preflight.checks.find((item) => item.key === "screen_config");
+  if (screenConfigCheck?.path) {
+    return path.resolve(screenConfigCheck.path);
+  }
+  return getUserConfigPath();
+}
+
+function readJsonObjectFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Config content must be a JSON object");
+  }
+  return parsed;
+}
+
+function readDebugPortFromConfigPath(configPath) {
+  try {
+    if (!fs.existsSync(configPath)) return null;
+    const parsed = readJsonObjectFile(configPath);
+    return parsePositivePort(parsed.debugPort);
+  } catch {
+    return null;
+  }
+}
+
+function persistDebugPortSelection(port, options = {}) {
+  const workspaceRoot = getWorkspaceRoot(options);
+  const configPath = getActiveScreenConfigPath(workspaceRoot);
+  const existed = fs.existsSync(configPath);
+  let config = {};
+
+  if (existed) {
+    config = readJsonObjectFile(configPath);
+  }
+
+  config.debugPort = port;
+  ensureDir(path.dirname(configPath));
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf8");
+
+  return {
+    port,
+    configPath,
+    existed
+  };
+}
+
+function applyExplicitPortSelection(options = {}, extras = {}) {
+  const selected = parsePositivePort(options.port);
+  if (!selected) return null;
+
+  process.env.BOSS_RECRUIT_CHROME_PORT = String(selected);
+  if (!extras.persist) return { port: selected, persisted: false };
+
+  try {
+    const persisted = persistDebugPortSelection(selected, options);
+    return {
+      port: selected,
+      persisted: true,
+      configPath: persisted.configPath
+    };
+  } catch (error) {
+    return {
+      port: selected,
+      persisted: false,
+      error: error.message
+    };
+  }
+}
+
+function setDebugPort(options = {}) {
+  const selected = parsePositivePort(options.port);
+  if (!selected) {
+    throw new Error("Missing required --port <number> for set-port.");
+  }
+
+  process.env.BOSS_RECRUIT_CHROME_PORT = String(selected);
+  const result = persistDebugPortSelection(selected, options);
+
+  return {
+    port: selected,
+    configPath: result.configPath,
+    existed: result.existed
+  };
+}
+
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -421,9 +514,18 @@ function hasModule(moduleName) {
 }
 
 function getDebugPort(options = {}) {
-  const raw = options.port || process.env.BOSS_RECRUIT_CHROME_PORT || "9222";
-  const port = Number.parseInt(String(raw), 10);
-  return Number.isFinite(port) && port > 0 ? port : 9222;
+  const fromOption = parsePositivePort(options.port);
+  if (fromOption) return fromOption;
+
+  const fromEnv = parsePositivePort(process.env.BOSS_RECRUIT_CHROME_PORT);
+  if (fromEnv) return fromEnv;
+
+  const workspaceRoot = getWorkspaceRoot(options);
+  const configPath = getActiveScreenConfigPath(workspaceRoot);
+  const fromConfig = readDebugPortFromConfigPath(configPath);
+  if (fromConfig) return fromConfig;
+
+  return 9222;
 }
 
 function getCalibrationTimeoutMs(options = {}) {
@@ -481,8 +583,10 @@ function ensureUserConfig() {
 }
 
 async function printDoctor(options) {
+  applyExplicitPortSelection(options, { persist: true });
   const port = getDebugPort(options);
-  const checks = runPipelinePreflight(process.cwd()).checks.slice();
+  const workspaceRoot = getWorkspaceRoot(options);
+  const checks = runPipelinePreflight(workspaceRoot).checks.slice();
   const pageState = await inspectBossPageState(port, { timeoutMs: 2000, pollMs: 500 });
   const userConfigPath = getUserConfigPath();
   checks.push({
@@ -523,6 +627,7 @@ async function printDoctor(options) {
 }
 
 async function calibrate(options) {
+  applyExplicitPortSelection(options, { persist: true });
   const port = getDebugPort(options);
   const output = options.output ? path.resolve(String(options.output)) : getUserCalibrationPath();
   const timeoutMs = getCalibrationTimeoutMs(options);
@@ -587,6 +692,7 @@ async function calibrate(options) {
 }
 
 async function launchChrome(options) {
+  applyExplicitPortSelection(options, { persist: true });
   const port = getDebugPort(options);
   const initialState = await inspectBossPageState(port, { timeoutMs: 2000, pollMs: 500 });
   let usedExistingInstance = initialState.state !== "DEBUG_PORT_UNREACHABLE";
@@ -692,6 +798,7 @@ function printHelp() {
   console.log("  boss-recruit-mcp install      Install Codex skill and initialize user config");
   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 doctor       Check config, calibration, and runtime prerequisites");
   console.log("  boss-recruit-mcp calibrate    Auto-open Boss search page, then run favorite-button calibration");
@@ -705,6 +812,9 @@ function printHelp() {
   console.log("Calibration command:");
   console.log("  boss-recruit-mcp calibrate --port 9222 [--timeout-ms 60000] [--output <path>]");
   console.log("");
+  console.log("Port command:");
+  console.log("  boss-recruit-mcp set-port --port 19222");
+  console.log("");
   console.log("MCP config command:");
   console.log("  boss-recruit-mcp mcp-config --client cursor");
   console.log("  boss-recruit-mcp mcp-config --client all --output-dir <dir>");
@@ -760,13 +870,15 @@ function installAll() {
   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).");
-  console.log("4. Run `boss-recruit-mcp doctor --port <your-port>` to verify config, calibration, and runtime prerequisites.");
-  console.log("5. Run `boss-recruit-mcp launch-chrome --port <your-port>`; if it reports the page redirected away from search, log in to Boss manually in that Chrome window.");
-  console.log("6. Run `boss-recruit-mcp calibrate --port <your-port>` to generate favorite-calibration.json for this environment.");
-  console.log("7. Run `boss-recruit-mcp start` or configure your MCP client to launch the command from the generated template.");
+  console.log("4. Run `boss-recruit-mcp set-port --port <your-port>` once to persist your chosen port for all later commands.");
+  console.log("5. Run `boss-recruit-mcp doctor` (or `boss-recruit-mcp doctor --port <your-port>`) to verify config, calibration, and runtime prerequisites.");
+  console.log("6. Run `boss-recruit-mcp launch-chrome` (or `--port <your-port>`); if it reports the page redirected away from search, log in to Boss manually in that Chrome window.");
+  console.log("7. Run `boss-recruit-mcp calibrate` (or `--port <your-port>`) to generate favorite-calibration.json for this environment.");
+  console.log("8. Run `boss-recruit-mcp start` or configure your MCP client to launch the command from the generated template.");
 }
 
 async function runPipelineOnce(options) {
+  applyExplicitPortSelection(options, { persist: true });
   const instruction = getRunInstruction(options);
   const confirmation = getRunConfirmation(options);
   const overrides = getRunOverrides(options);
@@ -819,6 +931,18 @@ switch (command) {
     );
     break;
   }
+  case "set-port": {
+    try {
+      const result = setDebugPort(options);
+      console.log(`Preferred debug port saved: ${result.port}`);
+      console.log(`Updated config: ${result.configPath}`);
+      console.log("Port priority for runtime commands: --port > BOSS_RECRUIT_CHROME_PORT > screening-config.json.debugPort > 9222");
+    } catch (error) {
+      console.error(error.message || "Failed to persist debug port.");
+      process.exitCode = 1;
+    }
+    break;
+  }
   case "mcp-config":
     try {
       printMcpConfig(options);

package/vendor/boss-screen-cli/boss-screen-cli.cjs

@@ -6,14 +6,70 @@ const os = require('os');
 const path = require('path');
 const readline = require('readline');
 const { spawn, spawnSync } = require('child_process');
+const DEFAULT_DEBUG_PORT = 9222;
 
-const args = process.argv.slice(2).reduce((acc, arg, i, arr) => {
-    if (arg.startsWith('--')) {
-        const key = arg.slice(2);
-        acc[key] = arr[i + 1] && !arr[i + 1].startsWith('--') ? arr[i + 1] : true;
+function parsePositiveInteger(raw) {
+    const value = Number.parseInt(String(raw || ''), 10);
+    if (Number.isFinite(value) && value > 0) {
+        return value;
     }
-    return acc;
-}, {});
+    return null;
+}
+
+function resolveDebugPort({ explicitPort = null, configPort = null } = {}) {
+    const fromExplicit = parsePositiveInteger(explicitPort);
+    if (fromExplicit) return fromExplicit;
+    const fromEnv = parsePositiveInteger(process.env.BOSS_RECRUIT_CHROME_PORT);
+    if (fromEnv) return fromEnv;
+    const fromConfig = parsePositiveInteger(configPort);
+    if (fromConfig) return fromConfig;
+    return DEFAULT_DEBUG_PORT;
+}
+
+function parseCliArgs(argv) {
+    const parsed = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+
+        if (token === '-h') {
+            parsed.help = true;
+            continue;
+        }
+        if (token === '-p') {
+            const next = argv[i + 1];
+            if (next && !next.startsWith('-')) {
+                parsed.port = next;
+                i += 1;
+            } else {
+                parsed.port = true;
+            }
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            continue;
+        }
+
+        const eqIndex = token.indexOf('=');
+        if (eqIndex > 2) {
+            const key = token.slice(2, eqIndex);
+            const value = token.slice(eqIndex + 1);
+            parsed[key] = value || true;
+            continue;
+        }
+
+        const key = token.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('-')) {
+            parsed[key] = next;
+            i += 1;
+        } else {
+            parsed[key] = true;
+        }
+    }
+    return parsed;
+}
+
+const args = parseCliArgs(process.argv.slice(2));
 
 let baseUrl = args.baseurl || args.baseUrl || null;
 let apiKey = args.apikey || args.apiKey || null;
@@ -25,10 +81,7 @@ let targetCount = Number.parseInt(args.target || args.targetCount || '', 10);
 if (!Number.isFinite(targetCount) || targetCount <= 0) {
     targetCount = null;
 }
-let debugPort = Number.parseInt(args.port || '9222', 10);
-if (!Number.isFinite(debugPort) || debugPort <= 0) {
-    debugPort = 9222;
-}
+let debugPort = resolveDebugPort({ explicitPort: args.port });
 let configFile = args.config ? path.resolve(String(args.config)) : path.resolve(process.cwd(), 'favorite-calibration.json');
 let outputCsv = args.output || `筛选结果_${Date.now()}.csv`;
 const bossSearchUrl = 'https://www.zhipin.com/web/chat/search';
@@ -36,16 +89,21 @@ const calibrationScriptPath = path.join(__dirname, 'calibrate-favorite-position-
 const MAX_RESUME_TEXT_CHARS = 12000;
 const OPENAI_DEFAULT_BASE_URL = 'https://api.openai.com/v1';
 
+const startupDiscovered = discoverInstalledBossRecruitResources();
+applyDiscoveredResources(startupDiscovered);
 applyOpenAIEnvironmentDefaults();
 
-if (args.help || args.h) {
+if (args.help) {
     printUsage();
     process.exit(0);
 }
 
 function printUsage() {
     const scriptName = path.basename(process.argv[1] || 'boss-screen-cli.cjs');
-    console.log(`Usage: node ${scriptName} --criteria <criteria> --targetCount <n> [--baseurl <url>] [--apikey <key>] [--model <model>] [--openai-organization <org_id>] [--openai-project <project_id>] [--port <9222>] [--config <favorite-calibration.json>] [--output <csv>]`);
+    console.log(`Usage: node ${scriptName} --criteria <criteria> --targetCount <n> [--baseurl <url>] [--apikey <key>] [--model <model>] [--openai-organization <org_id>] [--openai-project <project_id>] [--port <number>] [--config <favorite-calibration.json>] [--output <csv>]`);
+    console.log(`  -p, --port <number>   Chrome调试端口（默认: ${debugPort}）`);
+    console.log('  -h, --help            显示帮助');
+    console.log('  端口优先级: --port > BOSS_RECRUIT_CHROME_PORT > screening-config.json.debugPort > 9222');
     console.log('Tip: run without parameters to enter step-by-step interactive mode.');
 }
 
@@ -207,10 +265,10 @@ function applyDiscoveredResources(discovered) {
             openaiProject = discovered.config.openaiProject.trim();
         }
 
-        const configPort = Number.parseInt(String(discovered.config.debugPort || ''), 10);
-        if (!args.port && Number.isFinite(configPort) && configPort > 0) {
-            debugPort = configPort;
-        }
+        debugPort = resolveDebugPort({
+            explicitPort: args.port,
+            configPort: discovered.config.debugPort
+        });
 
         if (!args.output && typeof discovered.config.outputDir === 'string' && discovered.config.outputDir.trim()) {
             const outputDir = discovered.config.outputDir.trim();

package/vendor/boss-search-cli/src/cli.js

@@ -1,11 +1,74 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
 import { BossSearcher } from './boss-searcher.js';
 
+const DEFAULT_DEBUG_PORT = 9222;
+
+function parsePositiveInteger(raw) {
+  const value = Number.parseInt(String(raw || ''), 10);
+  if (Number.isFinite(value) && value > 0) {
+    return value;
+  }
+  return null;
+}
+
+function getCodexHome() {
+  return process.env.CODEX_HOME
+    ? path.resolve(process.env.CODEX_HOME)
+    : path.join(os.homedir(), '.codex');
+}
+
+function collectConfigCandidates() {
+  const currentFilePath = fileURLToPath(import.meta.url);
+  const scriptDir = path.dirname(currentFilePath);
+
+  return [
+    process.env.BOSS_RECRUIT_SCREEN_CONFIG
+      ? path.resolve(process.env.BOSS_RECRUIT_SCREEN_CONFIG)
+      : null,
+    path.join(getCodexHome(), 'boss-recruit-mcp', 'screening-config.json'),
+    path.resolve(process.cwd(), 'boss-recruit-mcp', 'config', 'screening-config.json'),
+    path.resolve(process.cwd(), 'config', 'screening-config.json'),
+    path.resolve(scriptDir, '..', '..', '..', 'config', 'screening-config.json')
+  ].filter(Boolean);
+}
+
+function resolvePortFromConfig() {
+  for (const configPath of collectConfigCandidates()) {
+    try {
+      if (!fs.existsSync(configPath)) continue;
+      const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      const port = parsePositiveInteger(parsed?.debugPort);
+      if (port) return port;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function resolveDebugPort(explicitPort) {
+  if (explicitPort) return explicitPort;
+
+  const envPort = parsePositiveInteger(process.env.BOSS_RECRUIT_CHROME_PORT);
+  if (envPort) return envPort;
+
+  const configPort = resolvePortFromConfig();
+  if (configPort) return configPort;
+
+  return DEFAULT_DEBUG_PORT;
+}
+
 class BossSearchCLI {
   constructor() {
     const args = this.parseArgs();
+    args.port = resolveDebugPort(args.port);
     this.args = args;
-    this.searcher = new BossSearcher(args.port);
+    this.searcher = args.help ? null : new BossSearcher(args.port);
   }
 
   ensureStep(result, label) {
@@ -18,6 +81,11 @@ class BossSearchCLI {
   }
 
   async run() {
+    if (this.args.help) {
+      this.printHelp();
+      return;
+    }
+
     console.log('========================================');
     console.log('  Boss直聘搜索自动化工具');
     console.log('========================================\n');
@@ -62,6 +130,24 @@ class BossSearchCLI {
     }
   }
 
+  printHelp() {
+    console.log('Boss直聘搜索自动化工具');
+    console.log('');
+    console.log('用法:');
+    console.log('  node src/cli.js [options]');
+    console.log('');
+    console.log('选项:');
+    console.log('  -k, --keywords <text>             搜索关键词');
+    console.log('  -d, --degree <text>               学历要求（默认: 不限）');
+    console.log('  -s, --schools <list>              院校要求，支持逗号分隔');
+    console.log('  -c, --city <text>                 城市');
+    console.log('      --filter-recent-viewed <bool> 过滤近14天查看');
+    console.log(`  -p, --port <number>               Chrome调试端口（默认: ${this.args.port}）`);
+    console.log('  -h, --help                        显示帮助');
+    console.log('');
+    console.log('端口优先级: --port > BOSS_RECRUIT_CHROME_PORT > screening-config.json.debugPort > 9222');
+  }
+
   parseArgs() {
     const args = {
       keywords: '',
@@ -69,7 +155,8 @@ class BossSearchCLI {
       schools: [],
       city: null,
       filterRecentViewed: null,
-      port: 9222,
+      port: null,
+      help: false,
       experience: '不限',
       ageMin: null,
       ageMax: null
@@ -135,14 +222,16 @@ class BossSearchCLI {
       } else if (arg === '--filter-recent-viewed') {
         args.filterRecentViewed = parseBooleanArg(argv[++i]);
       } else if (arg === '--port' || arg === '-p') {
-        const port = Number.parseInt(argv[++i], 10);
-        if (Number.isFinite(port) && port > 0) {
+        const port = parsePositiveInteger(argv[++i]);
+        if (port) {
           args.port = port;
         }
+      } else if (arg === '--help' || arg === '-h') {
+        args.help = true;
       }
     }
 
-    if (!args.keywords) {
+    if (!args.help && !args.keywords) {
       console.log('⚠️  未指定搜索关键词，使用默认值');
       args.keywords = '算法工程师';
     }