@reconcrap/boss-recommend-mcp 2.0.0 → 2.0.2

package/README.md

@@ -85,6 +85,8 @@ boss-recommend-mcp list-jobs --slow-live --port 9222
 - 页面就绪（已登录且在 recommend 页）后，会先提取岗位栏全部岗位并要求用户确认本次岗位；确认后先点击岗位，再执行 search/screen
 - 在真正开始 search/screen 前，会进行最后一轮全参数总确认（岗位 + 全部筛选参数 + criteria + target_count + post_action + max_greet_count）
 - npm 全局安装后会自动执行 install：生成 skill、导出 MCP 模板，并自动尝试写入已检测到的外部 agent MCP 配置（含 Trae / trae-cn / Cursor / Claude / OpenClaw）
+- 2.x installer 会迁移已存在的 legacy Boss MCP 配置：把 `boss-recommend` 指向统一 `@reconcrap/boss-recommend-mcp`，并从同一个 `mcp.json` 中移除旧 `boss-recruit-mcp` / standalone `boss-chat` / 本地 legacy Boss 路径；写入前会生成 `.boss-mcp-migration-*.bak` 备份
+- 2.x installer 会刷新外部 agent skills：`boss-recommend-pipeline`、`boss-recruit-pipeline`、`boss-chat` 都来自当前包，旧 recruit/chat skill 会被覆盖为统一 MCP 路由
 - npm / npx 安装后会自动初始化 `screening-config.json` 模板（优先写入 workspace 的 `config/`，不可写时回退到用户目录）
 - npm 安装流程会预创建运行目录（跨平台）：`~/.boss-recommend-mcp`、`~/.boss-recommend-mcp/runs`、`~/.boss-recommend-mcp/boss-chat` 及其 `logs/runs/profiles/reports/artifacts/state`
 - `post_action` 必须在每次完整运行开始时确认一次
@@ -126,6 +128,37 @@ npm install
 node src/cli.js start
 ```
 
+### 迁移 legacy MCP / skills
+
+全局 npm 安装会自动运行 `boss-recommend-mcp install`。该安装器会在 Windows 和 macOS 上自动检测 Trae / Trae CN / OpenClaw 的常见配置目录：
+
+- Windows: `%APPDATA%\Trae*\User\mcp.json`、`%USERPROFILE%\.trae*\mcp.json`、`%USERPROFILE%\.openclaw\mcp.json`、`%APPDATA%\OpenClaw\User\mcp.json`
+- macOS: `~/Library/Application Support/Trae*/User/mcp.json`、`~/.trae*/mcp.json`、`~/.openclaw/mcp.json`、`~/Library/Application Support/OpenClaw/User/mcp.json`
+
+如果检测到 legacy Boss server entries，installer 会：
+
+- 保留非 Boss MCP server。
+- 写入统一 server：`boss-recommend -> npx -y @reconcrap/boss-recommend-mcp@<installed-version> start`
+- 从同一个 `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`。
+
+手动指定 agent：
+
+```bash
+boss-recommend-mcp install --agent trae-cn
+boss-recommend-mcp install --agent openclaw
+boss-recommend-mcp doctor --agent trae-cn
+boss-recommend-mcp doctor --agent openclaw
+```
+
+自定义路径：
+
+```bash
+BOSS_RECOMMEND_MCP_CONFIG_TARGETS="/path/to/mcp.json" boss-recommend-mcp install
+BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS="/path/to/skills" boss-recommend-mcp install
+```
+
 可选环境变量（用于跨 agent 自动配置）：
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",
@@ -31,6 +31,7 @@
     "test:core-run": "node src/test-core-run.js",
     "test:core-screening": "node src/test-core-screening.js",
     "test:core-self-heal": "node src/test-core-self-heal.js",
+    "test:installer-migration": "node src/test-installer-migration.js",
     "test:recommend-actions": "node src/test-recommend-actions.js",
     "test:recommend-domain": "node src/test-recommend-domain.js",
     "test:recommend-run-service": "node src/test-recommend-run-service.js",

package/skills/boss-chat/SKILL.md

@@ -9,7 +9,7 @@ description: "Use when users want Boss chat-page screening/outreach via the bund
 
 当用户要在 Boss 聊天页单独跑筛选/沟通任务时，必须走内置的 chat 工具，而不是要求用户单独安装 `boss-chat`。
 
-适用范围是“chat-only 会话”。若用户意图包含推荐页找人（尤其是“先推荐再沟通”），必须让 `boss-recommend-pipeline` 接管，并通过 `follow_up.chat` 完成联动。
+适用范围是“chat-only 会话”。若用户意图包含推荐页找人（尤其是“先推荐再沟通”），必须先让 `boss-recommend-pipeline` 完成推荐页任务；推荐完成后如用户仍要聊天页处理，再显式走本 skill。
 
 ## Tool Routing
 
@@ -55,7 +55,7 @@ description: "Use when users want Boss chat-page screening/outreach via the bund
 - LLM 配置必须复用 `boss-recommend-mcp` 的 `screening-config.json`；不要再向用户单独要 `baseUrl/apiKey/model`。
 - 路由护栏（强制）：
   - 只在用户明确是 chat-only 任务时使用本 skill。
-  - 只要用户提到推荐页、先找人后沟通、或需要推荐筛选阶段，禁止调用 `start_boss_chat_run`；必须交给 `boss-recommend-pipeline` 并走 `follow_up.chat`。
+  - 只要用户提到推荐页、先找人后沟通、或需要推荐筛选阶段，禁止直接调用 `start_boss_chat_run`；必须先交给 `boss-recommend-pipeline` 完成推荐页任务。
   - 不得在 recommend 任务尚未完成时并行启动独立 chat run。
 - `job` / `start_from` / `criteria` 缺一不可；缺参时只补缺口。
 - `target_count` 在 chat-only 启动前也是必填项，不能默认省略。
@@ -78,8 +78,9 @@ description: "Use when users want Boss chat-page screening/outreach via the bund
 ## Handoff Rule (Recommend -> Chat)
 
 - 若用户先运行了 recommend 流水线，并在手动状态检查时确认 recommend 已完成，且用户目标是“立即进入聊天沟通”：
-  - 若该 recommend run **未配置** `follow_up.chat`：应立即调用 `start_boss_chat_run` 启动 chat（不要等下一次 30 分钟轮询）。
-  - 若该 recommend run **已配置** `follow_up.chat`：不要再重复新开 chat run，改为查询同一父 run / 子 run 状态。
+  - 先调用 `prepare_boss_chat_run` 获取聊天页岗位列表与缺参。
+  - 显式确认 `job/start_from/target_count/criteria` 后再调用 `start_boss_chat_run`。
+  - 不要查找或依赖 `follow_up.chat`；该自动衔接路径属于 legacy-only 行为。
 
 ## Response Style
 

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

@@ -7,20 +7,20 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 
 ## Goal
 
-当用户要在 Boss 推荐页筛人时，必须走 `start_recommend_pipeline_run`，并按“两阶段确认 -> 页面就绪 -> 岗位确认 -> 最终确认 -> 执行”的顺序完成。若用户还要求筛完后自动进入聊天页 follow-up，则必须把 chat 要求放进同一个 recommend run 的 `follow_up.chat`，不要要求单独再安装 `boss-chat`。
+当用户要在 Boss 推荐页筛人时，必须走 `start_recommend_pipeline_run`，并按“两阶段确认 -> 页面就绪 -> 岗位确认 -> 最终确认 -> 执行”的顺序完成。2.0 CDP-only 路径不再支持 legacy recommend -> chat 自动衔接；若用户要聊天页筛选或求简历，必须在推荐页任务完成后显式改用 `boss-chat` 工具。
 
 ## Hard Rules (Must Follow)
 
 - **路由**
   - 语义是推荐页（`recommend/推荐页/recommend page//web/chat/recommend`）时，只能走本 skill。
-  - 语义是“推荐页找人 + 结束后沟通/聊天”时，仍然只能走本 skill；必须通过 `follow_up.chat` 挂到同一个 recommend run。
+  - 语义是“推荐页找人 + 结束后沟通/聊天”时，先完成 recommend run；不得配置 `follow_up.chat`，后续聊天任务必须显式交给 `boss-chat`。
   - 只有用户**明确**说搜索页（`search/搜索页//web/chat/search`）时，才可转 `boss-recruit-pipeline`。
   - recommend 失败时（如 `JOB_TRIGGER_NOT_FOUND/NO_RECOMMEND_IFRAME/BOSS_LOGIN_REQUIRED`）禁止降级到 recruit；先修 recommend 页面就绪/登录态。
 
 - **确认不可代填（强制）**
   - 禁止 agent 自行“设置合理参数”并代替用户确认。
   - 禁止在用户未明确回复前，把任意 `*_confirmed` 字段设为 `true`。
-  - 禁止在用户未明确回复前，自行填充 `page_scope/school_tag/degree/gender/recent_not_view/criteria/target_count/post_action/max_greet_count/job/follow_up.chat.*`。
+  - 禁止在用户未明确回复前，自行填充 `page_scope/school_tag/degree/gender/recent_not_view/criteria/target_count/post_action/max_greet_count/job`。
   - 若工具返回 `pending_questions`，必须逐项向用户提问并等待用户回复；不得跳过提问直接执行。
 
 - **岗位确认时机**
@@ -31,6 +31,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
   - `criteria` 必须是用户开放式自然语言；禁止“严格/宽松执行”等预设替代。
   - `post_action=greet` 时，必须确认 `max_greet_count`；禁止自动默认为 `target_count`。
   - 正式执行前必须 `final_confirmed=true`。
+  - 真实筛选禁止传 `detail_limit: 0`；recommend 默认必须打开候选人详情/CV。只有用户明确要求“卡片-only 调试”时，才允许同时传 `detail_limit: 0` 和 `allow_card_only_screening: true`。
 
 - **Instruction 原文锁定**
   - 首次用户需求原文锁定为 `locked_instruction_raw`。
@@ -59,27 +60,16 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 必须确认：
 
 - `job`（来自 `job_options`，必须全量展示）
-- `final_review`（岗位 + 全参数总确认；若有 `follow_up.chat`，必须把 chat summary 一并展示）
-
-## Follow-up Chat
-
-当用户要求“推荐页跑完后自动开始聊天页任务”时：
-
-- 仍然只走 `start_recommend_pipeline_run`
-- 把 chat 配置放入顶层 `follow_up.chat`
-- `follow_up.chat` 必填：
-  - `criteria`
-  - `start_from`: `unread|all`
-  - `target_count`
-- `follow_up.chat` 可选：
-  - `greeting_text`（兼容 `greetingText`，自定义首条打招呼消息）
-  - `profile`（默认 `default`）
-  - `dry_run/no_state/safe_pacing/batch_rest_enabled`
-- `greeting_text` 未传时，boss-chat 会自动按默认优先级回退：本次显式值 > profile 历史值 > 内置默认招呼语
-- `job` / `port` 继承 recommend run 上下文；不要单独向用户再要一份
-- LLM 配置固定复用 recommend 的 `screening-config.json`；不要单独向用户再要 `baseUrl/apiKey/model`
-- 缺少 `follow_up.chat` 必填项时，按 `pending_questions` 补缺口；不要额外发起一轮独立的 chat 确认流程
-- 不允许提前调用 `start_boss_chat_run`；必须等 recommend run 完成并由 `follow_up.chat` 自动衔接
+- `final_review`（岗位 + 全参数总确认）
+
+## Chat Handoff
+
+当用户要求“推荐页跑完后继续聊天页任务”时：
+
+- 本次 recommend run 只提交 recommend 参数，不要写 `follow_up.chat`。
+- recommend 完成并由用户确认要继续后，切换到 `boss-chat` skill。
+- `boss-chat` 会重新调用 `prepare_boss_chat_run` 获取聊天页岗位列表，并显式确认 `job/start_from/target_count/criteria`。
+- 不得在 recommend run 尚未完成时并行启动 `start_boss_chat_run`。
 
 ## Closed vs Open Questions
 
@@ -104,7 +94,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 - 关键输入：
   - `confirmation`：`page_confirmed/page_value/filters_confirmed/school_tag_confirmed.../job_confirmed/job_value/final_confirmed`
   - `overrides`：`page_scope/school_tag/degree/gender/recent_not_view/criteria/job/target_count/post_action/max_greet_count`
-  - `follow_up.chat`：仅在“recommend 完成后自动进入 boss-chat”场景传入
+  - 不要传 `follow_up.chat`；该路径属于 legacy-only 行为
 
 最小策略：
 
@@ -116,16 +106,13 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 ## Async Run Policy
 
 - 用户未明确要求“持续跟进”时，不自动 `sleep + get_recommend_pipeline_run`。
-- 若 run 已进入 `chat_followup`，默认也不得自动轮询子 chat 状态；除非用户明确指定轮询频率/间隔。
 - 用户要求查进度时，再用 `get_recommend_pipeline_run`。
 - **长任务轮询节奏（强制）**：
-  - 推荐+聊天联动任务可能运行数小时，禁止高频轮询。
+  - 推荐任务可能运行数小时，禁止高频轮询。
   - 默认最小轮询间隔为 **30 分钟**（除非用户明确要求更频繁）。
   - 若刚启动 run（拿到 `ACCEPTED + run_id`），不得立即进入连续轮询。
 - `pause/resume/cancel` 必须复用同一 `run_id`，不要重复 `start`。
-- **完成后衔接（强制）**：
-  - 若本次 run 已带 `follow_up.chat`：chat 由同一 run 自动衔接，禁止再单独重复启动 chat run。
-  - 若用户手动触发 `get_recommend_pipeline_run` 且发现 recommend 已完成、而当前会话目标是“继续聊天沟通”且尚未启动 chat：应立即启动 chat（无需等待下一轮 30 分钟轮询）。
+- **完成后衔接（强制）**：若用户手动触发 `get_recommend_pipeline_run` 且发现 recommend 已完成、而当前会话目标是“继续聊天沟通”且尚未启动 chat：切换到 `boss-chat` 并重新走 chat-only 参数确认。
 
 ## Preflight and Recovery
 
@@ -150,7 +137,7 @@ description: "Use when users want Boss recommend-page filtering/screening via bo
 
 MCP 不可用时：
 
-`npx -y @reconcrap/boss-recommend-mcp@latest run --instruction "..." [--confirmation-json '{...}'] [--overrides-json '{...}'] [--follow-up-json '{...}']`
+`npx -y @reconcrap/boss-recommend-mcp@latest run --instruction "..." [--confirmation-json '{...}'] [--overrides-json '{...}']`
 
 禁止错误回退：
 

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

@@ -0,0 +1,17 @@
+# boss-recruit-pipeline
+
+Bundled search/recruit-page automation skill shipped with `boss-recommend-mcp` 2.x.
+
+Package: `@reconcrap/boss-recommend-mcp` (npm)
+Source: `https://github.com/reconcrap-cpu/boss-recommend-mcp`
+
+This skill intentionally replaces legacy `boss-recruit-mcp` skill installs. It routes Boss search/recruit tasks to the unified CDP-only MCP tools:
+
+- `run_recruit_pipeline`
+- `start_recruit_pipeline_run`
+- `get_recruit_pipeline_run`
+- `pause_recruit_pipeline_run`
+- `resume_recruit_pipeline_run`
+- `cancel_recruit_pipeline_run`
+
+Do not call the old `@reconcrap/boss-recruit-mcp` package from this skill.

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

@@ -0,0 +1,55 @@
+---
+name: "boss-recruit-pipeline"
+description: "Use when users want Boss search/recruit-page screening via the unified boss-recommend-mcp package. Replaces the legacy boss-recruit-mcp skill."
+---
+
+# Boss Recruit Pipeline Skill
+
+## Goal
+
+当用户要在 Boss 搜索页 / 招聘搜索页筛人时，必须走 `@reconcrap/boss-recommend-mcp` 2.x 内置的 recruit/search MCP 工具，不要安装或调用旧的 `@reconcrap/boss-recruit-mcp`。
+
+## Tool Routing
+
+- 同步启动：`run_recruit_pipeline`
+- 异步启动：`start_recruit_pipeline_run`
+- 查询进度：`get_recruit_pipeline_run`
+- 暂停：`pause_recruit_pipeline_run`
+- 继续：`resume_recruit_pipeline_run`
+- 取消：`cancel_recruit_pipeline_run`
+
+## Hard Rules
+
+- 只在用户明确说搜索页、search、recruit、招聘搜索、`/web/chat/search` 时使用本 skill。
+- 如果用户说推荐页、recommend、`/web/chat/recommend`，必须交给 `boss-recommend-pipeline`。
+- 如果用户说聊天页、未读、全部聊天、求简历，必须交给 `boss-chat`。
+- 禁止调用旧包：`@reconcrap/boss-recruit-mcp`、`boss-recruit-mcp`、旧本地 recruit repo、旧 vendor 脚本。
+- 浏览器自动化必须走 CDP-only 2.x MCP 工具；不得要求用户启用 legacy page-JS 或 `Runtime.evaluate` 路径。
+- 若用户未提供岗位，必须先询问岗位。搜索页岗位选择在关键词输入框旁边；不要猜测默认岗位。
+- 若用户提供城市、学历、学校、关键词、过滤已看、人选目标数、筛选条件、post action、max greet 等参数，必须逐项传入或确认。
+- `post_action=greet` 时必须确认 `max_greet_count`；不要默认等于 `target_count`。
+- 搜索页和推荐页一样支持多选筛选条件；不要把多选降级成单选。
+
+## Required Inputs
+
+- `job`
+- `keyword` 或用户明确的搜索意图
+- `criteria`
+- `target_count`
+
+常用可选项：
+
+- `city`
+- `degree`
+- `school_tag`
+- `recent_not_view`
+- `post_action`
+- `max_greet_count`
+- `port`
+
+## Response Style
+
+- 用结构化中文确认参数。
+- 缺参时只补缺口，不要改写用户的筛选条件。
+- 拿到 `ACCEPTED + run_id` 后默认停止本轮，不主动高频轮询。
+- 查询、暂停、恢复、取消时必须复用同一个 `run_id`。

package/src/cli.js

@@ -35,7 +35,9 @@ const currentFilePath = fileURLToPath(import.meta.url);
 const packageRoot = path.resolve(path.dirname(currentFilePath), "..");
 const packageJsonPath = path.join(packageRoot, "package.json");
 const skillName = "boss-recommend-pipeline";
-const bundledSkillNames = [skillName, "boss-chat"];
+const recruitSkillName = "boss-recruit-pipeline";
+const chatSkillName = "boss-chat";
+const bundledSkillNames = [skillName, recruitSkillName, chatSkillName];
 const exampleConfigPath = path.join(packageRoot, "config", "screening-config.example.json");
 const bossUrl = "https://www.zhipin.com/web/chat/recommend";
 const bossLoginUrl = "https://www.zhipin.com/web/user/?ka=bticket";
@@ -724,7 +726,7 @@ function buildMcpLaunchConfig(options = {}) {
     ? args
     : command === "boss-recommend-mcp"
       ? ["start"]
-      : buildDefaultMcpArgs();
+      : buildDefaultMcpArgs(options);
   const launchConfig = { command, args: launchArgs };
   if (env && typeof env === "object" && !Array.isArray(env) && Object.keys(env).length > 0) {
     launchConfig.env = env;
@@ -793,24 +795,56 @@ function parseAgentTargets(rawValue) {
   return unique;
 }
 
+function getExternalAppSupportBaseDirs() {
+  const home = os.homedir();
+  if (process.platform === "win32") {
+    return dedupePaths([
+      process.env.APPDATA || "",
+      path.join(home, "AppData", "Roaming")
+    ]);
+  }
+  if (process.platform === "darwin") {
+    return dedupePaths([
+      path.join(home, "Library", "Application Support")
+    ]);
+  }
+  return dedupePaths([
+    process.env.XDG_CONFIG_HOME || "",
+    path.join(home, ".config")
+  ]);
+}
+
+function buildAppUserPaths({ dirNames = [], tail = [] } = {}) {
+  const paths = [];
+  for (const baseDir of getExternalAppSupportBaseDirs()) {
+    const discovered = discoverAppDataDirsByPattern(baseDir, /^trae(?:[\s\-_]?cn)?$/i);
+    const names = dedupeLower([...dirNames, ...discovered]);
+    for (const dirName of names) {
+      paths.push(path.join(baseDir, dirName, "User", ...tail));
+    }
+  }
+  return dedupePaths(paths);
+}
+
 function getKnownExternalMcpConfigPathsByAgent() {
   const home = os.homedir();
-  const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
-  const traeDirNames = dedupeLower([
+  const appBases = getExternalAppSupportBaseDirs();
+  const traeDirNames = [
     "Trae",
     "Trae CN",
     "TraeCN",
     "trae-cn",
-    "trae_cn",
-    ...discoverAppDataDirsByPattern(appData, /^trae(?:[\s\-_]?cn)?$/i)
-  ]);
-  const traeConfigPaths = traeDirNames.map((dir) => path.join(appData, dir, "User", "mcp.json"));
+    "trae_cn"
+  ];
+  const traeConfigPaths = buildAppUserPaths({ dirNames: traeDirNames, tail: ["mcp.json"] });
+  const cursorConfigPaths = appBases.map((baseDir) => path.join(baseDir, "Cursor", "User", "mcp.json"));
+  const openClawConfigPaths = appBases.map((baseDir) => path.join(baseDir, "OpenClaw", "User", "mcp.json"));
   return {
-    cursor: [path.join(appData, "Cursor", "User", "mcp.json"), path.join(home, ".cursor", "mcp.json")],
+    cursor: [...cursorConfigPaths, path.join(home, ".cursor", "mcp.json")],
     trae: [...traeConfigPaths, path.join(home, ".trae", "mcp.json"), path.join(home, ".trae-cn", "mcp.json")],
     "trae-cn": [...traeConfigPaths, path.join(home, ".trae-cn", "mcp.json"), path.join(home, ".trae", "mcp.json")],
     claude: [path.join(home, ".claude", "mcp.json")],
-    openclaw: [path.join(home, ".openclaw", "mcp.json")]
+    openclaw: [path.join(home, ".openclaw", "mcp.json"), ...openClawConfigPaths]
   };
 }
 
@@ -837,21 +871,40 @@ function mergeMcpServerConfigFile(filePath, options = {}) {
       ? current.mcpServers
       : {};
   const existingEntry = existingServers[serverName];
+  const retainedServers = {};
+  const migratedLegacyServers = [];
+  for (const [name, config] of Object.entries(existingServers)) {
+    if (name === serverName) continue;
+    if (isBossMcpServerEntry(name, config)) {
+      migratedLegacyServers.push(name);
+      continue;
+    }
+    retainedServers[name] = config;
+  }
   const merged = {
     ...current,
     mcpServers: {
-      ...existingServers,
+      ...retainedServers,
       [serverName]: launchConfig
     }
   };
 
   ensureDir(path.dirname(filePath));
+  const before = pathExists(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+  const next = JSON.stringify(merged, null, 2);
+  let backupFile = null;
+  if (before && before.trim() !== next.trim()) {
+    backupFile = `${filePath}.boss-mcp-migration-${new Date().toISOString().replace(/[:.]/g, "-")}.bak`;
+    fs.writeFileSync(backupFile, before, "utf8");
+  }
   fs.writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf8");
-  const updated = JSON.stringify(existingEntry || null) !== JSON.stringify(launchConfig);
+  const updated = before.trim() !== next.trim() || JSON.stringify(existingEntry || null) !== JSON.stringify(launchConfig);
   return {
     file: filePath,
     server: serverName,
-    updated
+    updated,
+    migrated_legacy_servers: migratedLegacyServers,
+    backup_file: backupFile
   };
 }
 
@@ -867,7 +920,9 @@ function installExternalMcpConfigs(options = {}) {
         file: target,
         server: merged.server,
         created: !existed,
-        updated: merged.updated
+        updated: merged.updated,
+        migrated_legacy_servers: merged.migrated_legacy_servers,
+        backup_file: merged.backup_file
       });
     } catch (error) {
       skipped.push({
@@ -881,25 +936,30 @@ function installExternalMcpConfigs(options = {}) {
 
 function getKnownExternalSkillBaseDirsByAgent() {
   const home = os.homedir();
-  const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
-  const traeDirNames = dedupeLower([
+  const appBases = getExternalAppSupportBaseDirs();
+  const traeDirNames = [
     "Trae",
     "Trae CN",
     "TraeCN",
     "trae-cn",
-    "trae_cn",
-    ...discoverAppDataDirsByPattern(appData, /^trae(?:[\s\-_]?cn)?$/i)
-  ]);
-  const traeSkillDirs = traeDirNames.map((dir) => path.join(appData, dir, "User", "skills"));
+    "trae_cn"
+  ];
+  const traeSkillDirs = buildAppUserPaths({ dirNames: traeDirNames, tail: ["skills"] });
+  const cursorSkillDirs = appBases.map((baseDir) => path.join(baseDir, "Cursor", "User", "skills"));
+  const openClawSkillDirs = appBases.map((baseDir) => path.join(baseDir, "OpenClaw", "User", "skills"));
   return {
-    cursor: [path.join(home, ".cursor", "skills"), path.join(appData, "Cursor", "User", "skills")],
+    cursor: [path.join(home, ".cursor", "skills"), ...cursorSkillDirs],
     trae: [path.join(home, ".trae", "skills"), path.join(home, ".trae-cn", "skills"), ...traeSkillDirs],
     "trae-cn": [path.join(home, ".trae-cn", "skills"), path.join(home, ".trae", "skills"), ...traeSkillDirs],
     claude: [path.join(home, ".claude", "skills")],
-    openclaw: [path.join(home, ".openclaw", "skills"), path.join(appData, "OpenClaw", "User", "skills")]
+    openclaw: [path.join(home, ".openclaw", "skills"), ...openClawSkillDirs]
   };
 }
 
+function serializeMcpLaunchConfig(launchConfig) {
+  return JSON.stringify(launchConfig || {}).toLowerCase().replace(/\\/g, "/");
+}
+
 function isRecommendMcpLaunchConfig(launchConfig) {
   if (!launchConfig || typeof launchConfig !== "object") return false;
   const command = String(launchConfig.command || "").toLowerCase();
@@ -913,14 +973,33 @@ function isRecommendMcpLaunchConfig(launchConfig) {
   );
 }
 
+function isBossMcpServerEntry(name, launchConfig) {
+  const lowerName = String(name || "").toLowerCase();
+  const serialized = serializeMcpLaunchConfig(launchConfig);
+  return (
+    /boss[-_\s]?(recommend|recruit|chat)/i.test(lowerName)
+    || serialized.includes(recommendMcpPackageName.toLowerCase())
+    || serialized.includes("@reconcrap/boss-recruit-mcp")
+    || serialized.includes("@reconcrap/boss-chat")
+    || serialized.includes("boss-recommend-mcp")
+    || serialized.includes("boss-recruit-mcp")
+    || serialized.includes("boss-chat")
+    || serialized.includes("boss recommend pipeline")
+    || serialized.includes("boss recruit pipeline")
+  );
+}
+
 function inspectMcpServerEntries(filePath) {
   if (!pathExists(filePath)) {
     return {
       exists: false,
       has_boss_recommend: false,
       has_boss_recruit: false,
+      has_boss_chat: false,
       recommend_server_names: [],
-      recruit_server_names: []
+      recruit_server_names: [],
+      chat_server_names: [],
+      boss_server_names: []
     };
   }
   const parsed = readJsonObjectFileSafe(filePath);
@@ -929,8 +1008,13 @@ function inspectMcpServerEntries(filePath) {
     : {};
   const recommendNames = [];
   const recruitNames = [];
+  const chatNames = [];
+  const bossNames = [];
   for (const [name, config] of Object.entries(servers)) {
     const lowerName = String(name || "").toLowerCase();
+    if (isBossMcpServerEntry(name, config)) {
+      bossNames.push(name);
+    }
     if (isRecommendMcpLaunchConfig(config) || lowerName.includes("boss-recommend")) {
       recommendNames.push(name);
     }
@@ -942,13 +1026,23 @@ function inspectMcpServerEntries(filePath) {
     ) {
       recruitNames.push(name);
     }
+    if (
+      lowerName.includes("boss-chat")
+      || serialized.includes("@reconcrap/boss-chat")
+      || serialized.includes("boss-chat")
+    ) {
+      chatNames.push(name);
+    }
   }
   return {
     exists: true,
     has_boss_recommend: recommendNames.length > 0,
     has_boss_recruit: recruitNames.length > 0,
+    has_boss_chat: chatNames.length > 0,
     recommend_server_names: recommendNames,
-    recruit_server_names: recruitNames
+    recruit_server_names: recruitNames,
+    chat_server_names: chatNames,
+    boss_server_names: bossNames
   };
 }
 
@@ -972,9 +1066,16 @@ function mirrorSkillToExternalDirs(options = {}) {
     for (const bundledSkillName of bundledSkillNames) {
       try {
         const targetDir = path.join(baseDir, bundledSkillName);
+        const legacyBeforeCopy = isLegacyBossSkillDir(targetDir);
         ensureDir(path.dirname(targetDir));
         fs.cpSync(getSkillSourceDir(bundledSkillName), targetDir, { recursive: true, force: true });
-        mirrored.push({ base_dir: baseDir, target_dir: targetDir, skill: bundledSkillName });
+        fs.writeFileSync(path.join(targetDir, ".installed-version"), `${packageVersion}\n`, "utf8");
+        mirrored.push({
+          base_dir: baseDir,
+          target_dir: targetDir,
+          skill: bundledSkillName,
+          replaced_legacy: legacyBeforeCopy
+        });
       } catch (error) {
         skipped.push({ base_dir: baseDir, skill: bundledSkillName, reason: error.message });
       }
@@ -983,6 +1084,23 @@ function mirrorSkillToExternalDirs(options = {}) {
   return { baseDirs, mirrored, skipped };
 }
 
+function isLegacyBossSkillDir(targetDir) {
+  const skillFile = path.join(targetDir, "SKILL.md");
+  if (!pathExists(skillFile)) return false;
+  try {
+    const content = fs.readFileSync(skillFile, "utf8").toLowerCase();
+    return (
+      content.includes("@reconcrap/boss-recruit-mcp")
+      || content.includes("@reconcrap/boss-chat")
+      || content.includes("boss-screen-cli")
+      || content.includes(`runtime.${"evaluate"}`)
+      || content.includes("page js")
+    );
+  } catch {
+    return false;
+  }
+}
+
 function syncSkillAssets(options = {}) {
   const force = options.force === true;
   const results = [];
@@ -2180,8 +2298,8 @@ function printHelp() {
   console.log("  boss-recommend-mcp run          Disabled until the one-shot CLI has a CDP-only async replacement");
   console.log("  boss-recommend-mcp list-jobs    CDP-only list of exact recommend job names for cron/one-shot inputs");
   console.log("  boss-recommend-mcp chat <subcommand>  Run CDP-only boss-chat health/prepare/status commands");
-  console.log("  boss-recommend-mcp install      Install skill/MCP templates and auto-init screening-config.json (supports --agent trae-cn/cursor/...)");
-  console.log("  boss-recommend-mcp install-skill Install bundled Codex skills");
+  console.log("  boss-recommend-mcp install      Install/migrate skills and MCP configs; replaces legacy Boss MCP routes (supports --agent trae-cn/openclaw/...)");
+  console.log("  boss-recommend-mcp install-skill Install bundled Codex skills (recommend/recruit/chat)");
   console.log("  boss-recommend-mcp init-config  Create screening-config.json if missing (prefer workspace config/, fallback ~/.boss-recommend-mcp)");
   console.log("  boss-recommend-mcp config set   Write baseUrl/apiKey/model (prefer workspace config/, fallback ~/.boss-recommend-mcp)");
   console.log("  boss-recommend-mcp set-port     Persist preferred Chrome debug port to screening-config.json");
@@ -2257,7 +2375,14 @@ async function installAll(options = {}) {
     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})`);
+      const migrated = Array.isArray(item.migrated_legacy_servers) && item.migrated_legacy_servers.length > 0
+        ? `; migrated legacy servers: ${item.migrated_legacy_servers.join(", ")}`
+        : "";
+      const backup = item.backup_file ? `; backup: ${item.backup_file}` : "";
+      console.log(`- ${item.file} (${action}${migrated}${backup})`);
+    }
+    for (const item of externalMcpResult.skipped) {
+      console.warn(`External MCP warning: ${item.file} -> ${item.reason}`);
     }
   } else {
     console.log("No external MCP config target detected. Set BOSS_RECOMMEND_MCP_CONFIG_TARGETS to auto-configure custom agents.");
@@ -2265,7 +2390,10 @@ async function installAll(options = {}) {
   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}`);
+      console.log(`- ${item.target_dir}${item.replaced_legacy ? " (replaced legacy skill)" : ""}`);
+    }
+    for (const item of externalSkillResult.skipped) {
+      console.warn(`External skill warning: ${item.base_dir} / ${item.skill} -> ${item.reason}`);
     }
   } else {
     console.log("No external skill dir detected. Set BOSS_RECOMMEND_EXTERNAL_SKILL_DIRS to mirror skill for non-Codex agents.");
@@ -2635,8 +2763,10 @@ export const __testables = {
   getBossChatCliRunTarget,
   getDefaultMcpPackageSpecifier,
   getRunFollowUp,
+  inspectMcpServerEntries,
   installSkill,
   isInstalledPackageRoot,
+  mergeMcpServerConfigFile,
   resolveBossChatRuntimeLayout: resolveCdpBossChatRuntimeLayout,
   runBossChatCliCommand,
   runPipelineOnce

package/src/domains/recommend/run-service.js

@@ -332,7 +332,7 @@ export async function runRecommendWorkflow({
   fallbackPageScope = "recommend",
   filter = {},
   maxCandidates = 5,
-  detailLimit = 0,
+  detailLimit,
   closeDetail = true,
   delayMs = 0,
   cardTimeoutMs = 10000,
@@ -362,7 +362,7 @@ export async function runRecommendWorkflow({
   const normalizedFallbackPageScope = normalizeRecommendPageScope(fallbackPageScope) || "recommend";
   const postActionEnabled = normalizedPostAction !== "none";
   const limit = Math.max(1, Number(maxCandidates) || 1);
-  const detailCountLimit = Math.max(0, Number(detailLimit) || 0);
+  const detailCountLimit = detailLimit == null ? limit : Math.max(0, Number(detailLimit) || 0);
   const effectiveDetailLimit = postActionEnabled ? limit : detailCountLimit;
   const networkRecorder = effectiveDetailLimit > 0
     ? createRecommendDetailNetworkRecorder(client)
@@ -785,7 +785,7 @@ export function createRecommendRunService({
     fallbackPageScope = "recommend",
     filter = {},
     maxCandidates = 5,
-    detailLimit = 0,
+    detailLimit,
     closeDetail = true,
     delayMs = 0,
     cardTimeoutMs = 10000,
@@ -814,6 +814,8 @@ export function createRecommendRunService({
     const normalizedPostAction = normalizeRecommendPostAction(postAction) || "none";
     const requestedPageScope = normalizeRecommendPageScope(pageScope) || "recommend";
     const normalizedFallbackPageScope = normalizeRecommendPageScope(fallbackPageScope) || "recommend";
+    const candidateLimit = Math.max(1, Number(maxCandidates) || 1);
+    const normalizedDetailLimit = detailLimit == null ? candidateLimit : Math.max(0, Number(detailLimit) || 0);
     return manager.startRun({
       name,
       context: {
@@ -825,7 +827,7 @@ export function createRecommendRunService({
         fallback_page_scope: normalizedFallbackPageScope,
         filter: normalizedFilter,
         max_candidates: maxCandidates,
-        detail_limit: detailLimit,
+        detail_limit: normalizedDetailLimit,
         close_detail: closeDetail,
         cv_acquisition_mode: cvAcquisitionMode,
         max_image_pages: maxImagePages,
@@ -846,7 +848,7 @@ export function createRecommendRunService({
       },
       progress: {
         card_count: 0,
-        target_count: Math.max(1, Number(maxCandidates) || 1),
+        target_count: candidateLimit,
         processed: 0,
         screened: 0,
         detail_opened: 0,
@@ -864,7 +866,7 @@ export function createRecommendRunService({
         fallbackPageScope: normalizedFallbackPageScope,
         filter: normalizedFilter,
         maxCandidates,
-        detailLimit,
+        detailLimit: normalizedDetailLimit,
         closeDetail,
         delayMs,
         cardTimeoutMs,

package/src/domains/recruit/cards.js

@@ -64,4 +64,3 @@ export async function readFirstRecruitCardCandidate(client, frameNodeId, options
     candidate
   };
 }
-

package/src/domains/recruit/roots.js

@@ -65,4 +65,3 @@ export async function queryFirstAcrossRoots(client, roots, selectors) {
   }
   return null;
 }
-

package/src/index.js

@@ -540,7 +540,11 @@ function createRunInputSchema() {
       detail_limit: {
         type: "integer",
         minimum: 0,
-        description: "打开详情的人数上限；默认 0，0 表示只用卡片信息"
+        description: "打开详情/CV 的人数上限；默认跟随 target_count/max_candidates。生产筛选不应传 0；只有 allow_card_only_screening=true 时才会接受 0 作为调试卡片-only 模式"
+      },
+      allow_card_only_screening: {
+        type: "boolean",
+        description: "高级调试开关；默认 false。只有显式为 true 时，recommend 才会尊重 detail_limit=0 并只用卡片信息筛选"
       },
       delay_ms: {
         type: "integer",

package/src/recommend-mcp.js

@@ -75,6 +75,15 @@ function parseNonNegativeInteger(raw, fallback) {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
 }
 
+function resolveRecommendDetailLimit(args = {}, normalized = {}) {
+  const fallback = parsePositiveInteger(normalized.targetCount, 5);
+  const requested = parseNonNegativeInteger(args.detail_limit, fallback);
+  if (requested === 0 && args.allow_card_only_screening !== true) {
+    return fallback;
+  }
+  return requested;
+}
+
 function methodSummary(methodLog = []) {
   const summary = {};
   for (const entry of methodLog || []) {
@@ -867,7 +876,7 @@ function getRunOptions(args, parsed, normalized, session) {
     fallbackPageScope: "recommend",
     filter: normalized.filter,
     maxCandidates: normalized.targetCount,
-    detailLimit: parseNonNegativeInteger(args.detail_limit, 0),
+    detailLimit: resolveRecommendDetailLimit(args, normalized),
     closeDetail: true,
     delayMs: parseNonNegativeInteger(args.delay_ms, 0),
     cardTimeoutMs: slowLive ? 180000 : 90000,