hunter-mate 0.1.6 → 0.1.8

package/dist/commands/update.js

@@ -2,29 +2,28 @@ import { Command } from 'commander';
 import axios from 'axios';
 import * as fs from 'fs';
 import * as path from 'path';
-import { loadConfig } from '../config.js';
+import { loadConfig, resolveDataDir } from '../config.js';
 import { getToken } from '../keychain.js';
 import { i18n } from '../i18n/index.js';
 import { getCliLogger } from '../logger.js';
 import chalk from 'chalk';
 import { readInstalledVersions, ensureRuntimeConsistency } from '../version.js';
 import { isDevLinked, npmLatestVersion, npmSelfUpdate } from '../updater.js';
-const HOME = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-const RULES_DIR = path.join(HOME, '.hunter-mate', 'rules');
-const VERSION_FILE = path.join(RULES_DIR, 'version.json');
+const RULES_DIR = () => path.join(resolveDataDir(), 'rules');
+const VERSION_FILE = () => path.join(RULES_DIR(), 'version.json');
 function loadLocalVersion() {
-    if (!fs.existsSync(VERSION_FILE))
+    if (!fs.existsSync(VERSION_FILE()))
         return null;
     try {
-        return JSON.parse(fs.readFileSync(VERSION_FILE, 'utf-8'));
+        return JSON.parse(fs.readFileSync(VERSION_FILE(), 'utf-8'));
     }
     catch {
         return null;
     }
 }
 function saveLocalVersion(version) {
-    fs.mkdirSync(RULES_DIR, { recursive: true });
-    fs.writeFileSync(VERSION_FILE, JSON.stringify({ version, updatedAt: new Date().toISOString() }, null, 2));
+    fs.mkdirSync(RULES_DIR(), { recursive: true });
+    fs.writeFileSync(VERSION_FILE(), JSON.stringify({ version, updatedAt: new Date().toISOString() }, null, 2));
 }
 export async function runUpdate() {
     const config = loadConfig();
@@ -105,7 +104,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

@@ -5,9 +5,28 @@ export interface HunterMateConfig {
     saasUrl: string;
     lang: string;
     watchFolder?: string;
+    /**
+     * 重数据目录(数据库/日志/缓存/扩展/CLI 安装树等),不含 config.json 本身。
+     * 通过 `hunter-mate migrate-data-dir <dir>` 迁移;留空表示默认 ~/.hunter-mate。
+     */
+    dataDir?: string;
+    /**
+     * hunter-mate-harness 仓绝对路径(外部 adapters overlay 真相源)。
+     * `hunter-mate adapter sync` 读取;env HUNTER_MATE_HARNESS_PATH 优先级更高。 @fid FID-081-adapter-overlay-suite
+     */
+    harnessPath?: string;
 }
 export declare const CONFIG_DIR: () => string;
 export declare const CONFIG_FILE: () => string;
+/**
+ * 重数据目录解析(FID-071):
+ * HM_DATA_DIR(env,进程级覆盖,CLI spawn server 时注入) > config.dataDir(用户配置) > 默认 CONFIG_DIR。
+ * config.json 本身始终留在 CONFIG_DIR(KB 级不迁移),保证任何时刻都能定位配置。
+ * 注意:每次调用都实时读取(不缓存),config --data-dir 写入后同一进程内立即生效。
+ */
+export declare function resolveDataDir(): string;
+/** resolveDataDir 的别名,语义化表达"数据目录"(与 CONFIG_DIR 配置目录区分) */
+export declare const DATA_DIR: typeof resolveDataDir;
 /**
  * 已知废弃的 URL 路径前缀(按部署形态演进顺序追加)。
  * 每当 nginx / 服务端路径收敛(如子路径 → 根路径)时,把旧前缀加到这里,
@@ -43,4 +62,6 @@ export declare function saveConfig(config: Partial<HunterMateConfig>): {
     saasUrl: string;
     lang: string;
     watchFolder?: string;
+    dataDir?: string;
+    harnessPath?: string;
 };

package/dist/config.js

@@ -4,6 +4,29 @@ import { createJsonConfigStore } from '@chromepilot/kit';
 const HOME = () => process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
 export const CONFIG_DIR = () => path.join(HOME(), '.hunter-mate');
 export const CONFIG_FILE = () => path.join(CONFIG_DIR(), 'config.json');
+/**
+ * 重数据目录解析(FID-071):
+ * HM_DATA_DIR(env,进程级覆盖,CLI spawn server 时注入) > config.dataDir(用户配置) > 默认 CONFIG_DIR。
+ * config.json 本身始终留在 CONFIG_DIR(KB 级不迁移),保证任何时刻都能定位配置。
+ * 注意:每次调用都实时读取(不缓存),config --data-dir 写入后同一进程内立即生效。
+ */
+export function resolveDataDir() {
+    if (process.env.HM_DATA_DIR && process.env.HM_DATA_DIR.trim()) {
+        return path.resolve(process.env.HM_DATA_DIR);
+    }
+    try {
+        const raw = store.load();
+        if (raw && typeof raw.dataDir === 'string' && raw.dataDir.trim()) {
+            return path.resolve(raw.dataDir);
+        }
+    }
+    catch {
+        /* 配置不可读时回落默认目录 */
+    }
+    return CONFIG_DIR();
+}
+/** resolveDataDir 的别名,语义化表达"数据目录"(与 CONFIG_DIR 配置目录区分) */
+export const DATA_DIR = resolveDataDir;
 /**
  * 已知废弃的 URL 路径前缀(按部署形态演进顺序追加)。
  * 每当 nginx / 服务端路径收敛(如子路径 → 根路径)时,把旧前缀加到这里,
@@ -70,6 +93,10 @@ export function ensureConfigDir() {
     if (!fs.existsSync(CONFIG_DIR())) {
         fs.mkdirSync(CONFIG_DIR(), { recursive: true });
     }
+    const dataDir = resolveDataDir();
+    if (dataDir !== CONFIG_DIR() && !fs.existsSync(dataDir)) {
+        fs.mkdirSync(dataDir, { recursive: true });
+    }
 }
 export function loadConfig() {
     const raw = store.load();

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

@@ -57,5 +57,23 @@
     "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.",
+    "login.selfCheckOk": "Login self-check passed: protected endpoint reachable",
+    "login.selfCheckFail": "Login self-check failed: new token rejected by local server; please report with full output",
+    "login.selfCheckSkipped": "Login self-check skipped: local server unreachable; re-login once it is back",
+    "issueEnv.description": "Print the environment block needed for issue reports (CLI version / install type / git HEAD / server buildTime / OS); --format json for agents to paste directly",
+    "issueEnv.cliVersion": "CLI version",
+    "issueEnv.installType": "Install type",
+    "issueEnv.installDev": "dev (git worktree of source repo)",
+    "issueEnv.installPackage": "package (published npm build)",
+    "issueEnv.gitHead": "Code HEAD (version/buildTime do not identify code state; HEAD does)",
+    "issueEnv.gitBranch": "Branch",
+    "issueEnv.gitDirty": "uncommitted changes (dist may lag HEAD)",
+    "issueEnv.gitClean": "clean worktree",
+    "issueEnv.repoRoot": "Repo root",
+    "issueEnv.gitUnavailable": "unavailable (published package has no git info; use CLI version instead)",
+    "issueEnv.serverBuildTime": "server buildTime",
+    "issueEnv.serverNotRunning": "server not running (unavailable)"
 }

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

@@ -57,5 +57,23 @@
     "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。",
+    "login.selfCheckOk": "✓ 登录自检通过:受保护接口可达,search/report/job 可直接使用",
+    "login.selfCheckFail": "✗ 登录自检失败:新令牌被本地 server 拒绝,请带完整输出反馈,勿反复重试",
+    "login.selfCheckSkipped": "⚠ 登录自检跳过:本地 server 暂不可达,恢复后请重新 login",
+    "issueEnv.description": "输出提 issue 所需环境块(CLI 版本/安装方式/代码 git HEAD/server buildTime/OS),--format json 可供 agent 直接粘贴",
+    "issueEnv.cliVersion": "CLI 版本",
+    "issueEnv.installType": "安装方式",
+    "issueEnv.installDev": "dev(源码仓 git 工作区)",
+    "issueEnv.installPackage": "package(发布包)",
+    "issueEnv.gitHead": "代码 HEAD(版本号/buildTime 不说明代码状态,以 HEAD 为准)",
+    "issueEnv.gitBranch": "分支",
+    "issueEnv.gitDirty": "有未提交改动(dist 可能滞后于 HEAD)",
+    "issueEnv.gitClean": "工作区干净",
+    "issueEnv.repoRoot": "代码仓",
+    "issueEnv.gitUnavailable": "未获取(发布包无 git 信息,用 CLI 版本代替)",
+    "issueEnv.serverBuildTime": "server buildTime",
+    "issueEnv.serverNotRunning": "server 未运行(未获取)"
 }

package/dist/index.js

@@ -14,6 +14,7 @@ import { extensionCommand } from './commands/extension.js';
 import { reportCommand } from './commands/report.js';
 import { recordCommand } from './commands/record.js';
 import { cacheCommand } from './commands/cache.js';
+import { migrateDataDirCommand } from './commands/migrate.js';
 // 对应 ChromePilot 的新命令（环境管理 / 运维 / 扩展管理）
 import { initCommand } from './commands/init.js';
 import { installCommand } from './commands/install.js';
@@ -22,10 +23,34 @@ import { doctorCommand } from './commands/doctor.js';
 import { reloadCommand, openExtCommand, purgeCommand } from './commands/extras.js';
 import { recordingsCommand, adapterCommand, memoryCommand, traceCommand, autofixCommand } from './commands/ops.js';
 import { pluginCommand, skillCommand, externalCommand } from './commands/addons.js';
+import { customerCommand } from './commands/customer.js';
+import { noteCommand } from './commands/note.js';
+import { preferenceCommand } from './commands/preference.js';
+import { caseCommand } from './commands/case.js';
+import { issueEnvCommand } from './commands/issue-env.js';
 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 +80,35 @@ 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 === 'migrate-data-dir')
+        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 +118,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');
@@ -124,4 +168,10 @@ program.addCommand(purgeCommand);
 program.addCommand(reportCommand);
 program.addCommand(recordCommand);
 program.addCommand(cacheCommand);
+program.addCommand(migrateDataDirCommand);
+program.addCommand(customerCommand);
+program.addCommand(noteCommand);
+program.addCommand(preferenceCommand);
+program.addCommand(caseCommand);
+program.addCommand(issueEnvCommand);
 program.parse();

package/dist/keychain.d.ts

@@ -1,3 +1,18 @@
-export declare function saveToken(token: string): Promise<void>;
+/**
+ * token 签发方(hmh#43):
+ * - local: 本地 server 自签 UTOKEN(设备码/邮箱代理路径),AuthMiddleware 可直接验签;
+ * - saas:  邮箱登录时本地 server 不可达,CLI 直连 SaaS 验证拿到的 token,
+ *          由 SaaS 密钥签发,本地 server 的 USER_SESSION_SECRET 验不过 → 数据面 401;
+ * - unknown: 旧版本存的裸 token(无 issuer 标记),无法区分签发方。
+ */
+export type TokenIssuer = 'local' | 'saas' | 'unknown';
+export interface TokenInfo {
+    token: string;
+    issuer: TokenIssuer;
+}
+export declare function saveToken(token: string, issuer?: TokenIssuer): Promise<void>;
+/** 只取 token 字符串(兼容全部历史调用方) */
 export declare function getToken(): Promise<string | null>;
+/** 取 token + 签发方标记(hmh#43 诊断用) */
+export declare function getTokenInfo(): Promise<TokenInfo | null>;
 export declare function deleteToken(): Promise<void>;

package/dist/keychain.js

@@ -1,30 +1,50 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { resolveDataDir } from './config.js';
 const SERVICE = 'hunter-mate';
 const ACCOUNT = 'user';
-const HOME = process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || '.';
-const TOKEN_FILE = path.join(HOME, '.hunter-mate', 'token.json');
-function fallbackSave(token) {
-    fs.mkdirSync(path.dirname(TOKEN_FILE), { recursive: true });
+/** token 落盘文件(FID-071:随 dataDir 配置迁移;keytar 可用时不使用) */
+function tokenFile() {
+    return path.join(resolveDataDir(), 'token.json');
+}
+/** 兼容旧格式:裸 token 字符串或无 issuer 字段的 JSON */
+function parseStored(raw) {
+    if (!raw)
+        return null;
+    try {
+        const data = JSON.parse(raw);
+        if (typeof data === 'string')
+            return { token: data, issuer: 'unknown' };
+        if (data && typeof data.token === 'string') {
+            const issuer = data.issuer === 'saas' || data.issuer === 'local' ? data.issuer : 'unknown';
+            return { token: data.token, issuer };
+        }
+        return null;
+    }
+    catch {
+        return { token: raw, issuer: 'unknown' };
+    }
+}
+function fallbackSave(info) {
+    fs.mkdirSync(path.dirname(tokenFile()), { recursive: true });
     // POSIX 上 mode 0o600 强制 owner-only;Windows NTFS 上 mode bit 被忽略,
     // 由用户目录 ACL 兜底(%USERPROFILE%\.hunter-mate 默认只有当前用户可访问)。
     // 真正安全的 Windows 路径是走 keytar(Windows Credential Manager)→ setPassword。
-    fs.writeFileSync(TOKEN_FILE, JSON.stringify({ token }), { mode: 0o600 });
+    fs.writeFileSync(tokenFile(), JSON.stringify(info), { mode: 0o600 });
 }
 function fallbackGet() {
-    if (!fs.existsSync(TOKEN_FILE))
+    if (!fs.existsSync(tokenFile()))
         return null;
     try {
-        const data = JSON.parse(fs.readFileSync(TOKEN_FILE, 'utf-8'));
-        return data.token || null;
+        return parseStored(fs.readFileSync(tokenFile(), 'utf-8'));
     }
     catch {
         return null;
     }
 }
 function fallbackDelete() {
-    if (fs.existsSync(TOKEN_FILE)) {
-        fs.unlinkSync(TOKEN_FILE);
+    if (fs.existsSync(tokenFile())) {
+        fs.unlinkSync(tokenFile());
     }
 }
 async function getKeytar() {
@@ -41,26 +61,33 @@ async function getKeytar() {
         return null;
     }
 }
-export async function saveToken(token) {
+export async function saveToken(token, issuer = 'local') {
+    const payload = JSON.stringify({ token, issuer });
     const keytar = await getKeytar();
     if (keytar) {
         try {
-            await keytar.setPassword(SERVICE, ACCOUNT, token);
+            await keytar.setPassword(SERVICE, ACCOUNT, payload);
             return;
         }
         catch {
             // 降级到文件
         }
     }
-    fallbackSave(token);
+    fallbackSave({ token, issuer });
 }
+/** 只取 token 字符串(兼容全部历史调用方) */
 export async function getToken() {
+    const info = await getTokenInfo();
+    return info?.token ?? null;
+}
+/** 取 token + 签发方标记(hmh#43 诊断用) */
+export async function getTokenInfo() {
     const keytar = await getKeytar();
     if (keytar) {
         try {
-            const token = await keytar.getPassword(SERVICE, ACCOUNT);
-            if (token)
-                return token;
+            const raw = await keytar.getPassword(SERVICE, ACCOUNT);
+            if (raw)
+                return parseStored(raw);
         }
         catch {
             // 降级

package/dist/logger.js

@@ -1,6 +1,6 @@
 import { Logger, createHttpTransport } from "@chromepilot/logger-kit/client";
 import { PersistentLogQueue } from "@chromepilot/logger-kit/queue-node";
-import { loadConfig } from "./config.js";
+import { loadConfig, resolveDataDir } from "./config.js";
 import { getToken } from "./keychain.js";
 import path from "node:path";
 let logger = null;
@@ -25,7 +25,7 @@ export function getCliLogger() {
     return logger;
 }
 function homeDir() {
-    return process.env.HUNTER_MATE_HOME || process.env.HOME || process.env.USERPROFILE || ".";
+    return resolveDataDir();
 }
 export async function initCliLogger(options) {
     const cfg = loadConfig();

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

@@ -21,9 +21,9 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { createCliUpdater } from '@chromepilot/kit';
 import { readInstalledVersions } from './version.js';
+import { resolveDataDir } from './config.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 ROOT = resolveDataDir;
 const CLI_PREFIX = () => path.join(ROOT(), 'cli');
 /**
  * 判定是否开发软链模式(纯函数,便于单测):
@@ -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,11 @@
+/**
+ * 命令错误统一出口(对应 fix #18/#28):
+ * - logger 留痕(后台可检索,与现有 getCliLogger().error 一致)
+ * - console.error 落终端(用户能直接看懂,不再静默 exit 1)
+ * - 401/403 时给出重新登录的中文提示;
+ *   hmh#43:token 由 SaaS 签发(本地 server 未运行时登录所致)时给出定向诊断,
+ *   不再笼统报"登录已过期"
+ *
+ * 调用方随后自行 process.exit(1)。
+ */
+export declare function printCommandError(scope: string, err: unknown): Promise<void>;

package/dist/utils/command-error.js

@@ -0,0 +1,47 @@
+import { getCliLogger } from '../logger.js';
+import { getTokenInfo } from '../keychain.js';
+/**
+ * 命令错误统一出口(对应 fix #18/#28):
+ * - logger 留痕(后台可检索,与现有 getCliLogger().error 一致)
+ * - console.error 落终端(用户能直接看懂,不再静默 exit 1)
+ * - 401/403 时给出重新登录的中文提示;
+ *   hmh#43:token 由 SaaS 签发(本地 server 未运行时登录所致)时给出定向诊断,
+ *   不再笼统报"登录已过期"
+ *
+ * 调用方随后自行 process.exit(1)。
+ */
+export async 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})`);
+        let issuer = 'unknown';
+        try {
+            issuer = (await getTokenInfo())?.issuer ?? 'unknown';
+        }
+        catch {
+            // keychain 不可用时按 unknown 处理
+        }
+        if (issuer === 'saas') {
+            console.error('当前 token 由 SaaS 签发(登录时本地 server 未运行),本地 server 拒绝使用。\n' +
+                '请先启动本地 server(hunter-mate start),再重新执行 hunter-mate login。');
+        }
+        else {
+            console.error('登录已过期或无权访问,请运行 hunter-mate login 后重试');
+        }
+        return;
+    }
+    console.error(`✗ ${scope}: ${message}${status ? ` (HTTP ${status})` : ''}`);
+    if (bodyText && bodyText !== message) {
+        console.error(`  响应: ${bodyText}`);
+    }
+}

package/dist/utils/link.d.ts

@@ -0,0 +1,18 @@
+export type LinkKind = 'dir' | 'file';
+export interface LinkResult {
+    ok: boolean;
+    fallback?: 'copy+marker';
+    error?: string;
+}
+/**
+ * linkDev: cross-platform "point at the build artifact" dev-link helper.
+ * 实现对齐 chromepilot packages/cli/src/utils/link.ts(SSOT,同构复制)。
+ *
+ * - POSIX:  fs.symlinkSync(target, linkPath, type)
+ * - Windows directory: NTFS junction (no admin needed; cannot cross drives)。
+ *           跨盘或 junction 失败退化 copy + `<linkPath>.devlink` marker。
+ * - Windows file: copy + marker(Windows 文件软链需要 SeCreateSymbolicLink 权限,避免使用)。
+ */
+export declare function linkDev(target: string, linkPath: string, kind?: LinkKind): LinkResult;
+/** lstat 对悬空软链会抛异常而不是返回 false;包一层保证调用方拿到 boolean */
+export declare function isSymbolicLinkSafe(p: string): boolean;

package/dist/utils/link.js

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * linkDev: cross-platform "point at the build artifact" dev-link helper.
+ * 实现对齐 chromepilot packages/cli/src/utils/link.ts(SSOT,同构复制)。
+ *
+ * - POSIX:  fs.symlinkSync(target, linkPath, type)
+ * - Windows directory: NTFS junction (no admin needed; cannot cross drives)。
+ *           跨盘或 junction 失败退化 copy + `<linkPath>.devlink` marker。
+ * - Windows file: copy + marker(Windows 文件软链需要 SeCreateSymbolicLink 权限,避免使用)。
+ */
+export function linkDev(target, linkPath, kind = 'dir') {
+    if (fs.existsSync(linkPath)) {
+        try {
+            fs.rmSync(linkPath, { recursive: true, force: true });
+        }
+        catch (err) {
+            const e = err;
+            return { ok: false, error: `清理已存在目标失败: ${e.message}` };
+        }
+    }
+    if (process.platform !== 'win32') {
+        try {
+            fs.symlinkSync(target, linkPath, kind);
+            return { ok: true };
+        }
+        catch (err) {
+            const e = err;
+            return { ok: false, error: `symlink 失败: ${e.message}` };
+        }
+    }
+    // Windows + directory: try junction
+    if (kind === 'dir') {
+        const linkDrive = path.parse(path.resolve(linkPath)).root;
+        const targetDrive = path.parse(path.resolve(target)).root;
+        if (linkDrive && targetDrive && linkDrive !== targetDrive) {
+            try {
+                fs.cpSync(target, linkPath, { recursive: true });
+                fs.writeFileSync(`${linkPath}.devlink`, path.resolve(target), 'utf-8');
+                return { ok: true, fallback: 'copy+marker' };
+            }
+            catch (err) {
+                const e = err;
+                return { ok: false, error: `junction 跨盘符退化失败: ${e.message}` };
+            }
+        }
+        try {
+            fs.symlinkSync(target, linkPath, 'junction');
+            return { ok: true };
+        }
+        catch (err) {
+            const e = err;
+            try {
+                fs.cpSync(target, linkPath, { recursive: true });
+                fs.writeFileSync(`${linkPath}.devlink`, path.resolve(target), 'utf-8');
+                return { ok: true, fallback: 'copy+marker' };
+            }
+            catch (err2) {
+                const e2 = err2;
+                return { ok: false, error: `junction 与 copy 兜底均失败: ${e.message} / ${e2.message}` };
+            }
+        }
+    }
+    // Windows + file: copy + marker
+    try {
+        fs.copyFileSync(target, linkPath);
+        fs.writeFileSync(`${linkPath}.devlink`, path.resolve(target), 'utf-8');
+        return { ok: true, fallback: 'copy+marker' };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, error: `copy+marker 失败: ${e.message}` };
+    }
+}
+/** lstat 对悬空软链会抛异常而不是返回 false;包一层保证调用方拿到 boolean */
+export function isSymbolicLinkSafe(p) {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}