hunter-mate 0.1.5 → 0.1.7

package/dist/commands/search.js

@@ -3,6 +3,7 @@ import axios from 'axios';
 import { loadConfig } from '../config.js';
 import { getToken } from '../keychain.js';
 import { i18n } from '../i18n/index.js';
+import { printCommandError } from '../utils/command-error.js';
 export async function runSearch(options) {
     const config = loadConfig();
     const token = await getToken();
@@ -34,6 +35,12 @@ export const searchCommand = new Command('search')
     .option('--source <sources>', i18n.t('search.source'), 'u_person')
     .option('--top <n>', i18n.t('search.top'), '10')
     .action(async (options) => {
-    const data = await runSearch(options);
-    console.log(JSON.stringify(data, null, 2));
+    try {
+        const data = await runSearch(options);
+        console.log(JSON.stringify(data, null, 2));
+    }
+    catch (err) {
+        printCommandError('search:failed', err);
+        process.exit(1);
+    }
 });

package/dist/commands/server.d.ts

@@ -14,10 +14,10 @@ export declare function runStart(opts: {
     url: string;
     msg: string;
 }>;
-export declare function runStop(): {
+export declare function runStop(): Promise<{
     stopped: boolean;
     pid: number | null;
     msg: string;
-};
+}>;
 export declare const startCommand: Command;
 export declare const stopCommand: Command;

package/dist/commands/server.js

@@ -55,25 +55,50 @@ export function findServerRoot() {
     }
     return null;
 }
+/** 探活:server /health 是否可访问(短超时,永不 throw) */
+async function probeServerHealth(url, timeoutMs = 1500) {
+    try {
+        const res = await fetch(`${url}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** 从 config.serverUrl 解析默认端口(与 runStart 逻辑一致) */
+function defaultPortFromConfig(serverUrl) {
+    return new URL(serverUrl).port ? Number(new URL(serverUrl).port) : 34570;
+}
 /** 对应 ChromePilot start: 启动本地 NestJS Server（提供 REST + WebSocket + SPA） */
 export async function runStart(opts) {
     const config = loadConfig();
-    const defaultPort = new URL(config.serverUrl).port
-        ? Number(new URL(config.serverUrl).port)
-        : 34570;
+    const defaultPort = defaultPortFromConfig(config.serverUrl);
     const port = opts.port ?? defaultPort;
     const host = opts.host ?? '127.0.0.1';
     const url = `http://${host}:${port}`;
+    // 启动过程中的告警说明(会拼进最终返回 msg,保证用户看得见)
+    const notes = [];
     const existing = tryReadPid();
     if (existing) {
-        // 已在运行: 先做版本一致性检测（磁盘版本 vs 运行版本，server 不一致则自动重启）
-        // 动态 import 避免与 version.ts 的循环依赖（version.ts 静态引入本文件的 runStart/runStop）
-        const { ensureRuntimeConsistency } = await import('../version.js');
-        const report = await ensureRuntimeConsistency({ force: true });
-        if (report.actions.serverRestart && report.performed.length) {
-            return { started: true, pid: null, url, msg: report.performed.join('; ') };
+        // pid 文件存在 ≠ server 存活。pid 可能被系统中其他进程复用
+        // (Windows 现场:残留 node.exe 复用了 pid → 误判 already running,
+        //  server 实际从未被拉起,日志停在旧时间戳,用户无任何感知)。
+        // 因此必须先 /health 探活再决定是否走"已在运行"分支。
+        if (await probeServerHealth(url)) {
+            // 已在运行: 先做版本一致性检测（磁盘版本 vs 运行版本，server 不一致则自动重启）
+            // 动态 import 避免与 version.ts 的循环依赖（version.ts 静态引入本文件的 runStart/runStop）
+            const { ensureRuntimeConsistency } = await import('../version.js');
+            const report = await ensureRuntimeConsistency({ force: true });
+            if (report.actions.serverRestart && report.performed.length) {
+                return { started: true, pid: null, url, msg: report.performed.join('; ') };
+            }
+            return { started: false, pid: existing, url, msg: `server already running (pid=${existing})` };
         }
-        return { started: false, pid: existing, url, msg: `server already running (pid=${existing})` };
+        // stale pid:进程号存活但不是我们的 server(或 server 已僵死)。清理后继续启动,
+        // 不 kill —— 那个进程可能属于别的程序(误杀 foreign 进程红线)。
+        notes.push(`⚠ 检测到 stale server.pid (pid=${existing}):该进程存活但 ${url}/health 无响应,` +
+            `疑似 pid 被其他进程复用,已忽略并继续启动`);
+        cleanPidFile(PID_FILE());
     }
     // server 入口: bundled 模式下 <cli>/dist/assets/server/main.js；monorepo 下 packages/server/dist/main.js 或 src/main.ts(开发模式 ts-node)
     const serverRoot = findServerRoot();
@@ -150,8 +175,11 @@ export async function runStart(opts) {
     wd.unref();
     if (wd.pid)
         fs.writeFileSync(WATCHDOG_PID_FILE(), String(wd.pid));
-    // 等待 server health 就绪(最多 8s)
-    const deadline = Date.now() + 8000;
+    // 等待 server health 就绪。窗口给足:NestJS 全量路由映射 + TypeORM schema 同步
+    // 在慢机/Windows 上实测 10-15s,原 8s 会在 route mapping 阶段误报"未就绪"
+    // (server 实际 3 秒后就绪,watchdog 会保活,误报只会误导用户)。
+    const probeDeadlineMs = 30_000;
+    const deadline = Date.now() + probeDeadlineMs;
     let ready = false;
     while (Date.now() < deadline) {
         await new Promise((r) => setTimeout(r, 500));
@@ -179,7 +207,8 @@ export async function runStart(opts) {
             started: false,
             pid: wd.pid ?? null,
             url,
-            msg: `✗ server watchdog 启动后未就绪(pid=${wd.pid}),日志尾部:\n${tail || '(server.log 为空)'}\n` +
+            msg: (notes.length ? notes.join('\n') + '\n' : '') +
+                `✗ server watchdog 启动后 ${probeDeadlineMs / 1000}s 内未就绪(pid=${wd.pid}),日志尾部:\n${tail || '(server.log 为空)'}\n` +
                 `排障: hunter-mate doctor 或 TROUBLESHOOTING.md#server-启动即崩abi`,
         };
     }
@@ -193,12 +222,34 @@ export async function runStart(opts) {
         }
     }
     catch { /* ignore */ }
-    return { started: true, pid: wd.pid ?? null, url, msg: `server watchdog started (pid=${wd.pid}) on ${url} — logs: ${LOG_FILE()}` };
+    return {
+        started: true,
+        pid: wd.pid ?? null,
+        url,
+        msg: (notes.length ? notes.join('\n') + '\n' : '') +
+            `server watchdog started (pid=${wd.pid}) on ${url} — logs: ${LOG_FILE()}`,
+    };
 }
-export function runStop() {
+export async function runStop() {
+    const config = loadConfig();
+    const url = `http://127.0.0.1:${defaultPortFromConfig(config.serverUrl)}`;
+    // kill 任何进程前先 /health 确认它真的是我们的 server。
+    // pid 文件可能被复用(Windows 现场:残留 node.exe 占用 pid),误杀 foreign 进程不可接受。
+    const healthy = await probeServerHealth(url);
     // 优先停止 watchdog,让它去停止子 server
     const wdPid = tryReadPidFile(WATCHDOG_PID_FILE());
     if (wdPid) {
+        if (!healthy) {
+            // server 不响应时不杀 watchdog pid(可能已被其他进程复用),只清理 pid 文件
+            cleanPidFile(WATCHDOG_PID_FILE());
+            cleanPidFile(PID_FILE());
+            return {
+                stopped: false,
+                pid: wdPid,
+                msg: `✗ server 无响应(${url}/health 不可达),watchdog pid=${wdPid} 未杀(疑似 stale pid,` +
+                    `可能已被其他进程复用)。已清理 pid 文件;如确有残留进程请手工确认后 kill`,
+            };
+        }
         const ok = killGracefullySync(wdPid);
         cleanPidFile(WATCHDOG_PID_FILE());
         if (ok) {
@@ -218,6 +269,16 @@ export function runStop() {
     const pid = tryReadPid();
     if (!pid)
         return { stopped: false, pid: null, msg: 'no server.pid found or process dead' };
+    if (!healthy) {
+        // pid 存活但 server 不响应:不 kill(可能复用了别人的 pid),只清 pid 文件
+        cleanPidFile(PID_FILE());
+        return {
+            stopped: false,
+            pid,
+            msg: `✗ pid=${pid} 存活但 server 无响应,未发送 kill 信号(疑似 stale pid,` +
+                `可能属于其他进程)。已清理 pid 文件;如确认是僵死 server 请手工 kill`,
+        };
+    }
     const ok = killGracefullySync(pid);
     if (!ok) {
         return { stopped: false, pid, msg: `failed to signal ${pid}` };
@@ -238,8 +299,8 @@ export const startCommand = new Command('start')
 });
 export const stopCommand = new Command('stop')
     .description('停止本地 server（读 ~/.hunter-mate/server.pid 并 SIGTERM）')
-    .action(() => {
-    const r = runStop();
+    .action(async () => {
+    const r = await runStop();
     console.log(r.msg);
     if (!r.stopped && r.pid)
         process.exit(1);

package/dist/commands/update.js

@@ -105,7 +105,7 @@ export const updateCommand = new Command('update')
             }
             else {
                 console.log(chalk.cyan(`CLI 自更新: ${installed.cli} → ${latest}`));
-                const r = npmSelfUpdate(npmPackage);
+                const r = await npmSelfUpdate(npmPackage);
                 console.log(r.ok ? chalk.green(r.msg) : chalk.yellow(r.msg));
             }
         }

package/dist/config.d.ts

@@ -6,6 +6,41 @@ export interface HunterMateConfig {
     lang: string;
     watchFolder?: string;
 }
+export declare const CONFIG_DIR: () => string;
+export declare const CONFIG_FILE: () => string;
+/**
+ * 已知废弃的 URL 路径前缀(按部署形态演进顺序追加)。
+ * 每当 nginx / 服务端路径收敛(如子路径 → 根路径)时,把旧前缀加到这里,
+ * loadConfig() / saveConfig() 会自动剥离,doctor 会自检并给出 healed 记录。
+ * 匹配规则:字符串中任何一段形如 `{host}{prefix}` 都会被替换为 `{host}/`,
+ * 且自动处理尾斜杠(例如 https://host/llm-research/foo → https://host/foo)。
+ */
+export declare const DEPRECATED_URL_PATH_PREFIXES: string[];
+/**
+ * 规范化 URL 字符串: 剥离所有已知废弃的子路径前缀。
+ * 例: normalizeUrlValue('https://dev-ops.hiredchina.com/llm-research/errors')
+ *   → 'https://dev-ops.hiredchina.com/errors'
+ */
+export declare function normalizeUrlValue(value: string): string;
+/**
+ * 对 config 对象所有 string 字段应用 URL 规范化。
+ * 返回 { config, changed } 便于调用方决定是否持久化。
+ * 深度 1 层足够(配置文件是扁平 key-value)。
+ */
+export declare function normalizeConfig<T extends Record<string, any>>(raw: T): {
+    config: T;
+    changed: boolean;
+    migrated: Array<{
+        key: string;
+        from: string;
+        to: string;
+    }>;
+};
 export declare function ensureConfigDir(): void;
 export declare function loadConfig(): HunterMateConfig;
-export declare function saveConfig(config: Partial<HunterMateConfig>): HunterMateConfig;
+export declare function saveConfig(config: Partial<HunterMateConfig>): {
+    serverUrl: string;
+    saasUrl: string;
+    lang: string;
+    watchFolder?: string;
+};

package/dist/config.js

@@ -2,13 +2,67 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { createJsonConfigStore } from '@chromepilot/kit';
 const HOME = () => process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-const CONFIG_DIR = () => path.join(HOME(), '.hunter-mate');
-const CONFIG_FILE = () => path.join(CONFIG_DIR(), 'config.json');
+export const CONFIG_DIR = () => path.join(HOME(), '.hunter-mate');
+export const CONFIG_FILE = () => path.join(CONFIG_DIR(), 'config.json');
+/**
+ * 已知废弃的 URL 路径前缀(按部署形态演进顺序追加)。
+ * 每当 nginx / 服务端路径收敛(如子路径 → 根路径)时,把旧前缀加到这里,
+ * loadConfig() / saveConfig() 会自动剥离,doctor 会自检并给出 healed 记录。
+ * 匹配规则:字符串中任何一段形如 `{host}{prefix}` 都会被替换为 `{host}/`,
+ * 且自动处理尾斜杠(例如 https://host/llm-research/foo → https://host/foo)。
+ */
+export const DEPRECATED_URL_PATH_PREFIXES = [
+    '/llm-research', // 2026-08-21 dev-ops 从子路径部署收敛到根路径
+];
+/**
+ * 规范化 URL 字符串: 剥离所有已知废弃的子路径前缀。
+ * 例: normalizeUrlValue('https://dev-ops.hiredchina.com/llm-research/errors')
+ *   → 'https://dev-ops.hiredchina.com/errors'
+ */
+export function normalizeUrlValue(value) {
+    if (typeof value !== 'string')
+        return value;
+    let out = value;
+    for (const prefix of DEPRECATED_URL_PATH_PREFIXES) {
+        // 匹配 host/<prefix> 形式,支持 <prefix>/... 和 <prefix> 结尾
+        // e.g. https://host/llm-research   → https://host/
+        //      https://host/llm-research/x → https://host/x
+        const re = new RegExp(`(${prefix})(/|$)`, 'g');
+        out = out.replace(re, '/$2');
+    }
+    // 合并多余的连续斜杠(上面的替换可能产生 "//")
+    // 协议里的 :// 不动,只处理 host 之后的部分
+    out = out.replace(/^(https?:\/\/)(.*)/, (_m, scheme, rest) => {
+        return scheme + rest.replace(/\/{2,}/g, '/');
+    });
+    return out;
+}
+/**
+ * 对 config 对象所有 string 字段应用 URL 规范化。
+ * 返回 { config, changed } 便于调用方决定是否持久化。
+ * 深度 1 层足够(配置文件是扁平 key-value)。
+ */
+export function normalizeConfig(raw) {
+    const migrated = [];
+    const out = { ...raw };
+    for (const key of Object.keys(out)) {
+        const value = out[key];
+        // 覆盖类型定义之外的自定义字段(如用户手动添加的 apiBase 等)
+        if (typeof value === 'string' && (value.startsWith('http://') || value.startsWith('https://') || value.includes('/llm-research'))) {
+            const normalized = normalizeUrlValue(value);
+            if (normalized !== value) {
+                migrated.push({ key, from: value, to: normalized });
+                out[key] = normalized;
+            }
+        }
+    }
+    return { config: out, changed: migrated.length > 0, migrated };
+}
 const store = createJsonConfigStore({
     configPath: CONFIG_FILE,
     defaults: {
         serverUrl: 'http://localhost:34570',
-        saasUrl: 'https://dev-ops.hiredchina.com/llm-research',
+        saasUrl: 'https://dev-ops.hiredchina.com',
         lang: 'zh-CN',
     },
 });
@@ -18,8 +72,23 @@ export function ensureConfigDir() {
     }
 }
 export function loadConfig() {
-    return store.load();
+    const raw = store.load();
+    const { config: normalized, changed } = normalizeConfig(raw);
+    if (changed) {
+        // 配置含有已废弃路径,自动静默迁移并保存,用户下次读取一定是规范形态。
+        try {
+            fs.writeFileSync(CONFIG_FILE(), JSON.stringify(normalized, null, 2));
+        }
+        catch {
+            /* read-only fs, ignore */
+        }
+    }
+    return normalized;
 }
 export function saveConfig(config) {
-    return store.save(config);
+    const current = loadConfig(); // 已规范化(必要时已写回)
+    const { config: next } = normalizeConfig({ ...current, ...config });
+    ensureConfigDir();
+    fs.writeFileSync(CONFIG_FILE(), JSON.stringify(next, null, 2));
+    return next;
 }

package/dist/i18n/locales/en-US.json

@@ -57,5 +57,7 @@
     "purge.done.removed": "Removed",
     "purge.done.server": "Server",
     "purge.done.next": "To re-initialize, run",
-    "purge.done.nothing": "Nothing to purge"
+    "purge.done.nothing": "Nothing to purge",
+    "login.serverOfflineSaasFallback": "Warning: local server is not running; logged in via SaaS directly. Start the server and run login again for local data operations.",
+    "login.serverOfflineReloginHint": "Note: the saved SaaS token will be rejected (401) by local server protected routes."
 }

package/dist/i18n/locales/zh-CN.json

@@ -57,5 +57,7 @@
     "purge.done.removed": "清理数据量",
     "purge.done.server": "Server 状态",
     "purge.done.next": "如需重新初始化，请运行",
-    "purge.done.nothing": "无需清理"
+    "purge.done.nothing": "无需清理",
+    "login.serverOfflineSaasFallback": "警告: 本地 server 未运行,已直连 SaaS 登录;本地数据操作需启动 server 后重新 login。",
+    "login.serverOfflineReloginHint": "提示: 本次保存的是 SaaS 令牌,本地 server 的受保护路由将返回 401。"
 }

package/dist/index.js

@@ -26,6 +26,25 @@ import { i18n } from './i18n/index.js';
 import { initCliLogger, flushCliLogger, getCliLogger } from './logger.js';
 import packageJson from '../package.json' with { type: 'json' };
 const CLI_VERSION = packageJson.version;
+// 未捕获异常兜底(fix #27):任何命令抛出的未处理 Promise 统一友好提示 + exit 1,
+// 不再裸奔 stack 或以 exit code 0 静默结束。
+process.on('unhandledRejection', (reason) => {
+    const status = reason?.response?.status;
+    const message = reason?.response?.data?.message || reason?.response?.data?.error || reason?.message || String(reason);
+    if (status === 401 || status === 403) {
+        console.error('登录已过期或无权访问,请运行 hunter-mate login 后重试');
+    }
+    else {
+        console.error(`命令执行出错: ${message}`);
+    }
+    try {
+        getCliLogger().error('cli:unhandled-rejection', { status, error: message });
+    }
+    catch {
+        // logger 未就绪时忽略
+    }
+    process.exit(1);
+});
 initSentry();
 // patchConsole + patchStreams:把业务代码里的 console.error/warn 统一转发到 logger-kit,
 // 避免两套日志写法。AGENTS.md §11。
@@ -55,16 +74,33 @@ program
     // 2) server 在跑时对比磁盘版本 vs 运行版本,插件不一致 → reload,server 不一致 → 重启。
     // HUNTER_MATE_NO_AUTOUPDATE=1 可禁用;update/start/stop 自行处理避免递归;
     // server 未运行时一致性零成本跳过(本地 pid 探测,60s 节流)。
+    // doctor 跳过(fix #13): doctor 是只读自检, 不应触发 extension reload 广播,
+    // 也不应让 auto-doctor 以 repair 模式写数据(repair-linkedin-dupes 同属此类)。
     if (process.env.HUNTER_MATE_NO_AUTOUPDATE === '1')
         return;
     const name = thisCommand.name();
     if (name === 'update' || name === 'start' || name === 'stop')
         return;
+    if (name === 'doctor' || name === 'repair-linkedin-dupes')
+        return;
+    // fix #30: 命令以 --json(或 --format/-f json)输出时, [auto-update] 提示不得混入 stdout 的 JSON
+    const argv = process.argv;
+    const jsonMode = argv.includes('--json') ||
+        argv.includes('--format=json') ||
+        argv.includes('-f=json') ||
+        argv.some((a, i) => (a === '--format' || a === '-f') && argv[i + 1] === 'json');
+    const notify = (line) => {
+        const text = chalk.gray(`  [auto-update] ${line}`);
+        if (jsonMode)
+            console.error(text);
+        else
+            console.log(text);
+    };
     try {
         const { maybeCliSelfUpdate } = await import('./updater.js');
         const upd = await maybeCliSelfUpdate();
         for (const line of upd.logs)
-            console.log(chalk.gray(`  [auto-update] ${line}`));
+            notify(line);
     }
     catch {
         /* CLI 自更新检测永不阻塞主命令 */
@@ -74,7 +110,7 @@ program
         const report = await ensureRuntimeConsistency({});
         if (report.performed.length) {
             for (const line of report.performed)
-                console.log(chalk.gray(`  [auto-update] ${line}`));
+                notify(line);
         }
         try {
             const { runAutoDoctor } = await import('./auto-doctor.js');

package/dist/updater.d.ts

@@ -13,7 +13,7 @@ export interface NpmSelfUpdateResult {
     ok: boolean;
     msg: string;
 }
-export declare function npmSelfUpdate(pkg?: string): NpmSelfUpdateResult;
+export declare function npmSelfUpdate(pkg?: string): Promise<NpmSelfUpdateResult>;
 export interface CliUpdateOutcome {
     logs: string[];
     devSkipped: boolean;

package/dist/updater.js

@@ -52,17 +52,34 @@ 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') {
+export async 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];
+    // 死代理处理:npm 会继承 HTTP(S)_PROXY;指向死端口时 registry 查询必失败
+    // (现场真凶:update 查 registry 失败 + prebuild 下载失败回退 7 分钟源码编译)。
+    // 检测后从子进程环境剔除死代理变量,让 npm 直连,并在结果里告知用户。
+    const childEnv = { ...process.env };
+    let proxyNote = '';
+    try {
+        const { findDeadProxies } = await import('./utils/proxy-detect.js');
+        const dead = await findDeadProxies(800);
+        if (dead.length) {
+            for (const d of dead)
+                delete childEnv[d.varName];
+            proxyNote =
+                `⚠ 检测到死代理(${dead.map((d) => `${d.varName}=${d.value}`).join('; ')}),` +
+                    `已在本轮 npm install 中临时剔除使其直连;清除方法见 hunter-mate doctor 的 proxy_env 检查项\n`;
+        }
+    }
+    catch { /* 检测失败不阻断更新 */ }
     const r = spawnSync(npmBin, args, {
         stdio: 'inherit',
         timeout: 120_000,
         env: {
-            ...process.env,
+            ...childEnv,
             // 防止 npm 因为用户 home 不可写而失败;--prefix 已指定安装位置
             npm_config_cache: path.join(prefix, '.npm-cache'),
         },
@@ -70,12 +87,12 @@ export function npmSelfUpdate(pkg = 'hunter-mate') {
     if (r.status === 0) {
         return {
             ok: true,
-            msg: `${npmBin} install ${pkg}@latest --prefix ${prefix} 完成,下一条命令起使用新版本`,
+            msg: proxyNote + `${npmBin} install ${pkg}@latest --prefix ${prefix} 完成,下一条命令起使用新版本`,
         };
     }
     return {
         ok: false,
-        msg: `${npmBin} install ${pkg}@latest --prefix ${prefix} 失败 (exit=${r.status}),可手动执行`,
+        msg: proxyNote + `${npmBin} install ${pkg}@latest --prefix ${prefix} 失败 (exit=${r.status}),可手动执行`,
     };
 }
 /**
@@ -107,7 +124,7 @@ export async function maybeCliSelfUpdate() {
         if (latest === installed)
             return outcome;
         logs.push(`CLI 自更新: ${installed} → ${latest}`);
-        const r = npmSelfUpdate();
+        const r = await npmSelfUpdate();
         logs.push(r.msg);
         outcome.updated = r.ok;
     }

package/dist/utils/command-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 命令错误统一出口(对应 fix #18/#28):
+ * - logger 留痕(后台可检索,与现有 getCliLogger().error 一致)
+ * - console.error 落终端(用户能直接看懂,不再静默 exit 1)
+ * - 401/403 时给出重新登录的中文提示
+ *
+ * 调用方随后自行 process.exit(1)。
+ */
+export declare function printCommandError(scope: string, err: unknown): void;

package/dist/utils/command-error.js

@@ -0,0 +1,31 @@
+import { getCliLogger } from '../logger.js';
+/**
+ * 命令错误统一出口(对应 fix #18/#28):
+ * - logger 留痕(后台可检索,与现有 getCliLogger().error 一致)
+ * - console.error 落终端(用户能直接看懂,不再静默 exit 1)
+ * - 401/403 时给出重新登录的中文提示
+ *
+ * 调用方随后自行 process.exit(1)。
+ */
+export function printCommandError(scope, err) {
+    const e = err;
+    const status = e?.response?.status;
+    const body = e?.response?.data;
+    const bodyText = body ? (typeof body === 'string' ? body : JSON.stringify(body)) : '';
+    const message = e?.response?.data?.message || e?.response?.data?.error || e?.message || String(err);
+    try {
+        getCliLogger().error(scope, { status, error: message });
+    }
+    catch {
+        // logger 未就绪时忽略
+    }
+    if (status === 401 || status === 403) {
+        console.error(`✗ ${message} (HTTP ${status})`);
+        console.error('登录已过期或无权访问,请运行 hunter-mate login 后重试');
+        return;
+    }
+    console.error(`✗ ${scope}: ${message}${status ? ` (HTTP ${status})` : ''}`);
+    if (bodyText && bodyText !== message) {
+        console.error(`  响应: ${bodyText}`);
+    }
+}

package/dist/utils/proxy-detect.d.ts

@@ -0,0 +1,20 @@
+export interface ProxyEnvEntry {
+    varName: string;
+    value: string;
+}
+export interface DeadProxyFinding {
+    varName: string;
+    value: string;
+    host: string;
+    port: number;
+    reason: 'refused' | 'timeout' | 'unreachable';
+}
+/** 收集四个代理环境变量中已设置的项 */
+export declare function collectProxyEnv(): ProxyEnvEntry[];
+/**
+ * 找出指向 loopback 但端口不通的死代理。
+ * 远程代理(非 loopback)不探测,直接视为有效(由网络栈自己处理)。
+ */
+export declare function findDeadProxies(timeoutMs?: number): Promise<DeadProxyFinding[]>;
+/** 生成各 shell 的清除指令提示(用户直接复制执行) */
+export declare function buildUnsetHint(findings: DeadProxyFinding[]): string;

package/dist/utils/proxy-detect.js

@@ -0,0 +1,96 @@
+/**
+ * 死代理检测 — Windows/终端现场高频坑。
+ *
+ * 背景:用户的 shell 环境变量里可能残留指向已关闭本地代理的
+ * HTTP_PROXY / HTTPS_PROXY / http_proxy / https_proxy(如 http://127.0.0.1:1962)。
+ * 后果链(2026-09-02 现场):
+ *   npm registry 查询失败 → CLI 自更新误判"已是最新"或报错;
+ *   better-sqlite3 prebuild 下载失败 → 回退 node-gyp 源码编译 7 分钟+。
+ * 本模块只检测 loopback 代理(远程代理探测需要出网,不属于"死代理"语义),
+ * 且永不 throw —— 检测结果用于告警,不影响主流程。
+ */
+import net from 'node:net';
+const PROXY_VARS = ['HTTP_PROXY', 'HTTPS_PROXY', 'http_proxy', 'https_proxy'];
+/** 收集四个代理环境变量中已设置的项 */
+export function collectProxyEnv() {
+    const out = [];
+    for (const varName of PROXY_VARS) {
+        const value = process.env[varName];
+        if (value)
+            out.push({ varName, value });
+    }
+    return out;
+}
+/** 解析代理值为 {host, port}(仅处理显式端口的 http(s) 代理) */
+function parseProxyUrl(value) {
+    try {
+        const u = new URL(value);
+        if ((u.protocol !== 'http:' && u.protocol !== 'https:') || !u.port)
+            return null;
+        return { host: u.hostname, port: Number(u.port) };
+    }
+    catch {
+        return null;
+    }
+}
+function isLoopback(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '[::1]';
+}
+function probePort(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        let settled = false;
+        const done = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(r);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once('connect', () => done('open'));
+        socket.once('timeout', () => done('timeout'));
+        socket.once('error', (err) => done(err.code === 'ECONNREFUSED' ? 'refused' : 'unreachable'));
+        try {
+            socket.connect(port, host);
+        }
+        catch {
+            done('unreachable');
+        }
+    });
+}
+/**
+ * 找出指向 loopback 但端口不通的死代理。
+ * 远程代理(非 loopback)不探测,直接视为有效(由网络栈自己处理)。
+ */
+export async function findDeadProxies(timeoutMs = 800) {
+    const findings = [];
+    for (const { varName, value } of collectProxyEnv()) {
+        const parsed = parseProxyUrl(value);
+        if (!parsed || !isLoopback(parsed.host))
+            continue;
+        const result = await probePort(parsed.host, parsed.port, timeoutMs);
+        if (result !== 'open') {
+            findings.push({
+                varName,
+                value,
+                host: parsed.host,
+                port: parsed.port,
+                reason: result === 'refused' ? 'refused' : result === 'timeout' ? 'timeout' : 'unreachable',
+            });
+        }
+    }
+    return findings;
+}
+/** 生成各 shell 的清除指令提示(用户直接复制执行) */
+export function buildUnsetHint(findings) {
+    const vars = [...new Set(findings.map((f) => f.varName))].join(', ');
+    return [
+        `死代理告警: ${findings.map((f) => `${f.varName}=${f.value} (${f.reason === 'refused' ? '连接被拒绝' : f.reason === 'timeout' ? '连接超时' : '不可达'})`).join('; ')}`,
+        `该代理端口已不可用,会导致 npm registry 查询失败 / prebuild 下载失败回退源码编译。清除(当前会话):`,
+        `  PowerShell:  Remove-Item Env:${vars.replace(/, /g, ', Env:')}`,
+        `  CMD:         set ${findings.map((f) => f.varName).join('= && set ')}=`,
+        `  bash/zsh:    unset ${findings.map((f) => f.varName).join(' ')}`,
+        `  npm 专用:    npm config delete proxy && npm config delete https-proxy`,
+    ].join('\n');
+}