hunter-mate 0.1.3 → 0.1.5

package/dist/commands/doctor.js

@@ -9,6 +9,7 @@ import { runInstall } from './install.js';
 import { runExtensionCheck } from './extension.js';
 import { checkNativeModules } from '../native-check.js';
 import { getCliLogger } from '../logger.js';
+import { getToken } from '../keychain.js';
 const B = {
     reset: '\x1b[0m',
     bold: '\x1b[1m',
@@ -18,6 +19,32 @@ const B = {
     cyan: '\x1b[36m',
     magenta: '\x1b[35m',
 };
+/**
+ * 调用 server /doctor/run 统一入口。
+ * 失败时返回 null,调用方决定如何处理。
+ */
+export async function runDoctorChecks(opts) {
+    const config = loadConfig();
+    const token = await getToken().catch(() => undefined);
+    const checks = opts.checks && opts.checks.length ? opts.checks : undefined;
+    const timeout = opts.timeout ?? 60_000;
+    try {
+        const { data } = await axios.post(`${config.serverUrl}/doctor/run`, {
+            checks,
+            mode: opts.fix ? 'repair' : 'check',
+            dryRun: opts.dryRun === true,
+        }, {
+            timeout,
+            headers: token ? { Authorization: `UTOKEN ${token}` } : {},
+        });
+        return data;
+    }
+    catch (e) {
+        const message = e?.response?.data?.message || e.message || String(e);
+        getCliLogger().warn('doctor:checks:failed', { error: message, fix: opts.fix, checks });
+        return null;
+    }
+}
 /** 对应 ChromePilot doctor: 全链路健康检查 — 带 auto-heal, 无感启动 server/安装扩展 */
 export async function runDoctor(opts) {
     const checks = [];
@@ -25,13 +52,21 @@ export async function runDoctor(opts) {
     const healed = [];
     const actions = [];
     const autoHeal = opts.autoHeal !== false; // default true
-    const interactive = opts.interactive !== false; // default true
+    const fix = opts.fix === true;
     // ── Banner (human 模式) ──
     if (!opts.json) {
         console.log(`\n${B.bold}${B.cyan}╭─────────────────────────────────────────────╮${B.reset}`);
         console.log(`${B.bold}${B.cyan}│   HunterMate Doctor · 环境全链路自检与自愈   │${B.reset}`);
         console.log(`${B.bold}${B.cyan}╰─────────────────────────────────────────────╯${B.reset}\n`);
     }
+    // ── 0) Node 版本(Windows better-sqlite3 预构建友好度) ──
+    const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+    const nodeVersionFriendly = [20, 22, 24].includes(nodeMajor);
+    checks.push({
+        key: 'node_version',
+        status: nodeVersionFriendly ? 'ok' : 'warn',
+        detail: `Node ${process.versions.node}${nodeVersionFriendly ? '' : ' (hunter-mate 预构建包对 Node 20/22/24 支持最好,Windows 无编译器时建议切到 Node 22 LTS)'}`,
+    });
     // ── 1) 目录 & token ──
     let initResult = null;
     try {
@@ -184,7 +219,7 @@ export async function runDoctor(opts) {
                     if (!opts.json) {
                         console.log(`${B.magenta}→  hunter-mate 正在为你打开扩展所在目录...${B.reset}`);
                     }
-                    open(initResult.extensionDir).catch(() => { });
+                    open(path.dirname(initResult.extensionDir)).catch(() => { });
                     healed.push('open_ext_dir');
                 }
                 if (!opts.json) {
@@ -197,9 +232,11 @@ export async function runDoctor(opts) {
         }
     }
     // ── 5) 登录态(不强制) ──
+    let loggedIn = false;
     try {
         const { getToken } = await import('../keychain.js');
         const token = await getToken();
+        loggedIn = !!token;
         checks.push({
             key: 'auth',
             status: token ? 'ok' : 'warn',
@@ -211,6 +248,35 @@ export async function runDoctor(opts) {
     catch (e) {
         checks.push({ key: 'auth', status: 'skip', detail: `跳过(keychain 读取失败): ${e.message}` });
     }
+    // ── 6) 数据面 doctor checks ──
+    let data = null;
+    if (serverUp) {
+        if (!opts.json) {
+            console.log(`\n${B.bold}${B.cyan}→  正在运行数据面检查${fix ? ' (repair 模式)' : ' (只读 check 模式)'}...${B.reset}`);
+        }
+        data = await runDoctorChecks({
+            fix,
+            checks: opts.checks,
+            json: opts.json,
+            timeout: 120_000,
+        });
+        if (data) {
+            for (const c of data.checks) {
+                const status = c.ok ? 'ok' : c.severity === 'error' ? 'fail' : 'warn';
+                checks.push({
+                    key: `data_${c.id}`,
+                    status,
+                    detail: c.message || c.description,
+                });
+            }
+        }
+        else {
+            checks.push({ key: 'data_doctor', status: 'warn', detail: '无法连接 /doctor/run (server 可能尚未就绪)' });
+        }
+    }
+    else {
+        checks.push({ key: 'data_doctor', status: 'skip', detail: 'server 未运行,跳过数据面检查' });
+    }
     // ── Summary ──
     const anyFail = checks.some((c) => c.status === 'fail');
     const anyWarn = checks.some((c) => c.status === 'warn');
@@ -247,7 +313,14 @@ export async function runDoctor(opts) {
             console.log(`\n${B.bold}${B.red}✗  环境未就绪, 请按上方引导完成修复后重试。${B.reset}\n`);
         }
     }
-    return { summary, checks, hints, healed, actions };
+    return {
+        summary, checks, hints, healed, actions, data,
+        nodeVersion: process.versions.node,
+        serverRunning: serverUp,
+        extensionInstalled: extInstalled,
+        extensionConnected: extConnected,
+        loggedIn,
+    };
 }
 /** 友好中文引导 — 当环境不完备时给用户清晰的操作步骤 */
 function showFriendlyGuide(extInstalled, extConnected, serverUp, healed, extDir) {
@@ -261,21 +334,24 @@ function showFriendlyGuide(extInstalled, extConnected, serverUp, healed, extDir)
         console.log(`   hunter-mate 已尝试自动启动。若持续失败请手动执行:`);
         console.log(`   ${B.bold}hunter-mate start -f${B.reset}  (前台模式可看日志)\n`);
     }
+    const extParentDir = path.dirname(extDir);
+    const extFolderName = path.basename(extDir);
     if (!extInstalled) {
         console.log(`${B.bold}${B.yellow}⚠  Hunter Mate Chrome 扩展尚未安装${B.reset}`);
         console.log(`   步骤: hunter-mate 已自动把扩展文件复制到:`);
         console.log(`   ${B.cyan}${extDir}${B.reset}`);
+        console.log(`   并已打开扩展所在目录: ${B.cyan}${extParentDir}${B.reset}`);
         console.log(`   ${B.bold}接下来需要你手动在 Chrome 中加载(Chrome 安全策略限制命令行自动化):${B.reset}`);
         console.log(`   ${B.magenta}① 在 Chrome 地址栏输入:${B.reset}  chrome://extensions`);
         console.log(`   ${B.magenta}② 打开右上角「开发者模式」开关${B.reset}`);
-        console.log(`   ${B.magenta}③ 点击「加载已解压的扩展程序」${B.reset}`);
-        console.log(`   ${B.magenta}④ 选择上面的目录:${B.reset}  ${B.cyan}${extDir}${B.reset}`);
-        console.log(`   ${B.magenta}⑤ Chrome 工具栏应出现 Hunter Mate 图标${B.reset}\n`);
+        console.log(`   ${B.magenta}③ 把 ${B.bold}${extFolderName}${B.reset} 文件夹拖到 chrome://extensions 页面里${B.reset}`);
+        console.log(`      (也可以点击「加载已解压的扩展程序」后选择 ${B.cyan}${extDir}${B.reset})`);
+        console.log(`   ${B.magenta}④ Chrome 工具栏应出现 Hunter Mate 图标,侧栏显示「已连接」${B.reset}\n`);
     }
     if (extInstalled && !extConnected) {
         console.log(`${B.bold}${B.yellow}⚠  扩展已安装但尚未连接到 Server${B.reset}`);
         console.log(`   hunter-mate 已自动帮你打开了:`);
-        console.log(`   · 扩展所在目录: ${B.cyan}${extDir}${B.reset}`);
+        console.log(`   · 扩展所在目录: ${B.cyan}${extParentDir}${B.reset}`);
         console.log(`   · Chrome 扩展管理页: ${B.cyan}chrome://extensions${B.reset}`);
         console.log(`   ${B.bold}请确认以下几点:${B.reset}`);
         console.log(`   ${B.magenta}① 扩展已在 chrome://extensions 中「已开启」${B.reset} (灰色开关变蓝色)`);
@@ -304,14 +380,110 @@ export const doctorCommand = new Command('doctor')
     .option('--json', '仅以 JSON 输出检查结果与建议(跳过引导文案)')
     .option('--no-auto-heal', '禁用自动修复(仅检查并给出建议, 不自动启动/安装)')
     .option('--no-interactive', '无交互模式(不打印友好引导, 仅输出结构化结果)')
+    .option('--fix', '执行可修复的数据检查(默认只读 check)')
+    .option('--checks <ids>', '只跑指定检查,逗号分隔(如 linkedin-dupes)', (val) => val.split(',').map((s) => s.trim()).filter(Boolean))
+    .option('--list', '列出 server 上注册的数据检查项')
     .action(async (opts) => {
+    if (opts.list) {
+        const config = loadConfig();
+        try {
+            const { data } = await axios.get(`${config.serverUrl}/doctor/checks`, { timeout: 10_000 });
+            if (opts.json) {
+                console.log(JSON.stringify(data, null, 2));
+            }
+            else {
+                console.log(`\n${B.bold}${B.cyan}已注册 Doctor 检查项:${B.reset}`);
+                for (const c of data) {
+                    const fixTag = c.fixable ? `${B.green}[可修复]${B.reset}` : `${B.yellow}[只读]${B.reset}`;
+                    console.log(`  ${fixTag} ${B.bold}${c.id}${B.reset} (${c.severity})`);
+                    console.log(`     ${c.name}`);
+                    console.log(`     ${c.description}`);
+                }
+            }
+            process.exit(0);
+        }
+        catch (e) {
+            const message = e?.response?.data?.message || e.message || String(e);
+            getCliLogger().error('doctor:list failed', { message });
+            if (opts.json) {
+                console.log(JSON.stringify({ error: message }, null, 2));
+            }
+            else {
+                console.log(`${B.red}获取检查列表失败:${B.reset} ${message}`);
+            }
+            process.exit(1);
+        }
+        return;
+    }
     const r = await runDoctor({
         json: opts.json,
         autoHeal: opts.autoHeal !== false,
         interactive: opts.interactive !== false,
+        fix: opts.fix === true,
+        checks: opts.checks,
     });
     if (opts.json) {
         console.log(JSON.stringify(r, null, 2));
     }
     process.exit(r.summary === 'fail' ? 1 : 0);
 });
+export const repairLinkedInDupesCommand = new Command('repair-linkedin-dupes')
+    .description('修复 LinkedIn /in/<slug>/details/... 子页产生的重复 talent 数据')
+    .option('--dry-run', '仅预览,不真正合并/删除')
+    .option('--json', '仅输出 JSON 结果')
+    .action(async (opts) => {
+    const data = await runDoctorChecks({
+        fix: true,
+        checks: ['linkedin-dupes'],
+        dryRun: opts.dryRun === true,
+        json: opts.json,
+        timeout: 120_000,
+    });
+    if (!data) {
+        const message = '无法连接 server /doctor/run, 请确认 server 已启动';
+        getCliLogger().error('repair-linkedin-dupes failed', { message });
+        if (opts.json) {
+            console.log(JSON.stringify({ error: message }, null, 2));
+        }
+        else {
+            console.log(`修复失败: ${message}`);
+        }
+        process.exit(1);
+    }
+    const c = data.checks.find((x) => x.id === 'linkedin-dupes');
+    const details = c?.details || {};
+    const compat = {
+        dryRun: data.dryRun,
+        totalCandidates: details.totalCandidates ?? 0,
+        duplicateGroups: details.duplicateGroups ?? 0,
+        repairedCount: data.repaired?.length ?? 0,
+        merged: data.repaired ?? [],
+        summary: data.summary,
+    };
+    if (opts.json) {
+        console.log(JSON.stringify({ ...compat, raw: data }, null, 2));
+    }
+    else {
+        const B = {
+            reset: '\x1b[0m',
+            bold: '\x1b[1m',
+            green: '\x1b[32m',
+            yellow: '\x1b[33m',
+            cyan: '\x1b[36m',
+        };
+        console.log(`\n${B.bold}${B.cyan}LinkedIn 重复 talent 修复结果${B.reset}`);
+        console.log(`  模式: ${data.dryRun ? B.yellow + 'dry-run' + B.reset : B.green + '正式修复' + B.reset}`);
+        console.log(`  LinkedIn talent 总数: ${compat.totalCandidates}`);
+        console.log(`  归一组数: ${compat.duplicateGroups}`);
+        console.log(`  需合并组数: ${compat.repairedCount}`);
+        if (compat.merged.length) {
+            console.log(`\n${B.bold}合并详情:${B.reset}`);
+            for (const m of compat.merged) {
+                console.log(`  • master #${m.masterId} ← ${m.removedIds.map((id) => `#${id}`).join(', ')}`);
+                console.log(`    ${m.sourceUrl}`);
+            }
+        }
+    }
+    process.exit(0);
+});
+doctorCommand.addCommand(repairLinkedInDupesCommand);

package/dist/commands/extension.js

@@ -151,10 +151,10 @@ export function ensureEnvReady() {
                 process.exit(1);
             }
             console.log(`${B.green}✓  扩展已自动安装到 ${r.target}${B.reset}`);
-            // 打开目录引导
+            // 打开扩展所在目录(父目录),方便用户把 extension 文件夹拖到 chrome://extensions
             try {
                 const { default: open } = await import('open');
-                open(init.extensionDir).catch(() => { });
+                open(path.dirname(init.extensionDir)).catch(() => { });
             }
             catch { }
             showInstallGuide(init.extensionDir);

package/dist/commands/extras.d.ts

@@ -12,7 +12,7 @@ export declare function runReload(timeoutMs?: number): Promise<{
         error: string;
     }>;
 }>;
-/** 对应 ChromePilot open-ext / open-extension-folder: 打开 ~/.hunter-mate/extension */
+/** 对应 ChromePilot open-ext / open-extension-folder: 打开扩展所在目录(~/.hunter-mate),方便拖到 chrome://extensions */
 export declare function runOpenExt(target?: string): Promise<string>;
 export declare const reloadCommand: Command;
 export declare const openExtCommand: Command;

package/dist/commands/extras.js

@@ -102,10 +102,11 @@ export async function runReload(timeoutMs = 5000) {
         });
     });
 }
-/** 对应 ChromePilot open-ext / open-extension-folder: 打开 ~/.hunter-mate/extension */
+/** 对应 ChromePilot open-ext / open-extension-folder: 打开扩展所在目录(~/.hunter-mate),方便拖到 chrome://extensions */
 export async function runOpenExt(target) {
     const init = runInit();
-    const dir = target ?? init.extensionDir;
+    // 默认打开父目录,让用户能把 extension 文件夹拖进 Chrome;--target 可覆盖
+    const dir = target ?? path.dirname(init.extensionDir);
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
     try {
@@ -133,7 +134,7 @@ export const reloadCommand = new Command('reload')
 });
 export const openExtCommand = new Command('open-extension-folder')
     .alias('open-ext')
-    .description('打开 ~/.hunter-mate/extension 文件夹，方便拖到 chrome://extensions 加载（对应 chromepilot open-ext）')
+    .description('打开扩展所在目录(~/.hunter-mate)，方便把 extension 文件夹拖到 chrome://extensions 加载（对应 chromepilot open-ext）')
     .option('-t, --target <dir>', '指定自定义扩展目录')
     .action(async (opts) => {
     const dir = await runOpenExt(opts.target);

package/dist/commands/install.js

@@ -52,16 +52,19 @@ const B = {
 };
 /** 友好引导: 告诉用户如何在 Chrome 中加载 Hunter Mate 扩展 */
 export function showInstallGuide(extDir) {
+    const parentDir = path.dirname(extDir);
+    const folderName = path.basename(extDir);
     console.log(`\n${B.bold}${B.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━  Hunter Mate 扩展安装指引  ━━━━━━━━━━━━━━━━━━━━━━━━━━${B.reset}`);
     console.log(`\n${B.bold}扩展文件已经准备好:${B.reset}`);
-    console.log(`   ${B.cyan}${extDir}${B.reset}`);
-    console.log(`\n${B.bold}请按以下 5 步在 Chrome 中加载(约 30 秒):${B.reset}\n`);
+    console.log(`   扩展文件夹: ${B.cyan}${extDir}${B.reset}`);
+    console.log(`   已为你打开: ${B.cyan}${parentDir}${B.reset}`);
+    console.log(`\n${B.bold}请按以下 4 步在 Chrome 中加载(约 30 秒):${B.reset}\n`);
     console.log(`   ${B.magenta}①${B.reset} 打开 Chrome, 地址栏输入: ${B.cyan}chrome://extensions${B.reset}`);
     console.log(`      (hunter-mate 已帮你自动打开了这个页面)`);
     console.log(`   ${B.magenta}②${B.reset} 右上角打开「${B.bold}开发者模式${B.reset}」开关`);
-    console.log(`   ${B.magenta}③${B.reset} 点击「${B.bold}加载已解压的扩展程序${B.reset}」按钮`);
-    console.log(`   ${B.magenta}④${B.reset} 在文件选择框中选择目录: ${B.cyan}${extDir}${B.reset}`);
-    console.log(`   ${B.magenta}⑤${B.reset} Chrome 工具栏应出现 Hunter Mate 🤝 图标\n`);
+    console.log(`   ${B.magenta}③${B.reset} 把文件夹 ${B.bold}${folderName}${B.reset} 拖到 chrome://extensions 页面里`);
+    console.log(`      (也可以点击「加载已解压的扩展程序」后选择 ${B.cyan}${extDir}${B.reset})`);
+    console.log(`   ${B.magenta}④${B.reset} Chrome 工具栏应出现 Hunter Mate 🤝 图标,侧栏显示「已连接」\n`);
     console.log(`${B.bold}${B.yellow}常见问题:${B.reset}`);
     console.log(`   · 没看到「加载已解压的扩展程序」? → 先开启「开发者模式」开关`);
     console.log(`   · 加载后图标灰显? → 点击图标确认侧栏显示「已连接」`);
@@ -69,7 +72,7 @@ export function showInstallGuide(extDir) {
     console.log(`\n${B.bold}${B.cyan}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${B.reset}\n`);
 }
 export const installCommand = new Command('install')
-    .description('把内置 extension dist 复制到 ~/.hunter-mate/extension（对应 chromepilot install）。完成后自动打开目录并给出中文引导。')
+    .description('把内置 extension dist 复制到 ~/.hunter-mate/extension（对应 chromepilot install）。完成后自动打开扩展所在目录(~/.hunter-mate)并给出中文引导，方便把 extension 文件夹拖到 chrome://extensions。')
     .option('-t, --target <dir>', '目标目录，默认 ~/.hunter-mate/extension')
     .option('--no-open', '不自动打开扩展所在目录')
     .action(async (opts) => {
@@ -82,11 +85,11 @@ export const installCommand = new Command('install')
         return;
     }
     console.log(`${B.green}✓  hunter-mate install OK: ${r.copied} files${B.reset} → ${B.cyan}${r.target}${B.reset}`);
-    // 自动打开目录 + 引导
+    // 自动打开扩展所在目录(父目录),方便用户把 extension 文件夹拖到 chrome://extensions
     if (opts.open !== false) {
         try {
             const { default: open } = await import('open');
-            open(r.target).catch(() => { });
+            open(path.dirname(r.target)).catch(() => { });
         }
         catch { }
     }

package/dist/index.js

@@ -76,6 +76,13 @@ program
             for (const line of report.performed)
                 console.log(chalk.gray(`  [auto-update] ${line}`));
         }
+        try {
+            const { runAutoDoctor } = await import('./auto-doctor.js');
+            await runAutoDoctor(report);
+        }
+        catch {
+            /* auto-doctor 永不阻塞主命令 */
+        }
     }
     catch {
         /* 一致性检测永不阻塞主命令 */

package/dist/native-check.js

@@ -18,6 +18,13 @@ function locateServerEntryDir() {
 const checker = createNativeChecker({
     probeDir: () => locateServerEntryDir(),
     skipDetail: "未找到 server 入口(packages/server/dist|src)，跳过原生模块检查",
-    rebuildHint: (moduleName, compiledLabel) => `二选一：① 切回 ${compiledLabel} 的 node 再运行；② 用当前 node 重编译：pnpm rebuild -r ${moduleName}（重编后重启 server）`,
+    rebuildHint: (moduleName, compiledLabel) => {
+        const isWin = process.platform === "win32";
+        const base = `二选一：① 切回 ${compiledLabel} 的 node 再运行；② 用当前 node 重编译：pnpm rebuild -r ${moduleName}（重编后重启 server）`;
+        if (isWin && moduleName === "better-sqlite3") {
+            return `${base}。Windows 无 C++ 编译器时,推荐直接安装 Node 22 LTS(预构建包最全),无需安装 Visual Studio Build Tools`;
+        }
+        return base;
+    },
 });
 export const checkNativeModules = checker.checkNativeModules;

package/dist/updater.d.ts

@@ -6,17 +6,21 @@
 export declare function computeDevLinked(pkgRoot: string): boolean;
 export declare function isDevLinked(): boolean;
 export declare const npmLatestVersion: (pkg?: string) => string | null;
-export declare const npmSelfUpdate: (pkg?: string) => {
-    ok: boolean;
-    msg: string;
-};
 export declare const updateCheckIntervalMs: () => number;
 export declare const shouldCheckUpdate: (stateFile?: string, now?: number, intervalMs?: number) => boolean;
 export declare const markUpdateChecked: (stateFile?: string) => void;
+export interface NpmSelfUpdateResult {
+    ok: boolean;
+    msg: string;
+}
+export declare function npmSelfUpdate(pkg?: string): NpmSelfUpdateResult;
 export interface CliUpdateOutcome {
     logs: string[];
     devSkipped: boolean;
     updated: boolean;
 }
-/** preAction 集成入口:返回日志行数组,永不 throw */
+/**
+ * preAction 集成入口:返回日志行数组,永不 throw。
+ * 逻辑等价于 kit 的 autoCliUpdate,但安装命令走 --prefix。
+ */
 export declare function maybeCliSelfUpdate(): Promise<CliUpdateOutcome>;

package/dist/updater.js

@@ -6,18 +6,25 @@
  * - dev 判定(hc-hw local worktree 布局 + HUNTER_MATE_DEV=1)为本仓特有安装形态
  * - 已安装版本读取走 version.ts 的 package.json SSOT 扫描
  *
+ * 重要: hunter-mate 使用用户级安装(--prefix ~/.hunter-mate/cli),
+ * 避免 Workbuddy/Trae 沙盒拦截 `npm install -g` 全局写入。
+ * 因此覆盖 kit 默认的 npmSelfUpdate/autoCliUpdate,统一走 --prefix。
+ *
  * 逃生开关(kit autoCliUpdate 内统一处理):
  * - HUNTER_MATE_NO_AUTOUPDATE=1          关闭全部自动更新(CLI + 一致性,preAction 层)
  * - HUNTER_MATE_UPDATE_CHECK_INTERVAL_MS 覆盖节流间隔(默认 3600000)
  * - HUNTER_MATE_DEV=1                    强制视为 dev 模式(测试用)
  */
+import * as fs from 'node:fs';
 import * as path from 'path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createCliUpdater } from '@chromepilot/kit';
 import { readInstalledVersions } from './version.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const HOME = () => process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
 const ROOT = () => path.join(HOME(), '.hunter-mate');
+const CLI_PREFIX = () => path.join(ROOT(), 'cli');
 /**
  * 判定是否开发软链模式(纯函数,便于单测):
  * 包根路径含 /worktrees/ 段(hc-hw local worktree 布局)或 HUNTER_MATE_DEV=1。
@@ -31,7 +38,7 @@ export function computeDevLinked(pkgRoot) {
 export function isDevLinked() {
     return computeDevLinked(path.join(__dirname, '..'));
 }
-const updater = createCliUpdater({
+const kitUpdater = createCliUpdater({
     npmPackage: 'hunter-mate',
     envPrefix: 'HUNTER_MATE',
     stateDir: ROOT,
@@ -39,14 +46,73 @@ const updater = createCliUpdater({
     isDev: isDevLinked,
 });
 // ---------------------------------------------------------------------------
-// 兼容导出(调用方零改动)
+// 复用 kit 的工具函数(版本查询、节流标记等)
 // ---------------------------------------------------------------------------
-export const npmLatestVersion = updater.npmLatestVersion;
-export const npmSelfUpdate = updater.npmSelfUpdate;
-export const updateCheckIntervalMs = updater.updateCheckIntervalMs;
-export const shouldCheckUpdate = updater.shouldCheckUpdate;
-export const markUpdateChecked = updater.markUpdateChecked;
-/** preAction 集成入口:返回日志行数组,永不 throw */
+export const npmLatestVersion = kitUpdater.npmLatestVersion;
+export const updateCheckIntervalMs = kitUpdater.updateCheckIntervalMs;
+export const shouldCheckUpdate = kitUpdater.shouldCheckUpdate;
+export const markUpdateChecked = kitUpdater.markUpdateChecked;
+export function npmSelfUpdate(pkg = 'hunter-mate') {
+    const prefix = CLI_PREFIX();
+    fs.mkdirSync(prefix, { recursive: true });
+    // 优先使用用户通过环境变量指定的 npm 路径(沙盒内可能只有局部 npm)
+    const npmBin = process.env.HUNTER_MATE_NPM_BIN || 'npm';
+    const args = ['install', `${pkg}@latest`, '--prefix', prefix];
+    const r = spawnSync(npmBin, args, {
+        stdio: 'inherit',
+        timeout: 120_000,
+        env: {
+            ...process.env,
+            // 防止 npm 因为用户 home 不可写而失败;--prefix 已指定安装位置
+            npm_config_cache: path.join(prefix, '.npm-cache'),
+        },
+    });
+    if (r.status === 0) {
+        return {
+            ok: true,
+            msg: `${npmBin} install ${pkg}@latest --prefix ${prefix} 完成,下一条命令起使用新版本`,
+        };
+    }
+    return {
+        ok: false,
+        msg: `${npmBin} install ${pkg}@latest --prefix ${prefix} 失败 (exit=${r.status}),可手动执行`,
+    };
+}
+/**
+ * preAction 集成入口:返回日志行数组,永不 throw。
+ * 逻辑等价于 kit 的 autoCliUpdate,但安装命令走 --prefix。
+ */
 export async function maybeCliSelfUpdate() {
-    return updater.autoCliUpdate();
+    const logs = [];
+    const outcome = { logs, devSkipped: false, updated: false };
+    try {
+        if (process.env.HUNTER_MATE_NO_AUTOUPDATE === '1')
+            return outcome;
+        if (isDevLinked()) {
+            outcome.devSkipped = true;
+            logs.push('dev 软链模式,跳过 CLI 自更新(改代码请 pnpm build;reload/restart 自愈不受影响)');
+            return outcome;
+        }
+        if (!shouldCheckUpdate())
+            return outcome;
+        markUpdateChecked();
+        const installed = readInstalledVersions().cli;
+        if (!installed || installed === '0.0.0')
+            return outcome;
+        const latest = npmLatestVersion();
+        if (!latest) {
+            logs.push(`npm registry 查询 hunter-mate 失败,本次跳过自更新`);
+            return outcome;
+        }
+        if (latest === installed)
+            return outcome;
+        logs.push(`CLI 自更新: ${installed} → ${latest}`);
+        const r = npmSelfUpdate();
+        logs.push(r.msg);
+        outcome.updated = r.ok;
+    }
+    catch (err) {
+        logs.push(`自动更新检测异常(不影响命令执行): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return outcome;
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "hunter-mate",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "HiredChina 猎头 Agent 数据助手 CLI:人才库/客户/职位数据访问,浏览器录制解析简历,server/扩展一致性自愈",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+github.com:hiredchina-com/hunter-mate.git"
@@ -31,7 +31,7 @@
     "open": "^8.4.0",
     "uuid": "^9.0.0",
     "ws": "^8.21.3",
-    "@hunter-mate/shared": "0.1.2"
+    "@hunter-mate/shared": "0.1.4"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",